Come configurare le notifiche di completamento degli ordini API

Quali eventi considerare come completamento dell'ordine

Per prima cosa stabilite quale stato nell'API indica il completamento effettivo dell'ordine. Presso fornitori diversi può trattarsi di ordine eseguito, consegnato, annullato, rifiutato, restituito o parzialmente eseguito. Non legate l'automazione solo alla parola "successo": l'ordine può attraversare diversi stati intermedi e poi fermarsi a causa di un limite, di una verifica o di un annullamento.

Non bisogna gestire solo l'esito positivo. Se il servizio invia una notifica di errore, annullamento, reso o esecuzione parziale, anche questa va registrata nel sistema interno. Altrimenti nel pannello, nel CRM o nel bot l'ordine resterà in attesa, anche se l'ulteriore esecuzione non avverrà più.

Create una tabella di corrispondenza degli stati

Non trasferite lo stato dell'API nell'interfaccia senza elaborarlo. I nomi e la logica del fornitore possono cambiare, e uno stesso stato interno a volte unisce più stati esterni. Conservate il valore originale separatamente: sarà utile per analizzare gli errori e confrontarlo con la documentazione.

• pending, created, queued — ordine nuovo o in attesa di elaborazione.
• processing, in_progress, running — ordine in esecuzione.
• completed, delivered, success — ordine eseguito.
• partial, partially_completed — ordine parzialmente eseguito.
• cancelled, rejected, failed — ordine annullato o concluso con errore.
• refunded, returned — ordine che richiede un rimborso o una rettifica.
• Stato sconosciuto — non modifica automaticamente la scheda e viene inviato in verifica.

I nomi sopra riportati sono un esempio di schema. La tabella definitiva va costruita sugli stati dell'API specifica. Lo svantaggio della mappatura manuale è che dopo l'aggiornamento dell'API va mantenuta: un nuovo stato può arrivare all'handler prima che esista una regola per esso.

Scegliete webhook, polling dell'API o entrambi gli schemi

Un webhook è una richiesta inviata dal servizio al vostro URL al cambio di stato dell'ordine. Il polling dell'API funziona al contrario: il vostro sistema a intervalli richiede le informazioni sull'ordine. Per le notifiche di completamento di solito sono più comodi i webhook, perché l'aggiornamento arriva senza richieste costanti al metodo di verifica dello stato.

• I webhook sono adatti per una reazione rapida: aggiornamento della scheda, avvio della fase successiva o invio di un messaggio al responsabile.
• Il polling è adatto se il fornitore non supporta le notifiche callback o il server non accetta richieste esterne.
• Lo schema combinato usa i webhook come canale principale e il polling per individuare ordini persi o bloccati.

Lo svantaggio del polling è il ritardo e il carico superfluo sull'API. Lo svantaggio dei webhook è che bisogna proteggere l'endpoint, tenere conto dei duplicati e non affidarsi all'ordine di consegna degli eventi.

Configurate l'endpoint per la ricezione degli eventi

Per le notifiche serve un indirizzo HTTPS pubblico, accessibile dal lato del servizio API. Nelle impostazioni dell'integrazione di solito si indicano l'URL dell'handler, il segreto della firma e l'elenco degli eventi: cambio di stato, completamento, annullamento, errore o esecuzione parziale.

Dedicate un percorso separato solo per gli eventi API. Così è più semplice configurare il logging, limitare l'accesso, impostare i limiti di richieste e non mescolare il traffico di servizio con i moduli del sito. Non usate l'indirizzo dell'ambiente di test per gli ordini reali: dopo l'aggiornamento dell'ambiente il fornitore continuerà a inviare eventi all'URL salvato.

Prima del lancio verificate il metodo della richiesta e il formato del corpo secondo la documentazione. Il più delle volte è POST con JSON, ma si incontrano form-data, parametri query o uno schema di serializzazione proprietario. L'errore di parsing va registrato nel log, altrimenti sarà difficile distinguere un payload errato da un guasto dell'applicazione.

Conservate il collegamento tra ordine ed evento

Quando create un ordine tramite API, salvate l'identificatore restituito dal fornitore. Accanto conservate il numero interno dell'ordine, il tipo di servizio, lo stato originale, l'ora dell'ultima modifica e la risposta originale dell'API in forma sicura. Abbinate il webhook in arrivo tramite l'ID del fornitore, non tramite il link al canale, il nome del servizio o il nome del cliente.

Se l'API consente di trasmettere un identificatore esterno alla creazione, aggiungete il vostro numero d'ordine in un campo come external_id o client_reference. Questo semplifica la ricerca nei log e l'analisi delle situazioni controverse. Ma non rendete il numero esterno l'unica chiave: alcuni fornitori non lo restituiscono in ogni notifica.

