Cos'è l'API di Alva Digital Downloads?
L'API di Alva Digital Downloads è un'API REST versionata — v1 — che consente a un sistema esterno di gestire i download digitali su un negozio Shopify senza aprire l'admin di Shopify. Attraverso di essa uno sviluppatore può creare file, mapparli ai prodotti, cercare ordini, emettere URL di download, inviare di nuovo email di consegna e verificare le scorte di chiavi di licenza, il tutto tramite HTTPS standard.
L'API affianca l'interfaccia admin dell'app anziché sostituirla. Ogni risorsa che tocca — file, mappature dei prodotti, categorie, ordini, tag delle chiavi di licenza — è lo stesso dato che il tuo team modifica a mano in Alva, semplicemente raggiungibile da codice. Questo la rende il ponte tra Alva Digital Downloads e qualunque altro strumento gestisca la tua attività.
Cosa puoi fare con l'API di Alva
L'API di Alva copre il flusso di consegna principale dall'inizio alla fine. Gestisce file, mappature dei prodotti e categorie, cerca ordini ed emette URL di download, invia di nuovo email di consegna brandizzate e riporta le scorte di chiavi di licenza. I file possono essere caricati direttamente, o acquisiti da un URL remoto che Alva trasferisce in streaming direttamente nello storage per tuo conto.
In termini pratici, un'integrazione può:
- Gestire i file — carica un file direttamente, oppure fornisci ad Alva un URL e trasferisce in streaming l'asset nello storage per te (ingest da URL remoto), così una grande libreria non deve mai passare prima attraverso i tuoi server.
- Mappare prodotti e categorie — collega file, pacchetti, link o tag di chiavi di licenza ai prodotti Shopify usando lo stesso modello many-to-many che usa l'admin.
- Cercare ordini ed emettere URL di download — risolvi un ordine Shopify e genera un nuovo URL di download a tempo limitato per l'acquirente.
- Inviare di nuovo email di consegna — riattiva l'email di download per un ordine da codice, senza modificare nulla a mano.
- Verificare le scorte di chiavi di licenza — leggi quante chiavi restano per un tag prima di un grande lancio, così non esaurisci mai le scorte senza accorgertene.
I percorsi degli endpoint, i corpi delle richieste e le strutture delle risposte si trovano nel riferimento dell'API. Questo articolo resta al livello di cosa serve l'API; il riferimento è dove configuri ogni singola chiamata.
Come funzionano l'autenticazione e le chiavi API
L'autenticazione utilizza chiavi API per negozio. Ogni richiesta contiene un token Bearer che inizia con adk_live_. Alva Digital Downloads memorizza solo un hash sha256 del segreto — mai il testo in chiaro — lo confronta in tempo costante e adotta un approccio fail-closed, così una chiave mancante, malformata, sconosciuta o revocata restituiscono tutte la stessa risposta di non autorizzazione.
Crei una chiave nell'admin di Alva, copi il token una sola volta e lo conservi in un secret manager. Alva conserva solo l'id pubblico della chiave e l'hash, così il segreto in chiaro non è mai recuperabile dal tuo account. Poiché ogni modalità di errore restituisce una risposta identica, un attaccante non può sondare il tuo negozio per distinguere una chiave errata da una revocata.
Emetti una chiave separata per ogni sistema, e revoca una qualsiasi di esse nel momento in cui un'integrazione viene dismessa. Una chiave revocata smette di funzionare immediatamente su ogni endpoint, il che rende la rotazione delle credenziali un'azione da un clic anziché una migrazione coordinata.
Progettata per l'automazione su larga scala
L'API di Alva è progettata per essere pilotata da macchine che effettuano tentativi ripetuti. Le chiavi di idempotenza sono obbligatorie su ogni scrittura, con una finestra di replay di 24 ore che trasforma una richiesta duplicata nella risposta originale anziché in un secondo record. Un rate limiter a token bucket protegge il negozio, e ogni risposta restituisce un request_id per il tracciamento.
L'idempotenza non è facoltativa sulle scritture. Ogni richiesta non-GET deve inviare un header Idempotency-Key; riutilizza la stessa chiave e lo stesso corpo e Alva riproduce in sicurezza il primo risultato anziché creare un file, una mappatura o un'assegnazione duplicati. Un nuovo tentativo dopo una connessione interrotta è quindi innocuo:
curl https://.../api/v1/mappings \
-H "Authorization: Bearer adk_live_..." \
-H "Idempotency-Key: 2f9c-4b1e-...-e1" \
-H "Content-Type: application/json" \
-d '{ "product_id": "gid://shopify/Product/123", ... }'Oltre all'idempotenza, un rate limiter a token bucket limita i picchi così uno script fuori controllo non può sovraccaricare la tua pipeline di consegna, i valori sensibili vengono oscurati dai log, e l'ingest da URL remoto opera dietro un guard SSRF che blocca le richieste dirette a indirizzi interni. Il request_id su ogni risposta fornisce a te e al supporto di Alva un'unica stringa per tracciare una chiamata dalla richiesta al risultato.
API o Shopify Flow: quale strada fa per te?
Alva Digital Downloads ti offre due modi per automatizzare. Shopify Flow è la strada no-code — trigger e azioni visivi che assembli nell'editor di Shopify. L'API è la strada del codice, per i team che hanno bisogno di controllo programmatico dai propri sistemi. La maggior parte dei negozi non ha mai bisogno dell'API; Flow copre le automazioni comuni.
Se il tuo obiettivo è taggare un cliente segnalato per frode, revocare l'accesso in caso di rimborso o premiare gli acquirenti VIP, costruiscilo visivamente — la guida alle automazioni Shopify Flow per i download digitali illustra i trigger e le azioni di Alva. Ricorri all'API quando la logica risiede al di fuori di Shopify: un ERP che possiede il tuo catalogo, un LMS che fornisce l'accesso ai corsi, o un CRM che deve restare sincronizzato. Sotto il cofano, entrambi pilotano lo stesso motore dietro la consegna multicanale dei download di Alva.
A chi è destinata l'API di Alva
L'API di Alva è rivolta a tre tipi di pubblico: gli sviluppatori che vogliono automatizzare via script il lavoro in blocco su file e mappature, le agenzie che costruiscono storefront Shopify personalizzati o headless che consegnano beni digitali, e i team operativi che sincronizzano i download con un ERP, un LMS o un CRM esterno. I merchant che gestiscono uno storefront Shopify standard raramente ne hanno bisogno.
Una build headless può mantenere Shopify come fonte di verità per gli ordini mentre l'API emette URL di download verso un front end su misura. Un team operativo può lasciare che il proprio ERP crei file e mappature nel momento in cui un prodotto viene spedito, così lo storefront e il back office non divergono mai. Il filo conduttore è un controllo che deve avere origine al di fuori dell'admin di Shopify.
Nulla di tutto questo è un requisito per vendere prodotti digitali su Shopify — l'admin di Alva gestisce già tutto dall'inizio alla fine. L'API è per quella minoranza di negozi la cui scala o architettura ha superato il semplice cliccare attraverso un'interfaccia utente.
Come ottenere l'accesso all'API
L'accesso all'API è opzionale e soggetto a gate. Un flag di disponibilità globale più un interruttore per negozio fanno sì che l'API venga attivata per un negozio alla volta su richiesta, non abilitata per tutti di default. Contatta il supporto di Alva per attivarla per il tuo negozio. L'API è disponibile sui piani a pagamento e viene distribuita gradualmente.
Chiedi al supporto di Alva di abilitare l'accesso all'API, poi crea una chiave dall'admin di Alva. La guida di supporto all'uso dell'API esterna illustra chiavi, idempotenza, ingest remoto e assegnazioni degli ordini, e la build include un riferimento API completo, una specifica OpenAPI scaricabile e una collezione Postman. Consulta i piani per sapere dove si colloca l'API.
Domande frequenti
L'API di Alva Digital Downloads è un'API REST versionata, v1, che consente a un sistema esterno di gestire i download digitali su un negozio Shopify senza usare l'admin di Shopify. Attraverso di essa uno sviluppatore può creare file, mapparli ai prodotti, cercare ordini, emettere URL di download, inviare di nuovo email di consegna e verificare le scorte di chiavi di licenza tramite HTTPS standard.
Solo per le scritture. Ogni richiesta non-GET deve includere un header Idempotency-Key, che ha una finestra di replay di 24 ore, così una chiamata ripetuta restituisce la risposta originale anziché creare un file, una mappatura o un'assegnazione duplicati. Le richieste di lettura non ne hanno bisogno. Questo mantiene al sicuro le automazioni che riprovano dopo un errore di rete dall'effettuare modifiche duplicate.
L'API utilizza chiavi API per negozio. Ogni richiesta invia un token Bearer che inizia con adk_live_. L'app memorizza solo un hash sha256 del segreto, mai il testo in chiaro, lo confronta in tempo costante e adotta un approccio fail-closed, così una chiave mancante, malformata, sconosciuta o revocata restituiscono tutte la stessa risposta di non autorizzazione e non possono essere distinte tra loro.
Shopify Flow è la strada di automazione no-code, costruita a partire da trigger e azioni visivi all'interno di Shopify. L'API è la strada del codice, per i team che hanno bisogno di controllo programmatico dai propri sistemi. Usa Flow per le automazioni che risiedono all'interno di Shopify, e l'API quando la logica risiede in un ERP, un LMS o un CRM esterno.
L'accesso all'API è opzionale e soggetto a gate per ogni negozio. Un flag di disponibilità globale più un interruttore per negozio fanno sì che venga attivato individualmente su richiesta, non abilitato per tutti di default. Contatta il supporto di Alva per attivarlo per il tuo negozio. L'API è disponibile sui piani a pagamento e viene distribuita gradualmente.