Sviluppatori

API

L'API scango.ch collega la sua cassa self-service ad altri programmi, ad es. un gestionale di magazzino, un ERP, la sua contabilità o un negozio online. L'API è un'interfaccia REST: un programma invia richieste HTTPS e riceve dati in formato JSON.

Per l'accesso serve una chiave API, che Amministratori e Proprietari creano nella dashboard. Il riferimento tecnico completo con tutti gli endpoint e i campi si trova su developers.scango.ch.

A cosa serve l'API?

  • Riprendere i prodotti da un gestionale di magazzino e mantenere aggiornati prezzi o giacenze
  • Scaricare regolarmente gli ordini, ad es. per la contabilità o per un reporting proprio
  • Sincronizzare fornitori, categorie e negozi con un altro sistema
  • Gestire i log identità e la lista di blocco se utilizza il Controllo dell’età Stellard Age

Creare una chiave API

Elenco delle chiavi API con descrizione, tipo e data di creazione
  1. Apra Impostazioni › Organizzazione › Chiavi API.
  2. Clicchi su Crea chiave API.
  3. Inserisca una Descrizione con cui riconoscere la chiave in seguito, ad es. «Contabilità» o «Negozio online».
  4. Scelga il Tipo: Lettura consente solo di leggere i dati, Scrittura anche di creare, modificare ed eliminare.
  5. Clicchi su Crea.
  6. Viene mostrata la nuova chiave. La copi con l'icona di copia e la inserisca nel programma che deve accedere all'API.
Finestra Crea chiave API con descrizione e tipo

L'elenco mostra tutte le chiavi con Descrizione, Tipo (Read o Write) e la data in Creata. Con Mostra chiave API amministratori e proprietari possono visualizzare e copiare di nuovo una chiave in seguito. Elimina chiave API rende subito non valida una chiave; le integrazioni che la usano smettono di funzionare.

Autenticazione

Tutte le richieste vanno all'URL di base:

https://dashboard.scango.ch/api/v1

Invii la chiave API a ogni richiesta nell'header Authorization come Bearer <chiave API>. Se la chiave manca, non è valida o è stata eliminata, l'API risponde con lo stato 403. Lo stesso vale se tenta di modificare dati con una chiave di tipo Lettura.

Esempio: leggere i primi cinque prodotti.

curl -H "Authorization: Bearer $SCANGO_API_KEY" \
  "https://dashboard.scango.ch/api/v1/products?limit=5"

La risposta contiene le voci in data e le informazioni sull'elenco in meta, ad es. limit e returned.

Risorse

Risorsa

Percorso

Con tipo Lettura

In più con tipo Scrittura

Prodotti

/products

elencare, cercare, leggere singolarmente

creare, modificare, eliminare, caricare ed eliminare l'immagine del prodotto

Ordini

/orders

elencare per un periodo, leggere singolarmente

—

Fornitori

/suppliers

elencare, leggere singolarmente

creare, modificare, eliminare

Categorie

/categories

elencare, leggere singolarmente

creare, modificare, eliminare

Negozi

/stores

elencare, leggere singolarmente

creare, modificare, eliminare

Log identità

/identity-logs

elencare e leggere le scansioni, elencare la lista di blocco

creare, modificare, eliminare blocchi

Regole importanti

  • Importi in centesimi: gli importi sono numeri interi in centesimi, 120 significa CHF 1.20.
  • Elenchi: gli elenchi restituiscono { data, meta }. Con limit stabilisce quante voci contiene una risposta (predefinito 100, massimo 5000).
  • Paginazione: se meta contiene un valore nextCursor, legga la pagina successiva con il parametro cursor. Continui finché nextCursor è presente; meno voci di limit non significano che l'elenco sia finito.
  • Ordini: per elencarli, start e end (data e ora in formato ISO 8601) sono obbligatori. Con paymentState filtra per stato (successful, pending, cancelled, timeout, failed). Gli ordini eliminati sono esclusi, a meno che indichi includeDeleted=true.
  • Nessun webhook: l'API non segnala da sola i nuovi ordini. La interroghi a intervalli regolari.
  • Proteggere le chiavi: una chiave API dà accesso ai dati della sua organizzazione. La usi solo su un server, mai nel codice di un sito web o di un'app, e non la divulghi. Crei una chiave separata per ogni integrazione e scelga Lettura se non occorre modificare dati.

Documentazione completa

Tutti gli endpoint, i parametri, i campi e altri esempi si trovano nella documentazione per sviluppatori su developers.scango.ch. La descrizione OpenAPI è scaricabile all'indirizzo developers.scango.ch/openapi/scango.json.