> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codashop-yu-distrubution/ji-cheng-zhi-nan/usersync-api-qing-qiu/usersync-api-qing-qiu-shi-li-yu-xiang-ying.md). # UserSync API 请求示例与响应 ## **UserSync API 请求** #### 示例 格式 JSON-RPC ```javascript // { "id": "6164695159717629913", "jsonrpc": "2.0", "method": "syncUser", "params": [ { "isForTest": 1, "serviceProvider": "Coda", "purchaseOrigin": "TH", "user": { "userId": "111111", "zoneId": "101" }, "signature": "4646fbd3363ab452f40187f8744cd321f71968ed01cdc19c416203832cddd76e" } ] } ```
参数名称类型描述
id字符串唯一标识此次 API 调用的 ID。
jsonrpc字符串固定为 "2.0"，符合 json-rpc 标准。
method字符串固定为 "syncUser"。
params.serviceProvider字符串支付服务提供商名称，默认值为 "Coda"，合作伙伴可自定义。
params.isForTest整数是否为测试订单的标志：1 表示沙盒测试订单，0 表示真实订单。
params.signature字符串根据消息内容生成的签名，详见“签名计算”部分。
params.user.userId字符串用户在合作伙伴系统中的用户 ID 或玩家 ID。
params.user.zoneId字符串用户的区服 ID（服务器 ID），如无需要，默认值为 ""（空字符串）。
params.purchaseOrigin字符串用户发起购买时所在的国家/地区，使用 ISO 两位国家代码（例如 "US"、"SG"）。
参考：https://www.iban.com/country-codes
## 签名计算（Signature Calculation） 所有请求中必须包含签名。请求的签名是对以下字段按正确顺序进行哈希计算的结果： ### **UserSync API 请求：** `id + jsonrpc + method + serviceProvider + userId + zoneId + isForTest` ### **Validate 和 Topup API** 请求： `id + jsonrpc + method + serviceProvider + txnId + orderId + userId + zoneId + currency + amount + sku + quantity + paymentChannelId + isForTest (+ roleId)`
## UserSync API 响应 UserSync API 响应描述了合作伙伴对 UserSync API 请求的回应。 以下为有效及无效 UserSync API 响应的示例。 ### 有效 UserSync API 响应 #### 示例 1： **格式**：JSON-RPC ```javascript // { "id": "6164695159717629913", "jsonrpc": "2.0", "result": { "username": "Randy", "originCountry": "ID", } } ``` #### 示例 2： 如果发布者希望根据游戏内用户信息发送元数据以展示个性化 SKU 列表 ```javascript // { "id": "6164695159717629913", "jsonrpc": "2.0", "result": { "username": "Randy", "metadata": { "originCountry": "ID", "inGameLevel": "Gold Level" "roleInfo": "Warrior" },"personalisedSkus": [ { "skuId": "100_diamonds_coda", "description": "100 Diamonds", "details": { "status": 1 "category": "vip-cash", "price": 1.25, "currency": "USD", "pendingPurchaseLimit": 5 "validTill": "2025-04-29 00:00:00" "imageUrl": "https: //cdn1.partner.com/S/content/common/images/denom-image/BGMI/100x100/60_bgmi_uc.png" } }, { "skuId": "1000_diamonds_coda", "description": "100 Diamonds", "details": { "status": 2 "category": "growth", "price": 150000, "currency": "IDR", "pendingPurchaseLimit": 0, "imageUrl": "https: //cdn1.partner.com/S/content/common/images/denom-image/BGMI/100x100/60_bgmi_uc.png" } } ] } } ```
参数名称描述
id与请求关联的消息 ID。
jsonrpc固定为 "2.0"，符合 JSON-RPC 标准。
result表示成功的对象。
result.username玩家用户名、昵称或其他可用来让用户确认充值账号的信息。例如：唯一玩家 ID 为 “123456789”，用户名可能是 “Terminator123”（不一定唯一）。
result.metadata发行商可使用该字段补充信息，如用户所属国家、游戏等级、角色列表或角色信息等。（可选）
result.personalisedSkus用户可见的个性化 SKU 列表。（可选）
result.personalisedSkus.skuIdSKU 的唯一标识符。（可选）
result.personalisedSkus.descriptionSKU 的名称或描述信息。（可选）
result.personalisedSkus.details包含 SKU 详细信息的对象。（可选）
result.personalisedSkus.statusSKU 状态：
0 = INACTIVE（锁定/禁用）
1 = ACTIVE（可用）
2 = PURCHASED（已购买）
result.personalisedSkus.details.categorySKU 的分类或子类型。（可选）
result.personalisedSkus.details.price需要在充值 API 中发送给发行商的价格。（可选）
result.personalisedSkus.details.currency充值时发送给发行商的货币单位。（可选）
result.personalisedSkus.details.pendingPurchaseLimit根据当前资格，用户可购买该 SKU 的最大数量。（可选）
result.personalisedSkus.details.validTillSKU 可购买的截止时间，格式为 YYYY-MM-DD HH:MM:SS。（可选）
result.personalisedSkus.metadata.imageUrl指向合作方 CDN 中某个 SKU 的图片链接。（可选）
### 无效 UserSync API 响应 **格式**：JSON-RPC ```javascript // { "id": "6164695159717629913", "jsonrpc": "2.0", "error": { "code": -100, "message": "Invalid user ID" } } ``` | 参数名称 | 描述 | | ------------- | ------------------------- | | id | 与该响应关联的消息 ID。 | | jsonrpc | 固定为 "2.0"，符合 JSON-RPC 标准。 | | error.code | 表示错误原因的代码。 | | error.message | 说明错误情况的消息内容。 | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codashop-yu-distrubution/ji-cheng-zhi-nan/usersync-api-qing-qiu/usersync-api-qing-qiu-shi-li-yu-xiang-ying.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.