> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.fidly.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Les principes qui valent pour tous les endpoints : corps et paramètres de query, lecture des champs, création et modification.

## 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 :

```
X-Request-ID: 3f2a8c1e-9b47-4e3a-8d21-5c6f0a1b2d3e
```

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.