Google Play Developer API의 purchases.products.get(모바일/PC 공용) - GM툴 전용

기본 정보

Google Play Developer API 중 purchase.products.get을 랩핑해서 GM툴 등에서 사용할 목적으로 제공하는 API
1. 주의: 해당 API를 호출량이 많은 게임서버 등에서 사용하면 전체 API에 limit가 걸려서 결제에 문제가 생길 수 있으니 주의해서 사용(꼭 GM툴 등에서만 제한적으로사용)
해당 Google API는 상품 ID와 구매 토큰이 필수이며 상품 ID는 boid로 빌링 예약에 요청된 상품ID로 요청됩니다.

항목	내용	비고
호출주체	게임서버(s2s API)
도메인	각 환경별 도메인
인증 방식	HTTP 헤더 인증 정보
HTTP 메소드	POST
Content-Type	application/json

Request

HTTP Request end point

POST https://각 환경별 빌링시스템 도메인 /billing/api-game/v1/purchase/google/play/developer-api/purchases/products/get/forTool

HTTP Request Parameter

Content-Type: application/json 으로 요청되어야 합니다.

이름	데이터 타입	required Y/N	설명	예
pjid	String(20)	Y	프로젝트ID 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음	1004
boid	String(20)	Y	빌링 시스템 구매 예약 API를 통해서 생성된 ID	1234
googlePurchaseToken	String	N	구글 플레이 콘솔에서 확인 가능한 ‘구매토큰’ 미 입력시 빌링 시스템에 저장되어 있다면 boid로 해당 토큰을 이용해서 구글 API로 조회 입력되어 API요청되면 요청된 토큰 값으로 Google API 호출

이름

데이터 타입

required Y/N

설명

예

pjid

String(20)

프로젝트ID

동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음

1004

boid

String(20)

빌링 시스템 구매 예약 API를 통해서 생성된 ID

1234

googlePurchaseToken

String

구글 플레이 콘솔에서 확인 가능한 ‘구매토큰’

미 입력시 빌링 시스템에 저장되어 있다면 boid로 해당 토큰을 이용해서 구글 API로 조회
입력되어 API요청되면 요청된 토큰 값으로 Google API 호출

Response

응답은 JSON형태로 전달됩니다.

Response property

key	data type	description	example
billingPurchase	billingPurchase JSON	빌링의 구매 내역 참고 정보
googlePurchase	googlePurchase JSON	Google API(링크) 호출 후 응답결과 일부를 그대로 전달

billingPurchase JSON

key	data type	not null Y/N	description	example
reservedAtUnixTS		Y	빌링 구매 예약일시	1711635322
purchaseStatus	String(30)	Y	빌링시스템의 구매 상태 코드 상세내용은 코드표 참고	COMPLETED
payment	String(20)	Y	결제 수단 코드 결제가 진행된 스토어(돈을 지급한 행위가 발생한 스토어)	GOOGLE_PLAY
appStore	String(20)	Y	상점 코드 앱 스토어 코드 또는 상점 구분 코드	GOOGLE_PLAY_PC(구글PC) GOOGLE_PLAY(모바일)
productId	String(200)	Y	상품ID	google_com.hybeim.astra_belle0001
totalMicroPrice	Long	Y	구매 금액 micro단위 price에 100만을 곱한 값	22000000000
currency	String(10)	Y	구매 금액의 화폐 단위 3글자 포맷의 ISO-4217	KRW
completedAtUnixTS	Long	N	완료일시 주의: 완료상태가 아니었었다면 null일 수 있음	1711635331

googlePurchase JSON

Google Play Developer API 중 purchases.products를 이용해서 그대로 리턴
- 주의: 구글 API 정의서 문서가 업데이트 안된 부분이 있음

