Introduzione
Collegate i vostri sistemi a scango.ch: prodotti, ordini, fornitori, categorie, negozi e log di identità tramite un’unica API REST.
L’API clienti di scango.ch permette al vostro ERP, alla contabilità o alla gestione del magazzino di leggere e modificare i dati della vostra organizzazione: prodotti, ordini, fornitori, categorie, negozi e log di identità.
URL di base
https://dashboard.scango.ch/api/v1Autenticazione
Create una chiave API nel dashboard in Impostazioni → Organizzazione → Chiavi API (ruolo Admin richiesto) e inviatela con ogni richiesta:
Authorization: Bearer <api-key>| Tipo di chiave | Consente |
|---|---|
| Lettura | Tutte le richieste GET |
| Scrittura | Tutto ciò che consente Lettura, più creare, modificare ed eliminare prodotti e immagini prodotto, categorie, fornitori, negozi e identità bloccate |
Ogni problema di autenticazione o autorizzazione restituisce 403: chiave
mancante, sconosciuta o inattiva, oppure chiave Lettura su un’operazione di
scrittura.
Convenzioni
- Gli importi sono interi in centesimi:
120corrisponde a CHF 1.20. - Le date nei parametri query sono in UTC ISO-8601 con
Z, ad es.2024-01-01T00:00:00.000Z. Offset come+02:00vengono rifiutati. - I body delle richieste sono JSON. Gli aggiornamenti usano
POSTcon un body parziale. - Le risposte degli elenchi sono
{ data, meta }, i singoli elementi{ data }; le scritture restituiscono{ success: true }(con il nuovoidalla creazione). - L’eliminazione di prodotti, categorie, fornitori e negozi è un
soft-delete: l’elemento sparisce dagli elenchi, ma
GETper id lo restituisce ancora condeleted: true. - Gli errori sono JSON:
{ statusCode, message, timestamp, path }. I filtri di elenco non validi restituiscono{ error: { formErrors, fieldErrors } }.
Paginazione
limit imposta la dimensione della pagina: predefinito 100, massimo 5000.
| Endpoint | Paginazione |
|---|---|
| Prodotti, ordini, log di identità, identità bloccate | Passare meta.nextCursor come cursor finché nextCursor è assente |
Ricerca prodotti (q) |
offset, al massimo 250 per pagina |
| Categorie, fornitori, negozi | Senza paginazione: una risposta con fino a limit elementi |
Gli elementi eliminati (soft-delete) vengono filtrati dopo la lettura, quindi
una pagina può essere più corta di limit anche se esistono altre pagine.
Basatevi su nextCursor, non su returned < limit.
Ordini
start ed end sono obbligatori e inclusi; paymentState è facoltativo. Gli
ordini arrivano dal più recente. Gli ordini eliminati sono esclusi, salvo con
includeDeleted=true.
Non ci sono webhook: interrogate regolarmente i nuovi ordini, ad esempio ogni pochi minuti con una finestra che si sovrappone alla precedente.
Immagini prodotto
Impostate imageUrl quando create o aggiornate un prodotto, oppure caricate un
file con POST /products/{productId}/image (campo multipart file, max.
10 MiB). Rimuovetela con DELETE /products/{productId}/image.
Passi successivi
Guida rapida
La prima richiesta in pochi minuti.
Prodotti
Elencare, cercare e gestire l’assortimento.
Ordini
Esportare le vendite nella contabilità.
Specifica OpenAPI
Generare un client o importare l’API in Postman.
Tutti gli endpoint in sintesi: riferimento API.
Domande? Scrivete a support@scango.ch.