Gestion des versions
Versions datées, ce qui a changé, et comment passer à une nouvelle version.
L'API Wajub est versionnée par date. Votre compte est fixé sur la version en vigueur au moment de sa création, et un changement cassant sort sous une nouvelle date sans toucher à votre intégration. La version actuelle est la 2026-09-01.
Versions prises en charge
| Version | Statut | Ce qu'elle a changé |
|---|---|---|
2026-09-01 | Actuelle | ledger_balance_before et ledger_balance_after retirés de l'objet transfert. |
2026-08-01 | Prise en charge | complete remplace is_complete sur l'objet transfert. |
2025-01-01 | Prise en charge | La version d'origine. |
Une version reste prise en charge au moins six mois après avoir été remplacée, et son retrait est annoncé avant d'avoir lieu.
Choisir une version
Trois sources sont consultées, dans cet ordre : l'en-tête X-Wajub-Version de la requête, la
version fixée sur votre compte, puis la valeur par défaut de la plateforme.
Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i...
X-Wajub-Version: 2026-08-01L'en-tête n'est pris en compte que s'il correspond à YYYY-MM-DD. Toute autre valeur, un v2, un
latest, une chaîne vide, est ignorée en silence et c'est la version de votre compte qui
s'applique. Une date bien formée qui ne figure pas dans la liste des versions prises en charge
provoque une erreur franche :
Chaque réponse indique la version qui a répondu
X-Wajub-Version revient dans chaque réponse, y compris les erreurs et le 400 ci-dessus.
Enregistrez-le dans vos logs : c'est le moyen le plus rapide de découvrir qu'un service oublié est
encore fixé sur une ancienne date.
curl -i https://api.wajub.com/transfers/trf_01JXXXXXXXXXXXXX \
-H "Authorization: $WAJUB_API_KEY" \
-H "X-Wajub-Version: 2026-08-01"La conversion se fait dans les deux sens
Fixer une ancienne version ne se contente pas de désactiver les nouveaux champs. Wajub met à niveau
le corps de votre requête vers la forme actuelle avant que le contrôleur ne le voie, puis ramène la
réponse à la forme qu'attend votre version. Un client en 2025-01-01 peut envoyer is_complete et
lira is_complete, alors que le code derrière ne manipule jamais que complete.
C'est pourquoi un transfert lu en 2026-08-01 porte encore ledger_balance_before et
ledger_balance_after : ces champs ont été retirés en 2026-09-01, et la réponse est remise dans
l'ancienne forme à la sortie.
Ce qui compte comme un changement cassant
Cassant, sort sous une nouvelle datecassantfacultatifAdditif, sort immédiatementadditiffacultatifLisez les réponses avec tolérance
Les changements additifs arrivent sur toutes les versions, y compris la vôtre, sans préavis.
Ignorez les champs que vous ne connaissez pas, et ne laissez jamais une valeur d'enum inconnue
lever une exception. Un match sans branche par défaut est la cause la plus fréquente d'une
intégration qui casse lors d'une version non cassante.
Passer à une nouvelle version
- 1
Lisez ce qui a changé
Le changelog détaille les différences de chaque date, champ par champ.
- 2
Testez avec l'en-tête
Envoyez
X-Wajub-Versionavec la nouvelle date en utilisant une clé sandbox. Rien ne change sur votre compte : vous pouvez faire tourner ce test en parallèle de votre intégration actuelle aussi longtemps que nécessaire. - 3
Déployez service par service
Gardez l'en-tête pendant le déploiement, un service à la fois. Un service que vous n'avez pas migré continue de répondre sur l'ancienne date.
- 4
Fixez le compte, retirez l'en-tête
Une fois que tout tourne sur la nouvelle date, demandez au support de changer la version fixée sur votre compte, puis retirez l'en-tête. Konsole → Overview indique sur quelle version votre compte est fixé et laquelle est actuelle, pour que vous puissiez confirmer que le changement a bien été appliqué.