Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Le chiavi di licenza sono il tipo di diritto License Key. Crea un diritto License Key una volta con il limite di attivazione, la scadenza e le istruzioni che desideri, allegalo a qualsiasi prodotto e Dodo Payments genera e consegna automaticamente una chiave per acquisto o posto in abbonamento.

​
Cosa sono le chiavi di licenza?

Le chiavi di licenza sono token unici che autorizzano l’accesso al tuo prodotto. Sono ideali per:
  • Licenze software: App desktop, plugin e CLI
  • Controlli per utente: Limita le attivazioni per utente o dispositivo
  • Beni digitali: Regola download, aggiornamenti o funzionalità premium
All’interno di Dodo Payments, le chiavi di licenza sono gestite attraverso il sistema di Diritti, il che significa che il ciclo di vita di ogni chiave (creazione, scadenza, revoca, ri-concessione) è guidato dagli stessi eventi di pagamento e abbonamento come gli altri tuoi deliverable.

​
Crea un diritto di chiave di licenza

1

Open Entitlements

Vai su Diritti nel tuo dashboard Dodo Payments e fai clic su + per creare un nuovo diritto.
2

Choose License Key

Seleziona License Key come integrazione. Configura come si comporta ogni chiave emessa:
  • Limite di Attivazioni: Massimo di attivazioni simultanee per chiave (es., 1 per singolo utente, 5 per licenze di squadra, lascia vuoto per illimitate).
  • Durata: Quanto tempo la chiave rimane valida dopo l’emissione (es., 30 giorni, 1 anno). Per le chiavi emesse per abbonamento, lascia vuoto; le chiavi rimangono valide finché l’abbonamento è attivo.
  • Istruzioni di Attivazione: Istruzioni per i clienti inviate via email con la chiave. Esempi: Paste the key in Settings → License o Run: mycli activate <key>.
Modulo di diritto License Key con limite di attivazione, durata e istruzioni
3

Save the entitlement

Salva. Il diritto è ora disponibile per essere allegato a qualsiasi prodotto.

​
Allegare ai Prodotti

Apri un prodotto, espandi Impostazioni Avanzate → Diritti & Crediti, e seleziona il tuo diritto License Key. Un singolo prodotto può consegnare una chiave di licenza insieme ad altri diritti (accesso a Discord, download di file, accesso a repository GitHub, ecc.) nello stesso acquisto.
Pannello diritti del prodotto con License Key selezionato

​
Come vengono emesse le chiavi

L’emissione delle chiavi segue il ciclo di vita della concessione standard:
EventoComportamento
payment.succeeded (una tantum)Genera una chiave per quantity acquistata. La scadenza della chiave rispetta la durata del diritto.
subscription.activeGenera una chiave per abbonamento quantity (posto). La chiave non ha scadenza; la validità è legata allo stato dell’abbonamento.
subscription.renewedNo-op. Le chiavi esistenti persistono.
subscription.on_holdDisabilita le chiavi. Si riattivano quando l’abbonamento esce dalla sospensione.
subscription.cancelled / expiredDisabilita permanentemente le chiavi.
subscription.plan_changedDisabilita le vecchie chiavi; emette nuove per il nuovo piano.
refund.succeeded (una tantum)Disabilita le chiavi.
Revoca manuale via API/dashboardDisabilita le chiavi con revocation_reason: manual. Queste non sono ri-concesse automaticamente al rinnovo dell’abbonamento.
Chiave di licenza disabilitata direttamenteRevoca il diritto con revocation_reason: license_key_disabled. Riabilitazione della chiave riattiva il diritto automaticamente.

​
Comportamento della quantità

  • Prodotti in abbonamento rilasciano una chiave per posto (subscriptions.quantity).
  • Prodotti una tantum rilasciano una chiave per articolo nella riga del carrello (product_cart.quantity).
  • Concessioni API manuali rilasciano esattamente una chiave.

​
Attivazione, Validazione, Disattivazione

Gli endpoint API di attivazione/validazione/disattivazione sono pubblici e non richiedono una chiave API. Usali direttamente da software desktop, CLI o client basati su browser per verificare le chiavi durante l’esecuzione.
Endpoint Pubblici: Gli endpoint di attivazione, disattivazione e validazione delle licenze sono pubblici e non richiedono una chiave API. Chiamali direttamente dalle tue applicazioni client senza esporre le tue credenziali API.

​
Attivare una licenza

import DodoPayments from 'dodopayments';

// No API key needed for public license endpoints
const client = new DodoPayments();

const response = await client.licenses.activate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  name: 'Device Name',
});

console.log(response.id);

​
Validare una licenza

const response = await client.licenses.validate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});

console.log(response.valid);

​
Disattivare un’istanza di attivazione

await client.licenses.deactivate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  license_key_instance_id: 'instance_abc123',
});

​
Gestire le Chiavi

Apri il diritto License Key dal tuo dashboard per vedere ogni concessione (una riga per chiave cliente) con data di consegna, conteggio di attivazione, e un’azione di revoca. Ogni dettaglio della concessione evidenzia la chiave di licenza sottostante, la scadenza, le attivazioni utilizzate e il limite di attivazioni. Puoi anche elencare le concessioni programmaticamente: 
const grants = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'delivered',
});

for (const grant of grants.items) {
  console.log(grant.license_key.key, grant.license_key.activations_used);
}

​
Importare Chiavi di Licenza Esistenti tramite API

