Guia de Integração para Cumprimento Manual de Chaves de Licença

Este guia mostra como criar um sistema completo de fulfillment manual de chaves de licença. Em vez de o Dodo Payments gerar automaticamente uma chave após o pagamento, cada compra cria um grant Pending e aguarda que você forneça o valor da chave a partir do seu próprio sistema, de um fornecedor terceirizado ou de um pool finito de códigos. Ao final, você terá:

Um produto com uma autorização de Chave de Licença definida para cumprimento manual.
Um ouvinte de webhook que detecta quando um cliente está aguardando uma chave.
Uma chamada de cumprimento que entrega a chave e notifica o cliente automaticamente.

License Keys overview

O ciclo completo da chave de licença e a configuração fulfillment_mode.

Fulfill License Key Grant API

Referência da API para o endpoint que você chama para entregar uma chave.

Como Funciona

O cumprimento manual altera apenas a etapa de emissão. Ativação, validação, desativação, expiração e revogação funcionam exatamente como uma chave gerada automaticamente, uma vez entregue.

Pré-requisitos

Para seguir este guia, você precisará de:

Uma conta de comerciante do Dodo Payments.
Sua chave de API (DODO_PAYMENTS_API_KEY) e a chave secreta do webhook do painel de controle. Veja o guia de geração de chave de API.
Um endpoint de backend que possa receber webhooks.

Use https://test.dodopayments.com e credenciais de modo de teste durante a construção. Alterne para https://live.dodopayments.com e chaves ao vivo quando for para a produção.

Etapa 1 — Criar uma Autorização de Chave de Licença no Modo Manual

Uma autorização é uma definição reutilizável do que você entrega. Crie uma autorização de Chave de Licença e defina sua fulfillment_mode para manual.

Dashboard
API

Open Entitlements

Vá para Autorizations no seu painel e clique em + para criar uma nova autorização.

Choose License Key

Selecione Chave de Licença como a integração e dê um Nome. O formulário expõe esses campos:

Modo de Cumprimento — Automatic por padrão. Esta é a configuração que habilita o cumprimento manual; você a altera no próximo passo.
Duração da Licença — quanto tempo cada chave emitida permanece válida, ou Sem expiração.
Limite de Ativações — máximo de ativações por chave, ou Ilimitado.
Mensagem de Ativação — mensagem opcional voltada ao cliente exibida quando ele ativa a chave.

Formulário de novo entitlement de chave de licença com nome, modo de fulfillment, duração da licença, limite de ativações e mensagem de ativação

Set Fulfillment Mode to Manual

Abra o menu suspenso Fulfillment Mode e altere de Automatic para Manual. Essa é a configuração que orienta todo este guia — sem ela, as chaves são geradas e enviadas por e-mail automaticamente, e nenhum grant pendente é criado. Com Manual selecionado, cada compra cria um grant Pending para você processar. Clique em Create Entitlement para salvar.

Crie a autorização com integration_config.fulfillment_mode definida como manual.

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

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',
  },
});

console.log(entitlement.id); // ent_...

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

entitlement = 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",
    },
)

print(entitlement.id)

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"
    }
  }'

fulfillment_mode padrão é auto. Omitir, ou deixar uma autorização existente inalterada, mantém o comportamento automático. Somente autorizações explicitamente definidas para manual criam concessões pendentes.

Etapa 2 — Anexe a Autorização a um Produto

Abra o produto que deseja vender, expanda Configurações Avançadas → Autorizações e Créditos, e selecione a autorização de Chave de Licença que definiu como Manual na Etapa 1. Um único produto pode entregar essa chave de licença junto com outras autorizações na mesma compra.

Painel de autorizações do produto com Chave de Licença selecionada — Selecting the License Key entitlement in the product entitlements panel.

O modo de cumprimento é uma propriedade da autorização, não do produto. Porque você definiu como Manual na Etapa 1, todo produto a que essa autorização está vinculada cria concessões de chaves de licença pending na compra — não há nada extra para configurar aqui.

O modo de fulfillment é uma propriedade do entitlement, não do produto. Como você o definiu como Manual na Etapa 1, todo produto ao qual esse entitlement estiver associado criará grants de chave de licença Pending no momento da compra — não há nada adicional para configurar aqui.

Etapa 3 — Detectar Concessões Pendentes

Quando um cliente compra o produto, o Dodo Payments cria uma concessão em status pending sem chave anexada e dispara um webhook entitlement_grant.created. Este é o seu sinal de que um cliente está aguardando uma chave. Quando um cliente compra o produto, o Dodo Payments cria um grant com status Pending, sem nenhuma chave associada, e dispara um webhook entitlement_grant.created. Esse é o seu sinal de que um cliente está aguardando uma chave. Configure um endpoint de webhook (Desenvolvedor → Webhooks no painel) e aja sobre as concessões de chave de licença pendentes. A implementação segue a especificação Webhooks Padrão.

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!);

