> ## 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.
# Giới Thiệu
> Tự động cung cấp khóa giấy phép, tệp tải về, cờ tính năng, và truy cập vào các nền tảng như Discord, GitHub, Telegram, Framer, và Notion khi khách hàng thanh toán.
Entitlements biến một lần thanh toán thành công hoặc đăng ký hoạt động thành quyền truy cập thực tế: một khóa giấy phép trong hộp thư của khách hàng, một cờ tính năng ứng dụng của bạn kiểm tra, một vai trò Discord, một kho lưu trữ GitHub, một mẫu Notion, một liên kết remix Framer, một lời mời trò chuyện Telegram, hoặc một gói tệp tải về. Dodo Payments tự động phát hành, theo dõi và thu hồi quyền truy cập đó khi vòng đời thanh toán thay đổi.
## Entitlements là gì?
Một **entitlement** là một định nghĩa tái sử dụng của thứ bạn cung cấp cho khách hàng: một mã giấy phép Pro, một vai trò "Patrons" trên Discord, quyền truy cập vào kho lưu trữ GitHub riêng của bạn, một gói e-book có thể tải xuống. Bạn gắn entitlements vào sản phẩm, và Dodo Payments xử lý phần còn lại.
Khi một khách hàng mua sản phẩm, Dodo Payments tạo một **grant**, tức là việc phát hành entitlement đó cho khách hàng cụ thể. Grants di chuyển qua một tập hợp trạng thái nhỏ: `pending` trong khi việc giao hàng đang tiến hành, `delivered` khi khách hàng có quyền truy cập, `failed` nếu không thể hoàn thành việc giao hàng, và `revoked` khi quyền truy cập bị thu hồi.
Entitlements kiểm soát **fulfillment** (khách hàng có quyền truy cập không?). Credits kiểm soát **consumption** (họ có thể sử dụng bao nhiêu?). Cả hai có thể được gắn vào cùng một sản phẩm. Xem [Thanh toán Dựa trên Tín dụng](/features/credit-based-billing) cho thông tin về credits.
## Các Tích Hợp Có Sẵn
Dodo Payments cung cấp mỗi entitlement thông qua một tích hợp chuyên dụng. Chọn tích hợp phù hợp với những gì bạn bán.
Tạo mã giấy phép duy nhất với giới hạn kích hoạt và thời hạn. Phù hợp nhất cho phần mềm, plugin, và CLI.
Cung cấp các tập tin có thể tải xuống (e-books, mẫu, phương tiện) với URL tải xuống được ký trước và hướng dẫn tùy chọn.
Chặn các tính năng trong ứng dụng của bạn sau khi mua. Được cung cấp ngay lập tức, kiểm tra thông qua API, thu hồi khi hủy bỏ.
Cấp cho khách hàng một vai trò trong máy chủ Discord của bạn khi họ mua. Thu hồi tự động khi hủy bỏ.
Thêm khách hàng làm người cộng tác vào kho lưu trữ riêng tư theo mức quyền bạn chọn.
Thêm khách hàng vào trò chuyện hoặc kênh Telegram riêng tư sau khi mua.
Mở khóa một liên kết remix của mẫu Framer cho khách hàng thanh toán.
Nhân bản một mẫu Notion vào không gian làm việc của khách hàng khi mua.
***
## Cách thức hoạt động của Grants
Grants được điều khiển bởi các sự kiện thanh toán và đăng ký mà bạn đã nhận được dưới dạng webhooks. Bạn không cần phải tự gọi API grant cho các lần mua. Dodo Payments tự động tạo và thu hồi grants dựa trên vòng đời thanh toán cơ bản.
### Vòng đời của Grant
Một grant được tạo khi một khoản thanh toán hoàn thành hoặc một đăng ký trở nên hoạt động. Khóa giấy phép và cờ tính năng nhảy trực tiếp đến `delivered`. Mọi tích hợp khác bắt đầu ở `pending`. Các tích hợp dựa trên OAuth (Discord, GitHub, Notion) bao gồm một `oauth_url` mà khách hàng phải truy cập để hoàn thành ủy quyền. Các tích hợp trực tiếp từ nền tảng (Telegram, Framer, Tệp Kỹ Thuật Số) chỉ nằm trong `pending` ngắn gọn trong khi việc cung cấp được chuẩn bị, sau đó chuyển sang `delivered`.
Khi việc cung cấp hoàn thành (khóa giấy phép được tạo, vai trò được gán, truy cập kho lưu trữ được cấp, liên kết tệp được giải quyết, OAuth hoàn thành), grant di chuyển đến `delivered` và `delivered_at` được thiết lập.
Nếu cuộc gọi tích hợp trả về một lỗi không thể thử lại (token OAuth bị thu hồi, quyền bị từ chối, tệp không còn tồn tại), grant di chuyển đến `failed`. Các trường `error_code` và `error_message` ghi nhận lý do.
Khi quyền truy cập bị rút lại (đăng ký bị hủy, hoàn tiền, hoặc thu hồi do người bán khởi xướng), grant di chuyển đến `revoked`. Trường `revocation_reason` ghi lại kích hoạt.
### Hành vi của Grant theo sự kiện
| Sự kiện | Hành vi |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (thanh toán một lần) | Phát hành một grant cho mỗi quyền lợi được đính kèm. |
| `payment.succeeded` (thanh toán liên kết đăng ký) | Không hoạt động. Grants được điều khiển bởi sự kiện đăng ký dưới đây. |
| `subscription.active` | Phát hành grants cho bất kỳ quyền lợi đính kèm nào chưa có grant. Cấp lại bất kỳ grants nào trước đó đã bị thu hồi cho cùng đăng ký. |
| `subscription.renewed` | Không hoạt động. Các grants hiện tại tồn tại qua các lần gia hạn. |
| `subscription.on_hold` | Thu hồi tất cả grants đã cung cấp và đang chờ xử lý. `revocation_reason: subscription_on_hold`. |
| `subscription.cancelled` | Thu hồi tất cả. `revocation_reason: subscription_cancelled`. |
| `subscription.expired` | Thu hồi tất cả. `revocation_reason: subscription_expired`. |
| `subscription.plan_changed` | Thu hồi tất cả grants hiện tại, sau đó phát hành grants cho quyền lợi của kế hoạch mới. `revocation_reason: plan_changed`. |
| `refund.succeeded` (thanh toán một lần) | Thu hồi grants cho khoản thanh toán đó. `revocation_reason: refund`. |
| Thu hồi API thủ công | Thu hồi bằng `revocation_reason: manual`. Thu hồi thủ công không được cấp lại tự động khi gia hạn đăng ký. |
| Khóa giấy phép bị vô hiệu hóa | Đối với grants khóa giấy phép, việc vô hiệu hóa khóa cơ bản sẽ thu hồi grant bằng `revocation_reason: license_key_disabled`. Grant được tự động kích hoạt lại nếu khóa được kích hoạt lại. |
| Phát hiện drift nền tảng | Nếu phần nền tảng của một tích hợp chệch hướng so với đồng bộ (một vai trò Discord bị loại bỏ thủ công, ứng dụng GitHub mất quyền truy cập để kho lưu trữ, hoặc một cuộc đối chiếu phát hiện mục tiêu thiếu), grant bị thu hồi với `revocation_reason: platform_external`. Không được cấp lại tự động khi gia hạn đăng ký cho đến khi vấn đề nền tảng được giải quyết. |
Grants dựa trên đăng ký là idempotent cho mỗi `(entitlement, customer, subscription)`; gia hạn và kích hoạt lại không tạo ra grants trùng lặp. Grants một lần là idempotent cho mỗi `(entitlement, customer, payment)`.
***
## Tạo quyền lợi đầu tiên của bạn
Đi tới **Entitlements** trong bảng điều khiển Dodo Payments của bạn và nhấp vào **+** để tạo một quyền lợi mới.
Chọn loại tích hợp: Key giấy phép, Tệp kỹ thuật số, Cờ tính năng, Discord, GitHub, Telegram, Framer, hoặc Notion. Đối với các tích hợp nền tảng, kết nối tài khoản của bạn đầu tiên nếu bạn chưa làm.
Điền vào các trường cụ thể cho tích hợp. Ví dụ, GitHub yêu cầu kho lưu trữ và mức quyền; Discord yêu cầu máy chủ và vai trò tùy chọn; Khóa giấy phép yêu cầu hạn mức kích hoạt và ngày hết hạn.
Lưu quyền lợi. Bây giờ bạn có thể đính kèm nó vào bất kỳ sản phẩm nào.
## Đính kèm quyền lợi vào sản phẩm
Mở một sản phẩm, mở rộng **Cài đặt nâng cao → Quyền lợi & Tín dụng**, và chọn các quyền lợi mà nên được cung cấp khi sản phẩm được mua. Một sản phẩm có thể cung cấp nhiều quyền lợi cùng một lúc. Ví dụ, một kế hoạch Pro có thể bao gồm một khóa giấy phép, quyền truy cập GitHub, và một vai trò Discord.
***
## Trải nghiệm khách hàng
### Email và cổng thông tin khách hàng
Khách hàng nhận được một email cung cấp sau khi mua chứa khóa giấy phép, liên kết tải về, liên kết mời OAuth, hoặc lời mời nền tảng, tùy theo các quyền lợi trên sản phẩm. Các chi tiết này vẫn có sẵn vô thời hạn từ [Cổng thông tin Khách hàng](/features/customer-portal) dưới lịch sử đơn hàng của họ.
### Cung cấp dựa trên OAuth
Truy cập đăng ký Discord, GitHub và Notion yêu cầu khách hàng ủy quyền cho Dodo Payments để cấp quyền truy cập cho họ. Các grants này duy trì trạng thái `pending` cho đến khi khách hàng hoàn thành luồng OAuth bằng cách sử dụng liên kết từ email hoặc cổng thông tin khách hàng của họ. Sau khi họ ủy quyền, grant chuyển đến `delivered` và quyền truy cập nền tảng được cung cấp ngay lập tức.
### Thu hồi
Các grants bị thu hồi được loại bỏ ở cấp độ nền tảng: vai trò Discord bị loại bỏ, cộng tác viên GitHub bị loại bỏ, khóa giấy phép bị vô hiệu hóa. Khách hàng nhìn thấy sự thay đổi được phản ánh trong cổng thông tin khách hàng.
Đối với Tệp Kỹ Thuật Số, việc thu hồi loại bỏ quyền truy cập vào các URL được định sẵn trong tương lai nhưng không làm vô hiệu hóa các bản sao mà khách hàng đã tải xuống. Đặt nội dung kế hoạch tương ứng.
***
## Quản lý Grants
Mở bất kỳ quyền lợi nào từ bảng điều khiển để xem các grants của nó. Bảng chi tiết grant hiển thị tổng số grants, bộ lọc trạng thái, thông tin khách hàng, ngày cung cấp, và hành động thu hồi.
Bạn cũng có thể quản lý grants bằng chương trình:
```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")
```
***
## Quản lý API
Tạo một quyền lợi mới của bất kỳ loại tích hợp nào.
Danh sách các quyền lợi với bộ lọc theo loại tích hợp.
Truy xuất một quyền lợi và cấu hình đã giải quyết của nó.
Cập nhật tên, mô tả, hoặc cấu hình tích hợp.
Xóa mềm một quyền lợi; các grants hiện tại không bị ảnh hưởng.
Tải lên tệp cho một quyền lợi Tệp Kỹ Thuật Số (tối đa 500 MiB).
Danh sách tất cả grants cho một quyền lợi với bộ lọc trạng thái và khách hàng.
Thu hồi thủ công một grant.
***
## Webhooks
Dodo Payments phát bốn sự kiện webhook cho vòng đời grant. Đăng ký các sự kiện này để giữ cho ứng dụng của bạn đồng bộ với những gì mỗi khách hàng có thể truy cập.
| Sự kiện | Sinh ra khi |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entitlement_grant.created` | Một grant mới được tạo. Grants khóa-key đến `delivered`; mọi tích hợp khác đến `pending` và chuyển đến `delivered` khi cuộc gọi nền tảng thành công (hoặc, đối với tích hợp dựa trên OAuth, khi khách hàng ủy quyền). |
| `entitlement_grant.delivered` | Grant chuyển sang được cung cấp. Khách hàng hiện có quyền truy cập. |
| `entitlement_grant.failed` | Grant không thể được cung cấp. Kiểm tra `error_code` và `error_message`. |
| `entitlement_grant.revoked` | Quyền truy cập đã bị rút lại. Kiểm tra `revocation_reason`. |
Xem toàn bộ sơ đồ tải, các sự kiện mẫu, và tham chiếu `revocation_reason`.
***
## Thực hành tốt nhất
* **Sử dụng một quyền lợi cho mỗi kênh cung cấp.** Đừng chia sẻ một quyền lợi Discord duy nhất giữa các sản phẩm có ý định vai trò khác nhau; tạo một quyền lợi cho mỗi vai trò để thu hồi sạch. - **Thử nghiệm ở chế độ thử nghiệm trước tiên.** Tạo quyền lợi, đính kèm nó vào một sản phẩm thử nghiệm, chạy một lần thanh toán, và xem grant chuyển qua `pending → delivered`. Xác nhận rằng việc hủy đăng ký thử nghiệm thu hồi grant. - **Lắng nghe `entitlement_grant.delivered`, không phải `payment.succeeded`.** Một thanh toán có thể thành công trước khi việc hoàn thành kết thúc (đặc biệt đối với các luồng OAuth). Đợi sự kiện được cung cấp trước khi mở khóa các tính năng phụ thuộc trong các hệ thống của bạn. - **Xem `entitlement_grant.failed` là hành động được thực hiện.** Một grant thất bại có nghĩa là một khách hàng đã thanh toán nhưng không nhận được quyền truy cập. Hiển thị những trường hợp này cho nhóm hỗ trợ của bạn hoặc kích hoạt cấp lại. - **Map `revocation_reason` vào các luồng giữ chân của bạn.** Một thu hồi `subscription_on_hold` có thể phục hồi (khách hàng có thể cập nhật thẻ của họ). Một thu hồi `manual` là có chủ ý. Đối xử chúng khác nhau trong thông tin khách hàng.