# 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`.

```http
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](https://developer.noryo.app/fr-FR/merchant/enrichments/create), [Relire](https://developer.noryo.app/fr-FR/merchant/enrichments/read) et [Rafraîchir](https://developer.noryo.app/fr-FR/merchant/refresh).

## 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](https://developer.noryo.app/fr-FR/merchant/rate-limits).

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

## Dans cette section

- [En-têtes](https://developer.noryo.app/fr-FR/merchant/requests/headers) : les en-têtes de requête et de réponse, et quand ils sont présents.
- [Les deux identifiants](https://developer.noryo.app/fr-FR/merchant/identifiers) : `Idempotency-Key` et `external_transaction_id`, et pourquoi il vous faut les deux.
- [Idempotence](https://developer.noryo.app/fr-FR/merchant/requests/idempotency) : la fenêtre, la portée, les rejeux, la concurrence.
- [Formats](https://developer.noryo.app/fr-FR/merchant/requests/formats) : JSON, encodage, taille, formats de champs et d'identifiants.
- [Validation](https://developer.noryo.app/fr-FR/merchant/requests/validation) : le schéma fermé et chaque message d'erreur.

---

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