Entrega de Produtos Digitais

Entregue automaticamente arquivos para download, links externos e instruções de download quando os clientes fizerem uma compra. Entrega de Produtos Digitais é o tipo de entitlement Digital Files. Os arquivos são emitidos com URLs de download presignadas a cada concessão e revogados quando o acesso é retirado.

​

Visão geral

Entrega de Produtos Digitais é o tipo de entitlement Digital Files. Você faz upload dos seus arquivos uma vez para um entitlement Digital Files, associa o entitlement a um produto, e Dodo Payments entrega links de download presignados a todos os clientes pagantes por e-mail e pelo portal do cliente.

O entitlement oferece suporte a:

• Uploads de arquivos hospedados: armazene arquivos em Dodo Payments e disponibilize-os por meio de URLs presignadas de curta duração.
• Links de download externos: vincule arquivos hospedados no Dropbox, Google Drive, S3 ou em qualquer URL.
• Instruções de download: texto livre exibido ao cliente na página do pedido e no e-mail de entrega.

Você pode combinar os três em um único entitlement.

​

Principais recursos

File Upload

Faça upload de arquivos (PDF, ZIP, imagens, vídeos etc.) de até 500 MiB. Os arquivos são transmitidos e armazenados de forma eficiente.

Multiple Files

Associe quantos arquivos forem necessários a um único entitlement.

External Links

Forneça links de download externos (Dropbox, Google Drive, URLs S3 assinadas) como alternativa ou complemento.

Presigned URLs

Os arquivos hospedados são disponibilizados por meio de URLs presignadas de curta duração. Cada URL de download expira automaticamente após aproximadamente 15 minutos.

---

​

Configurar a Entrega de Produtos Digitais

1. Open Entitlements

   Acesse Entitlements no seu painel do Dodo Payments e clique em + para criar um novo entitlement.

2. Choose Digital Files

   Selecione Entrega de Produtos Digitais como a integração.

3. Add files, links, and instructions

   Configure qualquer combinação de:

   • Arquivos: faça upload de um ou mais arquivos. Cada upload retorna um file_id que é acrescentado ao entitlement.
   • URL externa: um link HTTPS acessível publicamente, entregue junto aos arquivos hospedados.
   • Instruções: texto livre exibido ao cliente (por exemplo, “Descompacte e execute setup.sh”).

   
4. Save the entitlement

   Salve. O entitlement já está disponível para ser associado a qualquer produto.

​

Associar a produtos

Abra um produto, expanda Configurações avançadas → Entitlements e créditos e selecione seu entitlement Digital Files. O entitlement é entregue a cada compra bem-sucedida ou assinatura ativa vinculada a esse produto.

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

---

​

Como funciona a entrega

A entrega de Digital Files segue o ciclo de vida padrão de concessão:

Evento	Comportamento
payment.succeeded (uma vez)	Emite uma concessão. A concessão contém URLs de download presignadas válidas por aproximadamente 15 minutos; os clientes podem atualizá-las reabrindo o link no e-mail ou a página do portal do cliente.
subscription.active	Emite uma concessão. Os arquivos permanecem acessíveis enquanto a assinatura estiver ativa.
subscription.renewed	No-op. A mesma concessão continua válida; novas URLs presignadas são criadas a cada busca.
subscription.on_hold / cancelled / expired	Revoga a concessão. Novas URLs presignadas deixam de ser emitidas.
subscription.plan_changed	Revoga a concessão antiga e emite uma nova para o entitlement do novo plano.
refund.succeeded (uma vez)	Revoga a concessão.
Revogação manual	Revoga com revocation_reason: manual.

A revogação impede que Dodo Payments emita novas URLs de download, mas não invalida cópias que o cliente já tenha baixado. Considere os downloads de arquivos hospedados como “entregues após a leitura”.

---

​

Experiência do cliente

​

Confirmação da compra

Após uma transação bem-sucedida, o cliente recebe um e-mail com links de download e todas as instruções configuradas por você.

​

Customer Portal acesso

Os clientes podem buscar novamente os links de download a qualquer momento no Customer Portal. A página do portal gera novas URLs presignadas sob demanda, portanto a mesma compra continua funcionando mesmo depois que os links do e-mail expirarem.

