Formats
JSON, encodage, taille maximale, format exact de chaque champ de requête, forme canonique utilisée pour comparer deux transactions, et format des identifiants rendus.
Transport
| Élément | Règle |
|---|---|
| Protocole | HTTPS, vers l'URL de base configurée |
Corps des routes POST | Un objet JSON, encodé en UTF-8, envoyé avec Content-Type: application/json |
| Taille du corps | 16 Kio au plus (16 384 octets), comptés en octets et non en caractères. Au-delà : 413 request_entity_too_large |
| Corps des réponses | JSON. Les erreurs sont en application/problem+json |
Route GET | Pas de corps |
La limite de 16 Kio couvre très largement une transaction ; elle existe parce que l'API traite une transaction par requête, pas un fichier.
Champs de requête
| Champ | Type | Format exact | Exemple |
|---|---|---|---|
descriptor | chaîne | Obligatoire, non vide (pas seulement des espaces), 512 caractères au plus | "CB MCDONALDS PARIS 4519" |
amount | nombre | Nombre JSON fini ; une chaîne est refusée | 12.40 |
currency | chaîne | ISO 4217, trois lettres majuscules | "EUR" |
occurred_at | chaîne | Date et heure ISO 8601 en UTC avec le suffixe Z, fraction de seconde facultative (1 à 9 chiffres) | "2026-09-06T11:42:00Z" |
country | chaîne | ISO 3166-1 alpha-2, deux lettres majuscules | "FR" |
mcc | chaîne | Quatre chiffres, sous forme de chaîne | "5814" |
external_transaction_id | chaîne | 1 à 255 caractères ; création uniquement | "tx_8f21c0" |
Seul descriptor est obligatoire. Un champ facultatif que vous n'avez pas doit être omis : la valeur null est refusée pour chacun d'eux. Voir Validation.
Pourquoi les majuscules
eur est refusé en 400, et fr aussi. C'est délibéré : la forme canonique compare currency, country et mcc tels quels, donc EUR et eur seraient deux identités économiques distinctes et deux factures pour ce que vous vouliez être un seul appel. Le validateur refuse l'ambiguïté plutôt que de normaliser dans votre dos.
La forme canonique
Pour décider si deux requêtes portent la même transaction (idempotence et déduplication), Noryo compare une forme canonique des six champs économiques :
| Champ | Traitement avant comparaison |
|---|---|
descriptor | Normalisation Unicode NFC, passage en minuscules, suites d'espaces réduites à un espace, espaces de début et de fin retirés |
amount | Représentation décimale à 15 chiffres significatifs |
occurred_at | Ramené en UTC et tronqué à la seconde |
currency, country, mcc | Aucun : comparés tels quels |
| Champ absent | Reste absent : un champ omis et un champ présent font deux entrées différentes |
Conséquences : "CB McDonalds Paris" et "cb mcdonalds paris" sont la même entrée ; 2026-09-06T11:42:00.250Z et 2026-09-06T11:42:00Z aussi ; 12.4 et 12.40 aussi. En revanche, une requête qui porte amount et une requête qui ne le porte pas sont deux transactions.
Cette forme sert uniquement à comparer. Le libellé brut, lui, n'est pas conservé.
Identifiants rendus par l'API
| Identifiant | Forme | Remarques |
|---|---|---|
enrichment_id | enr_ suivi d'un UUID version 4, en minuscules | Aléatoire : il ne révèle ni un ordre ni un volume. Un identifiant mal formé rend 404. |
request_id / Noryo-Request-Id | req_ suivi d'un UUID version 7 | Ordonné dans le temps, utile pour trier vos journaux. |
| Clé API | nry_mer_sbx_<key_id>.<secret> ou nry_mer_live_<key_id>.<secret> | Voir Clés API. |
Traitez ces identifiants comme opaques : stockez-les et comparez-les tels quels, sans en extraire de sens.
Valeurs rendues
| Champ | Forme |
|---|---|
merchant.confidence | Nombre entre 0 et 1 |
merchant.category | Code textuel, par exemple alimentation.restaurant |
merchant.logo_url | URI |
merchant.location | Objet { "city", "postal_code" } ou null. Voir Location. |
Retry-After | Nombre entier de secondes |
Publié le 2026-10-08 21:04 UTC (version 1).