# Recalculer un enrichissement

`POST /merchant/v1/enrichments/{enrichment_id}/refresh` — Merchant API · [Référence API](https://developer.noryo.app/fr-FR/merchant/reference)

Authentification : `bearerCredential` (http bearer).

Recalcule l'identité de marchand d'un enrichissement existant et rend un
**nouvel** `enrichment_id` : un rafraîchissement produit un nouveau résultat, il reçoit
donc une nouvelle identité. L'ancienne continue de pointer vers l'ancien instantané.

**L'`Idempotency-Key` est obligatoire ici.** 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.

## Paramètres

| Nom | Dans | Requis | Type | Description |
| --- | --- | --- | --- | --- |
| `enrichment_id` | path | oui | string | `enr_` suivi d'un UUID de version 4, tel que Noryo le rend. Toute autre forme rend `404`. Motif : `^enr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`. |
| `Idempotency-Key` | header | oui | string · length 1–255 | Obligatoire pour un rafraîchissement. Voir la description de la route. Motif : `^[\x21-\x7E]+$`. |

## Corps de la requête

`application/json` · requis · Schéma `RefreshRequest`

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `descriptor` | string · length ≤ 512 | oui | — |
| `amount` | number | — | — |
| `currency` | string | — | Motif : `^[A-Z]{3}$`. |
| `occurred_at` | string · date-time | — | Motif : `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?Z$`. |
| `country` | string | — | Motif : `^[A-Z]{2}$`. |
| `mcc` | string | — | Motif : `^[0-9]{4}$`. |

## Réponses

| Statut | Description |
| --- | --- |
| `200` | Recalculé et réglé. |
| `400` | `invalid_request`, `invalid_json`, `identifier_required`, `invalid_idempotency_key`, `unsupported_canonicalization`. |
| `401` | `invalid_api_key`. Absent, mal formé, inconnu, révoqué — **toujours le même code**. Toute distinction serait un oracle. |
| `402` | `no_active_subscription`, `sandbox_quota_exhausted`. |
| `403` | `insufficient_scope`, `account_inactive`, `production_not_enabled`. |
| `404` | Enrichissement inconnu, ou appartenant à quelqu'un d'autre. |
| `409` | `idempotency_key_reuse` — même clé, charge utile différente. `transaction_id_conflict` — même `external_transaction_id`, données économiques différentes. `input_mismatch`, `refresh_not_available`. |
| `413` | `request_entity_too_large`. La limite du corps est de 16 KiB, comptée en **octets**. |
| `415` | `unsupported_media_type`. Envoyez `Content-Type: application/json`. |
| `429` | `rate_limited`. Rien n'a été calculé et rien n'a été facturé. |
| `500` | `internal_error`. Le corps ne dit rien de l'incident ; citez le `request_id` au support. Reprendre avec la même `Idempotency-Key` est sans risque. |
| `503` | `engine_error`, `busy` ou `pricing_not_activated`. **Rien n'a été facturé et rien n'a été mémorisé** : reprenez avec la même `Idempotency-Key`. |

### `200` — `Enrichment`

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `enrichment_id` | string | — | Exemple : `"enr_7f3c1e20-…"`. |
| `merchant` | Merchant \| null | — | — |
| `merchant.name` | string | — | Exemple : `"McDonald's"`. |
| `merchant.category` | string | — | Exemple : `"alimentation.restaurant"`. |
| `merchant.logo_url` | string · uri | — | — |
| `merchant.location` | object \| null | — | **Toujours présent**, `null` s'il est inconnu. Absent et inconnu se ressemblent trop pour qu'on demande à un client de les distinguer. |
| `merchant.location.city` | string | — | Exemple : `"PARIS"`. |
| `merchant.location.postal_code` | string | — | Exemple : `"75018"`. |
| `merchant.confidence` | number · 0–1 | — | Un **score de confiance du modèle** de 0 à 1. Il ne doit **pas** être interprété comme une probabilité calibrée de justesse — Noryo a mesuré que son ordonnancement n'est pas monotone au-dessus de 0.95. Voir le guide. |
| `enrichment` | object | — | — |
| `enrichment.status` | string | — | `resolved` — identité complète et au-dessus du seuil de politique. `partial` — quelque chose manque ou est sous le seuil. `not_found` — le moteur a répondu, et sa réponse est « personne ». Valeurs : `resolved`, `partial`, `not_found`, `refresh_recalculated`. |
| `enrichment.reason` | string | — | — |
| `enrichment.environment` | string | — | Valeurs : `sandbox`, `production`. |
| `enrichment.source` | string | — | — |
| `enrichment.customized` | boolean | — | `true` quand une **règle de votre organisation** (Platform → Règles) a changé cette réponse — par exemple un nom d’affichage ou une catégorie. Le résultat Noryo lui-même est conservé intact, et une règle ne s’applique jamais hors de votre organisation ni de l’environnement de la clé. `false` sinon. Un `POST` est rendu avec les règles publiées à cet instant, et un rejeu idempotent rend ce même corps ; un `GET` applique les règles publiées **maintenant**. |
| `enrichment.rules` | array<object> | — | **Facultatif** — présent seulement quand `customized` vaut `true` : les règles qui ont changé cette réponse, chacune avec la version appliquée. Le champ que chaque règle a changé se lit dans les journaux de Platform. |
| `enrichment.rules[].id` | string · uuid | — | — |
| `enrichment.rules[].version` | integer ≥ 1 | — | — |
| `usage` | object | — | Ce que **cet appel** a coûté. |
| `usage.billable` | boolean | — | — |
| `usage.units` | integer | — | — |
| `usage.deduplicated` | boolean | — | — |
| `usage.deduplicated_by` | string \| null | — | — |

## Erreurs nommées par le contrat

- [`identifier_required`](https://developer.noryo.app/fr-FR/errors/identifier_required)
- [`invalid_idempotency_key`](https://developer.noryo.app/fr-FR/errors/invalid_idempotency_key)
- [`invalid_json`](https://developer.noryo.app/fr-FR/errors/invalid_json)
- [`invalid_request`](https://developer.noryo.app/fr-FR/errors/invalid_request)
- [`unsupported_canonicalization`](https://developer.noryo.app/fr-FR/errors/unsupported_canonicalization)
- [`invalid_api_key`](https://developer.noryo.app/fr-FR/errors/invalid_api_key)
- [`no_active_subscription`](https://developer.noryo.app/fr-FR/errors/no_active_subscription)
- [`sandbox_quota_exhausted`](https://developer.noryo.app/fr-FR/errors/sandbox_quota_exhausted)
- [`account_inactive`](https://developer.noryo.app/fr-FR/errors/account_inactive)
- [`insufficient_scope`](https://developer.noryo.app/fr-FR/errors/insufficient_scope)
- [`production_not_enabled`](https://developer.noryo.app/fr-FR/errors/production_not_enabled)
- [`idempotency_key_reuse`](https://developer.noryo.app/fr-FR/errors/idempotency_key_reuse)
- [`input_mismatch`](https://developer.noryo.app/fr-FR/errors/input_mismatch)
- [`refresh_not_available`](https://developer.noryo.app/fr-FR/errors/refresh_not_available)
- [`transaction_id_conflict`](https://developer.noryo.app/fr-FR/errors/transaction_id_conflict)
- [`request_entity_too_large`](https://developer.noryo.app/fr-FR/errors/request_entity_too_large)
- [`unsupported_media_type`](https://developer.noryo.app/fr-FR/errors/unsupported_media_type)
- [`rate_limited`](https://developer.noryo.app/fr-FR/errors/rate_limited)
- [`internal_error`](https://developer.noryo.app/fr-FR/errors/internal_error)
- [`busy`](https://developer.noryo.app/fr-FR/errors/busy)
- [`engine_error`](https://developer.noryo.app/fr-FR/errors/engine_error)
- [`pricing_not_activated`](https://developer.noryo.app/fr-FR/errors/pricing_not_activated)

## Exemples de requête

cURL

```bash
# The contract publishes no example body for this operation: build it from the request schema.
IDEMPOTENCY_KEY=$(uuidgen)
curl -sS -g -X POST 'https://api.noryo.app/merchant/v1/enrichments/{enrichment_id}/refresh' \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
```

JavaScript

```js
// Reuse the same key when you retry this request.
const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.noryo.app/merchant/v1/enrichments/{enrichment_id}/refresh", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
  },
  // The contract publishes no example body for this operation: build it from the request schema.
});
console.log(response.status, await response.text());
```

Python

```python
import os
import uuid

import requests  # pip install requests

# Reuse the same key when you retry this request.
idempotency_key = str(uuid.uuid4())

response = requests.post(
    "https://api.noryo.app/merchant/v1/enrichments/{enrichment_id}/refresh",
    headers={
        "Authorization": "Bearer " + os.environ["NORYO_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    # The contract publishes no example body for this operation: build it from the request schema.
)
print(response.status_code, response.text)
```

Go

```go
package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	// Reuse the same key when you retry this request.
	idempotencyKey := newUUID()

	// The contract publishes no example body for this operation: build it from the request schema.
	req, err := http.NewRequest("POST", "https://api.noryo.app/merchant/v1/enrichments/{enrichment_id}/refresh", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NORYO_API_KEY"))
	req.Header.Set("Idempotency-Key", idempotencyKey)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.StatusCode, string(data))
}

// newUUID returns a random (version 4) UUID: the standard library has none.
func newUUID() string {
	b := make([]byte, 16)
	if _, err := rand.Read(b); err != nil {
		panic(err)
	}
	b[6] = b[6]&0x0f | 0x40
	b[8] = b[8]&0x3f | 0x80
	return fmt.Sprintf("%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:])
}
```

Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;

public class Main {
    public static void main(String[] args) throws Exception {
        // Reuse the same key when you retry this request.
        String idempotencyKey = UUID.randomUUID().toString();
        // The contract publishes no example body for this operation: build it from the request schema.
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.noryo.app/merchant/v1/enrichments/{enrichment_id}/refresh"))
            .method("POST", HttpRequest.BodyPublishers.noBody())
            .header("Authorization", "Bearer " + System.getenv("NORYO_API_KEY"))
            .header("Idempotency-Key", idempotencyKey)
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

C#

```csharp
using System;
using System.Net.Http;

// Reuse the same key when you retry this request.
var idempotencyKey = Guid.NewGuid().ToString();

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.noryo.app/merchant/v1/enrichments/{enrichment_id}/refresh");
request.Headers.TryAddWithoutValidation("Authorization", "Bearer " + Environment.GetEnvironmentVariable("NORYO_API_KEY"));
request.Headers.TryAddWithoutValidation("Idempotency-Key", idempotencyKey);
// The contract publishes no example body for this operation: build it from the request schema.

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

---

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