Verifica del saldo tramite API prima di un lancio massivo di ordini

Perché richiedere il saldo prima di avviare una coda

Un lancio massivo di ordini senza una verifica aggiornata del saldo porta a rifiuti parziali: le prime richieste vengono create, mentre le successive ricevono un errore di fondi insufficienti. La situazione più difficile da gestire è quella con invio parallelo, servizi diversi e più processi che operano sullo stesso account.

Per il lancio non conta il volume complessivo delle ricariche né il saldo contabile nell'area personale. Serve la somma che il servizio consente di addebitare nel momento in cui viene creato un nuovo ordine. Il denaro destinato alle richieste attive può già trovarsi in riserva, anche se l'addebito definitivo non è ancora registrato nella cronologia delle operazioni.

Confrontate il budget della coda con il campo del saldo disponibile, non con la somma totale sul conto.

Come si presenta la risposta del metodo di saldo

I nomi dei campi sono definiti dalla documentazione della singola piattaforma, ma un contratto comodo del metodo di saldo di solito restituisce total, available, reserved, currency e updated_at. Di seguito è riportato un esempio di struttura da usare come riferimento in fase di integrazione. Non è una risposta universale per ogni servizio, ma un esempio di schema dati chiaro.

La richiesta può essere così:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

Risposta:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

In questo esempio total indica tutti i fondi dell'account, available il denaro per i nuovi ordini, reserved la somma destinata alle operazioni create in precedenza. Il controllo torna: 125.80 meno 41.30 è uguale a 84.50. Il campo currency definisce l'unità di calcolo, mentre updated_at aiuta a capire quanto sono recenti i dati.

Come interpretare available e reserved

Il campo available si usa per decidere se avviare. Se la coda costa 80.00 e available è 84.50, i fondi sono sufficienti solo a condizione che l'API non aggiunga una commissione separata o non ricalcoli il prezzo al momento della creazione della richiesta. Il campo reserved non va sommato al saldo disponibile: quella somma è già impegnata.

reserved può includere il costo di ordini con stato processing, pending o review — l'insieme esatto dipende dalle regole della piattaforma. A volte la riserva viene liberata dopo una cancellazione, un'esecuzione parziale o una verifica manuale. Per questo calcolarla autonomamente dall'elenco degli ordini è possibile solo come controllo aggiuntivo.

• total è adatto al confronto con la cronologia di ricariche e addebiti;
• available è adatto per ammettere una nuova coda al lancio;
• reserved mostra quanti fondi sono già bloccati per operazioni attive;
• currency non va ignorata nemmeno lavorando con un solo account;
• updated_at è utile per il registro e per diagnosticare una risposta obsoleta.

Una risposta con il solo campo balance è più semplice da gestire, ma ha un difetto: non permette di capire se quel denaro è subito disponibile o se una parte della somma è già trattenuta per altri ordini.

Verificate il formato degli importi nella documentazione API

Nell'esempio gli importi sono trasmessi come stringhe: "84.50", non come numero 84.5. Questo formato conserva il valore esatto restituito dal servizio. Se l'API usa stringhe con punto decimale, non conviene convertirle subito in numeri a virgola mobile ed eseguire confronti tramite float.

Ad esempio, il vostro calcolo potrebbe dare 84.499999 invece degli 84.50 attesi. Al limite del budget questo può far passare erroneamente una coda o, al contrario, bloccarla. Per le operazioni con valori decimali in forma di stringa usate un tipo di dato decimale che supporti la precisione della parte frazionaria fissa.

Un altro contratto diffuso è quello in unità minime intere. In tal caso la risposta può contenere "available_minor": 8450 e "currency": "USD", mentre il prezzo dell'ordine è "price_minor": 1250. All'interno di tale API 8450 significa 84.50, se le regole della valuta prevedono due posizioni decimali. Dividere il valore per 100 è possibile solo quando è indicato esplicitamente nella documentazione.

Non mescolate valute e formati di prezzo

Prima di calcolare la coda confrontate currency del saldo con la valuta del metodo dei prezzi o della risposta alla creazione dell'ordine. Se il saldo restituisce una valuta e il catalogo dei servizi un'altra, non si possono inserire le cifre direttamente. Serve un calcolo fornito dalla piattaforma stessa oppure un metodo di conversione separato e confermato.

La conversione preventiva dalla propria parte è comoda per la pianificazione, ma ha un difetto: il servizio può applicare un tasso diverso, una commissione o una regola di arrotondamento al momento dell'addebito. È più affidabile inviare l'ordine con parametri per i quali l'API restituisce il costo finale nella valuta del saldo, oppure ottenere il calcolo del prezzo immediatamente prima della creazione.

