Versioni API e changelog

La Merchant API di FlowAlp Pay è versionata tramite il path dell'URL. Ogni richiesta dichiara la versione che si aspetta: le integrazioni esistenti restano stabili mentre le novità arrivano nelle versioni più recenti.

Come funziona il versionamento#

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

Il segmento di versione (ad esempio v1.16) seleziona il comportamento dell'API per quella singola richiesta. Non esiste uno switch a livello di account: due dei tuoi sistemi possono chiamare versioni diverse nello stesso momento, il che rende semplici le migrazioni graduali. Le convenzioni generali degli URL sono descritte in Formato delle request.

Versioni supportate#

Usa v1.16, a meno che tu non mantenga un'integrazione più vecchia non ancora ritestata.

Fissare una versione#

I client REST fissano la versione direttamente nel path dell'URL:

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

Il client PHP riceve la versione — senza la v iniziale — come quinto argomento del costruttore:

<?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'
);

Indicazioni per l'upgrade#

1. Leggi il changelog qui sotto per ogni versione compresa tra quella attuale e quella di destinazione.
2. Aggiorna il segmento di versione (o l'argomento del costruttore dell'SDK) prima in un ambiente di staging.
3. Esegui uno smoke test delle credenziali con SignatureCheck, poi verifica i flussi principali end to end: checkout, elaborazione dei webhook, capture e refund.
4. Confronta i campi di risposta che il tuo codice interpreta, soprattutto dove il changelog segnala strutture di risposta modificate.
5. Rilascia in produzione e monitora il tasso di errori; se necessario puoi tornare indietro ripristinando il segmento di versione precedente.

Un piano di test strutturato è descritto in Testing per sviluppatori.

Changelog#

v1.16#

• Dettaglio dei payout: i tentativi di payout ripetuti non vengono più compressi in un'unica voce aggregata, che in precedenza esponeva un oggetto transaction vuoto. La risposta di dettaglio del payout ora risolve questi aggregati nei trasferimenti originali sottostanti, quindi vedi le singole transazioni dietro un payout. Vedi API Payout.

v1.15#

• Gestione degli errori: le richieste fallite restituiscono uno status HTTP specifico per il tipo di errore invece di una risposta generica. La modifica riguarda tutti gli endpoint; allinea la tua gestione degli errori con Errori della Merchant API.

v1.14#

v1.14 è la base dell'intervallo attualmente supportato. Non sono pubblicate voci di changelog dedicate; consideralo il comportamento di riferimento che v1.15 e v1.16 perfezionano.