> ## 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.

# 实体卡

> 把 ACTIVE 虚拟卡同号升级为实体卡的四步链路：virtual-to-physical 升级申请（卡面 cardLayoutCode、刻印名、地址快照）→ shipping-info 查物流 → activate 激活（幂等）→ set-pin 设 PIN（AES-GCM 密文上送）。

## 📄 正文

实体卡由一张已激活（ACTIVE）的虚拟卡经「虚拟卡转实体卡」同号升级而来。升级前后卡号、有效期、CVV2 与 `cardId` 全程保持不变——激活前查询返回原虚拟卡信息，激活后按实体卡生效，因此您无需在升级后替换卡片或迁移任何绑定关系。卡状态背景见[状态机与冻结体系](../basic-concepts/states-and-freezing)。

四步链路如下：

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/corp-physical-flow-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=c8ee68465f9dcef8c0be3b335b513462" alt="虚拟卡转实体卡的完整路径" width="665" height="326" data-path="imgs/diagrams/corp-physical-flow-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/corp-physical-flow-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=d530408fffe0435b7948e36b5d0fa48a" alt="虚拟卡转实体卡的完整路径" width="665" height="326" data-path="imgs/diagrams/corp-physical-flow-dark.svg" />
</Frame>

<Note>
  寄送地址挂在员工名下，受理虚拟卡转实体卡时读取并**锁定为快照**，此后修改地址不影响在途制卡。
</Note>

## ① 升级申请：虚拟卡转实体卡

```http theme={null}
POST /open-api-corp/card/v1/virtual-to-physical
```

把 ACTIVE 虚拟卡同号升级为实体卡。

### 请求参数

| 字段               | 类型     | 必填 | 说明                                                         |
| ---------------- | ------ | -- | ---------------------------------------------------------- |
| `cardApplyRef`   | String | 是  | ≤64；合作伙伴侧申请唯一标识（幂等键）；字符集 `^[A-Za-z0-9_-]+$`                |
| `organizationId` | String | 是  | ≤20；卡所属公司                                                  |
| `cardId`         | String | 是  | ≤20；被升级虚拟卡；须属本合作伙伴 / 公司、当前为虚拟卡且 ACTIVE；持卡人 / 托管人、寄送地址由该卡派生 |
| `cardLayoutCode` | String | 是  | 卡面 code；须为已配置卡面（取值由 DCS 按合作伙伴配置下发，非固定枚举）                   |
| `embossingName`  | String | 是  | ≤26；卡面压花第一行                                                |
| `embossingName2` | String | 否  | ≤26；卡面压花第二行（可选）                                            |

### 响应 data

| 字段            | 类型     | 说明        |
| ------------- | ------ | --------- |
| `cardApplyId` | String | 虚转实受理单 id |

### 请求与响应示例

```json theme={null}
{
  "cardApplyRef": "ext-v2p-0001",
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardId": "5185740066240790530",
  "cardLayoutCode": "LAYOUT_CLASSIC_BLACK",
  "embossingName": "DOE JOHN",
  "embossingName2": "EXAMPLE HK LIMITED"
}
```

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardApplyId": "5136744097353943557"
  }
}
```

### 错误码

| 错误码                         | 说明                        |
| --------------------------- | ------------------------- |
| `CARD_INVALID`              | 卡不存在 / 不属本合作伙伴 / 非 ACTIVE |
| `CARD_NOT_VIRTUAL`          | 卡已是实体卡，不可再转               |
| `CARD_CONVERT_IN_PROGRESS`  | 同卡已有在途虚转实申请（未终结）          |
| `APPLY_DUPLICATE`           | 同一 `cardApplyRef` 已受理（幂等） |
| `SHIPPING_ADDRESS_REQUIRED` | 持卡人 / 托管人未维护寄送地址          |
| `COUNTRY_SANCTIONED`        | 收件国命中制裁名单                 |
| `LIMIT_PHYSICAL_EXCEEDED`   | 实体卡数超上限（公司级或持卡人级）         |

关联 Webhook：`CARD_SHIPPED`（寄出）/ `CARD_ACTIVATED`（激活）。

## ② 查询制卡寄送进度

```http theme={null}
GET /open-api-corp/card/v1/shipping-info
```

查询实体卡制卡寄送进度与物流单号。

### 请求参数

| 字段               | 类型     | 必填 | 说明        |
| ---------------- | ------ | -- | --------- |
| `organizationId` | String | 是  | ≤20；卡所属公司 |
| `cardId`         | String | 是  | ≤20；卡 id  |

### 响应 data

| 字段                    | 类型     | 说明          |
| --------------------- | ------ | ----------- |
| `cardId`              | String | 卡 id        |
| `trackingNumber`      | String | 物流单号（未寄出为空） |
| `trackingCompanyName` | String | 物流公司        |

### 响应示例（已寄出 / 未寄出）

```json theme={null}
// 场景一：已寄出
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "trackingNumber": "SF1234567890123",
    "trackingCompanyName": "SF Express"
  }
}

