Automazioni & RPA

Collega robot software e sistemi gestionali a Blu Pantheon con API REST in ingresso e webhook firmati HMAC in uscita.

Blu Pantheon è progettata per non restare isolata. Ogni conversazione, prenotazione, documento classificato o richiesta di handover può diventare un evento che alimenta i tuoi sistemi: ERP, CRM, AS/400, DMS, protocollo informatico, ticketing.

Questa sezione descrive il contratto di integrazione, le credenziali, la firma dei messaggi e le guide operative per le principali piattaforme RPA e iPaaS.

A chi è rivolta questa sezione

System integrator, automation engineer e team IT che devono collegare Blu Pantheon a sistemi aziendali esistenti. Serve familiarità con HTTP, JSON e con la gestione dei segreti.

Quando usare l'RPA con Blu Pantheon

L'automazione è la scelta giusta quando il sistema di destinazione non ha API moderne o quando il processo attraversa più applicazioni. Casi tipici in Italia:

Gestionali legacy (AS/400, applicativi client-server, terminali 5250) che si pilotano solo a livello di interfaccia utente.
Protocollo informatico e DMS della Pubblica Amministrazione, dove il deposito documentale avviene tramite procedure guidate.
CRM e ERP con API parziali, dove alcune operazioni richiedono comunque interazione UI.
Processi multi-sistema: una prenotazione confermata in Blu Pantheon deve creare contemporaneamente l'ordine nell'ERP, la scheda nel CRM e il ticket nel service desk.

Se invece il sistema di destinazione espone API REST moderne, valuta prima l'integrazione diretta: è più semplice da mantenere di un robot.

Le due direzioni di integrazione

Inbound — il bot chiama Blu Pantheon

Il robot invoca le API REST con una chiave API. Serve per leggere dati, creare clienti, chiudere sessioni, caricare documenti.

Outbound — Blu Pantheon chiama te

La piattaforma invia webhook firmati HMAC-SHA256 al tuo endpoint quando accade un evento. Serve per reagire in tempo reale.

Direzione	Chi inizia	Trasporto	Autenticazione	Latenza tipica
Inbound	Il tuo robot / backend	HTTPS verso `https://api.blupantheon.com`	Chiave API `bp_live_...` nel header `Authorization`	50-300 ms
Outbound	Blu Pantheon	HTTPS verso il tuo endpoint pubblico	Firma HMAC-SHA256 nel header `X-BP-Signature`	consegna entro pochi secondi dall'evento

Devo… → uso…

Devo…	Uso…	Pagina
Reagire in tempo reale a un evento della piattaforma	Webhook outbound	Webhook
Verificare che il webhook arrivi davvero da Blu Pantheon	Firma HMAC-SHA256	Firma HMAC
Leggere o scrivere dati da un robot	API REST + chiave API	Autenticazione
Evitare duplicati su una scrittura ripetuta	Header `Idempotency-Key`	Modello di integrazione
Recuperare dati storici o riallineare dopo un disservizio	Polling API paginato	Modello di integrazione
Capire perché una consegna è fallita	Log consegne in Console	Osservabilità
Interpretare un codice HTTP di errore	Tabella diagnostica	Errori comuni
Costruire un flusso completo end-to-end	Ricette pronte	Ricette

Architettura di riferimento

   Visitatore
       │
       ▼
  Widget / Canale ──► Agente AI ──► Motore eventi Blu Pantheon
                                          │
                        ┌─────────────────┴─────────────────┐
                        │ outbound (webhook firmato HMAC)   │
                        ▼                                   │
             https://automation.acme.it/webhooks/blupantheon │
                        │                                   │
                        ▼                                   │
              Orchestratore RPA (coda di lavoro)             │
                        │                                   │
                        ▼                                   │
              Robot ──► Gestionale / ERP / DMS               │
                        │                                   │
                        └──── inbound (REST + chiave API) ───┘
                                    api.blupantheon.com

Il pattern raccomandato è listener sottile + coda: l'endpoint HTTP che riceve il webhook verifica la firma, accoda il messaggio e risponde 202 in pochi millisecondi. Il robot elabora la coda in modo asincrono. In questo modo il tempo di risposta resta ben sotto i 10 secondi anche quando il gestionale è lento.

Sicurezza in sintesi

Requisiti non negoziabili

Un'integrazione in produzione deve rispettare tutti i punti seguenti. Le richieste che non li soddisfano vengono rifiutate o non consegnate.

Ambito	Requisito
Trasporto	Solo HTTPS con certificato TLS valido e catena completa. Nessun redirect.
Credenziali inbound	Chiave API `bp_live_...` in `Authorization: Bearer`. Mai in query string.
Credenziali outbound	Segreto `whsec_...` usato solo per verificare la firma, mai trasmesso.
Verifica firma	Obbligatoria su ogni webhook, con confronto a tempo costante.
Anti-replay	Finestra di tolleranza di 5 minuti sul timestamp firmato.
Idempotenza	Deduplica sul header `X-BP-Delivery` in ricezione, `Idempotency-Key` in scrittura.
Least privilege	Ogni chiave API riceve solo gli scope strettamente necessari.
Rotazione	Chiavi e segreti ruotati almeno ogni 12 mesi, con sovrapposizione.