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.

​
Panoramica

La Consegna di Prodotti Digitali è il tipo di autorizzazione File Digitali. Carichi i tuoi file una volta su un’autorizzazione File Digitali, colleghi l’autorizzazione a un prodotto, e Dodo Payments fornisce link di download presigned a ogni cliente pagante tramite email e il portale clienti. L’autorizzazione supporta:
  • Caricamenti di file ospitati: memorizza i file su Dodo Payments e fornisce loro tramite URL presigned a breve durata.
  • Link di download esterni: collega a file ospitati su Dropbox, Google Drive, S3 o qualsiasi URL.
  • Istruzioni di download: testo libero mostrato al cliente sulla pagina dell’ordine e nell’email di consegna.
Puoi combinare tutti e tre su un’unica autorizzazione.

​
Caratteristiche Principali

File Upload

Carica file (PDF, ZIP, immagini, video, ecc.) fino a 100 MB. I file vengono trasmessi e memorizzati in modo efficiente.

Multiple Files

Allega quanti file vuoi a un’unica autorizzazione.

External Links

Fornisci link di download esterni (Dropbox, Google Drive, URL S3 firmati) come alternativa o aggiunta.

Presigned URLs

I file ospitati vengono forniti tramite URL presigned a breve durata. Ogni URL di download scade automaticamente dopo circa 15 minuti.

​
Configura Consegna di Prodotti Digitali

1

Open Entitlements

Vai su Autorizzazioni nel dashboard di Dodo Payments e fai clic su + per creare una nuova autorizzazione.
2

Choose Digital Files

Seleziona Consegna di Prodotti Digitali come integrazione.
3

Add files, links, and instructions

Configura qualsiasi combinazione di:
  • File: carica uno o più file. Ogni caricamento restituisce un file_id che viene aggiunto all’autorizzazione.
  • URL esterno: un link HTTPS pubblicamente raggiungibile consegnato insieme ai file ospitati.
  • Istruzioni: testo libero mostrato al cliente (ad es., “Decomprimi ed esegui setup.sh”).
Autorizzazione File Digitali con campi di caricamento file, URL esterno e istruzioni
4

Save the entitlement

Salva. L’autorizzazione è ora disponibile per essere allegata a qualsiasi prodotto.

​
Allegare ai Prodotti

Apri un prodotto, espandi Impostazioni Avanzate → Autorizzazioni & Crediti, e seleziona la tua autorizzazione File Digitali. L’autorizzazione viene consegnata a ogni acquisto riuscito o abbonamento attivo collegato a quel prodotto.
Pannello di autorizzazioni del prodotto con Consegna di Prodotti Digitali selezionata

​
Come Funziona la Consegna

La consegna dei File Digitali segue il processo standard del ciclo di vita della concessione:
EventoComportamento
payment.succeeded (una tantum)Emetti una concessione. La concessione fornisce URL di download presigned validi per ~15 minuti; i clienti possono aggiornarli riaprendo il link dell’email o la pagina del portale clienti.
subscription.activeEmetti una concessione. I file restano accessibili finché l’abbonamento è attivo.
subscription.renewedNessuna azione. La stessa concessione continua; nuovi URL presigned vengono creati a ogni richiesta.
subscription.on_hold / cancelled / expiredRevoca la concessione. Nuovi URL presigned non vengono più forniti.
subscription.plan_changedRevoca la vecchia concessione; emetti una nuova per l’autorizzazione del nuovo piano.
refund.succeeded (una tantum)Revoca la concessione.
Revoca manualeRevoca con revocation_reason: manual.
La revoca impedisce a Dodo Payments di emettere nuovi URL di download, ma non invalida le copie che un cliente ha già scaricato. Tratta i download dei file ospitati come “forniti una volta letti.”

​
Esperienza del Cliente

​
Conferma Acquisto

Dopo una transazione riuscita, il cliente riceve un’email con link di download e eventuali istruzioni configurate.
Email di conferma acquisto che mostra link di download per i prodotti digitali

​
Accesso al Portale Clienti

I clienti possono recuperare nuovamente i link di download in qualsiasi momento dal Portale Clienti. La pagina del portale genera nuovi URL presigned su richiesta, quindi lo stesso acquisto continua a funzionare anche dopo che i link dell’email sono scaduti.
Interfaccia del portale clienti che mostra i prodotti digitali disponibili per il download
I clienti possono scaricare i file direttamente dalle email di conferma o accedervi in qualsiasi momento attraverso il loro portale.

​
Gestione Programmata dei File

​
Carica un file su un’autorizzazione

import DodoPayments from 'dodopayments';
import fs from 'node:fs';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode',
});

await client.entitlements.files.upload('ent_files_abc', {
  file: fs.createReadStream('./pro-bundle.zip'),
  filename: 'pro-bundle.zip',
});

