API 서비스 명세서 - Koscom · 2017-11-15 · api 서비스 명세서 페이지 1 변 경 이...

[BC 카드]

API 서비스 명세서 코스콤 오픈 API 플랫폼 - BC 카드 업종정보 API

API 서비스 명세서

페이지 1

변 경 이 력

버전 날짜 내용 작성자

0.1 2017.11.13 BC카드 업종정보 API 명세서 초안


페이지 2

목 차

I. API 명세서 개요 .................................................................................................................................................................................................................................................... 4

II. API 목록 .................................................................................................................................................................................................................................................................... 4

III. API 명세서 명세서 ............................................................................................................................................................................................................................................... 5

1. { /businesstype/v1.0/index }.......................................................................................................................................................................................................................... 5

1.1 API 개요 ........................................................................................................................................................................................................................................................ 5

1.2 리소스 목록 ................................................................................................................................................................................................................................................. 5

1.3 리소스 명세 ................................................................................................................................................................................................................................................. 6

1.4 예시............................................................................................................................................................................................................................................................... 13

2. { /businesstype/v1.0/code }........................................................................................................................................................................................................................ 17

2.1 API 개요 ..................................................................................................................................................................................................................................................... 17

2.2 리소스 목록 .............................................................................................................................................................................................................................................. 18

2.3 리소스 명세 .............................................................................................................................................................................................................................................. 18

2.4 예시............................................................................................................................................................................................................................................................... 22

3. { /zscore/v1.0/index } .................................................................................................................................................................................................................................... 25

3.1 API 개요 ..................................................................................................................................................................................................................................................... 25


페이지 3

3.2 리소스 목록 .............................................................................................................................................................................................................................................. 27

3.3 리소스 명세 .............................................................................................................................................................................................................................................. 27

3.4 예시............................................................................................................................................................................................................................................................... 35

IV. 응답 처리 ........................................................................................................................................................................................................................................................... 39


페이지 4

I. API 명세서 개요

본 문서는 API 정의와 명세를 포함하며, 개발 목적으로 활용함.

II. API 목록

순번 API ID API 명 (영문) API 명 (한글)

1 businesstype/v1.0/index business type index v1.0 업종 지수 v1.0

2 businesstype/v1.0/code business type code v1.0 업종 코드 v1.0

3 zscore/v1.0/index zscore index v1.0 ZScore 지수 v1.0


페이지 5

III. API 명세서 명세서

1. { /businesstype/v1.0/index }

1.1 API 개요

API

정보

API ID /businesstype/v1.0/index

API 명(국문) 업종 지수 v1.0

API 명(영문) business type index v1.0

API 설명 국내 카드 가맹점들의 업종별/월별 매출 및 거래 건수에 대한 지수 정보

API 보안 API 인증/권한 [O] API Key

API URL 개발환경 (URL) https://sandbox-apigw.koscom.co.kr/bccard/businesstype/v1.0/index

* 샌드박스는 개발을 위한 일부 과거 데이터만 제공 합니다. (최신 데이터 사용을 위해서는 별도의 계약이 필요 합니다.)

1.2 리소스 목록

일련

번호

리소스

이름

메서드

(method) API 리소스 설명

1 /businesstype/v1.0/index GET 전체 업종 지수 리스트 제공(기본 최대 200건)


페이지 6

2 /businesstype/v1.0/index/{code} GET 특정 업종 코드의 지수 리스트 제공

3 /businesstype/v1.0/index/{code}/detail GET 특정 업종 코드의 지수 항목 제공

1.3 리소스 명세

A. /businesstype/v1.0/index

리소스 개요

리소스 번호 1 메서드 GET

리소스 유형 목록 조회 리소스이름 업종 지수 목록

URI /businesstype/v1.0/index

설명 업종 지수 리스트(기본 최대 200건) 제공

Query String 구성

항목 데이터 형 예시 설명

page INT page=0 페이지 번호 (0부터 시작)

size INT size=10 페이지 당 목록 수

search 특정 항목으로 검색, 각각의 검색항목은 ’ ,’ 기호로 구분


페이지 7

세부 항목 데이터 형 예 시 설명

idxYM String search= idxYM:201510

search= idxYM <201511

search= idxYM >201509

search= idxYM >201509, idxYM

<201511

