사이드 메뉴
커뮤니케이션
API 제공
어드민 API
Legacy REST API
이 문서는 일부 REST API의 기존 버전 사용 방법을 안내합니다. 이 문서는 예고 없이 변경 또는 삭제될 수 있으므로, 가급적 최신 버전 사용을 권장합니다.
| 메서드 | 호스트 | Internal URL | External URL |
|---|---|---|---|
GET | kapi.kakao.com | - | /v1/account/service_purchase_history |
| 데이터 | 동의항목 |
|---|---|
| 카카오 T 최근 6개월 탑승 정보 카카오 T 가입 일시(연결 시각), 택시 서비스 유형별 탑승 횟수, 택시 서비스 유형별 예상 요금 합계, 미수금 존재 여부 중요: 카카오 T 앱과 연결(가입)된 사용자인 경우에만 데이터 제공 참고: 택시 서비스 유형은 일반, 블루, 블랙 세 가지 | 카카오택시 최근 6개월 탑승정보(탑승횟수, 예상금액 등) |
| 카카오쇼핑 최근 6개월 이용 정보 카카오쇼핑 가입 일시(연결 시각), 조회 기간, 총 구매 횟수, 서비스 유형별 상세 이용 내역(지불 방법, 구매 횟수, 총 구매 금액, 취소 및 환불 건수, 총 취소 및 환불 금액) 중요: 카카오쇼핑 앱과 연결(가입)된 사용자인 경우에만 데이터 제공 참고: 서비스 유형은 배송 상품, 모바일 교환권 두 가지 | 카카오쇼핑 최근 6개월 이용정보(구매횟수, 환불횟수, 누적액 등) |
사용자의 최근 6개월간 카카오 서비스 이용 내역을 조회합니다. 조회 가능한 서비스 종류와 제공하는 데이터는 위 필요한 동의항목 표를 참고합니다.
액세스 토큰을 헤더에 담아 GET으로 요청합니다. 이 API는 사용 협의 시 등록한 카카오뱅크의 전용망을 이용해 HTTPS로 요청해야 합니다.
요청 성공 시 사용자의 최근 6개월 카카오 서비스 이용 내역 데이터를 받습니다. 이 API는 요청 시점에서 사용자가 각 조회 대상 서비스를 이용해 해당 서비스 앱과 연결(가입)되어 있고, 서비스별 필요한 동의항목에 동의한 경우에만 데이터를 제공합니다. 사용자가 이용하지 않는 서비스이거나 제공에 동의하지 않은 데이터는 응답에 포함되지 않습니다.
헤더
| 이름 | 형식 | 설명 |
|---|---|---|
| 액세스 토큰 방식 | Authorization: Bearer ${ACCESS_TOKEN} | 서비스 앱에서 액세스 토큰으로 요청합니다. |
| 서비스 앱 어드민 키 방식 | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} | 서비스 앱에서 어드민 키와 사용자 ID로 요청합니다. |
서비스 앱 어드민 키 방식
서비스 앱 어드민 키 방식은 테스트 전용입니다. 실제 서비스에서 이 API는 액세스 토큰 방식으로만 호출해야 합니다.
- 없음
- 이 요청 방식은 테스트 전용으로 실제 서비스에서 사용할 수 없습니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 카카오 서비스 이용 내역을 조회할 사용자의 카카오뱅크 회원번호 | O |
| target_id_type | String | target_id 타입회원번호( user_id)로 고정참고: ID 종류 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 사용자의 카카오뱅크 회원번호 | O |
| taxi_passenger_history | TaxiPassengerHistory | 사용자의 최근 6개월간 카카오 T 택시 이용 내역 필요한 동의항목: 카카오택시 최근 6개월 탑승정보(탑승횟수, 예상금액 등) 중요: 사용자가 카카오 T 서비스에 연결(가입)된 경우에만 데이터 제공 | X |
| commerce_order_history | CommerceOrderHistory | 사용자의 최근 6개월간 카카오쇼핑 이용 내역 필요한 동의항목: 카카오쇼핑 최근 6개월 이용정보(구매횟수, 환불횟수, 누적액 등) 중요: 사용자가 카카오쇼핑 서비스에 연결(가입)된 경우에만 데이터 제공 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| registered_at | Datetime | 카카오 T 가입 일시, UTC* | O |
| has_outstanding_payments | Boolean | 미수금 존재 여부 | X |
| count_of_completed_calls | Call | 최근 6개월간 탑승 횟수 | X |
| sum_of_fares | Call | 최근 6개월간 예상 요금 합계 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| medium | Integer | 중형 택시 이용 내역 상위 필드가 count_of_completed_calls인 경우: 탑승 횟수상위 필드가 sum_of_fares인 경우: 예상 요금 합계 | X |
| deluxe | Integer | 모범 택시 이용 내역 상위 필드가 count_of_completed_calls인 경우: 탑승 횟수상위 필드가 sum_of_fares인 경우: 예상 요금 합계 | X |
| luxury | Integer | 블랙 택시 이용 내역 상위 필드가 count_of_completed_calls인 경우: 탑승 횟수상위 필드가 sum_of_fares인 경우: 예상 요금 합계 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| registered_at | String | 카카오쇼핑 가입 일시, UTC* | O |
| from_date | String | 이용 내역 조회 대상 기간의 시작 일시, UTC* 참고: 정확한 조회 기간 파악을 위해 제공하는 정보 | O |
| to_date | String | 이용 내역 조회 대상 기간의 종료 일시, UTC* 참고: 정확한 조회 기간 파악을 위해 제공하는 정보 | O |
| total_order_count | Integer | 조회 기간 중 총 구매 횟수 참고: 포인트 복합 결제로 인해 총 구매 횟수와 order_list의 구매 내역 건수가 일치하지 않을 수 있음 | X |
| order_list | OrderList | 조회 기간 중 상세 이용 내역 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| pay_method | PayMethod | 지불 방법, PayMethod 중 하나중요: 카카오쇼핑 이용 내역은 지불 방법별로 합산해 제공됨 | O |
| order_count | Integer | pay_method의 구매 횟수 | O |
| order_sum | Integer | pay_method의 주문 금액의 합 | O |
| cancel_count | Integer | pay_method의 취소 및 환불 수 | O |
| cancel_sum | Integer | pay_method의 취소 및 환불 금액의 합 | O |
| 이름 | 값 |
|---|---|
| Mobile | 휴대전화 결제 |
| Card | 신용카드 |
| KakaoBankWalletCard | 뱅크월렛 카카오 |
| KakaoBankWalletCardGift | 뱅크월렛 카카오 |
| KakaoBankWalletMoney | 뱅크월렛 카카오 |
| KakaoBankWalletMoneyGift | 뱅크월렛 카카오 |
| KakaoSimplePayment | 카드 간편결제 |
| KakaoSimpleMobile | 휴대전화 간편결제 |
| KakaoEasyBank | 카카오머니 결제 |
| KakaoB2bPrePayment | B2B 선결제 |
| KakaoB2bAfterPayment | B2B 후결제 |
| KakaoPayEasyCard | 카카오페이카드 |
| KakaoPayEasyPoint | 카카오페이머니 |
| BankAccount | 무통장입금 |
| KakaoPoint | 쇼핑 포인트 |
| PayOffZeroAmount | 무료 구매 |
예제
요청: 액세스 토큰 방식
- 파라미터: 없음
curl -v -G GET "https://kapi.kakao.com/v1/account/service_purchase_history" \-H "Authorization: Bearer ${ACCESS_TOKEN}"
응답: 사용자가 조회 대상 서비스에 연결(가입)되지 않은 경우
// HTTP/1.1 200 OK{"id": 1376016924429759243}
응답: 사용자의 조회 대상 서비스 이용 내역이 없는 경우
- 사용자가 카카오 T, 카카오쇼핑에 연결(가입)되었으나 최근 6개월간 이용 내역이 없음
// HTTP/1.1 200 OK{"id": 1376016924429759243,"taxi_passenger_history": {"registered_at": "2016-12-23T16:30:00Z"},"commerce_order_history": {"registered_at": "2014-06-04T14:48:22Z"}}
응답: 카카오 T와 카카오쇼핑 이용 내역 조회
// HTTP/1.1 200 OK{"id": 1376016924429759243,"taxi_passenger_history": {"registered_at": "2016-12-23T16:30:00Z","has_outstanding_payments": false,"count_of_completed_calls": {"medium": 268,"deluxe": 11,"luxury": 88},"sum_of_fares": {"medium": 25362637,"deluxe": 248080,"luxury": 4180800}},"commerce_order_history": {"registered_at": "2014-06-04T14:48:22Z","from_date": "2016-08-08T09:09:11Z","to_date": "2017-02-08T09:09:11Z","total_order_count": 1533,"order_list": {"delivery": [{"pay_method": "Mobile","order_count": 7,"order_sum": 4310,"cancel_count": 7,"cancel_sum": 4310},{"pay_method": "KakaoPoint","order_count": 1541,"order_sum": 722912,"cancel_count": 252,"cancel_sum": 318390}],"voucher": [{"pay_method": "Mobile","order_count": 13,"order_sum": 7500,"cancel_count": 13,"cancel_sum": 7500},{"pay_method": "KakaoPoint","order_count": 340,"order_sum": 265100,"cancel_count": 217,"cancel_sum": 154680}]}}}
응답: 카카오 T 서비스 이용 내역 조회, 미수금 있음
// HTTP/1.1 200 OK{"id": 1376016924429759243,"taxi_passenger_history": {"registered_at": "2016-12-23T16:30:00Z","has_outstanding_payments": true, // 미수금 존재 시 true"count_of_completed_calls": {"medium": 268,"deluxe": 11,"luxury": 88},"sum_of_fares": {"medium": 25362637,"deluxe": 248080,"luxury": 4180800}}}