Versions de l'API et dépréciations

La version est dans le chemin : tous les endpoints publics sont sous /v1 (https://api.xaalis.org/v1/…, mode test sur https://sandbox-api.xaalis.org/v1/…). v1 est la seule version aujourd’hui. Le contrat est le document OpenAPI que l’API publie sur https://api.xaalis.org/openapi.json.

Changements possibles à l’intérieur de v1

Ils sont rétrocompatibles et arrivent sans nouvelle version ni préavis. Votre intégration doit les supporter :

• De nouveaux endpoints, et de nouveaux paramètres ou en-têtes de requête optionnels.
• De nouveaux champs dans les objets de réponse et les webhooks — ignorez les champs que vous ne connaissez pas.
• De nouveaux types d’événements webhook — ignorez ceux que vous ne traitez pas et répondez quand même 2xx.
• De nouvelles valeurs dans les énumérations (un nouveau status de paiement, un nouveau provider, un nouveau code d’erreur) — traitez une valeur inconnue comme « non gérée », jamais comme une erreur qui arrête le traitement.
• De nouveaux codes d’erreur, des messages plus longs, un ordre de champs différent, des identifiants d’une autre longueur (le préfixe reste : pay_, po_, …).

Changements qui exigent une nouvelle version

Supprimer ou renommer un endpoint, un champ ou une valeur d’énumération ; rendre obligatoire un paramètre optionnel ; changer le type ou le sens d’un champ ; changer la façon d’exprimer les montants (ils restent des entiers en F CFA). Ces changements n’arrivent que dans une /v2, à côté de v1, jamais en modifiant v1.

Comment une dépréciation est annoncée

Quand un élément de v1 est déprécié :

1. C’est annoncé sur cette page et par e-mail à chaque propriétaire de compte, avec la date d’arrêt.
2. Les réponses de l’endpoint déprécié portent l’en-tête standard Deprecation (RFC 9745) et un en-tête Sunset avec la date de fin (RFC 8594), plus un Link vers le remplaçant.
3. Il continue de fonctionner au moins 12 mois après l’annonce.

Rien n’est déprécié aujourd’hui.

SDK et extensions

Les SDK Node, Python et PHP et l’extension WooCommerce suivent le versionnage sémantique : un changement incompatible dans l’interface d’un SDK donne une nouvelle version majeure, même si l’API ne change pas. Voir Téléchargements pour les versions actuelles.