> ## Documentation Index
> Fetch the complete documentation index at: https://docs.umeme.app/llms.txt
> Use this file to discover all available pages before exploring further.

# À savoir

> Six règles valent pour toute l'API. Les connaître évite l'essentiel des erreurs d'intégration.

## Une API asynchrone

Une vente se soumet, puis s'achève plus tard. La réponse à `POST /v1/ventes` dit seulement si la vente est prise ; son issue arrive par le rappel, ou par `GET /v1/ventes/{uuid}`.

## L'uuid, votre filet de sécurité

* Générez un UUID v4 pour chaque vente, et **enregistrez-le avant l'appel**.
* En cas de doute (délai dépassé, erreur `5xx`), renvoyez la même vente avec le même `uuid` : `DOUBLON_IGNORE` dit qu'elle était arrivée.
* Le même `uuid` pour une autre vente reçoit `409 UUID_REUTILISE`.
* Seul `NON_TROUVEE`, à la consultation, prouve qu'une vente n'existe pas.

> [!WARNING]
>
> Un délai dépassé ou une erreur `5xx` n'est jamais un échec : la vente a peut-être été prise. Renvoyez-la avec le même `uuid`, ou consultez-la.

## Les rappels

Quand une vente atteint son statut final, Umeme envoie un `POST` en HTTPS à votre URL de rappel. Répondez `200` ; sinon, Umeme réessaie huit fois en 25 minutes :

**0:00**1ʳᵉ**1:00**2ᵉ**2:00**3ᵉ**5:00**4ᵉ**10:00**5ᵉ**15:00**6ᵉ**20:00**7ᵉ**25:00**8ᵉ

Chaque tentative attend `10 s` la connexion et `30 s` la réponse. Ensuite, le rappel se renvoie à la demande pendant 90 jours. Chaque rappel porte un identifiant d'événement, le même à chaque tentative : il vous sert à écarter les doublons.

Chaque rappel est signé par la clé privée d'Umeme, selon la RFC 9421. Vous le vérifiez avec la clé publique que sert `GET /v1/cle-publique` : voir [Recevoir et vérifier les rappels](https://docs.umeme.app/guides/rappels.md).

> [!NOTE]
>
> Umeme ne promet aucune adresse IP de départ pour les rappels : la signature est votre seule garantie d'origine.

## Montants et heures

Les montants sont en dollars US, en nombre décimal, deux décimales au plus : `5`, `12.5`. Les heures sont en UTC, au format ISO 8601 : `2026-11-07T08:26:44Z`.

## Codes et messages

Chaque refus et chaque échec porte un code stable et un message en français. Comparez les codes, jamais les messages : un message se corrige, un code ne se renomme jamais. Voir [Codes d'erreur](https://docs.umeme.app/ressources/codes-erreur.md).

## Ce qui peut changer

Umeme peut ajouter des champs, des codes ou des routes : ignorez ce que vous ne connaissez pas. Rien n'est retiré ni renommé sans une nouvelle version, annoncée au [Journal des changements](https://docs.umeme.app/ressources/journal.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.