# Concepts essentiels

> Le vocabulaire de Noryo Merchant API en une page : libellé, enrichissement, identité économique, identifiants, statuts, unités et environnements.

Cette page définit les termes employés partout dans la documentation. Les noms de champs et de valeurs restent en anglais, tels que l'API les rend.

## Le libellé et l'enrichissement

| Terme | Définition |
|---|---|
| `descriptor` | Le libellé bancaire brut, tel qu'il figure sur le relevé (`CB MCDONALDS PARIS 4519`). C'est le seul champ obligatoire d'une requête. Noryo ne le conserve pas. |
| Enrichissement | Le résultat d'un appel qui a abouti : une identité marchande (ou l'absence d'identité), un statut et ce que l'appel a coûté. |
| `enrichment_id` | L'identité publique d'un résultat, de la forme `enr_<uuid>`. Un rafraîchissement produit un nouveau résultat, donc un nouvel `enrichment_id` ; l'ancien continue de désigner l'ancien résultat. |
| `merchant` | L'identité marchande : `name`, `category`, `logo_url`, `location`, `confidence`. Elle vaut `null` quand le statut est `not_found`. |

## Ce qui identifie une transaction

| Terme | Définition |
|---|---|
| Identité économique | Les six champs `descriptor`, `amount`, `currency`, `occurred_at`, `country` et `mcc`, comparés sous une forme canonique. Deux appels qui ne diffèrent que par le montant sont deux enrichissements distincts. |
| `external_transaction_id` | Votre identifiant de la transaction. Il porte la déduplication économique : la même transaction envoyée deux fois n'est facturée qu'une fois. Il n'expire pas. |
| `Idempotency-Key` | Un en-tête de requête qui protège le transport : une reprise réseau rejoue la réponse mémorisée au lieu de recalculer. Fenêtre de 24 heures. |

Les deux identifiants ne se remplacent pas l'un l'autre. Voir [Les deux identifiants](https://developer.noryo.app/fr-FR/merchant/identifiers).

## Ce que dit la réponse

| Terme | Définition |
|---|---|
| `enrichment.status` | `resolved`, `partial`, `not_found` ou `refresh_recalculated`. C'est le champ à lire en premier, avant `merchant`. Voir [Statuts](https://developer.noryo.app/fr-FR/merchant/enrichments/statuses). |
| `enrichment.reason` | Une raison publique en liste fermée pour `partial` et `not_found`, `null` sinon. |
| `confidence` | Un score de confiance du modèle entre 0 et 1. Ce n'est pas une probabilité calibrée. Voir [Confidence](https://developer.noryo.app/fr-FR/merchant/results/confidence). |
| `usage` | Ce que **cet appel** a coûté : `billable`, `units`, `deduplicated`, `deduplicated_by`. |
| Unité | L'unité de comptage de l'usage. Un résultat `resolved` ou `refresh_recalculated` vaut 1 unité ; `partial` et `not_found` valent 0. |

## Qui appelle, et où

| Terme | Définition |
|---|---|
| Organisation et workspace | Une organisation regroupe des workspaces ; une clé API appartient à un workspace. Les résultats, les clés d'idempotence et la déduplication sont propres à un workspace et à un environnement. La dotation Sandbox est comptée par organisation. |
| Environnement | `sandbox` ou `production`. Il est porté par le préfixe de la clé et confirmé par le serveur ; la réponse le répète dans `enrichment.environment`. |
| Scopes | `enrich:read` autorise la lecture (`GET`), `enrich:write` autorise la création et le rafraîchissement. |
| `Noryo-Request-Id` | L'identifiant d'une tentative HTTP, de la forme `req_<uuid>`. Il figure dans l'en-tête de chaque réponse et dans le corps de chaque erreur. |
| `code` | Le code machine d'une erreur Problem Details, par exemple `idempotency_key_reuse`. C'est le seul élément d'une erreur sur lequel bâtir une logique. |

## Ce que Noryo fait de vos entrées

Les six champs économiques entrent tous dans l'identité économique, mais seul `descriptor` oriente aujourd'hui la résolution. En particulier, `country` ne filtre pas la réponse : c'est un choix mesuré, expliqué dans [Lire une réponse](https://developer.noryo.app/fr-FR/merchant/reading-the-response).

Pour savoir si deux requêtes portent la même transaction, Noryo compare une forme canonique et non les octets envoyés : le `descriptor` est normalisé (Unicode NFC, minuscules, espaces compressés), `occurred_at` est ramené à la seconde en UTC, tandis que `currency`, `country` et `mcc` sont comparés tels quels. C'est pourquoi `currency` et `country` doivent être en majuscules. Voir [Formats](https://developer.noryo.app/fr-FR/merchant/requests/formats).

---

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