GET /v1/catalog — sincronizza il catalogo per l'Italia
Recupera SKU localizzati con MOQ, lead time, fasce prezzo. Paginazione cursor, If-Modified-Since per delta sync, flag disponibilità hub Milano.
Paginazione e delta
GET /v1/catalog?country=Italy&cursor=…&limit=200 (max 500). Ogni pagina: { data:[…], next_cursor }. Header If-Modified-Since per delta sync — server risponde 304 se nulla è cambiato. ETag supportato. Catalogo completo per Italia ~12k SKU.
Forma dell'oggetto
Ogni item: { sku, name_i18n:{en, it}, category_path, moq, lead_time_days, base_price_cents (EUR, esclusa IVA), iva_rate:22%, weight_grams, hub:'Milano', sustainability:{recycled_pct, gots_certified}, image_urls[], variants[] }. Prezzi pre-tax; applica IVA 22% o usa il campo esplicito.
Filtri e ricerca
Filtri: ?category=apparel&min_moq=50&max_lead_days=15&hub=Milano&certified=gots. Ricerca full-text via ?q=…. Tutti i parametri combinabili. Limite 500 risultati per request mantiene p95 sotto 250 ms.
FAQ
Con che frequenza cambia il catalogo?
Aggiornamenti prezzi giornalieri (00:30 UTC), nuovi SKU settimanali (lun 06:00 UTC). Usa webhook catalog.updated per sync push.
Posso ottenere le immagini prodotto?
image_urls[] restituisce URL CDN a risoluzione originale; aggiungi ?w=800 per varianti ridimensionate (image processing server-side).
I prezzi includono IVA?
No — base_price_cents esclude IVA. Applica iva_rate (tipicamente 22%) per il prezzo al cliente in Italia.
Come funziona l'enforcement del MOQ?
Campo moq è il minimo assoluto per riga. Invii inferiori restituiscono 400 min_qty_violation. Alcuni SKU hanno moq_increment per quantità a step.
Posso filtrare per certificazione?
Sì — ?certified=gots,fairwear,iso14001 restituisce solo SKU con tutte le certificazioni elencate. Combina con ?sustainability_min_recycled_pct=30.