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

# 概述（接入凭证与开发者配置）

> 讲清集成前的三项开发者配置：apiKey / secretKey 凭证配发（含生产环境安全提取）、接口 IP 白名单、Webhook 配置。

## 📄 正文

在开始集成前，您需要从 DCS 获得一套接入凭证，并完成接口白名单与回调（Webhook）的配置。作为持牌、自有 BIN 的发卡机构，DCS 的凭证发放、IP 白名单登记与 Webhook 配置均由 DCS 团队协同完成，确保每一份生产密钥都经过安全交付。下文说明这套流程的三个要点。

## 凭证配发：apiKey / secretKey

DCS 会为每一个 Enterprise（企业主体）配置一套接入凭证，作为 API 调用的"准入凭证"：

| 字段          | 描述                                   |
| ----------- | ------------------------------------ |
| `apiKey`    | 调用 open-api 使用的 key，用于身份识别与请求来源追踪    |
| `secretKey` | 用于请求签名（HmacSHA256）的鉴权 key，请妥善保管，切勿泄露 |

凭证由 DCS 团队提供给您：

* **沙盒环境**：请直接联系 DCS 团队获取 `apiKey` / `secretKey`。
* **生产环境**：走"安全邮箱 + 一次性提取链接"流程（见下方[生产环境凭证的安全提取](#生产环境凭证的安全提取)），避免凭证在传递过程中泄露给第三方。

> 凭证如何参与请求签名（`X-DAPI-API-KEY` / `X-DAPI-SIGN` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE`、HmacSHA256 签名规则）请参阅 [接入资源 › 鉴权指南](../integration-resources/overview)。

### 生产环境凭证的安全提取

为保证生产环境的 `apiKey` / `secretKey` 不会泄露给其他第三方，生产凭证按以下流程一次性安全提取：

1. 向 DCS 团队提供：一个**安全邮箱地址**（接收提取流程）+ 一个**提取请求 IP**（将被加入提取白名单）。
2. 安全邮箱会收到 DCS 发送的邮件，其中包含一个**临时安全链接（仅一次提取有效）**。
3. 将 `extractUrl` 与 `extractSecretKey` 拼接后，在指定机器上执行，即可提取到 `apiKey` / `secretKey`。

邮件中包含的字段：

| 字段                 | 类型     | 描述           |
| ------------------ | ------ | ------------ |
| `expireTime`       | string | 提取安全码的有效期    |
| `extractSecretKey` | string | 密钥提取安全码      |
| `extractUrl`       | string | 密钥提取 URL     |
| `howToUse`         | string | 使用方式         |
| `notes`            | string | 提示：链接仅可被提取一次 |

提取流程的成功响应示例（示例中的密钥、URL、时间戳均为占位符）：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "expireTime": "<EXPIRE_TIME>",
    "extractSecretKey": "<EXTRACT_SECRET_KEY>",
    "extractUrl": "https://<DECARD_DOMAIN>/internal/open-api/v1/secret-extract/",
    "howToUse": "Please concatenate the url with the secret-key and execute it on the specified machine.",
    "notes": "This link is only valid for one AKSK extraction. If the content is not properly accessed, the AKSK may have been compromised, please contact us promptly."
  }
}
```

> **响应结构**：全站统一为 `{code, message, messageDetail, data}`，成功码字面量为 `SYS_SUCCESS`，不含 `success` 布尔字段。
> **安全提示**：临时链接**仅可提取一次**。若未能成功提取到凭证，说明链接可能已被他人使用、密钥存在泄露风险，请立即与 DCS 商务沟通后重新发起邮件。

## 接口白名单（IP Whitelisting）

DCS 设有**接口白名单机制**：只有登记过的网络出口地址才能调用 open-api。在配发凭证时，请同时向 DCS 团队提供您的**网络出口地址**：

* 沙盒环境出口 IP
* 生产环境出口 IP

> IP 白名单的更多说明（多地址、变更流程等）见 [接入资源 › IP 白名单](../integration-resources/ip-whitelisting)。

## Webhook 配置

DCS 通过 Webhook 主动推送 KYC 状态、资产变动、卡交易、订单状态等事件。Webhook 由您实现接收端后同步 DCS 团队配置：

1. **实现接收端**：暴露一个 POST 接口，支持 `application/json`、2 秒内返回 `200 OK`（其他状态码触发重试）。
2. **同步 DCS 团队配置**：将您的回调 URL（必须为 HTTPS、公网可访问）同步给 DCS 团队，由 DCS 完成配置。
3. **验证与上线**：在 UAT 环境验证通过后上线。

Webhook 的签名由 DCS 用您的 `secretKey` 以 HmacSHA256 对消息体计算 `X-Signature`，由您校验。完整的事件格式、签名校验与接收示例见 [接入资源 › Webhook 与 WebSocket 实时通知](../integration-resources/webhook-websocket)。

## 配发与上线时序

下图描述从领取凭证到 Webhook 上线的协同路径：

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-model-overview-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=0fb38603c273424268809852d67468e8" alt="配发与上线时序" width="492" height="662" data-path="imgs/diagrams/va-model-overview-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-model-overview-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=f10666988675bc292e2aea786eac488b" alt="配发与上线时序" width="492" height="662" data-path="imgs/diagrams/va-model-overview-dark.svg" />
</Frame>

## 下一步

* 完成凭证配发与签名鉴权：[接入资源 › 鉴权指南](../integration-resources/overview)
* 登记接口白名单：[接入资源 › IP 白名单](../integration-resources/ip-whitelisting)
* 配置事件回调：[接入资源 › Webhook 与 WebSocket 实时通知](../integration-resources/webhook-websocket)