Guida all'integrazione per il rilascio manuale della chiave di licenza

• Un prodotto con un diritto alla chiave di licenza impostato per manual.
• Un listener webhook che rileva quando un cliente sta aspettando una chiave.
• Una chiamata di esecuzione che consegna la chiave e notifica automaticamente il cliente.

​

Come funziona

​

Prerequisiti

• Un account commerciante di Dodo Payments.
• La tua chiave API (DODO_PAYMENTS_API_KEY) e la chiave segreta del webhook dal pannello di controllo. Vedi la guida alla generazione della chiave API.
• Un endpoint backend che possa ricevere webhooks.

​

Passo 1 — Crea un Diritto alla Chiave di Licenza in Modalità Manuale

• Dashboard
• API

1

Open Entitlements

Vai a Diritti nel tuo pannello di controllo e clicca su + per creare un nuovo diritto.

2

Choose License Key

Seleziona Chiave di Licenza come integrazione e assegnale un Nome. Il formulario espone questi campi:

• Modalità di Rilascio — Automatic di default. Questa è l’impostazione che abilita il rilascio manuale; la cambi nel passo successivo.
• Durata della Licenza — quanto tempo rimane valida ciascuna chiave emessa o Nessuna scadenza.
• Limite di Attivazioni — attivazioni massime per chiave o Illimitato.
• Messaggio di Attivazione — messaggio opzionale rivolto al cliente mostrato quando attivano la chiave.

3

Set Fulfillment Mode to Manual

Apri il menu a discesa Modalità di Rilascio e cambialo da Automatico a Manuale. Questa è l’impostazione che guida tutta questa guida — senza di essa, le chiavi vengono generate e inviate tramite email automaticamente e non viene creato alcun grant in sospeso. Con Manuale selezionato, ogni acquisto crea un grant pending da soddisfare. Clicca su Crea Diritto per salvare.

Crea il diritto con integration_config.fulfillment_mode impostato su 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_...

​

Passo 2 — Collega il Diritto a un Prodotto

​

Passo 3 — Rileva Grants in Sospeso

​

Ascolta il webhook

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 l’API List Grants

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

​

Passo 4 — Consegna la Chiave

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

​

Campi della richiesta

​

Passo 5 — Gestisci Errori e Retry

​

Verifica il Flusso

1. Acquista il prodotto in modalità test (vedi le guide al checkout).
2. Conferma che il tuo webhook ha ricevuto entitlement_grant.created con status: "pending" e integration_type: "license_key", o che il grant appare nella risposta di List Grants con quei filtri.
3. Chiama l’endpoint fulfill con una chiave di test.
4. Conferma che la risposta mostri status: "delivered" con un license_key popolato, il cliente riceva l’email della chiave e venga attivato entitlement_grant.delivered.

​

Riferimento API correlato