Entwickler

API

Über die scango.ch-API verbindest du deine Selbstbedienungskasse mit anderen Programmen, z. B. mit einer Warenwirtschaft, einem ERP, deiner Buchhaltung oder einem Webshop. Die API ist eine REST-Schnittstelle: Ein Programm sendet HTTPS-Anfragen und erhält Daten im JSON-Format zurück.

Für den Zugriff braucht es einen API-Schlüssel. Diesen erstellen Admins und Eigentümer im Dashboard. Die vollständige technische Referenz mit allen Endpunkten und Feldern findest du auf developers.scango.ch.

Wofür eignet sich die API?

  • Produkte aus einer Warenwirtschaft übernehmen und Preise oder Bestände aktuell halten
  • Einkäufe regelmässig abholen, z. B. für die Buchhaltung oder ein eigenes Reporting
  • Lieferanten, Kategorien und Filialen mit einem anderen System abgleichen
  • Ausweis-Logs und Sperrliste verwalten, wenn du die Alterskontrolle Stellard Age nutzen

API-Schlüssel erstellen

Liste der API-Schlüssel mit Beschreibung, Typ und Erstellungsdatum
  1. Öffne Einstellungen › Organisation › API-Schlüssel.
  2. Klick auf API Key erstellen.
  3. Gib eine Beschreibung ein, an der du den Schlüssel später erkennst, z. B. «Buchhaltung» oder «Webshop».
  4. Wähl den Typ: Lesen erlaubt nur das Abrufen von Daten, Schreiben zusätzlich das Anlegen, Ändern und Löschen.
  5. Klick auf Erstellen.
  6. Der neue Schlüssel wird angezeigt. Kopiere ihn mit dem Kopier-Symbol und hinterlege ihn im Programm, das auf die API zugreifen soll.
Dialog API Key erstellen mit Beschreibung und Typ

Die Liste zeigt alle Schlüssel mit Beschreibung, Typ (Read oder Write) und Datum unter Erstellt. Mit API-Schlüssel anzeigen können Admins und Eigentümer einen Schlüssel später erneut anzeigen und kopieren. API-Schlüssel löschen macht einen Schlüssel sofort ungültig; Integrationen mit diesem Schlüssel funktionieren danach nicht mehr.

Authentifizierung

Alle Anfragen gehen an die Basis-URL:

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

Den API-Schlüssel sendest du bei jeder Anfrage im Header Authorization als Bearer <API-Schlüssel>. Fehlt der Schlüssel, ist er ungültig oder gelöscht, antwortet die API mit dem Status 403. Dasselbe gilt, wenn du mit einem Schlüssel vom Typ Lesen Daten ändern wollen.

Beispiel: die ersten fünf Produkte abrufen.

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

Die Antwort enthält die Einträge unter data und Angaben zur Liste unter meta, z. B. limit und returned.

Ressourcen

Ressource

Pfad

Mit Typ Lesen

Zusätzlich mit Typ Schreiben

Produkte

/products

auflisten, suchen, einzeln abrufen

anlegen, ändern, löschen, Produktbild hochladen und löschen

Einkäufe

/orders

für einen Zeitraum auflisten, einzeln abrufen

—

Lieferanten

/suppliers

auflisten, einzeln abrufen

anlegen, ändern, löschen

Kategorien

/categories

auflisten, einzeln abrufen

anlegen, ändern, löschen

Filialen

/stores

auflisten, einzeln abrufen

anlegen, ändern, löschen

Ausweis-Logs

/identity-logs

Scans auflisten und abrufen, Sperrliste auflisten

Sperren anlegen, ändern, löschen

Wichtige Regeln

  • Beträge in Rappen: Geldbeträge sind ganze Zahlen in Rappen, 120 bedeutet CHF 1.20.
  • Listen: Listen liefern { data, meta }. Mit limit legst du fest, wie viele Einträge eine Antwort enthält (Standard 100, höchstens 5000).
  • Blättern: Enthält meta einen Wert nextCursor, holst du die nächste Seite mit dem Parameter cursor. Blättere weiter, solange nextCursor vorhanden ist; weniger Einträge als limit bedeuten nicht, dass die Liste zu Ende ist.
  • Einkäufe: Beim Auflisten sind start und end (Datum und Uhrzeit im ISO-8601-Format) Pflicht. Mit paymentState filterst du nach Status (successful, pending, cancelled, timeout, failed). Gelöschte Einkäufe fehlen, ausser du gibst includeDeleted=true an.
  • Keine Webhooks: Die API meldet neue Einkäufe nicht von sich aus. Frag sie in regelmässigen Abständen ab.
  • Schlüssel schützen: Ein API-Schlüssel gewährt Zugriff auf die Daten deiner Organisation. Verwende ihn nur auf einem Server, nie im Code einer Webseite oder App, und gib ihn nicht weiter. Erstell pro Integration einen eigenen Schlüssel und wähl Lesen, wenn keine Daten geändert werden müssen.

Vollständige Dokumentation

Alle Endpunkte, Parameter, Felder und weitere Beispiele findest du in der Entwicklerdokumentation auf developers.scango.ch. Die OpenAPI-Beschreibung steht unter developers.scango.ch/openapi/scango.json zum Download bereit.