Développeurs

API

L'API scango.ch relie votre caisse en libre-service à d'autres programmes, par exemple un logiciel de gestion des stocks, un ERP, votre comptabilité ou une boutique en ligne. L'API est une interface REST : un programme envoie des requêtes HTTPS et reçoit des données au format JSON.

L'accès nécessite une clé API, que les Admins et les Propriétaires créent dans le tableau de bord. La référence technique complète avec tous les endpoints et champs se trouve sur developers.scango.ch.

À quoi sert l'API ?

  • Reprendre les produits d'un logiciel de gestion des stocks et tenir à jour les prix ou les stocks
  • Récupérer régulièrement les commandes, p. ex. pour la comptabilité ou votre propre reporting
  • Synchroniser fournisseurs, catégories et magasins avec un autre système
  • Gérer les journaux d'identité et la liste de blocage si vous utilisez le Contrôle de l’âge Stellard Age

Créer une clé API

Liste des clés API avec description, type et date de création
  1. Ouvrez Paramètres › Organisation › Clés API.
  2. Cliquez sur Créer une clé API.
  3. Saisissez une Description qui vous permettra de reconnaître la clé plus tard, p. ex. « Comptabilité » ou « Boutique en ligne ».
  4. Choisissez le Type : Lecture permet uniquement de récupérer des données, Écriture permet en plus de créer, modifier et supprimer.
  5. Cliquez sur Créer.
  6. La nouvelle clé s'affiche. Copiez-la avec l'icône de copie et enregistrez-la dans le programme qui doit accéder à l'API.
Dialogue Créer une clé API avec description et type

La liste affiche toutes les clés avec Description, Type (Read ou Write) et la date sous Créée. Avec Afficher la clé API, les admins et les propriétaires peuvent afficher et copier une clé plus tard. Supprimer la clé API rend une clé immédiatement invalide ; les intégrations qui l'utilisent cessent de fonctionner.

Authentification

Toutes les requêtes sont adressées à l'URL de base :

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

Envoyez la clé API à chaque requête dans l'en-tête Authorization sous la forme Bearer <clé API>. Si la clé manque, est invalide ou a été supprimée, l'API répond avec le statut 403. Il en va de même si vous tentez de modifier des données avec une clé de type Lecture.

Exemple : récupérer les cinq premiers produits.

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

La réponse contient les entrées sous data et des informations sur la liste sous meta, p. ex. limit et returned.

Ressources

Ressource

Chemin

Avec le type Lecture

En plus avec le type Écriture

Produits

/products

lister, rechercher, récupérer individuellement

créer, modifier, supprimer, téléverser et supprimer l'image du produit

Commandes

/orders

lister pour une période, récupérer individuellement

—

Fournisseurs

/suppliers

lister, récupérer individuellement

créer, modifier, supprimer

Catégories

/categories

lister, récupérer individuellement

créer, modifier, supprimer

Magasins

/stores

lister, récupérer individuellement

créer, modifier, supprimer

Journaux d'identité

/identity-logs

lister et récupérer les scans, lister la liste de blocage

créer, modifier, supprimer des blocages

Règles importantes

  • Montants en centimes : les montants sont des nombres entiers en centimes, 120 signifie CHF 1.20.
  • Listes : les listes renvoient { data, meta }. Avec limit, vous définissez le nombre d'entrées par réponse (100 par défaut, 5000 au maximum).
  • Pagination : si meta contient une valeur nextCursor, récupérez la page suivante avec le paramètre cursor. Continuez tant que nextCursor est présent ; moins d'entrées que limit ne signifie pas que la liste est terminée.
  • Commandes : pour lister, start et end (date et heure au format ISO 8601) sont obligatoires. paymentState permet de filtrer par statut (successful, pending, cancelled, timeout, failed). Les commandes supprimées sont exclues, sauf si vous indiquez includeDeleted=true.
  • Pas de webhooks : l'API ne signale pas d'elle-même les nouvelles commandes. Interrogez-la à intervalles réguliers.
  • Protéger les clés : une clé API donne accès aux données de votre organisation. Utilisez-la uniquement sur un serveur, jamais dans le code d'un site web ou d'une application, et ne la transmettez pas. Créez une clé distincte par intégration et choisissez Lecture si aucune donnée ne doit être modifiée.

Documentation complète

Tous les endpoints, paramètres, champs et d'autres exemples figurent dans la documentation pour développeurs sur developers.scango.ch. La description OpenAPI est disponible au téléchargement sous developers.scango.ch/openapi/scango.json.