Documentazione per sviluppatori

🔐 Autenticazione

POST /api/auth/login

Autenticare gli utenti admin e ottenere il token di accesso

{
  "email": "admin@office16852.com",
  "password": "your_password"
}

POST /api/customers/auth/login

Autenticare utenti cliente (multi-tenant)

{
  "email": "customer@business.com",
  "password": "customer_password"
}

Chat e conversazioni

Tre percorsi: (1) Stessa origine, accesso anonimo, pubblico. → POST /api/chat (es. widget del sito marketing; senza login). (2) Embed cross-origin → POST /api/widget/chat with X-Widget-Key and allowed Origin. (3) App autenticata / Mission Control → POST /api/chat/session e POST /api/chat/message (richiede chat.manage and session/CSRF for cookie auth) — non for anonymous fetch dalle pagine pubbliche.

1) Pubblico anonimo (same-origin)

POST /api/chat

Unified pipeline for visitors on your own domain without signing in. Body includes message, session_id, opzionale business_id.

2) Widget cross-origin

POST /api/widget/chat

Incorporato nei siti dei clienti. Header: X-Widget-Key, Content-Type: application/json. Origin must be allowed for the key. See docs/REQUEST_FLOWS.md nel repository per i dettagli CORS.

3) Solo sessione autenticata / UI admin

POST /api/chat/session

Crea una sessione quando si accede a Mission Control o alla dashboard (RBAC + CSRF per i cookie).

POST /api/chat/message

Send a message from autenticato admin/chat UI (chat.manage). Restituisce 401 if called anonymously from a public page — use POST /api/chat per quel caso al posto giusto.

{
  "session_id": "session_123",
  "message": "Hello, I need help with my order"
}

GET /api/chat/history/:session_id

Recuperare la cronologia chat (autenticato)

📊 Analytics e monitoraggio

GET /api/analytics/overview

Ottieni una panoramica delle analisi di sistema

GET /api/health

Controlla lo stato di salute del sistema

GET /api/metrics/business

Ottieni metriche specifiche dell’azienda

Gestione clienti multi-tenant

GET /api/customers/dashboard/:businessId

Ottieni i dati della dashboard cliente per un’azienda specifica

GET /api/customers/analytics/:businessId

Ottieni analisi aziendali per un cliente specifico

GET /api/customers/integration/:businessId/status

Verifica lo stato dell’integrazione per l’azienda

🎯 Pilota UnityXpressions

GET /api/unityxpressions/dashboard

Dati della dashboard pilota UnityXpressions

GET /api/pilot/metrics/realtime

Metriche pilota in tempo reale

GET /api/pilot/feedback/recent

Feedback clienti recenti, pilota

🎓 Formazione e apprendimento

POST /api/training/unityxpressions/analyze

Analizza il business UnityXpressions per l'addestramento

POST /api/training/unityxpressions/quick-setup

Onboarding rapido per UnityXpressions

GET /api/learning/health

Stato di salute del motore di apprendimento

🔌 Installazione del widget

Aggiungi Bob a qualsiasi sito web con un singolo tag script. Dopo l'onboarding, il codice di embed del widget è disponibile nel Portale Clienti sotto Configurazione widget.

<!-- Canonical tenant-scoped bundle from Customer Portal Widget Setup (no API key in HTML). -->
<script src="https://YOUR_OFFICE_HOST/widget/YOUR_TENANT_UUID/widget.js" async></script>

GET /api/customer-portal/widget-code

Restituisce codice embed pronto. Richiesto JWT cliente.

🎭 Personalizzazione della persona

Le controllano tono, nome, istruzioni. Persona predefinita; personalizzi da admin o API.

GET /api/personas/:tenantId

Elenca tutte le personas per un tenant.

POST /api/personas/:tenantId

Crea una nuova persona. Corpo: { name, description, tone, systemPrompt }

PUT /api/personas/:tenantId/:personaId

Aggiorna tono, istruzioni o nome di una persona esistente.

💰 Piani e prezzi

Published pricebook is the source of truth. Use the APIs below for live numbers; this table matches pricebook-seed V1 (si aggiorna quando pubblichi una nuova versione).

Funzione	Base	Pro (piano)	Enterprise
Prezzo di listino (USD/mese)	$79	$249	$899
Crediti AI inclusi / mese	15,000	75,000	250,000
Posti del team	Fino a 3	Fino a 10	Illimitato
Integrazioni standard (incluse)	1	3	10
Supporto	Email	Priorità	Dedicato

GET /api/pricing/marketing-cards

Schede piano per marketing e checkout (prezzi, crediti, stime) — dal listino. Nessun login.

GET /api/pricing/snapshot

Istantanea pubblica e sicura del listino prezzi (senza campi costi fornitore). Nessuna autenticazione richiesta.

🛠️ Esempi di integrazione

Usa il blocco che corrisponde al tuo scenario. Non copiare l'esempio admin nell'HTML marketing anonimo.

Stessa origine, accesso anonimo (pubblico).

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    session_id: sessionId,
    message: userMessage,
    business_id: 'office16852-platform'
  })
});
const data = await response.json();

Widget cross-origin

const response = await fetch('https://office16852.com/api/widget/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Widget-Key': 'pk_live_...',
    'Origin': 'https://your-customer-site.com'
  },
  body: JSON.stringify({ session_id: sessionId, message: userMessage })
});

Solo admin autenticato (Bearer)

// JavaScript — requires logged-in admin / Mission Control (Bearer)
const response = await fetch('/api/chat/message', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    session_id: sessionId,
    message: userMessage
  })
});
const data = await response.json();

// Python — authenticated only
import requests
response = requests.post(
    'https://office16852.com/api/chat/message',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    },
    json={ 'session_id': session_id, 'message': user_message }
)

Office 168/52 developer documentation