> ## 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.
# Introduzione
> Fornisci automaticamente chiavi di licenza, file scaricabili, flag delle funzionalità e accesso a piattaforme come Discord, GitHub, Telegram, Framer e Notion quando i clienti pagano.
Le autorizzazioni trasformano un pagamento avvenuto o un abbonamento attivo in vero accesso: una chiave di licenza nella casella di posta del cliente, un flag delle funzionalità che la tua app controlla, un ruolo Discord, un repository GitHub, un modello Notion, un link remix di Framer, un invito alla chat di Telegram o un pacchetto di file scaricabili. Dodo Payments emette, traccia e revoca automaticamente tale accesso in base ai cambiamenti del ciclo di pagamento.
## Cosa sono le Entitlements?
Un'**entitlement** è una definizione riutilizzabile di qualcosa che fornisci a un cliente: una chiave di licenza Pro, un ruolo "Patrons" su Discord, accesso al tuo repository GitHub privato, un pacchetto di e-book scaricabile. Le entitlements si associano ai prodotti, e Dodo Payments si occupa del resto.
Quando un cliente acquista il prodotto, Dodo Payments crea una **grant**, un'emissione singola di quella entitlement al cliente. Le grants passano attraverso una piccola serie di stati: `pending` mentre la consegna è in corso, `delivered` una volta che il cliente ha accesso, `failed` se la consegna non è stata completata, e `revoked` quando l'accesso viene ritirato.
Le entitlements controllano il **fulfillment** (il cliente ha accesso?). I crediti controllano il **consumo** (quanto possono utilizzare?). Entrambi possono essere collegati allo stesso prodotto. Vedi [Credit-Based Billing](/features/credit-based-billing) per i crediti.
## Integrazioni Disponibili
Dodo Payments consegna ogni entitlement attraverso un'integrazione dedicata. Scegli l'integrazione che corrisponde a ciò che vendi.
Genera chiavi di licenza uniche con limiti di attivazione e scadenza. Ideale per software, plugin e CLI.
Fornisci file scaricabili (e-book, template, media) con URL di download presigned e istruzioni opzionali.
Limitare l'accesso alle funzionalità nella tua app dopo un acquisto. Consegnato istantaneamente, verificato tramite API, revocato alla cancellazione.
Concedi a un cliente un ruolo nel tuo server Discord quando acquista. Revocato automaticamente alla cancellazione.
Aggiungi i clienti come collaboratori a un repository privato al livello di autorizzazione che scegli.
Aggiungi i clienti a una chat o canale privato di Telegram dopo l'acquisto.
Sblocca un link di remix del modello Framer per i clienti paganti.
Duplica un modello Notion nello spazio di lavoro del cliente all'acquisto.
***
## Come funzionano le concessioni
Le concessioni sono generate dagli stessi eventi di pagamento e abbonamento che già ricevi come webhook. Non è necessario chiamare l'API delle concessioni per gli acquisti. Dodo Payments crea e revoca le concessioni automaticamente in base al ciclo di vita del pagamento sottostante.
### Ciclo di vita delle concessioni
Una concessione viene creata quando un pagamento è completato o un abbonamento diventa attivo. Le chiavi di licenza e i flag delle funzionalità passano direttamente a `delivered`. Ogni altra integrazione inizia in `pending`. Le integrazioni basate su OAuth (Discord, GitHub, Notion) includono un `oauth_url` che il cliente deve visitare per completare il consenso. Le integrazioni dirette alla piattaforma (Telegram, Framer, Digital Files) rimangono in `pending` solo brevemente mentre la consegna viene fornita, quindi passano a `delivered`.
Una volta completata la consegna (chiave di licenza generata, ruolo assegnato, accesso al repository concesso, link ai file risolto, OAuth completato), la concessione passa a `delivered` e `delivered_at` viene impostato.
Se la chiamata di integrazione restituisce un errore non ripetibile (token OAuth revocato, permesso negato, file non più esistente), la concessione passa a `failed`. I campi `error_code` e `error_message` catturano il motivo.
Quando l'accesso viene ritirato (abbonamento cancellato, rimborso emesso o revoca avviata dal commerciante), la concessione passa a `revoked`. Il campo `revocation_reason` registra il trigger.
### Comportamento delle concessioni per evento
| Evento | Comportamento |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (pagamento una tantum) | Emissione di una concessione per ogni diritto allegato. |
| `payment.succeeded` (pagamento legato all'abbonamento) | Nessuna operazione. Le concessioni sono gestite dall'evento di abbonamento qui sotto. |
| `subscription.active` | Emissione di concessioni per tutti i diritti allegati che non ne hanno già una. Concessione di nuovo eventuali concessioni precedentemente revocate per lo stesso abbonamento. |
| `subscription.renewed` | Nessuna operazione. Le concessioni esistenti persistono nei rinnovi. |
| `subscription.on_hold` | Revoca di tutte le concessioni consegnate e in sospeso. `revocation_reason: subscription_on_hold`. |
| `subscription.cancelled` | Revoca di tutto. `revocation_reason: subscription_cancelled`. |
| `subscription.expired` | Revoca di tutto. `revocation_reason: subscription_expired`. |
| `subscription.plan_changed` | Revoca di tutte le concessioni correnti, quindi emissione di concessioni per i diritti del nuovo piano. `revocation_reason: plan_changed`. |
| `refund.succeeded` (pagamento una tantum) | Revoca delle concessioni per quel pagamento. `revocation_reason: refund`. |
| Revoca manuale API | Revoca con `revocation_reason: manual`. Le revoche manuali non vengono riassegnate automaticamente alla rinnovazione dell'abbonamento. |
| Chiave di licenza disabilitata | Per le concessioni con chiave di licenza, disabilitare la chiave sottostante revoca la concessione con `revocation_reason: license_key_disabled`. La concessione è riattivata automaticamente se la chiave è riattivata. |
| Drift della piattaforma rilevato | Se il lato piattaforma di un'integrazione si disallinea (un ruolo Discord rimosso manualmente, l'app GitHub perde l'accesso al repository o un passaggio di riconciliazione rileva un target mancante), la concessione è revocata con `revocation_reason: platform_external`. Non viene riassegnata automaticamente alla rinnovazione dell'abbonamento fino a quando il problema sottostante della piattaforma non viene risolto. |
Le concessioni basate su abbonamento sono idempotenti per `(entitlement, customer, subscription)`; i rinnovi e le riattivazioni non creano concessioni duplicate. Le concessioni una tantum sono idempotenti per `(entitlement, customer, payment)`.
***
## Creare il tuo primo diritto
Vai su **Diritti** nel tuo pannello di Dodo Payments e fai clic su **+** per creare un nuovo diritto.
Scegli il tipo di integrazione: Chiave di licenza, File digitali, Flag delle funzionalità, Discord, GitHub, Telegram, Framer o Notion. Per le integrazioni sulla piattaforma, connetti prima il tuo account se non lo hai già fatto.
Compila i campi specifici dell'integrazione. Ad esempio, GitHub chiede un repository e un livello di autorizzazione; Discord chiede un server e un ruolo opzionale; la Chiave di licenza chiede limiti di attivazione e scadenza.
Salva il diritto. Ora puoi allegarlo a qualsiasi prodotto.
## Allegare diritti ai prodotti
Apri un prodotto, espandi **Impostazioni avanzate → Diritti e Crediti** e seleziona i diritti che devono essere consegnati quando il prodotto viene acquistato. Un singolo prodotto può consegnare più diritti contemporaneamente. Ad esempio, un piano Pro può includere una chiave di licenza, l'accesso a GitHub e un ruolo Discord.
***
## Esperienza del cliente
### E-mail e portale clienti
I clienti ricevono un'email di consegna dopo l'acquisto contenente la chiave di licenza, i link per il download, i link di invito OAuth o inviti alla piattaforma, a seconda di ciò che si applica ai diritti sul prodotto. Gli stessi dettagli rimangono disponibili indefinitamente dal [Portale Clienti](/features/customer-portal) sotto la loro cronologia ordini.
### Consegna basata su OAuth
L'accesso ai sottoscrittori di Discord, GitHub e Notion richiede che il cliente autorizzi Dodo Payments a concedergli l'accesso. Queste concessioni rimangono in stato `pending` fino a quando il cliente non completa il flusso OAuth utilizzando il link dalla loro email o portale clienti. Una volta autorizzati, la concessione passa a `delivered` e l'accesso alla piattaforma viene fornito immediatamente.
### Revoca
Le concessioni revocate vengono rimosse a livello di piattaforma: il ruolo Discord viene rimosso, il collaboratore GitHub viene rimosso, la chiave di licenza viene disabilitata. I clienti vedono il cambiamento riflesso nel portale clienti.
Per i file digitali, la revoca rimuove l'accesso agli URL presigned nel futuro ma non invalida le copie già scaricate dal cliente. Pianifica il contenuto del piano di conseguenza.
***
## Gestisci le concessioni
Apri qualsiasi diritto dalla dashboard per vedere le sue concessioni. Il pannello dettagli concessioni mostra le concessioni totali, i filtri di stato, le informazioni sui clienti, le date di consegna e un'azione di revoca.
Puoi anche gestire le concessioni in modo programmatico:
```typescript TypeScript theme={null} theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
});
// List grants for an entitlement
const grants = await client.entitlements.grants.list('ent_abc123', {
status: 'Delivered',
});
// Revoke a single grant
await client.entitlements.grants.revoke('grant_xyz789', {
id: 'ent_abc123',
});
```
```python Python theme={null} theme={null}
client.entitlements.grants.list(
"ent_abc123",
status="Delivered",
)
client.entitlements.grants.revoke(
"grant_xyz789",
id="ent_abc123",
)
```
```go Go theme={null} theme={null}
grants, _ := client.Entitlements.Grants.List(
ctx, "ent_abc123",
dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
)
_, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")
```
***
## Gestione API
Crea un nuovo diritto di qualsiasi tipo di integrazione.
Elenca i diritti con filtro per tipo di integrazione.
Recupera un diritto e la sua configurazione risolta.
Aggiorna nome, descrizione o configurazione dell'integrazione.
Elimina un diritto in modo soft; le concessioni esistenti non sono influenzate.
Carica un file in un diritto di File Digitali (fino a 500 MiB).
Elenca tutte le concessioni per un diritto con filtri di stato e clienti.
Revoca manualmente una singola concessione.
***
## Webhooks
Dodo Payments attiva quattro eventi webhook per il ciclo di vita delle concessioni. Iscriviti a questi eventi per mantenere la tua applicazione sincronizzata con ciò che ciascun cliente può accedere.
| Evento | Si attiva quando |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entitlement_grant.created` | Viene creata una nuova concessione. Le concessioni con chiave di licenza arrivano `delivered`; ogni altra integrazione arriva `pending` e transita a `delivered` una volta che la chiamata alla piattaforma ha successo (o, per le integrazioni basate su OAuth, una volta che il cliente autorizza). |
| `entitlement_grant.delivered` | La concessione passa a consegnata. Il cliente ora ha accesso. |
| `entitlement_grant.failed` | La concessione non ha potuto essere consegnata. Controlla `error_code` e `error_message`. |
| `entitlement_grant.revoked` | L'accesso è stato ritirato. Controlla `revocation_reason`. |
Visualizza lo schema del payload completo, eventi di esempio e il riferimento `revocation_reason`.
***
## Pratiche consigliate
* **Usa un diritto per canale di consegna.** Non condividere un solo diritto Discord tra prodotti con diverse intenzioni di ruolo; creane uno per ruolo per una revoca pulita.
* **Testa prima in modalità test.** Crea il diritto, allegalo a un prodotto di test, esegui un checkout e osserva la transizione della concessione tramite `pending → delivered`. Conferma che la cancellazione dell'abbonamento di test revoca la concessione.
* **Ascolta `entitlement_grant.delivered`, non `payment.succeeded`.** Un pagamento può avere successo prima che la consegna finisca (soprattutto per flussi OAuth). Aspetta l'evento consegnato prima di sbloccare le funzionalità dipendenti nei tuoi sistemi.
* **Tratta `entitlement_grant.failed` come attuabile.** Una concessione fallita significa che un cliente ha pagato ma non ha ottenuto accesso. Metti questi in evidenza al tuo team di supporto o attiva un riesame.
* **Mappa `revocation_reason` ai tuoi flussi di conservazione.** Una revoca `subscription_on_hold` è recuperabile (il cliente potrebbe aggiornare la propria carta). Una revoca `manual` è intenzionale. Trattale diversamente nelle comunicazioni con il cliente.