Conventions

Format des requêtes

Corps et réponses en JSON (Content-Type: application/json).
Les identifiants (productId, invoiceId, id) sont des UUID.
Les objets sont stricts : tout champ inconnu dans le corps ou la query est rejeté avec 400 INVALID_REQUEST.

Montants

Les montants sont des entiers exprimés dans la plus petite unité de la devise :

{ "value": 2500, "currency": "EUR" }

Champ	Type	Règle
`value`	entier	En centimes (EUR) ou en francs (XPF). Minimum effectif `1`.
`currency`	chaîne	`EUR` ou `XPF`.

Le montant doit en outre respecter les bornes configurées sur le produit (AMOUNT_BELOW_MINIMUM / AMOUNT_ABOVE_MAXIMUM).

Frais de service

Les frais de service sont calculés et appliqués par Nirio lors du paiement. Ils ne sont pas exposés dans les réponses de l'API.

Dates

Horodatages au format ISO 8601 avec décalage horaire : 2025-03-01T10:15:00.000Z ou 2025-03-01T11:15:00+01:00. Une date sans décalage est rejetée.
Dates de naissance au format YYYY-MM-DD.

Format des erreurs

Toutes les erreurs émises par le backend partagent la même enveloppe :

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "The product does not exist or is not owned by the partner."
  }
}

Le code est stable et doit être utilisé pour le traitement programmatique ; le message est indicatif (en anglais) et peut évoluer. Voir le catalogue des erreurs.

Erreurs communes à tous les endpoints

Statut	Code	Cause
`400`	`INVALID_REQUEST`	Corps, paramètre de chemin ou query invalide (type, format, champ inconnu…).
`401`	`MISSING_PARTNER_ID`	Identifiant partenaire absent ou invalide (voir Authentification).
`401`	—	Jeton absent ou invalide, rejeté par la gateway avec son propre format.

Idempotence

La création de facture est idempotente sur partnerInvoiceReference, clé unique pour l'ensemble du partenaire (tous produits confondus) :

même référence et même contenu → 200 OK avec la facture existante ;
même référence et contenu différent → 409 REFERENCE_ALREADY_EXISTS.

En cas d'erreur réseau ou de timeout, rejouez la requête à l'identique : vous ne créerez pas de doublon. Voir Créer une facture.

Pagination

La liste des factures est paginée par curseur opaque (nextCursor). Voir Lister les factures.