key	data type	not null Y/N	description	example
purchaseTimeMillis	Long	Y	The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).	1712021055660
purchaseState	Integer	Y	The purchase state of the order. Possible values are: 0. Purchased 1. Canceled 2. Pending 주의: 실제로 4 리턴되는 경우가 간혹 확인됨	0
consumptionState	Integer	Y	The consumption state of the inapp product. Possible values are: 0. Yet to be consumed 1. Consumed	1
orderId	String	Y	The order id associated with the purchase of the inapp product.	GPA.3347-7191-1433-51811
purchaseType	Integer	N	The type of purchase of the inapp product. This field is only set if this purchase was not made using the standard in-app billing flow. Possible values are: 0. Test (i.e. purchased from a license testing account) 1. Promo (i.e. purchased using a promo code) 2. Rewarded (i.e. from watching a video ad instead of paying) 주의: null 리턴되는 경우 존재	null 0
regionCode	String	N	ISO 3166-1 alpha-2 billing region code of the user at the time the product was granted. 주의: null 리턴되는 경우 존재	US

Success sample

{
  "resultCode": "SUCCESS",
  "resultMessage": "request success",
  "resultData": {
    "billingPurchase": {
      "reservedAtUnixTS": 1711635322,
      "purchaseStatus": "COMPLETED",
      "payment": "GOOGLE_PLAY",
      "appStore": "GOOGLE_PLAY_PC",
      "productId": "google_com.hybeim.astra_belle0001",
      "totalMicroPrice": 22000000000,
      "currency": "KRW",
      "completedAtUnixTS": 1711635331
    },
    "googlePurchase": {
      "purchaseTimeMillis": 1712021055660,
      "purchaseState": 0,
      "consumptionState": 1,
      "orderId": "GPA.3347-7191-1433-51813",
      "purchaseType": null,
      "regionCode": "US"
    }
  }
}

Error sample

boid가 존재하지 않음

{
  "resultCode": "INVALID_PARAMETER",
  "resultMessage": "not exist boid Billing data. boid: '2118'",
  "traceId": "b_50fd831689b2"
}

잘못된 purchase token으로 요청되어 구글 API가 에러 발생

{
  "resultCode": "EXTERNAL_API_ERROR",
  "resultMessage": "Google Play Developer API(purchases.products.get) error: '400 Bad Request\nGET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/com.hybeim.astra/purchases/products/google_com.hybeim.astra_belle0001/tokens/%E3%85%81%E3%85%81\r\n{\n  \"code\": 400,\n  \"errors\": [\n    {\n      \"domain\": \"global\",\n      \"message\": \"Invalid Value\",\n      \"reason\": \"invalid\"\n    }\n  ],\n  \"message\": \"Invalid Value\"\n}'",
  "traceId": "b_eb2050d044dd"
}

에러 코드 정의

resultCode에 올 수 있는 에러 코드입니다.
SDK 스펙상 해당 코드일 경우에도 상태코드는 200으로 리턴 됩니다.

에러코드	비고
INVALID_PARAMETER
EXTERNAL_API_ERROR	빌링 API가 호출하는 외부 API가 에러인 경우 예) 구글 API 장애로 구매의 상태 정보를 받아오지 못하는 경우 게임 서버는 지수 백오프 알고리즘으로 재 시도하거나 클라이언트의 미 처리 영수증 처리 기능으로 처리할 수 있음

에러코드

비고

INVALID_PARAMETER

EXTERNAL_API_ERROR

빌링 API가 호출하는 외부 API가 에러인 경우

예) 구글 API 장애로 구매의 상태 정보를 받아오지 못하는 경우
게임 서버는 지수 백오프 알고리즘으로 재 시도하거나 클라이언트의 미 처리 영수증 처리 기능으로 처리할 수 있음

요청 curl 샘플

도메인은 각 환경에 맞게 변경 필요

curl -X 'POST' \
  'http://localhost:10001/billing/api-game/v1/purchase/google/play/developer-api/purchases/products/get/forTool' \
  -H 'accept: application/json;charset=UTF-8' \
  -H 'X-Req-Pjid: required' \
  -H 'X-Auth-Access-Key: required' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
  "pjid": "1004",
  "boid": "28"

}'

기본 정보​

Request​

HTTP Request end point​

HTTP Request Parameter​

Response​

Response property​

googlePurchase JSON​

Success sample​

Error sample​

에러 코드 정의​

요청 curl 샘플​