数字产品交付 - Dodo Payments Documentation

概述

数字产品交付是数字文件的权限类型。您将文件上传到数字文件权限，附加到产品，Dodo Payments 会通过电子邮件和客户门户向每位付费客户提供预签名下载链接。该权限支持：

托管文件上传：在 Dodo Payments 中存储文件，并通过短期有效的预签名 URL 提供服务。
外部下载链接：链接到托管在 Dropbox、Google Drive、S3 或任何 URL 上的文件。
下载说明：在订单页面和交付电子邮件中显示给客户的自由格式文本。

您可以在单个权限中混合使用这三种。

关键功能

File Upload

上传文件（PDF、ZIP、图片、视频等）最多至500 MiB。文件被有效地流式传输和存储。

Multiple Files

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

External Links

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

Presigned URLs

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

设置数字产品交付

Open Entitlements

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

Choose Digital Files

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

Add files, links, and instructions

配置任意组合：

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

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',
});

curl -X POST "https://test.dodopayments.com/entitlements/ent_files_abc/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./pro-bundle.zip" \
  -F "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

上传文件（最多500 MiB）并将其附加到许可中。

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解释首先安装什么或如何组合文件。
注意500 MiB限制。 更大的工件（多GB数据集、视频课程）应外部托管并通过external_url链接，而不是上传。
结合许可证密钥实现可撤销访问。 如果需要在退款后撤销对产品内功能的访问，将数字文件许可与许可证密钥许可结合，并在运行时验证密钥。
测试客户门户的刷新流程。 确认客户可以在一周后返回门户并仍然获得有效的下载链接。这是当电子邮件链接过期时的主要恢复路径。

​概述

​关键功能

File Upload

Multiple Files

External Links

Presigned URLs

​设置数字产品交付

​附加到产品

​交付工作原理

​客户体验

​购买确认

​客户门户访问

​程序化管理文件

​向权限上传文件

​列出授权和解析下载 URL

​从权限中移除文件

​重要注意事项

​API 管理

Create Entitlement

Upload File

Delete File

List Grants

Update Entitlement

Revoke Grant

​Webhooks

​旧版数字产品交付

​最佳实践

概述

关键功能

设置数字产品交付

附加到产品

交付工作原理

客户体验

购买确认

客户门户访问

程序化管理文件

向权限上传文件

列出授权和解析下载 URL

从权限中移除文件

重要注意事项

API 管理

Webhooks

旧版数字产品交付

最佳实践