# Vue d'ensemble

> Ce que fait Noryo Merchant API, ses trois routes, les règles à connaître avant d'écrire une ligne et par où commencer.

Noryo Merchant API transforme un libellé bancaire brut (le `descriptor`, tel que la banque l'écrit sur un relevé) en identité marchande : un nom, une catégorie, un logo et une localisation quand ils sont connus, et un score de confiance. L'API répond en JSON sur HTTPS. Son contrat machine est un document OpenAPI 3.1, à partir duquel la [référence de l'API](https://developer.noryo.app/fr-FR/merchant/reference) est générée.

Cette documentation décrit le comportement réel du serveur. Une capacité qui n'existe pas n'y est pas décrite.

## Trois routes, pas de lot

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

| Route | Ce qu'elle fait | Ce qu'elle coûte |
|---|---|---|
| `POST /merchant/v1/enrichments` | Enrichit un libellé et rend un résultat identifié par un `enrichment_id` | 1 unité si le résultat est `resolved`, rien sinon |
| `GET /merchant/v1/enrichments/{enrichment_id}` | Relit un résultat passé | Jamais facturée |
| `POST /merchant/v1/enrichments/{enrichment_id}/refresh` | Recalcule l'identité et rend un **nouvel** `enrichment_id` | 1 unité si le résultat est `refresh_recalculated`, rien sinon |

Une requête porte une transaction. Il n'existe pas de route de traitement par lot.

## Les règles à connaître avant d'écrire une ligne

- **Un `200` ne veut pas dire qu'un marchand a été trouvé.** Lisez `enrichment.status` : `not_found` est une réponse normale et complète. Voir [Lire une réponse](https://developer.noryo.app/fr-FR/merchant/reading-the-response).
- **Une création exige au moins un identifiant** : l'en-tête `Idempotency-Key`, le champ `external_transaction_id`, ou les deux. Sans aucun des deux, l'API refuse en `400 identifier_required`. Voir [Les deux identifiants](https://developer.noryo.app/fr-FR/merchant/identifiers).
- **`confidence` est un score, pas une probabilité.** Noryo a mesuré que son ordre n'est pas monotone en haut de l'intervalle. Voir [Confidence](https://developer.noryo.app/fr-FR/merchant/results/confidence).
- **L'environnement est porté par la clé** : `nry_mer_sbx_` pour le Sandbox, `nry_mer_live_` pour la Production, sur la même URL. Voir [Environnements](https://developer.noryo.app/fr-FR/merchant/authentication/environments).
- **Le libellé brut n'est pas conservé**, et le contenu d'un résultat est conservé 90 jours. Voir [Rétention et 410](https://developer.noryo.app/fr-FR/merchant/retention).
- **Chaque erreur est un objet Problem Details (RFC 9457)** dont le champ `code` est le seul contrat machine. Voir [Erreurs](https://developer.noryo.app/fr-FR/merchant/error-handling) et le [catalogue des erreurs](https://developer.noryo.app/fr-FR/errors).

## Version et hôte

La version appartient à la famille : `/merchant/v1`. Une future `merchant/v2` vivrait à côté de `v1` au lieu de la remplacer.

L'hôte ne fait pas partie du contrat. Noryo peut servir l'API depuis plus d'un domaine, et aucun nom d'hôte n'entre dans une identité, une empreinte ou une signature. Le contrat déclare aujourd'hui `https://api.noryo.app` : placez cette valeur dans la configuration de votre URL de base plutôt que dans votre code. Voir [Versions et gouvernance](https://developer.noryo.app/fr-FR/merchant/governance).

## Par où commencer

1. [Démarrage rapide](https://developer.noryo.app/fr-FR/merchant/quickstart) : un enrichissement, son rejeu, sa relecture et son rafraîchissement, avec les réponses réelles.
2. [Concepts essentiels](https://developer.noryo.app/fr-FR/merchant/concepts) : le vocabulaire de l'API en une page.
3. [Authentification](https://developer.noryo.app/fr-FR/merchant/authentication) et [Clés API](https://developer.noryo.app/fr-FR/merchant/authentication/api-keys) : obtenir et présenter une clé.
4. [Requêtes](https://developer.noryo.app/fr-FR/merchant/requests) : en-têtes, idempotence, formats et validation.
5. [Enrichissements](https://developer.noryo.app/fr-FR/merchant/enrichments) : créer, relire, rafraîchir, statuts et cycle de vie.
6. [Exploitation](https://developer.noryo.app/fr-FR/merchant/operations) : limites de débit, reprises, délais, erreurs et identifiants de requête.

> **Note** Le Sandbox est gratuit et porte une dotation à vie de 2 000 unités par organisation. La Production n'est pas en libre-service : elle s'ouvre après l'examen d'un dossier par Noryo. Voir [Sandbox](https://developer.noryo.app/fr-FR/merchant/sandbox) et [Passage en production](https://developer.noryo.app/fr-FR/merchant/going-live).

---

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