Entrega de Produtos Digitais

​

Visão geral

• Uploads de arquivos hospedados: o Dodo Payments armazena seus arquivos e os disponibiliza por meio de URLs presigned de curta duração.
• Link de download externo: uma URL por entitlement que aponta para arquivos hospedados em outro local, como Dropbox, Google Drive ou S3.
• Instruções de download: texto livre exibido ao cliente na página do pedido e no email de entrega.

​

Principais recursos

​

Configurar o Digital Product Delivery

1

Open Entitlements

Acesse Entitlements no dashboard e clique em + para criar um entitlement.

2

Choose Digital Files

Selecione Digital Files e insira um Name para o entitlement.

3

Add Files, Links, and Instructions

Configure qualquer combinação destes campos:

• Upload files: faça upload de um ou mais arquivos. Cada upload retorna um file_id e adiciona o arquivo ao digital_file_ids do entitlement.
• External Download Link: uma URL, começando com http:// ou https://, que os clientes podem acessar. O Dodo Payments a entrega junto com os arquivos hospedados.
• Instructions: texto livre exibido ao cliente, por exemplo, “Descompacte e execute setup.sh.”

4

Save the Entitlement

Clique em Create Entitlement. Agora você pode associar o entitlement a qualquer produto.

​

Associar a produtos

​

Como funciona a entrega

​

Experiência do cliente

​

Confirmação da compra

​

Customer Portal acesso

​

Gerenciar arquivos programaticamente

​

Fazer upload de um arquivo para um entitlement

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);

curl -X POST "https://test.dodopayments.com/entitlements/ent_files_abc/files" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -F "filename=pro-bundle.zip" \
  -F "file=@./pro-bundle.zip"

​

Listar grants e resolver URLs de download

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`);
  }
}

​

Remover um arquivo de um entitlement

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

​

Considerações importantes

• URLs presigned expiram rapidamente. As URLs de download nos payloads de grants e nos eventos de webhook são válidas por 15 minutos. Não as armazene. Busque URLs novas quando o cliente precisar fazer o download novamente.
• A atualização dos arquivos afeta apenas compras futuras. Substituir ou remover um arquivo não altera downloads já emitidos. Cada grant mantém a configuração do entitlement existente no momento em que foi criado, portanto clientes antigos ainda podem obter a versão que estava disponível naquele momento.
• Reembolsos não invalidam cópias baixadas. Um cliente que já baixou um arquivo mantém essa cópia. Para conteúdo revogável, como mídia com licença restrita ou acesso limitado por tempo, combine Digital Files com License Keys e valide a chave em runtime.
• Para conteúdo sensível, prefira URLs externas com autenticação própria. As URLs presigned do Dodo Payments têm curta duração, mas qualquer pessoa com a URL pode baixar o arquivo até que ela expire. Conteúdo hospedado externamente e protegido por login de conta oferece mais controle.

​

Gerenciamento da API

​

Webhooks

"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
}

​

Digital Product Delivery legado

​

Práticas recomendadas

• Trate os downloads como entregas únicas. Os clientes podem compartilhar ou perder links, portanto projete seu produto partindo do princípio de que tudo o que eles baixarem será deles para manter.
• Use instruções para definir expectativas. Para pacotes com vários arquivos, adicione uma linha instructions que explique o que instalar primeiro ou como combinar os arquivos.
• Fique atento ao limite de 500 MiB. Hospede artefatos maiores, como conjuntos de dados de vários GB ou cursos em vídeo, externamente e vincule-os usando external_url em vez de fazer upload deles.
• Combine com License Keys para acesso revogável. Para revogar o acesso a recursos dentro do produto após um reembolso, combine o entitlement Digital Files com um entitlement License Key e valide a chave em runtime.
• Teste o fluxo de atualização do Customer Portal. Confirme que um cliente consegue retornar ao portal uma semana depois e ainda obter um link de download funcional. O portal é o principal caminho de recuperação quando os links de email expiram.