Pular para o conteúdo principal

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.

As chaves de licença são o tipo de direito de Chave de Licença. Crie um direito de Chave de Licença uma vez com o limite de ativação, expiração e instruções desejadas, anexe a qualquer produto, e o Dodo Payments gera e entrega uma chave por compra ou assento de assinatura, automaticamente.

​
O que são Chaves de Licença?

Chaves de licença são tokens únicos que autorizam o acesso ao seu produto. Elas são ideais para:
  • Licenciamento de software: Aplicativos de desktop, plugins e CLIs
  • Controles por usuário: Limitar ativações por usuário ou dispositivo
  • Bens digitais: Restringir downloads, atualizações ou recursos premium
Dentro do Dodo Payments, as chaves de licença são gerenciadas através do sistema de Entitlements, o que significa que o ciclo de vida de cada chave (criação, expiração, revogação, reatribuição) é conduzido pelos mesmos eventos de pagamento e assinatura que seus outros produtos.

​
Criar um Direito de Chave de Licença

1

Open Entitlements

Vá para Entitlements no seu painel do Dodo Payments e clique em + para criar um novo direito.
2

Choose License Key

Selecione License Key como a integração. Configure como cada chave emitida deve se comportar:
  • Limite de Ativações: Máximo de ativações simultâneas por chave (por exemplo, 1 para usuário único, 5 para licenças de equipe, deixar em branco para ilimitado).
  • Duração: Quanto tempo a chave permanece válida após a emissão (por exemplo, 30 dias, 1 ano). Para chaves emitidas por assinatura, deixe em branco; as chaves permanecem válidas enquanto a assinatura estiver ativa.
  • Instruções de Ativação: Instruções orientadas ao cliente enviadas por e-mail com a chave. Exemplos: Paste the key in Settings → License ou Run: mycli activate <key>.
Formulário de direito de Chave de Licença com limite de ativação, duração e instruções
3

Save the entitlement

Salvar. O direito agora está disponível para ser anexado a qualquer produto.

​
Anexar a Produtos

Abra um produto, expanda Configurações Avançadas → Direitos & Créditos, e selecione seu direito de Chave de Licença. Um único produto pode entregar uma chave de licença junto com outros direitos (acesso ao Discord, downloads de arquivos, acesso ao repositório do GitHub, etc.) na mesma compra.
Painel de direitos do produto com Chave de Licença selecionada

​
Como as Chaves são Emitidas

A emissão de chaves segue o ciclo de concessão padrão:
EventoComportamento
payment.succeeded (uma vez)Gere uma chave por quantity comprado. A expiração da chave respeita a duração do direito.
subscription.activeGere uma chave por assinatura quantity (assento). A chave não expira; a validade está vinculada ao status da assinatura.
subscription.renewedNenhuma operação. As chaves existentes persistem.
subscription.on_holdDesabilite as chaves. Elas se reativam quando a assinatura sai de espera.
subscription.cancelled / expiredDesabilite as chaves permanentemente.
subscription.plan_changedDesabilite as antigas chaves; emita novas para o novo plano.
refund.succeeded (uma vez)Desabilite as chaves.
Revogação manual via API/painelDesabilite as chaves com revocation_reason: manual. Estas não são automaticamente reemitidas na renovação da assinatura.
Chave de licença desabilitada diretamenteRevogue a concessão com revocation_reason: license_key_disabled. Reabilitar a chave reativa a concessão automaticamente.

​
Comportamento de Quantidade

  • Produtos por assinatura emitem uma chave por assento (subscriptions.quantity).
  • Produtos únicos emitem uma chave por item de linha do carrinho (product_cart.quantity).
  • Concessões manuais de API emitem exatamente uma chave.

​
Ativação, Validação, Desativação

Os endpoints de ativação/validação/desativação da API são públicos e não requerem chave de API. Use-os diretamente de software desktop, CLIs, ou clientes baseados em navegador para verificar chaves em tempo de execução.
Endpoints Públicos: Os endpoints de ativação, desativação e validação de licença são públicos e não requerem uma chave de API. Chame-os diretamente dos seus aplicativos cliente sem expor suas credenciais de API.

​
Ativar uma licença

import DodoPayments from 'dodopayments';

// No API key needed for public license endpoints
const client = new DodoPayments();

const response = await client.licenses.activate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  name: 'Device Name',
});

console.log(response.id);

​
Validar uma licença

const response = await client.licenses.validate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});

console.log(response.valid);

​
Desativar uma instância de ativação

await client.licenses.deactivate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  license_key_instance_id: 'instance_abc123',
});

​
Gerenciar Chaves

Abra o direito de Chave de Licença no seu painel para ver todas as concessões (uma linha por chave do cliente) com data de entrega, contagem de ativações e uma ação de revogação. Cada detalhe da concessão revela a chave de licença subjacente, expiração, ativações usadas e o limite de ativações. Você também pode listar concessões programaticamente: 
const grants = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'delivered',
});

for (const grant of grants.items) {
  console.log(grant.license_key.key, grant.license_key.activations_used);
}

​
Importar Chaves de Licença Existentes via API

