# Vue d'ensemble

> Ce que Noryo Transaction Intelligence fait d'une transaction brute, ce qu'elle n'est pas, et par où commencer.

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](https://developer.noryo.app/fr-FR/transaction-intelligence/reference) 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](https://developer.noryo.app/fr-FR/transaction-intelligence/enrich-a-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](https://developer.noryo.app/fr-FR/transaction-intelligence/counterparties-and-entities).

### 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](https://developer.noryo.app/fr-FR/transaction-intelligence/transaction-types).

### 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](https://developer.noryo.app/fr-FR/transaction-intelligence/relationships) et [Séries récurrentes](https://developer.noryo.app/fr-FR/transaction-intelligence/recurring-series).

### 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](https://developer.noryo.app/fr-FR/transaction-intelligence/score-semantics).

## Les trois opérations

| Opération | Ce qu'elle fait | Réponse |
| --- | --- | --- |
| `POST /transactions/v1/enrichments` | Enrichit une transaction et crée un `Enrichment` | `201`, ou `200` sur un rejeu avec `Idempotency-Key` |
| `GET /transactions/v1/enrichments/{enrichment_id}` | Relit un enrichissement rendu, pendant 30 jours | `200`, puis `404` après expiration |
| `POST /transactions/v1/coverage-windows` | Déclare ce que vous avez fourni pour un compte sur une période | `200`, intervalles voisins fusionnés |

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](https://developer.noryo.app/fr-FR/transaction-intelligence/observation-coverage).

Toutes trois s'authentifient par une clé de la famille `txn`, envoyée dans `Authorization: Bearer nry_txn_sbx_…` et créée sur [Platform](https://platform.noryo.app/keys). 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](https://developer.noryo.app/fr-FR/transaction-intelligence/errors). Schémas et exemples complets : [référence](https://developer.noryo.app/fr-FR/transaction-intelligence/reference).

## Sandbox et calibration

> **Note** TI est aujourd'hui disponible en sandbox uniquement : aucune clé de production n'existe et rien n'est facturé. Les nombres des réponses (`confidence`, `strength`, `match_strength`) sont des forces d'évidence déterministes et non des probabilités : le contrat les marque `calibration = non_calibree` et `is_probability = false`, parce qu'aucun corpus de référence ne permet encore de les rapporter à une fréquence observée. Comparez-les au sein d'une même classe et d'un même type, et décidez sur `policy.outcome`.

## Plan de la documentation

- [Quickstart](https://developer.noryo.app/fr-FR/transaction-intelligence/quickstart) : de l'identité Noryo au premier enrichissement.
- [Authentification](https://developer.noryo.app/fr-FR/transaction-intelligence/authentication) : la famille de clés `txn` et l'en-tête `Authorization`.
- [Enrichir une transaction](https://developer.noryo.app/fr-FR/transaction-intelligence/enrich-a-transaction) : `TransactionInput`, signaux utilisés, idempotence.
- [Relire un enrichissement](https://developer.noryo.app/fr-FR/transaction-intelligence/read-an-enrichment) : `GET` par `enrichment_id`, expiration.
- [Couverture d'observation](https://developer.noryo.app/fr-FR/transaction-intelligence/observation-coverage) : déclarer ce qui a été fourni pour un compte.
- [Contreparties et entités](https://developer.noryo.app/fr-FR/transaction-intelligence/counterparties-and-entities) : marque, entité légale, activité, provenance.
- [Types de transaction](https://developer.noryo.app/fr-FR/transaction-intelligence/transaction-types) : ce qui s'est passé, par opposition au rail.
- [Relations](https://developer.noryo.app/fr-FR/transaction-intelligence/relationships) : `refund_of`, `reversal_of`, `transfer_pair`.
- [Séries récurrentes](https://developer.noryo.app/fr-FR/transaction-intelligence/recurring-series) : `series_id`, cadence, ancrage calendaire.
- [Cycle de vie d'une série](https://developer.noryo.app/fr-FR/transaction-intelligence/series-lifecycle) : `active`, `late`, `inactive`, `ended`, `unknown`.
- [Scission, fusion, supersession](https://developer.noryo.app/fr-FR/transaction-intelligence/split-merge-supersession) : quand l'identité d'une série est corrigée.
- [Sémantique des scores](https://developer.noryo.app/fr-FR/transaction-intelligence/score-semantics) : ce que chaque nombre mesure et à quoi il se compare.
- [Erreurs](https://developer.noryo.app/fr-FR/transaction-intelligence/errors) : l'objet `Problem` et le catalogue [/errors](https://developer.noryo.app/fr-FR/transaction-intelligence/errors).
- [Limites de débit](https://developer.noryo.app/fr-FR/transaction-intelligence/rate-limits) : seau à jetons, `429`, `Retry-After`.
- [Limites du sandbox](https://developer.noryo.app/fr-FR/transaction-intelligence/sandbox-limitations) : ce que le sandbox ne fait pas.
- [Usage et clés d'API](https://developer.noryo.app/fr-FR/transaction-intelligence/usage-and-api-keys) : créer, révoquer, lire l'usage sur Platform.

---

Page canonique : https://developer.noryo.app/fr-FR/transaction-intelligence