README

금융위원회(FSC) 공공데이터 OpenAPI를 Laravel에서 쉽게 호출하기 위한 패키지입니다. data.go.kr 기관코드 1160100(금융위원회)의 API들을 공통 클라이언트로 묶어 제공합니다.

현재 상태: 공통 토대(설정 · HTTP 클라이언트 · 응답 파서 · 예외 · 엔드포인트 추상 베이스)와 테스트 골격이 구성되어 있습니다. 구현된 API는 아래 표를 참고하세요. 나머지는 이 패턴을 따라 추가됩니다.

API	서비스	메서드
기업기본정보	GetCorpBasicInfoService_V2	Fsc::corp()->getCorpOutline(...)
개인사업자기본정보	GetSBProfileInfoService	Fsc::proprietor()->getOutline(...) / getClosureStatus(...)
금융회사기본정보	GetFnCoBasiInfoService	Fsc::financialCompany()->getFnCoOutline(...)

요구사항

• PHP ^8.3
• Laravel ^12.0 또는 ^13.0

설치

composer require sejongtf/laravel-fsc

설정 파일을 publish합니다:

php artisan vendor:publish --tag=fsc-config

설정

data.go.kr에서 발급받은 금융위원회 OpenAPI 디코딩(Decoding) 일반 인증키를 .env에 설정합니다. 패키지가 요청 시 자동으로 URL 인코딩하므로, 이미 인코딩된 키를 넣으면 이중 인코딩될 수 있습니다.

FSC_SERVICE_KEY=your-decoded-service-key
# 선택값
FSC_BASE_URL=https://apis.data.go.kr/1160100
FSC_NUM_OF_ROWS=10
FSC_TIMEOUT=10
# 응답 캐싱 (기본 비활성)
FSC_CACHE_ENABLED=false
FSC_CACHE_TTL=3600
FSC_CACHE_STORE=
FSC_CACHE_PREFIX=fsc

사용법 (저수준 호출)

현재는 임의의 금융위원회 API를 직접 호출할 수 있습니다. 공통 파라미터 (serviceKey, resultType, numOfRows, pageNo)는 자동으로 주입됩니다.

use Sejongtf\Fsc\Facades\Fsc;

$response = Fsc::get(
    'service/GetStockSecuritiesInfoService', // servicePath
    'getStockPriceInfo',                     // operation
    ['likeItmsNm' => '삼성', 'numOfRows' => 20],
);

$response->items();        // array<int, array> — 결과 목록 (단건도 배열로 정규화)
$response->totalCount();   // int
$response->pageNo();       // int
$response->hasMorePages(); // bool
$response->raw();          // 원본 응답 배열

의존성 주입으로 클라이언트를 직접 받을 수도 있습니다:

use Sejongtf\Fsc\Http\Client;

public function __construct(private Client $client) {}

응답 캐싱

동일한 요청의 반복 호출을 줄이기 위해 성공 응답을 Laravel 캐시에 저장할 수 있습니다. 기본은 비활성(opt-in)이며, .env 또는 config/fsc.php 에서 켭니다.

FSC_CACHE_ENABLED=true
FSC_CACHE_TTL=3600        # 보관 시간(초). basDt 단위 데이터면 더 길게 잡아도 됩니다.
FSC_CACHE_STORE=redis     # 비우면 Laravel 기본 캐시 스토어 사용
FSC_CACHE_PREFIX=fsc      # 캐시 키 접두사

동작 방식:

• resultCode 가 "00" 인 성공 응답만 캐싱합니다. 비정상 응답(FscApiException)은 캐싱하지 않습니다.
• 캐시 키는 servicePath · operation · 요청 파라미터로 만들며, serviceKey 는 키에서 제외됩니다 (파라미터 순서는 키에 영향을 주지 않습니다).
• 캐싱은 저수준 Fsc::get() 과 모든 엔드포인트(Fsc::corp() 등)에 공통 적용됩니다.

// FSC_CACHE_ENABLED=true 인 경우, 동일 인자의 두 번째 호출은 캐시에서 제공됩니다.
$first  = Fsc::corp()->getCorpOutline(crno: '1101113892240'); // 네트워크 호출
$second = Fsc::corp()->getCorpOutline(crno: '1101113892240'); // 캐시 적중

기업기본정보 (GetCorpBasicInfoService_V2)

법인등록번호(crno) 또는 법인명(corpNm)으로 기업개요를 조회합니다. 데이터 명세

use Sejongtf\Fsc\Facades\Fsc;

// 원시 Response 로 받기
$response = Fsc::corp()->getCorpOutline(crno: '1101113892240');
$response->items();      // array<int, array>
$response->totalCount(); // int

// 법인명으로 부분 검색 + 기준일자 지정
$response = Fsc::corp()->getCorpOutline(
    corpNm: '메리츠',
    params: ['basDt' => '20240102', 'numOfRows' => 50],
);

