数字产品交付

使用 Digital Files 权益和短时有效的预签名 URL，在购买后自动交付可下载文件、外部链接和说明。

​

概述

Digital Product Delivery 是 Digital Files 权益类型。您只需将文件上传到 Digital Files 权益一次，然后将该权益附加到产品。Dodo Payments 随后会通过电子邮件和 Customer Portal 向每位付款客户提供预签名下载链接。

Digital Files 权益支持：

• 托管文件上传：Dodo Payments 存储您的文件，并通过短时有效的预签名 URL 提供文件。
• 外部下载链接：每个权益可配置一个 URL，指向托管在其他位置的文件，例如 Dropbox、Google Drive 或 S3。
• 下载说明：在客户订单页面和交付邮件中向客户显示的自由文本。

您可以在一个权益中组合使用这三种方式。在控制台中，至少添加一个文件或一个外部下载链接。

​

关键功能

File Upload

可上传 PDF、ZIP 压缩包、图片和视频等文件，每个文件最大为 500 MiB。Dodo Payments 会将每次上传流式传输到存储中。

Multiple Files

可根据需要将任意数量的文件附加到一个权益。

External Links

可以添加外部下载链接，例如 Dropbox、Google Drive 或已签名的 S3 URL，以替代托管文件或与托管文件搭配使用。

Presigned URLs

Dodo Payments 通过预签名 URL 提供托管文件。每个下载 URL 会在生成 15 分钟后过期。

---

​

设置 Digital Product Delivery

1. Open Entitlements

   在控制台中转到 Entitlements，然后点击 + 创建权益。

2. Choose Digital Files

   选择 Digital Files，并为权益输入一个 Name。

3. Add Files, Links, and Instructions

   配置以下字段的任意组合：

   • Upload files：上传一个或多个文件。每次上传都会返回 file_id，并将文件添加到权益的 digital_file_ids 中。
   • External Download Link：一个以 http:// 或 https:// 开头、客户可以访问的 URL。Dodo Payments 会将其与托管文件一同交付。
   • Instructions：向客户显示的自由文本，例如“解压并运行 setup.sh。”

   
4. Save the Entitlement

   点击 Create Entitlement。现在，您可以将该权益附加到任何产品。

​

附加到产品

打开一个产品，转到其 Entitlements 部分，然后选择您的 Digital Files 权益。对于该产品的每次成功购买或有效订阅，Dodo Payments 都会交付此权益。

Attaching the Digital Files entitlement to a product alongside other entitlements.

---

​

交付工作原理

Digital Files 交付遵循标准的授予生命周期。每个事件对 Digital Files 授予的影响如下：

Event	Behavior
payment.succeeded（一次性）	发放一个授予。该授予包含 15 分钟后过期的预签名下载 URL。客户重新打开邮件链接或 Customer Portal 页面即可获取新的 URL。
subscription.active	发放一个授予。订阅有效期间，文件始终可访问。
subscription.renewed	无变化。相同的授予会继续有效，每次获取都会生成新的预签名 URL。
subscription.past_due	无变化。整个宽限期内，下载始终可用。
subscription.on_hold / cancelled / expired	撤销授予。Dodo Payments 将停止发放新的预签名 URL。
subscription.paused	撤销授予。在订阅恢复之前，Dodo Payments 将停止发放新的预签名 URL。
subscription.plan_changed	撤销旧授予，并针对新方案的权益发放一个新授予。
refund.succeeded（一次性）	撤销授予。
Manual revoke	使用 revocation_reason: manual 撤销授予。

撤销会阻止 Dodo Payments 发放新的下载 URL，但不会使客户已经下载的副本失效。客户下载托管文件后，应将其视为已交付。

---

​

客户体验

​

购买确认

付款成功后，客户会收到一封包含下载链接和您配置的说明的电子邮件。

​

客户门户访问

在授予有效期间，客户可以从 Customer Portal 再次获取下载链接。该门户会按需生成新的预签名 URL，因此即使邮件中的链接过期，购买内容仍可正常使用。

客户可以从确认邮件中下载文件，也可以随时从 Customer Portal 中打开文件。

---

​

程序化管理文件

​

将文件上传到权益

要上传文件，请将其作为 multipart/form-data 发送到 file 字段中。可选的 filename 字段必须位于 file 部分之前，因为 Dodo Payments 会忽略其后发送的字段。如果没有 filename，Dodo Payments 会使用上传文件的名称。响应会返回新的 file_id。

