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

# 介绍

> Dodo Payments API 提供全面的端点用于支付处理、订阅管理和数字产品交付。我们的 RESTful API 遵循行业标准，为所有操作提供详细的响应。

<Card title="SDKs & Libraries" icon="code" href="/developer-resources/dodo-payments-sdks">
  通过使用 <strong>TypeScript</strong>、<strong>Python</strong>、<strong>Go</strong>、<strong>PHP</strong>、<strong>Java</strong>、<strong>Kotlin</strong>、<strong>C#</strong>、<strong>Ruby</strong> 和 <strong>React Native</strong> 的官方 SDK 来加速您的集成。这些库简化了 API 请求、身份验证和错误处理，让您专注于构建出色的支付体验。
</Card>

## 环境 URLs

* **测试模式**: [`https://test.dodopayments.com`](https://test.dodopayments.com)
* **实时模式**: [`https://live.dodopayments.com`](https://live.dodopayments.com)

<Note>
  了解更多关于[Test Mode vs Live Mode](/miscellaneous/test-mode-vs-live-mode)的信息。
</Note>

## API 密钥管理和认证

<Steps>
  <Step title="Access API Keys">
    在您的控制面板中导航到 **开发者 → API 密钥** 来管理您的密钥。
  </Step>

  <Step title="Generate a New Key">
    选择 **添加 API 密钥**，提供描述性名称，并配置写入访问权限：

    * **启用写入权限**（选中）：所有 API 操作的全面读写权限
    * **启用写入权限**（未选中）：只读访问 - 只能获取数据（支付、订阅、客户、产品）。无法创建或修改资源。

    <Tip>
      取消选中“启用写入权限”用于仅需查看数据而无需进行更改的控制面板集成、分析工具或任何系统。
    </Tip>
  </Step>

  <Step title="Store Your Key Securely">
    立即复制生成的密钥，并确保其安全存储。
  </Step>

  <Step title="Authenticate Your API Requests">
    使用您的 API 密钥来认证所有请求。应用以下授权格式：

    ```bash theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    <Warning>
      切勿在客户端代码或公共存储库中暴露您的秘密 API 密钥。
    </Warning>
  </Step>
</Steps>

## 响应格式

<CodeGroup>
  ```json Success Response theme={null}
  {
    "id": "pay_1234567890",
    "status": "succeeded",
    "amount": 2999,
    "currency": "USD",
    "created_at": "2024-01-15T10:30:00Z"
  }
  ```

  ```json Error Response theme={null}
  {
    "code": "INVALID_REQUEST",
    "message": "The request contains invalid parameters"
  }
  ```
</CodeGroup>

## 速率限制

我们的 API 使用双窗口速率限制系统并具有突发保护。限制根据您的认证方法和业务等级应用。

### 默认限制（等级 0）

| 窗口      | 限制     |
| ------- | ------ |
| 每秒（突发）  | 40 请求  |
| 每分钟（持续） | 240 请求 |

### 业务等级

对于有更高 API 需求的业务，可提供更高的速率限制：

| 等级       | 突发（每秒） | 持续（每分钟） |
| -------- | ------ | ------- |
| 等级 0（默认） | 40     | 240     |
| 等级 1     | 100    | 1,000   |
| 等级 2     | 500    | 5,000   |

<Tip>
  联系支持以将您的业务升级到更高的速率限制等级。
</Tip>

### 未认证的请求

没有有效认证头的请求根据 IP 地址进行速率限制：

| 窗口      | 限制     |
| ------- | ------ |
| 每秒（突发）  | 20 请求  |
| 每分钟（持续） | 100 请求 |

### 速率限制头

使用这些响应头监控您的使用情况：

* `X-RateLimit-Limit` - 允许的最大请求数
* `X-RateLimit-Remaining` - 当前窗口中剩余的请求数
* `X-RateLimit-Reset` - 速率限制重置的时间

<Note>
  当您超过速率限制时，API 返回 `429 Too Many Requests` 响应。在重试逻辑中实施指数退避。
</Note>

## 错误处理

要有效管理错误，请查阅 *错误代码* 和 *交易失败* 部分以获得详细指导。

<CardGroup cols={2}>
  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    深入了解全面的错误详情及其解决方案。
  </Card>

  <Card title="Transaction Failures" icon="circle-exclamation" href="/api-reference/transaction-failures">
    获取有关常见交易问题及其解决方案的见解。
  </Card>
</CardGroup>

## Webhooks

接收有关支付事件的实时通知。参阅我们的 [Webhook 指南](/developer-resources/webhooks) 以获取设置说明。

<Card title="Webhook Guide" icon="webhook" href="/developer-resources/webhooks">
  设置 webhooks 以获得实时通知和事件处理。
</Card>

## 相关开发者指南

探索我们全面的指南，以了解如何使用 API 实现关键功能：

<CardGroup cols={2}>
  <Card title="One-time Payments Integration" icon="code-merge" href="/developer-resources/integration-guide">
    学习如何在您的应用程序中集成一次性支付、结账会话和支付链接
  </Card>

  <Card title="Subscription Integration" icon="credit-card" href="/developer-resources/subscription-integration-guide">
    完整指南以实现订阅、管理计划和处理订阅生命周期事件
  </Card>

  <Card title="Usage-Based Billing" icon="arrow-trend-up" href="/developer-resources/usage-based-billing-guide">
    设置计量和使用事件以进行计量计费和基于消耗的定价模型
  </Card>

  <Card title="Webhooks" icon="box" href="/developer-resources/webhooks">
    通过 webhook 事件接收实时通知并自动化工作流
  </Card>

  <Card title="Checkout Sessions" icon="cart-shopping" href="/developer-resources/checkout-session">
    创建安全的、托管的结账体验，提供完全自定义和高级功能
  </Card>
</CardGroup>