금융보안원 로고

회원가입 로그인

API가이드

데이터 표준 API 기본규격

1. 기본 규격 1) 데이터 표현규격

  1. JSON: 데이터를 교환하기 위한 API의 메시지 형식은 JSON 방식을 사용함

    JSON(JavaScript Object Notation)

    용량이 적은 메시지를 송수신하기 위해 데이터 객체를 속성·값(Key:Value) 형식으로 표현하는 개방형 표준 메시지 형식

  2. 메시지 인코딩 방식 : 메시지 전송을 위한 인코딩 방식은 UTF-8 을 사용함

    UTF-8

    ASCII 코드를 확장하여 전 세계의 모든 문자코드를 표현할 수 있는 표준 인코딩 방식으로써, 범용성이 높아 호환성이 우수

  3. 명명 규칙 : API 명세 내 URI와 파라미터의 명명으로 'Under Scores'표기법(각 소문자 영단어가 밑줄 문자(_)로 연결)을 사용함

    ※ 단, OAuth 2.0과 같이 타 표준에서 요구하는 URI나 파라미터 명명 규칙 등이 존재하는 경우 해당 표준을 우선 준용함

  4. 통화코드 표현 형식 : 통화코드 표현은 ISO 4217을 사용함

    ※ 예시 : KRW - 한국원화

