Guide
Certification
Prouvez votre intégration dans le bac à sable, par l’API, et ouvrez-la à tous les commerçants.
Ce que donne la certification
Une application OAuth neuve ne peut être autorisée que par des bacs à sable. La certification l’ouvre à tous les commerçants Gillia. Elle est automatique et publique : pas de formulaire, pas d’appel, personne à attendre. Vous jouez un scénario dans votre bac à sable, l’API vérifie ce que votre application a réellement fait, et quand tous les contrôles sont verts, votre application passe aussitôt en production.
Rien n’est déclaratif : chaque contrôle est un fait lu dans le journal des appels des jetons reçus par votre application.
Les contrôles
Chaque profil commence par cinq contrôles communs :
| Contrôle | Ce que l’API cherche |
|---|---|
oauth_authorized | Un bac à sable a autorisé votre application par OAuth, et le jeton est actif |
sites_listed | Un GET /sites réussi avec ce jeton |
retry_on_unavailable | Après un 503, un appel réussi à la même route dans les 15 minutes |
backoff_on_rate_limit | Après un 429, votre appel suivant attend au moins 2 secondes, et la route finit par répondre |
no_error_loop | Jamais la même requête en échec 5 fois de suite |
Puis les gestes du profil choisi, chacun réussi au moins une fois :
| Profil | Droits nécessaires | Gestes |
|---|---|---|
catalog | pos.catalog.read | GET …/catalog/products, GET …/catalog/products/{productId} |
customers | pos.customers.read pos.customers.write | GET …/customers, POST …/customers |
orders | pos.orders.write | PUT …/partner-webhook, POST …/partner-webhook/test acquitté, POST …/partner-orders, GET …/partner-orders/{externalReference} |
sales | pos.sales.read | GET …/sales/tickets, GET …/closures |
inventory | pos.catalog.read pos.inventory.write | GET …/inventory/stocks, POST …/inventory/adjustments |
accounting | pos.accounting.read | GET …/accounting/entries, GET …/accounting/fec |
Simuler les incidents
Inutile d’attendre une vraie panne. Avec un jeton de bac à sable, ajoutez l’en-tête Gillia-Simulate à n’importe quelle route publique :
| Valeur | Réponse |
|---|---|
unavailable | 503, Retry-After: 5 |
rate_limited | 429, Retry-After: 2 |
server_error | 500 |
L’API répond comme si l’incident arrivait et n’exécute rien. La réponse porte Gillia-Simulated pour la distinguer dans vos journaux.
curl https://gillia.app/pos-api/api/v1/sites \
-H "Authorization: Bearer gsk_test_…" \
-H "Gillia-Simulate: unavailable"
Pas à pas
- Démarrez une session pour votre application et un profil :
curl https://gillia.app/pos-api/api/v1/me/apps/gci_…/certification \
-H "Authorization: Bearer gsk_test_CLE_DU_BAC_A_SABLE" \
-H "Content-Type: application/json" \
-d '{ "profile": "orders" }'
- Faites tourner votre application sur votre bac à sable : faites-la autoriser par OAuth, puis laissez-la travailler. Déclenchez un
503simulé et un429simulé sur une route qu’elle appelle, et laissez sa logique de reprise faire le reste.
- Relisez l’état aussi souvent que vous voulez. Chaque contrôle est vert, ou vient avec ce qu’il reste à faire :
curl https://gillia.app/pos-api/api/v1/me/apps/gci_…/certification \
-H "Authorization: Bearer gsk_test_CLE_DU_BAC_A_SABLE"
Quand tous les contrôles sont verts, status passe à passed et appStatus à production : les vrais commerçants peuvent désormais autoriser votre application.
Bon à savoir
- Seuls comptent les appels faits pendant la session et avec les jetons OAuth de votre application ; la clé de votre bac à sable ne compte pas.
- Une session dure 7 jours. En démarrer une nouvelle remplace celle en cours.
- La certification vérifie un comportement, pas votre métier : gardez votre secret client sur votre serveur et traitez les données des commerçants avec soin.