Blu Pantheon
Riferimento API

Riferimento endpoint

Riferimento completo degli endpoint REST di Identity, Console, Billing e Booking con esempi di richiesta e risposta.

Riferimento operativo degli endpoint più usati, raggruppati per servizio. Tutti gli esempi usano il base URL di produzione https://api.blupantheon.com; sostituiscilo con quello dell'ambiente in uso (vedi Ambienti).

Idempotenza sulle scritture

Ogni endpoint POST, PUT, PATCH e DELETE accetta l'header Idempotency-Key con un valore univoco generato dal client (consigliato un UUID v4). Se la stessa chiave viene riusata entro 24 ore con un body identico, la piattaforma restituisce la risposta originale senza rieseguire l'operazione. Se il body è diverso la risposta è 409 con codice DUPLICATE_REQUEST.

Identity

Prefisso /identity/v1. Gestisce autenticazione, utenti, ruoli, chiavi API e configurazione del tenant.

Login

POST/identity/v1/auth/loginPubblico

Autentica un utente con email e password e restituisce access token e refresh token.

Corpo della richiesta

ParametroTipoObblig.DefaultDescrizione
emailstringSì—Indirizzo email dell’utente, non sensibile alle maiuscole.
passwordstringSì—Password in chiaro, trasmessa esclusivamente su TLS.
tenantSlugstringNo—Obbligatorio solo se l’utente appartiene a più tenant.
deviceNamestringNo—Etichetta del dispositivo mostrata nell’elenco delle sessioni attive.
Richiesta
curl -sS -X POST https://api.blupantheon.com/identity/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"mario.rossi@acme.it","password":"••••••••","tenantSlug":"acme"}'
200 OK
{
  "type": "success",
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_8c1d4f7a2b9e0563a1d8c47f2e9b0355",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "user": { "id": "usr_4a7b1e90", "email": "mario.rossi@acme.it", "roles": ["tenant_admin"] }
}

Refresh

POST/identity/v1/auth/refreshPubblico

Scambia un refresh token valido con una nuova coppia di token. Il token presentato viene invalidato.

Richiesta
{ "refreshToken": "rt_8c1d4f7a2b9e0563a1d8c47f2e9b0355" }
200 OK
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_1f6b2e94d7c3a08516ba9e2f7c4d1088",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Logout

POST/identity/v1/auth/logoutBearer JWT

Revoca la sessione corrente o tutte le sessioni attive. Accetta Idempotency-Key.

Richiesta
{ "refreshToken": "rt_1f6b2e94d7c3a08516ba9e2f7c4d1088", "allSessions": false }
200 OK
{ "revokedSessions": 1, "revokedAt": "2026-09-04T10:32:15.482Z" }

Profilo corrente

GET/identity/v1/meBearer JWT

Restituisce il profilo dell'utente o dell'applicazione associata alla credenziale usata.

Richiesta
curl -sS https://api.blupantheon.com/identity/v1/me \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx"
200 OK
{
  "id": "usr_4a7b1e90",
  "email": "mario.rossi@acme.it",
  "firstName": "Mario",
  "lastName": "Rossi",
  "status": "active",
  "roles": ["tenant_admin"],
  "permissions": ["identity:users:read", "identity:users:write", "console:sessions:read"],
  "tenant": { "id": "tnt_2b8e4f11", "slug": "acme", "name": "ACME S.p.A." },
  "mfaEnabled": true,
  "lastLoginAt": "2026-09-04T08:12:09.640Z",
  "createdAt": "2025-11-14T09:21:03.117Z"
}

Elenco utenti

GET/identity/v1/usersBearer JWT

Elenca gli utenti del tenant. Supporta paginazione a cursore, ricerca testuale e filtri di stato.

Parametri query

