Guide
Authentification et droits
Une clé par intégration, des droits choisis par le commerçant, un périmètre d’établissements.
La clé d’API
Chaque appel porte une clé dans l’en-tête Authorization :
Authorization: Bearer gsk_…
- Qui la crée : le commerçant, dans Paramètres › Intégrations, onglet Clés API, bouton Nouvelle clé partenaire. Seul un administrateur de l’établissement peut le faire.
- Quand on la voit : une seule fois, à la création. Gillia n’en garde qu’une empreinte : une clé perdue ne se retrouve pas, le commerçant en crée une autre.
- Ce qu’elle porte : l’enseigne du commerçant, les droits qu’il a choisis et, s’il l’a voulu, une liste d’établissements.
- Comment elle s’arrête : le commerçant la révoque dans le même écran. L’arrêt est immédiat ; vos appels reçoivent alors
401.
Le commerçant voit dans ce tableau la date du dernier appel de chaque clé : une clé inutilisée se repère.
Les droits
Le commerçant choisit un niveau par domaine. Chaque niveau correspond à un ou plusieurs droits techniques, ceux que la référence indique sur chaque route.
| Domaine (écran) | Niveau | Droits techniques | Ce que ça ouvre |
|---|---|---|---|
| Clients | Lecture | pos.customers.read | Lister et lire les clients |
| Clients | Lecture et écriture | pos.customers.read pos.customers.write | Créer et modifier des clients |
| Catalogue | Lecture | pos.catalog.read | Articles, catégories, images, zones, niveaux de stock |
| Catalogue | Lecture et écriture | pos.catalog.read pos.catalog.write | Créer et modifier des articles et leurs images |
| Ventes | Lecture | pos.sales.read | Tickets de caisse, clôture (Z) d’une journée, solde d’un bon d’achat |
| Stock | Enregistrer | pos.inventory.write | Ajustements de stock |
| Commandes partenaires | Envoyer et suivre | pos.orders.write | Commandes venues d’ailleurs, commandes partenaires, webhook |
| Bons d’achat | Émettre | pos.vouchers.write | Émettre un bon d’achat, prolonger sa validité |
| Achats fournisseurs | Lecture | pos.purchases.read | Commandes fournisseurs et réceptions |
| Comptabilité | Lecture | pos.accounting.read | Écritures comptables et FEC de toute l’enseigne (clé non limitée à des établissements). Pour l’instant accordé par OAuth seulement |
Toute clé lit en plus ses propres établissements (GET /sites), pour que vous trouviez les siteId.
Une route appelée sans le droit nécessaire répond 403. Demandez au commerçant d’ajouter le droit à la clé, ou de vous en créer une nouvelle : une clé ne s’élargit pas en douce.
Le droit Ventes donne accès aux tickets complets, prix d’achat compris : c’est la marge du commerçant. Ne le demandez que si votre service en a vraiment besoin.
Le périmètre d’établissements
Une clé sans restriction couvre toute l’enseigne : tous ses établissements, présents et futurs. Une clé restreinte ne voit que les établissements choisis :
GET /sitesne renvoie que ceux-là ;- une adresse qui vise un autre établissement répond
404, comme s’il n’existait pas.
Bonnes pratiques
- Une clé par intégration et par commerçant, avec les seuls droits utiles. Si l’un de vos services est compromis, le commerçant révoque une clé, pas toutes.
- Côté serveur seulement. Jamais dans une application mobile, une page web, un journal ou un dépôt de code.
- Stockée chiffrée, comme un mot de passe.
- Un 401 n’est pas une panne : la clé a été révoquée. Arrêtez les appels pour ce commerçant et prévenez-le, au lieu de réessayer en boucle.
Les applications pour plusieurs commerçants
Une application qui sert de nombreux commerçants (un logiciel de comptabilité, une place de marché…) se connecte par OAuth : le commerçant se connecte à Gillia, choisit son enseigne et accepte les droits demandés, sans copier de clé. Voir OAuth pour les applications multi-commerçants. Une application s’essaie d’abord sur des bacs à sable ; les vrais commerçants peuvent l’autoriser une fois certifiée.