Introduction
Reliez vos systèmes à scango.ch : produits, commandes, fournisseurs, catégories, magasins et journaux d’identité via une seule API REST.
L’API client de scango.ch permet à votre ERP, à votre comptabilité ou à votre gestion de stock de lire et de modifier les données de votre organisation : produits, commandes, fournisseurs, catégories, magasins et journaux d’identité.
URL de base
https://dashboard.scango.ch/api/v1Authentification
Créez une clé API dans le dashboard sous Paramètres → Organisation → Clés API (rôle Admin requis) et envoyez-la avec chaque requête :
Authorization: Bearer <api-key>| Type de clé | Autorise |
|---|---|
| Lecture | Toutes les requêtes GET |
| Écriture | Tout ce qu’autorise Lecture, plus la création, la modification et la suppression de produits et d’images produit, catégories, fournisseurs, magasins et identités bloquées |
Tout problème d’authentification ou d’autorisation renvoie 403 : clé absente,
inconnue ou inactive, ou clé Lecture sur une opération d’écriture.
Conventions
- Les montants sont des entiers en centimes :
120correspond à CHF 1.20. - Les dates dans les paramètres de requête sont en UTC au format ISO-8601
avec
Z, p. ex.2024-01-01T00:00:00.000Z. Les décalages comme+02:00sont refusés. - Les corps de requête sont en JSON. Les mises à jour utilisent
POSTavec un corps partiel. - Les réponses des listes sont
{ data, meta }, les éléments seuls{ data }; les écritures renvoient{ success: true }(avec le nouvelidà la création). - La suppression de produits, catégories, fournisseurs et magasins est
logique : l’élément disparaît des listes, mais
GETpar id le renvoie toujours avecdeleted: true. - Les erreurs sont en JSON :
{ statusCode, message, timestamp, path }. Les filtres de liste invalides renvoient{ error: { formErrors, fieldErrors } }.
Pagination
limit définit la taille de page : 100 par défaut, 5000 au maximum.
| Endpoint | Pagination |
|---|---|
| Produits, commandes, journaux d’identité, identités bloquées | Transmettre meta.nextCursor dans cursor jusqu’à l’absence de nextCursor |
Recherche de produits (q) |
offset, 250 par page au maximum |
| Catégories, fournisseurs, magasins | Sans pagination : une réponse avec jusqu’à limit éléments |
Les éléments supprimés logiquement sont filtrés après lecture : une page peut
donc être plus courte que limit alors que d’autres pages existent. Fiez-vous à
nextCursor, pas à returned < limit.
Commandes
start et end sont obligatoires et inclus ; paymentState est facultatif.
Les commandes arrivent de la plus récente à la plus ancienne. Les commandes
supprimées sont exclues, sauf avec includeDeleted=true.
Il n’y a pas de webhooks : interrogez régulièrement les nouvelles commandes, par exemple toutes les quelques minutes avec une fenêtre qui chevauche la précédente.
Images produit
Définissez imageUrl à la création ou à la mise à jour d’un produit, ou
téléversez un fichier avec POST /products/{productId}/image (champ multipart
file, 10 Mio max.). Supprimez-la avec DELETE /products/{productId}/image.
Étapes suivantes
Démarrage rapide
Votre première requête en quelques minutes.
Produits
Lister, rechercher et gérer votre assortiment.
Commandes
Exporter les ventes vers votre comptabilité.
Spécification OpenAPI
Générer un client ou importer l’API dans Postman.
Tous les endpoints en un coup d’œil : référence de l’API.
Des questions ? Écrivez à support@scango.ch.