Gestione dello stato "in esecuzione" durante la verifica dell'ordine tramite API

Cosa significa processing nella risposta API

Lo stato processing, in_progress o un altro stato equivalente indica che il fornitore ha preso in carico l'ordine, ma non ha registrato l'esito. Per i servizi di promozione può trattarsi della verifica del link, dell'attesa in coda, dell'avvio dell'attività o dell'erogazione graduale del volume ordinato.

Processing non conferma l'esecuzione riuscita e non significa errore. Dopo di esso l'ordine può passare a completed, partial, canceled o failed. Finché il fornitore restituisce uno stato intermedio, non create una nuova richiesta per lo stesso link e lo stesso volume.

HTTP 200 con stato processing significa risposta API riuscita, non completamento riuscito dell'ordine. Questi eventi vanno archiviati e gestiti separatamente.

Quali dati servono per verificare l'ordine

Per il polling serve l'ID esterno dell'ordine restituito dal fornitore alla creazione. Salvatelo insieme all'ID interno, al volume iniziale, ai parametri del servizio, al link, all'ora di creazione e alla risposta API originale. Cercare l'ordine per nome del canale, link o volume non è affidabile: tali valori possono coincidere per più richieste.

Se dopo la creazione arriva un timeout, non inviate nuovamente la richiesta in modo automatico. Il fornitore potrebbe aver accettato la richiesta e la risposta potrebbe essersi persa lungo il percorso. Usate prima il metodo di ricerca dell'ordine, se presente nella documentazione, oppure sottoponete il caso a verifica.

Il limite di memorizzare solo lo stato corrente è che in caso di contestazione non è possibile ricostruire quando l'ordine è passato a processing, se ci sono stati progressi e quali risposte erano arrivate prima.

Esempio di richiesta di stato tramite curl

L'indirizzo esatto, il metodo di autorizzazione e i nomi dei campi vanno presi dalla documentazione del fornitore. Di seguito è mostrato un modello: i valori tra parentesi angolari vanno sostituiti con i dati dell'API specifica.

Richiesta GET per un singolo ordine

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Esempio di risposta:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

I campi completed_quantity e remains sono riportati solo come esempio di struttura. Il fornitore può usare progress, start_count, balance o altri nomi. Il limite dell'approccio GET è che parte delle API accetta la verifica dello stato solo tramite POST.

Esempio di richiesta POST e verifica in batch

Richiesta POST dello stato di un singolo ordine

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

Non passate la chiave API nella stringa URL. Gli indirizzi delle richieste finiscono nei log dei proxy, nei sistemi di analisi, nella cronologia del browser e nei log tecnici. Il limite del POST è che è più difficile verificarlo manualmente tramite la barra degli indirizzi, ma non è un motivo per spostare il segreto nell'URL.

Richiesta in batch degli ordini attivi

Se l'API supporta la verifica in batch, inviate più ID con una sola richiesta:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Abbinate la risposta all'ordine interno tramite l'ID esterno, non tramite la posizione dell'elemento nell'array. Limite della verifica in batch: il fornitore può non restituire tutti gli ordini, limitare la dimensione della lista o segnalare un errore solo per un ID.

Come impostare il polling per processing

Dopo la prima risposta processing mettete la verifica successiva in coda. Scegliete l'intervallo in base alla documentazione API, ai limiti di frequenza e alla natura del servizio. Per le attività in cui lo stato cambia rapidamente è ammessa una verifica più frequente all'inizio. Per la promozione graduale le richieste brevi e costanti di solito non forniscono nuove informazioni.

Uno schema pratico è aumentare la pausa dopo risposte processing identiche. La prima verifica avviene dopo un ritardo iniziale, poi l'intervallo cresce fino a un massimo stabilito. Se l'API restituisce il progresso o un nuovo orario di aggiornamento, il conteggio può partire da questa modifica.

• Dopo la creazione dell'ordine non verificate lo stato immediatamente molte volte di seguito: il servizio può aver bisogno di tempo per mettere in coda.
• In caso di processing ripetuto aumentate l'intervallo tra le richieste, invece di mantenere una frequenza costante.
• Aggiungete una piccola variazione casuale all'orario di avvio delle attività, così gli ordini non interrogano l'API contemporaneamente.
• Se il fornitore trasmette Retry-After o una raccomandazione analoga, usatela come prioritaria.
• Per gli ordini con webhook mantenete un polling di controllo: la notifica potrebbe non arrivare.