// CorpOutline DTO 배열로 받기
$outlines = Fsc::corp()->getCorpOutlineAsObjects(corpNm: '메리츠');
foreach ($outlines as $corp) {
    $corp->corpNm;                     // 법인명
    $corp->enpRprFnm;                  // 대표자명
    $corp->bzno;                       // 사업자등록번호
    $corp->employeeCount();            // ?int — 종업원수
    $corp->isSmallMediumEnterprise();  // ?bool — 중소기업 여부
}

어떤 Response 든 mapInto() 로 임의의 DTO 에 매핑할 수 있습니다:

use Sejongtf\Fsc\Endpoints\Corp\CorpOutline;

$outlines = $response->mapInto(CorpOutline::class);

개인사업자기본정보 (GetSBProfileInfoService)

개인사업자의 개요정보(지역·업종·설립년도·대표자 연령대/성별·종업원수)와 휴폐업정보를 집계 단위로 제공합니다 (사업자등록번호 등 개별 식별자는 없음). 데이터 명세

use Sejongtf\Fsc\Facades\Fsc;
use Sejongtf\Fsc\Endpoints\Proprietor\ProprietorProfile;

// 개인사업자개요정보조회 (getOtlInfo)
$outlines = Fsc::proprietor()->getOutlineAsObjects([
    'basYm'      => '202208',   // 기준년월 (YYYYMM)
    'bizAreaNm'  => '속초',      // 사업 지역명 (부분 검색)
    'bizBzcCdNm' => '제조업',     // 사업 업종명 (부분 검색)
    'bizBzcCd'   => '10',        // 사업 업종코드
    'estbYr'     => '2007',      // 설립년도
    'rprSexNm'   => '남성',       // 대표자 성별명
    'numOfRows'  => 50,
]);

foreach ($outlines as $row) {
    $row->bizAreaNm;            // 사업 지역명 (시군구)
    $row->bizBzcCdNm;          // 사업 업종명
    $row->rprAggrNm;          // 대표자 연령대명 (예: 70대)
    $row->establishmentYear(); // ?int — 설립년도
}

// 개인사업자휴폐업정보조회 (getCsdoStatus)
$rows = Fsc::proprietor()->getClosureStatusAsObjects(['basYm' => '202208']);
$rows[0]->csdoClsfNm;   // 휴폐업구분명 (휴업/폐업/휴폐업)
$rows[0]->isClosed();   // ?bool

// 원시 Response 가 필요하면 getOutline() / getClosureStatus() 사용
$response = Fsc::proprietor()->getOutline(['basYm' => '202208']);
$response->totalCount();

금융회사기본정보 (GetFnCoBasiInfoService)

법인등록번호(crno) 또는 금융회사명(fncoNm)으로 금융회사기업개요(주소·설립일·종업원수·상장정보 등)를 조회합니다. 데이터 명세

use Sejongtf\Fsc\Facades\Fsc;

// 금융회사명으로 부분 검색
$rows = Fsc::financialCompany()->getFnCoOutlineAsObjects(fncoNm: '은행', params: ['numOfRows' => 20]);
foreach ($rows as $fnco) {
    $fnco->fncoNm;          // 금융회사명
    $fnco->fncoRprNm;       // 대표자명
    $fnco->fncoAdr;         // 주소
    $fnco->fncoEstbDt;      // 설립일자
    $fnco->employeeCount(); // ?int — 종업원수
}

// 법인등록번호 + 기준일자
$response = Fsc::financialCompany()->getFnCoOutline(
    crno: '1101113892240',
    params: ['basDt' => '20200408'],
);
$response->items();

예외

새 금융위원회 API 추가하기

AbstractEndpoint를 상속해 servicePath / operation을 정의하고, 도메인 메서드를 추가합니다.

namespace Sejongtf\Fsc\Endpoints\Stock;

use Sejongtf\Fsc\Endpoints\AbstractEndpoint;
use Sejongtf\Fsc\Http\Response;

class StockSecuritiesInfo extends AbstractEndpoint
{
    protected string $servicePath = 'service/GetStockSecuritiesInfoService';
    protected string $operation   = 'getStockPriceInfo';

    public function getStockPriceInfo(array $filters = []): Response
    {
        return $this->call($filters);
    }
}

그리고 Sejongtf\Fsc\Fsc에 팩토리 메서드를 노출합니다:

public function stock(): StockSecuritiesInfo
{
    return new StockSecuritiesInfo($this->client);
}

사용:

$items = Fsc::stock()->getStockPriceInfo(['basDt' => '20240102'])->items();

테스트

composer test

테스트는 Http::fake() 기반으로 동작하므로 실제 data.go.kr 호출 없이 검증됩니다.

License

MIT © 세종티에프