# Rafraîchir

> POST /merchant/v1/enrichments/{enrichment_id}/refresh recalcule une transaction connue et rend un nouvel enrichment_id. Ses conditions, sa facturation et chaque refus possible.

Un rafraîchissement recalcule l'identité marchande d'une transaction déjà enrichie et rend un **nouvel `enrichment_id`**, annoncé dans un en-tête `Location` relatif. L'ancien identifiant continue de pointer vers l'ancien résultat : un rafraîchissement ajoute un résultat, il n'en écrase pas un. Il exige le scope `enrich:write`.

## Les trois conditions

1. **Une `Idempotency-Key` est obligatoire.** Le rafraîchissement est délibérément exclu de la déduplication économique : c'est le seul chemin facturable sans déduplicateur, et la clé est sa seule protection contre une reprise réseau. Sans elle : `400 identifier_required`.
2. **L'enrichissement d'origine doit porter un `external_transaction_id`.** Un résultat créé avec une seule `Idempotency-Key` existe et se relit, mais il n'y a rien *contre quoi* recalculer : `409 refresh_not_available`. Relisez-le en `GET`, ou faites un nouvel appel portant un `external_transaction_id`.
3. **Le corps doit porter la même entrée économique que la transaction.** Un rafraîchissement est un recalcul de la même transaction, pas une correction : si l'entrée a changé, c'est une autre transaction, et la réponse est `409 input_mismatch`. Comme Noryo ne conserve pas le libellé brut, vous devez le renvoyer.

## Exemple

```bash
curl -sS -i -X POST "https://api.noryo.app/merchant/v1/enrichments/enr_ffe80956-cc3e-4e1f-b4b6-724ad231fbb7/refresh" \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refresh-tx_demo_001-2026-10-08" \
  -d '{"descriptor":"CB MCDONALDS PARIS 4519","amount":12.40,"currency":"EUR","occurred_at":"2026-09-06T11:42:00Z","country":"FR","mcc":"5814"}'
```

```http
HTTP/1.1 200 OK
location: /merchant/v1/enrichments/enr_dd424f15-6371-4565-a4dc-8770815d48c4
noryo-idempotency-replayed: false
```

Le corps a la même forme qu'une création ; `enrichment.status` y vaut `refresh_recalculated` quand le recalcul aboutit.

## Ce qu'un corps de rafraîchissement ne peut **pas** porter

Un rafraîchissement vise l'enrichissement nommé dans l'URL. Envoyer un `external_transaction_id` dans le corps est donc refusé :

```text
400  code: invalid_request   detail: unknown field: external_transaction_id
```

Ce n'est pas une formalité. Accepter les deux laisserait un même appel désigner deux identités économiques différentes, et il n'y aurait plus de réponse honnête à la question *laquelle avez-vous payée*. L'identifiant de transaction est dérivé de l'enrichissement cible, côté serveur.

## Le résultat, et sa facturation

| Statut du recalcul | Facturation (Production) | Devient le résultat courant de la transaction ? |
|---|---|---|
| `refresh_recalculated` | 1 unité | oui |
| `partial` | non facturé | non |
| `not_found` | non facturé | non |

Un rafraîchissement qui n'aboutit pas ne détruit jamais le résultat courant : il est consigné comme une tentative, avec son propre `enrichment_id`, et ce qu'un nouvel envoi de la transaction rend reste ce que vous avez payé en dernier. En Sandbox, `refresh_recalculated` consomme une unité de la dotation.

L'URL peut nommer n'importe quel enrichissement de la transaction, le premier comme un rafraîchissement antérieur : c'est la transaction qui est recalculée.

## Ce qui se passe si…

| Situation | Réponse |
|---|---|
| Pas d'`Idempotency-Key` | `400 identifier_required`, détail `refresh requires an Idempotency-Key` |
| `external_transaction_id` dans le corps | `400 invalid_request` |
| Identifiant de chemin inconnu, mal formé, d'un autre workspace ou environnement | `404 enrichment_not_found` |
| Enrichissement d'origine sans `external_transaction_id` | `409 refresh_not_available` |
| Entrée économique différente de celle de la transaction | `409 input_mismatch` |
| Même `Idempotency-Key` et même requête, dans les 24 heures | `200`, rejeu de la réponse mémorisée, `Noryo-Idempotency-Replayed: true` |
| Même `Idempotency-Key` déjà utilisée pour une autre requête (une création, par exemple) | `409 idempotency_key_reuse` |
| Moteur indisponible | `503 engine_error`, rien n'est facturé ni mémorisé : reprenez avec la même clé |
| Dotation Sandbox épuisée | `402 sandbox_quota_exhausted` |

## Après une expiration

Quand le contenu d'un résultat a dépassé ses 90 jours de rétention, la transaction reste connue. Un rafraîchissement avec la même entrée économique la recalcule et produit un nouveau résultat lisible ; il est facturé s'il aboutit. Voir [Rétention et 410](https://developer.noryo.app/fr-FR/merchant/retention).

---

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