• 특정 날짜로 목록 조회

• 사용 기호

: (equal) < (less than) > (greate than)

, (검색 항목 구분)

sort

날짜 기준으로 정렬


idxYM String sort= idxYM:asc

sort= idxYM:desc

• 특정 날짜로 목록 정렬

• 사용 기호

: (equal)

전문구성

응답전문

순번 항목명 데이터형 설명

1 content

List 항목 목록 리스트

서브 항목 데이터형 설명

idxYM STRING 기준년월 (YYYYMM)

tpBuzCode STRING 업종코드

amtIdx STRING 코스콤 금액 지수

cntIdx STRING 코스콤 건수 지수

2 sort - sort 정보


페이지 8

3 numberOfElements INT 조회된 항목(content) 건수

4 totalPages INT 전체 페이지 개수

5 first BOOLEAN 첫 페이지 여부 (true, false)

6 last BOOLEAN 마지막 페이지 여부 (true, false)

7 size INT 요청한 목록 개수

8 number INT 조회 페이지 순번 (0 부터 시작)

B. /businesstype/v1.0/index/{code}

리소스 개요


리소스 유형 목록 조회 리소스이름 코드별 업종 지수 목록

URI /businesstype/v1.0/index/{code}

설명 • 코드별 업종 지수 리스트(기본 최대 200건) 제공

• {code} 는 업종을 식별하는 ID 이다.

Query String 구성




페이지 9


search

특정 항목으로 검색, 각각의 검색항목은 , 기호로 구분






<201511


• 사용 기호



전문구성

응답전문


1 content



idxYM STRING 기준년월 (YYYYMM)


amtIdx STRING 코스콤 금액 지수

cntIdx STRING 코스콤 건수 지수






페이지 10




C. /businesstype/v1.0/index/{code}/detail

리소스 개요


리소스 유형 상세 조회 리소스이름 업종 지수 상세

URI /businesstype/v1.0/index/{code}/detail

설명 • 코드별 업종 지수 상세


Query String 구성


search







• 사용 기호



페이지 11


<201511


전문구성

응답전문


1 idxYM STRING 기준년월 (YYYYMM)

2 tpBuzCode STRING 업종코드

3 amtIdx STRING 코스콤 금액 지수

4 cntIdx STRING 코스콤 건수 지수

1.4 예시

• BC카드가 제공하는 2015년 11월 전체 업종지수 정보 조회

요청 예시

GET https://sandbox-apigw.koscom.co.kr/bccard/businesstype/v1.0/index?search=idxYM:201511

Accept: application/json;charset=UTF-8

응답 예시

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

https://sandbox-apigw.koscom.co.kr/bccard/businesstype/v1.0/index


페이지 12

Content-Length: 44174

Date: Thu, 13 Jul 2017 07:30:38 GMT

{

"sort": [

{

"direction": "DESC",

"property": "idxYM",

"ignoreCase": false,

"nullHandling": "NATIVE",

"descending": true,

"ascending": false

}

],

"totalPages": 2,

"totalElements": 270,

"numberOfElements": 200,

"last": false,

"first": true,

"size": 200,

"content": [

{

"idxYM": "201511",

"tpBuzCode": "1001",

"amtIdx": "75.36",


페이지 13

"cntIdx": "73.62"

},

{

"idxYM": "201511",


"amtIdx": "83.85",

"cntIdx": "86"

},

.

.

.

{

"idxYM": "201511",


"amtIdx": "95.35",

"cntIdx": "111.8"

},

{

"idxYM": "201511",


"amtIdx": "57.66",

"cntIdx": "62.48"

},


페이지 14

{

"idxYM": "201511",


"amtIdx": "72.41",

"cntIdx": "74.98"

}

],

"number": 0

}


페이지 15

2. { /businesstype/v1.0/code }

2.1 API 개요

API

정보

API ID /businesstype/v1.0/code

API 명(국문) 업종 코드 v1.0

API 명(영문) business type code v1.0

API 설명 BC카드의 가맹점을 통해 분류한 업종 약 270개 업종 코드 및 업종 명 조회

API

보안 API 인증/권한 [O] API Key

API

URL

개발환경 (URL) https://sandbox-apigw.koscom.co.kr/bccard/businesstype/v1.0/code

