# Compatibilité

> Ce sur quoi un client peut s'appuyer, ce qui peut changer sans changement de version, et les règles pour écrire une intégration qui ne casse pas.

Cette page dit ce sur quoi votre code peut s'appuyer, et ce qu'il ne doit pas supposer.

## Ce sur quoi s'appuyer

| Élément | Pourquoi |
|---|---|
| Le champ `code` des erreurs | C'est le contrat machine du corps d'erreur, et la seule promesse de stabilité que Noryo donne sur ce corps. Le passage d'un domaine à un autre ne change aucun code. |
| Le statut HTTP | Il accompagne chaque code |
| Le format des clés | `nry_mer_sbx_` ou `nry_mer_live_`, `key_id` de 10 caractères, un point, le secret : un format public figé |
| Le préfixe `enr_` et le préfixe `req_` | Ils distinguent les identifiants d'enrichissement et de requête |
| La version portée par le chemin | `/merchant/v1` ; une future `v2` vivrait à côté |

## Ce qui peut changer sans changement de version

| Élément | Conséquence pour votre code |
|---|---|
| `title` et `detail` des erreurs | Écrits pour des humains, en anglais ; reformulables à tout moment. Ne les analysez pas. |
| Le domaine de l'URL de base et des liens `type` | L'hôte ne fait pas partie du contrat : gardez l'URL de base en configuration |
| La politique de résolution (seuil, champs requis) | Elle décide `resolved` ou `partial` ; son seuil n'est pas une valeur du contrat. Décidez sur `enrichment.status`, pas sur un seuil de `confidence` recopié. |
| Les limites de débit | Réglages d'exploitation ; lisez `Noryo-RateLimit-Limit` plutôt qu'une constante |
| La couverture du catalogue | Une transaction `not_found` aujourd'hui peut être résolue par un rafraîchissement demain |

## Les règles d'un client qui ne casse pas

1. **Décidez sur `code`**, jamais sur le texte d'une erreur.
2. **Traitez une valeur inconnue avec prudence.** Une raison `enrichment.reason` inconnue se lit comme `unspecified` ; un statut inattendu se traite comme un résultat non exploitable ; un code d'erreur inconnu se traite selon son statut HTTP.
3. **Lisez les réponses avec tolérance.** Ignorez les champs que vous ne connaissez pas, et acceptez qu'un champ facultatif (`category`, `logo_url`) soit absent.
4. **Envoyez des requêtes strictes.** Le schéma de requête est fermé : n'ajoutez aucun champ hors contrat, il serait refusé. Omettez un champ facultatif plutôt que de l'envoyer à `null`.
5. **Traitez les identifiants comme opaques.** Stockez `enrichment_id` et `Noryo-Request-Id` tels quels, sans en tirer de sens métier : un `enrichment_id` est aléatoire et ne dit ni un ordre ni un volume.
6. **Résolvez `Location` contre votre URL de base**, puisqu'il est relatif.
7. **Lisez les noms d'en-têtes sans tenir compte de la casse**, comme le veut HTTP.

## Les noms officiels

Le produit s'appelle **Noryo Merchant API**. Les noms de champs, de statuts et de codes restent en anglais dans toutes les langues de la documentation, tels que l'API les rend.

---

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