Requêtes
L'anatomie d'une requête Merchant API et l'ordre exact dans lequel le serveur la contrôle, qui détermine le statut rendu et la consommation d'un jeton de débit.
Une requête Merchant API est une requête HTTPS vers l'URL de base configurée, authentifiée par une clé, avec un corps JSON pour les deux routes POST.
POST /merchant/v1/enrichments HTTP/1.1
Host: api.noryo.app
Authorization: Bearer nry_mer_sbx_<key_id>.<secret>
Content-Type: application/json
Idempotency-Key: 0b6f2c1e-6f1d-4a43-9d7e-2b9e6f5c8a10
{"descriptor":"CB MCDONALDS PARIS 4519","external_transaction_id":"tx_8f21c0"}L'ordre des contrôles
Le serveur contrôle une requête dans un ordre fixe et s'arrête au premier refus. Cet ordre explique le statut que vous recevez quand plusieurs choses sont fausses à la fois, et quels refus consomment un jeton de débit.
| Étape | Contrôle | Refus |
|---|---|---|
| 1 | Hôte déclaré pour l'API | 400 invalid_request |
| 2 | Content-Type: application/json (routes POST) | 415 unsupported_media_type |
| 3 | Corps de 16 Kio au plus (routes POST) | 413 request_entity_too_large |
| 4 | Corps JSON lisible (routes POST) | 400 invalid_json |
| 5 | En-tête Authorization, clé connue, préfixe cohérent | 401 invalid_api_key |
| 6 | Forme de l'Idempotency-Key, si l'en-tête est présent | 400 invalid_idempotency_key |
| 7 | Clé non révoquée, organisation et workspace actifs | 401 invalid_api_key, 403 account_inactive |
| 8 | Limite de débit | 429 rate_limited |
| 9 | Contrôles propres à la route (schéma du corps, scope, identifiants, identifiant de chemin) | 400, 403, 404, 409 |
| 10 | Calcul et règlement (idempotence, déduplication, dotation, accès commercial) | 402, 403, 409, 410, 503 |
Le détail des étapes 9 et 10 pour chaque route est donné dans Créer, Relire et Rafraîchir.
Ce qui consomme un jeton de débit
Chaque requête qui atteint l'étape 8 consomme un jeton, quelle que soit la réponse finale : un 200, un rejeu idempotent, un 400 de validation, un 403 insufficient_scope, un 404, un 409. Une requête refusée aux étapes 1 à 7 ne consomme rien : une clé inconnue ou révoquée n'a pas de seau à user. Une lecture GET coûte un jeton, comme une création. Voir Limites de débit.
Ce qui n'entre dans aucun calcul
L'hôte, l'Idempotency-Key, le Noryo-Request-Id et la clé API n'entrent pas dans l'identité économique d'une transaction. Le même corps envoyé par deux clés du même workspace et du même environnement désigne la même transaction. Voir Les deux identifiants.
Dans cette section
- En-têtes : les en-têtes de requête et de réponse, et quand ils sont présents.
- Les deux identifiants :
Idempotency-Keyetexternal_transaction_id, et pourquoi il vous faut les deux. - Idempotence : la fenêtre, la portée, les rejeux, la concurrence.
- Formats : JSON, encodage, taille, formats de champs et d'identifiants.
- Validation : le schéma fermé et chaque message d'erreur.
Publié le 2026-10-08 21:04 UTC (version 1).