# Démarrage rapide

> Un enrichissement de bout en bout dans le Sandbox : créer, rejouer, relire, rafraîchir, puis provoquer une erreur, avec les réponses réelles de l'API.

Ce parcours fait un premier appel complet dans le Sandbox. Les réponses montrées proviennent d'appels réels à l'API ; seuls les identifiants changeront chez vous. Recopiez la forme, pas les identifiants.

## Avant de commencer

Il vous faut une clé Sandbox, de la forme `nry_mer_sbx_<key_id>.<secret>`. Elle se crée dans la page [Clés d'API](https://platform.noryo.app/keys) de Platform, et son secret n'est affiché qu'une seule fois. Voir [Clés API](https://developer.noryo.app/fr-FR/merchant/authentication/api-keys).

```bash
export NORYO_API_KEY='nry_mer_sbx_<key_id>.<secret>'   # le secret affiché à la création
export NORYO_API='https://api.noryo.app'               # URL de base : à configurer, l'hôte n'est pas dans le contrat
```

## 1. Enrichir un libellé

```bash
curl -sS -i -X POST "$NORYO_API/merchant/v1/enrichments" \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-001" \
  -d '{
    "descriptor": "CB MCDONALDS PARIS 4519",
    "amount": 12.40,
    "currency": "EUR",
    "occurred_at": "2026-09-06T11:42:00Z",
    "country": "FR",
    "mcc": "5814",
    "external_transaction_id": "tx_demo_001"
  }'
```

```http
HTTP/1.1 200 OK
content-type: application/json
noryo-request-id: req_01a07868-6443-79fa-a4c8-221f1745244f
noryo-idempotency-replayed: false
noryo-ratelimit-limit: 60
noryo-ratelimit-remaining: 59
```

```json
{
  "enrichment_id": "enr_ffe80956-cc3e-4e1f-b4b6-724ad231fbb7",
  "merchant": {
    "name": "McDonald's",
    "category": "alimentation.restaurant",
    "location": { "city": "PARIS", "postal_code": "75018" },
    "logo_url": "https://www.mcdonalds.fr/apple-touch-icon.png",
    "confidence": 0.96
  },
  "enrichment": {
    "status": "resolved",
    "reason": null,
    "environment": "sandbox",
    "source": "noryo",
    "customized": false
  },
  "usage": { "billable": false, "units": 1, "deduplicated": false, "deduplicated_by": null }
}
```

Lisez d'abord `enrichment.status` : ici `resolved`. Dans le Sandbox, `billable` vaut toujours `false` ; `units: 1` est décompté de la dotation Sandbox. `confidence: 0.96` est un score, pas une probabilité : voir [Confidence](https://developer.noryo.app/fr-FR/merchant/results/confidence).

## 2. Rejouer la même requête

Relancez exactement la même commande, avec la même `Idempotency-Key` et le même corps.

```http
HTTP/1.1 200 OK
noryo-idempotency-replayed: true
```

Le corps est celui de la première réponse, rendu depuis la mémoire d'idempotence. Rien n'a été recalculé et rien de nouveau n'a été facturé. Le `noryo-request-id` est nouveau : chaque tentative a le sien. C'est ce mécanisme qui rend une reprise réseau sans danger. Voir [Idempotence](https://developer.noryo.app/fr-FR/merchant/requests/idempotency).

## 3. Relire le résultat

```bash
curl -sS "$NORYO_API/merchant/v1/enrichments/enr_ffe80956-cc3e-4e1f-b4b6-724ad231fbb7" \
  -H "Authorization: Bearer $NORYO_API_KEY"
```

```json
{
  "enrichment_id": "enr_ffe80956-cc3e-4e1f-b4b6-724ad231fbb7",
  "merchant": { "name": "McDonald's", "confidence": 0.96, "…": "…" },
  "enrichment": { "status": "resolved", "environment": "sandbox", "…": "…" },
  "retrieval": { "billable": false, "units": 0 },
  "original": { "billable": false, "units": 1 }
}
```

`retrieval` dit ce que coûte **cette lecture** : toujours rien. `original` dit ce qu'a coûté l'enrichissement quand il a eu lieu. Voir [Relire un enrichissement](https://developer.noryo.app/fr-FR/merchant/enrichments/read).

## 4. Rafraîchir

Un rafraîchissement recalcule la même transaction. Il exige une `Idempotency-Key` et la même entrée économique que l'appel d'origine, sans `external_transaction_id` dans le corps.

```bash
curl -sS -i -X POST "$NORYO_API/merchant/v1/enrichments/enr_ffe80956-cc3e-4e1f-b4b6-724ad231fbb7/refresh" \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-refresh-001" \
  -d '{"descriptor":"CB MCDONALDS PARIS 4519","amount":12.40,"currency":"EUR","occurred_at":"2026-09-06T11:42:00Z","country":"FR","mcc":"5814"}'
```

```http
HTTP/1.1 200 OK
location: /merchant/v1/enrichments/enr_dd424f15-6371-4565-a4dc-8770815d48c4
noryo-idempotency-replayed: false
```

Un **nouvel** `enrichment_id`, annoncé par un en-tête `Location` relatif. `enrichment.status` vaut `refresh_recalculated`, et l'ancien identifiant pointe toujours vers l'ancien résultat. Voir [Rafraîchir](https://developer.noryo.app/fr-FR/merchant/refresh).

## 5. Provoquer une erreur

Réutilisez la clé `demo-001` avec un autre corps :

```bash
curl -sS -X POST "$NORYO_API/merchant/v1/enrichments" \
  -H "Authorization: Bearer $NORYO_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-001" \
  -d '{"descriptor":"AUTRE CHARGE","external_transaction_id":"tx_autre"}'
```

```json
{
  "type": "https://developer.noryo.app/errors/idempotency_key_reuse",
  "title": "Idempotency key reused",
  "status": 409,
  "code": "idempotency_key_reuse",
  "detail": "this Idempotency-Key is bound to a different request for the remainder of its TTL",
  "request_id": "req_01a07784-d343-75f8-b0ae-b0629b305cd4"
}
```

Une clé reste liée à sa première requête pendant 24 heures. Toutes les erreurs ont cette forme ; bâtissez votre logique sur `code`. Voir [Erreurs](https://developer.noryo.app/fr-FR/merchant/error-handling).

## Et ensuite

- Envoyez les deux identifiants en production : la clé protège la reprise, l'identifiant de transaction protège la facture. Voir [Les deux identifiants](https://developer.noryo.app/fr-FR/merchant/identifiers).
- Mettez en place des reprises qui respectent `Retry-After` et gardent la même `Idempotency-Key`. Voir [Reprises](https://developer.noryo.app/fr-FR/merchant/operations/retries).
- Stockez de votre côté ce dont vous avez besoin : le contenu d'un résultat n'est conservé que 90 jours. Voir [Rétention et 410](https://developer.noryo.app/fr-FR/merchant/retention).
- Préparez la Production : voir [Passage en production](https://developer.noryo.app/fr-FR/merchant/going-live).

---

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