Vai al contenuto principale

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.

Contratto pubblicatoGET /openapi/v1.json

Avvio rapido

Tre passaggi per la tua prima lettura del catalogo:

  1. 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.
  2. Inseriscila nell'header X-Api-Key di ogni richiesta — il tuo tenant viene risolto dalla chiave, mai dall'host.
  3. 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:read

Impaginazione

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.