Aller au contenu
Sandbox

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.

Voir en Markdown

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 de Platform, et son secret n'est affiché qu'une seule fois. Voir Clés API.

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
Shell

1. Enrichir un libellé

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"
  }'
Shell
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
HTTP
{
  "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 }
}
JSON

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.

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/1.1 200 OK
noryo-idempotency-replayed: true
HTTP

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.

3. Relire le résultat

curl -sS "$NORYO_API/merchant/v1/enrichments/enr_ffe80956-cc3e-4e1f-b4b6-724ad231fbb7" \
  -H "Authorization: Bearer $NORYO_API_KEY"
Shell
{
  "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 }
}
JSON

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.

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.

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"}'
Shell
HTTP/1.1 200 OK
location: /merchant/v1/enrichments/enr_dd424f15-6371-4565-a4dc-8770815d48c4
noryo-idempotency-replayed: false
HTTP

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.

5. Provoquer une erreur

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

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"}'
Shell
{
  "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"
}
JSON

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.

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.
  • Mettez en place des reprises qui respectent Retry-After et gardent la même Idempotency-Key. Voir Reprises.
  • 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.
  • Préparez la Production : voir Passage en production.

Publié le 2026-10-09 10:18 UTC (version 2).

Cette page vous a-t-elle aidé ?