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

Questa guida spiega come costruire un sistema di rilascio manuale della chiave di licenza dall’inizio alla fine. Invece che Dodo Payments generi automaticamente una chiave al pagamento, ogni acquisto crea un grant pending e attende che tu fornisca il valore della chiave dal tuo sistema, un fornitore terzo o da un pool finito di codici. Alla fine avrai:

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.

License Keys overview

Il ciclo di vita completo della chiave di licenza e l’impostazione fulfillment_mode.

Fulfill License Key Grant API

Riferimento API per l’endpoint che chiami per consegnare una chiave.

Come funziona

Il rilascio manuale cambia solo il passaggio di emissione. Attivazione, validazione, disattivazione, scadenza e revoca funzionano esattamente come una chiave generata automaticamente una volta consegnata.

Prerequisiti

Per seguire questa guida avrai bisogno di:

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.

Usa https://test.dodopayments.com e credenziali in modalità test durante la costruzione. Passa a https://live.dodopayments.com e chiavi live quando vai in produzione.

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

Un diritto è una definizione riutilizzabile di ciò che consegni. Crea un diritto alla chiave di licenza e imposta il suo fulfillment_mode su manual.

Dashboard
API

Open Entitlements

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

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.

Nuovo modulo di diritto alla chiave di licenza con nome, modalità di rilascio, durata della licenza, limite di attivazioni e messaggio di attivazione

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.

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 predefinito su auto. Omesso, o lasciando un diritto esistente invariato, mantiene il comportamento automatico. Solo i diritti esplicitamente impostati su manual creano grant in sospeso.

Passo 2 — Collega il Diritto a un Prodotto

Apri il prodotto che vuoi vendere, espandi Impostazioni Avanzate → Diritti e Crediti, e seleziona il diritto alla Chiave di Licenza che hai impostato su Manuale nel Passo 1. Un singolo prodotto può consegnare questa chiave di licenza insieme ad altri diritti nello stesso acquisto.

Pannello dei diritti del prodotto con Chiave di Licenza selezionata — Selecting the License Key entitlement in the product entitlements panel.

La modalità di rilascio è una proprietà del diritto, non del prodotto. Poiché l’hai impostato su Manuale nel Passo 1, ogni prodotto a cui è collegato questo diritto crea grant di chiavi di licenza pending all’acquisto — non c’è nulla di extra da configurare qui.

Se non hai ancora un prodotto, creane uno prima (una tantum o abbonamento). Vedi la Guida all’Integrazione dei Pagamenti Una Tantum per vendere il prodotto al checkout.

Passo 3 — Rileva Grants in Sospeso

Quando un cliente acquista il prodotto, Dodo Payments crea un grant in stato pending con nessuna chiave allegata e attiva un webhook entitlement_grant.created. Questo è il tuo segnale che un cliente è in attesa di una chiave.

Ascolta il webhook

Configura un endpoint webhook (Sviluppatore → Webhooks nel pannello di controllo) e agisci sui grants di chiavi di licenza in attesa. L’implementazione segue la specifica Standard Webhooks.

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

Il payload del grant trasporta integration_type: "license_key", così puoi riconoscere un grant di chiavi di licenza senza una ricerca aggiuntiva. Consulta il riferimento al webhook di Entitlement Grant per il payload completo.

O consulta l’API List Grants

Se preferisci non fare affidamento sui webhooks, elenca i grants per il diritto e filtra per integration_type e status: Se preferisci non affidarti ai webhook, elenca le concessioni per la tua idoneità di License Key e filtra per status. Ogni concessione su un’idoneità di License Key è già una concessione di tipo license-key, quindi non è necessario alcun filtro integration_type:

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"

Passo 4 — Consegna la Chiave

Ottieni il valore della chiave dal tuo sistema, quindi invialo all’endpoint Fulfill License Key Grant. Questo richiede la tua chiave API segreta (permesso Editor); non è uno degli endpoint di licenza pubblici.

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

Campi della richiesta

key

string

obbligatorio

La stringa della chiave di licenza da consegnare al cliente. Gli spazi bianchi vengono rimossi; un valore vuoto o composto solo da spazi bianchi viene rifiutato.

activations_limit

integer

Limite di attivazione per chiave. Torna alla configurazione del diritto quando è omesso.

expires_at

string