운영환경 (URL) https://apigw.koscom.co.kr/bccard/businesstype/v1.0/code


일련 번호 리소스 이름 메서드


1 /businesstype/v1.0/code GET 전체 업종 코드 리스트 제공(기본 최대 200건)

2 /businesstype/v1.0/code/{code} GET 특정 업종 코드 상세 정보 제공

https://apidev.bccard.com/apis/businesstype/v1.0/code

https://api.bccard.com/apis/businesstype/v1.0/code


페이지 16


A. /businesstype/v1.0/code

리소스 개요


리소스 유형 목록 조회 리소스이름 업종 코드 목록

URI /businesstype/v1.0/code

설명 BC카드의 가맹점으로 분류한 업종 코드 및 업종 명 리스트(기본 최대 200건)

Query String 구성




search


세부 항목 데이터 형 예시 설명

tpBuzNm STRING search=tpBuzNm:주점 • 특정 업종명으로 목록 조회

• 기호

: (equal)


페이지 17


전문구성

응답전문


1 content




tpBuzNm STRING 업종명








B. /businesstype/v1.0/code/{code}

리소스 개요


페이지 18


리소스 유형 상세 조회 리소스이름 업종 코드 목록

URI /businesstype/v1.0/code/{code}

설명 • BC카드의 가맹점으로 분류한 업종 코드 및 업종 명 상세 정보 제공


Query String 구성


전문구성

응답전문


1 tpBuzCode STRING 업종코드

2 tpBuzNm STRING 업종명


페이지 19

2.4 예시

• BC카드가 제공하는 약270개의 업종 분류 코드 및 업종 명을 제공 (현재 : 201711)

요청 예시

GET https://sandbox-apigw.koscom.co.kr/bccard/businesstype/v1.0/code


응답 예시

HTTP/1.1 200 OK



Date: Thu, 13 Jul 2017 07:30:38 GMT

{

"sort": [

{

"direction": "ASC",

"property": "TP_BUZ_CODE",



"descending": false,

"ascending": true

}


페이지 20

],

"totalPages": 2,



"last": false,

"first": true,

"size": 200,

"content": [

{


"tpBuzNm": "특급 호텔"

},

{


"tpBuzNm": "1급 호텔"

},

{


"tpBuzNm": "2급 호텔"

},

{


"tpBuzNm": "콘 도"

},

.


페이지 21

.

.

{


"tpBuzNm": "칵테일바"

},

{


"tpBuzNm": "주점"

}

],

"number": 0

}

3. { /zscore/v1.0/index }

3.1 API 개요

API

정보

API ID /zscore/v1.0/index

API 명(국문) ZScore 지수 v1.0

API 명(영문) zscore index v1.0.

API 설명 • 카드 빅데이터를 기반으로 상장종목의 월별 매출 추세를 추산해 지수 정보 제공

• 국제코드 종목의 작업기준년월, 가맹점명, 국제종목코드, Z스코어를 조회하는 API


페이지 22

• BC카드가 표준화한 z값만 제공하며, 평균/표준편차는 공개되지 않음

API 보안 API 인증/권한 [O] API Key

API URL 개발환경 (URL) https://sandbox-apigw.koscom.co.kr/bccard/zscore/v1.0/index

* 샌드박스는 개발을 위한 일부 과거 데이터만 제공 합니다. (최신 데이터 사용을 위해서는 별도의 계약이 필요 합니다.)


일련 번호 리소스 이름 메서드


1 /zscore/v1.0/index GET 전체 ZScore 리스트 제공(기본 최대 200건)

2 /zscore/v1.0/index/{code} GET 특정 ZScore 코드 정보 제공


A. /zscore/v1.0/index

리소스 개요


리소스 유형 목록조회 리소스이름 ZScore 목록 조회

URI /zscore/v1.0/index


페이지 23

설명 ZScore 리스트(기본 최대 200건) 정보 제공

Query String 구성




search



regYm STRING

search=idxYM:201503

search=idxYM<201506

search=idxYM>201503

search=idxYM>201503, idxYM<201506

- 등록년월 기준으로 목록 조회

- 기호

: (equal)

< (less than)

> (greate than)


merNm STRING search=merNm:경동가스

- 가맹점명 기준으로 목록 조회

- 기호

: (equal)


페이지 24

전문구성

응답전문


