# Versions et gouvernance

> Ce qui fait foi (le contrat OpenAPI), comment l'API est versionnée par famille de chemin, ce que désignent la version du contrat et la date de publication, et pourquoi l'hôte n'en fait pas partie.

## Ce qui fait foi

Le **contrat machine** de Noryo Merchant API est un document OpenAPI 3.1. La [référence de l'API](https://developer.noryo.app/fr-FR/merchant/reference) en est générée, et ce document n'est pas traduit : c'est la même source pour tous, à partir de laquelle un client peut générer son code. Les pages de guide, comme celle-ci, l'expliquent et décrivent les comportements qu'un schéma ne dit pas (idempotence, déduplication, rétention).

## La version appartient à la famille

La version est portée par le chemin : `/merchant/v1`. Elle appartient à la **famille** d'API, pour qu'une future `merchant/v2` puisse vivre à côté de `merchant/v1` au lieu de la remplacer. Les trois routes actuelles sont toutes sous `/merchant/v1`.

```http
POST /merchant/v1/enrichments
GET  /merchant/v1/enrichments/{enrichment_id}
POST /merchant/v1/enrichments/{enrichment_id}/refresh
```

## Trois numéros, trois sens

| Ce que vous voyez | Ce qu'il désigne | Valeur actuelle |
|---|---|---|
| Le segment `v1` du chemin | La version de la famille d'API, celle que votre code appelle | `v1` |
| La version du contrat OpenAPI | La révision du document machine | `1.0.0` |
| La date de publication de la documentation | La publication de la documentation qui contient cette version de contrat | 2026-10-01 |

La référence affiche la date de publication ; c'est elle qu'il faut citer pour dire « la documentation telle que je l'ai lue ». Voir [Journal des modifications](https://developer.noryo.app/fr-FR/merchant/governance/changelog).

## L'hôte ne fait pas partie du contrat

Noryo peut servir l'API depuis plus d'un domaine. Aucun nom d'hôte n'entre dans une identité, une empreinte ou une signature :

- l'en-tête `Location` d'un rafraîchissement est un chemin **relatif** ;
- l'identité économique d'une transaction ne dépend pas de l'hôte appelé ;
- le `type` d'une erreur est un lien vers la documentation, pas une partie du code d'erreur.

Le contrat déclare aujourd'hui `https://api.noryo.app`. Placez l'URL de base dans votre configuration, et ne l'écrivez pas en dur ailleurs.

## Ce qui est stable, et ce qui ne l'est pas

La page [Compatibilité](https://developer.noryo.app/fr-FR/merchant/governance/compatibility) détaille ce sur quoi votre code peut s'appuyer (les codes d'erreur, le format des clés et des identifiants) et ce qui peut changer sans version (le texte des messages d'erreur, la politique de résolution).

## Dans cette section

- [Compatibilité](https://developer.noryo.app/fr-FR/merchant/governance/compatibility) : écrire un client qui ne casse pas.
- [Journal des modifications](https://developer.noryo.app/fr-FR/merchant/governance/changelog) : les publications datées.

---

Page canonique : https://developer.noryo.app/fr-FR/merchant/governance