​
Elenca concessioni e risolvi URL di download

const grants = await client.entitlements.grants.list('ent_files_abc', {
  customer_id: 'cus_abc123',
});

for (const grant of grants.items) {
  for (const file of grant.digital_product_delivery.files) {
    console.log(file.filename, file.download_url, `expires in ${file.expires_in}s`);
  }
}

​
Rimuovi un file da un’autorizzazione

await client.entitlements.files.delete('ent_files_abc', 'df_a4f6c1de');

​
Considerazioni Importanti

  • Gli URL presigned scadono velocemente. Gli URL di download restituiti nei payload delle concessioni o negli eventi webhook sono validi per ~15 minuti. Non memorizzarli; recuperali nuovamente quando il cliente deve scaricare di nuovo.
  • Aggiornare i file influisce solo sugli acquisti futuri. Sostituzioni o rimozioni di file non alterano retroattivamente i download già emessi. I clienti precedenti possono comunque recuperare la versione che era valida quando la loro concessione è stata creata.
  • I rimborsi non invalidano le copie scaricate. Un cliente che ha già scaricato un file mantiene quella copia. Per contenuti revocabili (media con licenze, accesso limitato nel tempo), abbina File Digitali con Chiavi di Licenza e valida a runtime.
  • Per contenuti sensibili, preferisci URL esterni con la propria autenticazione. Gli URL presigned di Dodo Payments sono a breve durata ma non autenticati all’interno del loro intervallo; chiunque abbia l’URL può scaricare in quel lasso di tempo. Contenuti ospitati esternamente e protetti da account offrono garanzie più forti.

​
Gestione API

Create Entitlement

Crea un’autorizzazione File Digitali con URL esterno e istruzioni opzionali.

Upload File

Carica un file (fino a 100 MB) e aggiungilo all’autorizzazione.

Delete File

Rimuovi un file dall’autorizzazione.

List Grants

Elenca concessioni e leggi gli URL di download risolti.

Update Entitlement

Aggiorna istruzioni, URL esterno o sostituisci i file.

Revoke Grant

Revoca manualmente l’accesso a un cliente.

​
Webhook

La consegna e la revoca dei file digitali attivano i quattro eventi webhook entitlement_grant.*. Per le concessioni File Digitali, il payload include un oggetto digital_product_delivery con l’elenco dei file risolti (URL presigned, nomi file, dimensioni), l’opzionale instructions, e il opzionale external_url. 
"digital_product_delivery": {
  "files": [
    {
      "file_id": "df_a4f6c1de",
      "download_url": "https://files.dodopayments.com/.../pro-bundle.zip?Signature=...",
      "filename": "pro-bundle.zip",
      "content_type": "application/zip",
      "file_size": 18742390,
      "expires_in": 900
    }
  ],
  "instructions": "Unzip and run setup.sh from the project root.",
  "external_url": null
}

​
Consegna di Prodotti Digitali Legacy

I prodotti configurati con il vecchio blocco digital_product_delivery sul prodotto stesso sono stati automaticamente migrati a un’autorizzazione File Digitali. I file esistenti caricati sotto l’API legacy dei file del prodotto sono preservati; continuano a essere scaricabili e apparire nei payload delle concessioni contrassegnati con source: "legacy". Gli aggiornamenti futuri (aggiungere file, modificare istruzioni, sostituire l’URL esterno) devono essere effettuati modificando l’autorizzazione File Digitali migrata sotto Autorizzazioni.I campi legacy a livello di prodotto (digital_product_delivery.external_url, digital_product_delivery.instructions) continuano a essere popolati nelle risposte dei prodotti per la compatibilità con versioni precedenti, ma l’autorizzazione è la fonte di verità andando avanti.

​
Buone Pratiche

  • Tratta i download come unici. I clienti condivideranno o perderanno i link, quindi progetta il tuo prodotto assumendo che qualsiasi cosa scarichino sia loro.
  • Usa le istruzioni per impostare aspettative. Per pacchetti multilingua, aggiungi una riga instructions che spieghi cosa installare per primo o come combinare i file.
  • Monitora il limite di 100 MB. Gli artefatti più grandi (dataset multi-GB, corsi video) dovrebbero essere ospitati esternamente e collegati tramite external_url invece di essere caricati.
  • Combina con Chiavi di Licenza per accesso revocabile. Se hai bisogno di revocare l’accesso a funzionalità del prodotto dopo un rimborso, abbina l’autorizzazione File Digitali con un’autorizzazione Chiave di Licenza e verifica la chiave a runtime.
  • Testa il flusso di aggiornamento del portale clienti. Verifica che un cliente possa tornare al portale una settimana dopo e ottenere ancora un link di download funzionante. Questo è il principale percorso di recupero quando i link dell’email scadono.
Last modified on May 14, 2026