1 content



merNm STRING 가맹점명

koscomTckr STRING 국제표준 (종목코드)

intlTckr STRING 주식종목코드 (단축코드)








B. /zscore/v1.0/index/{code}

리소스 개요


리소스 유형 상세 리소스이름 ZScore 상세


페이지 25

URI /zscore/v1.0/index

설명 종목코드별 ZScore 상세 정보 제공

Query String 구성


search



idxYm STRING

search=idxYM:201503

search=idxYM<201506

search=idxYM >201503

search=idxYM>201503,idxYM<201506

- 등록년월 기준으로 목록 조회

- 기호

: (equal)

< (less than)

> (greate than)


merNm STRING search=merNm:경동가스

- 가맹점명 기준으로 목록 조회

- 기호

: (equal)

전문구성


페이지 26

응답전문


1 merNm String 가맹점 명

2 koscomTckr String 국제표준 (종목코드)

3 intlTckr String 주식종목코드 (단축코드)

4 idxYm String 지수 기준월

5 zScore String Z-Score 값


페이지 27

3.4 예시

A. /zscore/v1.0/index

• BC카드가 zScore를 산출하는 약 95개 종목에 대한 종목정보 조회 (현재 : 201711)

요청 예시

GET https://sandbox-apigw.koscom.co.kr/bccard/ zscore/v1.0/index


응답 예시

HTTP/1.1 200 OK



Date: Thu, 13 Jul 2017 07:30:38 GMT

{

"sort": [

{

"direction": "ASC",

"property": "INTL_TCKR",



"descending": false,

"ascending": true


페이지 28

}

],

"totalPages": 1,



"last": true,

"first": true,

"size": 200,

"content": [

{

"merNm": "메리츠화재",

"koscomTckr": "KR7000060004",

"intlTckr": "000060"

},

{

"merNm": "CJ대한통운",



},

{

"merNm": "기아차",



},

{


페이지 29

"merNm": "한화손해보험",



},

{

"merNm": "삼화페인트",



},

{

"merNm": "롯데손해보험",



},

.

.

.

{

"merNm": "한국타이어",



},

{

"merNm": "골프존",



페이지 30


}

],

"number": 0

}


페이지 31

B. /zscore/v1.0/index/{code}

• 삼성전자의 월별 매출을 추정하여 산출한 zScore 조회

요청 예시

GET https://sandbox-apigw.koscom.co.kr/bccard/ zscore/v1.0/index/005930


응답 예시

HTTP/1.1 200 OK



Date: Thu, 13 Jul 2017 07:30:38 GMT

[

{

"merNm": "삼성전자",


"intlTckr": "005930",

"idxYm": "201504",

"zScore": "0.433700352429091608995559325779713810457"

},

{




페이지 32

"intlTckr": "005930",

"idxYm": "201505",

"zScore": "0.5582539895105550366662095869092192641882"

},

{



"intlTckr": "005930",

"idxYm": "201506",

"zScore": "0.1315526673210397411042276131740144462468"

},

.

.

.

{



"intlTckr": "005930",

"idxYm": "201703",

"zScore": "-1.16219364316722097731611963051710195496"

}

]


페이지 33

IV. 응답 처리

• Header

Status Code Message Description

200 OK The request ha succeeded

201 Create The request has succeeded and a new resource has been created as a

result of it.

204 No Countent There is no content to send for this request.

400 Bad Request This response means that server could not understand the request due

to invalid syntax

401 Unauthorized Authentication is needed to get requested response.

403 Forbidden Client des not have access rights to the content so server is rejecting to

give proper response.

404 Not Found Server can not find requested resource.

405 Method Not Allowed The request method is known by the server but has been disabled and

can not be used.

500 Internal Server Error The server has encountered a situation it doesn’t know how to handle.


페이지 34

• BODY

항목 명 칭 예시

error 에러 코드 {

“error”: “invalid_request”,

“error_description”: “Validation error”,

“details”: “extra error messages”

}

error_description 에러 메시지

details 상세 메시지

- End of Document -

API 서비스 명세서 - Koscom · 2017-11-15 · api 서비스 명세서 페이지 1 변 경 이...

Documents

Transcript of API 서비스 명세서 - Koscom · 2017-11-15 · api 서비스 명세서 페이지 1 변 경 이...