Ricevere gli ordini Amazon con le SP-API Notifications (al posto del polling)

Flusso delle Amazon SP-API Notifications da EventBridge/SQS verso una Azure Function — Dalle SP-API Notifications a una Azure Function: ricevere gli ordini Amazon a eventi, senza polling.

Molte integrazioni Amazon importano gli ordini con il polling: interrogano la SP-API a intervalli regolari. Funziona, ma è fragile e in ritardo. Le SP-API Notifications ribaltano l'approccio: è Amazon a notificare i cambi di stato, e tu li consumi a eventi. Questa guida mostra come riceverli in modo affidabile su Azure con un consumer in .NET.

Perché le Notifications e non il polling

meno chiamate e nessun rate limit sprecato a vuoto;
latenza più bassa: reagisci quando l'evento accade;
meno logica di cursori e finestre temporali da mantenere.

Come funziona: destinazioni e sottoscrizioni

Il modello ha due passaggi. Prima si crea una destinazione con createDestination; poi si crea una sottoscrizione al tipo di notifica desiderato (per esempio ORDER_CHANGE). Amazon consegna le notifiche verso le proprie infrastrutture: Amazon EventBridge oppure una coda Amazon SQS.

Elemento	Ruolo
createDestination	Registra dove Amazon deve consegnare (EventBridge o SQS)
createSubscription	Attiva un tipo di notifica (es. ORDER_CHANGE) sulla destinazione
EventBridge / SQS	Punto di consegna lato Amazon/AWS

Dal lato Amazon ad Azure

Le notifiche atterrano su EventBridge o SQS (lato AWS). Per portarle in un'architettura Azure, un piccolo ponte legge da SQS e rilancia su Azure Service Bus, dove i tuoi worker le elaborano. È lo stesso schema descritto nell'ingestione ordini con Azure Functions e Service Bus: disaccoppi ricezione ed elaborazione e assorbi i picchi senza perdere eventi.

Idempotenza e affidabilità

Una notifica può arrivare più di una volta: tratta tutto come at-least-once e rendi idempotente l'elaborazione usando l'identificativo dell'ordine come chiave. La notifica è un segnale, non la fonte di verità: alla ricezione richiama la SP-API per leggere lo stato aggiornato dell'ordine, applicando i pattern di retry e rate limit per le chiamate.

Dati sensibili: Restricted Data Token

Gli ordini contengono dati personali (PII). Le operazioni che li espongono sono restricted e richiedono un Restricted Data Token (RDT), diverso dal token standard. Pianifica il flusso RDT per le chiamate che leggono indirizzi e dati dell'acquirente, e conserva i segreti fuori dal codice.

Esempio di bridge SQS verso Azure Service Bus

Il ponte non deve elaborare l'ordine: deve solo validare, deduplicare il messaggio AWS e accodare un evento interno. L'elaborazione vera resta nei worker Azure.

public async Task RunAsync(SqsMessage message)
{
    var notification = JsonSerializer.Deserialize<AmazonNotification>(message.Body);
    var key = $"amazon:{notification.NotificationType}:{notification.Payload.OrderId}";

    if (await dedup.ExistsAsync(key))
        return;

    await serviceBus.SendMessageAsync(new ServiceBusMessage(message.Body)
    {
        MessageId = key,
        CorrelationId = notification.NotificationMetadata.NotificationId,
        Subject = notification.NotificationType
    });

    await dedup.MarkAsync(key, TimeSpan.FromDays(7));
}

Se il worker Azure fallisce dopo aver letto l'ordine aggiornato, il messaggio resta nella dead-letter queue con correlation ID e payload originale. Questo rende il recupero molto più semplice del polling cieco.

Polling vs notifiche: confronto operativo

Aspetto	Polling	Notifications
Latenza	dipende dall'intervallo, spesso 5-15 minuti	quasi immediata, poi coda interna
Rate limit	consuma chiamate anche senza ordini	chiamate solo quando arriva un evento
Recovery	serve cursore temporale robusto	serve deduplica e dead-letter queue

Errori comuni

restare sul polling "perché funziona", accumulando latenza e rate limit;
elaborare in modo sincrono dentro il ricevitore invece di accodare;
fidarsi del payload della notifica come verità invece di rileggere l'ordine;
dimenticare l'RDT per le operazioni con PII.

Conclusione

Le SP-API Notifications rendono l'integrazione Amazon più reattiva e leggera, ma la robustezza la dai tu: destinazione e sottoscrizioni corrette, ponte verso Azure, idempotenza e RDT per i dati sensibili. Da leggere prima: la guida pratica all'Amazon SP-API. Riferimenti: Notifications API (Amazon) e Restricted Data Token.