Enrichir une transaction

Une transaction brute entre, un enrichissement structuré sort. POST /transactions/v1/enrichments prend un objet TransactionInput, authentifié par votre clé nry_txn_sbx_* (voir Authentification), et rend un objet Enrichment : contrepartie, type de transaction, relations, séries. Cette page décrit le corps attendu, l'en-tête Idempotency-Key, la différence entre 201 et 200, et les deux blocs à lire en premier : signals et resolution.policy.

L'opération

Le corps est du application/json, sinon 415. Toute erreur porte request_id dans son corps, à citer au support ; une fois la credential acceptée, chaque réponse porte aussi les en-têtes noryo-request-id, noryo-ratelimit-limit et noryo-ratelimit-remaining (voir Limites de débit).

Le corps : TransactionInput

Seuls descriptor et direction sont requis ; un champ facultatif n'est utile que s'il est lu (voir signals.used plus bas).

Un schéma fermé

Un champ inconnu n'est jamais ignoré : il est refusé par un 422 invalid_input dont errors[] porte field et code, ici unknown_field. La règle vaut aussi à l'intérieur de payment, location_hint, counterparty_hint et account_hint, et un tableau à la place de l'un de ces objets est refusé must_be_object.

occurred_at : un instant, pas une date

La valeur est un horodatage RFC 3339 avec décalage, par exemple 2026-09-09T07:31:00+02:00. Une date seule est refusée : minuit n'est pas le même jour partout, et la cadence des séries se lit au calendrier. Le code must_be_rfc3339_with_offset couvre la forme et le calendrier : 2026-02-30T00:00:00Z, un décalage +16:00 ou une seconde 23:59:60 sont refusés.

amount : un décimal en chaîne

amount.value est une chaîne ("49.90"), jamais un nombre JSON : un flottant perdrait des centimes en silence. Le nombre de décimales admis dépend de la devise : 5.905 en EUR est refusé (amount_precision_exceeds_currency), 100.50 en ISK aussi, car ISK et JPY n'en ont aucune et KWD en a trois. currency doit appartenir à l'enum de Money.currency ; toute autre devise rend un 422 de type unknown_currency.

account_hint et counterparty_hint

L'IBAN, du compte comme de la contrepartie, est réduit dès l'entrée à son pays et son code banque : le numéro de compte n'entre pas dans le système. Sans account_hint, une paire de virement ne peut pas être identifiée. Pour une carte ou un portefeuille sans IBAN, external_account_id porte votre propre identifiant ; il sert à relier la transaction à une couverture d'observation déclarée sur le même compte et n'entre pas dans l'empreinte.

external_transaction_id n'entre pas non plus dans l'empreinte : il dit comment vous nommez la transaction, pas ce qu'elle est, et il empêche deux envois d'une même transaction d'être rapprochés l'un de l'autre.

Idempotency-Key

L'en-tête est facultatif. Sa valeur va de 1 à 255 octets d'ASCII visible (0x21 à 0x7E) ; une valeur vide ou hors alphabet rend un 400 invalid_idempotency_key.

« Requête différente » se juge sur l'empreinte économique, et sur elle seule. Deux corps qui ne diffèrent que par external_transaction_id, account_hint ou counterparty_hint ont la même empreinte : le premier envoi est rejoué. Ne réutilisez donc pas une clé pour deux transactions que vous ne distinguez que par ces champs. Une clé est retenue au moins 24 heures ; au-delà, elle peut ouvrir une opération neuve.

201 ou 200

Un 201 signifie qu'un enrichissement a été créé ; un 200, qu'une requête déjà traitée a été rejouée, sans rien créer. Les deux portent un en-tête Location vers la ressource, relisible pendant 30 jours par GET /transactions/v1/enrichments/{enrichment_id} (voir Relire un enrichissement). Le corps est un Enrichment : enrichment_id, created_at, contract_version, canonical_version, fingerprint, signals, resolution, puis relationships et series (listes vides quand aucune relation ni série n'a été conclue) et relationships_policy, dont unresolved dit pourquoi un détecteur n'a pas conclu.

signals.used et signals.ignored

signals.used liste les signaux reçus qui ont été transmis au moteur : au résolveur d'identité, ou à la base pour les séries, les relations et la couverture d'observation. signals.ignored liste ceux que personne n'a lus. Seuls les champs présents dans votre requête figurent dans l'une ou l'autre liste. Aujourd'hui, payment.mcc, payment.card_present, payment.network_merchant_id, location_hint.city, location_hint.postal_code et counterparty_hint.bic sont acceptés puis ignorés.

Ce bloc n'est pas une commodité : sans lui, vous pourriez envoyer un MCC pendant des mois, recevoir 201, et croire qu'il pèse sur la réponse. Vérifiez dans vos tests d'intégration qu'aucun champ dont vous dépendez n'apparaît dans ignored. signals.conflicting recopie resolution.signal_conflicts, pour que le bloc soit complet.

Le sens de policy.outcome

resolution.policy dit ce que la réponse affirme, et c'est le champ à utiliser pour décider. Il porte outcome, archetype, missing et policy_version.

Ce que « résolu » veut dire dépend de la nature de la transaction. Un virement à une personne est resolved sans qu'aucune identité ne soit créée ; un retrait d'espèces est resolved sans marchand ; un achat carte, lui, exige sa contrepartie, et son absence rend partial avec missing: ["counterparty_entity"]. Un counterparty à null est un résultat, pas une panne, et counterparty_note dit pourquoi. Les nombres de resolution.confidence sont des constantes déclarées, ni probabilités ni seuils : voir Sémantique des scores.

Exemples

Avec curl :

curl -X POST https://api.noryo.app/transactions/v1/enrichments \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tx-2026-09-09-0042" \
  -d '{
    "descriptor": "CARTE 09/09 MONOPRIX PARIS 15",
    "direction": "outgoing",
    "occurred_at": "2026-09-09T07:31:00+02:00",
    "amount": { "value": "49.90", "currency": "EUR" },
    "payment": { "rail": "card", "mcc": "5411", "card_present": true },
    "location_hint": { "country": "FR" },
    "account_hint": { "iban": "FR7630006000011234567890189" },
    "external_transaction_id": "tx-2026-09-09-0042"
  }'

Avec fetch :

const response = await fetch("https://api.noryo.app/transactions/v1/enrichments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "tx-2026-09-09-0042",
  },
  body: JSON.stringify({
    descriptor: "CARTE 09/09 MONOPRIX PARIS 15",
    direction: "outgoing",
    occurred_at: "2026-09-09T07:31:00+02:00",
    amount: { value: "49.90", currency: "EUR" },
    payment: { rail: "card", mcc: "5411", card_present: true },
    location_hint: { country: "FR" },
    account_hint: { iban: "FR7630006000011234567890189" },
    external_transaction_id: "tx-2026-09-09-0042",
  }),
});

const enrichment = await response.json();
console.log(response.status, enrichment.signals, enrichment.resolution.policy);

Sur cette requête, la réponse liste payment.mcc et payment.card_present dans signals.ignored.

Réponses d'erreur

Toute erreur rendue par l'API est un objet Problem avec type, title, status et request_id, detail quand l'API en donne un et, sur un 422, errors[]. Un 401 signale une credential absente, mal formée, d'une autre famille, inconnue ou révoquée ; un 403 un workspace inactif ; un 413 un corps trop volumineux ; un 415 un corps qui n'est pas du application/json ; un 429 une limite de débit atteinte, à rejouer après Retry-After. Les cas 400, 409 et 422 sont décrits plus haut. Le catalogue complet est sur Erreurs et sur /transaction-intelligence/errors/<code>.