Guía de Integración para el Cumplimiento Manual de Claves de Licencia

• Un producto con un derecho de Clave de Licencia configurado para cumplimiento manual.
• Un receptor de webhooks que detecta cuando un cliente está esperando una clave.
• Una llamada de cumplimiento que entrega la clave y notifica automáticamente al cliente.

​

Cómo Funciona

​

Requisitos previos

• Una cuenta de comerciante de Dodo Payments.
• Una API key, creada en Developer → API Keys y almacenada en DODO_PAYMENTS_API_KEY, y el secreto de firma de webhook de Developer → Webhooks, almacenado en DODO_PAYMENTS_WEBHOOK_KEY. Consulta la guía de generación de API keys.
• Un endpoint de backend que pueda recibir webhooks.

​

Paso 1 — Crea un entitlement de License Key en modo manual

• Dashboard
• API

1

Open Entitlements

Ve a Entitlements en el dashboard y haz clic en + para crear un entitlement.

2

Choose License Key

Selecciona License Keys e introduce un Name. El formulario contiene estos campos:

• Fulfillment Mode: Automatic de forma predeterminada. Esta es la configuración que habilita el cumplimiento manual, y la cambiarás en el siguiente paso.
• License Length: cuánto tiempo permanece válida cada clave emitida, o No expiration.
• Activations Limit: el número máximo de activaciones por clave, o Unlimited.
• Activation Message: un mensaje opcional dirigido al cliente que se muestra cuando este activa la clave y que se incluye en el correo electrónico de la clave de licencia.

3

Set Fulfillment Mode to Manual

Abre el menú desplegable Fulfillment Mode y cámbialo de Automatic a Manual. El resto de esta guía depende de esta configuración: sin ella, Dodo Payments genera y envía las claves automáticamente y no crea ningún grant pendiente. Con Manual seleccionado, cada compra crea un grant Pending que debes completar. Haz clic en Create Entitlement para guardar.

Crea el entitlement con integration_config.fulfillment_mode establecido en manual.

Node.js

Python

cURL

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

See all 19 lines

​

Paso 2 — Vincula el entitlement a un producto

​

Paso 3 — Detecta los grants pendientes

​

Escucha el webhook

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_PAYMENTS_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'
  ) {
    // queueLicenseKeyFulfillment is your own job queue, not part of the SDK.
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

​

O consulta la API List Grants

// Uses the client from Step 1.
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 -G https://test.dodopayments.com/entitlements/ent_license_key_id/grants \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  --data-urlencode "status=Pending"

​

Paso 4 — Entrega la clave

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

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

​

Campos de la solicitud

​

Paso 5 — Gestiona los errores y los reintentos

​

Verifica el flujo

1. Compra el producto en modo de prueba. Consulta las guías de checkout.
2. Confirma que tu webhook recibió entitlement_grant.created con status: "Pending" e integration_type: "license_key", o que el grant aparece en la respuesta de List Grants filtrada por status=Pending.
3. Llama al endpoint de cumplimiento con una clave de prueba.
4. Confirma que la respuesta muestra status: "Delivered" con un license_key rellenado, que el cliente recibe el correo electrónico con la clave y que se activa entitlement_grant.delivered.

​

Referencia de API relacionada