export async function POST(request: Request) {
  const rawBody = await request.text();
  const headers = {
    'webhook-id': request.headers.get('webhook-id') || '',
    'webhook-signature': request.headers.get('webhook-signature') || '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') || '',
  };

  await webhook.verify(rawBody, headers);
  const event = JSON.parse(rawBody);

  // A customer bought a manual-mode license key and is waiting for it.
  if (
    event.type === 'entitlement_grant.created' &&
    event.data.integration_type === 'license_key' &&
    event.data.status === 'pending'
  ) {
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!);

export async function POST(request: Request) {
  const rawBody = await request.text();
  const headers = {
    'webhook-id': request.headers.get('webhook-id') || '',
    'webhook-signature': request.headers.get('webhook-signature') || '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') || '',
  };

  await webhook.verify(rawBody, headers);
  const event = JSON.parse(rawBody);

  // A customer bought a manual-mode license key and is waiting for it.
  if (
    event.type === 'entitlement_grant.created' &&
    event.data.integration_type === 'license_key' &&
    event.data.status === 'Pending'
  ) {
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

Ou faça polling da API de Listagem de Concessões

Se preferir não depender de webhooks, liste as concessões para a autorização e filtre por integration_type e status: Se você preferir não depender de webhooks, liste as concessões para o direito de Chave de Licença e filtre por status. Toda concessão em um direito de Chave de Licença já é uma concessão de chave de licença, então nenhum filtro integration_type é necessário:

Node.js

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

for (const grant of pending.items) {
  console.log(`Grant ${grant.id} for customer ${grant.customer_id} needs a key`);
}

Node.js

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

for (const grant of pending.items) {
  console.log(`Grant ${grant.id} for customer ${grant.customer_id} needs a key`);
}

cURL

curl -G https://test.dodopayments.com/entitlements/ent_license_key_id/grants \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  --data-urlencode "status=Pending"

Etapa 4 — Entregar a Chave

Obtenha o valor da chave do seu próprio sistema, depois envie-o com o endpoint Cumprir Concessão de Chave de Licença. Isso requer sua chave de API secreta (permissão de Editor); não é um dos endpoints de licença pública.

async function fulfill(grantId: string, key: string) {
  const res = await fetch(
    `https://test.dodopayments.com/grants/${grantId}/license-key`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      },
      body: JSON.stringify({
        key,
        // Optional — fall back to the entitlement config when omitted
        activations_limit: 5,
        expires_at: '2027-05-01T00:00:00Z',
      }),
    },
  );

  if (!res.ok) {
    // See the status code table below for handling
    throw new Error(`Fulfillment failed: ${res.status}`);
  }

  return res.json(); // updated grant, now status: "delivered"
}

async function fulfill(grantId: string, key: string) {
  const res = await fetch(
    `https://test.dodopayments.com/grants/${grantId}/license-key`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      },
      body: JSON.stringify({
        key,
        // Optional — fall back to the entitlement config when omitted
        activations_limit: 5,
        expires_at: '2027-05-01T00:00:00Z',
      }),
    },
  );

  if (!res.ok) {
    // See the status code table below for handling
    throw new Error(`Fulfillment failed: ${res.status}`);
  }

  return res.json(); // updated grant, now status: "Delivered"
}

Campos de solicitação

string

obrigatório

A string da chave de licença a ser entregue ao cliente. Espaços em branco são removidos; um valor vazio ou apenas de espaço em branco é rejeitado.

integer

Limite de ativações por chave. Retoma a configuração da autorização quando omitido.

string

Expiração por chave (ISO 8601). Retoma a duração da configuração da autorização quando omitido. Para concessões emitidas por assinatura, a validade permanece vinculada à assinatura independentemente.

Com sucesso, a concessão avança para delivered, o cliente recebe automaticamente a chave (o mesmo e-mail que receberia sob cumprimento automático), e entitlement_grant.delivered dispara. Em caso de sucesso, o grant passa para Delivered, o cliente recebe a chave automaticamente (o mesmo e-mail que receberia no fulfillment automático), e os eventos de webhook license_key.created e entitlement_grant.delivered são disparados.

E-mail de chave de licença do cliente mostrando a chave, produto, limite de ativação, expiração e instruções de ativação — The license key email the customer receives once you fulfill the grant.

Você não precisa enviar a chave por e-mail você mesmo — a entrega acontece automaticamente quando a concessão é cumprida.

Etapa 5 — Lidando com Erros e Novas Tentativas

O endpoint valida a concessão antes de entregar algo. Trate essas respostas:

