Chaves de Licença - Dodo Payments Documentation

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

Open Entitlements

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

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

Novo formulário de direitos de Chave de Licença com nome, modo de cumprimento, duração da licença, limite de ativações e mensagem de ativação

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:

Evento	Comportamento
`payment.succeeded` (uma vez)	Gere uma chave por `quantity` comprado. A expiração da chave respeita a duração do direito.
`subscription.active`	Gere uma chave por assinatura `quantity` (assento). A chave não expira; a validade está vinculada ao status da assinatura.
`subscription.renewed`	Nenhuma operação. As chaves existentes persistem.
`subscription.on_hold`	Desabilite as chaves. Elas se reativam quando a assinatura sai de espera.
`subscription.cancelled` / `expired`	Desabilite as chaves permanentemente.
`subscription.plan_changed`	Desabilite as antigas chaves; emita novas para o novo plano.
`refund.succeeded` (uma vez)	Desabilite as chaves.
Revogação manual via API/painel	Desabilite as chaves com `revocation_reason: manual`. Estas não são automaticamente reemitidas na renovação da assinatura.
Chave de licença desabilitada diretamente	Revogue 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.

Modo de cumprimento

Cada direito de Chave de Licença tem um fulfillment_mode que controla quem fornece a chave:

auto (padrão): Dodo Payments gera e envia automaticamente a chave por e-mail após pagamento ou assinatura. Este é o comportamento descrito acima e se aplica quando fulfillment_mode é omitido.
manual: A compra cria uma concessão pending sem chave, e você fornece cada valor de chave. Veja Cumprimento Manual abaixo.

Cumprimento Manual

Por padrão, o Dodo Payments gera e envia por e-mail uma chave de licença assim que um cliente paga. Com o cumprimento manual você fornece a chave: a compra cria uma concessão pending sem chave, notifica você e aguarda a submissão do valor da chave. Use-o quando as chaves vierem do seu próprio sistema, de um fornecedor terceirizado ou de um estoque finito de códigos pré-impressos.

Procurando uma construção passo a passo? Veja o Guia de Integração de Cumprimento Manual de Chave de Licença para um passo a passo completo desde a criação do produto até a entrega da chave.

Quando usar

A execução automática é o padrão adequado para a maioria das licenças de software. Escolha o cumprimento manual quando o Dodo Payments não puder gerar a chave por conta própria:

Traga suas próprias chaves: A chave é gerada por seu aplicativo, um produto de desktop ou seu próprio servidor de licenças.
Fornecedores terceiros: Você revende chaves emitidas por um fornecedor upstream (uma chave de jogo, uma credencial de API, uma plataforma parceira).
Inventário finito: Você distribui códigos de um pool pré-alocado e deseja atribuí-los um a um.
Revisão humana: Você quer verificar uma compra antes de liberar o acesso.

Habilitar cumprimento manual

Defina fulfillment_mode: "manual" na configuração de integração do direito da Chave de Licença:

const entitlement = await client.entitlements.create({
  name: 'Pro License (Manual)',
  integration_type: 'license_key',
  integration_config: {
    fulfillment_mode: 'manual',
    activations_limit: 5,
    duration_count: 1,
    duration_interval: 'Year',
  },
});

fulfillment_mode é compatível com versões anteriores. Direitos criados antes de essa configuração existir não têm fulfillment_mode e continuam a se comportar como auto. A mudança para manual só afeta concessões criadas após a alteração; chaves já entregues não são tocadas.

Encontrar concessões aguardando cumprimento

Quando um cliente compra um produto em modo manual, a concessão é criada em status pending sem chave e um webhook entitlement_grant.created é disparado com integration_type: "license_key" e status: "pending". Você pode reagir a esse webhook ou consultar o endpoint List Grants com os filtros integration_type e status:

const pending = await client.entitlements.grants.list('ent_license_key_id', {
  integration_type: 'license_key',
  status: 'pending',
});

Entregar a chave

Envie a chave com o endpoint Fulfill License Key Grant. A concessão passa para delivered e o cliente recebe automaticamente a chave — o mesmo e-mail que receberia na execução automática.

cURL

curl -X POST https://test.dodopayments.com/grants/grant_8VbC6JDZ/license-key \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "activations_limit": 5,
    "expires_at": "2027-05-01T00:00:00Z"
  }'

activations_limit e expires_at são opcionais e voltam à configuração do direito quando omitidos. Cada concessão pode ser cumprida uma vez; tentar cumprir novamente uma concessão já cumprida retorna 409 em vez de emitir uma segunda chave.

