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

# 快速开始

> 按最短发卡路径九步跑通「开户 → 充值 → 发卡 → 消费」：实现请求签名、发起调用、接收 Webhook。

## 📄 正文

本页假设您已按[前置准备](./first-steps)取得凭据、登记回调地址并了解通用约定。下面以「给一名员工发一张公司资金池付款的虚拟卡」为例，逐步跑通全流程。

## 最短发卡路径

| # | 步骤            | 接口                                             | 同步/异步 | 您要拿到的                        |
| - | ------------- | ---------------------------------------------- | ----- | ---------------------------- |
| 1 | 取得凭据          | —                                              | —     | AK / SK 与接入域名                |
| 2 | 组织开户          | `POST /organization/v1/apply`                  | 异步受理  | `organizationApplyId`        |
| 3 | 等待开户与 VA 创建结果 | Webhook `ORGANIZATION_CREATED`（兜底 query-apply） | 异步    | `organizationId`（公司 ACTIVE）  |
| 4 | 资金充值          | 客户银行转账至公司资金池 VA                                | 异步    | 充值到账通知（`BANK_TRANSFER_INFO`） |
| 5 | 创建员工          | `POST /customer/v1/apply`                      | 异步受理  | `customerApplyId`            |
| 6 | 等待员工结果        | Webhook `CUSTOMER_CREATED`（兜底 query-apply）     | 异步    | `customerId`                 |
| 7 | 申请虚拟卡         | `POST /card/v1/apply`                          | 异步受理  | `cardApplyId`                |
| 8 | 等待建卡结果        | Webhook `CARD_CREATED`（兜底 query-apply）         | 异步    | `cardId`（卡 ACTIVE）           |
| 9 | 查卡确认          | `GET /card/v1/query`                           | 同步    | 卡 BIN、后四位、卡组织、状态             |

<Warning>
  **顺序不可跳**：创建员工要求公司已 ACTIVE（等第 3 步）；申请虚拟卡要求持卡主体（公司或员工）已 ACTIVE（等第 5 步）。被拒时：公司 / 员工 KYB / KYC 被拒走 resubmit 沿用同一申请单 ID 重提。
</Warning>

## 请求签名

所有业务接口（路径以 `/open-api-corp/` 开头）必须签名，验签失败返回 HTTP 401。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/corp-signing-flow-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=3cad3a7141b9d15f270b4e05eafbf40e" alt="请求签名的计算步骤" width="446" height="262" data-path="imgs/diagrams/corp-signing-flow-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/corp-signing-flow-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=ed73c0b9464e6142c9e0856abe98d34a" alt="请求签名的计算步骤" width="446" height="262" data-path="imgs/diagrams/corp-signing-flow-dark.svg" />
</Frame>

**请求头**

| Header             | 必填 | 说明                          |
| ------------------ | -- | --------------------------- |
| `X-DAPI-API-KEY`   | Y  | 您的 AK                       |
| `X-DAPI-TIMESTAMP` | Y  | 请求时间戳，epoch 毫秒              |
| `X-DAPI-NONCE`     | Y  | 随机数，整数 \[10000, 99999]，单次有效 |
| `X-DAPI-SIGN`      | Y  | 签名，见下                       |
| `Content-Type`     | Y  | POST 时为 `application/json`  |

**签名算法**

```
payload      = (GET) 原始 query string（无则空串 ""）
             = (POST) 请求体 JSON 原文
dataToSign   = apiKey + timestamp + nonce + payload
X-DAPI-SIGN  = Hex( HMAC-SHA256( SK, dataToSign ) )   # 小写 Hex
```

HMAC 输出为小写 Hex；签名串按 UTF-8 字节参与计算。POST 的 payload 是请求体原文，签名用的字节与实际发出的字节必须完全一致（cURL 用 `--data-binary`）。

* **时间戳窗口**：服务端校验 |now − timestamp| ≤ 5 秒，超窗返回 `DAPI_TIMESTAMP_EXPIRED`。请确保服务器已启用 NTP。
* **防重放**：同一签名短窗口内只接受一次，重复返回 `DAPI_NONCE_DUPLICATE`；nonce 不在区间返回 `DAPI_NONCE_ILLEGAL`。每次请求都重新生成 nonce。
* **SK 永远不出现在任何请求中**，只用于本地计算签名。

**完整示例 · 公司开户（bash）**

```bash theme={null}
BASE="https://<接入域名>"
AK="<your_access_key>"; SK="<your_secret_key>"
BODY='{"organizationRef":"EXT-COMPANY-0001","organizationName":"Example Company Limited","companyRegistrationNumber":"REG-0000000","email":"contact@example.com","fundingCurrencies":["USD"]}'
TS=$(python3 -c 'import time;print(int(time.time()*1000))')
NONCE=$(python3 -c 'import random;print(random.randint(10000,99999))')
SIGN=$(printf '%s' "${AK}${TS}${NONCE}${BODY}" | openssl dgst -sha256 -hmac "${SK}" -r | cut -d' ' -f1)
curl -sS -X POST "${BASE}/open-api-corp/organization/v1/apply" \
  -H "X-DAPI-API-KEY: ${AK}" -H "X-DAPI-TIMESTAMP: ${TS}" \
  -H "X-DAPI-NONCE: ${NONCE}" -H "X-DAPI-SIGN: ${SIGN}" \
  -H "Content-Type: application/json" --data-binary "${BODY}"
```

## 接收 Webhook

回调流程：DCS → 您的服务端的 HTTP POST，统一信封 `{webhookId, webhookType, businessId, data, notificationTime}`。接收端必须实现四件事：

| 项        | 要求                                                                                                                                                    |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 验签       | `X-Signature = Hex(HMAC-SHA256(SK, sortedCompactJson(整个 payload)))`。sortedCompactJson = 全层级字段名字典序排序 + 去空白紧凑序列化；必须用相同方式复算比对，不能直接对原始字节验签。签名密钥由 DCS 单独下发 |
| 幂等       | 按 `webhookId` 去重（同一事件所有重试复用同一个）；去重命中后仍返回 2xx                                                                                                          |
| 快速返回 2xx | 返回 2xx 即视为投递成功（DCS 不解析响应体），业务处理请异步化                                                                                                                   |
| 不假设顺序    | 以 `webhookId`（雪花 id，单调递增）+ 资源当前状态为准，必要时回查查询接口                                                                                                         |

<Note>
  **重试窗口约 3 分钟**：非 2xx 或超时会重投，上限 3 次、间隔约 1 分钟、无退避（首发 + 重投合计最多 4 次）。全部失败后置为失败态并告警。因此建议接入查询接口进行定时轮询——它是回调彻底失败时的兜底。
</Note>

## 下一步

* 理解持卡主体、资金模型与状态机：[持卡主体与资金模型](../basic-concepts/identity-and-funding)
* 按业务域深入每个环节：[管理公司](../how-to-use/managing-companies) 起步的使用指南