2) 데이터 통신규격

  1. 네트워크 구간 보호 : 참여주체(정보 제공자, 마이데이터사업자, 종합포털, 통합인증기관) 간 안전한 통신을 위한 보호 방안으로, TLS 기반 상호인증 (Mutual Authentication) 및 전송구간 암호화를 사용

    TLS (Transport Layer Security)

    - 전송(Transport) 계층과 응용(Application) 계층 사이에서 종단 간 인증, 전송 데이터의 암호화, 무결성을 보장하는 표준 프로토콜

    - 안전한 전송을 위해 TLS 1.3이상 버전 사용

  2. 메시지 교환 방식 : API 요청 및 응답(메시지) 교환방식은 REST 방식을 사용함

    REST (REpresentational State Transfer)

    - HTTP 기반으로 데이터를 전달하는 프레임워크로써, URI로 정보의 자원을 표현하고 자원에 대한 행위를 HTTP 메소드(GET, POST 등)로 표현

    - 다만, 보안상 이유로 HTTP 메소드 중 GET, POST만 제한적 이용

  3. URI 계층 구조 : 업권별 웹서버 상의 자원(리소스)을 고유하게 식별하고, 위치를 지정할 수 있도록 URI 계층 구조는 다음과 같이 구성

    분류 URI 계층 구조
    OAuth 2.0 관련 API
    (인증 API, 지원 API 일부)     		<base path> / oauth / 2.0 / [authorize | token | revoke]
    업권별 정보제공 API <base path> / <version> / <industry> / <resource>
    지원 API <base path> / <version> / <resource>
    통합인증 API <base path> / <version> / <resource>

    <base path> : 정보 제공자의 API서버 도메인명(또는 IP)로써 종합포털에 기관정보와 함께 등록한 정보
    금융회사가 마이데이터사업자 허가를 받는 경우, 금융회사가 정보제공을 위해 사용하는 도메인(예:base path #1)과 마이데이터사업자로서 정보 제공을 위해 사용하는 도메인(예:base path #2)을 구분

    <version> : 표준API 규격 버전정보로써 "v"+숫자로 표기(예: v1, v34 등)

    <industry> : 업권 정보
    업권을 URI로 구분하고, 업권 간 URI 중복을 방지하기 위해 <industry>로 구분
    지원 API는 종합포털과 마이데이터사업자/정보제공자 간 이용되는 API 이기 때문에 <industry> 불필요

    업권 <industry>값
    은행 bank
    카드 card
    금융투자 invest
    보험 insu
    전자금융 efin
    할부금융 capital
    보증보험
    (서울보증보험)    		 ginsu
    통신 telecom
    P2P p2p
    인수채권
    (한국자산관리공사, 국민행복기금, 케이알앤씨, 농협자산관리회사 등 채권인수회사)    		 bond
    대부 (금전대부업자, 매입추심업자) usury

    업권이 복수 개인 기관(예:겸영여신업자 등)의 경우, 종합포털로 부터 업권별 기관코드가 각각 발급되며, 따라서 종합포털에 기관 등록 시 업권 수만큼 복수 개의 기관 등록 필요

    즉, 기관 별 <industry>는 1:1 관계 (한 기관이 복수 개의 <industry>를 가질 수 없음

    <resource> 정보제공자가 보유하고 있는 특정 자원을 요청하기 위한 식별 정보러써, 정보제공자가 제공해야 할 API를 특정
    API 명세(제5장 ~ 제7장) 내 "API 명 (URI)"는 <resource>만을 표기하였으며, 따라서 실제 URI는 <version> , <industry>등을 포함
    (상세 URI는 제4장 참조)

    URI 예시
    1. 1. A 은행이 제공해야 하는 "업권별 정보제공 API" 목록 :
      <base path> / <version> / bank / <resource>
    2. 2. B 전자금융업자가 제공해야 하는 "업권별 정보제공 API" 목록 :
      <base path> / <version> / efin / <resource>
    3. 3. 은행업, 카드업 모두 수행하는 C기관이 제공해야 하는 "업권별 정보제공 API" 목록 :
      <base path #1> / <version> / bank / <resource>
      <base path #2> / <version> / card / <resource>

    C기관(은행업)의 기관코드와 C기관(카드업)의 기관코드는 상이

    ※ 예시1~3 모두, 인증 API 및 지원 API는 <base path> 별로 제공

  4. HTTP 헤더 : 표준 API에 지원되는 HTTP 헤더를 다음과 같이 지정

    Content-Type : 데이터(Body)의 포맷을 지정하기 위한 헤더 값으로 필요에 따라 application/x-www-form-urlencoded, 또는 application/json으로 지정

    구분 구분 헤더 값 지정
    요청
    (Request)     		OAuth 2.0 관련 API 호출 시 application/x-www-form-urlencoded
    JSON 형식으로 데이터 전송 시 application/json
    응답
    (Response)     		OAuth 2.0 인가코드 발급요청
    API 호출 시    		 application/x-www-form-urlencoded
    JSON 형식으로 데이터 전송 시 application/json

    x-api-type : 정보주체의 개입 없이 마이데이터사업자가 정기적 전송을 위해 호출한 API인지 여부를 구분하기 위한 헤더 값 (정보주체가 직접 개입 하여 API를 호출하는 경우 본 헤더 정보는 생략)

    * 예시 : 사용자가 마이데이터사업자 앱에 접속하여 "조회" 등 버튼 클릭 시 API 호출

    분류 조건 헤더 값 지정
    요청
    (Request)     		정지적 전송 시 "x-api-type : scheduled"
    비정기적 전송 시 생략
    응답
    (Response)     		해당없음 -

  5. 응답코드 및 메시지 : 기본적인 HTTP 응답코드는 정상응답 여부 및 주요한 에러를 범주로 처리하는 등 각 API 처리상황의 상세한 판단이 불가능 하므로, 세부 응답코드 및 메시지를 사용함 ([별첨1] 참조)

    OAuth 2.0 관련 API

    - RFC 6479 및 7009 국제표준 준용

    그 외

    - 세부 응답코드와 메시지는 응답 본문 내 ‘rsp_code’, ‘rsp_msg’ 필드에 포함하여 반환

  6. 페이지네이션, 부분범위 조회 : 정보의 목록을 반환하는 API(거래내역 조회 등)에는 부분범위 조회를 위한 ‘Cursor-Based Pagination’ 기법을 적용하여 데이터수신자의 처리 효율성과 정보 제공자의 부하를 경감함

    부분범위 조회 요청/응답 파라미터 규격
    구분 이름 타입 (길이) 설명
    요청 limit N (3) 기준개체 이후 반환될 개체의 개수 (최대 500자까지 설정 가능)
    next_page* aN (1000) 다음 페이지 요청을 위한 기준개체 (설정 시 해당 개체를 포함한 limit 개 반환)
    응답
    (JSON 응답)     		next_page* aN (1000) 다음 페이지 요청을 위한 기준개체 (다음 페이지 존재하지 않는 경우 미회신)

    * 기준개체 식별자의 생성규칙은 정보제공자가 자율적으로 정함.

  7. 부하개선을 위한 조회 Timestamp : 마이데이터사업자가 정보를 수집한 이후 동일한 정보에 대해 정기전송 요청 시 정보 제공자의 정보가 수정사항이 없을 경우 조회 Timestamp를 이용하여 전송을 최소화
    정보제공자는 조회 Timestamp 기능을 의무적으로 구현할 필요없음(선택사항)
    예시 : Timestamp를 이용한 부하개선
    1. 1. (정보수신자) 최초로 API 호출 (본 예시는 "계좌 기본정보 조회"(가칭) API를 호출 시 시나리오)

      - ST(조회 timestamp)=0

    2. 2. (정보제공자) ST와 MT(가장 최근에 DB갱신된 시간)를 비교

      - ST(0) < MT(40)이므로, DB를 조회하여 정보를 정보수신자에게 전달

      - 이때 정보수신자가 조회한 시간(current time)을 함께 회신 (예시에서는 현재시각을 100이라 가정)

    3. 3. (정보수신자) 전달받은 정보 및 조회기준시점(100)을 DB에 반영
    4. 4. (정보수신자) 정기적 전송을 위해 정보수신자가 동일한 API를 호출

      - DB에 저장되어 있는 ST(100)을 함께 정보제공자에게 전달

    5. 5. (정보제공자) 그 사이에 정보제공자의 DB가 변경된 적이 없으므로(MT=40), UP_TO_DATE 회신
    6. 6. (정보제공자) 계좌 기본정보가 갱신될 경우, MT도 UPDATE 시점의 시간(예시에서는 UPDATE 시점의 현재시각을 150이라 가정)도 갱신
    7. 7. (정보수신자) 정기적 전송을 위해 정보수신자가 동일한 API를 호출

      - DB에 저장되어 있는 ST(100)을 함께 정보제공자에게 전달

    8. 8. (정보제공자) ST와 MT(가장 최근에 DB갱신된 시간=150)를 비교

      - ST(100) < MT(150)이므로, DB를 조회하여 정보를 정보수신자에게 전달

      - 이때 정보수신자가 조회한 시간(current time)을 함께 회신 (예시에서는 현재시각을 200이라 가정)

    9. 9. (정보수신자) 전달받은 정보 및 조회기준시점(200)을 DB에 반영