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

# 实体卡寄送

> 说明实体卡寄送状态、物流信息查询接口和 WebSocket 实时通知，并列出 DeCard 托管目前支持的寄送功能。

## 📄 概述

实体卡从用户申请成功开始进入制卡与寄送流程。系统为每张实体卡维护一条物流跟踪记录，并按固定状态机推进；您可随时查询当前状态，进入寄送阶段后还可拿到运单号与物流公司名称。状态变更同时通过 WebSocket 实时推送（见下文）。

<Warning>
  **当前支持范围**：DeCard 托管的实体卡寄送功能**只有一个只读查询接口**（查询状态、运单号和物流公司）。目前**不提供**运费报价、各国费率表、寄送方式选择、收货地址修改、批量寄送、金属卡加价等功能。寄送时效、运费和改址政策请在接入时与 DCS 确认。
</Warning>

***

## 物流状态机

实体卡物流按以下四态**严格顺序**推进：

| 状态码                         | 名称   | 含义                                               |
| :-------------------------- | :--- | :----------------------------------------------- |
| **PENDING\_EMBOSSING**      | 待制卡  | 用户已申请实体卡，系统已创建物流跟踪记录，等待开始制卡                      |
| **EMBOSSING\_IN\_PROGRESS** | 制卡中  | 实体卡正在制作；制卡系统已生成制卡文件并处理                           |
| **IN\_DELIVERY**            | 邮寄中  | 实体卡制作完成并交付物流，此时返回运单号与物流公司                        |
| **DELIVERY\_COMPLETE**      | 邮寄完成 | 实体卡已妥投，物流流程结束（是否已激活以卡状态 `physicalCardStatus` 为准） |

> 状态转换遵循严格顺序：PENDING\_EMBOSSING → EMBOSSING\_IN\_PROGRESS → IN\_DELIVERY → DELIVERY\_COMPLETE。仅在进入 IN\_DELIVERY 后，`trackingNumber` 与 `trackingCompanyName` 才会有值。

> 该物流状态机与卡的 `physicalCardStatus`（`UN_APPLY` / `INACTIVE` / `ACTIVE` / `REPLACE` / `FROZEN` / `CANCELLED`，见 [卡管理 · 概述](../how-to-use/managing-cards/overview)）是**两套不同的状态字段**：前者描述「卡在物流流程上的位置」，后者描述「卡本身的可用状态」。请勿混用。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-shipping-states-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=dd7afb2ef0e917d3abaa9f507438aea0" alt="实体卡邮寄状态流转" width="524" height="236" data-path="imgs/diagrams/va-shipping-states-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-shipping-states-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=ddfc88caea1c125abb418608bfec0993" alt="实体卡邮寄状态流转" width="524" height="236" data-path="imgs/diagrams/va-shipping-states-dark.svg" />
</Frame>

***

## 查询物流信息

### 前置条件

* 该卡为**实体卡**且已成功申请（即已存在物流跟踪记录）。虚拟卡或尚未申请实体卡时查询无对应记录。
* 已持有该用户的 `externalUserId` 与目标卡的 `cardId`。

### 接口

| 接口                                    | 查询参数                                     | 说明         |
| :------------------------------------ | :--------------------------------------- | :--------- |
| `GET /card/v2/physical-shipping-info` | `externalUserId`（必填）、`cardId`（必填，string） | 以卡 ID 精确定位 |

### 请求示例

```bash theme={null}
curl -X GET "{{dicard-server}}/card/v2/physical-shipping-info?externalUserId=<EXTERNAL_USER_ID>&cardId=<CARD_ID>" \
  -H "Content-Type: application/json"
```

