빌링 구매 리스트 조회- 운영툴용 playerId 조건
기본 정보
- 빌링 시스템에 구매 요청된 리스트를 조회하는 API
- playerId 조건으로 조회하는 기능으로 게임 운영툴에서만 사용할 목적의 API
경고
부하가 큰 조회일 가능성이 있기 때문에 내부적으로 분리된 Read DB를 이용할 수도 있습니다.
- 인게임의 일반 결제 로직에서 사용하면 안되는 API입니다.
- 운영툴 용도로만 사용해야합니다.
| 항목 | 내용 | 비고 |
|---|---|---|
| 호출주체 | 게임서버(s2s API) | |
| 도메인 | 각 환경별 도메인 | |
| 인증 방식 | HTTP 헤더 인증 정보 | |
| HTTP 메소드 | POST | |
| Content-Type | application/json |
Request
HTTP Request end point
POST https://각 환경별 빌링API 도메인/billing/api-game/v1/purchase/optool/playerId/list
HTTP Request Header
- 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
HTTP Request Parameter
- 아래 파라미터들을 Content-Type: application/json으로 호출하면 됩니다.
| 이름 | 데이터 타입 | 필수여부 | 설명 | 예 |
|---|---|---|---|---|
| pjid | String(20) | Y | 프로젝트ID
| 1201 |
| playerId | String(50) | Y | 구매를 진행했던 유저의 ID(게임에서 결제 스콥을 관리하고 싶은 id값으로 사용. 게임에서 추가 구분이 없다면 imid를 사용할 수도 있음) | |
| purchaseStatus | String(30) | N | 빌링시스템에 구매 상태 | 코드 표 참고 |
| startReservedAtUnixTS | Long | Y | 예약일시 기준의 조회 범위: 시작
| 1753153578 |
| endReservedAtUnixTS | Long | Y | 예약일시 기준의 조회 범위: 종료
| 1756549738 |
| pageItemSize | int | Y | 한 페이지에서 가져올 데이터 개수(1~100) | |
| pageNo | int | Y | 조회할 페이지 번호(1부터 시작함) |
HTTP Request Parameter(Sample json)
요청 샘플 json입니다. 하단 curl 커맨드를 참고하셔도 좋습니다.
{
"pjid": "1201",
"playerId": "NN5UN8NDL4TYDT7H9WWG",
"startReservedAtUnixTS": 1719307665,
"endReservedAtUnixTS": 1722670867,
"pageItemSize": 3,
"pageNo": 1
}
- 응답은 JSON Array형태로 전달됩니다.
- 파라미터 boid 중에서 존재하지 않는 잘 못된 boid의 데이터는 응답되지 않습니다.
Response property
| key | data type | not null | description | example |
|---|---|---|---|---|
| existNextPageYn | String(1) | Y | 다음 페이지 데이터가 존재하는지 여부
| Y 또는 N |
| purchaseList | purchaseList json의 array | Y | 구매 리스트
|
purchaseList Json
- 구매 상태 등에 따라서 일부 필드의 값은 null일 수 있습니다.
| key | data type | not null | description | example |
|---|---|---|---|---|
| boid | String(20) | Y | 빌링 시스템의 주문ID | 4 |
| reservedAtUnixTS | Long | Y | 구매 예약된 일시
| 1720523107 |
| pjid | String(20) | Y | 프로젝트ID | 1201 |
| svcId | String(20) | Y | 서비스ID | 121010041 |
| purchaseStatus | String(30) | Y | 빌링시스템에 구매 상태 | 코드 표 참고 |
| payment | String(20) | Y | 결제가 진행된 스토어
| GOOGLE_PLAY |
| appStore | String(20) | Y | 앱을 다운로드한 플랫폼 스토어
| GOOGLE_PLAY_PC |
| imid | String(40) | N
| IMID
| aaaabbbb-ccccddd-fffccc-tttggg |
| playerId | String(50) | Y | 구매를 진행한 유저의 ID
| |
| productId | String(50) | Y | 구매 진행한 상품ID | |
| totalMicroPrice | Long | Y | 구매 금액 전체의 micro단위
| 2200000000 |
| currency | String(10) | N | 구매 금액의 화폐 단위
| USD |
| completedAtUnixTS | Long | N | 구매 완료된 일시 Unix Timestamp 타입 | 1720523107 |
| canceledAtUnixTS | Long | N | 구매 취소된 일시
| 1720523107 |
| os | String(10) | Y | 구매한 디바이스의 OS | |
| paymentOrderId | String(100) | N | 결제가 진행된 payment의 주문ID
| |
| paymentTesterPurchaseYn | String(1) | N | 스토어에 등록된 테스터의 결제 여부
|
Sample
Success Sample
{
"resultCode": "SUCCESS",
"resultMessage": "request success.",
"resultData": {
"existNextPageYn": "Y",
"purchaseList": [
{
"boid": "38",
"reservedAtUnixTS": 1722670867,
"pjid": "1201",
"svcId": "10040200",
"purchaseStatus": "RESERVED",
"payment": "GOOGLE_PLAY",
"appStore": "GOOGLE_PLAY",
"imid": "NN5UN8NDL4TYDT7H9WWG",
"playerId": "NN5UN8NDL4TYDT7H9WWG",
"productId": "item.bag.blue",
"totalMicroPrice": null,
"currency": null,
"completedAtUnixTS": null,
"canceledAtUnixTS": null,
"os": "ANDROID",
"paymentOrderId": null,
"paymentTesterPurchaseYn": null
},
{
"boid": "28",
"reservedAtUnixTS": 1719970957,
"pjid": "1201",
"svcId": "10040200",
"purchaseStatus": "VERIFY_SUCCESS",
"payment": "GOOGLE_PLAY",
"appStore": "GOOGLE_PLAY",
"imid": "NN5UN8NDL4TYDT7H9WWG",
"playerId": "NN5UN8NDL4TYDT7H9WWG",
"productId": "item.bag.blue",
"totalMicroPrice": 11000000000,
"currency": "KRW",
"completedAtUnixTS": 1719971000,
"canceledAtUnixTS": null,
"os": "ANDROID",
"paymentOrderId": "GPA.3328-3141-9896-82116",
"paymentTesterPurchaseYn": "Y"
},
{
"boid": "27",
"reservedAtUnixTS": 1719970887,
"pjid": "1201",
"svcId": "10040200",
"purchaseStatus": "COMPLETED",
"payment": "GOOGLE_PLAY",
"appStore": "GOOGLE_PLAY",
"imid": "NN5UN8NDL4TYDT7H9WWG",
"playerId": "NN5UN8NDL4TYDT7H9WWG",
"productId": "item.bag.blue",
"totalMicroPrice": 11000000000,
"currency": "KRW",
"completedAtUnixTS": 1719970902,
"canceledAtUnixTS": null,
"os": "ANDROID",
"paymentOrderId": "GPA.3349-0630-2483-54115",
"paymentTesterPurchaseYn": "Y"
}
]
}
}
Error Sample
- pageItemLimit가 너무 클 때
{
"resultCode": "INVALID_PARAMETER",
"resultMessage": "'pageItemLimit' must be between 1 and 100",
"traceId": "b_48fac24f63f5"
}
- 시작과 종료일 범위가 최대 조회기간인 50일을 넘을 때
{
"resultCode": "INVALID_PARAMETER",
"resultMessage": "The maximum search period is '50' days.",
"traceId": "b_951c9a963d88"
}
- 시작이 종료일보다 나중일 때
{
"resultCode": "INVALID_PARAMETER",
"resultMessage": "startReservedAtUnixTS must be less than endReservedAtUnixTS.",
"traceId": "b_45ce98a4d4e4"
}
에러 코드 정의
- 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
- 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
- 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
- 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.
| 에러코드 | 비고 |
|---|---|
| SYSTEM_ERROR | 빌링 API에서 발생한 시스템 에러
|
| NOT_ALLOW_AUTH | API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생 |
- 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
| 에러코드 | 비고 |
|---|---|
| INVALID_PARAMETER |
요청 curl Sample
- 도메인 및 인증 헤더 등은 변경 필요
curl -X 'POST' \
'http://localhost:10001/billing/api-game/v1/purchase/optool/playerId/list' \
-H 'accept: application/json;charset=UTF-8' \
-H 'X-Req-Pjid: 입력필요' \
-H 'X-Auth-Access-Key: 입력필요' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"pjid": "1201",
"playerId": "NN5UN8NDL4TYDT7H9WWG",
"startReservedAtUnixTS": 1719307665,
"endReservedAtUnixTS": 1722670867,
"pageItemSize": 3,
"pageNo": 1
}'