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.
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. |
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. |
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.
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.
Publié le 2026-10-08 21:04 UTC (version 1).