Conventions

Argent et volume - des chaînes

{
  "balance": "124.30",
  "currency": "USD"
}
{
  "purchased_gb": "25.000",
  "used_gb": "2.566",
  "left_gb": "22.434"
}

Analysez-les en decimal, pas en float. Devise - USD. Un gigaoctet = 10^9 octets.

Heure

ISO-8601 avec un décalage explicite, toujours en UTC : 2026-08-28T14:03:11+00:00.

Énumérations extensibles

Le statut de commande, le type de transaction, le type d’événement, le statut de forfait, kind et family s’enrichissent au sein de v1 sans préavis - une valeur inconnue doit être tolérée. Dans les filtres, une valeur inconnue est lue comme « sans filtre ».

Pagination

Paramètre	Signification
offset	combien de lignes ignorer ; 0 par défaut
limit	1..200, 50 par défaut (pour GET /api/v1/packages - 200)

Les deux sont ramenés dans leurs bornes plutôt que refusés, et renvoyés dans le corps déjà ajustés. La réponse porte total.

GET /api/v1/orders?limit=100&offset=100
    -> { "orders": [...], "total": 317, "offset": 100, "limit": 100 }

Sur les listes qui reçoivent des écritures, offset désigne une position : lors d’un export complet, dédoublonnez par id. L’ordre est fixe - les plus récents en premier.

Le journal des événements se lit autrement : ?after=<id>, la réponse porte next_after.

Idempotence

Les opérations qui débitent de l’argent exigent l’en-tête : POST /api/v1/packages (achat), POST /api/v1/packages/{id}/topup (ajout de trafic) et POST /api/v1/packages/{id}/prolong (prolongation d’adresses).

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Une chaîne de 255 caractères au maximum, les espaces en début et en fin sont supprimés.

Une nouvelle tentative avec la même clé et le même corps renvoie la même réponse. Générez la clé avant la requête et réutilisez-la lors d’une nouvelle tentative, y compris après un délai dépassé.

La clé est mémorisée 24 heures : la même clé un jour plus tard lance une nouvelle opération.

Erreurs :

• 422 - idempotency_key_required (en-tête absent), idempotency_key_invalid (vide ou plus long que 255), idempotency_key_reused (même clé avec un autre corps)
• 409 - idempotency_in_progress (la requête précédente est encore en cours - réessayez un peu plus tard avec la même clé)
• 500 - operation_indeterminate (nouvelle tentative avec la clé d’une opération dont l’issue est indéterminée - voir Erreurs)

Cache du catalogue géo

Les niveaux du catalogue géo renvoient un ETag - un hachage opaque de la version du catalogue. Envoyez-le dans If-None-Match - vous recevrez 304 sans corps. La même version sous forme lisible figure dans le corps, dans le champ version.

Versionnement

Publié dans v1 sans préavis : un nouveau champ dans une réponse, un nouveau paramètre facultatif, une nouvelle valeur d’une énumération extensible, un nouvel endpoint, un nouveau code d’erreur sur un statut existant.

Uniquement dans une nouvelle version : suppression ou renommage d’un champ, restriction d’un type, nouveau champ obligatoire dans une requête, changement du statut ou du code d’un cas décrit, changement d’une valeur par défaut.

Dépréciation : en-têtes Deprecation et Sunset, au moins 6 mois avant la désactivation.