API Blu Pantheon

Le API di Blu Pantheon sono API REST su HTTPS, con payload JSON e autenticazione tramite token Bearer. Ogni funzione disponibile nella Console è esposta anche via API: puoi automatizzare l'onboarding degli utenti, sincronizzare anagrafiche clienti, leggere conversazioni e statistiche, gestire prenotazioni e consultare consumi e fatture.

Cosa puoi fare

Ambienti e base URL

Ogni servizio è raggiungibile tramite un prefisso dedicato:

Versionamento

La versione maggiore è espressa nel path (/v1). Le modifiche retrocompatibili — nuovi campi in risposta, nuovi valori enum documentati come estendibili, nuovi endpoint — vengono rilasciate senza cambiare la versione.

Le modifiche non retrocompatibili comportano una nuova versione maggiore (/v2) e seguono questa politica:

Puoi fissare esplicitamente la revisione minore inviando l'header X-BP-Api-Version con una data:

curl https://api.blupantheon.com/identity/v1/me \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx" \
  -H "X-BP-Api-Version: 2026-09-01"

Se l'header è assente viene usata la revisione più recente compatibile con /v1.

Convenzioni

• Formato: richieste e risposte in application/json, codifica UTF-8. Il Content-Type è obbligatorio su tutte le richieste con body.
• Nomi dei campi: camelCase sia in input sia in output (createdAt, projectId, nextCursor).
• Date e orari: ISO 8601 con fuso orario esplicito, sempre in UTC nelle risposte (2026-09-04T10:32:15.482Z). In input sono accettati anche offset locali (2026-09-04T12:32:15+02:00).
• Identificatori: stringhe opache con prefisso tipizzato (usr_4a7b1e90, sess_9f2c8d41, bp_proj_7f3a9c21). Non fare assunzioni su lunghezza o alfabeto.
• Importi: interi in centesimi con codice valuta ISO 4217 separato ({ "amount": 12900, "currency": "EUR" }).
• Idempotenza: tutte le scritture accettano l'header Idempotency-Key. Vedi Endpoint.
• Paginazione: basata su cursore. Vedi Paginazione.
• Errori: envelope strutturato con code, title, message, traceId. Vedi Errori.

Hello World

L'esempio seguente autentica una chiamata con una chiave API e legge il profilo associato all'endpoint GET /identity/v1/me.

curl -sS https://api.blupantheon.com/identity/v1/me \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Risposta:

{
  "id": "usr_4a7b1e90",
  "email": "mario.rossi@acme.it",
  "firstName": "Mario",
  "lastName": "Rossi",
  "status": "active",
  "roles": ["tenant_admin"],
  "tenant": {
    "id": "tnt_2b8e4f11",
    "slug": "acme",
    "name": "ACME S.p.A."
  },
  "createdAt": "2025-11-14T09:21:03.117Z",
  "updatedAt": "2026-08-30T16:04:55.902Z"
}

Continua