Os clientes podem baixar arquivos diretamente dos e-mails de confirmação ou acessá-los a qualquer momento pelo portal.

---

​

Gerenciar arquivos programaticamente

​

Fazer upload de um arquivo para um entitlement

TypeScript

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"

​

Listar concessões 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('df_a4f6c1de', { id: 'ent_files_abc' });

---

​

Considerações importantes

• URLs presignadas expiram rapidamente. As URLs de download retornadas em payloads de concessão ou eventos de webhook são válidas por aproximadamente 15 minutos. Não as armazene; busque-as novamente quando o cliente precisar fazer outro download.
• A atualização de arquivos afeta apenas compras futuras. Substituir ou remover um arquivo não altera retroativamente os downloads já emitidos. Clientes antigos ainda podem buscar novamente a versão que estava vigente quando a concessão foi criada.
• Reembolsos não invalidam cópias baixadas. Um cliente que já baixou um arquivo mantém essa cópia. Para conteúdo revogável (mídia com licença restrita, acesso limitado por tempo), combine Digital Files com License Keys e valide em tempo de execução.
• Para conteúdo sensível, prefira URLs externas com sua própria autenticação. As URLs presignadas de Dodo Payments têm curta duração, mas não exigem autenticação durante esse período; qualquer pessoa com a URL pode fazer o download dentro dessa janela. Conteúdo hospedado externamente e protegido por conta oferece garantias mais fortes.

---

​

Gerenciamento por API

Create Entitlement

Crie um entitlement Digital Files com URL externa e instruções opcionais.

Upload File

Faça upload de um arquivo (até 500 MiB) e acrescente-o ao entitlement.

Delete File

Remova um arquivo do entitlement.

List Grants

Liste as concessões e leia as URLs de download resolvidas.

Update Entitlement

Atualize as instruções, a URL externa ou substitua arquivos.

Revoke Grant

Revogue manualmente o acesso de um cliente.

---

​

Webhooks

A entrega e a revogação de arquivos digitais disparam os quatro eventos de webhook entitlement_grant.*. Para concessões de Digital Files, o payload inclui um objeto digital_product_delivery com a lista de arquivos resolvida (URLs presignadas, nomes de arquivo e tamanhos), o instructions opcional e o external_url opcional.

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

---

​

Entrega de Produtos Digitais legada

Produtos configurados com o bloco digital_product_delivery antigo no próprio produto foram migrados automaticamente para um entitlement Digital Files. Os arquivos existentes enviados pela API legada de arquivos do produto são preservados; eles continuam disponíveis para download e aparecem nos payloads de concessão identificados com source: "legacy". Atualizações futuras (adicionar arquivos, alterar instruções ou substituir a URL externa) devem ser feitas editando o entitlement Digital Files migrado em Entitlements.

Os campos legados no nível do produto (digital_product_delivery.external_url, digital_product_delivery.instructions) continuam sendo preenchidos nas respostas do produto para compatibilidade retroativa, mas o entitlement será a fonte de verdade daqui em diante.

---

​

Práticas recomendadas

• Considere os downloads como uma única entrega. Os clientes podem compartilhar ou perder links, portanto desenvolva seu produto partindo do princípio de que tudo o que eles baixarem será deles.
• Use instruções para definir expectativas. Para pacotes com vários arquivos, adicione uma linha instructions explicando o que instalar primeiro ou como combinar os arquivos.
• Observe o limite de 500 MiB. Artefatos maiores (conjuntos de dados de vários GB, cursos em vídeo) devem ser hospedados externamente e vinculados por meio de external_url, em vez de serem enviados.
• Combine com License Keys para acesso revogável. Se precisar revogar o acesso a recursos dentro do produto após um reembolso, combine o entitlement Digital Files com um entitlement de License Key e valide a chave em tempo de execução.
• Teste o fluxo de atualização do portal do cliente. Confirme que um cliente consegue retornar ao portal uma semana depois e ainda obter um link de download funcional. Esse é o principal caminho de recuperação quando os links de e-mail expiram.