> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 集成

> 简要介绍平台工具和集成方式。

<Warning>
  **注意**: 请一定在测试环境完整验证后，才部署功能到生产。<br />
  Clink的测试环境和生产使用不同域名和API密钥。请不要在测试环境使用真实信息或者生产密钥。
</Warning>

## 商户后台

后台给您的账户提供日常运营功能。以下资源通过后台进行管理：

<Columns cols={2}>
  <Card title="商户" icon="store" href="guides/account/merchant">
    业务运行主体。
  </Card>

  <Card title="用户" icon="user" href="guides/account/user">
    可以登录商户后台的用户。
  </Card>

  <Card title="产品&价格" icon="package-search" href="guides/resources/product">
    售卖的产品和定价配置。
  </Card>

  <Card title="余额" icon="circle-dollar-sign" href="finance/balance">
    账户余额和费用信息。
  </Card>
</Columns>

## API 集成

我们提供安全且易用的API。API集成通过商户后台生成的密钥进行认证。

### 初始化API密钥

进入**开发者**页面，点击**初始化密钥**，请务必复制并安全保存密钥，因为它只会显示一次。

<AccordionGroup>
  <Accordion icon="code" title="生成API密钥">
    <img src="https://mintcdn.com/clink/peBNaRlFWIQS8vOQ/images/cn/cn_empty_key.png?fit=max&auto=format&n=peBNaRlFWIQS8vOQ&q=85&s=ad263b7f6b0a872716f7dd8fbbc08cce" alt="key" width="1399" height="473" data-path="images/cn/cn_empty_key.png" />
  </Accordion>
</AccordionGroup>

### 密钥类型

* 密钥（Secret Key）：用于验证Clink的API请求。默认情况下，此密钥可以执行任何API请求，没有限制。
  * 测试环境密钥格式：sk\_test\_\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*
  * 生产环境密钥格式：sk\_prod\_\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*
* 可发布密钥（Publishable Key）：用于客户端代码中，主要用于嵌入支付表单。Clink正在开发此功能的支持。
  * 测试环境密钥格式：pk\_test\_\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*
  * 生产环境密钥格式：pk\_prod\_\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*

### 密钥轮换

轮换密钥会使当前密钥失效并自动生成替代密钥。您可以选择让旧密钥立即失效，或设定在特定时间后失效。

轮换API密钥的步骤：

* 进入**开发者**页面
* 在要轮换的密钥行中点击更多按钮(⋮)，然后选择**轮换密钥**
* 从**失效时间**下拉菜单中选择期限
* 点击**轮换密钥**
* **复制**对话框中显示的新密钥
* 保存密钥值，因为之后将无法再次查看

### 删除密钥

删除密钥后，该密钥将立即无法进行API调用。如果某个密钥是最后一个有效的密钥，则**不能**删除它。

删除API密钥的步骤：

* 打开API密钥页面
* 轮换要删除的密钥
* 更新代码使用新密钥
* 点击旧密钥的更多按钮，然后选择删除

### 限制密钥的IP地址

只有密钥（Secret Key）可以限制特定IP地址。您可以将API请求限制在一个或多个IP地址，或使用[CIDR](https://zh.wikipedia.org/wiki/%E6%97%A0%E7%B1%BB%E5%88%AB%E5%9F%9F%E9%97%B4%E8%B7%AF%E7%94%B1)限制IP地址范围。

* 打开API密钥页面
* 在要限制的密钥行中点击更多按钮(⋮)，然后选择**管理IP限制**
* 开启\_限制使用特定IP地址\_
* 点击**添加**按钮
* 输入单个IP地址或CIDR范围
* 点击**保存**按钮

## Webhooks

Webhooks允许应用程序向其他应用程序提供实时信息。它们在事件发生时立即传递数据，确保您能即时接收信息。
注册webhook端点后，当事件发生时，Clink会将实时事件数据推送到您应用程序的webhook端点。

### 注册

要注册webhook端点，请进入**开发者**页面并选择Webhooks标签：

* 点击**新增**按钮
* 输入您的**HTTPS**端点
* 选择您想要监听的事件类型。我们建议监听所有事件

有关事件类型及其相关数据的详细信息，请参阅[Webhook参考文档](/cn/api-reference/webhook)

### 验证签名

Clink使用 HMAC SHA-256 为每个事件生成签名。签名密钥在webhook端点注册后可用。

生成签名的步骤：

* 从请求头中提取时间戳、签名和签名类型：
  * 时间戳在**X-Clink-Timestamp**字段中
  * Clink生成的签名在**X-Clink-Signature**字段中
  * 签名类型在**X-Clink-SignType**字段中。当前值为**SHA256**。
* 准备要签名的载荷字符串，连接以下内容：
  * 时间戳（字符串形式）
  * 字符 **.**
  * 收到的原始请求体
* 使用SHA256哈希函数计算HMAC，并将结果编码为hex字符串生成签名
* 比较签名值，只有在签名匹配时才处理事件

验签时必须使用原始请求体。请不要先解析JSON再重新序列化后计算签名，因为格式变化会导致签名不一致。

### 事件投递

Clink会尝试将事件投递到您的目标端点最多10次，使用指数退避策略。所有重试将在大约一天内完成。

请注意，我们不保证事件会按照生成的顺序投递。请确保您的应用程序不依赖于按特定顺序接收事件。

### 最佳实践

感谢Stripe提供的详细指南：[使用webhooks的最佳实践](https://docs.stripe.com/webhooks#best-practices)