Chaves de Licença

​

O que são chaves de licença?

• Licenciamento de software: aplicativos para desktop, plugins e CLIs.
• Controles por assento: limite as ativações por usuário ou dispositivo.
• Bens digitais: controle o acesso a downloads, atualizações ou recursos premium.

​

Criar um Direito de Chave de Licença

1

Open Entitlements

Acesse Entitlements no dashboard e clique em + para criar um entitlement.

2

Choose License Key

Selecione License Keys, insira um Name e configure como cada chave emitida deve funcionar:

• Fulfillment Mode: Automatic (o padrão) gera e envia cada chave por email. Manual permite que você forneça cada chave. Consulte Manual Fulfillment.
• Activations Limit: o número máximo de ativações ativas por chave, por exemplo 1 para um único usuário ou 5 para uma licença de equipe. Selecione Unlimited para não definir um limite.
• License Length: por quanto tempo uma chave permanece válida após ser emitida, por exemplo, 30 dias ou 1 ano, ou No expiration. Para produtos de assinatura, escolha No expiration: as chaves emitidas para uma assinatura não expiram, e sua validade acompanha o status da assinatura.
• Activation Message: instruções opcionais voltadas ao cliente, com até 2.500 caracteres, incluídas no email que entrega a chave. Por exemplo: Paste the key in Settings → License ou Run: mycli activate <key>.

3

Save the Entitlement

Clique em Create Entitlement. Agora você pode associar o entitlement a qualquer produto.

​

Anexar a Produtos

​

Como as Chaves são Emitidas

​

Comportamento da quantidade

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

​

Fulfillment Mode

• auto (padrão, Automatic no dashboard): Dodo Payments gera e envia a chave por email no pagamento ou na assinatura. Esse é o comportamento mostrado na tabela acima e se aplica quando fulfillment_mode é omitido.
• manual (Manual no dashboard): cada unidade comprada cria uma concessão Pending sem chave, e você fornece cada valor de chave. Consulte Manual Fulfillment.

​

Manual Fulfillment

​

Quando usar

• Traga suas próprias chaves: seu aplicativo, produto para desktop ou servidor de licenças gera a chave.
• Fornecedores terceirizados: você revende chaves emitidas por um fornecedor upstream, como uma chave de jogo, uma credencial de API ou uma licença de plataforma parceira.
• Estoque finito: você distribui códigos de um conjunto pré-alocado e os atribui um por vez.
• Revisão humana: você quer verificar uma compra antes de liberar o acesso.

​

Ativar o fulfillment manual

// `client` is a DodoPayments instance created with your API key.
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',
  },
});

curl -X POST https://test.dodopayments.com/entitlements \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro License (Manual)",
    "integration_type": "license_key",
    "integration_config": {
      "fulfillment_mode": "manual",
      "activations_limit": 5,
      "duration_count": 1,
      "duration_interval": "Year"
    }
  }'

​

Encontrar concessões aguardando fulfillment

const pending = await client.customers.listEntitlementGrants('cus_abc123', {
  integration_type: 'license_key',
  status: 'Pending',
});

​

Entregar a chave

curl -X POST https://test.dodopayments.com/grants/entg_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"
  }'

​

Ativação, validação e desativação

​

Ativar uma licença

import DodoPayments from 'dodopayments';

// The license endpoints don't check the token, but the SDK requires a value.
// Never ship your secret API key in client software.
const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' });

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

console.log(response.id);

from dodopayments import DodoPayments

# The license endpoints don't check the token, but the SDK requires a value.
client = DodoPayments(bearer_token="public", environment="test_mode")

response = client.licenses.activate(
    license_key="PRO-AAAA-BBBB-CCCC-DDDD",
    name="Device Name",
)
print(response.id)

curl -X POST https://test.dodopayments.com/licenses/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "name": "Device Name"
  }'

​

Validar uma licença

// Uses the client from the activation example.
const response = await client.licenses.validate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});

console.log(response.valid);

curl -X POST https://test.dodopayments.com/licenses/validate \
  -H "Content-Type: application/json" \
  -d '{ "license_key": "PRO-AAAA-BBBB-CCCC-DDDD" }'

​

Desativar uma instância de ativação

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

​

Gerenciar chaves

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 pela API

const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'pdt_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});

​

Como as chaves diferem por origem

​

Chaves de licença na URL de retorno

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001%2CLK-002&email=customer%40example.com

https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com

​

Gerenciamento da API

​

Webhooks

​

Chaves de licença legadas

​

Práticas recomendadas

• Escolha limites de ativação claros: selecione padrões como 1 para aplicativos de usuário único ou 3–5 para licenças de equipe e documente-os para seus clientes.
• Escreva mensagens de ativação precisas: os clientes as copiam do email da chave de licença, portanto caminhos e comandos exatos evitam chamados ao suporte.
• Valide as chaves usando a API: para produtos conectados à rede, chame /licenses/validate em vez de depender de uma ativação armazenada localmente em cache.
• Use webhooks para revogação: trate entitlement_grant.revoked para desativar recursos no aplicativo quando um cliente cancelar ou receber um reembolso.
• Teste assinaturas e compras avulsas: o comportamento das chaves de licença é diferente entre os dois casos; por exemplo, chaves de assinatura não expiram. Teste ambos antes de entrar em produção.