Einführung

Verbinden Sie Ihre Systeme mit scango.ch: Produkte, Bestellungen, Lieferanten, Kategorien, Filialen und Identitätsprotokolle über eine REST-API.

Mit der Kunden-API von scango.ch lesen und ändern ERP-, Buchhaltungs- oder Warenwirtschaftssysteme die Daten Ihrer Organisation: Produkte, Bestellungen, Lieferanten, Kategorien, Filialen und Identitätsprotokolle.

Basis-URL

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

Authentifizierung

Erstellen Sie im Dashboard unter Einstellungen → Organisation → API-Schlüssel einen API-Schlüssel (Admin-Rolle erforderlich) und senden Sie ihn bei jeder Anfrage mit:

Authorization: Bearer <api-key>

Jedes Authentifizierungs- oder Berechtigungsproblem liefert 403: ein fehlender, unbekannter oder inaktiver Schlüssel oder ein Lese-Schlüssel bei einem Schreibzugriff.

Konventionen

• Geldbeträge sind Ganzzahlen in Rappen: 120 entspricht CHF 1.20.
• Datumsangaben in Query-Parametern sind UTC im ISO-8601-Format mit Z, z. B. 2024-01-01T00:00:00.000Z. Offsets wie +02:00 werden abgelehnt.
• Request-Bodys sind JSON. Aktualisierungen verwenden POST mit einem partiellen Body.
• Antworten von Listen sind { data, meta }, einzelne Einträge { data }; Schreibzugriffe liefern { success: true } (beim Anlegen mit der neuen id).
• Löschen von Produkten, Kategorien, Lieferanten und Filialen ist ein Soft-Delete: Der Eintrag fehlt in Listen, GET per ID liefert ihn aber weiterhin mit deleted: true.
• Fehler sind JSON: { statusCode, message, timestamp, path }. Ungültige Listenfilter liefern { error: { formErrors, fieldErrors } }.

Paginierung

limit bestimmt die Seitengrösse: Standard 100, höchstens 5000.

Soft-gelöschte Einträge werden nach dem Lesen herausgefiltert. Eine Seite kann daher kürzer als limit sein, obwohl weitere Seiten existieren. Verlassen Sie sich auf nextCursor, nicht auf returned < limit.

Bestellungen

start und end sind Pflicht und inklusive; paymentState ist optional. Bestellungen kommen neueste zuerst. Gelöschte Bestellungen fehlen, ausser mit includeDeleted=true.

Es gibt keine Webhooks: Fragen Sie neue Bestellungen regelmässig ab, zum Beispiel alle paar Minuten mit einem Zeitfenster, das sich mit dem vorherigen überschneidet.

Produktbilder

Setzen Sie imageUrl beim Anlegen oder Aktualisieren eines Produkts oder laden Sie eine Datei mit POST /products/{productId}/image hoch (Multipart-Feld file, max. 10 MiB). Entfernen mit DELETE /products/{productId}/image.

Nächste Schritte

Alle Endpunkte im Überblick: API-Referenz.

Fragen? Schreiben Sie an support@scango.ch.