Guide
Démarrer
De la clé d’API à votre premier appel, en cinq minutes.
Ce qu’il vous faut
- Une clé d’API. C’est le commerçant qui la crée et vous la transmet : un commerçant garde toujours la main sur ce que vous voyez de ses données.
- Un outil pour faire une requête HTTPS :
curl, Postman, ou le langage de votre choix.
L’adresse de base de l’API est la même pour tout le monde :
https://gillia.app/pos-api/api/v1
Pour essayer tout de suite, sans attendre un commerçant : créez un bac à sable. Vous recevez une boutique d’exemple et une clé de test gsk_test_… avec tous les droits. Voir Tester dans le bac à sable.
1. Obtenir une clé
Le commerçant ouvre Paramètres › Intégrations, onglet Clés API, puis Nouvelle clé partenaire. Il y choisit :
- un nom (le vôtre, pour s’y retrouver) ;
- les droits, domaine par domaine : Clients, Catalogue, Ventes, Stock, Commandes partenaires, Bons d’achat, Achats fournisseurs ;
- s’il le veut, les établissements auxquels la clé est limitée.
La clé s’affiche une seule fois : il vous la transmet par un canal sûr. Elle commence par gsk_.
Ne mettez jamais une clé dans une application mobile, une page web ou un dépôt de code : elle donne accès aux données du commerçant. Gardez-la côté serveur.
2. Votre premier appel
Listez les établissements que la clé peut lire :
curl https://gillia.app/pos-api/api/v1/sites \
-H "Authorization: Bearer gsk_VOTRE_CLE"
Réponse :
{
"items": [
{
"id": "6f1c2a7e-0b9d-4c55-9a41-2f0e7d3b8c10",
"name": "Boulangerie du Marché",
"apiEnabled": true
}
]
}
Notez l’id : c’est le siteId des adresses suivantes. Toute clé peut lire ses établissements, quels que soient ses autres droits.
3. Lire le catalogue
Avec le droit Catalogue › Lecture :
curl "https://gillia.app/pos-api/api/v1/sites/6f1c2a7e-0b9d-4c55-9a41-2f0e7d3b8c10/pos/catalog/products?page=1&pageSize=50" \
-H "Authorization: Bearer gsk_VOTRE_CLE"
Les listes sont paginées : page (à partir de 1) et pageSize. La réponse donne les articles de la page et de quoi savoir s’il en reste.
4. Et ensuite
- Authentification et droits : quel droit ouvre quelle route.
- Limites, erreurs et idempotence : réessayer proprement, ne jamais créer de doublon.
- Webhooks : être prévenu quand une commande change d’état.
- Référence API : toutes les routes, leurs paramètres et leurs réponses.