ParametroTipoObblig.DefaultDescrizione
limitnumberNo50Elementi per pagina, da 1 a 200.
cursorstringNo—Cursore restituito dalla chiamata precedente.
statusstringNo—Filtra per stato: active, invited, disabled.
rolestringNo—Filtra per ruolo assegnato, ad esempio tenant_admin.
qstringNo—Ricerca su nome, cognome ed email. Minimo 2 caratteri.
sortstringNocreatedAtCampo di ordinamento: createdAt, updatedAt, lastLoginAt, email.
Richiesta
curl -sS "https://api.blupantheon.com/identity/v1/users?limit=50&status=active&sort=createdAt&order=desc" \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx"
200 OK
{
  "data": [
    {
      "id": "usr_4a7b1e90",
      "email": "mario.rossi@acme.it",
      "firstName": "Mario",
      "lastName": "Rossi",
      "status": "active",
      "roles": ["tenant_admin"],
      "lastLoginAt": "2026-09-04T08:12:09.640Z",
      "createdAt": "2025-11-14T09:21:03.117Z"
    }
  ],
  "pagination": { "nextCursor": "eyJpZCI6InVzcl80YTdiMWU5MCJ9", "hasMore": true, "total": 87 }
}

Creazione utente

POST/identity/v1/usersBearer JWT

Crea un utente e, se richiesto, invia l'invito via email. Accetta Idempotency-Key.

Corpo della richiesta

ParametroTipoObblig.DefaultDescrizione
emailstringSì—Indirizzo email univoco nel tenant.
firstNamestringSì—Nome, da 1 a 100 caratteri.
lastNamestringSì—Cognome, da 1 a 100 caratteri.
rolesstring[]Sì—Ruoli da assegnare. Almeno un ruolo esistente nel tenant.
sendInvitationbooleanNotrueSe true invia l’email di invito con il link di attivazione.
localestringNoit-ITLingua delle comunicazioni inviate all’utente.
Richiesta
curl -sS -X POST https://api.blupantheon.com/identity/v1/users \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1a2b8c-4d5e-4a90-b3c7-1e2f3a4b5c6d" \
  -d '{
    "email": "giulia.bianchi@acme.it",
    "firstName": "Giulia",
    "lastName": "Bianchi",
    "roles": ["operator"],
    "sendInvitation": true
  }'
201 Created
{
  "id": "usr_8d2c6f04",
  "email": "giulia.bianchi@acme.it",
  "firstName": "Giulia",
  "lastName": "Bianchi",
  "status": "invited",
  "roles": ["operator"],
  "invitationExpiresAt": "2026-09-11T10:32:15.482Z",
  "createdAt": "2026-09-04T10:32:15.482Z"
}

Aggiornamento utente

PATCH/identity/v1/users/{userId}Bearer JWT

Aggiorna i campi indicati. I campi omessi restano invariati. Accetta Idempotency-Key.

Richiesta
{
  "firstName": "Giulia",
  "lastName": "Bianchi Ferrari",
  "roles": ["operator", "supervisor"]
}
200 OK
{
  "id": "usr_8d2c6f04",
  "email": "giulia.bianchi@acme.it",
  "firstName": "Giulia",
  "lastName": "Bianchi Ferrari",
  "status": "active",
  "roles": ["operator", "supervisor"],
  "updatedAt": "2026-09-04T11:04:52.318Z"
}

Disattivazione utente

DELETE/identity/v1/users/{userId}Bearer JWT

Disattiva l'utente e revoca tutte le sue sessioni. L'operazione è reversibile dalla Console. Accetta Idempotency-Key.

200 OK
{
  "id": "usr_8d2c6f04",
  "status": "disabled",
  "revokedSessions": 3,
  "disabledAt": "2026-09-04T11:20:07.905Z"
}

Disattivazione, non cancellazione

La disattivazione conserva lo storico delle attività per finalità di audit. Per la cancellazione definitiva dei dati personali usa la procedura di esercizio dei diritti descritta nella sezione conformità: è un flusso separato e irreversibile.

Elenco ruoli

GET/identity/v1/rolesBearer JWT

Elenca i ruoli disponibili nel tenant con i permessi associati.