> 请求需携带鉴权头（`X-DAPI-API-KEY` / `X-DAPI-SIGN` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE`），详见 [接入资源 › 鉴权指南](../integration-resources/overview)。示例中 `<EXTERNAL_USER_ID>` 与 `<CARD_ID>` 为占位符，请替换为实际值，**切勿写入真实 PII**。

### 响应字段（`data`）

| 字段                    | 类型     | 说明                            |
| :-------------------- | :----- | :---------------------------- |
| `cardId`              | string | 卡 ID                          |
| `externalUserId`      | string | 用户外部 ID                       |
| `cardMantissa`        | string | 卡号后四位                         |
| `status`              | string | 物流状态，见上文状态机                   |
| `trackingNumber`      | string | 运单号（仅 `IN_DELIVERY` 及之后有值）    |
| `trackingCompanyName` | string | 物流公司名称（仅 `IN_DELIVERY` 及之后有值） |

<Warning>
  `cardId` 类型为 **string**（非数字），示例请按字符串书写。
</Warning>

### 响应示例（脱敏占位）

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": null,
  "data": {
    "cardId": "<CARD_ID>",
    "externalUserId": "<EXTERNAL_USER_ID>",
    "cardMantissa": "<LAST_4>",
    "status": "IN_DELIVERY",
    "trackingNumber": "<TRACKING_NO>",
    "trackingCompanyName": "<CARRIER_NAME>"
  }
}
```

> 响应结构统一为 `{ code, message, messageDetail, data }`（无 `success` 布尔字段）；成功码 `code` 字面量 = `SYS_SUCCESS`（全站一致）。`messageDetail` 在成功时通常为 `null`。

### 错误处理

| 场景              | 表现 / 处理                                                                                                         |
| :-------------- | :-------------------------------------------------------------------------------------------------------------- |
| 卡非实体卡 / 尚未申请实体卡 | 无物流跟踪记录；`data` 为空或无 `status`。请先确认该卡已通过 H5 完成实体卡申请（见 [申请卡](../how-to-use/managing-cards/issuing-cards)）          |
| 尚未进入寄送阶段        | `status` 为 `PENDING_EMBOSSING` / `EMBOSSING_IN_PROGRESS` 时，`trackingNumber` / `trackingCompanyName` 为空，属正常，无需重试 |
| 参数缺失 / 卡不属于该用户  | 请求失败；以响应 `code` / `message` 判断，`externalUserId` 与 `cardId`（或 `cardMantissa`）须匹配同一用户名下的卡                         |

***

## WebSocket 实时通知

除主动查询外，DCS 在物流状态变更时通过 **WebSocket 实时推送**通知（DeCard 托管特色能力）。无需轮询即可获知最新进展。

### 推送时机

* 创建物流跟踪记录时
* 物流状态发生变更时
* 物流信息（运单号 / 物流公司）更新时

### 消息类型与数据结构

WebSocket 推送的消息类型为 `CARD_PHYSICAL_SHIPPING`，数据字段与上文「响应字段」一致（`cardId` / `externalUserId` / `cardMantissa` / `status` / `trackingNumber` / `trackingCompanyName`）。

<Note>
  WebSocket 的连接握手、鉴权与完整数据结构集中在 [接入资源 › Webhook 与 WebSocket 实时通知](../integration-resources/webhook-websocket) 页；本消息类型的数据字段见该页 [`CARD_PHYSICAL_SHIPPING` 实体卡物流信息](../integration-resources/webhook-websocket#3-4-card_physical_shipping-实体卡物流信息) 小节（`messageType` = `CARD_PHYSICAL_SHIPPING`）。
</Note>

***

## 下一步

* 实体卡的**申请 / 激活 / 设 PIN**（H5 引导页），见 [申请卡](../how-to-use/managing-cards/issuing-cards)。
* 卡的总体状态与 `physicalCardStatus` 状态机，见 [卡管理 · 概述](../how-to-use/managing-cards/overview)。
* WebSocket / Webhook 连接与完整数据结构，见 [接入资源 › Webhook 与 WebSocket 实时通知](../integration-resources/webhook-websocket)。