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

기본 정보

1. Google Play Developer API 중 purchase.products.get을 랩핑해서 GM툴 등에서 사용할 목적으로 제공하는 API

   1. 주의: 해당 API를 호출량이 많은 게임서버 등에서 사용하면 전체 API에 limit가 걸려서 결제에 문제가 생길 수 있으니 주의해서 사용(꼭 GM툴 등에서만 제한적으로사용)

2. 해당 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 호출 Open image-20240409-013454.png	enkkffhocgldhgiekaccejgg.AO-J1OwnKm6Qa-08VFgLfGl1ATomhD3XLtCdfFZ_DUp5Zt1R8zGx6DgXlFqT-pqRpGVgKJr--iQVd049gygu_Eh9H0WeWNM4lA

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

요청 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" }'