Skip to content
Gillia Developers v1

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)NiveauDroits techniquesCe que ça ouvre
ClientsLecturepos.customers.readLister et lire les clients
ClientsLecture et écriturepos.customers.read pos.customers.writeCréer et modifier des clients
CatalogueLecturepos.catalog.readArticles, catégories, images, zones, niveaux de stock
CatalogueLecture et écriturepos.catalog.read pos.catalog.writeCréer et modifier des articles et leurs images
VentesLecturepos.sales.readTickets de caisse, clôture (Z) d’une journée, solde d’un bon d’achat
StockEnregistrerpos.inventory.writeAjustements de stock
Commandes partenairesEnvoyer et suivrepos.orders.writeCommandes venues d’ailleurs, commandes partenaires, webhook
Bons d’achatÉmettrepos.vouchers.writeÉmettre un bon d’achat, prolonger sa validité
Achats fournisseursLecturepos.purchases.readCommandes fournisseurs et réceptions
ComptabilitéLecturepos.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 /sites ne 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.