# Enrichment

> Chaque champ de l'objet Enrichment rendu par la création et le rafraîchissement, et du résultat stocké rendu par la lecture : type, présence, valeurs possibles.

L'objet `Enrichment` est la réponse `200` de `POST /merchant/v1/enrichments` et de `POST …/refresh`. La lecture `GET` rend la même structure, où `usage` est remplacé par `retrieval` et `original`.

## Champs de premier niveau

| Champ | Type | Présence | Description |
|---|---|---|---|
| `enrichment_id` | chaîne | toujours | Identité publique du résultat, `enr_<uuid>`. Nouvelle à chaque rafraîchissement. |
| `merchant` | objet ou `null` | toujours | L'identité marchande. `null` quand le statut est `not_found`. Voir [Merchant](https://developer.noryo.app/fr-FR/merchant/models/merchant). |
| `enrichment` | objet | toujours | Le verdict : statut, raison, environnement |
| `usage` | objet | création et rafraîchissement | Ce que **cet appel** a coûté |
| `retrieval` | objet | lecture `GET` uniquement | Ce que **cette lecture** coûte |
| `original` | objet | lecture `GET` uniquement | Ce qu'a coûté l'enrichissement quand il a eu lieu |

## `enrichment`

| Champ | Type | Valeurs |
|---|---|---|
| `status` | chaîne | `resolved`, `partial`, `not_found`, `refresh_recalculated`. Voir [Statuts](https://developer.noryo.app/fr-FR/merchant/enrichments/statuses). |
| `reason` | chaîne ou `null` | `null` pour `resolved` et `refresh_recalculated` ; sinon une valeur de la liste fermée (`no_usable_merchant_identity`, `missing_required_fields`, `confidence_below_threshold`, …) |
| `environment` | chaîne | `sandbox` ou `production`, l'environnement de la clé qui a créé le résultat |
| `source` | chaîne | L'origine du résultat. Aujourd'hui, toujours `noryo`. |
| `customized` | booléen | Indique un résultat personnalisé. Aujourd'hui, toujours `false`. |

## `usage` (création et rafraîchissement)

| Champ | Type | Description |
|---|---|---|
| `billable` | booléen | L'appel est facturé. Toujours `false` en Sandbox, et sur un rejeu par `external_transaction_id`. |
| `units` | entier | 1 pour `resolved` et `refresh_recalculated`, 0 sinon ; 0 sur un rejeu par `external_transaction_id` |
| `deduplicated` | booléen | `true` si la réponse vient de la déduplication économique |
| `deduplicated_by` | chaîne ou `null` | `external_transaction_id` quand `deduplicated` vaut `true`, `null` sinon |

> **Attention** Un rejeu par `Idempotency-Key` (`Noryo-Idempotency-Replayed: true`) rend le corps mémorisé à l'identique, `usage` compris. Ce `usage` décrit l'appel d'origine, pas le rejeu, qui n'est pas facturé.

## `retrieval` et `original` (lecture)

| Champ | Type | Description |
|---|---|---|
| `retrieval.billable` | booléen | Toujours `false` |
| `retrieval.units` | entier | Toujours `0` |
| `original.billable` | booléen | L'appel d'origine a été facturé |
| `original.units` | entier | Les unités de l'appel d'origine |

## Exemples

Un résultat `partial` en Production :

```json
{
  "enrichment_id": "enr_3b9c2a71-8f0e-4d6a-9c5b-1e2f3a4b5c6d",
  "merchant": { "name": "Enseigne", "category": "alimentation.restaurant", "location": null, "confidence": 0.62 },
  "enrichment": { "status": "partial", "reason": "confidence_below_threshold", "environment": "production", "source": "noryo", "customized": false },
  "usage": { "billable": false, "units": 0, "deduplicated": false, "deduplicated_by": null }
}
```

Un rejeu par `external_transaction_id` :

```json
{
  "enrichment_id": "enr_ffe80956-cc3e-4e1f-b4b6-724ad231fbb7",
  "merchant": { "name": "McDonald's", "category": "alimentation.restaurant", "location": { "city": "PARIS", "postal_code": "75018" }, "confidence": 0.96 },
  "enrichment": { "status": "resolved", "reason": null, "environment": "production", "source": "noryo", "customized": false },
  "usage": { "billable": false, "units": 0, "deduplicated": true, "deduplicated_by": "external_transaction_id" }
}
```

Ces deux exemples illustrent la forme ; leurs valeurs ne proviennent pas d'appels réels.

---

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