Evyoo POS API Les notions
Six mots suffisent pour comprendre toute l'API.
L'adresse de votre entreprise#
Chaque entreprise a sa propre adresse, par exemple clientA.evyooht.com. C'est elle qui dit de quelle entreprise vous lisez les données. Toutes les adresses de l'API sont construites ainsi :
https://votre-entreprise.evyooht.com/api/v1/...- Vous n'avez jamais à indiquer le nom de l'entreprise ailleurs : ni dans un paramètre, ni dans un en-tête. L'adresse suffit. Cela empêche, par construction, de lire les données d'une autre entreprise.
- Si votre société a plusieurs entreprises Evyoo, elles ont chacune leur adresse et leurs propres clés.
/api/v1: lev1est la version de l'API. Elle ne change pas sous vos pieds : un changement incompatible ouvrirait unev2, lav1continuerait de marcher.
La clé d'accès#
Votre identifiant (client_id dans les outils OAuth). Elle commence par evy_ak_. Elle n'est pas secrète à elle seule.
Le code de sécurité#
Votre mot de passe (client_secret dans les outils OAuth). Il commence par evy_sk_.
- Il est affiché une seule fois, à sa création. Evyoo n'en garde pas de copie lisible : s'il est perdu, on en crée un nouveau, on ne le retrouve pas.
- Il reste sur votre serveur. Ne le mettez jamais dans une page web, une application mobile ou un dépôt de code. Voir les bonnes pratiques.
Le jeton#
Un « ticket » valable 15 minutes, que vous obtenez en échange de la clé d'accès et du code de sécurité. C'est lui, et non le code de sécurité, qui voyage avec chaque requête. S'il est volé, il cesse de marcher au bout de 15 minutes.
Il se présente ainsi dans chaque requête :
Authorization: Bearer evy_at_votre_jetonLa permission#
Ce que votre clé a le droit de lire. Chaque ressource a la sienne : products:read ouvre les produits, invoices:read les factures. Sans la permission, vous recevez une erreur 403.
Deux permissions particulières n'ouvrent aucune ressource, elles ajoutent des champs sensibles à des réponses que vous pouvez déjà lire :
| Permission | Ce qu'elle ajoute |
|---|---|
costs:read | Les coûts : coût d'achat, coût moyen, coût de revient des documents. |
customers:financial | La limite de crédit et le solde des clients. |
Sans elles, ces champs sont absents de la réponse : ni vides, ni masqués. Ce n'est pas une panne : vous n'avez simplement pas ce droit. Voir la liste complète des permissions.
Votre clé peut aussi être limitée à certaines succursales, ou à une liste de prix. Dans ce cas vous ne voyez que celles-ci, partout (documents, stock, totaux).
La ressource#
Une catégorie de données : products, customers, invoices… Chacune se lit de deux façons :
| Adresse | Ce qu'elle donne |
|---|---|
/products | Une liste : une page de produits, avec des filtres, un tri et une pagination. |
/products/463 | Un produit, par son identifiant. Pour un document, avec ses lignes et ses paiements. |
Lecture seule#
L'API ne fait que lire. Aucune requête ne peut créer, modifier ni supprimer quoi que ce soit : vous ne risquez pas d'abîmer vos données en essayant.
Ce qu'il faut retenir#
- Adresse : celle de votre entreprise, jamais écrite en dur.
- Deux clés : la clé d'accès et le code de sécurité, gardés sur votre serveur.
- Un jeton de 15 minutes, réutilisé jusqu'à son expiration.
- Des permissions qui disent ce que vous pouvez lire.