Se il metodo dei prezzi risponde "price": "12.345", mentre il saldo memorizza valori con due cifre, verificate la regola di arrotondamento. Non arrotondate automaticamente per difetto: l'addebito effettivo potrebbe risultare superiore. Per ammettere la coda usate proprio la somma che l'API indica come costo finale dell'ordine.

Calcolate il budget della coda prima della prima richiesta

Prima del lancio raccogliete tutte le richieste e calcolate il loro costo tenendo conto del volume, del servizio scelto, della regione, delle opzioni aggiuntive e della commissione, se viene trasmessa separatamente. Non confrontate available con il prezzo base dell'interfaccia: nell'API il totale può dipendere dai parametri del singolo ordine.

Supponiamo che nella coda ci siano tre ordini. L'API di calcolo del prezzo ha restituito per essi 18.40, 27.15 e 31.60 nella stessa valuta indicata in balance.currency. Il budget è pari a 77.15. Se balance.available è 84.50, dopo il lancio pianificato restano 7.35. Se available è 76.90, non si può avviare l'intera coda.

1. Ottenete i prezzi in base ai parametri effettivi di ciascun ordine.
2. Sommate i costi finali senza modificarne il formato e la valuta.
3. Confrontate il budget con available da una risposta aggiornata del saldo.
4. Se il saldo è sufficiente, fissate la somma come riserva locale del lancio.
5. Dopo la creazione di ogni richiesta riducete la riserva locale del costo confermato.

Un margine riduce il rischio di rifiuto in caso di addebito aggiuntivo, ma ha un difetto: una parte dei fondi disponibili resterà inutilizzata, anche se la coda avrebbe potuto passare per intero.

Eseguite un secondo controllo subito prima dell'invio

Il saldo ottenuto durante la preparazione della campagna perde rapidamente attualità. Nel tempo tra il calcolo e il lancio un altro operatore, un'automazione o un ordine attivo possono modificare available e reserved. Una nuova richiesta è necessaria dopo aver formato la coda e immediatamente prima della prima richiesta.

Lo schema operativo prevede due fasi: prima ottenere i prezzi e valutare il budget, poi richiedere di nuovo balance. Se il valore di available è diminuito ed è sceso sotto la somma calcolata, la coda non viene inviata per intero. Tra il controllo finale e il lancio non conviene eseguire altri addebiti dallo stesso account.

Una sola richiesta per l'intero lancio riduce il carico sull'API, ma il suo difetto è che il saldo disponibile può cambiare mentre una coda lunga è ancora in elaborazione.

Come avviare la coda in caso di fondi insufficienti

Se available è inferiore al budget, non inviate tutte le richieste sperando che una parte passi. Suddividete la coda in pacchetti il cui costo rientri nel limite disponibile. Nell'esempio con saldo 76.90 si possono inviare i primi due ordini per 45.55, poi fermarsi: il terzo da 31.60 richiede una nuova verifica.

Definite esplicitamente l'ordine delle richieste durante il batching. Potete inviare prima gli ordini prioritari oppure formare pacchetti di costo simile. Ogni variante ha un difetto: l'ordine per priorità rinvia le posizioni meno importanti, mentre l'ordinamento per prezzo può alterare il piano originale della campagna.

• Formate un pacchetto con una somma non superiore all'available corrente.
• Create gli ordini del pacchetto e salvate i loro identificatori.
• Attendete le risposte o verificate gli stati delle operazioni dopo i timeout.
• Fate una pausa se lo richiedono i limiti dell'API o le regole del servizio.
• Richiedete di nuovo balance prima del pacchetto successivo.

Dopo ogni pacchetto basatevi sulla nuova risposta dell'API, non solo sulla detrazione locale dal saldo precedente. Il calcolo locale è utile per il controllo, ma non vede i rimborsi, gli addebiti esterni e il ricalcolo delle riserve.

Proteggete il budget durante l'invio parallelo

Con l'elaborazione sequenziale è sufficiente ridurre il limite locale dopo la conferma dell'ordine. Nel modello parallelo due worker possono vedere contemporaneamente available 84.50 e pianificare ciascuno una spesa di 60.00. Entrambe le decisioni sembrano ammissibili singolarmente, ma insieme superano il saldo disponibile.

Per la protezione serve un contatore condiviso della riserva locale o una coda a cui si accede in modo atomico. Prima dell'invio il worker tenta di impegnare la somma dell'ordine in questo contatore. Se il limite libero non basta, la richiesta resta in attesa di una nuova verifica del saldo.

• La coda sequenziale è più semplice da controllare, ma si avvia più lentamente.
• L'invio parallelo riduce i tempi di lancio, ma richiede il blocco del budget condiviso.
• La prenotazione locale riduce i conflitti, ma può bloccarsi dopo un guasto di un worker.
• La prenotazione lato API è più affidabile, ma non è disponibile su ogni piattaforma.

