Quickstart

Ce guide mène d'une identité Noryo à un premier enrichissement relu, en sept étapes, entièrement dans le sandbox : aucune clé de production n'existe aujourd'hui, et rien n'est facturé. Il vous faut :

• une identité Noryo (https://auth.noryo.app) et l'appartenance à un workspace sur https://platform.noryo.app ;
• curl, ou un Node.js récent où fetch est natif, pour les exemples TypeScript.

11. Activer le sandbox sur Platform

Connectez-vous à https://platform.noryo.app avec votre identité Noryo et ouvrez la page Clés d'API (/keys).

Complétez d'abord le profil développeur du workspace : prénom, nom, courriel vérifié, téléphone professionnel, nom d'organisation, puis ce que vous construisez et votre contexte d'intégration. Un owner ou un admin le remplit une fois, pour tout le workspace. Tant qu'un élément manque, l'activation est refusée et aucune clé n'est émise ; Platform liste les éléments manquants. Détail sur Accès production.

Le profil complet, un owner ou un admin clique sur Activer le sandbox Transaction Intelligence. L'activation est un choix du workspace, journalisé : elle ne crée rien d'autre qu'un droit d'émettre des clés nry_txn_sbx_, sans intervention de Noryo.

22. Créer une clé et copier le secret

Nommez la clé (par exemple « intégration de test ») et cliquez sur Créer une clé Sandbox. Un owner, un admin ou un developer peut créer et révoquer des clés ; tout membre peut les lister. Le nombre de clés actives par workspace est plafonné (le plafond est lu du serveur ; les révoquées ne comptent pas).

Le credential a la forme nry_txn_sbx_<key_id>.<secret>. Le key_id est public (10 caractères) et reste visible dans la liste. Le secret n'est affiché qu'une fois, à la création : Noryo ne le conserve pas, seul un vérificateur HMAC est stocké. Copiez-le maintenant. Perdu, il n'existe pas de bouton de rotation : révoquez la clé et créez-en une nouvelle. Une clé révoquée rend 401 dès la requête suivante.

33. Ranger le secret dans une variable d'environnement

Le secret vit côté serveur, dans une variable d'environnement. Tous les exemples lisent NORYO_API_KEY.

export NORYO_API_KEY="nry_txn_sbx_..."

Ne le placez jamais dans un bundle navigateur, un dépôt public, un binaire mobile ou du JavaScript côté client. Une clé nry_mer_* (Merchant API) est refusée sur Transaction Intelligence, et réciproquement. Détail sur Authentification.

44. Premier appel : enrichir une transaction

Le corps est un TransactionInput. Deux champs suffisent : descriptor, le libellé tel que la banque le rend, et direction, incoming ou outgoing. Le schéma est fermé : un champ inconnu est refusé 422, jamais ignoré. Le corps est du application/json, sinon 415.

Corps minimal

curl -sS -i https://api.noryo.app/transactions/v1/enrichments \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"descriptor":"CARTE 09/09 MONOPRIX PARIS","direction":"outgoing"}'

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",
  },
  body: JSON.stringify({ descriptor: "CARTE 09/09 MONOPRIX PARIS", direction: "outgoing" }),
});

console.log(response.status, response.headers.get("location")); // 201
const enrichment = await response.json();
console.log(enrichment.enrichment_id);

Statut 201 : l'enrichissement est créé. L'en-tête Location dit où il vit, et le corps porte son enrichment_id, de la forme enr_<uuid>. Conservez-le pour l'étape 5.

Exemple complet

L'exemple achat_carte du contrat : occurred_at en RFC 3339 avec décalage, amount.value en chaîne, le compte dans account_hint (pour relier une couverture), votre identifiant dans external_transaction_id.

curl -sS https://api.noryo.app/transactions/v1/enrichments \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -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"
  }'

const transaction = {
  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 response = await fetch("https://api.noryo.app/transactions/v1/enrichments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(transaction),
});

const enrichment = await response.json();
console.log(enrichment.resolution.policy.outcome);

Ce que la réponse contient

Extrait de la réponse 201 du contrat pour cet exemple :

{
  "enrichment_id": "enr_3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "created_at": "2026-09-09T05:31:02Z",
  "contract_version": "ti_v1",
  "canonical_version": "canon_ti_v1",
  "fingerprint": "canon_ti_v1:c2a1…",
  "signals": {
    "used": ["descriptor", "direction", "payment.rail", "location_hint.country", "occurred_at", "amount", "account_hint.iban", "external_transaction_id"],
    "ignored": ["payment.mcc", "payment.card_present"],
    "conflicting": []
  },
  "resolution": {
    "policy": { "outcome": "resolved", "archetype": "achat_carte", "missing": [], "policy_version": "ti_resolution_v1" },
    "counterparty": { "entity_id": "b83d1756-258c-4541-adc7-54eec83dbd3c", "name": "Monoprix", "kind": "brand" },
    "category": { "slug": "alimentation.supermarche", "label": "Supermarché", "source": "entity_graph" },
    "transaction_type": { "canonical": "card_purchase", "evidence": "rail_rule", "contradiction": null }
  },
  "relationships": [],
  "series": [],
  "relationships_policy": {
    "detector_version": "rel_v1",
    "calibration": "non_calibree",
    "unresolved": [{ "type": "series", "outcome": "single_occurrence", "occurrences": 1 }]
  }
}

