Skip to main content
Toutes les opérations de l’API sont servies sous le préfixe /v1, à partir de l’URL de base du backend POS.
L’URL de base dépend de votre environnement (l’application n’est pas encore déployée à une adresse publique fixe). Le chemin d’une opération apparaît dans la Référence API, par exemple GET /v1/products ou POST /v1/checkout/finalize.

​
Forme des réponses

​
Succès

Les routes de domaine renvoient leur charge utile directement, en JSON brut — il n’y a pas d’enveloppe { "data": … } sur ces routes. Selon l’opération, c’est un objet (un modèle de lecture), un tableau, ou une page.
L’unique exception est GET /v1/auth/whoami, une route récente qui renvoie { "data": { "effectivePermissions": [ … ] } }. Unifier toutes les réponses de succès sous une enveloppe { data } est un chantier transverse volontairement non réalisé ici, car il toucherait le client API et toutes les applications.

​
Erreur

Un échec renvoie l’enveloppe d’erreur partagée :
  • code — un ResultCode du noyau (voir Codes d’erreur).
  • message — un message lisible.
  • statusCode — le statut HTTP, cohérent avec le code d’état de la réponse.
  • fieldErrors — présent uniquement sur VALIDATION_FAILED : la liste des erreurs de champ { field, message }.
Une erreur de validation de requête est normalisée dans exactement la même enveloppe qu’un rejet de cas d’usage.

​
Pagination

Les opérations de liste se paginent par les paramètres de requête page et pageSize (pageSize plafonné, en pratique à 100).
La réponse d’une liste paginée porte les éléments et le comptage :

​
Validation

Les schémas qui valident une requête au runtime sont les mêmes que ceux qui génèrent le spec OpenAPI : les paramètres, la querystring et le corps documentés sont exactement ceux validés à l’exécution. Un corps ou un paramètre invalide produit un 400 VALIDATION_FAILED avec fieldErrors.