Scadenza per chiave (ISO 8601). Torna alla durata della configurazione del diritto quando è omesso. Per grants emessi da abbonamenti, la validità rimane legata all’abbonamento indipendentemente.

Al successo, il grant passa a delivered, il cliente riceve automaticamente la chiave (la stessa email che riceverebbero sotto rilascio automatico), e viene attivato entitlement_grant.delivered. Il cliente riceve un’email con la chiave di licenza, il prodotto, il limite di attivazione, la scadenza e le tue istruzioni per l’attivazione:

Email del cliente con chiave di licenza che mostra la chiave, il prodotto, il limite di attivazione, la scadenza e le istruzioni per l'attivazione — The license key email the customer receives once you fulfill the grant.

Non è necessario inviare l’email della chiave da solo — la consegna avviene automaticamente quando il grant è soddisfatto.

Passo 5 — Gestisci Errori e Retry

L’endpoint valida il grant prima di consegnare qualsiasi cosa. Gestisci queste risposte:

Stato	Significato	Cosa fare
`200`	Chiave consegnata, grant ora `delivered`.	Fatto.
`400`	Non è un grant di chiavi di licenza, o la chiave è vuota/bin bianca.	Correggi la richiesta; non riprovare così com’è.
`404`	Nessun grant con quell’ID per la tua azienda.	Verifica `grant_id`.
`409`	Grant non in attesa di rilascio (già consegnato o ha già una chiave), o il valore della chiave esiste già.	Se già consegnato, trattalo come successo. Se chiave duplicata, fornisci una chiave diversa.
`422`	Il corpo della richiesta ha fallito la validazione (e.g. `activations_limit < 1`).	Correggi il campo e riprova.

Il rilascio è sicuro da riprovare su errori transitori (timeout, 5xx). Ogni grant può essere soddisfatto solo una volta, quindi un retry dopo una chiamata di successo ma non riconosciuta restituisce 409 piuttosto che emettere una seconda chiave o inviare un’email duplicata. Usa il grant id come chiave di idempotenza.

Verifica il Flusso

Acquista il prodotto in modalità test (vedi le guide al checkout).
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.
Chiama l’endpoint fulfill con una chiave di test.
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.

Una volta consegnato, il cliente può attivare e convalidare la chiave contro gli endpoint di licenza pubblici esattamente come una chiave generata automaticamente.

Riferimento API correlato

Create Entitlement

Crea il diritto alla chiave di licenza con fulfillment_mode: manual.

List Grants

Filtra per integration_type e status per trovare grants in sospeso.

Fulfill License Key Grant

Consegna il valore della chiave e passa il grant a consegnato.

Entitlement Grant Webhooks

Gli eventi entitlement_grant.* che segnalano grants in sospeso e consegnati.

Create Entitlement

Create the License Key entitlement with fulfillment_mode: manual.

List Grants

Filter by integration_type and status to find pending grants.

Fulfill License Key Grant

Deliver the key value and transition the grant to delivered.

Entitlement Grant Webhooks

The entitlement_grant.* events that signal pending and delivered grants.

Integration Guides

Billing Deconstructions

Cookbooks

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

License Keys overview

Fulfill License Key Grant API

Come funziona

Prerequisiti

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

Passo 2 — Collega il Diritto a un Prodotto

Passo 3 — Rileva Grants in Sospeso

Ascolta il webhook

O consulta l’API List Grants

Passo 4 — Consegna la Chiave

Campi della richiesta

Passo 5 — Gestisci Errori e Retry

Verifica il Flusso

Riferimento API correlato

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

​Come funziona

​Prerequisiti

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

​Passo 2 — Collega il Diritto a un Prodotto

​Passo 3 — Rileva Grants in Sospeso

​Ascolta il webhook

​O consulta l’API List Grants

​Passo 4 — Consegna la Chiave

​Campi della richiesta

​Passo 5 — Gestisci Errori e Retry

​Verifica il Flusso

​Riferimento API correlato

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Come funziona

Prerequisiti

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

Passo 2 — Collega il Diritto a un Prodotto

Passo 3 — Rileva Grants in Sospeso

Ascolta il webhook

O consulta l’API List Grants

Passo 4 — Consegna la Chiave

Campi della richiesta

Passo 5 — Gestisci Errori e Retry

Verifica il Flusso

Riferimento API correlato