200 OK
{
  "data": [
    {
      "id": "rol_1a4c7e02",
      "name": "tenant_admin",
      "displayName": "Amministratore",
      "system": true,
      "permissions": ["identity:users:read", "identity:users:write", "console:*:*"],
      "userCount": 3
    },
    {
      "id": "rol_9b3e5d71",
      "name": "operator",
      "displayName": "Operatore",
      "system": false,
      "permissions": ["console:sessions:read", "console:sessions:write"],
      "userCount": 24
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false, "total": 6 }
}

Creazione chiave API

POST/identity/v1/api-keysBearer JWT

Crea una chiave API. Il segreto completo è restituito una sola volta. Accetta Idempotency-Key.

Corpo della richiesta

ParametroTipoObblig.DefaultDescrizione
namestringSì—Nome descrittivo del consumatore, ad esempio erp-sync-produzione.
scopesstring[]Sì—Permessi nel formato servizio:risorsa:azione. Non può superare i permessi del creatore.
expiresAtstringNo—Data ISO 8601 di scadenza. Se omessa la chiave non scade.
ipAllowliststring[]No—Elenco di indirizzi o reti CIDR autorizzati a usare la chiave.
Richiesta
curl -sS -X POST https://api.blupantheon.com/identity/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2c9f7a10-63b4-4f8e-9d15-0a7c3e5b8f42" \
  -d '{
    "name": "erp-sync-produzione",
    "scopes": ["console:clients:read", "console:clients:write"],
    "ipAllowlist": ["203.0.113.24/32"]
  }'
201 Created
{
  "id": "key_6d3f0a82",
  "name": "erp-sync-produzione",
  "prefix": "bp_live_xxxx",
  "secret": "bp_live_xxxxxxxxxxxxxxxx",
  "scopes": ["console:clients:read", "console:clients:write"],
  "status": "active",
  "createdAt": "2026-09-04T10:32:15.482Z"
}

Revoca chiave API

DELETE/identity/v1/api-keys/{keyId}Bearer JWT

Revoca immediatamente la chiave. L'operazione è irreversibile. Accetta Idempotency-Key.

200 OK
{ "id": "key_6d3f0a82", "status": "revoked", "revokedAt": "2026-09-04T12:01:44.223Z" }

Elenco tenant

GET/identity/v1/tenantsBearer JWT

Elenca i tenant a cui la credenziale ha accesso. Per la maggior parte degli utenti restituisce un solo elemento.

