> ## Documentation Index
> Fetch the complete documentation index at: https://developers.0flaw.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions et compatibilité

> Ce que nous pouvons changer sans préavis, et ce qui imposera une v2.

La version est dans l'URL : `/api/v1`. Une future `v2` sera publiée **à côté** de la v1,
jamais à sa place.

## Notre engagement

<Columns cols={2}>
  <Card title="Sans préavis, dans la v1" icon="circle-check">
    * Ajouter un endpoint
    * Ajouter un champ **optionnel** en entrée
    * Ajouter un champ en sortie
    * Ajouter une permission
    * Ajouter un type d'événement webhook
  </Card>

  <Card title="Cela imposera une v2" icon="triangle-exclamation">
    * Supprimer ou renommer un champ ou un endpoint
    * Rendre obligatoire un champ jusque-là optionnel
    * Changer le type ou le sens d'un champ existant
    * Changer la signification d'un événement existant
  </Card>
</Columns>

## Écrivez un client tolérant

Trois règles qui éviteront que votre intégration casse sur une évolution pourtant compatible :

<Steps>
  <Step title="Ignorez les champs inconnus">
    Ne validez pas nos réponses en mode strict. Nous ajoutons régulièrement des champs.
  </Step>

  <Step title="Ne dépendez pas de l'ordre des clés JSON">
    Il n'est pas garanti et peut changer d'une version à l'autre de notre runtime.
  </Step>

  <Step title="Ne plantez pas sur une valeur d'énumération inconnue">
    C'est le piège qui casse le plus d'intégrations en pratique. Si `action` vaut demain une
    valeur que vous ne connaissez pas, journalisez-la et poursuivez — ne levez pas d'exception.
  </Step>
</Steps>

## Dépréciation

Le jour où une `v2` existera, les endpoints `v1` renverront les en-têtes `Deprecation` et
`Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)), avec un **préavis minimum de six
mois** avant toute extinction. Les changements sont annoncés dans cette documentation.

## Webhooks

Le champ `type` d'un événement est le contrat.

* **Enrichir `data`** avec de nouveaux champs est non cassant : traitez-les comme optionnels.
* **Changer la sémantique** d'un événement donne lieu à un **nouveau `type`**, jamais à une
  mutation silencieuse de l'existant.

Filtrez donc toujours sur `type` avant de traiter une livraison, et ignorez les types que vous
ne connaissez pas — vous en recevrez de nouveaux au fil du temps si vous y êtes abonné.