API ChronoStock

Lettura dell'inventario di un negozio, in sola lettura. Versione 1.

Questa API serve a mostrare sul sito di un rivenditore gli orologi che ha in ChronoStock, sempre aggiornati. È di sola lettura: non consente di creare, modificare o cancellare nulla.

Ogni negozio ha una propria chiave. Con quella chiave si vedono solo gli orologi di quel negozio.

Autenticazione

La chiave va nell'intestazione X-API-Key di ogni richiesta. Ha la forma cs_live_ seguita da 32 caratteri.

curl -H "X-API-Key: cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://api.chronostock.xyz/v1/watches

La chiave è un segreto. Va usata dal server del sito, mai dal codice JavaScript della pagina: lì sarebbe leggibile da chiunque apra gli strumenti per sviluppatori. Se una chiave viene esposta, il negozio ne chiede una nuova e la vecchia smette di funzionare all'istante.

Elenco orologi

GET https://api.chronostock.xyz/v1/watches

Parametri

Parametro	Tipo	Descrizione
limit	numero	Quanti orologi per pagina. Predefinito 100, massimo 500.
cursor	testo	Il valore `next_cursor` ricevuto dalla pagina precedente.

Risposta

{
  "watches": [
    {
      "id": "1743512400000-k29fa1x7q",
      "marca": "Rolex",
      "modello": "Submariner Date",
      "referenza": "126610LN",
      "anno": 2022,
      "condizione": "Ottimo",
      "disponibilita": "disponibile",
      "prezzo": 13500,
      "valuta": "EUR",
      "materiale": "Acciaio",
      "colore": "Nero",
      "quadrante": "Indici",
      "bracciale": "Oyster",
      "corredo": ["Scatola", "Garanzia"],
      "punto_vendita": "Milano",
      "foto": [
        "https://firebasestorage.googleapis.com/...jpg",
        "https://firebasestorage.googleapis.com/...jpg"
      ],
      "foto_anteprima": "https://firebasestorage.googleapis.com/...jpg",
      "aggiornato_il": "2026-08-14T09:31:02.481Z"
    }
  ],
  "count": 1,
  "next_cursor": "1743512400000-k29fa1x7q"
}

Paginazione

Quando next_cursor non è null, ci sono altri orologi. Si richiama lo stesso indirizzo passando quel valore come cursor.

Fermarsi solo quando next_cursor è null, mai quando una pagina contiene meno elementi di limit. È la regola che evita di mostrare un catalogo incompleto.

async function tuttiGliOrologi(chiave) {
  const orologi = [];
  let cursor = null;

  do {
    const url = new URL('https://api.chronostock.xyz/v1/watches');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const r = await fetch(url, { headers: { 'X-API-Key': chiave } });
    if (!r.ok) throw new Error('API ' + r.status);

    const dati = await r.json();
    orologi.push(...dati.watches);
    cursor = dati.next_cursor;
  } while (cursor);

  return orologi;
}

Singolo orologio

GET https://api.chronostock.xyz/v1/watches/{id}

Restituisce { "watch": { ... } } con gli stessi campi dell'elenco. Risponde 404 se l'orologio non esiste, appartiene a un altro negozio, oppure è stato venduto.

I campi

Campo	Tipo	Note
id	testo	Identificativo stabile. Usalo come chiave sul tuo sito.
marca	testo o null
modello	testo o null
referenza	testo o null	Il numero di referenza del produttore.
anno	numero o null
condizione	testo o null	Nuovo, NOS, Ottimo, Buono, Discreto, Da revisionare.
disponibilita	testo	`disponibile` oppure `prenotato`.
prezzo	numero o null	Prezzo di vendita richiesto. Può essere null se il negozio non lo ha indicato.
valuta	testo o null	Codice a tre lettere, es. EUR. È null quando è null il prezzo.
materiale	testo o null
colore	testo o null	Colore del quadrante.
quadrante	testo o null	Indici, Roman, Diamonds.
bracciale	testo o null
corredo	elenco	Scatola, Garanzia, Corredo, Pellicolato, Parzialmente pellicolato, Quadranti. Può essere vuoto.
punto_vendita	testo o null	Sede in cui si trova l'orologio, se il negozio ne ha più di una.
foto	elenco	Indirizzi diretti, usabili in un tag `<img>`.
foto_anteprima	testo o null	Versione ridotta della prima foto, per le liste.
aggiornato_il	testo o null	Data ISO 8601 dell'ultima modifica.

Cosa non viene mai esposto

Sono esclusi per scelta, e non è possibile richiederli: prezzo d'acquisto, prezzo di listino, prezzo di vendita realizzato, fornitore, note interne, storico dei prezzi, date di acquisto e vendita, dati di chi ha prenotato, e il numero di serie.

Sono esclusi anche gli orologi venduti. Un orologio che sparisce dall'elenco è stato venduto: il sito dovrebbe toglierlo dal catalogo, o segnarlo come non più disponibile.

Errori

Codice	Significato
401	Chiave mancante, malformata o revocata.
404	Indirizzo inesistente, oppure orologio non trovato, di un altro negozio o venduto.
405	Metodo diverso da GET. L'API è di sola lettura.
429	Troppe richieste: il limite è 240 al minuto per chiave.
500	Errore del servizio. Riprova più tardi.

Il corpo dell'errore è sempre { "error": "..." }.

Frequenza di aggiornamento

Le risposte hanno Cache-Control: private, max-age=60: sono valide per un minuto. Non serve interrogare l'API più spesso di così. Per un catalogo, aggiornare ogni 10-15 minuti è più che sufficiente e riduce il carico su entrambi i lati.