Vue d'ensemble

Noryo Transaction Intelligence (TI) est une API HTTP qui prend une transaction financière telle qu'elle sort d'un relevé (un libellé, un sens, un montant, une date) et en rend une lecture structurée : qui est en face, ce que cette entité fait, à quoi l'argent est allé, ce qui s'est réellement passé, et comment cette opération se relie aux autres opérations de votre workspace. Les réponses sont en JSON, servies sur https://api.noryo.app, et le contrat complet est publié en OpenAPI 3.1 sur https://api.noryo.app/openapi.json. La référence de ce portail est générée depuis ce même document.

Ce que TI n'est pas

TI lit des transactions, elle n'en exécute aucune. Elle n'est pas un prestataire de services de paiement : aucun argent ne transite par elle. Elle n'est pas une banque ni une plateforme de banking-as-a-service : elle ne tient aucun compte et ne conserve aucun numéro de compte (un IBAN est réduit dès l'entrée à son pays et à son code banque). Elle n'est pas un grand livre : un enrichissement est une lecture opérationnelle, relisible pendant 30 jours, pas une écriture comptable.

La chaîne, d'une transaction brute à un sens structuré

Un appel POST /transactions/v1/enrichments reçoit un TransactionInput et rend un Enrichment. Entre les deux, chaque étape du moteur laisse une trace lisible dans la réponse.

1. La transaction brute

Vous envoyez un descriptor (le libellé tel que la banque l'a écrit), une direction (incoming ou outgoing) et, si vous en disposez, occurred_at, amount, payment, location_hint, counterparty_hint, account_hint et external_transaction_id. Le schéma est fermé : un champ inconnu est refusé (422), jamais ignoré en silence. La réponse dit ensuite, dans signals.used et signals.ignored, quels signaux ont réellement pesé et lesquels n'ont été lus par personne. Voir Enrichir une transaction.

2. La normalisation

Le libellé est ramené à une forme canonique. resolution.normalized rend le descriptor nettoyé, le signal retenu, la partie useful et le residual, avec la normalizer_version qui les a produits. La transaction reçoit aussi une empreinte économique, fingerprint, calculée sous canonical_version : c'est elle qui fonde l'idempotence, pas votre identifiant external_transaction_id.

3. La contrepartie et l'entité

Le libellé normalisé est confronté au graphe d'entités partagé de Noryo. Quand une entité est reconnue, resolution.counterparty porte son entity_id, son name, son kind (brand ou organisation) et ses semantics : les roles de l'entité, son activity (le métier, en noms d'industrie), sa legal_entity (une marque n'est pas la société qui contracte), son recurring_model (l'habitude du métier, pas un verdict sur cette transaction) et une provenance dont la nature est déclarée : curated, deterministic, provider, inferred ou participant, dans cet ordre d'autorité. Quand rien n'est reconnu, counterparty vaut null : c'est un résultat, pas une panne, et counterparty_note ou identity_abstention dit pourquoi. Voir Contreparties et entités.

4. Catégorie, lieu, intermédiaires

resolution.category répond à « à quoi l'argent est allé », en ligne de budget, et dit d'où elle vient (source : entity_graph ou generic_trade_entry) ; un libellé qui nomme un métier plutôt qu'une enseigne remplit la catégorie et laisse counterparty à null. resolution.intermediaries liste les facilitateurs de paiement lus dans le libellé (PAYPAL *NETFLIX en donne un) : ils ne sont jamais la contrepartie. Le lieu, lui, n'est pas résolu dans cette version : location_hint.country est un signal d'entrée utilisé, mais confidence.location vaut toujours 0 et aucun lieu n'est rendu.

5. Le type de transaction

resolution.transaction_type dit ce que la transaction signifie (canonical), par quelle règle (evidence) et s'il y a eu contradiction. Il se distingue de resolution.payment, qui dit comment l'argent a circulé (rail, mechanism) : un salaire reçu par virement SEPA est les deux. Quand deux signaux se contredisent, signal_conflicts le rend et aucune certitude n'est fabriquée. Voir Types de transaction.

6. Relations et récurrence

La transaction est ensuite rapprochée des autres transactions de votre workspace. relationships[] porte les liens économiques entre deux opérations (refund_of, reversal_of, transfer_pair), avec le role de celle-ci et l'identifiant de l'autre dans counterpart. series[] porte les séries récurrentes auxquelles elle appartient (recurring_payment, subscription, recurring_income, salary_series), avec leur cadence, leur status, leur lifecycle et leur identity. Ce qu'un workspace observe reste dans ce workspace et n'alimente jamais le graphe partagé. Voir Relations et Séries récurrentes.

7. Un sens financier structuré

resolution.policy résume le tout : outcome vaut resolved, partial ou unresolved selon l'archetype de la transaction, et missing nomme ce qui manque. Un virement à une personne est resolved sans entité ; un achat carte exige sa contrepartie. C'est ce champ, et non un nombre, qu'il faut lire pour décider. Voir Sémantique des scores.

Les trois opérations

Sans déclaration de couverture (completeness : complete, partial ou unknown), une absence ne prouve rien : le cycle de vie d'une série reste unknown plutôt que de passer late. Noryo enregistre votre déclaration telle quelle (provenance vaut toujours caller_asserted) et ne vérifie pas l'exhaustivité d'une banque. Voir Couverture d'observation.

Toutes trois s'authentifient par une clé de la famille txn, envoyée dans Authorization: Bearer nry_txn_sbx_… et créée sur Platform. Le document GET /openapi.json est public : aucune clé, aucun débit consommé. Chaque réponse authentifiée porte un en-tête noryo-request-id, chaque erreur un request_id dans son corps ; chaque erreur de l'API est un objet Problem dont le type est catalogué sur /errors. Schémas et exemples complets : référence.

Sandbox et calibration

Plan de la documentation

• Quickstart : de l'identité Noryo au premier enrichissement.
• Authentification : la famille de clés txn et l'en-tête Authorization.
• Enrichir une transaction : TransactionInput, signaux utilisés, idempotence.
• Relire un enrichissement : GET par enrichment_id, expiration.
• Couverture d'observation : déclarer ce qui a été fourni pour un compte.
• Contreparties et entités : marque, entité légale, activité, provenance.
• Types de transaction : ce qui s'est passé, par opposition au rail.
• Relations : refund_of, reversal_of, transfer_pair.
• Séries récurrentes : series_id, cadence, ancrage calendaire.
• Cycle de vie d'une série : active, late, inactive, ended, unknown.
• Scission, fusion, supersession : quand l'identité d'une série est corrigée.
• Sémantique des scores : ce que chaque nombre mesure et à quoi il se compare.
• Erreurs : l'objet Problem et le catalogue /errors.
• Limites de débit : seau à jetons, 429, Retry-After.
• Limites du sandbox : ce que le sandbox ne fait pas.
• Usage et clés d'API : créer, révoquer, lire l'usage sur Platform.