API rivenditori CityShirt

• Base e autenticazione
• Regola prezzi
• stato
• prodotti
• disponibilità
• feed.csv
• Esempi
• Limiti ed errori
• Connettore WooCommerce
• Condizioni d'uso

Indirizzo base e autenticazione

Indirizzo base: https://www.cityshirt.it/api/rivenditori/v1. Tutte le risposte sono JSON UTF-8 (Content-Type: application/json; charset=utf-8, Cache-Control: no-store). Sono ammesse solo richieste GET (CORS aperto per le GET).

Ogni richiesta porta la tua chiave (inizia con csr_, seguita da 40 caratteri):

X-Api-Key: csr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

In alternativa Authorization: Bearer <chiave>. Solo per il feed CSV (che si apre anche da un programma di importazione) è ammesso ?chiave=<chiave> nell'indirizzo. Tieni la chiave riservata: non scriverla nel codice pubblico del sito.

Regola dei prezzi

Tutti i prezzi sono in euro, IVA esclusa, con due decimali.

• prezzo_rivenditore = il nostro costo +30%, e mai sopra il prezzo che paga il pubblico per la stessa quantità. Nelle API è il prezzo per 1 pezzo; ordinando oltre 500 pezzi dello stesso articolo il ricarico scende al +20%, come per il pubblico.
• prezzo_consigliato = il nostro prezzo al pubblico per 1 pezzo, IVA esclusa. Puoi usarlo come riferimento per il tuo listino.
• Il costo di acquisto da noi non viene mai mostrato.

GET/stato

Controlla che la chiave funzioni e quanti prodotti ci sono.

{"ok":true,"negozio":"cityshirt.it","versione_api":"1","rivenditore":"La Tua Azienda","prodotti":394,"aggiornato":"2026-10-17T10:00:00+02:00"}

GET/prodotti

Parametro	Significato
pagina, per_pagina	Paginazione. Predefinito 1 e 100; massimo 250 prodotti per pagina.
catalogo	tutti (predefinito), ingrosso oppure gadget. Su cityshirt.it il catalogo è l'ingrosso (capi neutri); gadget restituisce una lista vuota.
categoria	Codice categoria (categoria_slug), per esempio tshirt, felpa, polo.
q	Cerca nel nome, codice, marca e categoria.
modificati_dal	Data ISO 8601: solo i prodotti aggiornati da quel momento (per sincronizzare solo le novità).

Risposta: {"pagina":1,"per_pagina":100,"totale":N,"pagine":P,"prodotti":[…]}. Un prodotto:

{
  "sku": "TSRA150",
  "nome": "T-shirt 150 Manica Corta",
  "catalogo": "ingrosso",
  "marca": "JHK",
  "categoria": "T-shirt",
  "categoria_slug": "tshirt",
  "descrizione": "<p>…</p>",
  "immagini": ["https://www.cityshirt.it/assets/uploads/dga/TSRA150.jpg"],
  "prezzo_rivenditore": 2.25,
  "prezzo_consigliato": 2.42,
  "iva": 22,
  "valuta": "EUR",
  "quantita_minima": 1,
  "disponibile": 5320,
  "varianti": [
    {"sku":"TSRA150MWH","colore":"Bianco","hex":"#ffffff","taglia":"M","ean":"8445481178398",
     "disponibile":500,"in_arrivo":0,"prezzo_rivenditore":2.25,"prezzo_consigliato":2.42,
     "immagine":"https://www.cityshirt.it/assets/uploads/dga/TSRA150.jpg"}
  ],
  "aggiornato": "2026-10-17T10:00:00+02:00"
}

Un solo prodotto: GET /prodotti/{sku} (codice del prodotto, maiuscole o minuscole). Se il fornitore indica "500+" pezzi, disponibile vale 500. Le immagini sono sempre indirizzi completi.

GET/disponibilita

