> ## 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.

# 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

<CardGroup cols={2}>
  <Card title="File Upload" icon="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.
  </Card>

  <Card title="Multiple Files" icon="files">
    Associe quantos arquivos forem necessários a um único entitlement.
  </Card>

  <Card title="External Links" icon="link">
    Forneça links de download externos (Dropbox, Google Drive, URLs S3 assinadas) como alternativa ou complemento.
  </Card>

  <Card title="Presigned URLs" icon="lock">
    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.
  </Card>
</CardGroup>

***

## Configurar a Entrega de Produtos Digitais

<Steps>
  <Step title="Open Entitlements">
    Acesse **Entitlements** no seu painel do Dodo Payments e clique em **+** para criar um novo entitlement.
  </Step>

  <Step title="Choose Digital Files">
    Selecione **Entrega de Produtos Digitais** como a integração.
  </Step>

  <Step title="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").

    <Frame>
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/digital-files/create.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=33ad03277809d14585d247442c191462" alt="Digital Files entitlement with file upload, external URL, and instructions fields" style={{ maxHeight: '500px', width: 'auto' }} width="1669" height="989" data-path="images/entitlements/digital-files/create.png" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    Salve. O entitlement já está disponível para ser associado a qualquer produto.
  </Step>
</Steps>

## 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.

<Frame caption="Attaching the Digital Files entitlement to a product alongside other entitlements.">
  <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/attach-to-product.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=965ad78262791fa8dbb712b4fdf89538" alt="Product entitlements panel showing Digital Product Delivery selected" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1197" data-path="images/entitlements/attach-to-product.png" />
</Frame>

***

## Como funciona a entrega

A entrega de Digital Files segue o [ciclo de vida padrão de concessão](/features/entitlements/introduction#how-grants-work):

| 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`.                                                                                                                                                                  |

<Warning>
  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".
</Warning>

***

## 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ê.

<Frame>
  <img src="https://mintcdn.com/dodopayments/mOQO5ej_lx0yH9p-/images/digital-product-delivery/2.png?fit=max&auto=format&n=mOQO5ej_lx0yH9p-&q=85&s=54f5247f6d67fe5bb48736682995e23e" alt="Purchase confirmation email showing download links for digital products" style={{ maxHeight: '500px', width: 'auto' }} width="1920" height="1080" data-path="images/digital-product-delivery/2.png" />
</Frame>

### Customer Portal acesso

Os clientes podem buscar novamente os links de download a qualquer momento no [Customer Portal](/features/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.

<Frame>
  <img src="https://mintcdn.com/dodopayments/mOQO5ej_lx0yH9p-/images/digital-product-delivery/3.png?fit=max&auto=format&n=mOQO5ej_lx0yH9p-&q=85&s=490c6755474c1f00a93f7adde7dabb63" alt="Customer portal interface showing available digital products for download" style={{ maxHeight: '500px', width: 'auto' }} width="1920" height="1080" data-path="images/digital-product-delivery/3.png" />
</Frame>

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

***

## Gerenciar arquivos programaticamente

### Fazer upload de um arquivo para um entitlement

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  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',
  });
  ```

  ```bash cURL theme={null} theme={null}
  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"
  ```
</CodeGroup>

### Listar concessões e resolver URLs de download

```typescript theme={null} theme={null}
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

```typescript theme={null} theme={null}
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](/features/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

<CardGroup cols={2}>
  <Card title="Create Entitlement" icon="plus" href="/api-reference/entitlements/create-entitlement">
    Crie um entitlement Digital Files com URL externa e instruções opcionais.
  </Card>

  <Card title="Upload File" icon="upload" href="/api-reference/entitlements/upload-file">
    Faça upload de um arquivo (até 500 MiB) e acrescente-o ao entitlement.
  </Card>

  <Card title="Delete File" icon="trash" href="/api-reference/entitlements/delete-file">
    Remova um arquivo do entitlement.
  </Card>

  <Card title="List Grants" icon="users" href="/api-reference/entitlements/list-grants">
    Liste as concessões e leia as URLs de download resolvidas.
  </Card>

  <Card title="Update Entitlement" icon="pen" href="/api-reference/entitlements/update-entitlement">
    Atualize as instruções, a URL externa ou substitua arquivos.
  </Card>

  <Card title="Revoke Grant" icon="ban" href="/api-reference/entitlements/revoke-grant">
    Revogue manualmente o acesso de um cliente.
  </Card>
</CardGroup>

***

## Webhooks

A entrega e a revogação de arquivos digitais disparam os quatro [eventos de webhook `entitlement_grant.*`](/developer-resources/webhooks/intents/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.

```json theme={null} theme={null}
"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

<Note>
  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.
</Note>

***

## 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.