Status	Significado	O que fazer
`200`	Chave entregue, concessão agora é `delivered`.	Concluído.
`400`	Não é uma concessão de chave de licença, ou a chave está vazia/em branco.	Corrija a solicitação; não tente novamente como está.
`404`	Nenhuma concessão com esse ID para o seu negócio.	Verifique o `grant_id`.
`409`	Concessão não aguardando cumprimento (já entregue ou já possui uma chave), ou o valor da chave já existe.	Se já foi entregue, trate como sucesso. Se uma chave duplicada, forneça uma chave diferente.
`422`	Corpo da solicitação falhou na validação (e.g. `activations_limit < 1`).	Corrija o campo e tente novamente.

Status	Significado	O que fazer
`200`	Chave entregue; o grant agora está em `Delivered`.	Concluído.
`400`	Não é um grant de chave de licença, ou a chave está vazia/em branco.	Corrija a solicitação; não tente novamente como está.
`404`	Não há nenhum grant com esse ID para sua empresa.	Verifique o `grant_id`.
`409`	O grant não está aguardando fulfillment (já foi entregue ou já possui uma chave), ou o valor da chave já existe.	Se já tiver sido entregue, trate como sucesso. Se a chave for duplicada, forneça uma chave diferente.
`422`	O corpo da solicitação falhou na validação (por exemplo, `activations_limit < 1`).	Corrija o campo e tente novamente.

Verifique o Fluxo

Compre o produto em modo de teste (veja os guias de checkout).
Confirme se seu webhook recebeu entitlement_grant.created com status: "pending" e integration_type: "license_key", ou se a concessão aparece na resposta da Listagem de Concessões com esses filtros.
Chame o endpoint de cumprimento com uma chave de teste.
Confirme se a resposta mostra status: "delivered" com um license_key preenchido, o cliente recebe o e-mail da chave e entitlement_grant.delivered dispara.
Compre o produto no modo de teste (consulte os guias de checkout).
Confirme que seu webhook recebeu entitlement_grant.created com status: "Pending" e integration_type: "license_key", ou que o grant aparece na resposta de List Grants com esses filtros.
Chame o endpoint de fulfill com uma chave de teste.
Confirme que a resposta mostra status: "Delivered" com um license_key preenchido, que o cliente recebeu o e-mail com a chave e que entitlement_grant.delivered foi disparado.

Referência de API Relacionada

Create Entitlement

Crie a autorização de Chave de Licença com fulfillment_mode: manual.

List Grants

Filtre por integration_type e status para encontrar concessões pendentes.

Fulfill License Key Grant

Entregue o valor da chave e faça a transição da concessão para entregue.

Entitlement Grant Webhooks

Os eventos entitlement_grant.* que sinalizam concessões pendentes e entregues.

Create Entitlement

Crie o entitlement de License Key com fulfillment_mode: manual.

List Grants

Filtre por status e customer_id para encontrar grants pendentes.

Fulfill License Key Grant

Forneça o valor da chave e faça a transição do grant para o status delivered.

Entitlement Grant Webhooks

Os eventos entitlement_grant.* que sinalizam grants pendentes e entregues.

Integration Guides

Billing Deconstructions

Cookbooks

Guia de Integração para Cumprimento Manual de Chaves de Licença

License Keys overview

Fulfill License Key Grant API

Como Funciona

Pré-requisitos

Etapa 1 — Criar uma Autorização de Chave de Licença no Modo Manual

Etapa 2 — Anexe a Autorização a um Produto

Etapa 3 — Detectar Concessões Pendentes

Ou faça polling da API de Listagem de Concessões

Etapa 4 — Entregar a Chave

Campos de solicitação

Etapa 5 — Lidando com Erros e Novas Tentativas

Verifique o Fluxo

Referência de API Relacionada

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

License Keys overview

Fulfill License Key Grant API

​Como Funciona

​Pré-requisitos

​Etapa 1 — Criar uma Autorização de Chave de Licença no Modo Manual

​Etapa 2 — Anexe a Autorização a um Produto

​Etapa 3 — Detectar Concessões Pendentes

​Ou faça polling da API de Listagem de Concessões

​Etapa 4 — Entregar a Chave

​Campos de solicitação

​Etapa 5 — Lidando com Erros e Novas Tentativas

​Verifique o Fluxo

​Referência de API Relacionada

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Como Funciona

Pré-requisitos

Etapa 1 — Criar uma Autorização de Chave de Licença no Modo Manual

Etapa 2 — Anexe a Autorização a um Produto

Etapa 3 — Detectar Concessões Pendentes

Ou faça polling da API de Listagem de Concessões

Etapa 4 — Entregar a Chave

Campos de solicitação

Etapa 5 — Lidando com Erros e Novas Tentativas

Verifique o Fluxo

Referência de API Relacionada