TypeScript

import DodoPayments from 'dodopayments';
import { openAsBlob } from 'node:fs'; // Node.js 20 or later

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

// The SDK sends a FormData body as multipart/form-data. Append `filename` before `file`.
const form = new FormData();
form.append('filename', 'pro-bundle.zip');
form.append('file', await openAsBlob('./pro-bundle.zip'), 'pro-bundle.zip');

const { file_id } = await client.entitlements.files.upload('ent_files_abc', { body: form });
console.log(file_id);

​

列出授予并解析下载 URL

每个 Digital Files 授予都有一个 digital_product_delivery 对象，其中每个文件都包含一个新的预签名 URL。要读取这些 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`);
  }
}

​

从权益中移除文件

要解除文件关联，请传入其 file_id 和权益 ID：

await client.entitlements.files.delete('YOUR_FILE_ID', { id: 'ent_files_abc' });

---

​

重要注意事项

• **预签名 URL 很快就会过期。**授予 payload 和 webhook 事件中的下载 URL 有效期为 15 分钟。不要存储这些 URL。客户需要再次下载时，请获取新的 URL。
• **更新文件只会影响未来的购买。**替换或移除文件不会改变已经发放的下载内容。每个授予都会保留其创建时的权益配置，因此过去的客户仍可获取当时有效的版本。
• **退款不会使已下载的副本失效。**已经下载文件的客户会保留该副本。对于许可证受限媒体或限时访问等可撤销内容，请将 Digital Files 与 License Keys 搭配使用，并在运行时验证密钥。
• **对于敏感内容，建议使用带有独立身份验证的外部 URL。**Dodo Payments 的预签名 URL 有效期较短，但任何拥有该 URL 的人都可以在其过期前下载文件。将外部托管内容置于账户登录保护之后，可以让您获得更多控制权。

---

​

API 管理

Create Entitlement

创建一个 Digital Files 权益，可选择配置外部 URL 和说明。

Upload File

上传最大 500 MiB 的文件并将其附加到权益。

Delete File

从权益中解除文件关联。

List Grants

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

Update Entitlement

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

Revoke Grant

手动撤销客户的访问权限。

---

​

Webhooks

Digital file 交付和撤销会发送四个 entitlement_grant.* webhook 事件。对于 Digital Files 授予，payload 包含一个 digital_product_delivery 对象，其中包括解析后的文件列表、可选的 instructions 和可选的 external_url。每个文件都包含一个预签名的 download_url、filename、content_type、以字节为单位的 file_size，以及 expires_in，即 URL 过期前的秒数：

"digital_product_delivery": {
  "files": [
    {
      "file_id": "YOUR_FILE_ID",
      "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
}

---

​

Legacy Digital Product Delivery

在产品本身配置了旧版 digital_product_delivery 区块的产品，已自动迁移到 Digital Files 权益。通过旧版产品文件 API 上传的文件会被保留：这些文件仍可下载，并会与新上传的文件一起出现在授予 payload 中。权益的 digital_files 配置会在 legacy_file_ids 列表中跟踪这些文件。要添加文件、更改说明或替换外部 URL，请在 Entitlements 下编辑迁移后的 Digital Files 权益。

产品响应仍会包含旧版产品级字段（digital_product_delivery.external_url、digital_product_delivery.instructions）以保持向后兼容，但权益才是事实来源。

---

​

最佳实践

• **将下载视为一次性交付。**客户可能会分享或丢失链接，因此应基于客户下载的任何内容都归其所有这一前提来设计产品。
• **使用说明明确客户预期。**对于多文件捆绑包，请添加一行 instructions，说明应先安装什么或如何组合文件。
• **注意 500 MiB 上限。**对于多 GB 数据集或视频课程等较大的资源，请将其托管在外部，并使用 external_url 链接到这些资源，而不是上传它们。
• **与 License Keys 结合使用以实现可撤销访问。**要在退款后撤销客户对产品内功能的访问权限，请将 Digital Files 权益与 License Key 权益搭配使用，并在运行时验证密钥。
• **测试 Customer Portal 刷新流程。**确认客户一周后返回门户时，仍能获取有效的下载链接。邮件链接过期后，门户是主要的恢复途径。