Commerce Integration Hub
Una piattaforma per raccogliere ordini da sistemi diversi e monitorarne l’elaborazione, gestendo richieste duplicate e interruzioni temporanee dei servizi.
Il problema
I marketplace, i gestionali e i sistemi dei partner inviano ordini in formati diversi. Se una risposta non arriva, il sistema mittente può inviare di nuovo un ordine già ricevuto; inoltre, lo stesso identificativo può essere associato a dati diversi. Chi gestisce le integrazioni deve poter capire quali ordini sono arrivati, quali hanno avuto problemi e quali possono essere reinviati.
Cosa ho costruito
Ho sviluppato un gateway in Node.js e TypeScript che riceve webhook firmati e raccoglie ordini da un’API, convertendoli in un formato comune. Un servizio scritto in Kotlin con Quarkus conserva gli ordini in PostgreSQL e li elabora in modo asincrono, ricevendo gli eventi pubblicati su Kafka.
La console React permette di cercare gli ordini, seguirne la cronologia e controllare i tentativi di invio dal gateway. Quando un invio ha esaurito i tentativi automatici, un amministratore autorizzato può richiedere un nuovo tentativo se il connettore è attivo e i dati necessari sono ancora disponibili. La richiesta e il suo esito vengono registrati.
Una mappa interattiva dell’architettura permette di esplorare i componenti, i loro collegamenti e la relativa documentazione tecnica.
Il percorso di un ordine
Scelte progettuali
Separare i protocolli esterni dal modello degli ordini
Il gateway verifica le firme, converte i dati e recupera gli ordini dalle API esterne. Il servizio centrale verifica la coerenza degli ordini, riconosce duplicati e conflitti e ne gestisce lo stato durante l’elaborazione. I due servizi comunicano tramite un’API HTTP e usano database distinti.
Gestire le richieste duplicate
Il sistema riconosce un ordine già ricevuto attraverso il sistema di provenienza e l’identificativo esterno. Se i dati coincidono, lo considera un duplicato; se sono diversi, segnala un conflitto senza sovrascrivere l’ordine esistente. L’ordine e l’evento da pubblicare vengono salvati nella stessa transazione, così ogni nuovo ordine accettato ha un evento da inviare a Kafka.
Seguire l’elaborazione e individuare gli errori
La cronologia degli ordini, i tentativi di invio, le metriche e il tracing aiutano a capire come procede l’elaborazione e dove si verificano gli errori, anche quando il lavoro riprende dopo un’interruzione.
Mantenere ricostruibile l’indice di ricerca
PostgreSQL conserva i dati autorevoli degli ordini. OpenSearch mantiene una proiezione usata per la ricerca operativa, che può essere ricostruita a partire dai dati in PostgreSQL.
Stato e limiti
Il progetto può essere eseguito in locale con sistemi esterni simulati e dati sintetici. Il tracing con OpenTelemetry è opzionale e le tracce possono essere consultate in Jaeger. Le prestazioni sotto carico non sono state misurate.