200 OK
{
  "data": [
    {
      "id": "tnt_2b8e4f11",
      "slug": "acme",
      "name": "ACME S.p.A.",
      "status": "active",
      "plan": "business",
      "region": "eu-west",
      "createdAt": "2025-11-14T09:18:55.402Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false, "total": 1 }
}

Impostazioni tenant

PATCH/identity/v1/tenants/{tenantId}/settingsBearer JWT

Aggiorna le impostazioni del tenant: sicurezza, localizzazione e criteri password. Accetta Idempotency-Key.

Richiesta
{
  "defaultLocale": "it-IT",
  "timezone": "Europe/Rome",
  "security": {
    "mfaRequired": true,
    "sessionIdleTimeoutMinutes": 30,
    "passwordMinLength": 12,
    "ipAllowlist": ["203.0.113.0/24"]
  }
}
200 OK
{
  "tenantId": "tnt_2b8e4f11",
  "defaultLocale": "it-IT",
  "timezone": "Europe/Rome",
  "security": {
    "mfaRequired": true,
    "sessionIdleTimeoutMinutes": 30,
    "passwordMinLength": 12,
    "ipAllowlist": ["203.0.113.0/24"]
  },
  "updatedAt": "2026-09-04T12:15:31.774Z"
}

Console

Prefisso /console/v1. Conversazioni, anagrafiche, progetti, knowledge base e statistiche.

Elenco sessioni

GET/console/v1/sessionsAPI Key

Elenca le conversazioni. Filtrabile per progetto, stato, canale e intervallo temporale.

Parametri query

ParametroTipoObblig.DefaultDescrizione
projectIdstringNo—Limita i risultati a un progetto, ad esempio bp_proj_7f3a9c21.
statusstringNo—Stato della sessione: open, closed, handover, abandoned.
channelstringNo—Canale di origine: web, whatsapp, email, telegram, api.
clientIdstringNo—Limita i risultati alle sessioni di un cliente.
createdAfterstringNo—Data ISO 8601 di inizio finestra, estremo escluso.
createdBeforestringNo—Data ISO 8601 di fine finestra, estremo escluso.
limitnumberNo50Elementi per pagina, da 1 a 200.
Richiesta
curl -sS -G "https://api.blupantheon.com/console/v1/sessions" \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx" \
  --data-urlencode "projectId=bp_proj_7f3a9c21" \
  --data-urlencode "status=open" \
  --data-urlencode "limit=50"
200 OK
{
  "data": [
    {
      "id": "sess_9f2c8d41",
      "projectId": "bp_proj_7f3a9c21",
      "clientId": "cli_5e1a7b30",
      "channel": "web",
      "status": "open",
      "language": "it",
      "messageCount": 14,
      "startedAt": "2026-09-04T09:12:44.006Z",
      "lastActivityAt": "2026-09-04T09:41:02.884Z"
    }
  ],
  "pagination": { "nextCursor": "eyJpZCI6InNlc3NfOWYyYzhkNDEifQ", "hasMore": true, "total": 1234 }
}

Dettaglio sessione

GET/console/v1/sessions/{sessionId}API Key

Restituisce il dettaglio completo di una sessione, incluse metriche e metadati raccolti.

200 OK
{
  "id": "sess_9f2c8d41",
  "projectId": "bp_proj_7f3a9c21",
  "clientId": "cli_5e1a7b30",
  "channel": "web",
  "status": "open",
  "language": "it",
  "messageCount": 14,
  "metrics": {
    "durationSeconds": 1698,
    "averageResponseMs": 1240,
    "tokensUsed": 8412,
    "satisfactionScore": 4
  },
  "metadata": { "sourceUrl": "https://www.acme.it/supporto", "utmCampaign": "settembre-2026" },
  "tags": ["preventivo", "prima-linea"],
  "startedAt": "2026-09-04T09:12:44.006Z",
  "lastActivityAt": "2026-09-04T09:41:02.884Z"
}

Messaggi di una sessione

GET/console/v1/sessions/{sessionId}/messagesAPI Key

Elenca i messaggi in ordine cronologico. Consigliato order=asc per ricostruire la conversazione.

200 OK
{
  "data": [
    {
      "id": "msg_1c7e0b93",
      "sessionId": "sess_9f2c8d41",
      "role": "user",
      "content": "Buongiorno, vorrei un preventivo per 50 licenze.",
      "createdAt": "2026-09-04T09:12:44.301Z"
    },
    {
      "id": "msg_4f9a2d18",
      "sessionId": "sess_9f2c8d41",
      "role": "assistant",
      "content": "Certamente. Mi conferma la ragione sociale e la partita IVA?",
      "citations": [{ "documentId": "doc_2e8b4c07", "title": "Listino 2026", "score": 0.87 }],
      "createdAt": "2026-09-04T09:12:46.914Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false, "total": 14 }
}

Chiusura sessione

POST/console/v1/sessions/{sessionId}/closeAPI Key

Chiude la conversazione e ne congela lo storico. Accetta Idempotency-Key.

Richiesta
{ "reason": "resolved", "note": "Preventivo inviato via email." }
200 OK
{
  "id": "sess_9f2c8d41",
  "status": "closed",
  "reason": "resolved",
  "closedAt": "2026-09-04T10:02:11.556Z"
}

Richiesta di passaggio a operatore

POST/console/v1/sessions/{sessionId}/handoverAPI Key

Trasferisce la conversazione a un operatore umano e notifica la coda indicata. Accetta Idempotency-Key.

Richiesta
{
  "queue": "vendite",
  "priority": "high",
  "reason": "Richiesta di sconto fuori listino",
  "context": { "dealSize": "50 licenze" }
}
202 Accepted
{
  "sessionId": "sess_9f2c8d41",
  "handoverId": "hnd_7a3c5e01",
  "status": "pending",
  "queue": "vendite",
  "position": 2,
  "requestedAt": "2026-09-04T09:44:18.220Z"
}

Clienti

Elenco progetti

GET/console/v1/projectsAPI Key

Elenca i progetti configurati nel tenant, con stato di pubblicazione e canali attivi.

200 OK
{
  "data": [
    {
      "id": "bp_proj_7f3a9c21",
      "name": "Assistenza clienti",
      "slug": "assistenza-clienti",
      "status": "published",
      "channels": ["web", "whatsapp"],
      "defaultLanguage": "it",
      "createdAt": "2026-01-20T10:05:44.918Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false, "total": 4 }
}

Dettaglio progetto

GET/console/v1/projects/{projectId}API Key

Restituisce la configurazione completa del progetto: modello, comportamento, knowledge base collegate.

200 OK
{
  "id": "bp_proj_7f3a9c21",
  "name": "Assistenza clienti",
  "status": "published",
  "model": { "provider": "azure-openai", "name": "gpt-4o", "temperature": 0.2 },
  "dataStores": ["ds_3c8f1a60", "ds_7e2b9d45"],
  "tools": ["booking.create", "crm.lookup"],
  "handover": { "enabled": true, "queue": "vendite" },
  "updatedAt": "2026-08-28T15:39:07.462Z"
}

Knowledge base

GET/console/v1/data-storesAPI Key

Elenca le knowledge base del tenant con conteggio documenti e spazio occupato.

200 OK
{
  "data": [
    {
      "id": "ds_3c8f1a60",
      "name": "Documentazione prodotto",
      "documentCount": 312,
      "sizeBytes": 184320512,
      "status": "ready",
      "lastIndexedAt": "2026-09-03T22:14:51.309Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false, "total": 3 }
}

Caricamento documento

POST/console/v1/data-stores/{storeId}/documentsAPI Key

Carica un documento nella knowledge base. Richiesta multipart/form-data. Accetta Idempotency-Key.

Richiesta
curl -sS -X POST "https://api.blupantheon.com/console/v1/data-stores/ds_3c8f1a60/documents" \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 9e0b1c47-2f83-4d5a-8b16-7c4e2a9d5f30" \
  -F "file=@listino-2026.pdf" \
  -F 'metadata={"title":"Listino 2026","language":"it","tags":["listino"]}'
202 Accepted
{
  "id": "doc_2e8b4c07",
  "dataStoreId": "ds_3c8f1a60",
  "title": "Listino 2026",
  "fileName": "listino-2026.pdf",
  "sizeBytes": 1843205,
  "status": "processing",
  "createdAt": "2026-09-04T10:32:15.482Z"
}

Indicizzazione asincrona

Il documento è utilizzabile solo quando lo stato passa a ready. Attendi l'evento webhook document.indexed invece di interrogare ripetutamente lo stato: vedi Riferimento webhook.

Statistiche

GET/console/v1/statisticsAPI Key

Restituisce metriche aggregate su conversazioni, consumi e qualità in una finestra temporale.

Parametri query

ParametroTipoObblig.DefaultDescrizione
fromstringSì—Inizio della finestra in formato ISO 8601.
tostringSì—Fine della finestra in formato ISO 8601. Massimo 366 giorni dall’inizio.
granularitystringNodayAggregazione dei punti: hour, day, week, month.
projectIdstringNo—Limita le metriche a un progetto.
metricsstringNo—Elenco di metriche separate da virgola. Se omesso restituisce il set predefinito.
200 OK
{
  "range": { "from": "2026-08-01T00:00:00Z", "to": "2026-09-01T00:00:00Z", "granularity": "day" },
  "totals": {
    "sessions": 4820,
    "messages": 61204,
    "handovers": 312,
    "tokensUsed": 18420115,
    "averageSatisfaction": 4.3,
    "resolutionRate": 0.87
  },
  "series": [
    { "date": "2026-08-01", "sessions": 142, "messages": 1810, "handovers": 9 },
    { "date": "2026-08-02", "sessions": 118, "messages": 1503, "handovers": 6 }
  ]
}

Billing

Prefisso /billing/v1. Abbonamento, consumi e documenti contabili del tenant.

Abbonamento

GET/billing/v1/subscriptionAPI Key

Restituisce piano attivo, ciclo di fatturazione e limiti inclusi.

200 OK
{
  "id": "sub_4b7e1a09",
  "plan": "business",
  "status": "active",
  "billingCycle": "monthly",
  "currentPeriodStart": "2026-09-01T00:00:00Z",
  "currentPeriodEnd": "2026-10-01T00:00:00Z",
  "price": { "amount": 49900, "currency": "EUR" },
  "limits": { "seats": 25, "sessionsPerMonth": 20000, "storageGb": 100 },
  "cancelAtPeriodEnd": false
}

Fatture

GET/billing/v1/invoicesAPI Key

Elenca le fatture emesse, dalla più recente. Il campo pdfUrl è un link firmato valido 15 minuti.

200 OK
{
  "data": [
    {
      "id": "inv_0f3d8b52",
      "number": "2026/000418",
      "status": "paid",
      "issuedAt": "2026-09-01T06:00:00Z",
      "dueAt": "2026-09-15T00:00:00Z",
      "paidAt": "2026-09-01T06:04:33.117Z",
      "total": { "amount": 60878, "currency": "EUR" },
      "taxAmount": { "amount": 10978, "currency": "EUR" },
      "pdfUrl": "https://files.blupantheon.com/invoices/inv_0f3d8b52.pdf?sig=..."
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false, "total": 11 }
}

Consumi

GET/billing/v1/usageAPI Key

Restituisce i contatori di utilizzo del periodo corrente o di un periodo indicato.

200 OK
{
  "period": { "start": "2026-09-01T00:00:00Z", "end": "2026-10-01T00:00:00Z" },
  "items": [
    { "metric": "sessions", "used": 4820, "included": 20000, "unit": "sessione" },
    { "metric": "tokens", "used": 18420115, "included": 50000000, "unit": "token" },
    { "metric": "storage", "used": 42, "included": 100, "unit": "GB" }
  ],
  "overage": { "amount": 0, "currency": "EUR" },
  "updatedAt": "2026-09-04T10:00:00Z"
}

Profilo di fatturazione

PUT/billing/v1/billing-profileBearer JWT

Aggiorna i dati di fatturazione del tenant. Sostituisce l'intero profilo. Accetta Idempotency-Key.

Richiesta
{
  "legalName": "ACME S.p.A.",
  "vatNumber": "IT01234567890",
  "taxCode": "01234567890",
  "sdiCode": "ABCDEFG",
  "pec": "amministrazione@pec.acme.it",
  "address": {
    "line1": "Via Roma 12",
    "city": "Milano",
    "postalCode": "20121",
    "province": "MI",
    "country": "IT"
  }
}
200 OK
{
  "tenantId": "tnt_2b8e4f11",
  "legalName": "ACME S.p.A.",
  "vatNumber": "IT01234567890",
  "sdiCode": "ABCDEFG",
  "verified": true,
  "updatedAt": "2026-09-04T12:22:48.903Z"
}

Booking

Prefisso /booking/v1. Disponibilità e gestione degli appuntamenti.

Disponibilità

GET/booking/v1/availabilityAPI Key

Restituisce gli slot prenotabili per una risorsa o un servizio in un intervallo di date.

Parametri query

ParametroTipoObblig.DefaultDescrizione
serviceIdstringSì—Servizio richiesto, ad esempio svc_1d9a4f70.
fromstringSì—Inizio dell’intervallo in formato ISO 8601.
tostringSì—Fine dell’intervallo in formato ISO 8601. Massimo 90 giorni.
resourceIdstringNo—Limita la ricerca a una risorsa specifica, ad esempio un operatore.
timezonestringNoEurope/RomeFuso orario usato per calcolare gli orari di apertura.
200 OK
{
  "serviceId": "svc_1d9a4f70",
  "timezone": "Europe/Rome",
  "slots": [
    { "start": "2026-09-08T09:00:00+02:00", "end": "2026-09-08T09:30:00+02:00", "resourceId": "res_5c2e8a13", "available": true },
    { "start": "2026-09-08T09:30:00+02:00", "end": "2026-09-08T10:00:00+02:00", "resourceId": "res_5c2e8a13", "available": false }
  ]
}

Creazione prenotazione

POST/booking/v1/bookingsAPI Key

Crea una prenotazione su uno slot disponibile. Accetta Idempotency-Key: indispensabile per evitare doppie prenotazioni in caso di timeout.

Richiesta
{
  "serviceId": "svc_1d9a4f70",
  "resourceId": "res_5c2e8a13",
  "start": "2026-09-08T09:00:00+02:00",
  "clientId": "cli_5e1a7b30",
  "notes": "Primo appuntamento conoscitivo",
  "customFields": { "canale": "chat" }
}
201 Created
{
  "id": "bkg_2a6f9c34",
  "serviceId": "svc_1d9a4f70",
  "resourceId": "res_5c2e8a13",
  "clientId": "cli_5e1a7b30",
  "status": "pending",
  "start": "2026-09-08T07:00:00Z",
  "end": "2026-09-08T07:30:00Z",
  "confirmationCode": "ACME-4821",
  "createdAt": "2026-09-04T10:32:15.482Z"
}

Conferma prenotazione

POST/booking/v1/bookings/{bookingId}/confirmAPI Key

Conferma una prenotazione in stato pending e invia la notifica al cliente. Accetta Idempotency-Key.

200 OK
{
  "id": "bkg_2a6f9c34",
  "status": "confirmed",
  "confirmedAt": "2026-09-04T10:35:02.771Z",
  "notificationsSent": ["email", "sms"]
}

Annullamento prenotazione

DELETE/booking/v1/bookings/{bookingId}API Key

Annulla la prenotazione e libera lo slot. Accetta Idempotency-Key.

Richiesta
{ "reason": "client_request", "note": "Il cliente ha chiesto di rimandare." }
200 OK
{
  "id": "bkg_2a6f9c34",
  "status": "cancelled",
  "reason": "client_request",
  "cancelledAt": "2026-09-05T08:12:40.019Z"
}

Elenco prenotazioni

GET/booking/v1/bookingsAPI Key

Elenca le prenotazioni filtrabili per stato, servizio, risorsa, cliente e intervallo temporale.

Richiesta
curl -sS -G "https://api.blupantheon.com/booking/v1/bookings" \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx" \
  --data-urlencode "status=confirmed" \
  --data-urlencode "from=2026-09-08T00:00:00Z" \
  --data-urlencode "to=2026-09-15T00:00:00Z" \
  --data-urlencode "limit=100"
200 OK
{
  "data": [
    {
      "id": "bkg_2a6f9c34",
      "serviceId": "svc_1d9a4f70",
      "clientId": "cli_5e1a7b30",
      "status": "confirmed",
      "start": "2026-09-08T07:00:00Z",
      "end": "2026-09-08T07:30:00Z",
      "confirmationCode": "ACME-4821"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false, "total": 37 }
}

Approfondimenti

Autenticazione

Come ottenere e gestire le credenziali usate in questi esempi.

Paginazione

Cursori, filtri e ordinamento applicabili a tutte le collezioni.

Errori

Codici restituiti dagli endpoint e come gestirli.

Webhook

Ricevi gli eventi invece di interrogare gli endpoint in polling.

Errori

Envelope di errore, mappa degli status HTTP, catalogo completo dei codici e uso del traceId con il supporto.

Riferimento webhook

Schema degli eventi, catalogo completo, payload di esempio, firma HMAC, ritentativi e coda dei messaggi non recapitati.

In questa pagina

IdentityLoginRefreshLogoutProfilo correnteElenco utentiCreazione utenteAggiornamento utenteDisattivazione utenteElenco ruoliCreazione chiave APIRevoca chiave APIElenco tenantImpostazioni tenantConsoleElenco sessioniDettaglio sessioneMessaggi di una sessioneChiusura sessioneRichiesta di passaggio a operatoreClientiElenco progettiDettaglio progettoKnowledge baseCaricamento documentoStatisticheBillingAbbonamentoFattureConsumiProfilo di fatturazioneBookingDisponibilitàCreazione prenotazioneConferma prenotazioneAnnullamento prenotazioneElenco prenotazioniApprofondimenti