> ## 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.
# 介绍
> 当客户付款时，自动交付许可证密钥、可下载文件、功能标志，以及访问 Discord、GitHub、Telegram、Framer 和 Notion 等平台。
授权将成功付款或活跃订阅转换为实际访问：客户收件箱中的许可证密钥、应用检查的功能标志、Discord 角色、GitHub 仓库、Notion 模板、Framer 混音链接、Telegram 聊天邀请或可下载文件包。随着支付生命周期的变化，Dodo Payments 自动发布、跟踪和撤销该访问权限。
## 什么是Entitlements?
**Entitlement** 是您向客户提供的产品的可重用定义：Pro许可证密钥、“Patrons”Discord角色、私人GitHub存储库的访问权限、可下载的电子书包。您可以将entitlement 附加到产品中，然后Dodo Payments 将处理其余工作。
当客户购买产品时，Dodo Payments 会创建一个 **grant**，即该entitlement的单个客户发行。Grants会经过一小组状态：在交付进行中时的`pending`，客户获得访问权限后的`delivered`，如果交付无法完成的`failed`，以及访问被撤回时的`revoked`。
Entitlements 控制**交付**（客户是否有访问权限？）。Credits 控制**消耗**（他们可以使用多少？）。两者都可以附加到相同的产品中。查看 [Credit-Based Billing](/features/credit-based-billing) 以了解credits。
## 可用集成
Dodo Payments 通过专用集成交付每个entitlement。选择与您销售的产品匹配的集成。
生成具有激活限制和到期时间的唯一许可证密钥。最佳用于软件、插件和CLI。
通过预签名的下载URL和可选说明交付可下载文件（电子书、模板、媒体）。
在您的应用中通过购买来限制功能。即时交付，通过 API 检查，取消时撤销。
当客户购买时，在您的 Discord 服务器中为其授予角色。取消时自动撤销。
在您选择的权限级别上将客户添加为私人仓库的协作者。
购买后将客户添加到私人 Telegram 聊天或频道中。
为付费客户解锁 Framer 模板混音链接。
将 Notion 模板复制到客户的工作区中。
***
## 授权工作原理
授权由您已接收为 webhooks 的同一支付和订阅事件驱动。您无需自己调用授权 API 进行购买。Dodo Payments 根据基础支付生命周期自动创建和撤销授权。
### 授权生命周期
当付款完成或订阅激活时，会创建授权。许可证密钥和功能标志直接跳转到 `delivered`。其他集成在 `pending` 开始。基于 OAuth 的集成（Discord、GitHub、Notion）包括一个客户必须访问以完成同意的 `oauth_url`。平台直接集成（Telegram、Framer、Digital Files）仅在交付准备期间短暂停留在 `pending`，然后过渡到 `delivered`。
一旦交付完成（生成许可证密钥、分配角色、授予仓库访问权限、解析文件链接、完成 OAuth），授权将移动到 `delivered`，并设置 `delivered_at`。
如果集成调用返回不可重试错误（撤销的 OAuth 令牌、拒绝权限、文件不再存在），授权将移动到 `failed`。`error_code` 和 `error_message` 字段捕获原因。
当访问被撤回（订阅取消、发出退款或商家发起的撤销）时，授权将移动到 `revoked`。`revocation_reason` 字段记录触发器。
### 不同事件的授权行为
| Event | 行为 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded`（一次性付款） | 每个附加的授权发放一个授权。 |
| `payment.succeeded`（与订阅相关的付款） | 无操作。授权由下面的订阅事件驱动。 |
| `subscription.active` | 对于尚未收到授权的任何附加授权发放授权。重新授予任何先前为相同订阅撤销的授权。 |
| `subscription.renewed` | 无操作。现有授权在续订期间持续存在。 |
| `subscription.on_hold` | 撤销所有已交付和待处理的授权。`revocation_reason: subscription_on_hold`。 |
| `subscription.cancelled` | 撤销所有。`revocation_reason: subscription_cancelled`。 |
| `subscription.expired` | 撤销所有。`revocation_reason: subscription_expired`。 |
| `subscription.plan_changed` | 撤销所有现有授权，然后为新计划的授权发放。`revocation_reason: plan_changed`。 |
| `refund.succeeded`（一次性付款） | 撤销该付款的授权。`revocation_reason: refund`。 |
| Manual API revoke | 使用 `revocation_reason: manual` 撤销。手动撤销不会在订阅续订时自动重新授予。 |
| License key disabled | 对于许可证密钥授权，禁用基础密钥会以 `revocation_reason: license_key_disabled` 撤销授权。如果密钥重新启用，授权会自动重新激活。 |
| Platform drift detected | 如果集成的平台端不同步（手动删除 Discord 角色、GitHub 应用失去仓库访问权限或协调时检测到缺失目标），授权会以 `revocation_reason: platform_external` 撤销。在订阅续订时不会自动重新授予，直到解决基础平台问题。 |
由订阅驱动的授权对于 `(entitlement, customer, subscription)` 是幂等的；续订和重新激活不会创建重复的授权。一次性授权对于 `(entitlement, customer, payment)` 是幂等的。
***
## 创建您的第一个授权
在您的 Dodo Payments 仪表板中进入 **Entitlements** 并单击 **+** 创建新授权。
选择集成类型：许可证密钥、数字文件、功能标志、Discord、GitHub、Telegram、Framer 或 Notion。对于平台集成，如果尚未连接，请先连接您的账户。
填写特定于集成的字段。例如，GitHub 需要仓库和权限级别；Discord 需要服务器和可选角色；许可证密钥需要激活限制和到期时间。
保存授权。您现在可以将其附加到任何产品上。
## 将授权附加到产品
打开产品，展开 **高级设置 → 授权和积分**，选择购买产品时应交付的授权。单个产品可以一次交付多个授权。例如，一个专业计划可以包括许可证密钥、GitHub 访问权限和 Discord 角色。
***
## 客户体验
### 邮件和客户门户
客户收到购买后包含许可证密钥、下载链接、OAuth 邀请链接或平台邀请的交付邮件，这取决于产品上的授权。相同的详细信息可在他们的 [客户门户](/features/customer-portal) 中的订单历史记录中无限期地使用。
### 基于 OAuth 的交付
Discord、GitHub 和 Notion 订阅者访问需要客户授权 Dodo Payments 授予他们访问权限。这些授权在客户使用其电子邮件或客户门户中的链接完成 OAuth 流程之前，处于 `pending` 状态。一旦他们授权，授权将移动到 `delivered`，并立即提供平台访问。
### 撤销
撤销的授权在平台级别被移除：Discord 角色被移除，GitHub 协作者被移除，许可证密钥被禁用。客户可以在客户门户中看到反映的变化。
对于数字文件，撤销会删除对预签名 URL 的访问，但不会使客户已下载的副本失效。请相应规划内容限制。
***
## 管理授权
从仪表板打开任何授权以查看其授权。授权详细信息面板显示总授权数、状态过滤器、客户信息、交付日期和撤销操作。
您也可以以编程方式管理授权：
```typescript TypeScript theme={null} theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
});
// List grants for an entitlement
const grants = await client.entitlements.grants.list('ent_abc123', {
status: 'Delivered',
});
// Revoke a single grant
await client.entitlements.grants.revoke('grant_xyz789', {
id: 'ent_abc123',
});
```
```python Python theme={null} theme={null}
client.entitlements.grants.list(
"ent_abc123",
status="Delivered",
)
client.entitlements.grants.revoke(
"grant_xyz789",
id="ent_abc123",
)
```
```go Go theme={null} theme={null}
grants, _ := client.Entitlements.Grants.List(
ctx, "ent_abc123",
dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
)
_, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")
```
***
## API 管理
创建任意集成类型的新授权。
通过集成类型进行过滤列出授权。
检索授权及其解析的配置。
更新名称、描述或集成配置。
软删除授权；现有授权不受影响。
上传文件到数字文件授权（最多 500 MiB）。
列出授权的所有授权，带有状态和客户过滤器。
手动撤销单个授权。
***
## Webhooks
Dodo Payments 为授权生命周期触发四个 webhook 事件。订阅这些事件以保持您的应用程序与每个客户的访问权限同步。
| Event | 触发时 |
| ----------------------------- | ------------------------------------------------------------------------------------------------ |
| `entitlement_grant.created` | 创建新授权时。许可证密钥授权到达 `delivered`；其他每个集成到达 `pending`，并在平台调用成功后（或基于 OAuth 的集成中，在客户授权后）过渡到 `delivered`。 |
| `entitlement_grant.delivered` | 授权过渡到已交付状态。客户现在拥有访问权限。 |
| `entitlement_grant.failed` | 授权无法交付。检查 `error_code` 和 `error_message`。 |
| `entitlement_grant.revoked` | 访问已被撤回。检查 `revocation_reason`。 |
查看完整的负载架构、示例事件和 `revocation_reason` 参考。
***
## 最佳实践
* **每个交付渠道使用一个授权。** 不要在具有不同角色意图的产品之间共享单个 Discord 授权；为每个角色创建一个，以便于撤销。
* **首先在测试模式中测试。** 创建授权，将其附加到测试产品，进行结账，并观察授权通过 `pending → delivered` 的过渡。确认取消测试订阅是否撤销授权。
* **监听 `entitlement_grant.delivered`，而不是 `payment.succeeded`。** 付款可以在履行完成之前成功（尤其对于 OAuth 流程）。等待交付事件再解锁您自己系统中的依赖功能。
* **将 `entitlement_grant.failed` 视为可操作的。** 失败的授权意味着客户支付了但未获得访问权限。将这些情况呈现给您的支持团队或触发重新授权。
* **将 `revocation_reason` 映射到您的保留流程。** `subscription_on_hold` 撤销是可恢复的（客户可能会更新他们的卡）。 `manual` 撤销是有意的。在客户通信中区别对待。