Non create un nuovo ordine in base a un ID sconosciuto proveniente dal webhook. Un evento sconosciuto va salvato nel log e verificato separatamente. La creazione automatica di una voce può portare a dati errati o all'elaborazione di una richiesta falsificata.

Usate una struttura payload chiara

I nomi esatti dei campi dipendono dall'API. Quello che segue non è il contratto di un servizio specifico, ma un esempio di evento JSON a cui ispirarsi nella progettazione dell'handler interno. Sono importanti l'identificatore dell'evento, l'ID dell'ordine presso il fornitore, lo stato, l'ora della modifica e i dati per la diagnostica.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

Non usate la quantità di unità eseguite come indicatore di completamento senza lo stato. L'ordine può essere eseguito parzialmente, e il numero nel payload può essere arrotondato, aggiornato in ritardo o non essere affatto trasmesso. Lo svantaggio di conservare l'intero corpo dell'evento è che può contenere dati personali o campi di servizio, quindi tali registrazioni vanno mascherate e limitate nella durata di conservazione.

Verificate la firma sul corpo originale della richiesta

Un URL handler aperto può ricevere una richiesta non solo dal servizio API. Se il fornitore trasmette una firma, un segreto o un token, verificateli prima di modificare l'ordine. Uno schema diffuso è HMAC-SHA256: il fornitore calcola la firma dai byte del corpo della richiesta e da un segreto condiviso, poi trasmette il risultato in un header HTTP.

Il principio di calcolo è questo: si prende il corpo originale della richiesta, ad esempio i byte JSON senza modifiche, e il segreto dell'integrazione. Poi si calcola HMAC-SHA256. Se il risultato in forma esadecimale coincide con il valore dell'header, il corpo non è stato modificato dopo la firma e la richiesta è probabilmente inviata da una parte che conosce il segreto.

Esempio condizionale: HMAC_SHA256(segreto, raw_body) = firma dall'header X-Signature. Il nome dell'header, l'algoritmo e il formato del risultato vanno presi solo dalla documentazione dell'API. Alcuni servizi aggiungono un timestamp o un ID evento alla stringa da firmare. In questo caso non si può verificare solo il corpo JSON.

Non modificate il JSON prima di verificare la firma

La firma si verifica sui byte originali della richiesta, non sull'oggetto JSON che l'applicazione ha già analizzato e ricostruito. Con una nuova serializzazione possono cambiare l'ordine dei campi, gli spazi, l'escaping dei caratteri, il ritorno a capo o la codifica. Per una persona il JSON resterà lo stesso, ma l'insieme dei byte cambierà e l'HMAC non coinciderà più.

Per evitarlo, ottenete prima il raw body come bytes o buffer, salvatelo in memoria, calcolate la firma e solo dopo la verifica riuscita analizzate il JSON. Non applicate al corpo trim, conversione di codifica, ordinamento delle chiavi e formattazione. Nel middleware del framework verificate che il JSON non venga analizzato automaticamente prima dell'accesso al corpo originale.

Lo svantaggio di questo schema è che l'handler diventa dipendente dall'ordine dei middleware. Con una configurazione errata l'applicazione vedrà solo l'oggetto trasformato, e le notifiche legittime inizieranno a essere rifiutate.

Esempio di handler con verifica HMAC

Quello che segue è un esempio condizionale in Python. Mostra l'ordine delle operazioni, non un'integrazione pronta: header, algoritmo, formato della firma e campi del payload vanno sostituiti con i valori della documentazione del fornitore.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Per il confronto usate una funzione che non si interrompe al primo carattere non corrispondente. Questo riduce il rischio di fuga di informazioni sulla firma tramite il tempo di risposta. Non trasmettete il segreto nel codice client, non aggiungetelo all'URL e non registratelo integralmente nei log.

Rendete idempotente l'elaborazione degli eventi

Il fornitore può consegnare lo stesso evento più volte. Le cause sono comuni: il vostro server ha risposto lentamente, la connessione si è interrotta dopo il salvataggio dei dati, l'endpoint ha temporaneamente restituito un errore o il servizio ha avviato una nuova consegna secondo le proprie regole. La ripetizione non significa che l'API abbia creato un nuovo ordine.

Idempotenza significa che lo stesso evento modifica il risultato una sola volta. Se non si tiene conto di questa regola, il duplicato invierà di nuovo un messaggio al cliente, creerà più attività per il manager, accrediterà un compenso o avvierà un'operazione ripetuta.

La soluzione migliore è usare l'event_id dal payload. Salvatelo in una tabella separata o in un registro degli eventi elaborati con un vincolo di unicità. Se non c'è un ID separato, formate la chiave da campi stabili: ID dell'ordine del fornitore, tipo di evento, stato e ora della modifica. Questa variante è peggiore: con timestamp imprecisi eventi diversi possono sembrare uguali.