Já possui chaves de licença em outro sistema? Use a API Create License Key para importá-las no Dodo Payments. Isso permite migrar chaves existentes sem interromper seus clientes — eles continuam a ativar, validar e desativar usando as mesmas strings de chave sem reemitir.
As chaves de licença criadas ou atualizadas pela API não disparam notificações de e-mail para os clientes. Se precisar notificar os clientes sobre uma chave importada, faça isso separadamente em sua aplicação.
const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'prod_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});

​
Como chaves importadas diferem de chaves geradas automaticamente

CampoChave gerada automaticamenteChave importada
source"auto""import"
payment_idDefinido para o pagamento de origemnull (sem transação do Dodo Payments)
subscription_idDefinido se a chave foi emitida por uma assinaturanull a menos que explicitamente vinculado
Notificação por e-mail ao clienteEnviada na emissãoNão enviada — tratar separadamente
Use o campo source nas respostas GET /license_keys para distinguir inventário migrado de chaves emitidas organicamente ao reconciliar ou auditar.
Migrando de Polar.sh ou Lemon Squeezy? O dodo-migrate CLI automatiza importações em massa de produtos, clientes, descontos e chaves de licença com um único comando e mapeia IDs externos para IDs do Dodo automaticamente.

​
Chaves de Licença na URL de Retorno

Quando um cliente completa uma compra para um produto com um direito de Chave de Licença, a chave gerada é automaticamente anexada ao seu return_url como um parâmetro de consulta. Isso permite que você exiba a chave imediatamente na sua página de sucesso sem precisar fazer uma chamada adicional à API. 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
Se a compra gerar várias chaves (quantidade > 1), elas serão separadas por vírgulas: 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001,LK-002&email=customer%40example.com
Para assinaturas, subscription_id é usado em vez de payment_id: 
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com
Analise o parâmetro license_key na sua página de retorno para mostrar a chave imediatamente, melhorando a experiência pós-compra.

​
Gerenciamento de API

Ativação, desativação e validação são públicas; não requerem chave de API.

Activate License

Crie ou registre uma instância de ativação para uma chave de licença.

Deactivate License

Revogue uma ativação anterior para liberar capacidade.

Validate License

Verifique a autenticidade, status e restrições antes de conceder acesso.
Crie, liste, recupere e atualize registros individuais de chaves de licença. Use-os para importar chaves existentes ou buscar detalhes de uso.

Create License Key

Crie uma nova chave de licença ou importe uma existente.

List License Keys

Navegue por todas as chaves com detalhes de status e uso.

Get License Key

Recupere uma chave específica e seus metadados.

Update License Key

Modifique a expiração, limites de ativação, ou habilite/desabilite uma chave.
Gerencie o próprio direito de Chave de Licença: seu limite de ativação, duração e instruções.

Create Entitlement

Crie um direito de Chave de Licença.

Update Entitlement

Atualize a configuração do direito.

List Grants

Liste as chaves emitidas para um direito.

Revoke Grant

Revogue manualmente a chave de um cliente.

​
Webhooks

A entrega e revogação de chave de licença disparam os quatro eventos de webhook entitlement_grant.*. O payload de concessão inclui um objeto license_key populado com a chave, expiração, ativações usadas e limite. Os eventos legados license_key.* (license_key.created) continuam a disparar para o ciclo de vida do registro de chave de licença subjacente; veja a página de payload de webhook de Chave de Licença.
Para novas integrações, ouça entitlement_grant.delivered em vez de license_key.created. O evento de direito informa que a entrega está completa em todas as integrações no produto, não apenas a chave de licença.

​
Chaves de Licença Legadas

Os produtos criados com o flag mais antigo license_key_enabled foram automaticamente migrados para um direito de Chave de Licença. A migração é transparente: as chaves dos clientes existentes continuam funcionando inalteradas, os endpoints públicos /licenses/activate, /licenses/validate, /licenses/deactivate continuam funcionando, e os endpoints da API /license_keys/* continuam lendo e escrevendo no mesmo armazenamento de chaves.A seção de painel License Keys autônoma permanece disponível como uma lista plana de todas as chaves emitidas, útil para auditoria e pesquisa. A nova configuração (mudança de limites de ativação, durações ou instruções) deve ser feita editando o direito de Chave de Licença migrado sob Entitlements.

​
Melhores Práticas

  • Mantenha os limites de ativação claros: Escolha padrões sensatos (1 para aplicativos de um único usuário, 3–5 para licenças de equipe) e documente-os.
  • Forneça instruções de ativação precisas: Os clientes copiam e colam estas a partir do e-mail deles, portanto, caminhos e comandos exatos economizam tickets de suporte.
  • Valide chaves no lado do servidor: Para produtos conectados à rede, valide via /licenses/validate em vez de armazenar a ativação em cache localmente.
  • Use webhooks para revogação: Ouça entitlement_grant.revoked para desabilitar recursos do aplicativo imediatamente quando um cliente cancelar ou fizer reembolso.
  • Teste com assinaturas e compras únicas: O comportamento da chave de licença difere sutilmente entre os dois, então teste ambos antes de entrar em operação.
Last modified on May 14, 2026