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

> The principles that hold on every endpoint: request body and query parameters, reading fields, creating and updating.

## Request body or query parameter?

One rule holds across the whole API:

* the **body** of a request describes the resource itself — the data that will be
  stored (the fields of an invoice, a relation, a journal...);
* **query parameters** configure the call — options that change its behavior
  without being stored, such as `?ignore_duplicate=true` when creating a relation,
  `?type=purchase` on a file import, or `?send_peppol=true` to send an invoice
  right at creation.

A query parameter sent in the body is not ignored: the request is refused with a
`422` naming the offending field.

## Reading responses

Responses follow the same reading rules everywhere:

* **Amounts are JSON numbers** — never strings.
* **A missing value is `null`** — never an empty string: `"phone": null` means no
  phone is recorded.
* **A field that does not exist for the type is absent, not `null`**: a `company`
  relation carries `vat`, `identifier`, `electronic_address`, `is_customer`,
  `is_supplier`; a `contact` carries `first_name`, `last_name` — each without the
  other's fields.
* **An enumeration can read `unknown`** — a historical value the API cannot
  classify comes out that way; handle it in your mappings.

Test for `null` to mean "no value", and for the absence of the key to mean "not
applicable to this type".

## Tracing a request

Every response carries an **`X-Request-ID`** header — an opaque identifier for that
exact call on our side:

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

Record it alongside your own logs. When you contact support about a failed or
surprising call, **quote this value**: it points us straight at that request's trace
and server logs, and removes the back-and-forth over *when* it happened and *which*
endpoint. It is especially useful on a `500 internal_error`.

## Creating and updating

Three rules hold for every `POST` and `PATCH`:

* **All or nothing** — a request that violates any rule is refused as a whole: an
  object is never created or updated halfway.
* **A `PATCH` applies only the fields present** — omitting a field leaves it
  unchanged; there is no need to send the full object back.
* **An unknown or read-only field is an error** — the request is refused with a
  `422` naming it, never silently ignored: a typo does not go unnoticed.