KBX v20 — Official Market/Data Provider Adapters

목적

KRX OPEN API, OPENDART, KIS를 KBX/Domain에서 직접 호출하지 않고 Provider Adapter 뒤에 격리한다. 공식 문서에서 확인되지 않은 URL·호출한도·오류코드는 계약에 추정하여 넣지 않는다.

이용 순서: 인증키 신청 → API 서비스 탐색 → 개별 서비스 활용 신청 → 승인 후 이용.
인증키는 Request Header의 AUTH_KEY로 전달한다.
개별 데이터 서비스 URL/메서드는 승인된 KRX 서비스 명세를 운영 설정으로 등록한다. v20 저장소는 확인되지 않은 공통 URL을 만들지 않는다.
숫자형 공통 호출한도는 이번 공식 자료에서 확인되지 않아 null로 유지한다.

Base: https://opendart.fss.or.kr/api/
인증: query crtfc_key, 40자리.
Reference operations: list.json, company.json, corpCode.xml.
응답 status: 000 정상, 013 데이터 없음, 020 요청 제한, 800 점검, 900 정의되지 않은 오류 등.
020은 공식 가이드에서 일반적으로 20,000건 이상의 요청에서 발생할 수 있다고 설명하지만 서비스별 제한이 다를 수 있으므로 KBX가 20,000을 보편적 quota로 고정하지 않는다.

REST 실전: https://openapi.koreainvestment.com:9443
REST 모의: https://openapivts.koreainvestment.com:29443
OAuth token: POST /oauth2/tokenP, grant_type=client_credentials, appkey/appsecret.
Access token 유효기간 24시간, 공식 문서는 6시간 갱신발급주기를 안내한다.
2026-04-20 공식 공지: 실전 REST 18 req/s, 모의 1 req/s, token 발급 1 req/s. 동시 호출은 100~150ms 간격 권장.
v20의 KIS Adapter는 시세 조회 GET만 지원한다. 주문/정정취소 POST는 별도 Trading Integration 계약 없이는 추가하지 않는다.
현재가 Reference: /uapi/domestic-stock/v1/quotations/inquire-price, TR FHKST01010100.

AUTH_KEY, crtfc_key, appkey, appsecret, access_token은 UI·Telemetry·Audit diff·로그에 저장하지 않는다. Adapter는 IKbxProviderSecretStore에서만 읽는다.

Provider 데이터는 업무 원장이 아니다. Provider 장애 시 기존 Domain Write를 되돌리거나 외부 응답을 Business Truth로 승격하지 않는다. 데이터 신선도와 원천 시각을 별도 보존한다.