Versions de l'API et changelog

La Merchant API de FlowAlp Pay est versionnée via le chemin de l'URL. Chaque requête déclare la version qu'elle attend : les intégrations existantes restent stables tandis que les nouveautés arrivent dans les versions plus récentes.

Fonctionnement du versionnement#

https://api.pay.flowalp.com/<version>/<Object>/<id>/?instance=<instance>

Le segment de version (par exemple v1.16) sélectionne le comportement de l'API pour cette seule requête. Il n'existe pas de bascule au niveau du compte : deux de vos systèmes peuvent appeler des versions différentes en même temps, ce qui facilite les migrations progressives. Les conventions générales d'URL sont décrites dans Format des requêtes.

Versions prises en charge#

Utilisez v1.16, sauf si vous maintenez une intégration plus ancienne qui n'a pas encore été retestée.

Épingler une version#

Les clients REST épinglent la version directement dans le chemin de l'URL :

curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=<instance>" \
  --header "x-api-key: <api-secret>"

Le client PHP reçoit la version — sans le v initial — comme cinquième argument du constructeur :

<?php
use FlowAlpPay\FlowAlpPay;

$client = new FlowAlpPay(
    getenv('FLOWALP_PAY_INSTANCE'),
    getenv('FLOWALP_PAY_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

Conseils de mise à niveau#

1. Lisez le changelog ci-dessous pour chaque version comprise entre votre version actuelle et la version cible.
2. Modifiez d'abord le segment de version (ou l'argument du constructeur du SDK) dans un environnement de staging.
3. Exécutez un test rapide des identifiants avec SignatureCheck, puis déroulez vos flux principaux de bout en bout : checkout, traitement des webhooks, capture et remboursement.
4. Comparez les champs de réponse que votre code analyse, en particulier là où le changelog mentionne des structures de réponse modifiées.
5. Déployez en production et surveillez les taux d'erreur ; au besoin, revenez en arrière en rétablissant l'ancien segment de version.

Un plan de test structuré est décrit dans Tests pour développeurs.

Changelog#

v1.16#

• Détails des versements : les tentatives de versement répétées ne sont plus regroupées en une seule entrée agrégée, qui exposait auparavant un objet transaction vide. La réponse de détail d'un versement résout désormais ces agrégats en leurs virements d'origine sous-jacents : vous voyez les transactions individuelles derrière un versement. Voir API Versements.

v1.15#

• Gestion des erreurs : les requêtes en échec renvoient un code de statut HTTP spécifique à l'erreur au lieu d'une réponse générique. Ce changement concerne tous les endpoints ; alignez votre gestion des erreurs sur Erreurs Merchant API.

v1.14#

v1.14 constitue la base de la plage actuellement prise en charge. Aucune entrée de changelog dédiée n'est publiée ; considérez-la comme le comportement de référence que v1.15 et v1.16 affinent.