实体卡寄送 - DCS Technical Documentation

📄 概述

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

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

物流状态机

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

状态码	名称	含义
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，见卡管理 · 概述）是两套不同的状态字段：前者描述「卡在物流流程上的位置」，后者描述「卡本身的可用状态」。请勿混用。

查询物流信息

前置条件

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

接口

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

请求示例

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），详见接入资源 › 鉴权指南。示例中 <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` 及之后有值）

cardId 类型为 string（非数字），示例请按字符串书写。

响应示例（脱敏占位）

{
  "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 完成实体卡申请（见申请卡）
尚未进入寄送阶段	`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）。

WebSocket 的连接握手、鉴权与完整数据结构集中在接入资源 › Webhook 与 WebSocket 实时通知页；本消息类型的数据字段见该页 CARD_PHYSICAL_SHIPPING 实体卡物流信息小节（messageType = CARD_PHYSICAL_SHIPPING）。

下一步

实体卡的申请 / 激活 / 设 PIN（H5 引导页），见申请卡。
卡的总体状态与 physicalCardStatus 状态机，见卡管理 · 概述。
WebSocket / Webhook 连接与完整数据结构，见接入资源 › Webhook 与 WebSocket 实时通知。

​📄 概述

​物流状态机

​查询物流信息

​前置条件

​接口

​请求示例

​响应字段（data）

​响应示例（脱敏占位）

​错误处理

​WebSocket 实时通知

​推送时机

​消息类型与数据结构

​下一步

📄 概述

物流状态机

查询物流信息

前置条件

接口

请求示例

响应字段（`data`）

响应示例（脱敏占位）

错误处理

WebSocket 实时通知

推送时机

消息类型与数据结构

下一步