Você não precisa enviar a chave por e-mail — a entrega acontece automaticamente quando a concessão é cumprida. Isso difere de importar chaves via POST /license_keys, que intencionalmente não notifica o cliente.

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 a partir de software de 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 exigem chave de API. Chame-os diretamente de suas aplicações clientes 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 dashboard para ver cada concessão (uma linha por chave de 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, validade, 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á tem chaves de licença em outro sistema? Use a API Create License Key para importá-las para o Dodo Payments. Isso permite migrar chaves existentes sem interromper seus clientes — eles continuam a ativar, validar e desativar usando as mesmas strings de chaves sem reemissão.

Chaves de licença criadas ou atualizadas através da API não disparam notificações de e-mail para os clientes. Se precisar notificar os clientes sobre uma chave importada, cuide disso 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 as chaves diferem por fonte

Campo	Chave gerada automaticamente	Chave cumprida manualmente	Chave Importada
`source`	`"auto"`	`"manual"`	`"import"`
Origem	Gerada pelo Dodo Payments no pagamento	Fornecida por você contra uma concessão pendente	Criada/migrada via `POST /license_keys`
`payment_id`	Definida para o pagamento de origem	Resolvida da concessão ou de sua assinatura	`null` (sem transação do Dodo Payments)
`subscription_id`	Definido se emitido via uma assinatura	Definido se a concessão veio de uma assinatura	`null` a menos que explicitamente vinculado
Notificação de e-mail do cliente	Enviada na emissão	Enviada no cumprimento	Não enviada — gerenciar separadamente

Use o campo source em respostas GET /license_keys para distinguir inventário migrado e chaves cumpridas manualmente de chaves emitidas organicamente ao reconciliar ou auditar.

Migrando do Polar.sh ou Lemon Squeezy? O dodo-migrate CLI automatiza importações em massa de produtos, clientes, descontos e chaves de licença em um único comando e mapeia IDs externos para IDs do Dodo automaticamente.

Chaves de Licença na URL de Retorno

Quando um cliente conclui uma compra de um produto com direito a Chave de Licença, a chave gerada é automaticamente anexada à sua return_url como um parâmetro de consulta. Isso permite exibir a chave imediatamente na sua página de sucesso sem fazer uma chamada de API extra.

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

Lifecycle Operations (Public Endpoints)

Ativação, desativação e validação são públicas; não é necessária 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.

License Key Management

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.

Entitlement Management

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

Entrega e revogação de chave de licença disparam os quatro eventos entitlement_grant.* de webhook. A carga útil da concessão inclui um objeto license_key preenchido com a chave, validade, ativações usadas e limite. Os eventos legados license_key.* (license_key.created) continuam a ser acionados para o ciclo de vida do registro de chave de licença subjacente; veja a página de carga útil 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á concluída em todas as integrações no produto, não apenas na chave de licença.

Chaves de Licença Legadas

Produtos criados com a antiga flag license_key_enabled foram automaticamente migrados para um direito de Chave de Licença. A migração é transparente: as chaves dos clientes existentes continuam a funcionar inalteradas, os endpoints públicos /licenses/activate, /licenses/validate, /licenses/deactivate continuam a funcionar, e os endpoints da API /license_keys/* continuam a ler e a escrever na mesma loja de chaves.A seção autônoma Chaves de Licença no painel continua disponível como uma lista plana de todas as chaves emitidas, útil para auditoria e pesquisa. Nova configuração (alterando limites de ativação, durações ou instruções) deve ser feita editando o direito de Chave de Licença migrado em Direitos.

Melhores Práticas

Mantenha os limites de ativação claros: Escolha padrões sensatos (1 para aplicativos de usuário único, 3-5 para licenças de equipe) e documente-os.
Forneça instruções de ativação precisas: Os clientes copiam essas instruções de seus e-mails, então caminhos e comandos exatos economizam tickets de suporte.
Valide as chaves no lado do servidor: Para produtos conectados à rede, valide via /licenses/validate em vez de armazenar a ativação localmente.
Use webhooks para revogação: Ouça entitlement_grant.revoked para desativar funcionalidades no aplicativo imediatamente quando um cliente cancela ou solicita reembolso.
Teste com assinaturas e compras únicas: O comportamento da chave de licença difere ligeiramente entre os dois, então teste ambos antes de ir ao ar.

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

​Criar um Direito de Chave de Licença

​Anexar a Produtos

​Como as Chaves são Emitidas

​Comportamento de Quantidade

​Modo de cumprimento

​Cumprimento Manual

​Quando usar

​Habilitar cumprimento manual

​Encontrar concessões aguardando cumprimento

​Entregar a chave

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

​Ativar uma licença

​Validar uma licença

​Desativar uma instância de ativação

​Gerenciar Chaves

​Importar Chaves de Licença Existentes via API

​Como as chaves diferem por fonte

​Chaves de Licença na URL de Retorno

​Gerenciamento de API

Activate License

Deactivate License

Validate License

Create License Key

List License Keys

Get License Key

Update License Key

Create Entitlement

Update Entitlement

List Grants

Revoke Grant

​Webhooks

​Chaves de Licença Legadas

​Melhores Práticas

O que são Chaves de Licença?

Criar um Direito de Chave de Licença

Anexar a Produtos

Como as Chaves são Emitidas

Comportamento de Quantidade

Modo de cumprimento

Cumprimento Manual

Quando usar

Habilitar cumprimento manual

Encontrar concessões aguardando cumprimento

Entregar a chave

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

Ativar uma licença

Validar uma licença

Desativar uma instância de ativação

Gerenciar Chaves

Importar Chaves de Licença Existentes via API

Como as chaves diferem por fonte

Chaves de Licença na URL de Retorno

Gerenciamento de API

Webhooks

Chaves de Licença Legadas

Melhores Práticas