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

​

Prerrequisitos

• Una cuenta de comerciante de Dodo Payments.
• Tu clave API (DODO_PAYMENTS_API_KEY) y la clave secreta del webhook desde el panel de control. Consulta la guía de generación de claves API.
• Un punto final backend que pueda recibir webhooks.

​

Paso 1 — Crear un Derecho de Clave de Licencia en Modo Manual

• Dashboard
• API

1

Open Entitlements

Ve a Derechos en tu panel de control y haz clic en + para crear un nuevo derecho.

2

Choose License Key

Selecciona Clave de Licencia como la integración y dale un Nombre. El formulario expone estos campos:

• Modo de Cumplimiento — Automatic por defecto. Esta es la configuración que permite el cumplimiento manual; la cambiarás en el siguiente paso.
• Duración de la Licencia — cuánto tiempo se mantiene válida cada clave emitida, o Sin vencimiento.
• Límite de Activaciones — activaciones máximas por clave, o Ilimitado.
• Mensaje de Activación — mensaje opcional de cara al cliente que se muestra cuando activan la clave.

3

Set Fulfillment Mode to Manual

Abre el menú desplegable Fulfillment Mode y cámbialo de Automatic a Manual. Este es el ajuste que determina toda esta guía: sin él, las claves se generan y envían por correo electrónico automáticamente y no se crea ninguna concesión pendiente. Con Manual seleccionado, cada compra crea una concesión Pending que debes completar. Haz clic en Create Entitlement para guardar.

Crea el derecho con integration_config.fulfillment_mode configurado 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_...

​

Paso 2 — Adjuntar el Derecho a un Producto

​

Paso 3 — Detectar Concesiones Pendientes

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

​

O consulta la API de Listado de Concesiones

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`);
}

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

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 solicitud

​

Paso 5 — Manejar Errores y Reintentos

​

Verifica el Flujo

1. Compra el producto en modo de prueba (consulta las guías de pago).
2. Confirma que tu webhook recibió entitlement_grant.created con status: "pending" e integration_type: "license_key", o que la concesión aparece en la respuesta de List Grants con esos filtros.
3. Llama al punto final de cumplimiento con una clave de prueba.
4. Confirma que la respuesta muestra status: "delivered" con license_key poblado, el cliente recibe el correo electrónico con la clave y se activa entitlement_grant.delivered.
5. Compra el producto en modo de prueba (consulta las guías de checkout).
6. Confirma que tu webhook recibió entitlement_grant.created con status: "Pending" y integration_type: "license_key", o que la concesión aparece en la respuesta de List Grants con esos filtros.
7. Llama al endpoint de entrega con una clave de prueba.
8. Confirma que la respuesta muestra status: "Delivered" con un license_key completado, que el cliente recibe el correo electrónico con la clave y que se activa entitlement_grant.delivered.

​

Referencia de API Relacionada