Hai già chiavi di licenza in un altro sistema? Usa l’API Crea License Key per importarle in Dodo Payments. Questo ti permette di migrare le chiavi esistenti senza interrompere i tuoi clienti — continuano ad attivare, validare, e disattivare contro le stesse stringhe di chiavi senza ri-emissione.
Le chiavi di licenza create o aggiornate tramite l’API non attivano notifiche email ai clienti. Se hai bisogno di notificare i clienti riguardo una chiave importata, gestiscilo separatamente nella tua applicazione.
const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'prod_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});

​
Come le chiavi importate differiscono dalle chiavi auto-generate

CampoChiave auto-generataChiave importata
source"auto""import"
payment_idImpostato sul pagamento originantenull (nessuna transazione Dodo Payments)
subscription_idImpostato se la chiave è stata emessa tramite un abbonamentonull a meno che non sia esplicitamente collegato
Notifica email al clienteInviata all’emissioneNon inviata — gestire separatamente
Usa il campo source nelle risposte GET /license_keys per distinguere l’inventario migrato dalle chiavi emesse organicamente quando si concilia o si effettua un controllo.
Migrazione da Polar.sh o Lemon Squeezy? La CLI dodo-migrate automatizza le importazioni in massa di prodotti, clienti, sconti e chiavi di licenza in un unico comando e mappa automaticamente gli ID esterni agli ID Dodo.

​
Chiavi di Licenza nell’URL di Ritorno

Quando un cliente completa un acquisto per un prodotto con un diritto di License Key, la chiave generata viene automaticamente aggiunta alla tua return_url come un parametro di query. Questo ti permette di visualizzare immediatamente la chiave sulla tua pagina di successo senza effettuare una chiamata API aggiuntiva. 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
Se l’acquisto genera più chiavi (quantità > 1), sono separate da virgole: 
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001,LK-002&email=customer%40example.com
Per gli abbonamenti, viene utilizzato subscription_id invece di payment_id: 
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com
Analizza il parametro license_key sulla tua pagina di ritorno per mostrare immediatamente la chiave, migliorando l’esperienza post-acquisto.

​
Gestione API

Attivazione, disattivazione e validazione sono pubblici; non è richiesta una chiave API.

Activate License

Crea o registra un’istanza di attivazione per una chiave di licenza.

Deactivate License

Revoca un’attivazione precedente per liberare capacità.

Validate License

Controlla l’autenticità, lo stato e i vincoli prima di concedere l’accesso.
Crea, elenca, recupera e aggiorna i record individuali delle chiavi di licenza. Usa questi per importare chiavi esistenti o recuperare i dettagli di utilizzo.

Create License Key

Crea una nuova chiave di licenza o importa una esistente.

List License Keys

Sfoglia tutte le chiavi con stato e dettagli di utilizzo.

Get License Key

Recupera una chiave specifica e i suoi metadati.

Update License Key

Modifica la scadenza, i limiti di attivazione o abilita/disabilita una chiave.
Gestire il diritto License Key stesso: il suo limite di attivazione, durata e istruzioni.

Create Entitlement

Crea un diritto License Key.

Update Entitlement

Aggiorna la configurazione del diritto.

List Grants

Elenca le chiavi emesse per un diritto.

Revoke Grant

Revoca manualmente la chiave di un cliente.

​
Webhooks

La consegna e la revoca delle chiavi di licenza attivano i quattro eventi webhook entitlement_grant.*. Il payload della concessione include un oggetto license_key popolato con la chiave, la scadenza, le attivazioni usate e il limite. Gli eventi legacy license_key.* (license_key.created) continuano a essere attivati per il ciclo di vita dei record delle chiavi di licenza sottostanti; vedi la pagina del payload webhook delle chiavi di licenza.
Per nuove integrazioni, ascolta entitlement_grant.delivered piuttosto che license_key.created. L’evento di diritto ti dice che la consegna è completa su tutte le integrazioni del prodotto, non solo chiave di licenza.

​
Chiavi di Licenza Legacy

I prodotti creati con la vecchia flag license_key_enabled sono stati automaticamente migrati a un diritto License Key. La migrazione è trasparente: le chiavi esistenti dei clienti continuano a funzionare inalterate, gli endpoint pubblici /licenses/activate, /licenses/validate, /licenses/deactivate continuano a funzionare, e gli endpoint API /license_keys/* continuano a leggere e scrivere nello stesso archivio chiavi.La sezione autonoma License Keys del dashboard rimane disponibile come un elenco piatto di ogni chiave emessa, utile per controllo e ricerca. La nuova configurazione (cambiando i limiti di attivazione, le durate o le istruzioni) deve essere fatta modificando il diritto License Key migrato sotto Diritti.

​
Migliori Pratiche

  • Mantieni chiari i limiti di attivazione: Scegli impostazioni predefinite sensate (1 per app a utente singolo, 3–5 per licenze di team) e documentali.
  • Fornisci istruzioni precise di attivazione: I clienti incollano queste dalla loro email, quindi percorsi e comandi esatti riducono i ticket di supporto.
  • Valida le chiavi lato server: Per prodotti connessi alla rete, valida tramite /licenses/validate piuttosto che memorizzare localmente l’attivazione in cache.
  • Usa webhooks per la revoca: Ascolta entitlement_grant.revoked per disabilitare immediatamente le funzionalità in-app quando un cliente annulla o rimborsa.
  • Testa con abbonamenti e una tantum: Il comportamento delle chiavi di licenza differisce leggermente tra i due, quindi testa entrambi prima di andare in produzione.
Last modified on May 14, 2026