Concetti fondamentali

Base URL & identificazione del negozio

https://<dominio-del-negozio>/api/v1

Chiamando l’API attraverso il dominio del negozio ricevi solo i dati di quel negozio — niente identificativo da inviare. Da un client senza dominio (mobile/server) usa la chiave publishable.

Envelope

Tutte le risposte JSON hanno la stessa busta:

{ "data": null, "meta": null, "error": null, "error_code": null }

Errori

Sugli errori error_code porta un codice macchina stabile e data di solito è null. Il frontend deve fare switch su error_code, non mostrare error (inglese, solo per debug).

{
  "data": null,
  "error": "Invalid credentials",
  "error_code": "auth.invalid_credentials"
}

Alcuni rifiuti mettono in data i dettagli che servono a spiegarli: per esempio checkout.min_order_not_met porta min_order_total, subtotal e currency.
Validazione (422): error_code vale validation.failed e la risposta ha in più detail, la lista dei campi errati (il campo è l’ultimo elemento di loc).
Rate limit (429): la risposta è {"detail": "..."}, senza la busta.

Gli status HTTP seguono la semantica standard (200, 201, 400, 401, 403, 404, 409, 422, 429, 502).

Paginazione

Le liste accettano page e page_size e restituiscono meta:

{ "meta": { "page": 1, "page_size": 24, "total": 190, "total_pages": 8 } }

Internazionalizzazione

Molti endpoint di contenuto accettano ?lang=it|en|sq (o l’header Accept-Language) e restituiscono i campi già risolti nella lingua richiesta, con fallback alla lingua di default del negozio.

Immagini

I percorsi immagine sono relativi (/uploads/products/xyz.webp): preponi l’origin del negozio → https://<dominio>/uploads/.... In produzione sono servite via CDN/redirect firmato, quindi usa l’URL così com’è restituito.

Multi-tenant in breve

Ogni negozio è un tenant isolato. La chiave publishable e il dominio determinano il tenant per le chiamate storefront; il claim tenant_id del token staff lo determina per la Admin API. Non c’è modo, con credenziali di un negozio, di vedere i dati di un altro.

Inizia

Guide

AI & MCP