> ## 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. # 申请虚拟卡 > 调用 apply 为公司或员工发一张虚拟卡：全字段说明（subjectType 与 cardProfileId 匹配、公司卡托管人、ruleIds 绑定规则）、完整错误码，以及用 query-apply / query / list 查申请进度、单卡详情与卡列表。 ## 📄 正文 发卡永远从虚拟卡开始：`POST /open-api-corp/card/v1/apply` 受理即返回 `cardApplyId`，风控与建卡全程异步，终态经 Webhook `CARD_CREATED` / `CARD_REJECTED` 通知，`GET /open-api-corp/card/v1/query-apply` 作查询兜底。建卡成功后用 `cardId` 走单卡查询与列表查询。整条链路在卡组各页的位置见[管理卡片（概述）](./managing-cards)。 ## 申请虚拟卡 ```http theme={null} POST /open-api-corp/card/v1/apply ``` ### 请求参数 | 字段 | 类型 | 必填 | 说明 | | --------------------- | --------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------- | | `cardApplyRef` | String | 是 | ≤64；合作伙伴侧申请唯一标识 | | `subjectType` | String | 是 | `ORGANIZATION`（公司卡）/ `CUSTOMER`（员工卡） | | `subjectId` | String | 是 | ≤20；持卡主体外部 id：`ORGANIZATION`→`organizationId`，`CUSTOMER`→`customerId`。须存在、类型一致、ACTIVE、属本合作伙伴 | | `cardProfileId` | String | 是 | 卡类型码 = 四类型之一（与 `subjectType` 的搭配见下表） | | `custodianCustomerId` | String | 条件必填 | ≤20；公司卡（`subjectType`≠`CUSTOMER`）必填：值 = 本公司某员工的 `customerId`，须 ACTIVE | | `ruleIds` | `Array` | 条件必填 | ≤5 条；开卡时同步绑定的交易限额限次规则，元素为规则外部 id。资金来源为公司资金池的两种卡型（`COMPANY_UTILITY_CARD` / `EMPLOYEE_CARD_CORPORATE_FUNDED`，即公司公用卡 / 员工卡（公司池））必填；其余卡型可选 | ### cardProfileId 四卡型与 subjectType 的搭配 卡型由两个正交维度组合而成：持卡主体（卡发给谁）× 余额模式（钱从哪个账户扣）。完整卡型介绍见[概述 · 卡片类型](../getting-started/overview)。 | 业务卡型 | 卡类型码（`cardProfileId`） | `subjectType` | 余额模式 | 托管人（`custodianCustomerId`） | | --------- | -------------------------------- | -------------- | ----------------------- | -------------------------- | | 公司公用卡 | `COMPANY_UTILITY_CARD` | `ORGANIZATION` | company pool 公司池 | 必填 | | 专款专用卡 | `COMPANY_DEDICATED_PURPOSE_CARD` | `ORGANIZATION` | card's own balance 独立余额 | 必填 | | 员工卡（公司池） | `EMPLOYEE_CARD_CORPORATE_FUNDED` | `CUSTOMER` | SHARED 公司池 | 不适用 | | 员工卡（独立余额） | `EMPLOYEE_CARD_SELF_FUNDED` | `CUSTOMER` | DEDICATED 独立余额 | 不适用 | 按监管要求，公司卡须指定一名本公司在职员工作为托管人（Custodian）。卡片有问题时将联系托管人，消费遇 3DS 挑战需由托管人完成验证。 ### ruleIds 绑定规则 `ruleIds` 中的每条规则须同时满足：**已存在、属同一公司、状态 ACTIVE**；配置金额限额的规则须与卡核销币种有交集。数组内不得重复——重复携带同一条规则即拒（不会静默去重），请自行去重后再提交。 **任一条不满足即整单拒绝**（受理前早拒、不产生 `cardApplyId`），不做部分成功；开卡后仍可经限额限次接口调整绑定，见[设置消费限额](./spend-limits)。 ### 请求示例 ```json theme={null} // 场景一：员工卡（公司池，SHARED——ruleIds 必填） { "cardApplyRef": "ext-card-apply-0001", "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c", "cardProfileId": "EMPLOYEE_CARD_CORPORATE_FUNDED", "ruleIds": ["5136744097353943556"] } // 场景二：公司公用卡（不记名——custodianCustomerId 必填；SHARED——ruleIds 必填） { "cardApplyRef": "ext-card-apply-0002", "subjectType": "ORGANIZATION", "subjectId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f", "cardProfileId": "COMPANY_UTILITY_CARD", "custodianCustomerId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c", "ruleIds": ["5136744097353943556"] } ``` ### 响应 data 与示例 | 字段 | 类型 | 说明 | | ------------- | ------ | -------------------------------------------------------------------------------------- | | `cardApplyId` | String | 卡申请 ID | | `status` | String | 本接口受理成功固定返回 `PENDING`（建卡结果经 Webhook 异步通知）；卡申请状态枚举全集：`PENDING` / `SUCCEED` / `REJECTED` | ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "data": { "cardApplyId": "5136744097353943553", "status": "PENDING" } } ``` ### 错误码 | 错误码 | 说明 | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `CARD_PROFILE_INVALID` | 卡类型不可用（如：类型码无效/未启用、本合作伙伴未开通、`subjectType` 与该类型适用主体不符）；具体原因见 message/reason | | `CARD_LIMIT_EXCEEDED` | 超开卡上限（公司级或持卡人级，活卡+在途计数）；具体级别见 message/reason | | `SUBJECT_INVALID` | 公司卡托管人缺失/非本公司有效员工 | | `SUBJECT_INVALID` | 持卡主体（公司）不存在/无效 | | `CUSTOMER_INVALID` | 持卡/托管员工不存在/无效 | | `DAPI_PERMISSION_DENIED` | 合作伙伴不存在 / 未激活（入驻方身份由 AK 派生，属授权问题，归口网关授权码，HTTP 401；一般不出现） | | `APPLY_DUPLICATE` | 同一 `cardApplyRef` 已存在在途或已成功的申请，不可重复提交 | | `CARD_RULE_REQUIRED` | 公司余额模式卡未携带 `ruleIds`（传空数组同样视为未携带） | | `CARD_RULE_DUPLICATE` | `ruleIds` 内重复携带同一条规则。不会静默去重——重复通常意味着调用方对「实际绑了哪几条」的认知有偏差，悄悄收敛会让您误以为绑成功了 N 条。注：同时超过 5 条且存在重复时，返回本码而非 `CARD_RULE_LIMIT_EXCEEDED` | | `CARD_RULE_LIMIT_EXCEEDED` | `ruleIds` 超过 5 条 | | `CARD_RULE_INVALID` | 规则不存在、不属本公司、或非 ACTIVE——三者统一一个码，避免据此探测某规则是否存在于其他公司名下；具体原因见 message | | `CARD_RULE_CURRENCY_NOT_MATCH` | 规则的金额限额币种与卡可核销币种无交集 | 关联 Webhook：`CARD_CREATED` / `CARD_REJECTED`。 ## 查询卡申请进度 ```http theme={null} GET /open-api-corp/card/v1/query-apply?cardApplyId=5136744097353943553 ``` 请求参数只有一个：`cardApplyId`（String，必填，≤20；卡申请 ID）。 **响应 data**： | 字段 | 类型 | 说明 | | -------------- | ------ | ------------------------------------------------------ | | `cardApplyId` | String | 申请 ID | | `status` | String | 卡申请状态枚举全集：`PENDING`（受理中 / 建卡中）/ `SUCCEED` / `REJECTED` | | `cardId` | String | 成功后的卡 ID（未建卡为空） | | `errorCode` | String | 被拒错误码：固定 `CARD_RISK_REJECTED`（仅 `REJECTED` 时） | | `errorMessage` | String | 被拒原因：固定 `risk check refused`（仅 `REJECTED` 时；不透传内部风控码） | ```json theme={null} // 场景一：建卡成功 { "code": "SYS_SUCCESS", "message": null, "data": { "cardApplyId": "5136744097353943553", "status": "SUCCEED", "cardId": "5185740066240790530", "errorCode": null, "errorMessage": null } } // 场景二：风控拒绝 { "code": "SYS_SUCCESS", "message": null, "data": { "cardApplyId": "5136744097353943553", "status": "REJECTED", "cardId": null, "errorCode": "CARD_RISK_REJECTED", "errorMessage": "risk check refused" } } ``` 错误码：`APPLY_NOT_FOUND`——卡申请不存在（或不属本合作伙伴）。 ## 查询单张卡详情 ```http theme={null} GET /open-api-corp/card/v1/query?cardId=5185740066240790530 ``` 请求参数只有一个：`cardId`（String，必填，≤20；卡 ID）。 **响应 data**： | 字段 | 类型 | 说明 | | ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | | `cardId` | String | 卡 ID | | `panFirst6` | String | 卡号前 6 位（BIN；不返回完整 PAN） | | `panLast4` | String | 卡号后 4 位（不返回完整 PAN） | | `organizationId` | String | 所属公司 | | `subjectType` | String | `ORGANIZATION` / `CUSTOMER` | | `subjectId` | String | 持卡主体外部 id | | `cardProfileId` | String | 卡产品编码：`COMPANY_UTILITY_CARD` / `COMPANY_DEDICATED_PURPOSE_CARD` / `EMPLOYEE_CARD_CORPORATE_FUNDED` / `EMPLOYEE_CARD_SELF_FUNDED` | | `cardNetwork` | String | `VISA` / `MASTERCARD` / `UPI` | | `currency` | String | `USD` / `HKD` | | `status` | String | 卡状态：`ACTIVE` / `FROZEN` / `LOCKED` / `RESTRICTED` / `LOST` / `EXPIRED` / `CLOSED` | ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "data": { "cardId": "5185740066240790530", "panFirst6": "520983", "panLast4": "5492", "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f", "subjectType": "CUSTOMER", "subjectId": "a3f8d2b1-6c94-4e07-b512-9d8e7f6a5b4c", "cardProfileId": "EMPLOYEE_CARD_CORPORATE_FUNDED", "cardNetwork": "MASTERCARD", "currency": "USD", "status": "ACTIVE" } } ``` 错误码：`CARD_INVALID`——卡不存在 / 不属本合作伙伴 / 非 ACTIVE。 ## 查询卡列表 ```http theme={null} GET /open-api-corp/card/v1/list?organizationId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&subjectType=EMPLOYEE&status=ACTIVE&page=1&pageSize=20 ``` 分页查询本合作伙伴名下的卡，过滤参数均可选： | 字段 | 类型 | 必填 | 说明 | | ---------------- | ------- | -- | ------------------------------------------------------------------------------------ | | `organizationId` | String | 否 | ≤20；按所属公司过滤 | | `subjectType` | String | 否 | `ORGANIZATION` / `CUSTOMER` | | `subjectId` | String | 否 | ≤20；按持卡主体过滤 | | `status` | String | 否 | 按卡状态过滤：`ACTIVE` / `FROZEN` / `LOCKED` / `RESTRICTED` / `LOST` / `EXPIRED` / `CLOSED` | | `page` | Integer | 否 | 从 1 起，默认 1 | | `pageSize` | Integer | 否 | 1\~100，默认 20 | **响应 data**：分页外壳为 `page`（当前页，Integer）、`pageSize`（每页条数，Integer）、`total`（总条数，数字）、`result`（卡列表）；`result` 中每个元素的字段与上文单卡查询的响应 data 完全一致（`cardId` / `panFirst6` / `panLast4` / `organizationId` / `subjectType` / `subjectId` / `cardProfileId` / `cardNetwork` / `cardProfileId` / `currency` / `status`）。 ## 下一步 * SHARED 卡开卡前须先创建并持有可绑定的限额规则：[设置消费限额](./spend-limits) * 卡建成后展示卡号与 CVV2：[查看卡敏感信息](./secure-card-details)