Salvate evento e stato in un'unica operazione

La verifica "l'evento è stato elaborato" e la scrittura del risultato devono essere eseguite in modo atomico. Altrimenti due richieste identiche arrivate contemporaneamente vedranno entrambe l'assenza del record e avvieranno l'azione due volte. Un'opzione pratica è un indice univoco su event_id e una transazione del database.

La continuazione condizionale dell'handler è questa:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

Lo svantaggio di rispondere con un codice di successo per un ordine sconosciuto è che il fornitore potrebbe non ripetere la consegna. Per questo gli eventi sconosciuti vanno monitorati separatamente e analizzati rapidamente. Se la documentazione dell'API raccomanda un codice di risposta diverso per questi casi, seguitela.

Tenete conto della violazione dell'ordine degli eventi

I webhook non sempre arrivano rigorosamente in ordine di tempo di modifica dello stato. Prima può arrivare l'evento di completamento, poi la notifica ritardata dello stato "in corso". Se si registra semplicemente l'ultimo valore ricevuto, l'ordine eseguito tornerà attivo.

Definite le transizioni consentite. Ad esempio, uno stato intermedio non può sovrascrivere quello finale, e un ordine annullato non passa a eseguito senza una verifica separata. Se l'API consente la rettifica dello stato finale, conservate la causa, il valore originale e la fonte della modifica.

Se il payload contiene l'ora della modifica dell'ordine, confrontate proprio quella, non l'ora di ricezione del webhook. Quando l'API non trasmette tale marca temporale, usate le priorità degli stati e la verifica tramite il metodo di recupero dell'ordine. Lo svantaggio delle priorità è che non sostituiscono la sequenza reale, soprattutto se il fornitore consente il reso da uno stato finale.

Confermate rapidamente la consegna e spostate le azioni in coda

Non eseguite operazioni lunghe prima di rispondere al fornitore. La verifica della firma, la ricerca dell'ordine, la registrazione dell'evento e l'aggiornamento dello stato di solito si possono completare rapidamente. L'invio del messaggio, la sincronizzazione con il CRM, la generazione del report o le richieste a sistemi di terze parti è meglio passarli a una coda di attività.

L'ordine operativo è questo: verificare la firma, salvare atomicamente l'evento e il cambio di stato, restituire una risposta di successo, poi eseguire le azioni secondarie. Se rispondete prima del salvataggio, in caso di guasto i dati andranno persi. Se rispondete dopo un lungo invio di notifica, il fornitore può considerare la consegna non riuscita e inviare un duplicato.

Lo svantaggio della coda è che compare un componente separato da controllare: errori delle attività, ritardi e riavvii. In compenso un guasto nella notifica al manager non blocca la ricezione degli stati degli ordini.

Configurate le notifiche per il team e per il cliente

Dopo il cambio di stato non bisogna notificare tutti allo stesso modo. Al manager di solito interessano annullamenti, errori, esecuzione parziale e ordini che non cambiano da molto tempo. Al cliente spesso basta un esito chiaro: ordine eseguito, annullato o da chiarire.

• Ordine completato — aggiornamento nell'area personale o breve messaggio al cliente.
• Errore di esecuzione — notifica al responsabile con la causa trasmessa dall'API.
• Esecuzione parziale — attività di verifica di rettifica, rimborso o azione successiva.
• Stato sconosciuto — registrazione nel log e messaggio allo specialista tecnico.
• ID ordine sconosciuto — verifica separata del collegamento tra il vostro sistema e il fornitore.

Non inviate un messaggio a ogni transizione tecnica. Il feed diventerà rapidamente rumore e un problema importante passerà inosservato. La notifica interna deve contenere il numero dell'ordine, il servizio, lo stato attuale, l'ID esterno e il link alla scheda.

Tenete un registro e verificate gli ordini non completati

I log servono a capire se il servizio ha inviato l'evento, quale corpo è arrivato, perché la firma non è passata e in quale fase si è fermata l'elaborazione. Salvate l'ora di ricezione, l'ID dell'evento, l'ID dell'ordine, il tipo di evento, l'esito della verifica della firma, lo stato interno e il codice di risposta. Mascherate segreti, token e dati personali.

Monitorate separatamente gli errori di consegna, le firme non valide, gli ordini sconosciuti, gli stati non supportati, i duplicati e gli eventi che non si possono applicare a causa dell'ordine degli stati. La crescita di tali registrazioni può indicare un cambiamento dello schema API, un segreto scaduto, un guasto del percorso o un errore nella logica dell'handler.

Periodicamente verificate gli ordini in stati intermedi tramite il metodo di recupero dati dell'API. Questa verifica non sostituisce i webhook, ma aiuta a individuare un evento perso, un guasto della coda o un caso in cui lo stato esterno è cambiato senza una notifica corretta.