跳转到主要内容

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 会通过电子邮件和客户门户向每位付费客户提供预签名下载链接。 该权限支持：
  • 托管文件上传：在 Dodo Payments 中存储文件，并通过短期有效的预签名 URL 提供服务。
  • 外部下载链接：链接到托管在 Dropbox、Google Drive、S3 或任何 URL 上的文件。
  • 下载说明：在订单页面和交付电子邮件中显示给客户的自由格式文本。
您可以在单个权限中混合使用这三种。

​
关键功能

File Upload

上传文件（PDF、ZIP、图片、视频等）最大可达 100 MB。文件被有效地流式传输和存储。

Multiple Files

将所需数量的文件附加到单个权限中。

External Links

提供外部下载链接（Dropbox、Google Drive、签名 S3 URL）作为替代或补充。

Presigned URLs

托管文件通过短期有效的预签名 URL 提供。每个下载 URL 大约在 15 分钟后自动过期。

​
设置数字产品交付

1

Open Entitlements

在 Dodo Payments 仪表板中转到权限，单击 + 创建新权限。
2

Choose Digital Files

选择数字产品交付作为集成。
3

Add files, links, and instructions

配置任意组合：
  • 文件：上传一个或多个文件。每次上传返回一个 file_id，并附加到权限上。
  • 外部 URL：一个可公开访问的 HTTPS 链接，与托管文件一起提供。
  • 说明：显示给客户的自由格式文本（例如，“解压缩并运行 setup.sh”）。
带有文件上传、外部 URL 和说明字段的数字文件权限
4

Save the entitlement

保存。现在可以将该权限附加到任何产品上。

​
附加到产品

打开产品，展开高级设置 → 权限和信用额，选择您的数字文件权限。该权限在与该产品相关的每次成功购买或有效订阅时交付。
显示选择的数字产品交付的产品权限面板

​
交付工作原理

数字文件交付遵循标准的授予生命周期：
事件行为
payment.succeeded （一次性）颁发授权。授权携带有效约 15 分钟的预签名下载 URL；客户可以通过重新打开电子邮件链接或客户门户页面刷新它们。
subscription.active颁发授权。在订阅有效期间，文件保持可访问状态。
subscription.renewed无操作。同一授权继续；每次获取时生成新的预签名 URL。
subscription.on_hold / cancelled / expired撤销授权。不再发放新的预签名 URL。
subscription.plan_changed撤销旧授权；为新计划的权限颁发新授权。
refund.succeeded （一次性）撤销授权。
手动撤销使用 revocation_reason: manual 撤销。
撤销停止 Dodo Payments 发放新的下载 URL，但不会使客户已下载的副本失效。将托管的文件下载视为“读取后交付”。

​
客户体验

​
购买确认

交易成功后，客户会收到一封包含下载链接和您配置的任何说明的电子邮件。
显示数字产品下载链接的购买确认电子邮件

​
客户门户访问

客户可以随时从客户门户重新获取下载链接。门户页面按需生成新的预签名 URL，因此即使在电子邮件的链接过期后，同一购买仍然有效。
显示可供下载的数字产品的客户门户界面
客户可以直接从确认电子邮件下载文件，或随时通过其门户访问。

​
程序化管理文件

​
向权限上传文件

import DodoPayments from 'dodopayments';
import fs from 'node:fs';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode',
});

await client.entitlements.files.upload('ent_files_abc', {
  file: fs.createReadStream('./pro-bundle.zip'),
  filename: 'pro-bundle.zip',
});

​
列出授权和解析下载 URL

const grants = await client.entitlements.grants.list('ent_files_abc', {
  customer_id: 'cus_abc123',
});

for (const grant of grants.items) {
  for (const file of grant.digital_product_delivery.files) {
    console.log(file.filename, file.download_url, `expires in ${file.expires_in}s`);
  }
}

​
从权限中移除文件

await client.entitlements.files.delete('ent_files_abc', 'df_a4f6c1de');

​
重要注意事项

  • 预签名 URL 过期速度很快。 授权负载或 webhook 事件中返回的下载 URL 有效期为约 15 分钟。不要存储它们；客户需要重新下载时重新获取。
  • 更新文件仅影响未来购买。 替换或移除文件不会溯及既往地改变已发放的下载。过去的客户仍然可以重新获取在授权创建时当前的版本。
  • 退款不会使已下载的副本失效。 已下载文件的客户保留该副本。对于可撤销的内容（许可证限制的媒体、时间有限的访问），将数字文件与许可证密钥配对并在运行时验证。
  • 对于敏感内容，优选使用具有自身身份验证的外部 URL。 Dodo Payments 的预签名 URL 短期有效，但在其窗口内未经认证；任何拥有 URL 的人都可以在该窗口内下载。外部托管、账号限制的内容提供更强的保证。

​
API 管理

Create Entitlement

创建数字文件权限，并附带可选的外部 URL 和说明。

Upload File

上传文件（最大 100 MB）并将其附加到权限中。

Delete File

从权限中移除文件。

List Grants

列出授权并读取解析后的下载 URL。

Update Entitlement

更新说明、外部 URL 或替换文件。

Revoke Grant

手动撤销客户的访问。

​
Webhooks

数字文件传递和撤销触发四个entitlement_grant.* webhook 事件。对于数字文件授权，负载包括一个 digital_product_delivery 对象，其中包含解析的文件列表（预签名 URL、文件名、大小）、可选的 instructions 和可选的 external_url。 
"digital_product_delivery": {
  "files": [
    {
      "file_id": "df_a4f6c1de",
      "download_url": "https://files.dodopayments.com/.../pro-bundle.zip?Signature=...",
      "filename": "pro-bundle.zip",
      "content_type": "application/zip",
      "file_size": 18742390,
      "expires_in": 900
    }
  ],
  "instructions": "Unzip and run setup.sh from the project root.",
  "external_url": null
}

​
旧版数字产品交付

配置了旧的 digital_product_delivery 块的产品已自动迁移到数字文件权限。旧版产品文件 API 下上传的现有文件已保存；它们仍然可以下载并在授权负载中显示，标记为 source: "legacy"。将来的更新（添加文件、更改说明、替换外部 URL）应该通过编辑权限下的迁移数字文件权限进行。遗留的产品层级字段（digital_product_delivery.external_url、digital_product_delivery.instructions）继续在产品响应中填充以向后兼容，但权限是未来的真正数据源。

​
最佳实践

  • 将下载视为一次性操作。 客户会分享或丢失链接，因此设计您的产品时假设任何他们下载的东西都是他们永久保留的。
  • 使用说明设定期望。 对于多文件包，添加 instructions 行说明首先安装什么或如何合并文件。
  • 注意 100 MB 限制。 较大的工件（多 GB 数据集、视频课程）应在外部托管并通过 external_url 链接而非上传。
  • 结合许可证密钥实现可撤销访问。 如果需要在退款后撤销对产品内功能的访问，请将数字文件权限与许可证密钥权限配对，并在运行时验证密钥。
  • 测试客户门户刷新流程。 确认客户可以在一周后返回门户，仍然获得有效的下载链接。当电子邮件链接过期时，这是主要的恢复路径。
Last modified on May 14, 2026