Il limite del polling raro è che l'interfaccia può mostrare uno stato vecchio dopo il completamento effettivo. Il limite del polling troppo frequente è il rischio di incappare nei limiti API, ricevere 429 e creare un carico superfluo.

Quali tempi memorizzare per il controllo di processing

Per distinguere l'esecuzione normale da un blocco non basta un solo stato corrente. Per ogni ordine attivo memorizzate l'ora di creazione, la prima ricezione di processing, l'ultima risposta API riuscita, l'ultima modifica dello stato esterno e l'ultima modifica del progresso.

È inoltre utile salvare il volume iniziale, il volume confermato come eseguito, il residuo e lo stato originale del fornitore. Se l'API non restituisce il progresso, non è un motivo per considerare l'ordine bloccato: basatevi sull'ora dell'ultima risposta e sul periodo di elaborazione previsto, se indicato nelle condizioni del servizio.

Il tempo massimo di attesa non può essere impostato con un unico numero per tutti i servizi. Usate il termine che il fornitore indica per il servizio specifico, con un margine interno per la coda e l'aggiornamento dei dati. Se il termine non è indicato, impostate una regola separata per ogni categoria di servizi e rivedetela in base alla cronologia dell'elaborazione effettiva.

Cosa fare se processing non cambia

Un processing prolungato non dimostra un errore. Prima verificate se sono arrivate risposte API riuscite, se completed_quantity o remains sono cambiati, se ci sono stati webhook e se sono cambiate le regole del servizio. L'assenza di una crescita visibile può dipendere dal ritardo delle statistiche della piattaforma o dal fatto che il fornitore aggiorna il progresso solo alla fine.

Quando il termine interno di attesa è superato, non annullate l'ordine automaticamente. Eseguite una verifica straordinaria dello stato, richiedete i dati con un metodo separato, se previsto, e controllate la cronologia delle notifiche. Se il fornitore conferma ancora processing, portate l'ordine in uno stato interno "richiede verifica", ma conservate lo stato esterno senza sostituirlo.

• Registrate l'ora dell'ultima risposta confermata e l'intera risposta API.
• Verificate se il progresso è cambiato rispetto al polling precedente.
• Riducete la frequenza delle richieste automatiche dopo aver raggiunto la soglia interna.
• Trasmettete al supporto l'ID esterno, il link, i parametri del servizio, la cronologia degli stati e gli errori tecnici.
• Non riavviate il residuo prima della risposta del fornitore o di uno stato finale esplicito.

Il limite della verifica manuale è che l'ordine richiede l'attenzione del supporto. Ma l'annullamento automatico o il duplicato sono più pericolosi: l'esecuzione può proseguire presso il fornitore.

Come distinguere un errore di richiesta dallo stato dell'ordine

Un errore di rete, un timeout, un HTTP 429 e una risposta 5xx non comunicano lo stato dell'ordine stesso. Indicano solo che non è stato possibile ottenere un nuovo stato attendibile. In questa situazione mantenete l'ultimo stato confermato, registrate l'errore tecnico e pianificate una nuova verifica.

In caso di 429 tenete conto di Retry-After, se l'header è trasmesso. In caso di errori di rete temporanei e 5xx aumentate la pausa tra i tentativi. In caso di errore di autorizzazione, firma o diritti di accesso non impostate retry frequenti: occorre verificare la chiave, la scadenza del token, le restrizioni IP e le impostazioni di accesso.

Se l'API ha restituito HTTP 200, ma il JSON non viene analizzato o nella risposta mancano order_id e status, salvate il corpo della risposta per intero e contrassegnate la verifica come non valida. Non sostituite l'assenza di stato con completed, canceled o processing.

Quando interrompere le richieste automatiche ripetute

Il polling non deve essere infinito. Limitate il numero di tentativi tecnici per gli errori temporanei e controllate separatamente il termine complessivo di permanenza dell'ordine in processing. Dopo aver esaurito il limite di retry portate l'attività di verifica nella coda di analisi, invece di creare nuove richieste ogni minuto senza risultato.

La ripetizione della richiesta di stato è di solito sicura se il metodo legge solo i dati. I metodi di creazione, annullamento, ricarica, riavvio e rimborso non possono essere ripetuti meccanicamente dopo un timeout. Senza una chiave idempotente o un'esplicita conferma del fornitore, tale ripetizione può modificare l'ordine due volte.

Il limite della limitazione dei retry è che parte degli aggiornamenti diventa un'attività manuale. I retry infiniti sono peggiori: mascherano il guasto, consumano i limiti e complicano l'analisi dei log.

