> ## 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.
# Introdução
> Entregue automaticamente chaves de licença, arquivos para download e acesso a plataformas como Discord, GitHub, Telegram, Framer e Notion quando os clientes pagam.
Entitlements transformam um pagamento bem-sucedido ou assinatura ativa em acesso real: uma chave de licença na caixa de entrada do seu cliente, um papel do Discord, um repositório GitHub, um modelo Notion, um link de remix de Framer, um convite para chat no Telegram ou um pacote de arquivos para download. O Dodo Payments emite, rastreia e revoga esse acesso automaticamente conforme o ciclo de pagamento muda.
## O que são Entitlements?
Um **entitlement** é uma definição reutilizável de algo que você entrega a um cliente: uma chave de licença Pro, um papel "Patrons" no Discord, acesso ao seu repositório privado no GitHub, um pacote de e-books para download. Você anexa entitlements a produtos, e o Dodo Payments cuida do resto.
Quando um cliente compra o produto, o Dodo Payments cria uma **grant**, uma emissão única desse entitlement para o cliente. As grants passam por um pequeno conjunto de status: `pending` enquanto a entrega está em andamento, `delivered` quando o cliente tem acesso, `failed` se a entrega não puder ser concluída, e `revoked` quando o acesso é retirado.
Entitlements controlam o **fulfillment** (o cliente tem acesso?). Créditos controlam o **consumo** (quanto eles podem usar?). Ambos podem ser anexados ao mesmo produto. Veja [Faturamento Baseado em Créditos](/features/credit-based-billing) para créditos.
## Integrações Disponíveis
O Dodo Payments entrega cada entitlement por meio de uma integração dedicada. Escolha a integração que corresponde ao que você vende.
Gere chaves de licença únicas com limites de ativação e expiração. Ideal para softwares, plugins e CLIs.
Entregue arquivos para download (e-books, templates, mídias) com URLs de download pré-assinadas e instruções opcionais.
Conceda a um cliente um papel no seu servidor Discord quando ele comprar. Revogue automaticamente no cancelamento.
Adicione clientes como colaboradores a um repositório privado no nível de permissão que você escolher.
Adicione clientes a um chat ou canal privado no Telegram após a compra.
Desbloqueie um link de remix de template Framer para clientes pagantes.
Duplique um template do Notion no espaço de trabalho do cliente na compra.
***
## Como as Grants Funcionam
As grants são impulsionadas pelos mesmos eventos de pagamento e assinatura que você já recebe como webhooks. Você não precisa chamar a API de grant para cada compra. O Dodo Payments cria e revoga grants automaticamente com base no ciclo de pagamento subjacente.
### Ciclo de Vida da Grant
Uma grant é criada quando um pagamento é concluído ou uma assinatura se torna ativa. Chaves de licença vão direto para `delivered`. Todas as outras integrações começam em `pending`. Integrações baseadas em OAuth (Discord, GitHub, Notion) incluem um `oauth_url` que o cliente deve visitar para completar o consentimento. Integrações diretas de plataforma (Telegram, Framer, Arquivos Digitais) permanecem em `pending` apenas brevemente enquanto a entrega é provisionada, então transitam para `delivered`.
Uma vez que a entrega é concluída (chave de licença gerada, papel atribuído, acesso ao repositório concedido, links de arquivos resolvidos, OAuth concluído), a grant se move para `delivered` e `delivered_at` é definido.
Se a chamada de integração retornar um erro não-retryable (token OAuth revogado, permissão negada, arquivo não existe mais), a grant se move para `failed`. Os campos `error_code` e `error_message` capturam o motivo.
Quando o acesso é retirado (assinatura cancelada, reembolso emitido ou revogação iniciada pelo comerciante), a grant se move para `revoked`. O campo `revocation_reason` registra o gatilho.
### Comportamento da Grant por Evento
| Evento | Comportamento |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (pagamento único) | Emita uma grant por entitlement anexado. |
| `payment.succeeded` (pagamento vinculado à assinatura) | Sem ação. Grants são impulsionadas pelo evento de assinatura abaixo. |
| `subscription.active` | Emita grants para quaisquer entitlements anexados que ainda não tenham uma. Re-grante quaisquer grants previamente revogadas para a mesma assinatura. |
| `subscription.renewed` | Sem ação. Grants existentes persistem em renovações. |
| `subscription.on_hold` | Revogue todas as grants entregues e pendentes. `revocation_reason: subscription_on_hold`. |
| `subscription.cancelled` | Revogue tudo. `revocation_reason: subscription_cancelled`. |
| `subscription.expired` | Revogue tudo. `revocation_reason: subscription_expired`. |
| `subscription.plan_changed` | Revogue todas as grants atuais, então emita grants para os entitlements do novo plano. `revocation_reason: plan_changed`. |
| `refund.succeeded` (pagamento único) | Revogue grants para esse pagamento. `revocation_reason: refund`. |
| Revogação manual de API | Revogue com `revocation_reason: manual`. Revogações manuais não são automaticamente re-grantadas na renovação da assinatura. |
| Chave de licença desativada | Para grants de chave de licença, desativar a chave subjacente revoga a grant com `revocation_reason: license_key_disabled`. A grant é reativada automaticamente se a chave for reativada. |
| Desvio de plataforma detectado | Se o lado da plataforma de uma integração sair de sincronia (um papel no Discord removido manualmente, o App do GitHub perdendo acesso ao repositório ou um passe de reconciliação detectando um alvo ausente), a grant é revogada com `revocation_reason: platform_external`. Não é automaticamente re-grantada na renovação da assinatura até que o problema subjacente da plataforma seja resolvido. |
Grants impulsionadas por assinaturas são idempotentes por `(entitlement, customer, subscription)`; renovações e reativações não criam grants duplicadas. Grants de uma única vez são idempotentes por `(entitlement, customer, payment)`.
***
## Crie seu primeiro entitlement
Vá para **Entitlements** no seu painel do Dodo Payments e clique em **+** para criar um novo entitlement.
Escolha o tipo de integração: Chave de Licença, Arquivos Digitais, Discord, GitHub, Telegram, Framer ou Notion. Para integrações de plataforma, conecte sua conta primeiro, se ainda não tiver feito isso.
Preencha os campos específicos da integração. Por exemplo, GitHub pede um repositório e um nível de permissão; Discord pede um servidor e um papel opcional; Chave de Licença pede limites de ativação e expiração.
Salve o entitlement. Você agora pode anexá-lo a qualquer produto.
## Anexe Entitlements a Produtos
Abra um produto, expanda **Configurações Avançadas → Entitlements & Créditos**, e selecione os entitlements que devem ser entregues quando o produto for comprado. Um único produto pode entregar múltiplos entitlements de uma vez. Por exemplo, um plano Pro pode incluir uma chave de licença, acesso ao GitHub e um papel no Discord.
***
## Experiência do Cliente
### E-mail e portal do cliente
Os clientes recebem um e-mail de entrega após a compra contendo a chave de licença, links para download, links de convite OAuth ou convite para plataforma, conforme aplicável aos entitlements do produto. Os mesmos detalhes permanecem disponíveis indefinidamente no [Portal do Cliente](/features/customer-portal) sob o histórico de pedidos.
### Entrega baseada em OAuth
O acesso ao Discord, GitHub e Notion para assinantes exige que o cliente autorize o Dodo Payments a conceder acesso a eles. Essas grants permanecem em status `pending` até que o cliente complete o fluxo OAuth usando o link do e-mail ou do portal do cliente. Uma vez que autorizam, a grant se move para `delivered` e o acesso à plataforma é provisionado imediatamente.
### Revogação
Grants revogados são removidos no nível da plataforma: o papel do Discord é removido, o colaborador do GitHub é removido, a chave de licença é desativada. Os clientes veem a mudança refletida no portal do cliente.
Para Arquivos Digitais, a revogação remove o acesso às URLs pré-assinadas a partir de então, mas não invalida cópias que o cliente já baixou. Planeje o conteúdo do plano de acordo.
***
## Gerenciar Grants
Abra qualquer entitlement no painel para ver suas grants. O painel de detalhes da grant mostra o total de grants, filtros de status, informações do cliente, datas de entrega e uma ação de revogação.
Você também pode gerenciar grants programaticamente:
```typescript TypeScript theme={null} theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
});
// List grants for an entitlement
const grants = await client.entitlements.grants.list('ent_abc123', {
status: 'delivered',
});
// Revoke a single grant
await client.entitlements.grants.revoke('grant_xyz789', {
path_id: 'ent_abc123',
});
```
```python Python theme={null} theme={null}
client.entitlements.grants.list(
"ent_abc123",
status="delivered",
)
client.entitlements.grants.revoke(
"grant_xyz789",
path_id="ent_abc123",
)
```
```go Go theme={null} theme={null}
grants, _ := client.Entitlements.Grants.List(
ctx, "ent_abc123",
dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
)
_, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")
```
***
## Gerenciamento via API
Crie um novo entitlement de qualquer tipo de integração.
Liste entitlements com filtro por tipo de integração.
Recupere um entitlement e sua configuração resolvida.
Atualize o nome, descrição ou configuração de integração.
Exclua um entitlement suavemente; grants existentes não são afetadas.
Carregue um arquivo para um entitlement de Arquivos Digitais (até 100 MB).
Liste todas as grants de um entitlement com filtros de status e cliente.
Revogue manualmente uma única grant.
***
## Webhooks
O Dodo Payments dispara quatro eventos de webhook para o ciclo de vida da grant. Assine esses eventos para manter seu aplicativo em sincronia com o que cada cliente pode acessar.
| Evento | Dispara quando |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `entitlement_grant.created` | Uma nova grant é criada. Grants de chave de licença chegam `delivered`; toda outra integração chega `pending` e transita para `delivered` uma vez que a chamada à plataforma seja bem-sucedida (ou, para integrações baseadas em OAuth, uma vez que o cliente autorize). |
| `entitlement_grant.delivered` | A grant transita para entregue. O cliente agora tem acesso. |
| `entitlement_grant.failed` | A grant não pôde ser entregue. Inspecione `error_code` e `error_message`. |
| `entitlement_grant.revoked` | O acesso foi retirado. Inspecione `revocation_reason`. |
Veja o esquema completo de payload, eventos de exemplo e referência `revocation_reason`.
***
## Melhores Práticas
* **Use um entitlement por canal de entrega.** Não compartilhe um único entitlement do Discord por produtos com diferentes intenções de papel; crie um por papel para uma revogação limpa.
* **Teste primeiro no modo de teste.** Crie o entitlement, anexe-o a um produto de teste, realize um checkout e veja a grant transitar por `pending → delivered`. Confirme que o cancelamento da assinatura de teste revoga a grant.
* **Ouça `entitlement_grant.delivered`, não `payment.succeeded`.** Um pagamento pode ter sucesso antes de o fulfillment terminar (especialmente para fluxos OAuth). Aguarde o evento entregue antes de desbloquear recursos dependentes em seus próprios sistemas.
* **Considere `entitlement_grant.failed` como acionável.** Uma grant falhada significa que um cliente pagou mas não obteve acesso. Exiba isso para sua equipe de suporte ou ative um regrant.
* **Mapeie `revocation_reason` para seus fluxos de retenção.** Uma revogação `subscription_on_hold` é recuperável (o cliente pode atualizar seu cartão). Uma revogação `manual` é intencional. Trate-os de forma diferente nas comunicações com clientes.