Set up API access
1. Conferma che il negozio è approvato per il pilota
Alva deve approvare il negozio prima che le chiavi API possano essere create o utilizzate. Se l'accesso non è ancora attivo, contatta admin@alvaapps.com.
2. Crea una chiave API
Apri le Impostazioni di Alva, scegli Chiavi API e crea una chiave per l'integrazione. Copia il token una sola volta e conservalo in un gestore di segreti. Alva memorizza solo un id di chiave pubblica e un hash del segreto.
3. Invia il token come header Bearer
Invia ogni richiesta con Authorization: Bearer adk_live_.... Una chiave mancante, malformata, sconosciuta o revocata restituisce la stessa risposta non autorizzata, in modo che gli aggressori non possano enumerare le chiavi valide.
4. Includi le chiavi di idempotenza nelle scritture
Ogni richiesta diversa da GET deve includere un header Idempotency-Key. Riutilizzando la stessa chiave e lo stesso corpo viene riprodotta in sicurezza una risposta riuscita invece di creare un asset, una mappatura, un'assegnazione o una modifica di accesso duplicati.
Creare asset e mappare prodotti
Usa POST /api/v1/assets per importare un file remoto da un host autorizzato, oppure usa gli endpoint di upload diretto quando la tua integrazione carica direttamente nello storage di Alva. Interroga GET /api/v1/jobs/{job_id} finché l'import remoto non è completato.
Dopo che l'asset esiste, crea o aggiorna una mappatura con POST /api/v1/mappings. Gli id dei prodotti devono usare il formato GID di Shopify. L'API limita ogni mappatura al negozio associato alla chiave API.
Assegnare download agli ordini
Usa POST /api/v1/orders/{shopify_order_id}/assignments quando un sistema esterno deve dare a un cliente l'accesso a prodotti digitali mappati. L'assegnazione può creare il record del cliente, creare l'acquisto e, facoltativamente, inviare l'e-mail di consegna.
Usa gli endpoint di accesso agli ordini per revocare l'accesso, ripristinarlo, concedere download extra o inviare di nuovo l'e-mail di consegna. Queste azioni sono limitate al negozio e non accettano id del negozio nel corpo della richiesta.
Leggere la documentazione dell'API
Usa la guida rapida, il riferimento degli endpoint, la guida agli errori e la specifica OpenAPI scaricabile quando crei un'integrazione.
FAQ
Tutti i commercianti possono usare l'API esterna?
No. L'accesso all'API è disponibile previa approvazione. Contatta admin@alvaapps.com per attivare l'accesso all'API per il tuo negozio.
Do write requests need idempotency keys?
Sì. Ogni richiesta diversa da GET deve includere un header Idempotency-Key affinché i tentativi ripetuti non creino asset, mappature, assegnazioni o modifiche di accesso duplicati.
See also
È stato utile?
Last updated 2026-06-05