Come accettare lo stato finale dopo processing

Evitate il passaggio all'indietro da completed a processing a causa di una risposta di polling tardiva o di un webhook vecchio. A ogni aggiornamento confrontate l'ora dell'evento del fornitore, il numero di versione sequenziale, se presente, e lo stato interno corrente.

• new e pending possono passare a processing, canceled o failed.
• processing può passare a completed, partial, canceled o failed.
• partial non va considerato automaticamente come completed.
• completed, canceled e failed sono di solito considerati finali e bloccano il ritorno automatico all'indietro.
• Uno stato sconosciuto o una transizione non ammessa richiedono una verifica separata.

Anche una tabella rigida delle transizioni ha un limite: il fornitore può aggiungere un nuovo stato corretto. Per questo conservate lo stato originale e non sovrascrivetelo con la classificazione interna.

Come gestire partial e il residuo dell'ordine

Partial significa che è stata confermata solo una parte del volume iniziale. Nella risposta API possono esserci la quantità effettivamente eseguita, il residuo, la causa e i dati sul rimborso. Memorizzate questi valori separatamente: il volume iniziale dell'ordine non va sostituito con la quantità eseguita.

Un esempio di risposta finale può essere così:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

Prima determinate cosa conferma esattamente l'API: il rimborso è già stato effettuato, il rimborso è solo pianificato, il residuo è annullato o è necessario rivolgersi al supporto. Se non c'è un campo sul rimborso, non considerate il residuo compensato automaticamente.

Non riavviate la parte non eseguita senza una decisione separata. Il fornitore può ancora completare il calcolo, le statistiche della piattaforma possono aggiornarsi con ritardo e una nuova richiesta può creare una promozione duplicata. Il limite dell'attesa della conferma è che il residuo non sarà chiuso all'istante, ma non comparirà un ordine in più.

I webhook non sostituiscono la verifica di controllo

Il webhook permette di aggiornare la scheda dell'ordine subito dopo l'evento, senza attendere il polling successivo. Nel gestore trovate l'ordine tramite l'ID esterno, verificate la firma o il segreto, salvate l'ID dell'evento e applicate la transizione solo dopo aver verificato l'ammissibilità.

La consegna ripetuta del webhook deve essere sicura: lo stesso evento non va considerato una nuova modifica. Gli eventi possono anche arrivare fuori ordine, quindi non riportate un ordine finale all'indietro solo in base a un processing tardivo.

Il polling di controllo serve anche con webhook stabili. Il limite dei webhook è la configurazione più complessa: servono un gestore accessibile, la protezione da richieste false, la deduplicazione e un registro degli eventi.

Cosa mostrare al cliente durante processing e blocco

Nell'interfaccia non serve mostrare l'intero JSON tecnico. Per processing è sufficiente lo stato "ordine in lavorazione". Se l'API ha trasmesso un progresso attendibile, mostrate il volume confermato separatamente da quello iniziale e non spacciatelo per il risultato definitivo.

Per un ordine che ha superato il termine interno di controllo, usate uno stato comprensibile come "stiamo verificando l'esecuzione". Non comunicate annullamento, rimborso o completamento totale finché non è confermato dalla risposta del fornitore.

Le notifiche sono utili all'accettazione dell'ordine, al completamento finale, in caso di partial, annullamento, errore e necessità di verifica. I messaggi dopo ogni polling creano rumore e non aiutano il cliente a capire lo stato reale della richiesta.

Quali voci servono nel registro di elaborazione

La cronologia delle risposte aiuta ad analizzare un processing bloccato, un webhook perso, una contestazione sull'esecuzione parziale e una discrepanza tra interfaccia e API. Per ogni chiamata salvate l'ID esterno, la fonte dell'aggiornamento, l'ora della richiesta e della risposta, il codice HTTP, lo stato originale, lo stato normalizzato, il progresso, il residuo e il testo dell'errore tecnico.

Non scrivete nei log ordinari chiavi API, token, firme e altri segreti. Limitate l'accesso alle risposte grezze: possono contenere dati che non devono comparire nell'interfaccia del supporto.

Prima del lancio verificate gli scenari con processing ripetuto, assenza di progresso, timeout, 429, errore 5xx, JSON non valido, webhook tardivo, webhook duplicato, partial, canceled e stato sconosciuto. La modalità di test è utile per la struttura dell'integrazione, ma il suo limite è che può non riprodurre le code reali e i ritardi dell'API di produzione.