Sviluppatori
API Merchant
Un'API REST in sola lettura per il tuo negozio VeeBoost: un contratto pubblicato, autenticazione a chiave e impaginazione prevedibile — pensata per integrazioni che restano sincronizzate.
Un contratto unico, pubblicato come unica fonte di verità
Il tuo negozio pubblica il contratto completo leggibile dalle macchine (OpenAPI 3.1): ogni endpoint, parametro, risposta e codice di errore dell'API merchant. Questa pagina vi rimanda e non riproduce mai le tabelle degli endpoint — il contratto non può divergere, e nemmeno la tua integrazione.
GET /openapi/v1.jsonAvvio rapido
Tre passaggi per la tua prima lettura del catalogo:
- Crea una chiave API nel tuo admin (sezione Sviluppatori) con gli scope di lettura che ti servono. Inizia con vbk_ e viene mostrata una sola volta.
- Inseriscila nell'header X-Api-Key di ogni richiesta — il tuo tenant viene risolto dalla chiave, mai dall'host.
- Chiama il tuo primo endpoint, ad esempio GET /products, poi segui il contratto per tutto il resto.
Autenticazione
Ogni richiesta porta la tua chiave nell'header X-Api-Key. La v1 offre esattamente quattro scope di lettura — prodotti, ordini, clienti e consegne webhook. Uno scope mancante risponde 403, una chiave revocata viene rifiutata subito. Conserva le chiavi lato server: non appartengono mai a un browser o a un repository pubblico.
products:readorders:readcustomers:readwebhooks:readImpaginazione
Gli endpoint di lista impaginano: percorrili con il parametro page e leggi la busta restituita con ogni collezione — indica dove sei per risincronizzare l'integrazione senza tirare a indovinare. I parametri esatti di ogni endpoint sono documentati nel contratto.
Errori e limiti di frequenza
Gli errori restituiscono un corpo JSON strutturato che puoi interpretare, mai un paragrafo da raschiare. Una risposta 429 è un contratto stabile: sempre la stessa forma, con gli header X-RateLimit-* e un Retry-After che dice esattamente quando tornare. Insistere non sblocca dati — fai backoff.
Chiavi sandbox
Durante il gate pre-lancio, le chiavi sandbox vengono emesse dopo validazione del nostro team e girano con un budget di frequenza dedicato, separato dalle chiavi di produzione — esplora l'API sul tuo negozio senza toccare traffico reale o quote.
Esempi per linguaggio
Uno snippet per piattaforma, solo scope di lettura: ciascuno recupera il tuo catalogo prodotti. Sostituisci <api-base> con l'host API del tuo negozio indicato in admin → sezione Sviluppatori.
curl
curl -H "X-Api-Key: vbk_your_key" \
"https://<api-base>/products?page=1"JavaScript
async function listProducts(page = 1) {
const res = await fetch("https://<api-base>/products?page=" + page, {
headers: { "X-Api-Key": "vbk_your_key" },
});
if (res.status === 429) {
// Structured contract: honor Retry-After, never screen-scrape.
const wait = Number(res.headers.get("Retry-After")) * 1000;
await new Promise((done) => setTimeout(done, wait));
return listProducts(page);
}
if (!res.ok) throw new Error("products:read failed with " + res.status);
return res.json();
}Python
import requests
def list_products(page=1):
res = requests.get(
"https://<api-base>/products",
params={"page": page},
headers={"X-Api-Key": "vbk_your_key"},
timeout=10,
)
res.raise_for_status()
return res.json()La v1 è in sola lettura per design: products:read, orders:read, customers:read e webhooks:read sono gli unici scope esistenti. Scope di scrittura sarebbero una decisione v1.x documentata esplicitamente — nulla è pianificato in silenzio.