# Modèles

> Les objets que l'API reçoit et rend, comment ils s'emboîtent, et comment les identifiants se relient entre eux : transaction, enrichissement, clé d'idempotence, tentative.

Noryo Merchant API échange peu d'objets, tous décrits dans le contrat OpenAPI et dans la [référence de l'API](https://developer.noryo.app/fr-FR/merchant/reference). Cette section les présente du point de vue de l'intégrateur : ce que chaque champ garantit, quand il est présent, et quand il vaut `null`.

## La carte des objets

| Objet | Où | Contenu |
|---|---|---|
| `CreateRequest` | Corps de `POST /merchant/v1/enrichments` | `descriptor` et les champs économiques facultatifs, plus `external_transaction_id`. Voir [Formats](https://developer.noryo.app/fr-FR/merchant/requests/formats). |
| `RefreshRequest` | Corps de `POST …/refresh` | Les six champs économiques, sans `external_transaction_id` |
| `Enrichment` | Réponse `200` des deux routes `POST` | `enrichment_id`, `merchant`, `enrichment`, `usage`. Voir [Enrichment](https://developer.noryo.app/fr-FR/merchant/models/enrichment). |
| Résultat stocké | Réponse `200` de `GET` | `enrichment_id`, `merchant`, `enrichment`, `retrieval`, `original` |
| `Merchant` | Champ `merchant` | `name`, `category`, `logo_url`, `location`, `confidence`. Voir [Merchant](https://developer.noryo.app/fr-FR/merchant/models/merchant). |
| Location | Champ `merchant.location` | `city`, `postal_code`, ou `null`. Voir [Location](https://developer.noryo.app/fr-FR/merchant/models/location). |
| `Problem` | Toute réponse d'erreur | `type`, `title`, `status`, `code`, `detail`, `request_id`. Voir [Erreurs](https://developer.noryo.app/fr-FR/merchant/error-handling). |

```text
Enrichment
├── enrichment_id
├── merchant ─────── Merchant | null
│                    ├── name, category, logo_url, confidence
│                    └── location ── { city, postal_code } | null
├── enrichment ───── status, reason, environment, source, customized
└── usage ────────── billable, units, deduplicated, deduplicated_by
```

## Les relations entre identifiants

Quatre identifiants circulent, chacun à son échelle :

| Identifiant | Désigne | Choisi par | Durée de vie |
|---|---|---|---|
| `external_transaction_id` | Une transaction économique | Vous | Pas d'expiration |
| `enrichment_id` | Un résultat figé | Noryo | Contenu lisible 90 jours, identité conservée |
| `Idempotency-Key` | Une requête et sa réponse | Vous | 24 heures |
| `Noryo-Request-Id` | Une tentative HTTP | Noryo | Celle de vos journaux |

Leurs relations :

- **Une transaction a un ou plusieurs enrichissements** : le premier, puis un par rafraîchissement. L'un d'eux est son résultat courant. Voir [Cycle de vie](https://developer.noryo.app/fr-FR/merchant/enrichments/lifecycle).
- **Une `Idempotency-Key` désigne une seule requête** pendant 24 heures, donc au plus un enrichissement.
- **Une requête peut donner plusieurs tentatives** : chaque reprise a son propre `Noryo-Request-Id`, même quand elle rend la réponse mémorisée.
- **Un enrichissement sans `external_transaction_id`** n'appartient à aucune transaction : il ne se déduplique pas et ne se rafraîchit pas.

## Règles de présence

- `merchant` est toujours présent : un objet, ou `null` quand le statut est `not_found`.
- `merchant.location` est toujours présent quand `merchant` est un objet : un objet, ou `null`.
- `merchant.category` et `merchant.logo_url` sont omis quand ils sont inconnus.
- `enrichment.reason` est toujours présent : une raison, ou `null`.
- `usage.deduplicated_by` est toujours présent : `external_transaction_id`, ou `null`.

Écrivez un client qui ignore les champs de réponse qu'il ne connaît pas, et qui accepte qu'un champ facultatif soit absent.

---

Page canonique : https://developer.noryo.app/fr-FR/merchant/models