API dati

Schede prodotto in JSON, XML e CSV, con chiave API.

Le chiamate dati restituiscono la scheda completa di un prodotto in JSON, XML o CSV. Servono la chiave API nell'intestazione X-API-Key e, se concordato, un indirizzo IP autorizzato.

Autenticazione

curl -H "X-API-Key: LA-TUA-CHIAVE" "https://api.rivastories.com/v1/product/8003437063541?lang=IT&format=json"

La chiave è nell'area clienti (pagina Accesso) e nella mail di attivazione. Non va mai nel browser né in un link: solo nell'intestazione, da server a server. Se pensate sia finita in mani sbagliate, dall'area clienti o scrivendoci si rigenera e quella vecchia smette subito di funzionare.

Endpoint

Chiamata	Cosa restituisce
`GET /v1/product/{ean}`	La scheda del prodotto con quell'EAN/GTIN
`GET /v1/product?brand=…&mpn=…`	La scheda del prodotto con quel brand e codice produttore (alias `vendor`, `prod_id`). Se corrisponde a più prodotti: `409` con gli EAN candidati
`GET /v1/product/{ean}/download/images`	Zip con tutte le immagini (la principale si chiama `{ean}_main.*`)
`GET /v1/product/{ean}/download/documents`	Zip con i documenti (schede tecniche, manuali, etichette energetiche)
`GET /v1/refs/categories`	Vocabolario delle categorie (id, slug, nome, padre, traduzioni)
`GET /v1/refs/feature-groups`	Gruppi di caratteristiche per categoria
`GET /v1/refs/features`	Vocabolario delle caratteristiche (id, slug, nome, unità, tipo, traduzioni)
`GET /v1/refs/feature-values`	Valori ammessi delle caratteristiche a scelta chiusa

Parametri

Parametro	Valori	Default
`lang`	`IT`, `EN`	`IT`
`format`	`json`, `xml`, `csv` (per i refs: `json`, `xml`)	`json`

I tre formati

JSON è il formato di riferimento: tutti i campi, tipizzati (vedi Riferimento campi). XML porta gli stessi dati con gli stessi nomi, in elementi e attributi. CSV è una riga per prodotto: le colonne fisse, poi una colonna per caratteristica con intestazione {id}_{slug}__{nome}, pensata per fogli di calcolo e importatori a tabella.

<Product id="7368" mpn="7295847604" ean="8690842629853">
  <Brand slug="beko">Beko</Brand>
  <Category id="968">fridge-freezers</Category>
  <Name>Beko B3RCNE564HDXB: Frigorifero Combinato Beyond, Total No-Frost, 70 cm</Name>
  <Descriptions lang="IT"><Short/><Long>…</Long><Warranty/><BulletPoints><Item>…</Item></BulletPoints></Descriptions>
  <FullSpecs><Group id="interior" name="Capacità e spazio interno">
    <Attribute id="1262" slug="total-net-capacity-1262" unit="L" key="0">490 L</Attribute>
  </Group></FullSpecs>
  <KeyFacts><Fact name="Quanto ci sta">490 L in totale, frigo 340 L, congelatore 150 L</Fact></KeyFacts>
  <Images><Image url="https://…/1_medium.jpg" type="image_main" width="185" height="500"/></Images>
  <Documents><Document url="https://…/energy_datasheet.pdf" type="energy_datasheet" label="Scheda informativa del prodotto UE"/></Documents>
  <UpdatedAt>2026-10-22T12:37:46+00:00</UpdatedAt>
</Product>

Esempi completi

La stessa scheda (un frigorifero Beko) in tutti i formati, come la restituisce il servizio:

prodotto.json (indentato per la lettura)
prodotto.xml
prodotto.csv
refs-categories.estratto.json (le prime 25 voci del vocabolario categorie)

Aggiornamenti

Ogni scheda porta updated_at: per tenere allineato il vostro catalogo basta richiamare i prodotti e confrontare la data. Non esiste un feed massivo: le chiamate sono per prodotto, con un limite di 300 al minuto (10.000 schede in circa 35 minuti). Per carichi iniziali più grandi scriveteci: il limite si alza per contratto.

Immagini e documenti

Gli URL puntano alla nostra rete di distribuzione e restano stabili. Potete collegarli direttamente dalle vostre pagine (nessun limite di traffico) o scaricarli con gli zip. Per ogni immagine ci sono tre tagli: url_thumb (miniatura), url (media, 500 px lato lungo), url_high (originale).

Perimetro

Ogni chiave vede i brand previsti dal contratto ("tutto il catalogo" oppure una lista di brand). Un prodotto fuori perimetro risponde 403; i refs sono sempre completi.