À lire d'abord :

• signals.used et signals.ignored disent quels signaux reçus ont été transmis au moteur et lesquels personne n'a lus (ici payment.mcc et payment.card_present).
• resolution.policy.outcome est le verdict (resolved). Lisez-le, pas les nombres de confidence : des constantes déclarées, pas des probabilités (voir Sémantique des scores).
• counterparty peut valoir null : un inconnu honnête, pas une panne, et counterparty_note dit pourquoi.

Une seule occurrence ne fait pas une série : relationships_policy.unresolved le dit (single_occurrence). Tous les champs sont sur Enrichir une transaction.

55. Relire l'enrichissement

Avec l'identifiant reçu à l'étape 4 :

curl -sS https://api.noryo.app/transactions/v1/enrichments/enr_3f2504e0-4f89-41d3-9a0c-0305e82c3301 \
  -H "Authorization: Bearer $NORYO_API_KEY"

const enrichmentId = "enr_3f2504e0-4f89-41d3-9a0c-0305e82c3301";
const response = await fetch(
  `https://api.noryo.app/transactions/v1/enrichments/${enrichmentId}`,
  { headers: { Authorization: `Bearer ${process.env.NORYO_API_KEY}` } },
);

console.log(response.status); // 200
const stored = await response.json();
console.log(stored.expires_at);

La réponse 200 est un StoredEnrichment :

Un identifiant inconnu, malformé, expiré ou d'un autre workspace rend 404, la même réponse dans les quatre cas. Voir Relire un enrichissement.

66. Déclarer une couverture d'observation (facultatif)

Une couverture est un fait de compte et de période, pas de transaction : vous déclarez si toutes les opérations d'un compte entre deux dates ont été fournies (completeness : complete, partial ou unknown). Seul complete autorise Noryo à conclure d'une absence. Sans elle, une échéance absente ne prouve rien et le cycle de vie d'une série reste unknown. Le compte est celui de l'enrichissement (account_hint).

curl -sS https://api.noryo.app/transactions/v1/coverage-windows \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_hint": { "iban": "FR7630006000011234567890189" },
    "covered_from": "2026-07-01",
    "covered_to": "2026-07-31",
    "completeness": "complete"
  }'

const response = await fetch("https://api.noryo.app/transactions/v1/coverage-windows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    account_hint: { iban: "FR7630006000011234567890189" },
    covered_from: "2026-07-01",
    covered_to: "2026-07-31",
    completeness: "complete",
  }),
});

console.log(response.status, await response.json()); // 200

Réponse 200 du contrat :

{
  "covered_from": "2026-07-01",
  "covered_to": "2026-07-31",
  "completeness": "complete",
  "provenance": "caller_asserted",
  "merged_intervals": 0,
  "policy_version": "cov_v1",
  "note": "",
  "request_id": "req_01J9…"
}

provenance vaut toujours caller_asserted : Noryo enregistre votre déclaration sans la vérifier. Les intervalles qui se touchent fusionnent (merged_intervals) ; covered_to ne peut pas être dans le futur. Voir Couverture d'observation.

77. Lire l'usage sur Platform

Sur https://platform.noryo.app/usage, section Transaction Intelligence, vous lisez sur 24 h, 7 jours ou 30 jours, par jour UTC, par famille d'appel et par clé : le total des requêtes authentifiées, les succès (2xx), les erreurs client (4xx hors 429), les requêtes limitées (429, par clé ou par workspace) et les erreurs serveur (5xx). Une clé révoquée garde son historique ; le registre est conservé 35 jours.

Ce n'est pas un grand livre de facturation : un 422 compte comme une requête, un 401 n'est jamais compté, rien n'est facturé. Un zéro se distingue de « non observé » (avant la mise en service du registre) et d'« indisponible ». Voir Usage et clés d'API.

En-têtes et débit

Une fois la credential acceptée, chaque réponse porte noryo-request-id, l'identifiant à citer au support (sur une erreur, il est aussi dans le corps, request_id), ainsi que noryo-ratelimit-limit et noryo-ratelimit-remaining. Sur 429, Retry-After donne les secondes à attendre. Le débit est une protection opérationnelle :

Et ensuite

• Authentification : familles de clés, révocation, où ranger le secret.
• Enrichir une transaction, Relire un enrichissement, Couverture d'observation.
• Séries récurrentes et Relations : ce que plusieurs transactions font apparaître.
• Erreurs, Limites de débit, Limites du sandbox.
• La référence et le catalogue d'erreurs, générés depuis https://api.noryo.app/openapi.json.