Trovare le cose
Id interni e chiavi naturali: codici, EAN, partite IVA, numeri documento.
Id e chiavi naturali
L'id interno è l'identità (/articoli/123), ma un sistema esterno in genere non li conosce: per questo ogni risorsa accetta anche le chiavi naturali.
| Risorsa | Chiavi accettate |
|---|---|
| Articoli | id · codice (anche di variante) · EAN |
| Clienti | id · partita IVA · codice fiscale · email · codice tessera |
| Fornitori | id · partita IVA |
| Documenti | id · numero + sezionale + anno |
| Righe d'ordine (arrivi) | id riga · etichetta collo · codice/EAN dell'articolo atteso |
La ricerca col corpo JSON
Su ogni risorsa c'è POST /…/cerca: i filtri viaggiano nel corpo, che regge qualunque carattere e anche le liste (fino a 100 chiavi per volta):
curl -X POST https://tuaazienda.siriocloud.it/api/v1/articoli/cerca \
-H 'Authorization: Bearer sc_live_LATUACHIAVE' -H 'Content-Type: application/json' \
-d '{ "codici": ["ART-001", "ART-002", "ART-003"] }'La tolleranza sull'EAN
Un codice a barre corrisponde sia per valore esatto sia sulle prime 12 cifre (la tolleranza tipica dei lettori). Se l'EAN appartiene a una variante, la risposta lo indica:
POST /api/v1/articoli/cerca { "ean": "8001234567897" }
→ { "articoli": [ { "id": 17, "codice": "ART-001", …,
"variante_corrispondente": { "id": 42, "codice": "ART-001-ROSSO" } } ] }Gli upsert
Su articoli, clienti e fornitori il PUT fa «crea o aggiorna» con la chiave nel corpo: gli articoli per codice, i clienti per partita IVA (o codice fiscale per i privati), i fornitori per partita IVA. Esiste = aggiornamento parziale, manca = creazione con le validazioni piene; "se_manca": "errore" per il solo aggiornamento. Se la chiave identifica più di un record la risposta è 409 chiave_ambigua: l'aggiornamento richiede l'id esplicito.
Gli articoli con varianti
Un articolo con varianti (taglie, colori…) non si scrive mai «sul padre»: quantità, prezzi e movimenti appartengono alla variante. Le scritture senza variante su un articolo che le ha vengono rifiutate col motivo; le varianti si leggono da GET /articoli/{id}/varianti.