Evyoo POS API v1

Bonnes pratiques

Dix habitudes qui évitent presque tous les problèmes.

La sécurité#

1. Le code de sécurité reste sur votre serveur#

C'est un mot de passe. Jamais dans une page web, une application mobile, un fichier de configuration public, un dépôt de code ou un courriel. Si votre application s'exécute chez l'utilisateur (navigateur, téléphone), elle ne doit pas appeler l'API directement : elle appelle votre serveur, qui appelle l'API.

Lisez les clés dans des variables d'environnement ou un coffre-fort de secrets :

bash
export EVYOO_CLIENT_ID="evy_ak_votre_cle"
export EVYOO_CLIENT_SECRET="evy_sk_votre_code"

2. Une clé par système#

Ne partagez pas une clé entre deux systèmes : on ne pourrait pas en révoquer un sans couper l'autre. Demandez une clé par application.

3. Le moins de permissions possible#

Demandez à l'administrateur uniquement ce dont le système a besoin. Un tableau de bord de ventes n'a pas besoin de costs:read. Et vous pouvez, à chaque demande de jeton, demander moins que ce que votre clé permet (champ scope).

4. Changez le code s'il fuit#

Au moindre doute, faites régénérer le code de sécurité. L'ancien et les jetons en cours cessent aussitôt.

L'efficacité#

5. Gardez le jeton#

Réutilisez-le 15 minutes ; renouvelez-le sur un 401, une seule fois. Voir S'authentifier.

6. Demandez le moins possible#

Filtrez (status, customer_id, date_from…) plutôt que de tout lire et trier chez vous. Utilisez updated_since pour ne lire que les changements (Garder vos données à jour). Prenez per_page=100 quand vous lisez beaucoup.

7. Gardez les référentiels en mémoire#

Succursales, départements, sous-départements, listes de prix et types de client changent rarement. Lisez-les une fois par jour, pas à chaque besoin.

8. Respectez les limites#

Lisez X-RateLimit-Remaining et ralentissez avant zéro. Sur un 429, attendez Retry-After secondes. Voir Erreurs.

9. Notez le request_id#

Journalisez le request_id de chaque erreur de l'API. C'est ce que le support vous demandera, et il retrouve la ligne exacte chez nous.

L'usage des données#

10. Ce que vous lisez est exact à l'instant de l'appel#

L'API garantit l'exactitude de ce qu'elle renvoie au moment de la requête. Rien de plus : un stock change à chaque vente, un prix peut être modifié. Si vous affichez ces données à un tiers (un client sur un site, un assistant automatique, un partenaire) :

  • indiquez qu'elles sont données à titre indicatif et à un instant donné ;
  • ne gardez pas en mémoire plus longtemps que nécessaire une donnée qui bouge (le stock) ;
  • ne montrez que ce que vous avez décidé de montrer : un coût ou le solde d'un client ne doit pas ressortir par mégarde dans une réponse destinée au public.

L'API ne contrôle pas ce que votre système fait des données une fois lues : c'est votre responsabilité.