> ## 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 白名单

> 说明接入机构需要向 DCS 提交哪些出口 IP、各自用途，以及如何区分沙盒与生产环境。鉴权请求头与签名算法见鉴权指南，凭证的安全获取流程见前置准备。

<Warning>
  **白名单方向**：DeCard 托管模式的白名单由**接入机构**向 DCS 提供**接入机构自己的**网络出口地址，DCS 据此放行其调用。本页**不**列任何 DCS 自有 IP。
</Warning>

***

### 1. 为什么需要 IP 白名单

DCS 对接口调用启用 IP 白名单机制：只有来自接入机构**预先登记的网络出口地址**的请求，DCS 才会放行。这是在 API Key / Secret Key 签名鉴权之外的一层网络访问控制，将接口调用限制在可信网段内。

因此，在调用任何接口前，您需要把自己的**网络出口 IP** 提供给 DCS 报备。未报备或报备有误时，请求会在到达业务逻辑前被拒绝（见 [排障](#4-排障)）。

### 2. 两类需要报备的 IP

DeCard 托管模式（独立账户模式）下，**授权决策在 DCS 系统内部完成**，不存在「DCS 把授权转发回接入机构」的流程，因此**没有授权转发方向的白名单**。您需要向 DCS 报备的是以下两类用途不同的出口 IP：

| 用途            | 谁提供  | 方向         | 说明                                                                                 |
| :------------ | :--- | :--------- | :--------------------------------------------------------------------------------- |
| **接口调用白名单**   | 接入机构 | 接入机构 → DCS | 调用 DeCard 托管接口的网络出口地址。只有该名单内的来源 IP 才能成功调用接口。                                       |
| **生产凭证提取 IP** | 接入机构 | 接入机构 → DCS | 仅用于生产环境**一次性提取 API Key / Secret Key** 的请求 IP。该 IP 被加入「凭证提取」白名单，邮件下发的临时链接只能在此机器上执行。 |

<Warning>
  **这两类 IP 用途不同，请分别报备。** 用于**日常接口调用**的出口 IP，与用于**生产凭证一次性提取**的请求 IP，**可以不是同一个**，请分别向 DCS 说明各自用途。生产凭证提取的完整流程见 [前置准备](../getting-started/first-steps) 的「生产环境凭证安全提取」小节。
</Warning>

#### 关于 Webhook 方向

DCS 通过 Webhook 主动向您推送 KYC 状态、资产变动、卡交易、订单状态等事件。Webhook 的接入要求是：您暴露一个**公网可访问的 HTTPS** 回调地址，并以数字签名校验来源真实性（见 [Webhook 与 WebSocket 实时通知](./webhook-websocket)）。

<Note>
  如您的 Webhook 接收端有 IP 级入站限制需求，请联系 DCS 团队确认其出站 IP 范围。本页**不列任何 DCS IP**。
</Note>

### 3. 环境区分（沙盒 / 生产，勿混用）

DCS 区分**沙盒环境**与**生产环境**，二者的白名单**相互独立**。请为两套环境**分别**提供网络出口地址，切勿混用：

| 环境     | 接口调用白名单   | 生产凭证提取 IP              | 获取方式              |
| :----- | :-------- | :--------------------- | :---------------- |
| **沙盒** | 提供沙盒出口 IP | 不适用（沙盒凭证直接联系 DCS 团队获取） | 联系 DCS 团队         |
| **生产** | 提供生产出口 IP | 提供生产凭证一次性提取的请求 IP      | 通过商务渠道 / DCS 团队提交 |

**提交内容（占位示例，请替换为您的真实信息）**：

```text theme={null}
# 接口调用出口 IP
沙盒环境出口 IP：  <your-sandbox-egress-ip>
生产环境出口 IP：  <your-production-egress-ip>

# 生产凭证一次性提取（仅生产）
安全邮箱：          <your-secure-email>      # 接收凭证提取邮件
凭证提取请求 IP：    <your-extract-ip>        # 加入「凭证提取」白名单的机器 IP
```

> 提交方式：沙盒环境请直接联系 DCS 团队；生产环境请通过商务渠道 / DCS 团队提交并说明每个 IP 的用途。

### 4. 排障

白名单未报备或报备有误时，常见症状与排查：

| 症状                 | 可能原因                                            | 处理                            |
| :----------------- | :---------------------------------------------- | :---------------------------- |
| 接口请求被拒（鉴权之外的网络层拒绝） | 实际调用出口 IP 不在接口调用白名单内（如机器扩容、出口网关变更、NAT 出口 IP 漂移） | 确认当前真实出口 IP，提交给 DCS 补登白名单     |
| 连接被防火墙拦截 / 超时      | 您侧防火墙限制了到 DCS 的出站连接                             | 放行您侧到 DCS 的出站访问               |
| 生产凭证提取链接执行失败       | 执行机器的 IP 与报备的「凭证提取请求 IP」不一致；或链接已被使用过（仅一次有效）     | 在报备的指定机器上执行；如已失效需与商务沟通后重新发送邮件 |
| 沙盒能调通、生产被拒         | 沙盒与生产白名单未分别配置（误用同一套）                            | 为生产环境单独报备出口 IP                |

> 排查出口 IP 时，请以**实际发出请求那台机器/网关的公网出口 IP** 为准，而非内网地址。

***

## 下一步 / 相关

* 鉴权头与签名算法：[鉴权指南](./overview)
* 领取并安全提取凭证：[前置准备](../getting-started/first-steps)
* 事件推送的接入要求：[Webhook 与 WebSocket 实时通知](./webhook-websocket)