AG mette a disposizione un'API REST pubblica per gli ordini a livello programmatico — utile se stai realizzando una vetrina, un'automazione o un'integrazione che deve effettuare ordini su AG senza usare il checkout web. L'accesso all'API è controllato per singolo account.
Abilitazione dell'accesso API
L'accesso all'API viene abilitato dagli amministratori di AG su base per-account. Una volta abilitato, vedrai la card API Keys in Settings.
Generazione di una chiave API
- Apri Settings e trova la card API Keys.
- Clicca su New key, assegna un Name e clicca Create.
- Copia il token
ag_live_...immediatamente — viene mostrato una sola volta. - Salvalo in modo sicuro (in un secrets manager o in un file
.env).
Cosa puoi fare con l'API
- Ottenere preventivi di prezzi e opzioni di consegna prima di effettuare un ordine.
- Effettuare ordini con configurazione completa (carta, formato, cornice, montaggio, indirizzo di consegna).
- Gestire la tua carta salvata — obbligatoria per effettuare ordini.
- Elencare e recuperare ordini effettuati tramite l'API.
Autenticazione
Passa il token come header Bearer su ogni richiesta:
Authorization: Bearer ag_live_...
Configurazione richiesta
- Una carta salvata registrata (vedi How to manage saved cards) — gli ordini via API vengono addebitati automaticamente.
- Un paese di residenza impostato sull'account — determina la valuta e l'instradamento della filiale Stripe.
Idempotenza
POST /v1/orders accetta un header Idempotency-Key per deduplica i tentativi in modo sicuro. Invialo sempre per le integrazioni in produzione.
Codici promozionali tramite l'API
POST /v1/orders accetta un promo_code. I codici vengono convalidati — un codice non valido rifiuta l'ordine anziché addebitare silenziosamente il prezzo intero — e un ordine interamente coperto da una promozione non richiede una carta salvata. Gli ordini in batch di grandi dimensioni (circa 150 articoli) sono supportati.