Impianto di stampa gratis sopra 500 € di gadget
Citygraph

API rivenditori, versione 1

Pagina per il webmaster. L'API dà al tuo sito il catalogo Citygraph (prodotti, foto, prezzi rivenditore, disponibilità) in formato JSON. La chiave personale la riceve chi ha una richiesta approvata: richiedila qui.

Indirizzo del servizio

https://www.citygraph.it/api/rivenditori/v1

Risposte in JSON UTF-8 (Content-Type: application/json; charset=utf-8), mai in cache (Cache-Control: no-store). Sono ammesse solo richieste GET, con CORS aperto (*).

Autenticazione

Invia la chiave nell'intestazione X-Api-Key. Sono accettate anche Authorization: Bearer <chiave> e, solo per il feed CSV, il parametro ?chiave=. La chiave inizia con cgr_: tienila sul server, mai nel codice che gira nel browser.

X-Api-Key: cgr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoint

GET /stato

Verifica la chiave e restituisce il numero di prodotti.

{"ok":true,"negozio":"citygraph.it","versione_api":"1","rivenditore":"Rossi Srl","prodotti":1716,"aggiornato":"2026-10-16T08:00:00.000Z"}

GET /prodotti

Elenco paginato. Parametri (tutti facoltativi):

Risposta
{
  "pagina": 1, "per_pagina": 100, "totale": 1716, "pagine": 18,
  "prodotti": [
    {
      "sku": "TSRA150",
      "nome": "T-shirt 150 manica corta",
      "catalogo": "ingrosso",
      "marca": "JHK",
      "categoria": "TSHIRT",
      "categoria_slug": "tshirt",
      "descrizione": "<p>...</p>",
      "immagini": ["https://www.citygraph.it/ingrosso/TSRA150.jpg"],
      "prezzo_rivenditore": 2.08,
      "prezzo_consigliato": 2.24,
      "iva": 22,
      "valuta": "EUR",
      "quantita_minima": 1,
      "disponibile": 5320,
      "varianti": [
        {"sku":"TSRA150MWH","colore":"Bianco","hex":"#ffffff","taglia":"M","ean":"8445000000000",
         "disponibile":120,"in_arrivo":500,"prezzo_rivenditore":2.08,"prezzo_consigliato":2.24,
         "immagine":"https://www.citygraph.it/ingrosso/TSRA150.jpg"}
      ],
      "aggiornato": "2026-10-16T08:00:00.000Z"
    }
  ]
}

I prezzi sono numeri a 2 decimali, per pezzo, IVA esclusa. Un prodotto senza varianti ha varianti: [] e la disponibilità sul prodotto. Le immagini sono URL assoluti.

GET /prodotti/{sku}

Un singolo prodotto, con lo stesso formato. Lo sku è quello del prodotto base (maiuscole o minuscole non contano). Se non esiste: errore non_trovato.

GET /disponibilita

Solo le giacenze, leggere e veloci. Con ?sku=A,B,C (massimo 500 codici, di prodotto o di variante); senza sku restituisce tutte le varianti, paginate con pagina e per_pagina (massimo 1000).

{
  "aggiornato": "2026-10-16T08:00:00.000Z",
  "articoli": [
    {"sku":"TSRA150MWH","sku_prodotto":"TSRA150","disponibile":120,"in_arrivo":500,"stato":"disponibile"}
  ]
}

stato vale disponibile, esaurito oppure su_ordinazione (non c'è giacenza ma è in arrivo o ordinabile).

GET /feed.csv

Tutto il catalogo in un file, una riga per variante, separatore ;, UTF-8 con BOM, prezzi con il punto decimale. Si può chiamare anche dal browser con ?chiave=. Parametro facoltativo catalogo.

sku_prodotto;sku;nome;marca;categoria;colore;taglia;ean;prezzo_rivenditore;prezzo_consigliato;iva;disponibile;in_arrivo;immagine;immagini_extra

Esempi

curl
curl -H "X-Api-Key: LA_TUA_CHIAVE" \
  "https://www.citygraph.it/api/rivenditori/v1/disponibilita?sku=TSRA150MWH,TSRA150LWH"
PHP
<?php
$chiave = 'LA_TUA_CHIAVE'; // tienila nel server, non nel browser
$ch = curl_init('https://www.citygraph.it/api/rivenditori/v1/prodotti?catalogo=ingrosso&per_pagina=50');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . $chiave],
    CURLOPT_TIMEOUT => 20,
]);
$risposta = curl_exec($ch);
$codice = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$dati = json_decode($risposta, true);
if ($codice !== 200) { die($dati['messaggio'] ?? 'Errore'); }
foreach ($dati['prodotti'] as $p) {
    echo $p['sku'], ' ', $p['nome'], ' ', $p['prezzo_rivenditore'], " EUR\n";
}

Regola dei prezzi

prezzo_rivenditore è il nostro costo +30%, e non supera mai il prezzo pubblico della stessa quantità. È il prezzo a cui compri da noi. prezzo_consigliato è il prezzo che il nostro sito applica al pubblico per 1 pezzo: puoi usarlo come riferimento, ma il prezzo al tuo cliente lo decidi tu. Entrambi sono IVA esclusa (aliquota nel campo iva).

Limiti ed errori

Massimo 120 richieste al minuto per chiave. Per tenere il catalogo aggiornato bastano il feed CSV o /prodotti?modificati_dal=… una volta al giorno e /disponibilita ogni ora.

Gli errori hanno sempre questa forma, con il codice HTTP indicato:

{"errore":"chiave_non_valida","messaggio":"La chiave API non è valida."}
CodiceHTTPSignificato
chiave_mancante401Non hai inviato la chiave.
chiave_non_valida401La chiave non esiste o è sbagliata.
chiave_sospesa403La chiave è stata sospesa: contattaci.
non_trovato404Prodotto o codice non trovato.
troppe_richieste429Oltre 120 richieste al minuto con la stessa chiave.
errore_interno500Problema nostro: riprova tra poco.

Condizioni d'uso di foto e dati

Connettore WooCommerce

Plugin pronto da installare: importa prodotti e foto dal catalogo, applica il prezzo rivenditore e aggiorna le disponibilità ogni ora. Dopo l'installazione inserisci l'indirizzo del servizio e la tua chiave.

Scarica il connettore (.zip)

Non hai ancora la chiave? Richiedi maggiori informazioni. Per domande tecniche scrivi a info@citygraph.it.

WhatsApp Chiama

Area admin