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

# 前置准备

> 对接前要准备的事：从签约到上线的六个阶段、环境隔离与凭据保管、三个贯穿全流程的前提，以及所有接口共用的通用约定。

## 📄 正文

无论您是先做技术评估还是直接启动对接，都建议先过一遍本页：把凭据、回调地址、出口 IP 与通用约定准备就绪，再进入[快速开始](./quickstart)跑通第一张卡。DCS 作为持牌发卡机构承担发卡与清算；您只需实现签名、调用与 Webhook 接收三件事。

## 开始集成

从签约到规模化上线，接入过程分为六个阶段。每个阶段都有明确的前置依赖；在前一阶段就绪之前，不建议进入下一阶段。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/corp-first-steps-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=401bb8847ac4fbb4b9f2cb1033638ff8" alt="六个阶段的接入路径" width="684" height="250" data-path="imgs/diagrams/corp-first-steps-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/corp-first-steps-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=55ea429d8daaa490760f3ad00cba4d70" alt="六个阶段的接入路径" width="684" height="250" data-path="imgs/diagrams/corp-first-steps-dark.svg" />
</Frame>

| 阶段        | 主要工作                                                               |
| --------- | ------------------------------------------------------------------ |
| 1 · 签约与圈定 | 完成商务签约，提交合作伙伴与首家开户公司的资质及尽调材料，确认卡型、卡面、是否需要实体卡及寄送范围、是否具备 PCI DSS 资质。 |
| 2 · 环境配置  | 登记回调地址与出口 IP，完成密钥的安全接收与存储，确认卡产品与卡面配置。                              |
| 3 · 集成开发  | 实现请求签名并跑通最短发卡路径，实现 Webhook 接收端（验签、幂等、快速返回 2xx），实现查询接口的定时轮询兜底。      |
| 4 · 测试与认证 | 按用例集逐项验证正常路径、被拒后重新提交、幂等重复、回调重试与去重、签名失败与时钟偏差、限额与参数校验等场景。            |
| 5 · 试点    | 在生产环境以小流量灰度验证（建议先开通一家公司、一名员工、一张卡），并接入监控与告警。                        |
| 6 · 上线与扩量 | 确认试点无误后，逐步放开发卡与交易规模，进入常态化运营。                                       |

## 环境与凭据

* **环境隔离**：测试环境与生产环境为完全独立的部署，其域名、凭据、数据与回调密钥均各自独立、互不通用、互不迁移；切换环境时须同时更换域名与凭据。两套环境的路径前缀一致，均为 `/open-api-corp/`。
* **凭据保管**：AK（API Key）在请求头中标识合作伙伴身份；SK（Secret Key）仅用于本地计算签名，同时也是获取卡敏感信息接口的解密密钥；Webhook 签名密钥由 DCS 单独下发。SK 须存放于密钥管理服务或加密配置中，不得写入代码仓库、日志或前端。

## 三个前提

① **所有创建类接口都是异步受理。** 公司开户、创建员工、申请虚拟卡调用后同步返回的只是对应的申请单 ID 与 `status=PENDING`，代表「已受理」，不代表「已创建成功」。真正的终态推荐以 Webhook 为主、轮询查询接口为兜底。

② **成功与否看响应体的 `code`，不看 HTTP 状态码。** 统一响应信封为 `{code, message, data}`，`code == "SYS_SUCCESS"` 才是成功，其余均为失败。HTTP 状态码仅作参考（鉴权失败为 401）。

③ **您的身份由 AK 决定，不在请求里传。** DCS 按请求头里的 AK 验签后即确定合作伙伴身份。请求体中不需要、也不要携带任何合作伙伴 / 企业标识字段，携带了也会被忽略。

## 通用约定

本节约定所有接口共用的基础规则；后续每个接口只需关注其自身的参数与字段。

| 约定       | 说明                                                                                                                   |
| -------- | -------------------------------------------------------------------------------------------------------------------- |
| Base URL | `https://{接入域名}/open-api-corp/{模块}/v1/{动作}`；全程 HTTPS。测试与生产环境使用各自独立的接入域名，由 DCS 在对接阶段下发。                               |
| 方法语义     | 查询类接口使用 GET（参数经查询串传入）；写入与动作类接口使用 POST（参数置于 JSON 请求体，Content-Type 为 `application/json`）。                              |
| 响应信封     | 无论成功或失败，均返回统一信封 `{code, message, data}`。以 `code == "SYS_SUCCESS"` 判定业务成功，其余为失败；HTTP 状态码仅作参考（鉴权失败为 401）。              |
| 分页       | 列表类接口共用 `page`（自 1 起，默认 1）、`pageSize`（1\~100，默认 20）、`total`、`result`。                                                |
| 幂等       | 所有写入类接口均带幂等键（`organizationRef` / `customerRef` / `cardApplyRef` / `transferRef` / `ruleRef` 等），由合作伙伴生成并持久化，重试时复用同一值。 |
| 版本策略     | 版本号内嵌于路径中（当前为 v1）。向后兼容的变更（新增可选字段、枚举、错误码）在 v1 内直接发布，请以宽容方式解析响应、忽略未知字段；不兼容的变更通过新版本号发布。                                 |

**ID 约定**。契约中所有 ID 均为 JSON 字符串：`organizationId`、`customerId` 为统一用户中心分配的 UUID 形态字符串；`cardId`、三类申请单 ID（`organizationApplyId` / `customerApplyId` / `cardApplyId`）、`webhookId` 为 19 位雪花数字串（必须作字符串传输，不可使用数字字面量，否则超出双精度安全整数范围会被静默截断）；`transferId`、`ruleId`、`statementId`、`transactionId` 等为业务字符串，应原样透传。多态 ID（`subjectId`、`subjectId`、`subjectId`）的语义由同一结构中的类型字段决定，不可由取值形态推断。合作伙伴侧 ID（`externalXxx`）为自定义字符串，字符集为 `^[A-Za-z0-9_-]+$`、长度不超过 64，同时充当幂等键。

## 下一步

* 准备就绪后，前往[快速开始](./quickstart)，按最短发卡路径跑通第一张卡。
* 理解持卡主体、资金模型与状态机：[持卡主体与资金模型](../basic-concepts/identity-and-funding)