快速开始 - DCS Technical Documentation

📄 正文

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

最短发卡路径

#	步骤	接口	同步/异步	您要拿到的
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、后四位、卡组织、状态

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

请求签名

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

请求头

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）

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，单调递增）+ 资源当前状态为准，必要时回查查询接口

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

下一步

理解持卡主体、资金模型与状态机：持卡主体与资金模型
按业务域深入每个环节：管理公司起步的使用指南

​📄 正文

​最短发卡路径

​请求签名

​接收 Webhook

​下一步

📄 正文

最短发卡路径

请求签名

接收 Webhook

下一步