// 场景二：未寄出
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "trackingNumber": null,
    "trackingCompanyName": null
  }
}
```

错误码：`CARD_INVALID`——卡不存在 / 不属本合作伙伴。

## ③ 激活实体卡

```http theme={null}
POST /open-api-corp/card/v1/activate
```

激活实体卡，前置是卡**已寄出**。**本接口幂等**——重复调用返回同样的成功结果。

### 请求参数与响应

请求参数：`cardId`（String，必填，≤32；卡 id）。按卡操作的接口只凭 `cardId` 定位，不带 `organizationId`。响应为动作类，`data` 为 `null`。

```json theme={null}
{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardId": "5185740066240790530"
}
```

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530"
  }
}
```

### 错误码

| 错误码                | 说明             |
| ------------------ | -------------- |
| `CARD_INVALID`     | 卡不存在 / 不属本合作伙伴 |
| `CARD_NOT_SHIPPED` | 卡未寄出，尚不可激活     |

关联 Webhook：`CARD_ACTIVATED`。

## ④ 设置 PIN

```http theme={null}
POST /open-api-corp/card/v1/set-pin
```

设置实体卡 PIN，前置条件是实体卡**已激活**。

<Note>
  PIN 与核身字段由合作伙伴用 SK 做 AES-GCM 加密后上送，与 `retrieve-secure-card` **同一套加解密约定、方向相反**（约定见[查看卡敏感信息](./secure-card-details)：AES/GCM/NoPadding、128 位标签、密钥即 SK）。
</Note>

### 请求参数

| 字段                    | 类型     | 必填 | 说明                                     |
| --------------------- | ------ | -- | -------------------------------------- |
| `organizationId`      | String | 是  | ≤20；卡所属公司                              |
| `cardId`              | String | 是  | ≤20；卡 id                               |
| `encryptedPin`        | String | 是  | 密文 PIN（企业密钥 AES-GCM；明文须 4 位数字、禁连续、禁全同） |
| `encryptedCvv2`       | String | 是  | 密文 CVV2（核身）                            |
| `encryptedExpireDate` | String | 是  | 密文有效期（核身，原文 mm/yy）                     |
| `encryptedPanLast4`   | String | 是  | 密文卡号后四位（核身）                            |
| `iv`                  | String | 是  | 本次随机 IV（Base64）；4 个密文字段共用同一个 `iv`      |

### 请求与响应示例

```json theme={null}
{
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardId": "5185740066240790530",
  "encryptedPin": "UGluTW9ja0NpcGhlclRleHQrVGFnMTZC",
  "encryptedCvv2": "Q3Z2Mk1vY2tDaXBoZXJUZXh0K1RhZzE2Qg==",
  "encryptedExpireDate": "RXhwTW9ja0NpcGhlclRleHQrVGFnMTZC",
  "encryptedPanLast4": "TGFzdDRNb2NrQ2lwaGVyVGV4dCtUYWcxNkI=",
  "iv": "MTIzNDU2Nzg5MGFi"
}
```

响应 data 为 `cardId` 与 `success`（Boolean，是否设置成功）：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "success": true
  }
}
```

### 错误码

| 错误码                      | 说明                              |
| ------------------------ | ------------------------------- |
| `CARD_INVALID`           | 卡不存在 / 不属本合作伙伴                  |
| `PIN_CARD_NOT_ACTIVATED` | 卡未激活，不可设置 PIN                   |
| `PIN_CARD_STATE_INVALID` | 卡状态不允许设置 PIN（非 ACTIVE / 用户主动冻结） |
| `PIN_RULE_VIOLATION`     | PIN 非 4 位数字 / 连续 / 全同           |

## 下一步

* 还没有可升级的虚拟卡？先发一张：[申请虚拟卡](./applying-virtual-cards)
* 卡状态与冻结能力域背景：[状态机与冻结体系](../basic-concepts/states-and-freezing)