Giacenze aggiornate. Con ?sku=TSRA150MWH,TSRA150LWH (fino a 500 codici, di prodotto o di variante); senza sku restituisce tutte le varianti, a pagine (pagina, per_pagina, massimo 1000).

{"aggiornato":"2026-10-17T10:00:00+02:00","articoli":[
  {"sku":"TSRA150MWH","sku_prodotto":"TSRA150","disponibile":500,"in_arrivo":0,"stato":"disponibile"}
]}

stato può essere disponibile, esaurito o su_ordinazione (non a magazzino ma ordinabile: arriva su prenotazione).

GET/feed.csv?chiave=…

Un file CSV con una riga per variante, separatore ;, UTF-8 con BOM, prezzi con il punto decimale. Colonne:

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

immagini_extra contiene gli altri indirizzi foto separati da |.

Esempi

curl

curl -H "X-Api-Key: LA_TUA_CHIAVE" "https://www.cityshirt.it/api/rivenditori/v1/stato"
curl -H "X-Api-Key: LA_TUA_CHIAVE" "https://www.cityshirt.it/api/rivenditori/v1/prodotti?categoria=tshirt&per_pagina=50"
curl -H "X-Api-Key: LA_TUA_CHIAVE" "https://www.cityshirt.it/api/rivenditori/v1/disponibilita?sku=TSRA150MWH,TSRA150LWH"
curl -o feed.csv "https://www.cityshirt.it/api/rivenditori/v1/feed.csv?chiave=LA_TUA_CHIAVE"

PHP

<?php
$chiave = "LA_TUA_CHIAVE";   // meglio nel file di configurazione, fuori dal webroot
$ch = curl_init("https://www.cityshirt.it/api/rivenditori/v1/prodotti?per_pagina=100");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ["X-Api-Key: $chiave"]]);
$risposta = curl_exec($ch);
$codice = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$dati = json_decode($risposta, true);
if ($codice !== 200) { exit("Errore: " . ($dati["messaggio"] ?? $codice)); }
foreach ($dati["prodotti"] as $p) {
    echo $p["sku"], " ", $p["nome"], " ", $p["prezzo_rivenditore"], " EUR + IVA\n";
}

Limiti e codici di errore

Massimo 120 richieste al minuto per chiave. Meglio sincronizzare il catalogo una volta al giorno (usa modificati_dal) e le disponibilità ogni ora o a ogni carrello, con l'elenco degli sku che servono.

Gli errori hanno questa forma: {"errore":"chiave_non_valida","messaggio":"La chiave API non è valida."}

HTTP	errore	Quando
401	chiave_mancante	Nessuna chiave nella richiesta.
401	chiave_non_valida	La chiave non esiste o è scritta male.
403	chiave_sospesa	La chiave è stata sospesa: contattaci.
404	non_trovato	Indirizzo o prodotto inesistente.
400	richiesta_non_valida	Parametro non corretto (per esempio una data sbagliata).
429	troppe_richieste	Superato il limite di 120 richieste al minuto: aspetta 60 secondi.
500	errore_interno	Problema nostro: riprova tra poco o scrivici.

Connettore per WooCommerce

Il plugin importa i prodotti nel tuo WooCommerce, aggiorna prezzi e disponibilità ogni ora e usa la chiave che ti abbiamo dato. Si installa da Plugin › Aggiungi nuovo › Carica plugin.

Scarica cgfa-connettore-rivenditori.zip

Condizioni d'uso di foto e dati

• Foto, descrizioni e prezzi si usano solo per vendere i prodotti CityShirt e solo finché il programma rivenditori è attivo.
• È vietato rivendere, cedere o pubblicare i dati del catalogo a terzi, e usare la chiave su siti diversi da quello concordato.
• Se il programma termina, o la chiave viene sospesa, vanno tolti dal tuo sito prodotti e foto.
• Programma riservato a chi ha partita IVA. Prezzi IVA esclusa.

Dubbi? Scrivici su WhatsApp o a info@cityshirt.it.