> ## Documentation Index
> Fetch the complete documentation index at: https://docs.renaiss.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 实物兑换接入指南

> 检查兑换资格、查询运费、提交已核对的订单，并跟踪配送。

持有托管卡牌的钱包可以申请实物配送。所有 `/v2/redeem` 请求均需要后端的开发者密钥及同一 EOA 的[钱包会话](https://docs.renaiss.xyz/cn/authentication.md#验证配送钱包)。GET 请求需要 `redeem:read`，其他方法需要 `redeem:write`。提交结账还需要钱包签名。

## 金库地区与批次

先[查询金库地区](https://docs.renaiss.xyz/cn/api-reference/redeem/list-regions.md)，查看钱包在各地区可兑换的卡牌数量。用户选定地区后，用 `countryCode`（例如 `HK`）[查询该地区可兑换的卡牌](https://docs.renaiss.xyz/cn/api-reference/redeem/list-eligible-cards.md)。每张卡会返回 `regionCountryCode` 和 `vaultDisplayName`。

每次结账可包含同一金库地区最多 50 个不同的代币 ID。两张香港金库的卡可以一起报价；马来西亚金库的卡需另行报价和结账，即便收件人相同。**收件地**另填在 `address.countryCode`。

## 从选择卡牌到下单

1. **验证收货地址。** 调用[验证配送地址](https://docs.renaiss.xyz/cn/api-reference/redeem/validate-address.md)时，在请求体顶层传入 `countryCode`、`addressLine1`、`city` 和 `postalCode`。按需填写 `addressLine2` 和 `state`，并根据响应中的 `status` 和 `detail` 确认地址。
2. **获取运费报价。** 调用[查询运费](https://docs.renaiss.xyz/cn/api-reference/redeem/quote-shipping.md)，传入选定的 `tokenIds`，将收货地址放在 `address` 对象中。保存 `quoteId` 和 `expiresAt`。向用户展示快递选项、保险和报价中的 `handlingFeeInUsd`。若费用减免，该值可为零。地址表单的国家及地区列表由应用提供。
3. **准备结账。** 调用[准备结账](https://docs.renaiss.xyz/cn/api-reference/redeem/prepare-checkout.md)，传入 `quoteId`、`courierId`、`recipient` 和 `insurance`。保存 `preparationId`。请用户确认卡牌、收件人、地址和总额，另行列出预估关税及税款。

## 核对签名内容

兑换完成后，所选 NFT 将被永久销毁。请求钱包签名前，逐项核对：

* 将钱包、链、卡牌 ID、收件人、地址、快递及 `totalFeeInUsdt` 与用户确认的订单对照。
* 确认代币及合约可信、授权未过期、钱包余额及授权额度充足。如需向 Permit2 授权 USDT，先等待交易确认。
* 核对 `permitTypedData` 中的 witness 与 `redemptionTypedData` 中兑换批次的哈希，再请钱包签署许可。如有变化，先返回确认页。

> [accordion] 使用 TypeScript SDK 签名
>
> ```ts theme={null}
> import {
>   getError, getValue, isFailed,
>   type PreparedRedemption, type RedemptionClient, type RedemptionExpectation,
> } from '@renaiss-protocol/client';
>
> export async function signReviewedCheckout(
>   shipping: RedemptionClient,
>   prepared: PreparedRedemption,
>   reviewed: RedemptionExpectation,
> ) {
>   const result = await shipping.signRedemption({ prepared, expected: reviewed });
>   if (isFailed(result)) throw new Error(getError(result).detail);
>   return getValue(result);
> }
> ```

使用 `preparationId` 和 `signature` [提交一次结账](https://docs.renaiss.xyz/cn/api-reference/redeem/submit-checkout.md)。保存返回的 `requestId`，用于[跟踪订单](https://docs.renaiss.xyz/cn/api-reference/redeem/get-order.md)。

## 过期与恢复

报价有效期为十分钟。结账准备沿用原报价的到期时间。任一数据在提交前过期，都要重新报价并请用户核对价格。

如果未收到结账响应，先查 `GET /checkout/{preparationId}`，再判断是否需要付款。结账状态保留 24 小时。会话过期时，重新验证同一钱包即可恢复。按钱包和链保存待处理 ID，恢复日志中不要记录签名、令牌或收货信息。

## 订单与物流

[查询订单列表](https://docs.renaiss.xyz/cn/api-reference/redeem/list-orders.md)可查看摘要。使用 `requestId` 可[查询单笔订单](https://docs.renaiss.xyz/cn/api-reference/redeem/get-order.md)。如果新订单还未出现在列表中，可先查看[结账状态](https://docs.renaiss.xyz/cn/api-reference/redeem/get-checkout.md)或订单详情。需要更新配送进度时，[刷新物流信息](https://docs.renaiss.xyz/cn/api-reference/redeem/refresh-tracking.md)。

有数据时展示 `shipmentStatus`、`trackingNumber`、`trackingUrl` 和 `trackingLastSyncedAt`。支持 `trackingStage` 的部署可区分处理中、出库、运输和送达。创建或更新时间本身不能证明已发货。

请在目标环境的 [HTTP 参考](https://docs.renaiss.xyz/cn/api-reference.md#选择环境)中核对是否支持 `hasCancelledToken` 和 `total`。支持时，`hasCancelledToken=true` 匹配至少一张卡被持有人取消的订单；`total` 是跨分页的匹配总数。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.