Skip to main content

​
Corps de requête ou paramètre de query ?

Une même règle vaut sur toute l’API :
  • le corps d’une requête décrit la ressource elle-même — les données qui seront stockées (les champs d’une facture, d’un tiers, d’un journal…) ;
  • les paramètres de query configurent l’appel — des options qui changent son comportement sans être stockées, comme ?ignore_duplicate=true à la création d’une relation, ?type=purchase sur l’import d’un fichier, ou ?send_peppol=true pour envoyer une facture dès sa création.
Un paramètre de query envoyé dans le corps n’est pas ignoré : la requête est refusée par un 422 qui nomme le champ en cause.

​
Lire les réponses

Les réponses suivent partout les mêmes règles de lecture :
  • Les montants sont des nombres JSON — jamais des chaînes.
  • Une valeur absente vaut null — jamais une chaîne vide : "phone": null signifie qu’aucun téléphone n’est renseigné.
  • Un champ qui n’existe pas pour le type est absent, pas null : une relation company porte vat, identifier, electronic_address, is_customer, is_supplier ; un contact porte first_name, last_name — chacune sans les champs de l’autre.
  • Une énumération peut valoir unknown — une valeur historique que l’API ne sait pas classer sort ainsi ; prévoyez ce cas dans vos mappings.
Testez donc null pour « aucune valeur », et l’absence de la clé pour « sans objet pour ce type ».

​
Suivre une requête

Chaque réponse porte un en-tête X-Request-ID — un identifiant opaque de cet appel précis chez nous :
Conservez-le à côté de vos propres logs. Lorsque vous contactez le support à propos d’un appel en échec ou surprenant, citez cette valeur : elle nous mène directement à la trace et aux logs serveur de cette requête, et supprime les allers-retours sur quand c’est arrivé et quel endpoint. Particulièrement utile sur un 500 internal_error.

​
Créer et modifier

Trois règles valent pour tous les POST et PATCH :
  • Tout ou rien — une requête qui viole une règle est refusée en bloc : un objet n’est jamais créé ni modifié à moitié.
  • Un PATCH n’applique que les champs présents — omettre un champ le laisse tel quel ; il n’est pas nécessaire de renvoyer l’objet complet.
  • Un champ inconnu ou en lecture seule est une erreur — la requête est refusée par un 422 qui le nomme, jamais ignorée en silence : une faute de frappe ne passe pas inaperçue.