Skip to main content

API Tavoli e Prenotazioni

Panoramica​

La gestione tavoli e prenotazioni e distribuita su 5 servizi Moleculer, tutti basati su TenantDbMixin per l'isolamento multi-tenant:

ServizioCollectionDescrizione
tavolotavoliCRUD tavoli, stati, locking, QR code
salasaleCRUD sale (room)
prenotazioneprenotazioniPrenotazioni con flusso completo
bookingsbookingsBatch upload prenotazioni (sync)
capacityproduction_categories / slot_configSlot e capacita

Tutti gli endpoint richiedono autenticazione JWT. Il tenantId viene estratto automaticamente dal token.

Endpoint Tavoli​

Elenco Tavoli​

curl -X GET "https://api.example.com/api/tavoli?salaId=<SALA_ID>&attivo=true" \
  -H "Authorization: Bearer <JWT_TOKEN>"

Parametri opzionali: attivo (boolean), capacitaMin (numero minimo coperti), posizione, salaId. La risposta include alias inglesi per compatibilita con waiter_ui (id, name, seats, status, roomId).

Aggiornamento Stato Tavolo​

curl -X PUT "https://api.example.com/api/tavoli/<TABLE_ID>/status" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "occupied",
    "orderId": "<ORDER_ID>",
    "pax": 4,
    "totalAmount": 0
  }'

Valori consentiti: free, occupied, open, dirty, reserved, payment_pending. Ogni cambio stato pubblica un messaggio NATS su tenant.{tenantId}.restaurant.tables.status per la sincronizzazione real-time.

Locking Tavolo​

# Acquisire lock
curl -X POST "https://api.example.com/api/tavoli/<TABLE_ID>/lock" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{ "deviceId": "device-001", "operatorName": "Mario", "ttl": 300 }'

# Rilasciare lock
curl -X POST "https://api.example.com/api/tavoli/<TABLE_ID>/unlock" \
  -d '{ "deviceId": "device-001" }'

Il lock usa Redis con TTL configurabile (default 300 secondi). Solo il device che detiene il lock puo rilasciarlo. L'admin puo forzare il rilascio con DELETE /<TABLE_ID>/lock.

Verifica Disponibilita​

curl -X POST "https://api.example.com/api/tavoli/verifica-disponibilita" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "dataOra": "2026-03-17T20:00:00",
    "numeroPersone": 4,
    "durataMediaPasto": 90
  }'

Incrocia tavoli attivi con capacita sufficiente e prenotazioni esistenti nella fascia oraria. Restituisce elenco tavoli disponibili con capacita totale.

Endpoint Sale​

CRUD Sale​

# Lista sale
curl -X GET "https://api.example.com/api/sale" \
  -H "Authorization: Bearer <JWT_TOKEN>"

# Crea sala
curl -X POST "https://api.example.com/api/sale" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "codice": "TERRAZZA",
    "descrizione": "Terrazza panoramica",
    "width": 1000,
    "height": 800
  }'

Il codice viene convertito in maiuscolo. Dimensioni default: 800x600. La risposta include alias inglesi (name, width, height) per waiter_ui.

Endpoint Prenotazioni​

Creazione Prenotazione​

curl -X POST "https://api.example.com/api/prenotazioni" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "covers": 4,
    "bookingDate": "2026-03-17T20:00:00",
    "customerName": "Mario Rossi",
    "customerPhone": "+39 333 1234567",
    "tableIds": ["<TABLE_ID>"],
    "notes": "Allergia al glutine",
    "state": "confermata"
  }'

Il servizio accetta parametri sia in inglese (covers, bookingDate, customerName) sia in italiano (numeroPersone, dataOra, cliente). Genera un codice prenotazione univoco di 6 caratteri. Pubblica un messaggio NATS su tenant.{tenantId}.restaurant.bookings.created.

Cambio Stato​

# Conferma
curl -X POST "https://api.example.com/api/prenotazioni/<ID>/conferma"

# Annullamento
curl -X POST "https://api.example.com/api/prenotazioni/<ID>/annulla" \
  -d '{ "motivo": "Cliente ha chiamato per disdire" }'

# Cambio stato generico
curl -X POST "https://api.example.com/api/prenotazioni/<ID>/stato" \
  -d '{ "nuovoStato": "no_show" }'

Stati validi: pending, confermata, caparra_pagata, completata, annullata, no_show.

Sincronizzazione​

# Sync down (delta)
curl -X GET "https://api.example.com/api/prenotazioni/sync?modifiedSince=2026-03-17T08:00:00Z"

# Batch upload
curl -X POST "https://api.example.com/api/prenotazioni/batch" \
  -d '{ "items": [{ "covers": 2, "bookingDate": "...", "customerName": "..." }] }'

L'endpoint syncDown supporta filtri dal/al (range date) e modifiedSince (delta sync). Default: prenotazioni degli ultimi 7 giorni.

Eventi Realtime​

I servizi tavoli e prenotazioni pubblicano eventi NATS per la sincronizzazione:

  • tenant.{tenantId}.restaurant.tables.status -- Cambio stato tavolo
  • tenant.{tenantId}.restaurant.bookings.created -- Nuova prenotazione
  • tenant.{tenantId}.restaurant.bookings.updated -- Prenotazione modificata
  • tenant.{tenantId}.restaurant.bookings.cancelled -- Prenotazione annullata

FAQ​

D: Qual e la differenza tra bookings e prenotazione? R: prenotazione e il servizio principale con CRUD completo, flusso stati e sincronizzazione NATS. bookings e un servizio semplificato per batch upload dal POS (legacy).

D: Come funziona la riconciliazione tavoli/prenotazioni? R: L'azione tavolo.verificaDisponibilita interroga prenotazione.getPrenotazioniGiorno per ottenere le prenotazioni del giorno e calcolare la sovrapposizione temporale.

D: I parametri italiani sono deprecati? R: No, sono mantenuti per retrocompatibilita. I parametri inglesi hanno priorita. Entrambi i formati sono salvati nel documento per garantire la compatibilita con tutte le app.

Vedi Anche​

Questa pagina ti è stata utile?