Documentazione tecnica per integrare Xeora con sistemi esterni, bot e automazioni. Per una guida machine-readable e aggiornata usa GET /config/info.
/tenants/:tenant_id/... con la tua API Key. Le route di discovery sono pubbliche, mentre le operazioni su dati richiedono autenticazione.
La maggior parte delle route operative richiede una API Key tenant. I flussi OTP cliente/prenotazione/ordine usati da chat e clienti richiedono comunque la API Key tenant dell’agente, oltre all’OTP: l’OTP viene inviato/accettato solo se email e dati tenant corrispondono.
Includi la API Key nell’header HTTP:
Authorization: Bearer ***Nota: il parametro query ?api_key=*** non è più supportato per sicurezza
https://xeora.it/wp-json/xeora/v1/Per nuove integrazioni esterne, agenti, bot e automazioni usa le route tenant-scoped:
/wp-json/xeora/v1/tenants/:tenant_id/...Queste route includono sempre il tenant nel percorso e sono il modello consigliato perché rendono esplicito quale business/tenant sta usando l’integrazione.
Le route legacy come /wp-json/xeora/v1/bookings/... restano disponibili per compatibilità, ma non sono il punto di ingresso consigliato per nuove integrazioni.
Lista tenant attivi. Richiede autenticazione, tutti i tenant accessibili alla chiave.
{
"success": true,
"tenants": [
{ "id": 1, "business_name": "Il Mio Business", "slug": "il-mio-business", "status": "active" }
],
"count": 1
}Lista servizi attivi per tenant. Supporta paginazione.
| Parametro | Tipo | Descrizione |
|---|---|---|
| service_id | opzionale | Filtra un singolo servizio tramite parametro query. |
| per_page | opzionale | Risultati per pagina (max 100). |
| page | opzionale | Numero pagina. |
Il totale reale è total_items, non count. Se count < total_items, recupera le pagine successive o usa per_page=100.
Campi personalizzati del servizio.
Scaglioni di prezzo del servizio.
Prodotti extra associati al servizio.
Recensioni del servizio.
Lista staff attivo. Accetta service_id per filtrare gli operatori compatibili con un servizio.
Slot disponibili per una data.
| Parametro | Tipo | Descrizione |
|---|---|---|
| date | richiesto | YYYY-MM-DD |
| service_id | richiesto | ID servizio |
| staff_id | richiesto per hourly | ID staff per servizi orari. |
| duration_minutes | opzionale | Durata custom in minuti. |
Disponibilità mensile per servizi daily.
| Parametro | Tipo | Descrizione |
|---|---|---|
| service_id | richiesto | ID servizio |
| year | richiesto | Anno |
| month | richiesto | Mese 1-12 |
| staff_id | opzionale | ID staff, utile per servizi hourly. |
Giorni chiusi in un mese. Non compatibile con tutti gli orari; verifica il tipo di servizio prima di usarlo come regola.
Crea una prenotazione. Per servizi hourly servono date/time e staff_id; per daily servono start_date/end_date o days.
{
"service_id": 15,
"staff_id": 1,
"booking_type": "daily",
"start_date": "2026-06-15",
"end_date": "2026-06-17",
"customer_name": "Mario Rossi",
"customer_email": "mario@example.com",
"customer_phone": "+39 333 1234567",
"customer_notes": "Nota opzionale",
"payment_provider": "paypal",
"products": [
{ "id": 5, "quantity": 2 }
]
}{
"success": true,
"message": "Prenotazione creata. Link pagamento: ...",
"booking_id": 184,
"appointment_id": 184,
"status": "pending",
"payment_status": "pending_paypal",
"payment_method": "paypal",
"total_price": 350.00,
"amount_now": 350.00,
"approval_url": "https://www.sandbox.paypal.com/checkoutnow?token=***",
"paypal_order_id": "5O190127TN364715T"
}approval_url per PayPal o checkout_url per Stripe. Non usare GET /payments/:booking_id/status per recuperare il link: serve solo al polling dello stato pagamento.Dettaglio prenotazione: richiede API Key tenant + OTP prenotazione.
Richiede API Key tenant. Invia OTP alla email della prenotazione solo se email e prenotazione corrispondono.
{ "customer_email": "mario@example.com" }Aggiorna prenotazione. Richiede customer_email della prenotazione + otp.
Cancella prenotazione. Richiede customer_email della prenotazione + otp.
POST /tenants/:tenant_id/bookings/:booking_id/request-otp, poi invia customer_email + otp nella chiamata di update/cancel.Polling stato pagamento prenotazione. Richiede API Key tenant + OTP prenotazione. Non restituisce link pagamento.
Polling stato pagamento ordine ticketing/evento. Richiede API Key tenant + OTP ordine. Usa order_id, non event_id.
Provider pagamento disponibili per tenant.
Crea o recupera cliente. In caso di nuovo cliente invia password di accesso e welcome email.
Richiede API Key tenant. Invia OTP cliente via email solo se l'email ha biglietti o prenotazioni nel tenant. Rate-limited per evitare spam.
Verifica OTP cliente solo se email e tenant corrispondono a dati reali del cliente.
{ "email": "mario@example.com", "otp": "123456" }Biglietti cliente tramite API Key tenant + email + OTP valido e non scaduto.
Prenotazioni cliente tramite API Key tenant + email + OTP valido e non scaduto.
Lista eventi disponibili.
Dettaglio evento e tipi di biglietto.
Biglietti disponibili per evento.
Statistiche di vendita dell’evento.
Inizia pagamento biglietti evento.
Crea ordine biglietti. Richiede line_items con id_tipo_biglietto e quantità.
{
"event_id": 12,
"customer_name": "Mario Rossi",
"customer_email": "mario@example.com",
"customer_phone": "+39 333 1234567",
"line_items": [
{ "ticket_type_id": 4, "quantity": 2 }
],
"payment_provider": "stripe"
}Dettaglio ordine: richiede API Key tenant + OTP ordine.
Completa ordine dopo pagamento esterno/manuale.
Cancella ordine. Richiede API Key tenant, email dell'ordine + OTP valido.
Statistiche ordini.
Lista biglietti del tenant.
Dettaglio biglietto: richiede API Key tenant + OTP ordine. Per chat/WhatsApp preferisci il flusso OTP ordine.
Dettaglio biglietto tramite numero: richiede API Key tenant + OTP ordine. Il numero da solo non basta.
Recupera QR code biglietto: richiede API Key tenant + OTP ordine. Per chat/WhatsApp preferisci il flusso OTP ordine.
Valida biglietto per check-in.
Cancella biglietto solo con customer_email dell'ordine e OTP ordine valido.
{
"customer_email": "mario@example.com",
"otp": "123456"
}Statistiche biglietti.
Crea prodotto extra per il tenant. Richiede tenant_id, name e price.
Configurazione webhook agente.
Registra URL webhook.
{
"webhook_url": "https://il-tuo-server.com/webhook",
"webhook_secret": "segreto-condiviso",
"enabled": true
}Rimuove webhook registrato.
Callback payment provider verso Xeora. Pubblico, ma deve contenere un evento Stripe firmato o un evento PayPal verificabile.
Statistiche sui limiti commerciali di creazione prenotazioni/ticket. Le chiamate di discovery, availability e check non consumano questo limite.
Informazioni API e guida workflow. Endpoint pubblico, non richiede autenticazione.
curl -X POST https://xeora.it/wp-json/xeora/v1/tenants/1/bookings \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{
"service_id": 15,
"booking_type": "daily",
"start_date": "2026-06-15",
"end_date": "2026-06-17",
"customer_name": "Mario Rossi",
"customer_email": "mario@example.com",
"customer_phone": "+39 333 1234567",
"payment_provider": "paypal"
}'const response = await fetch('https://xeora.it/wp-json/xeora/v1/tenants/1/bookings', {
method: 'POST',
headers: {
'Authorization': 'Bearer...KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
service_id: 15,
booking_type: 'daily',
start_date: '2026-06-15',
end_date: '2026-06-17',
customer_name: 'Mario Rossi',
customer_email: 'mario@example.com',
customer_phone: '+39 333 1234567',
payment_provider: 'paypal'
})
});
const data = await response.json();
// PayPal
if (data.approval_url) {
window.location.href = data.approval_url;
}
// Stripe
if (data.checkout_url) {
window.location.href = data.checkout_url;
}curl -X POST https://xeora.it/wp-json/xeora/v1/tenants/1/orders \
-H "Authorization: Bearer *** \
-H "Content-Type: application/json" \
-d '{
"event_id": 12,
"customer_name": "Mario Rossi",
"customer_email": "mario@example.com",
"customer_phone": "+39 333 1234567",
"line_items": [
{ "ticket_type_id": 4, "quantity": 2 }
],
"payment_provider": "stripe"
}'Authorization: Bearer ***.