Modello di integrazione

Questa pagina definisce come Blu Pantheon e i tuoi sistemi si parlano. Leggila prima di scrivere una riga di codice: le scelte descritte qui determinano affidabilità, costi operativi e facilità di diagnosi dell'integrazione.

I due canali

Inbound — dal tuo sistema verso Blu Pantheon

Il robot, il middleware o il backend aziendale chiama le API REST della piattaforma.

Caratteristiche:

• Sincrono: la risposta contiene subito il risultato.
• Autenticato con chiave API bp_live_xxxxxxxxxxxxxxxx.
• Soggetto a limiti di frequenza con header X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• Idempotente su richiesta per le scritture, tramite header Idempotency-Key.

Outbound — da Blu Pantheon verso il tuo sistema

Quando accade un evento, la piattaforma esegue una POST HTTPS verso l'endpoint registrato.

POST /webhooks/blupantheon HTTP/1.1
Host: automation.acme.it
Content-Type: application/json
User-Agent: BluPantheon-Webhooks/1.0
X-BP-Event: session.handover.requested
X-BP-Delivery: 7c1f0f9e-4b2a-4e7c-9a10-2f5c8d3b6a41
X-BP-Timestamp: 1767225600
X-BP-Signature: t=1767225600,v1=9f2c...c41d

Caratteristiche:

• Asincrono: l'evento viene consegnato dopo il fatto, non blocca la conversazione.
• At-least-once: la stessa consegna può ripetersi. La deduplica è responsabilità del consumatore.
• Non ordinato: due eventi vicini nel tempo possono arrivare invertiti.
• Firmato: ogni corpo è autenticato con HMAC-SHA256.

Flusso completo passo per passo

Scenario: un visitatore chiede di parlare con un operatore, il robot RPA apre un ticket nel gestionale e riporta il numero di pratica nella conversazione.

Sincrono contro asincrono

Garanzie di consegna

At-least-once

Ogni evento viene consegnato almeno una volta. Una consegna può ripetersi se:

• il tuo endpoint risponde con un codice diverso da 2xx;
• la risposta arriva oltre 10 secondi;
• la connessione TCP o il handshake TLS falliscono;
• un operatore esegue un replay manuale dalla Console.

Nessuna garanzia di ordine

Gli eventi non sono ordinati. Non assumere che session.created arrivi prima di session.message.created della stessa sessione. Per ricostruire l'ordine usa il campo createdAt del payload, non l'ordine di arrivo.

function shouldApply(incoming, stored) {
  if (!stored) return true;
  return new Date(incoming.createdAt) > new Date(stored.createdAt);
}

Idempotenza

Schema di deduplica consigliato: una tabella con delivery_id come chiave primaria, stato (received, processing, done, failed) e timestamp. Conserva i record almeno 7 giorni, cioè oltre la durata massima della catena di ritentativi.

CREATE TABLE bp_webhook_delivery (
  delivery_id   CHAR(36)     NOT NULL PRIMARY KEY,
  event_type    VARCHAR(64)  NOT NULL,
  event_id      VARCHAR(64)  NOT NULL,
  status        VARCHAR(16)  NOT NULL DEFAULT 'received',
  received_at   DATETIME(3)  NOT NULL,
  processed_at  DATETIME(3)  NULL,
  INDEX idx_event (event_id),
  INDEX idx_status_received (status, received_at)
);

Backpressure e code

Il tuo endpoint deve rispondere entro 10 secondi. Se il sistema a valle rallenta, non rallentare la risposta: accoda.

Timeout e budget di errore

Definisci un budget di errore esplicito: ad esempio, non più dello 0,5% di consegne fallite su finestra di 24 ore. Superata la soglia, l'integrazione va considerata degradata e va aperta una verifica. Vedi Osservabilità per le metriche.

Webhook, polling o batch?

Quando scegliere cosa

• Webhook: reazione in tempo reale a eventi di business. È la scelta predefinita.
• Polling API: quando non puoi esporre un endpoint pubblico (rete chiusa, vincoli di sicurezza), oppure per riconciliazione periodica dopo un disservizio.
• Batch export: per popolamento iniziale, data warehouse, reportistica e analisi storiche.

curl -sS -G "https://api.blupantheon.com/identity/v1/events" \
  -H "Authorization: Bearer $BP_API_KEY" \
  -H "X-BP-Project: bp_proj_7f3a9c21" \
  --data-urlencode "since=2026-09-04T08:00:00Z" \
  --data-urlencode "limit=100" \
  --data-urlencode "cursor=$LAST_CURSOR"

Versionamento del contratto

Ogni payload contiene apiVersion. Le regole di compatibilità sono:

Passi successivi