Se il processo si è concluso prima di ricevere la risposta, la riserva locale non va considerata subito spesa o libera. Verificate prima se l'ordine è stato creato, tramite il suo identificatore esterno o con un metodo di ricerca delle operazioni.

Usate la riserva API, se prevista

Alcune API permettono di creare una riserva per un insieme di operazioni o di eseguire un ordine in due passaggi: calcolo, blocco della somma, conferma. In questo schema l'intervallo tra verifica e addebito è più ridotto, e un altro processo ha meno possibilità di consumare i fondi dell'account.

Se tale metodo è disponibile, salvate l'identificatore della riserva, la sua somma, la valuta, la scadenza e lo stato. Poi trasmettete questo identificatore alla creazione degli ordini, se il contratto dell'API lo richiede. Al termine della coda verificate la parte non utilizzata e l'effettivo rilascio del blocco.

La riserva API non risolve tutti i problemi: può avere una scadenza breve, non coprire le commissioni o essere liberata dopo un errore di conferma. La riserva locale è più semplice da implementare, ma il suo difetto è che non protegge dalle spese generate al di fuori della vostra applicazione.

Distinguete l'errore del saldo dal saldo pari a zero

Una risposta con codice di errore, un timeout o un limite di frequenza delle richieste non significano che available sia pari a zero. Non inserite automaticamente l'ultimo valore noto se da esso dipende un lancio importante. Se non è possibile ottenere un saldo aggiornato, la coda va messa in pausa.

Gestite separatamente il rifiuto alla creazione dell'ordine. Può essere legato a fondi insufficienti, ma anche a un identificatore di servizio errato, a un volume non ammesso, a una limitazione sul canale o alla ripetizione di una stessa operazione. Salvate il codice e il testo dell'errore insieme all'identificatore esterno della richiesta.

• In caso di errore di autorizzazione aggiornate l'accesso e solo dopo ripetete la richiesta.
• In caso di limite di richieste rispettate una pausa secondo le regole dell'API.
• In caso di timeout alla creazione verificate prima se l'operazione è effettivamente comparsa.
• In caso di errore di fondi insufficienti fermate il pacchetto e richiedete di nuovo balance.

Non create duplicati dopo un timeout

Un timeout significa che il vostro client non ha ricevuto la risposta, non che il server non abbia elaborato la richiesta. Un nuovo invio senza verifica può creare un secondo ordine e impegnare di nuovo il denaro. È particolarmente pericoloso in una coda in cui il nuovo tentativo automatico è impostato su più prove.

Trasmettete un identificatore esterno univoco dell'ordine se l'API supporta il campo client_order_id, external_id o idempotency_key. Salvatelo prima di inviare la richiesta. Dopo un timeout cercate l'operazione tramite questo valore oppure richiedete lo stato tramite l'identificatore ottenuto in precedenza.

La ripetizione senza verifica è più rapida, ma il suo difetto è diretto: possibili duplicati di ordini, doppia prenotazione e discrepanze tra il vostro calcolo del budget e gli addebiti effettivi.

Cosa salvare nel registro del lancio

Il registro aiuta a ricostruire lo svolgimento di un'operazione massiva e a spiegare perché un determinato pacchetto si è fermato. Per ogni lancio salvate l'ora dei due controlli, total, available, reserved, currency, il budget calcolato, la dimensione della riserva locale e l'elenco degli identificatori esterni delle richieste.

Per ogni tentativo di creazione registrate il costo, il codice di risposta, l'identificatore tecnico dell'operazione e lo stato finale. I segreti non entrano nel registro: token di autorizzazione, chiavi API, intestazioni complete delle richieste e dati personali vanno mascherati o esclusi prima della scrittura.

Il logging completo è comodo in fase di debug, ma ha un difetto: senza filtri nell'archivio possono finire dati di accesso e informazioni sui clienti.

Verificate lo schema su una coda ridotta

Prima di un lancio importante eseguite uno scenario breve: ottenete balance, richiedete i prezzi finali, create un pacchetto limitato, richiedete di nuovo balance e confrontate la variazione attesa di available e reserved con la risposta effettiva. Così potete notare quando il servizio prenota la somma e quando la addebita definitivamente.

Il pacchetto di test non garantisce lo stesso comportamento sotto carico elevato: possono intervenire limiti, processi paralleli o restrizioni del singolo servizio. Per questo in una coda massiva continuate a suddividere il lancio in pacchetti, a verificare il saldo disponibile tra un pacchetto e l'altro e ad analizzare ogni rifiuto separatamente.