# 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](https://developer.noryo.app/fr-FR/merchant/requests/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](https://developer.noryo.app/fr-FR/merchant/authentication/api-keys). |

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](https://developer.noryo.app/fr-FR/merchant/models/location). |
| `Retry-After` | Nombre entier de secondes |

---

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