# Placeful — llms-full.txt



> Complete public corpus. Index version: https://placeful-app.com/llms.txt



## Home

# Placeful

> Piattaforma di prenotazioni, comande e gestione del locale

Placeful è la piattaforma di prenotazioni, comande e gestione del locale per le attività: pubblica eventi prenotabili, incorpora il calendario nel tuo sito, gestisci menu con ordini al tavolo e controlla prenotazioni, personale e pagamenti da un’unica dashboard.

## Caratteristiche

- **Widget di prenotazione integrabile** — Aggiungi il calendario delle prenotazioni a qualsiasi sito web con un semplice snippet — i clienti prenotano senza lasciare il tuo sito.
- **Eventi e disponibilità** — Crea tipi di evento, aree, mappe dei posti e fasce orarie. Tieni sotto controllo capacità, prenotazioni e liste d’attesa dalla dashboard.
- **Pagamenti online** — Incassa in sicurezza con Stripe per prenotazioni e comande, con politiche di rimborso per attività.
- **Menu e conti aperti** — Crea menu con tracciamento delle giacenze, apri conti al tavolo dal registratore e incassa per comanda — contanti, carta o Stripe — poi stampa gli scontrini e chiudi la giornata con il rapporto Z del cassetto.
- **Ordini QR degli ospiti** — Gli ospiti inquadrano il QR del tavolo, sfogliano il menu e ordinano o pagano da soli — con approvazione dello staff o in automatico.
- **Monitor cucina** — Un monitor cucina live instrada le pietanze alle postazioni con invio portate e ritmi di preparazione — inviate, in preparazione, pronte — in tempo reale.
- **App membri** — I membri hanno un’app installabile: prenotazioni, mappa posti, ordini autonomi e i propri ordini — con notifiche push.
- **Sincronizzazione con Google Calendar** — Collega Google Calendar per replicare le prenotazioni confermate sul tuo calendario e individuare subito i conflitti.
- **Notifiche automatiche** — Email di conferma, promemoria e cancellazione — più notifiche push sul dispositivo — tengono clienti e staff sincronizzati.
- **Gestione personale** — Turni, orari, attività, presenze, riepiloghi paghe e stanze voce stile walkie-talkie — più un portale self-service per lo staff.
- **Assistente AI e MCP** — Un assistente AI integrato risponde alle domande ed esegue azioni dopo conferma — gli agenti esterni si collegano via MCP.
- **Ruoli e permessi** — Ogni azienda ha il proprio spazio di lavoro con ruoli, permessi e fatturazione a consumo.

## Come funziona

1. **Crea la tua attività** — Registrati, configura il tuo spazio di lavoro e invita il team con ruoli e permessi.
2. **Pubblica eventi e disponibilità** — Definisci tipi di evento, aree e fasce orarie — capacità e prenotazioni si aggiornano in tempo reale.
3. **Condividi o incorpora** — Condividi il link di prenotazione o incorpora il calendario nel tuo sito. I clienti prenotano e pagano online.

## Domande frequenti

### Che cos’è Placeful?

Placeful è una piattaforma di prenotazioni, comande e gestione del locale. Le attività pubblicano eventi prenotabili, incorporano il calendario nel proprio sito, gestiscono menu con ordini al tavolo e controllano prenotazioni, personale e pagamenti da un’unica dashboard.

### Come prenotano i clienti?

I clienti scelgono data e fascia oraria sul calendario incorporato o sulla tua pagina pubblica di prenotazione, confermano con i propri dati e pagano online quando è previsto un prezzo. Le email di conferma e promemoria vengono inviate automaticamente. I membri possono anche usare l’app installabile per prenotazioni e comande.

### Gli ospiti possono ordinare al tavolo?

Sì. Gli ospiti inquadrano il QR del tavolo, sfogliano il menu e ordinano — con approvazione dello staff o in automatico. Le comande arrivano al monitor cucina in tempo reale e si possono pagare per conto.

### Posso incorporare il calendario delle prenotazioni nel mio sito?

Sì. Ogni attività dispone di un widget incorporabile: copia un breve snippet in qualsiasi sito web e il calendario delle prenotazioni appare nella pagina — i clienti prenotano senza lasciare il tuo sito.

### Come funzionano i pagamenti?

I pagamenti sono gestiti da Stripe. Ogni attività collega il proprio account Stripe e riceve i pagamenti direttamente — per prenotazioni e comande — con politiche di rimborso personalizzate.

### Si sincronizza con Google Calendar?

Sì. Collega Google Calendar per vedere le prenotazioni confermate sul tuo calendario e individuare i conflitti a colpo d’occhio.

### Esiste un piano gratuito?

Puoi creare un account gratuito, pubblicare il primo evento e incorporare il calendario nel tuo sito in pochi minuti.


---
> Source: https://placeful-app.com/


## Pricing

# Prezzi — Placeful

Prezzi di Placeful: piano gratuito e abbonamenti mensili o annuali con prenotazioni incluse, zero commissioni sulle tue prenotazioni, e piani superiori con comande, personale, magazzino e API.

| Piano | Mensile | Annuale | Prenotazioni | Commissioni |
|---|---|---|---|---|
| Gratuito | €0 | €0 | 50 | Nessuna tariffa per prenotazione |
| Starter | €29,00 | €290,00 | 150 | 150 prenotazioni incluse, poi €0,20 per prenotazione |
| Pro | €59,00 | €590,00 | 500 | 500 prenotazioni incluse, poi €0,15 per prenotazione |
| Business | €119,00 | €1.190,00 | ∞ | Nessuna tariffa per prenotazione |

---
> Source: https://placeful-app.com/pricing


## Docs — getting-started/overview

# Panoramica

# Panoramica

Benvenuto in **Placeful** — piattaforma multi-tenant per gestire eventi, posti, fasce orarie e prenotazioni con pagamenti Stripe, widget di prenotazione embeddabile e accesso basato sui ruoli per i team aziendali.

## Cosa puoi fare

- **Le aziende** sono il tenant. Ogni azienda possiede eventi, tipi evento, aree, posti, orari e prenotazioni. Gli utenti appartengono a una o più aziende con un ruolo: `owner`, `admin`, `manager`, `member`.
- **Gli eventi** hanno una data (eventualmente multi-giorno), una finestra di prenotazione opzionale e una capacità. Le prenotazioni si fanno sugli eventi — a meno che l'azienda giri in modello di prenotazione **areas**, dove i clienti prenotano un'area direttamente per una finestra oraria (un'azienda a eventi può anche consentire entrambi — vedi *Prenotazione aree*).
- **Mappa del locale e tavoli** — lo staff disegna le aree e posiziona i tavoli fisici su una pianta visuale (`/venue/map`); ogni prenotazione può essere fissata ai tavoli — anche su più tavoli — dalla [mappa posti](/docs/venue/seating) (`/venue/seating`), dall'editor prenotazione o dal planner.
- **Chiusure** — regole (intervalli di date, ricorrenze settimanali, fasce orarie) che bloccano locale, area o tavolo (`/availability/calendar`).
- **Planner** — griglia mensile su `/admin/planner` che dipinge chiusure, prenotazioni, eventi e spostamenti tavoli per giorno.
- **Le prenotazioni** riservano capacità (posti o slot orari) e attraversano una macchina a stati: `Pending` → `Free` / `Paid` / `Added` (gli stati confermati) → `Cancelled`, `Failed`, `Expired`, oppure la catena rimborsi `RefundPending` → `Refunding` → `Refunded` / `RefundFailed`. Un codice promo inviato parcheggia la prenotazione in `PromoPending` finché lo staff la approva o rifiuta.
- **Il widget** è un calendario di prenotazione embeddabile (iframe + snippet script) generato per azienda per siti esterni.
- **Stripe** gestisce checkout, account connessi per azienda (payout più fee applicativa della piattaforma), rimborsi e fatturazione degli abbonamenti ai pacchetti.
- **Waitlist** — sugli eventi con `waitlist_enabled`, i clienti a sold-out possono mettersi in coda e vengono promossi FIFO quando si libera un posto.
- **Comande** — menu con categorie, modificatori, portate e giacenze opzionali; conti live sulla comanda staff, un kitchen board con invio portate e ritmi di preparazione, auto-ordine QR per gli ospiti, scontrini stampabili e un cassetto cassa giornaliero con chiusura Z-report (`/orders`).
- **Personale** — dipendenti con organico, contratti, turni, attività, timbrature, ferie e riepiloghi buste paga; un portale self-service e stanze radio voce stile walkie-talkie per la sala.
- **App membri** — una PWA installabile su `/m`: prenotazioni di oggi, mappa posti, auto-ordine, kitchen board e notifiche push.
- **Google Calendar** — lo staff può replicare le prenotazioni confermate sul proprio calendario e vedere i conflitti con i blocchi occupati.
- **Assistente AI** — un assistente in-app (pulsante sparkle, oppure **Ctrl+K** → *Chiedi all'assistente* nella command palette) risponde a domande sui dati della tua azienda e su questa documentazione, propone modifiche da confermare e ti porta ai record — vedi [Assistente AI](/docs/getting-started/assistant).

## Ruoli in sintesi

| Ruolo | Vede | Può fare |
|-------|------|----------|
| Owner | Tutto nella sua azienda | Controllo completo: fatturazione, membri, account Stripe, eliminazione azienda |
| Admin | Risorse operative | Gestisce eventi, prenotazioni (incl. rimborsi), membri — non fatturazione né creazione/eliminazione azienda |
| Manager | Operatività quotidiana | Crea/modifica eventi, tipi evento, posti, orari, prenotazioni — no aree, no rimborsi, no gestione membri |
| Member | Proprio contesto | Vede, crea e modifica le proprie prenotazioni |
| Employee | Superfici di sala + portale | Comanda e kitchen board, segni di servizio sulle prenotazioni (seated/completed/no-show), radio voce, propri turni/timbrature/ferie — no gestione prenotazioni o soldi |

Gli sviluppatori (staff piattaforma con flag `developer`) bypassano tutti i controlli di ruolo.

## Prossimi passi

- [Fai la prima prenotazione](/docs/getting-started/first-booking)
- Le guide per lo staff (*Crea un evento*, *Prezzi*, *Widget*, …) compaiono automaticamente nell'hub quando il tuo ruolo lo consente.


---
> Source: https://placeful-app.com/docs/getting-started/overview


## Docs — getting-started/first-booking

# La tua prima prenotazione

# La prima prenotazione

Come prenota un cliente un posto su un evento: dal widget alla conferma.

## 1. Apri il widget

Il cliente raggiunge il widget in due modi:

- **Embedded** nel sito dell'azienda tramite lo snippet generato, oppure
- **Direttamente** su `/widget/calendar` (l'URL caricato dall'iframe dello snippet).

Il widget elenca gli eventi pubblicati imminenti dell'azienda dentro la loro finestra di prenotazione. (Nell'app staff, il link **Prenotazioni** in nav apre il gestore prenotazioni — non il widget.)

## 2. Scegli un evento

Ogni evento mostra data e disponibilità. Il conteggio esatto dei posti rimasti appare solo quando la disponibilità scende a `show_bookable_threshold` o sotto. Gli eventi sold-out offrono la **waitlist** se l'evento ha `waitlist_enabled`.

## 3. Scegli posti / orario

Dipende dal `booking_mode` dell'evento:

- **Fasce fisse** — scegli un posto in un'area, poi uno slot orario (capacità `seat_time`).
- **Flexible window** — scegli numero di persone e finestra oraria. Se l'evento ha posti, il cliente sceglie anche un posto (nessuno slot orario fisso); senza posti la finestra si prenota sull'evento stesso.

Se il prenotabile espone più righe di prezzo (es. `adult`, `child`), il cliente imposta una quantità per prezzo; il totale persone deve coincidere con la somma delle quantità per prezzo.

## 4. Conferma e paga

- **Prenotazioni gratuite** (totale `0`) saltano il pagamento e si confermano subito — stato `Free`.
- **Codici promo** — il campo "Ho un codice promo" parcheggia la prenotazione in `PromoPending` per la revisione staff invece di addebitare la carta. I codici approvati confermano la prenotazione (copertura piena) o inviano al cliente un link per pagare il restante; quelli rifiutati ricadono su annullamento o pagamento pieno, a scelta dello staff.
- **Prenotazioni a pagamento** vanno a Stripe Checkout sull'account connesso dell'azienda. Un hold di capacità (`booking.hold_minutes`, default 30 min) riserva il posto durante il pagamento; `booking.max_hold_lifetime_minutes` (default 90 min) è il limite massimo dell'intero flusso.
- Lo sweeper `bookings:expire-holds` (ogni 5 min) scade gli hold decaduti — e consolida le sessioni Checkout che Stripe ha già incassato, così un pagamento lento si conferma comunque invece di perdersi.

## 5. Fine

La pagina finale (`/booking/{booking}/{outcome}/finish`) mostra il codice prenotazione e il download `.ics` per il calendario. Le email di promemoria partono 24 h e 1 h prima dell'inizio evento (`bookings:send-reminders`, ogni ora).

> Evento pieno? Con `waitlist_enabled` attivo i clienti entrano in coda e ricevono un link di offerta quando si libera un posto.


---
> Source: https://placeful-app.com/docs/getting-started/first-booking


## Docs — bookings/refunds

# Rimborsi

# Rimborsi

I rimborsi restituiscono denaro dopo che una prenotazione è stata pagata. Il flusso è in due passi — **richiesta** e poi **approvazione** — così un rimborso non è mai silenzioso.

## Chi può rimborsare

`bookings.refund` — concesso di default a **owner** e **admin**. Membri e manager non possono rimborsare. Approvare richiede inoltre di essere autenticati con lo stesso permesso — il link firmato da solo non basta.

## Richiedere un rimborso

1. Apri l'editor della prenotazione (`/booking/{booking}/-editor`).
2. Clicca **Rimborso**, scegli l'importo e inserisci una motivazione.
3. La prenotazione passa a `RefundPending`; la riga `Financial` registra `refund_amount`, `refund_reason`, `refund_requested_by` / `refund_requested_at` e lo stato `pending_refund`.
4. L'**owner** aziendale riceve via email una `BookingRefundRequestedNotification` con il link di approvazione firmato. Anche annullare una prenotazione pagata può creare una richiesta di rimborso e notifica il prenotante (`BookingCancellationRefundRequestedNotification`).

## Approvare un rimborso

Il link di approvazione è **firmato** (middleware `signed`):

```
/bookings/{booking}/refunds/{financial}/approve?signature=...
```

- GET mostra una pagina di conferma con motivazione e importi; POST approva.
- `ApproveBookingRefund` emette il rimborso Stripe sull'account connesso (con `refund_application_fee`, così la fee piattaforma viene restituita proporzionalmente), porta la prenotazione da `Refunding` a `Refunded`, registra `refunded_amount`/`refunded_at` e notifica il prenotante (`BookingRefundApprovedNotification`).
- Un fallimento Stripe imposta `RefundFailed` con `refund_failed_at` + `refund_failure_reason` e lancia `BookingRefundFailed` — lo staff può riprovare manualmente.
- I rimborsi parziali sono supportati: `refund_amount` può essere sotto il totale incassato; `refunded_amount` traccia quanto è stato effettivamente restituito.

## Pagamenti tardivi

Un pagamento Stripe che arriva **dopo** che la prenotazione è già scaduta o annullata viene scritto nel registro `late_payments` e l'owner viene notificato (`LatePaymentReceivedNotification`). `BOOKING_AUTO_REFUND_LATE_PAYMENTS` (default **true**) lo rimborsa automaticamente — impostalo a `false` per trattenere il denaro e riconciliare a mano. È un effetto reale sul denaro.


---
> Source: https://placeful-app.com/docs/bookings/refunds


## Docs — bookings/waitlist

# Waitlist

# Waitlist

Quando un prenotabile è sold-out e l'evento ha `waitlist_enabled`, i clienti possono entrare in lista d'attesa direttamente dal widget. La promozione è FIFO per prenotabile (per `waitlist_entries.created_at`).

## Come funziona

1. Il cliente entra in lista → viene creata una `WaitlistEntry` in `waiting`.
2. Si libera capacità (prenotazione annullata, hold scaduto, prenotazione modificata) → `OfferSpotOnCapacity` promuove la prossima voce in attesa: stato `offered`, un `offer_token` da 64 caratteri e `expires_at` = ora + **24 h** (`OfferSpotOnCapacity::DEFAULT_OFFER_TTL_HOURS`). Il cliente riceve una `WaitlistSpotOfferedNotification` con il link `/waitlist/claim/{token}`.
3. Il cliente apre il link — deve essere loggato **come l'utente della voce** — e clicca **Reclama**: stato `claimed`, poi redirect alla pagina di riepilogo prenotazione pre-compilata con prenotabile e numero di persone.
4. Completare quella prenotazione porta la voce a `fulfilled` (il `waitlist_entry_id` viene propagato; un listener su `BookingCreated` fa da rete di sicurezza).
5. **Declina** → `cancelled` e la prossima voce in attesa viene promossa subito.
6. `waitlist:expire-claims` (ogni 5 min) scade le voci offered/claimed stantie e promuove la prossima in coda.

## Stati

```
waiting → offered → claimed → fulfilled
            ↘ expired   ↘ cancelled (declinata)
```

## Due tipi di voce

`waitlist_entries.kind` divide la tabella in due cicli di vita che non si mescolano mai:

- **`capacity`** (default) — il flusso sold-out qui sopra: utenti con account in coda per capacità liberata, promozione FIFO, link di reclamo coperto da token **e** utente autenticato corrispondente.
- **`walkin`** — la [coda alla porta](/docs/venue/door-ops): lo staff prende i gruppi walk-in in giornata su un'Area, l'ospite è una coppia nome/telefono (nessun account), l'offerta parte via SMS/mail e la pagina di reclamo è a solo token. Le voci walk-in non promuovono mai in automatico e vengono accomodate a mano — vedi door ops.

## Permessi

Owner, admin e manager vedono lo stato della waitlist sul widget e nel flusso di prenotazione. Entrare in lista e reclamare sono azioni del cliente — il link di reclamo è coperto dal token a 64 caratteri **e** dall'utente autenticato corrispondente, nessun ruolo staff necessario. Le scritture sulla coda walk-in richiedono `bookings.seat`.


---
> Source: https://placeful-app.com/docs/bookings/waitlist


## Docs — bookings/custom-fields

# Campi personalizzati di prenotazione

# Campi personalizzati di prenotazione

Chiedi ai clienti ciò che il modulo standard non copre — intolleranze, ragione sociale, note di arrivo — agganciando campi personalizzati a un **evento** o a un'**area**. Le risposte sono salvate sulla prenotazione e visibili allo staff nel dettaglio.

## Dove si definiscono

- **Editor evento → Campi personalizzati** — si applica a ogni prenotazione di quell'evento.
- **Editor area → Campi personalizzati** — si applica alle prenotazioni senza evento di quell'area.

Ogni campo ha etichetta, chiave tecnica, tipo, un placeholder opzionale e un ordine.

## Tipi di campo

| Tipo | Input reso |
|---|---|
| `text` | testo su riga singola (max 255 caratteri) |
| `textarea` | testo multilinea (max 5000 caratteri) |
| `select` | menu a tendina — richiede un'etichetta per riga |
| `checkbox` | toggle sì/no (accettato/non accettato) |
| `date` | selezione data (YYYY-MM-DD) |
| `number` | input numerico (interi o decimali) |

## Quando viene chiesto il campo

Ogni campo ha una **fase di raccolta**:

- **Prenotazione** — chiesto nella pagina di conferma pubblica, dentro il flusso di prenotazione. I campi in fase di prenotazione possono essere **obbligatori**: il cliente non può confermare senza rispondere.
- **Post-prenotazione** — chiesto dopo la conferma (pagina di conferma e follow-up). I campi post-prenotazione sono sempre opzionali — non possono mai bloccare una prenotazione.

## Risposte

Le risposte sono salvate nella revisione del dettaglio prenotazione come `{chiave: {etichetta, valore}}` — modificare o eliminare un campo non cancella le risposte già raccolte, e lo storico delle revisioni conserva i valori precedenti. Lo staff vede le risposte nel dettaglio prenotazione; fanno parte anche degli export.

## Limiti e regole

- I campi sono per singolo prenotabile: duplicare un evento non implica duplicarne i campi — ricreali sul nuovo evento o sulla nuova area.
- I campi `select` richiedono almeno un'opzione; liste di opzioni vuote vengono rifiutate.
- Mantieni stabili le chiavi: la chiave è l'identificatore di archiviazione, quindi rinominarla apre un nuovo flusso di risposte.


---
> Source: https://placeful-app.com/docs/bookings/custom-fields


## Docs — orders/guest-ordering

# Ordini QR degli ospiti

# Ordini QR degli ospiti e impostazioni

Gli ospiti possono ordinare dal proprio telefono scansionando il **QR del tavolo** — niente account, niente app da installare. Tutto il flusso si configura da `/orders/settings`.

## Modalità di ordinazione

`orders_mode` decide cosa fa davvero il telefono dell'ospite:

| Modalità | Esperienza ospite |
|---|---|
| **Chiama cameriere** | Il telefono segnala solo il tavolo — lo staff prende la comanda di persona. |
| **Lista condivisa** | Gli ospiti compongono una selezione; il cameriere la vede e la conferma in righe reali. |
| **Con approvazione** | Gli ospiti inviano righe vere; restano `queued` sul [monitor cucina](/docs/orders/kitchen-board) finché lo staff le approva. |
| **Diretta in cucina** | Le righe ospiti partono immediatamente — nessun checkpoint umano. |

L'interruttore **QR ospiti** (`orders_guest_qr`) accende o spegne l'intero canale ospite. Quando è spento il QR apre comunque il menu ma nulla può essere inviato.

## Sospendere gli ordini

**Sospendi gli ordini online** (`orders_paused`) nelle impostazioni ordini blocca temporaneamente i nuovi ordini QR, dei membri e della vetrina senza cambiare la modalità di ordinazione. L'ordinazione parte attiva; disattiva la sospensione per riprenderla.

I menu restano visibili, i carrelli restano intatti e le pagine aperte si aggiornano quando cambia la sospensione. Ogni nuovo invio verifica anche il valore attuale nel database: una pagina vecchia non può aggirare il blocco. Gli invii già accettati vengono riutilizzati senza duplicare le righe.

Gli ordini dello staff e degli aggregatori di consegna non sono interessati. Conti esistenti, preparazione, ritiro e pagamenti (anche i tentativi di pagamento anticipato) restano disponibili. La sospensione non modifica gli annunci sui marketplace esterni.

## QR dei tavoli

La pagina impostazioni elenca ogni tavolo con un QR stampabile che punta a `/o/t/{token}` — il token è una capability URL per tavolo: chiunque lo possiede apre la pagina di quel tavolo, quindi tratta le stampe come chiavi. **Ruota** genera un token nuovo e invalida quello stampato (QR perso/rubato, foto trapelata). L'auto-ordinazione dei membri nell'[app](/docs/app/member-app) usa lo stesso conto sotto al cofano.

## Impostazioni di cassa

- **Servizio** — punti base applicati sul subtotale (es. `1000` = 10 %), aggiunti al totale di ogni conto.
- **Mance** — campo mancia su ogni tranche di pagamento quando abilitato.

Gli ospiti possono pagare la loro parte online via Stripe Checkout quando il locale ha un account collegato — valgono le stesse divisioni della [comanda](/docs/orders/order-pad).

## Permessi

Le impostazioni ordini stanno dietro `companies.update` (permesso impostazioni locale). L'ordinazione lato staff segue i [permessi della comanda](/docs/orders/order-pad); gli ospiti non hanno bisogno di alcun account.


---
> Source: https://placeful-app.com/docs/orders/guest-ordering


## Docs — companies/stripe-connect

# Stripe Connect

# Stripe Connect

Stripe Connect permette a ogni azienda di ricevere payout sul proprio account Stripe mentre la piattaforma trattiene una commissione.

## Collegare un account

1. Vai su **Impostazioni azienda** → **Payments** → account Stripe (`/companies/{company}/stripe-accounts`).
2. Clicca **Onboard** (`POST /companies/{company}/stripe/onboard`) — redirige al flusso di onboarding Stripe.
3. Stripe torna su `stripe-accounts/{stripeAccount}/refresh`; la riga account salva `stripe_account_id`, `type`, `country` ed `email`. L'azione **Sync** (`POST stripe-accounts/{stripeAccount}/sync`) ri-scarica lo stato dell'account.

## Payout & commissioni

- I pagamenti sono **destination charge**: `transfer_data.destination` = account dell'azienda, `application_fee_amount` = fee flat + percentuale del package. I rimborsi passano `refund_application_fee` così la fee piattaforma viene restituita proporzionalmente.
- `app:stripe-sync-payouts` (giornaliero 03:15) sincronizza i totali pagati dalla storia payout Stripe; ogni riga `Financial` registra `payout_id` e `paid_out_at`.
- `app:stripe-sync-commissions` (giornaliero 03:00) riconcilia le fee Stripe totali (ciò che Stripe addebita alla piattaforma) per account connesso.

## Webhook

Tre endpoint pubblici — niente sessione/CSRF, verificati da firma Stripe:

- `POST /stripe/webhook` — payment intent, rimborsi, completamento checkout.
- `POST /stripe/connect-webhook` — eventi account connessi.
- `POST /stripe/billing-webhook` — ciclo di vita abbonamenti.

Tutti rate-limited dal limiter `stripe-webhook`: **1000 req/min per IP** (generoso apposta — Stripe riprova su 5xx e un checkout produce più eventi). Gli eventi bloccati in `processing_at` da oltre 5 minuti vengono recuperati ogni ora (`app:stripe-reap-stale-webhook-events`).

## Permessi

- `stripeaccounts.view` — vede gli account connessi (owner + admin).
- `stripeaccounts.create` / `stripeaccounts.update` — onboard, modifica e sync (owner di default).
- I pannelli embedded controllano inoltre `companies.update` / la policy `view` dell'account.


---
> Source: https://placeful-app.com/docs/companies/stripe-connect


## Docs — widget/embed-widget

# Embeddare il widget

# Widget di prenotazione embeddabile

Il widget di prenotazione è un iframe da incollare in qualsiasi sito esterno. Renderizza un calendario localizzato degli eventi **pubblicati** imminenti dell'azienda e gestisce l'intero flusso di prenotazione — inclusa waitlist e handoff widget-auth.

## Tre modi di integrazione

Apri **Impostazioni azienda → tab Widget prenotazioni** (`/companies/{company}/edit?tab=widget` — owner/admin). Scegli il percorso adatto alla piattaforma:

- **Condividi un link** — il link diretto di prenotazione (`/book/{company}`) funziona ovunque: pulsanti di navigazione, bio, email. I link per canale pre-taggano sorgente/medium UTM. Zero codice.
- **Script di una riga** *(predefinito)* — un solo tag `<script src="…/api/embed/snippet.js?public_key=bw_pk_…">`. Inserisce il pulsante di prenotazione dove lo incolli e carica il runtime da solo. Il clic apre il calendario come overlay. Richiede una pagina che esegua JavaScript — la maggior parte delle piattaforme lo fa.
- **Frame incorporato** — un tag `<iframe src="…/w/bw_pk_…">`. `/w/{public_key}` crea la sessione embed lato server e reindirizza a `/embed?token=…`, quindi non serve alcun JS nella pagina ospite — il formato che sopravvive ai CMS che rimuovono gli script (blocchi embed di Wix e Squarespace, piani gratuiti wordpress.com). Compromesso: il calendario appare incorporato nella pagina invece che come overlay. Con **Domini consentiti** configurati, l'URL `/w/` funziona solo dentro pagine di quei domini — aperto come link diretto (email, chat, host con `referrerpolicy="no-referrer"`) risponde "Widget non disponibile".
- **HTML avanzato** — il blocco originale `<button>` + `<script>` inline. Identico a ciò che le installazioni precedenti hanno già pubblicato, ma incorpora la selezione corrente nel markup: dopo aver cambiato filtri o stile va ricopiato (lo script di una riga serve sempre le opzioni salvate).

Le **guide per piattaforma** nella tab danno i passi per CMS (WordPress, Wix/Squarespace, Shopify, HTML personalizzato), e **Verifica il tuo embed** scarica l'URL di pagina che incolli e riporta se trova la tua public key, i runtime del widget o un link `/book/` — riservato ai gestori widget, con rate limit e difese contro richieste verso reti private.

Gli host che creano sessioni embed vengono ricordati (più recenti prima, max 20) e proposti come **suggerimenti** con un clic sopra la textarea dei domini auth consentiti — finiscono solo nella textarea; nulla persiste finché non salvi. Fidarsi automaticamente di un host visto non sarebbe sicuro, quindi l'aggiunta è sempre esplicita.

`generateWidgetSnippet()` crea la `WidgetIntegration` aziendale al primo uso (public key `bw_pk_…`, secret `bw_sk_…` — il secret non è mai usato lato client). I campi bottone si risolvono per-campo: evento → tipo evento → azienda → default `config/booking-widget.php`. Il livello azienda si modifica sotto **Avanzate → Stile predefinito bottone** — alimenta ogni bottone widget (prenotazioni, richieste, voucher). La pagina welcome della dashboard renderizza il bottone live quando l'azienda non ha ancora prenotazioni.

## oEmbed

Le pagine `/book/{company}` e `/book/{company}/{eventType}` pubblicizzano `GET /oembed?url=…` via `<link rel="alternate" type="application/json+oembed">`. I CMS compatibili con oEmbed trasformano automaticamente un link di prenotazione incollato in un iframe del widget incorporato. Il provider risponde solo per URL sull'host di questa app (`/book/*` e `/w/*`), restituisce HTML `type: rich` che punta a `/w/{key}`, e limita `maxwidth`/`maxheight` a 1200/720. Nota: i CMS che isolano i provider oEmbed non fidati (WordPress avvolge i provider non in whitelist in un frame sandbox dove cookie e form sono bloccati) — usa lì lo snippet script o l'URL iframe `/w/`.

## Filtri e stile

Sotto **Avanzate** puoi scegliere **tipi evento** e/o **eventi** per limitare ciò che il widget mostra (vuoto = tutto). Un singolo evento selezionato apre il widget direttamente su di esso. I filtri confluiscono in ogni formato — URL dello script, URL iframe `/w/` e HTML grezzo — quindi genera una volta e poi copia. Sovrascrizione di **testo / classi / stile del bottone**; l'anteprima live renderizza il bottone reale.

## Come funziona l'embed

1. Il bottone dello snippet chiama `POST /api/embed/session` con la `public_key` → restituisce un token `bw_et_…` da 15 minuti e l'URL iframe `/embed?token=…`.
2. L'iframe carica `/embed` attraverso il middleware `widget.locale`; `ConfigureEmbedSession` imposta `SameSite=None` su HTTPS così il cookie di sessione sopravvive negli iframe cross-site.
3. Se l'integrazione ha `allowed_domains`, l'header `Origin`/`Referer` deve combaciare — il parametro `origin` non è mai considerato fidato. L'origine dell'app stessa passa sempre: la allowlist blocca gli embedder esterni, mai l'host che serve la pagina.
4. Quando l'iframe non può portare il cookie di sessione (un embed cross-site su host non-HTTPS non può emettere `SameSite=None`), le pagine `booking/*` accettano il fallback `embed` + `embed_parent_origin` — validato contro `allowed_domains` dell'integrazione (o l'origine dell'app) prima di rilassare `frame-ancestors`.

Ogni render di `/embed` riuscito marca anche l'origine host validata nella sessione con un timestamp. Le pagine `booking/*` e gli header di sicurezza si fidano di quel marcatore solo finché è fresco — `booking-widget.embed_marker_ttl` secondi, sei ore di default (il token iframe `bw_et_…` scade comunque dopo 15 minuti). Un marcatore mancante, malformato, nel futuro o scaduto fallisce chiuso: la pagina torna all'origine dell'app, `?embed=1` da solo può solo rinfrescare un marcatore già fresco — mai resuscitarne uno morto — e resta il fallback allowlist `embed_parent_origin`.

Prima di imporre una allowlist in produzione, esegui `php artisan widget:allowlist-audit`: elenca ogni integrazione attiva con funzionalità widget e `allowed_domains` ancora vuota (exit 1 se ne esistono, sola lettura), così puoi popolare la lista in anticipo invece di bloccare gli embed attivi.

## Link diretti di prenotazione

- `/api/{company}/direct-booking` — apre il widget dritto sugli eventi di un'azienda.
- `/api/{eventType}/event-type-booking` — preseleziona un tipo evento.
- Aggiungi `?open=1` a qualsiasi URL `/book/...` — il widget si apre al caricamento della pagina, senza clic (il "Link di prenotazione immediata" mostrato nelle impostazioni widget).
- `data-area-id` sul bottone dello snippet (o `area_id` su `POST /api/embed/session`) — deep-link diretto a un'area per le aziende che offrono la prenotazione aree.
- `data-event-type-ids` / `data-event-ids` sul bottone dello snippet (o array `event_type_ids` / `event_ids` su `POST /api/embed/session`, CSV su `GET /api/embed/snippet`) — whitelist separate da virgola: il calendario del widget mostra solo i tipi/eventi elencati. Gli attributi singolari `data-event-type-id` / `data-event-id` restano supportati; `data-event-id` inoltre fissa e apre quell'evento.
- `data-cal-display` sul bottone dello snippet (o oggetto `cal_display` su `POST /api/embed/session`) — overlay di visualizzazione per-embed, vedi sotto.

## Avvisami quando aprono le date

La pagina pubblica di un tipo evento (`/book/{company}/{eventType}`) senza date aperte mostra il modulo **Avvisami**: email più una casella di consenso marketing esplicita e non preselezionata. L'invio crea o aggiorna l'ospite (ricevuta di consenso registrata, tag `event-interest`) e salva una riga in `event_type_interests`; la risposta è identica sia che l'email fosse già nota sia di no. Quando una data di quel tipo passa a *Pubblicato* ed è prenotabile, ogni ospite in attesa riceve **una sola** email di annuncio con il link per prenotare (consenso ricontrollato all'invio, disiscrizione con un clic). L'invio viene reclamato in modo atomico tramite `notified_at`, quindi pubblicazioni ripetute non scrivono mai due volte allo stesso ospite; solo un nuovo consenso lo riarma. L'editor del tipo evento mostra quanti ospiti sono in attesa. La cancellazione dell'ospite elimina i suoi interessi.

## Attribuzione

`POST /api/embed/session` riceve già l'URL della pagina ospite (`page_url`, inviato da `widget.js`). Alla creazione della sessione i cinque parametri `utm_*` di quell'URL vengono filtrati in whitelist, troncati e salvati sulla sessione embed; le prenotazioni create dentro l'iframe li ereditano in `bookings.utm` (`{source, medium, campaign, term, content}`). Parametri `utm_*` espliciti sull'URL `/booking/confirm` vincono sulla copia di sessione — sono il salto più fresco. Le prenotazioni senza nessuno dei due portano `utm = null`. La sezione dashboard **Per fonte** riporta le prenotazioni per `bookings.source` (web/widget/staff/walkin…) più le principali `utm_campaign`, scopate per azienda.

## Regole di visualizzazione

**Impostazioni azienda → Visualizzazione calendario** (`/companies/{company}/edit?tab=display` — owner/admin) decide cosa il calendario pubblico elenca e come ogni elemento si legge, per condizione. Condizioni evento: `available`, `sold_out`, `suspended`, `closed`, `draft`, `unavailable` (limiti/figli), `upcoming` (vendite non aperte), `sales_expired` (finestra vendite chiusa), `ended`. Posti/orari accettano `available`, `sold_out`, `closed`, `unavailable`; le aree le stesse più il toggle `closed_day` per i giorni la cui programmazione è stata interamente rimossa dalle chiusure.

Ogni regola sceglie **mostra/nascondi**, **apre il pannello** (`auto` riproduce il comportamento precedente — i prenotabili si aprono, i sold-out si aprono solo con la lista d'attesa attiva, i fallimenti per soli figli aprono un pannello in sola lettura, tutto il resto resta chiuso — `always`/`never` lo sovrascrivono), e un **badge**: etichetta di stato, posti rimasti, totale prenotati, prenotati/capacità, percentuale prenotata, testo personalizzato (token `{availables}` `{booked}` `{capacity}` `{from}` `{to}`), oppure nessuno. `capacity.threshold` nasconde i badge "posti rimasti" finché restano più di N posti; il `show_bookable_threshold` del singolo prenotabile ha comunque priorità.

Le regole si ereditano a cascata azienda → tipo evento → evento (ogni livello sovrascrive per condizione) e il salvataggio emette `venue.updated`, così i widget aperti si ridipingono live. I vincoli sono solo di visualizzazione: gli elementi nascosti non sono mai serializzati né prenotabili, e nulla qui allenta autorizzazione, capacità o controlli sugli archiviati.

Un singolo embed può adattare la policy con `data-cal-display='{"events":{"closed":{"visible":false}}}'` — l'overlay si fonde per ultimo nella cascata, quindi vince per ogni chiave che imposta. È sanificato con whitelist: sezioni, condizioni e campi sconosciuti vengono scartati, `visible` non si può forzare su `available`, e non può mai aggirare i controlli su tenant, archiviati o capacità.

## Modalità aree

Quale calendario renderizza l'iframe dipende dal modello di prenotazione dell'azienda:

- Le aziende **`areas`** ottengono sempre il calendario aree (`/widget/areas`) — scegli un giorno → un'area → una finestra `[from, to)`.
- Le aziende **ibride** (`events` + *Consenti prenotazioni senza evento*) renderizzano il calendario eventi unificato, che offre anche la scelta area "senza evento"; un deep-link `data-area-id` apre il calendario aree direttamente su quell'area.
- Quando almeno un'area ha una forma disegnata, entrambi i widget mostrano la mappa del locale come selettore delle aree (forme toccabili, aree non disegnate su una riga di chip); i tavoli sul floor sono dipinti come decorazione. Senza nulla di disegnato, i clienti vedono la lista semplice. Dentro le prenotazioni di evento con posti la stessa mappa funge anche da selettore delle posizioni — i posti prendono la forma della loro area madre — incluse le aziende solo-eventi che attivano `area_map_picker`.

Vedi [Prenotazione aree](/docs/venue/area-booking) per le impostazioni a livello di area che lo governano.

## Voucher vendibili

Le aziende possono vendere voucher regalo dal proprio sito — **Impostazioni azienda → tab Voucher** (`?tab=vouchers`) configura gli importi predefiniti, il range dell'importo libero, i giorni di validità, il link alle condizioni e mostra lo storico acquisti. Abilitare lo shop sblocca la modalità voucher nel builder embed unificato (**tab Widget prenotazioni**, selettore → *Voucher regalo*): un bottone `data-promo-voucher` che apre lo shop voucher nello stesso overlay (`POST /api/embed/session` con `mode: 'voucher'`). Testo/classi/stile del bottone persistono nel meta dell'integrazione sotto `buttons.voucher` — i campi vuoti ereditano lo stile predefinito aziendale del bottone.

Il compratore sceglie l'importo, inserisce la propria email, opzionalmente lo invia come regalo (email destinatario + messaggio), e paga tramite l'account Stripe connesso dell'azienda — stessa meccanica destination-charge delle prenotazioni. Su `checkout.session.completed` il sistema crea un `PromoCode` whitelist (`source='purchase'`, `balance` = importo) e lo invia via email al compratore o al destinatario regalo.

I codici voucher sono **multi-uso**: ogni riscatto decrementa `balance` sotto lock della riga promo, quindi il valore residuo continua a funzionare su prenotazioni successive fino a esaurimento. Acquisto scaduto/rimborsato → `status='expired'`/`'refunded'`; un rimborso Stripe completo disattiva il codice creato.

**Voucher mirati**: selezionare eventi o tipi di evento nel builder in modalità voucher incorpora `data-event-id`/`data-event-ids` nel bottone voucher — ogni voucher acquistato tramite esso resta vincolato a quella selezione. Lo shop mostra la limitazione prima del pagamento, il codice creato rifiuta qualsiasi altra prenotazione (errore di validazione per i clienti E per le approvazioni staff), e la mail di consegna dichiara l'ambito. `data-area-id` viene ignorato ai fini del targeting. Gli stessi selettori esistono nell'editor codici promo per i codici manuali.

**Reinvio + card stampabile**: ogni riga pagata dello storico acquisti ha un'azione **Reinvia** che rispedisce la mail del codice al titolare (destinatario regalo se presente, altrimenti acquirente). La mail di consegna linka anche una gift card stampabile brandizzata su `GET /voucher/{code}/card` — logo, importo, saldo residuo, destinazione e scadenza, con bottone stampa/"salva come PDF". Il codice stesso è la credenziale della pagina (viaggia già nella mail); la rotta è rate-limited e solo i voucher acquistati si risolvono — i codici promo staff danno 404.

## Widget lead-gen: richieste e raccolta

Il selettore nella **tab Widget prenotazioni** genera anche le superfici lead-gen — stessi formati embed (script / iframe / HTML), stessa pipeline di sessione, stessa allowlist di origini:

- **Richiesta evento privato** (`mode: 'inquiry'`, trigger `data-inquiry`) apre il form lead del locale dentro `/embed` con `source=widget` marcato al mount. I parametri calendario (`event_id`, `area_id`, `cal_display`, …) sono ignorati. I lead arrivano nell'[inbox lead](/docs/venue/leads).
- **Raccolta email** (`mode: 'capture'`, trigger `data-capture`) apre il form iscrizione con consenso dentro `/embed`. Le iscrizioni fanno upsert nel guestbook con semantica primo-consenso-vince.

Entrambi i form mantengono gli URL pubblici diretti — `/inquiry/{company}` e `/capture/{company}` — per i link diretti. Una volta configurati gli `allowed_domains`, quelle pagine possono essere *incorporate* solo dai siti consentiti (`frame-ancestors`); senza lista configurata restano liberamente incorporabili come prima.

## Interruttori per superficie

In **Avanzate → Superfici widget** ogni modalità ha un toggle. Spegnendola la si scrive in `meta.disabled_modes` dell'integrazione e ogni entrypoint la rifiuta all'istante — generazione sessioni, `snippet`/`snippet.js`, redirect `/w/`, render `/embed` già attivi e le pagine pubbliche dirette. Le altre modalità non vengono toccate; riattivandola il servizio riprende subito.

## Link di prenotazione per canale

La tab widget prenotazioni mostra anche i **deep link per canale**: URL di prenotazione pronti da incollare già taggati con sorgente/medium UTM, così l'[attribuzione sorgente](/docs/bookings/manage-bookings) su ogni prenotazione divide il traffico per canale — Google Business Profile, Instagram, Facebook, più un campo sorgente libera che normalizza ciò che digiti. Un tag campagna opzionale si applica a ogni riga. Copia il link nel campo "Prenota online" del Profilo dell'attività, nella bio di Instagram o nel pulsante "Prenota ora" di Facebook e le prenotazioni portano la sorgente automaticamente — nessun embed necessario.

## Dentro il widget

I clienti vedono gli eventi pubblicati, dentro la finestra di prenotazione e non sold-out (quelli sold-out offrono la waitlist quando abilitata). Lingua e tema si cambiano dentro l'iframe. Gli eventi di aziende **private** sono prenotabili solo dai membri azienda.

## Permessi

La gestione dello snippet è owner/admin via impostazioni azienda. Il widget stesso è pubblico — chiunque abbia l'URL embed può navigare e prenotare (salvo il flag `private` dell'azienda). Un utente loggato a un'azienda **diversa** vede il widget esattamente come un visitatore anonimo — nessun permesso staff, nessuna prenotazione forzata — e la sua azienda attiva non cambia mai.


---
> Source: https://placeful-app.com/docs/widget/embed-widget


## Docs — app/member-app

# L'app per i membri

# L'app per i membri

L'app membri è la shell mobile installabile di Placeful — una superficie pensata per il telefono su `/m`, per clienti e staff di sala. È una **PWA**: aggiungila alla home e gira standalone con icona, splash e pagina offline proprie.

## Installazione

Dalla scheda home dell'app tocca **Installa** (o *Condividi → Aggiungi a Home* su iOS). La shell installata parte da `/m` e mette in cache gli asset — senza connettività mostra un'onesta pagina offline invece di una schermata Livewire rotta.

## Cosa contiene

- **Oggi** (`/m`) — saluto, numero di prenotazioni di oggi, conti aperti e le tue prossime prenotazioni; il prompt di installazione vive qui.
- **Prenotazioni** (`/m/bookings`) — le tue prenotazioni del giorno con coperti, orario e tavoli assegnati; cancella dal dettaglio.
- **Check-in** (`/m/checkin`) — manifesto ingressi e scanner dei biglietti QR per gli eventi (staff, `bookings.seat`).
- **Pre-shift** (`/m/pre-shift`) — il foglio briefing del giorno: coperti per fascia, flag VIP/abitudinari/allergie e walk-in (staff, `bookings.viewAny`; vedi [Briefing pre-servizio](/docs/venue/pre-shift)).
- **Sala** (`/m/seating`) — la mappa del locale: tocca un tavolo per i pin delle prenotazioni, lo stato del conto live e le azioni di seating (assegnare una prenotazione, aprire un ordine).
- **Comande** (`/m/orders`) — conti attivi più *I miei ordini* (tutto ciò che il tuo account ha ordinato). Richiede il [modulo ordini](/docs/orders/order-pad).
- **Cucina** (`/m/kitchen`) — lo stesso [monitor cucina](/docs/orders/kitchen-board) del desktop, filtrato per stazione.
- **Ordina da solo** (`/m/order`) — ordina sul tuo tavolo/prenotazione senza personale.
- **Comanda** (`/m/pad`) — la comanda staff in forma mobile, raggiungibile anche per tavolo a `/m/tables/{table}/order`.

## Chi può usarla

I membri registrati via widget possono essere non verificati — l'app funziona comunque — e i membri di un'azienda con abbonamento scaduto mantengono accesso a prenotazioni e ordini (stessa regola delle pagine prenotazioni). Le superfici di ordinazione seguono il flag `orders` del pacchetto, esattamente come il modulo desktop.

## Push e offline

L'app registra lo stesso service worker che alimenta le [notifiche push](/docs/app/push-notifications); toccando una notifica si apre la pagina giusta. Le navigazioni sono network-first con la shell offline come fallback.


---
> Source: https://placeful-app.com/docs/app/member-app


## Docs — developer/api-tokens

# Token API

# Token API

I token API (Laravel Sanctum) autenticano le richieste senza cookie di sessione. `Features::api()` di Jetstream è attivo, quindi ogni utente autenticato può gestire i token su **Profilo → Token API** (`/user/api-tokens`).

Le persone demo non possono creare token API e i token di una persona sono rifiutati in autenticazione — le persone sono solo per impersonificazione (vedi [ambiente demo](demo-environment.md)).

## Creare un token

1. Inserisci un nome e seleziona le abilities che il token deve avere.
2. Il token in chiaro viene mostrato **una volta sola** — copialo subito.

## Abilities

Le abilities offerte sono `create`, `read`, `update`, `delete`, `companies.sync`, `areas.sync`, `events.sync`, `widget.manage`, `tables.sync`, `venue_items.sync` (default: `read`).

L'ability è necessaria ma non sufficiente: `HasCompanies::hasCompanyPermission` richiede inoltre che l'**utente** del token possegga il permesso azienda corrispondente. Es. `companies.sync` funziona solo quando il token ha l'ability *e* l'utente ha il permesso `companies.sync` su quell'azienda (owner/admin di default).

## Usare un token

```
Authorization: Bearer <token>
```

Testalo su `GET /api/user`:

```bash
curl -H "Authorization: Bearer <token>" https://tuo-dominio/api/user
```

## Sync API

I token guidano la sync API in ingresso — `PUT /api/v1/companies/{company}` e gli endpoint area sotto `/api/v1/companies/{company}/areas` — gated dal middleware `ability:` e dalle policy `sync`, rate-limited a 60 req/min keyed sul token. Riferimento endpoint completo: `docs/api-integration.md` nel repo.

## Server MCP (`POST /mcp/bookings`)

Ogni chiamata tool attraverso il server MCP richiede l'ability mappata a quel tool, verificata prima di qualsiasi query — un token di sola `read` riceve `{"error": "forbidden"}` sui tool di scrittura. La route è rate-limited a **60 richieste/min per token** (bucket condiviso con la sync API). Il controllo permesso aziendale si applica comunque.

| Ability | Tool |
| --- | --- |
| `read` | `list-events`, `get-event`, `list-event-types`, `get-availability`, `next-available-event`, `find-slot`, `list-bookings`, `get-booking`, `search-bookings`, `list-pending-approvals`, `list-areas`, `list-tables`, `list-venue-items`, `list-orders`, `get-order`, `get-kpi`, `list-menu-items`, `list-waitlist-entries`, `get-guest`, `list-inquiries`, `get-stock-levels` |
| `create` | `create-booking` |
| `update` | `update-booking`, `mark-booking-service`, `check-in-booking`, `assign-table-to-booking`, `offer-waitlist-spot`, `publish-event`, `convert-inquiry`, `toggle-menu-item-sold-out` |
| `delete` | `cancel-booking` |

`create-booking` accetta `bookable_type` `event`, `time`, `seat`, `seat_time`, `area` — solo foglie prenotabili: un padre che possiede ancora figli risponde `{"error": "pick_a_leaf", "children": [...]}` con gli id delle foglie su cui riprovare.

Oltre ai tool il server espone **risorse** in sola lettura (`docs://catalog` per l'indice dei documenti, `docs://{category}/{slug}` per una pagina, `changelog://index` per i rilasci) e **prompt** — flussi già pronti come `daily-service-brief` e `fill-cancelled-slot` che istruiscono il client su quali tool chiamare. Entrambi richiedono l'ability `read`. Riferimento completo: [Server MCP](/docs/developer/mcp-server).
## Scadenza

I nuovi token scadono dopo 90 giorni (`SANCTUM_TOKEN_TTL_DAYS`; imposta `0` per disattivare). La data di scadenza compare accanto a ogni token nella lista del profilo — rigenera il token prima di quella data. I token creati prima di questa modifica non hanno scadenza (`Nessuna scadenza`) e continuano a funzionare finché non vengono revocati.

## Revoca

Revoca un token dalla pagina profilo. La revoca è immediata; le richieste in volo con il token revocato falliscono alla chiamata successiva.


---
> Source: https://placeful-app.com/docs/developer/api-tokens


## Docs — developer/api-versioning

# Versionamento API

# Versionamento API

L'API di sincronizzazione in ingresso è versionata tramite prefisso URL — `/api/v1/*`. Il registro in `config/api.php` dichiara il ciclo di vita di ogni versione e il middleware `api.version` (alias di `App\Http\Middleware\EnforceApiVersion`) lo applica al gruppo di rotte.

## Stati del ciclo di vita

| Stato | Comportamento |
|---|---|
| `current` | Pienamente supportata. Le risposte portano `X-API-Version`. |
| `deprecated` | Ancora servita, con header `Deprecation` (RFC 9745), `Sunset` (RFC 8594) e `Link: rel="deprecation"`. |
| `sunset` | Le richieste ricevono `410 Gone` con corpo `application/problem+json` che indica la versione di destinazione. |

Una versione si ritira automaticamente al superamento di `sunset_at` — nessun intervento manuale.

## Aggiungere una versione

1. Crea i controller in `App\Http\Controllers\Api\V2`.
2. Aggiungi un gruppo `Route::prefix('v2')->middleware(['api.version:v2', ...])` in `routes/api.php`.
3. Registra `'v2'` in `config/api.php` e imposta `v1` su `deprecated` con le date `deprecated_at`/`sunset_at`.

## Rotte non versionate — contratto stabile

`/api/embed/*`, `/{company}/direct-booking`, `/{eventType}/event-type-booking` e `/webhooks/*` **non** sono versionate: i siti esterni le incorporano e non possono migrare secondo i nostri tempi. Le modifiche non retrocompatibili richiedono una rotta parallela, mai una modifica.


---
> Source: https://placeful-app.com/docs/developer/api-versioning


## Docs — developer/voice-ai

# Bridge partner voice-AI

# Bridge partner voice-AI

Gli agenti vocali stile Hostie/Slang integrano **noi** — chiamano il server MCP, che espone già tutta la superficie di prenotazione che serve a un agente. Nessuna API vocale separata: gli stessi tool servono chat assistant e runtime vocali.

## Endpoint

`POST /mcp/bookings` — Laravel MCP (JSON-RPC over HTTP), autenticato con **token Sanctum bearer** (`Authorization: Bearer …`). Emetti un token con scope per locale dalle impostazioni sviluppatore; un token vede solo la propria azienda — dati di ospiti e prenotazioni non attraversano mai i tenant.

**Ability dei token**: ogni chiamata richiede l'ability mappata al suo tool — `create` per `create_booking`, `delete` per `cancel_booking`, `update` per `mark_booking_service`/`assign_table_to_booking`/`offer_waitlist_spot`, `read` per tutto il resto — e la route è rate-limited a **60 richieste/min per token**. Un token di sola `read` riceve `{"error": "forbidden"}` sui tool di scrittura.

## Tool per un agente vocale

| Tool | Uso nella chiamata |
| --- | --- |
| `list_events` | «Cosa c'è questo weekend?» — eventi e tipi in arrivo |
| `list_areas` | «Prenotate sale private?» — aree prenotabili |
| `get_event` | Dettagli di un evento prima del preventivo |
| `get_availability` | Capienza live + orari/posti aperti per un evento |
| `create_booking` | Prenota uno slot — `bookable_type` (`event`/`time`/`seat`/`area`), `bookable_id`, `number`, `from`/`to` per finestre flessibili, `name`/`email`/`phone`, `notes`, `idempotency_key` |
| `get_booking` | Rilegge una prenotazione via codice |
| `cancel_booking` | Annulla via codice — si applica la policy di cancellazione (rimborso %, cutoff) |

`list_bookings`, `list_event_types`, `list_orders`, `list_tables`, `get_order`, `get_kpi` completano la lettura quando all'agente serve reporting. Registrati anche: `list_waitlist_entries`/`offer_waitlist_spot` (letture waitlist + offerta posti), `get_guest` (scheda CRM), `list_inquiries` (lead eventi), `get_stock_levels` (giacenze), `mark_booking_service` e `assign_table_to_booking` (operazioni di sala — stato servizio e assegnazione tavoli).

## Playbook per chiamata vocale

1. Il cliente dice una data → `list_events` → scegli l'evento.
2. Numero persone/orario → `get_availability` → verifica che lo slot basti.
3. Nome/telefono → `create_booking` con `idempotency_key` per chiamata (a prova di retry — una caduta a metà prenotazione rigioca sulla stessa prenotazione, niente doppi posti).
4. Ri-leggi il codice di conferma; il cliente riceve la normale mail.
5. Annullamento: `cancel_booking` con il codice — il pricing della policy è automatico.

## Garanzie

- Hold di capienza, limiti pacchetto, controlli di stato e obbligo telefono passano da `CreateNewBooking` — identico al widget web, nessuna corsia privilegiata per la voce.
- Gli eventi a pagamento restano `pending` e si completano col normale link di checkout; l'agente deve dire al cliente di attendere la mail di pagamento.
- Gli errori tornano come `{"error": "<code>"}` — codici stabili, usabili per diramare il flusso vocale.


---
> Source: https://placeful-app.com/docs/developer/voice-ai


## Docs — developer/ota

# Canali OTA

# Canali OTA

Superficie di prenotazione in ingresso per le OTA (partner tipo Viator).
Il contratto è indipendente dal provider e stabile — gli stessi percorsi
servono ogni provider, `{provider}` seleziona la mappatura del payload.
Viator è uno skeleton documentato, `generic` parla questo contratto così
com'è per integrazioni su misura, GetYourGuide risponde `501` fino alla
certificazione. Solo in ingresso: l'app non spinge mai disponibilità al
partner.

## Endpoint

```
GET  /api/ota/{provider}/availability?product_id={id}&date=YYYY-MM-DD[&to_date=YYYY-MM-DD]
POST /api/ota/{provider}/bookings
POST /api/ota/{provider}/bookings/{external_reference}/cancel
```

`{provider}` è uno tra `viator`, `getyourguide`, `generic`. Provider
sconosciuti o disabilitati rispondono `404`.

Rate limit: 60 richieste al minuto per collegamento.

## Autenticazione

Ogni richiesta porta due header:

- `X-Ota-Connection: {public_id}` — l'id pubblico del collegamento, visibile
  nella pagina admin dei canali OTA. Mai l'id interno.
- `X-Ota-Signature: {hex}` — HMAC-SHA256 esadecimale con chiave il segreto di
  firma del collegamento (mostrato una sola volta alla creazione o rotazione)
  calcolato su:

```
{METHOD}\n{REQUEST-URI}\n{RAW-BODY}
```

`REQUEST-URI` è l'esatto request target inclusa la query string —
`/api/ota/viator/availability?product_id=P-1&date=2027-01-15`. `RAW-BODY` è
il corpo non parsato (stringa vuota per le GET).

```php
$signature = hash_hmac(
    'sha256',
    "POST\n/api/ota/viator/bookings\n".$rawJsonBody,
    $webhookSecret,
);
```

Errori: collegamento sconosciuto `404 {"error":"unknown_connection"}`; firma
mancante o errata `401 {"error":"bad_signature"}`. L'azienda si risolve
sempre dal collegamento — il payload non può scegliere il tenant.

## Mappatura prodotti

I partner vendono valori `external_product_id`. Ogni id si mappa
nell'interfaccia admin a un solo prenotabile — un evento o un'area — più una
`price_key` opzionale (null usa la risoluzione prezzo predefinita del
prenotabile). Gli id non mappati rispondono `404 {"error":"unknown_product"}`.

## Disponibilità

```json
GET /api/ota/generic/availability?product_id=P-1&date=2027-01-15

{
  "product_id": "P-1",
  "days": [
    {"date": "2027-01-15", "available": true, "remaining": 7}
  ]
}
```

- `available` false significa chiuso, esaurito o fuori dalla finestra vendita.
- `remaining` è la capacità residua; `null` significa senza limite.
- I prodotti-area restituiscono in più `windows: [{from, to, remaining}]` —
  i segmenti vendibili del giorno. Ogni segmento ha la propria disponibilità
  (capienza del segmento meno il picco simultaneo, limitata da ogni pool
  giornaliero che il segmento occupa); il `remaining` del giorno è il
  gruppo più grande che entra in UN solo segmento, non il totale del giorno.
- Il `remaining` di un evento è limitato da OGNI data del suo periodo —
  una prenotazione consuma il pool di ogni giorno che l'evento occupa.
- Un evento senza fine vale solo nel suo giorno di inizio.
- `to_date` estende l'intervallo fino a 31 giorni.

## Creare una prenotazione

```json
POST /api/ota/generic/bookings

{
  "product_id": "P-1",
  "external_reference": "partner-ref-1001",
  "customer": {"name": "Mario Bianchi", "email": "mario@example.com", "phone": "+39002"},
  "number": 2,
  "from": "2027-01-15T10:00:00+00:00",
  "to": "2027-01-15T11:00:00+00:00",
  "date": "2027-01-15"
}
```

`from`/`to` valgono per i prodotti-area (finestre vendibili); `date` è il
giorno di calendario per i prodotti-evento e deve cadere dentro il periodo
dell'evento.

I prodotti-evento prenotano la foglia che il canale può indirizzare: un
evento semplice si prenota direttamente, un evento con fasce orarie prenota
la fascia che inizia a `from` (`from` diventa obbligatorio — mancante o non
corrispondente risponde `422`), e un evento con posti risponde
`available: false` invece di pubblicizzare uno slot che il partner non
potrebbe mai prenotare (la scelta del posto resta sul widget).

Risposta:

```json
{"booking": {"reference": "partner-ref-1001", "status": "confirmed",
             "booking_code": "BK-AB12", "number": 2,
             "created_at": "2027-01-10T09:30:00+00:00"}}
```

Le prenotazioni arrivano gratuite — se il prenotabile mappato richiederebbe
un pagamento la prenotazione è rifiutata con `422 {"error":"payment_required"}`
e la capacità impegnata viene rilasciata. Il denaro incassato dal partner si
riconcilia fuori dall'app.

Gli errori di validazione rispondono `422` con `error` (`booking_failed`) e
una mappa `fields`. I replay di un riferimento fallito restituiscono lo
stesso esito registrato.

### Idempotenza

`external_reference` è la chiave di idempotenza, unica per collegamento. Un
retry che ri-invia lo stesso riferimento riceve l'esito registrato — `200`
con lo stesso payload di prenotazione — senza toccare di nuovo la capacità.
Non riusare mai un riferimento per ordini diversi.

## Annullamento

```
POST /api/ota/{provider}/bookings/{external_reference}/cancel
```

Annulla la prenotazione sottostante attraverso il normale flusso di
cancellazione e porta la riga del registro a `cancelled`. Riferimento
sconosciuto → `404 {"error":"unknown_reference"}`. Annullare un riferimento
già annullato è un no-op `200`. Il rimborso del denaro incassato dal partner
è affare del partner — l'endpoint non innesca mai un rimborso.

## Checklist onboarding partner

1. Owner/admin crea un collegamento nella pagina dei canali OTA
   (`/ota`, feature di piano `ota`) e copia il `public_id`.
2. Ruota/copia il segreto di firma una volta — dopo è solo in scrittura.
3. Mappa ogni `external_product_id` del partner su un evento o un'area
   (+ `price_key` opzionale).
4. Il partner firma `METHOD\nREQUEST-URI\nRAW-BODY` a ogni chiamata e invia
   entrambi gli header.
5. Smoke-test `availability` → `bookings` → `cancel` con un riferimento
   usa-e-getta, poi go-live.


---
> Source: https://placeful-app.com/docs/developer/ota


## Docs — developer/mcp-server

# Server MCP

# Server MCP

Il prodotto espone un server [Model Context Protocol](https://modelcontextprotocol.io) su `POST /mcp/bookings`, così agenti AI (Claude, ChatGPT, strumenti personalizzati) possono leggere e agire sui dati live delle prenotazioni di un'azienda attraverso le stesse action dell'app web.

## Connessione

- **Endpoint:** `POST {app_url}/mcp/bookings` — JSON-RPC 2.0 su HTTP (`Accept: application/json, text/event-stream`).
- **Auth:** `Authorization: Bearer <personal-access-token>` — un token Sanctum creato in **Impostazioni utente → Token API**. Ogni tool richiede l'ability corrispondente: `read` per le letture, `create`/`update`/`delete` per le scritture. Un token senza ability riceve `forbidden`.
- **Scope:** tutti i tool girano nel contesto aziendale dell'utente autenticato — un token non può mai raggiungere un altro tenant.
- **Throttle:** l'endpoint è rate-limited (`throttle:sync`); resta sotto una richiesta al secondo.

## Metodi

Superficie MCP standard: `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/templates/list`, `resources/read`, `prompts/list`, `prompts/get`.

## Tool

31 tool, tutti con le stesse validazioni, limiti di capacità e vincoli di pacchetto dell'app web:

| Gruppo | Tool |
|---|---|
| Eventi | `list-events`, `get-event`, `list-event-types`, `next-available-event`, `publish-event` |
| Prenotazioni | `list-bookings`, `get-booking`, `search-bookings`, `create-booking`, `update-booking`, `cancel-booking`, `list-pending-approvals`, `check-in-booking`, `mark-booking-service`, `assign-table-to-booking` |
| Disponibilità | `get-availability`, `find-slot` |
| Locale | `list-areas`, `list-tables`, `list-venue-items` |
| Ordini e menu | `list-orders`, `get-order`, `list-menu-items`, `toggle-menu-item-sold-out` |
| Lista d'attesa e ospiti | `list-waitlist-entries`, `offer-waitlist-spot`, `get-guest` |
| Richieste | `list-inquiries`, `convert-inquiry` |
| Magazzino e KPI | `get-stock-levels`, `get-kpi` |

I tool di scrittura scrivono davvero — `create-booking` riserva capacità immediatamente, `offer-waitlist-spot` invia l'offerta. Non esiste modalità sandbox: usa un'azienda di prova per sperimentare.

## Risorse

Contenuti markdown in sola lettura, filtrati per ruolo e ability del chiamante:

- `docs://catalog` — l'indice della documentazione visibile all'utente del token.
- `docs://{category}/{slug}` — una pagina di documentazione in markdown (es. `docs://developer/api-tokens`). Stesso gating del docs hub: una pagina che l'utente non può vedere risponde `not_found`.
- `changelog://index` — lista dei rilasci pubblici.

## Prompt

Flussi operativi già pronti che istruiscono il client su quali tool chiamare — non scrivono mai da soli:

- `daily-service-brief` — digest pre-servizio per una data (prenotazioni, chiusure, approvazioni in sospeso, KPI).
- `fill-cancelled-slot` — riempi il vuoto di una prenotazione annullata dalla lista d'attesa (`booking_code` obbligatorio).
- `weekly-ops-review` — digest settimanale.
- `venue-health-check` — audit di configurazione in sola lettura (eventi pubblicati, pianta, disponibilità).

## Errori e limiti

Gli errori tornano come errori JSON-RPC (`invalid params`, `method not found`) o come payload del tool con chiave `error` — controlla `result.content[].text` per oggetti `{error: "..."}`. La sicurezza tenant replica l'app: gli id altrui risolvono come `*_not_found`, mai come fughe di dati.


---
> Source: https://placeful-app.com/docs/developer/mcp-server


## Docs — about/what-is

# Cos'è :app_name?

# Cos'è Placeful?

**Placeful è una piattaforma di prenotazioni per locali** — ristoranti, spazi eventi, tour ed esperienze — che unisce prenotazioni, mappa del locale, comande e gestione del personale in un unico prodotto. Ogni azienda ottiene una pagina pubblica di prenotazione su `/book/{company}` e un widget integrabile nel proprio sito.

## Per chi è

- **Locali** che gestiscono prenotazioni: ristoranti, bar, sale degustazione, tour operator, spazi eventi.
- **Team** con ruoli diversi: owner, admin, manager, member e personale di sala (employee) hanno ciascuno una vista dedicata.
- **Ospiti** che prenotano online — senza obbligo di account per una semplice prenotazione — e possono ordinare dal QR del tavolo.

## Cosa fa

- **Prenotazioni** — eventi con data, capienza, finestre di vendita, configurazioni posti/orari e prenotazione diretta di aree; una macchina a stati segue ogni prenotazione da pending a pagata, rimborsata o no-show.
- **Mappa del locale** — planimetria disegnata con aree e tavoli fisici; le prenotazioni si assegnano a uno o più tavoli.
- **Widget** — embed copia-incolla (`<button>` + `<script>`) che mostra il calendario prenotabile su qualsiasi sito esterno, localizzato.
- **Comande** — menu, comanda per il personale, cucina con partite per portata, auto-ordinazione ospite via QR e cassa giornaliera.
- **Pagamenti** — Stripe Checkout per le prenotazioni a pagamento; ogni azienda collega il proprio account Stripe e riceve i pagamenti direttamente (destination charges).
- **Personale** — anagrafica, contratti, turni, task, timbrature, ferie e radio vocale per la sala.
- **App membri** — PWA installabile su `/m` con le prenotazioni del giorno, mappa tavoli, auto-ordinazione e notifiche push.
- **Waitlist** — gli eventi sold out mantengono una coda FIFO; il posto liberato viene offerto automaticamente.
- **API e integrazioni** — REST API versionata (`/api/v1`), integrazione Stripe via webhook, mirroring Google Calendar e server MCP per assistenti AI.

## Prezzi

I pacchetti sono pubblicati su `/pricing`. Esiste un piano gratuito; i piani a pagamento sbloccano comande, magazzino, personale e supporto prioritario. **Placeful non applica commissioni per prenotazione** sul pacchetto gratuito — i pacchetti a pagamento possono prevedere una fee piatta + percentuale gestita tramite le application fee di Stripe.

## Disponibilità

Placeful è un SaaS ospitato — non esiste un'edizione self-hosted. Il prodotto e tutte le pagine pubbliche sono disponibili in italiano e inglese; i contenuti aziendali sono nella lingua scelta dall'azienda.


---
> Source: https://placeful-app.com/docs/about/what-is


## Docs — about/comparison

# Come si confronta :app_name

# Come si confronta Placeful

Posizionamento onesto: Placeful è **prenotazioni + operatività del locale**, non solo un link di scheduling. Questa pagina lo confronta con le alternative più comuni per aiutarti a scegliere lo strumento giusto.

## vs Calendly

| | Placeful | Calendly |
|---|---|---|
| Modello | Capienza del locale: tavoli, aree, eventi datati | Slot 1:1 su calendario personale |
| Planimetria | Mappa del locale, prenotazioni sui tavoli | Assente |
| Walk-in e porta | Coda, ticket QR, manifest d'ingresso | Assente |
| Comande in locale | Suite completa (comanda, cucina, QR) | Assente |
| Pagamenti | Stripe Connect per locale, caparre, rimborsi | Stripe/PayPal per prenotazione |
| Ideale per | Locali con prenotazioni tavoli/posti | Riunioni e consulenze |

## vs SimplyBook.me / Bookeo / resOS

| | Placeful | Suite di prenotazione |
|---|---|---|
| Tipi di prenotazione | Eventi, configurazioni posti/orari, aree, waitlist | Ampiezza comparabile |
| Operatività oltre la prenotazione | Comande, magazzino, turni, payroll, radio | Di solito solo prenotazioni o add-on |
| Widget integrabile | iframe + session token, blocco domini | Embed iframe |
| API pubblica | `/api/v1` versionata, token Sanctum | Variabile |
| App membri | PWA installabile inclusa | Variabile / a pagamento |
| Prontezza AI | Documenti pubblici, llms.txt, mirror markdown | Raramente documentata |

## Dove Placeful potrebbe non essere adatto

- Serve un **link di scheduling personale** per riunioni — Calendly è più semplice.
- Vuoi un prodotto **self-hosted** — Placeful è solo SaaS ospitato.
- Gestisci un **hotel/struttura ricettiva** pura — i PMS dedicati coprono meglio le camere.


---
> Source: https://placeful-app.com/docs/about/comparison


## Docs — about/faq

# Domande frequenti

# Domande frequenti

## Prodotto

**Cos'è esattamente Placeful?**
Una piattaforma di prenotazioni ospitata per locali: prenotazioni, planimetria, comande e gestione del personale in un unico prodotto. Vedi [Cos'è Placeful](/docs/about/what-is).

**Per chi è pensato?**
Locali che gestiscono prenotazioni — ristoranti, bar, tour, spazi eventi — e i team che li gestiscono.

**I clienti possono prenotare senza account?**
Sì. Un ospite può prenotare dalla pagina pubblica dell'azienda o dal widget integrato senza registrarsi. Creare un account permette di gestire e annullare le prenotazioni in seguito.

**Esiste un piano gratuito?**
Sì — esiste un pacchetto gratuito. I pacchetti a pagamento aggiungono comande, magazzino, strumenti per il personale e livelli di supporto. Vedi `/pricing`.

**Ci sono commissioni sulle prenotazioni?**
Placeful non applica commissioni per prenotazione sul pacchetto gratuito. I pacchetti a pagamento possono prevedere una fee piatta + percentuale, addebitata tramite le application fee di Stripe — l'account Stripe del locale riceve il pagamento direttamente.

**Posso integrare le prenotazioni nel mio sito?**
Sì — un widget copia-incolla (pulsante + script) mostra il calendario prenotabile su qualsiasi sito. Vedi [Integrare il widget](/docs/widget/embed-widget).

**Posso provarlo prima di pagare?**
I pacchetti a pagamento iniziano con un periodo di prova; nessun addebito finché la prova non termina e parte l'abbonamento.

## Dati e privacy

**Dove sono conservati i dati dei clienti?**
Sulla piattaforma ospitata con trattamento conforme al GDPR; il DPA è disponibile su `/dpa` e i diritti di cancellazione sono documentati su `/data-deletion`.

**Posso esportare i miei dati?**
Sì — i membri esportano i dati personali dal profilo; gli owner esportano prenotazioni e dati finanziari dalla dashboard.

## Tecnico

**Esiste un'API?**
Sì — una REST API versionata su `/api/v1` autenticata con token personali. Vedi [Token API](/docs/developer/api-tokens) e [Versionamento API](/docs/developer/api-versioning).

**Esiste un'interfaccia per agenti AI?**
Sì — un server MCP è esposto su `POST /mcp/bookings` per strumenti autenticati via Sanctum, e le pagine pubbliche offrono mirror markdown oltre agli indici `llms.txt`/`llms-full.txt` per gli agenti AI.

**È open source o self-hosted?**
No — è solo un prodotto SaaS ospitato.

**Quali lingue supporta?**
Italiano e inglese per l'interfaccia e le pagine pubbliche; widget e flusso di prenotazione sono localizzati allo stesso modo.


---
> Source: https://placeful-app.com/docs/about/faq


## Docs — about/ai-content-license

# Licenza dei contenuti AI

# Licenza dei contenuti AI

Questa pagina dichiara — in forma leggibile sia da persone che da macchine — come sistemi AI, answer engine e agenti automatizzati possono usare i contenuti pubblici di Placeful. È la destinazione del link `rel="license"` servito nel `<head>` di ogni pagina indicizzabile e della direttiva `Content-Signal` in `/robots.txt`.

## Permesso machine-readable

`/robots.txt` riporta questa riga Content-Signal per ogni percorso indicizzabile:

```
Content-Signal: ai-train=yes, search=yes, ai-input=yes
```

Significato secondo il framework Content Signals (rsl-standard):

- **ai-train=yes** — i contenuti pubblici possono essere usati come input di training per modelli AI.
- **search=yes** — i contenuti pubblici possono essere indicizzati e usati nei risultati di ricerca.
- **ai-input=yes** — i contenuti pubblici possono essere inclusi nel contesto AI a tempo di inferenza (RAG, grounding, retrieval live).

## Cosa è coperto

Solo le pagine pubbliche:

- Pagine marketing (`/`, `/pricing`, `/changelog`)
- Documentazione pubblica sotto `/docs`
- Pagine pubbliche di prenotazione aziendali (`/book/{company}` e varianti per tipo evento)
- I mirror markdown di tutte le pagine precedenti (URL `*.md`)
- `/llms.txt` e `/llms-full.txt`

Le pagine marcate `noindex` (aziende private, aree autenticate) **non** sono coperte — non trattarle come licenziate per uso AI.

## Condizioni

- **Attribuzione gradita**: citando o riassumendo, cita Placeful e linka la pagina sorgente.
- **Rispetta `noindex`**: i contenuti dietro autenticazione o marcati privati sono fuori scope.
- **Crawling educato**: la sitemap su `/sitemap.xml` elenca ogni URL indicizzabile e `/llms.txt` dà l'ordine di lettura curato — preferiscili al crawling alla cieca.

## Endpoint dedicati agli agenti

- `/llms.txt` — indice curato di pagine e documenti pubblici.
- `/llms-full.txt` — l'intero corpus pubblico in un unico file.
- `*.md` — ogni pagina HTML pubblica risponde ad `Accept: text/markdown` e ha un URL mirror `.md`.
- `/robots.txt` — gruppi `User-agent` dedicati a GPTBot, ClaudeBot, PerplexityBot, CCBot e altri crawler AI (i percorsi pubblici restano aperti, quelli privati restano bloccati).

## Contatti

Domande sull'uso AI di questi contenuti: `info@placeful-app.com`.


---
> Source: https://placeful-app.com/docs/about/ai-content-license


## Changelog — 2.6.0

# Placeful 2.6.0

## Novità

- **Server MCP v0.6.0** — il server `/mcp/bookings` ora espone risorse di documentazione (`docs://catalog`, `docs://{category}/{slug}`, `changelog://index`) e quattro prompt di flusso già pronti: `daily-service-brief`, `fill-cancelled-slot`, `weekly-ops-review`, `venue-health-check`.
- **Catalogo API** — `/.well-known/api-catalog` (RFC 9727) offre agli agenti un indice macchinabile di REST API, bridge OTA e server MCP con link alla documentazione.
- **Superficie agenti arricchita** — mirror `.md` aggiunti per hub documentazione, indice legale, pagina trust e landing page; `/trust` e le landing page pubbliche ora compaiono nella sitemap; robots.txt permette i feed Google Reserve sotto `/api`.
- **Schemi tool assistente strict** — le definizioni dei tool dell'assistente ora si normalizzano al contratto strict di function calling (`additionalProperties: false`, opzionali nullable) dietro `AI_ASSISTANT_STRICT_TOOLS`, con retry automatico senza strict per i provider che lo rifiutano.
- **Upgrade documentazione** — nuove pagine: server MCP, Importa dal web, Campi personalizzati di prenotazione; meta description per pagina, data di ultimo aggiornamento visibile e dati strutturati FAQ sulla pagina FAQ.

## Correzioni

- **Domanda orfana nelle capacità giornaliere** — le prenotazioni il cui slot o evento è stato eliminato continuano a contare nei pool condivisi venue/area grazie allo snapshot salvato, con la domanda riassociata a data e flag attuali dell'evento; snapshot malformati o di altri tenant vengono rifiutati invece di gonfiare o azzerare i pool.
- **Intento degli argomenti dei tool assistente** — i null emessi in strict mode non svuotano più i campi delle prenotazioni né fanno fallire i parametri opzionali; le modalità legacy degli snapshot si idratano senza errori.

## Documentazione e guide

- `developer/mcp-server`, `companies/web-import`, `bookings/custom-fields` in inglese e italiano.


---
> Source: https://placeful-app.com/changelog/2.6.0


## Changelog — 2.5.1

# Placeful 2.5.1

## In evidenza

- **Capienza giornaliera condivisa** — sedi, aree ed eventi possono condividere un tetto di ospiti per giornata; le prenotazioni lo consumano alla cassa, widget e feed OTA lo leggono in tempo reale e lo staff vede l'utilizzo previsto per giorno.
- **Prenotazioni affidabili sotto carico** — i canali (Reserve with Google, OTA, assistente, MCP) tornano a indirizzare la foglia prenotabile corretta, gli hold carta scaduti non possono più riattivarsi sopra una capienza venduta e il salvataggio tardivo della carta su prenotazioni gratuite ricontrolla la disponibilità prima di confermare.
- **Modifiche strutturali più sicure** — spostare un evento prenotato o passare un posto da flessibile a fisso ora valida la domanda sui pool giornalieri prima di salvare; lo spostamento su un giorno pieno viene rifiutato salvo accettazione esplicita (`accept_pool_overage` in API).

## Correzioni

- La disponibilità del widget coincide con il server: limiti per giorno e per finestra al posto della capienza in cache, quindi aree ed eventi multi-giorno non mostrano più un falso "esaurito".
- I rimborsi in sospeso riservano sia la finestra originaria sia quella di destinazione, tavoli fissati inclusi — una riprogrammazione non apre più uno slot in overbooking.
- Le modifiche alle serie propagano la partecipazione ai pool giornalieri ai membri; gli orari di posizionamento inviati via API con offset UTC vengono salvati nel fuso orario della sede.

## Privacy

- Il canale pubblico di disponibilità non pubblicizza più eventi nascosti o aree non visibili nel widget; lo staff conserva l'elenco completo sul canale privato.
- Le note giornaliere dello staff restano fuori dall'export d'archivio pur restando nel piano di eliminazione.


---
> Source: https://placeful-app.com/changelog/2.5.1


## Changelog — 2.5.0

# Placeful 2.5.0

## In evidenza

- **Riconciliazione documenti fornitori** — scansiona bolle e fatture dal telefono o da upload, estrazione dati assistita da AI (sessioni multi-pagina, XML FatturaPA) e coda di abbinamento a tre vie che lega ogni fattura fornitore alla bolla e al movimento bancario. I feed bancari PSD2 via GoCardless/Enable Banking tengono i movimenti sincronizzati.
- **Vendita e riscatto voucher** — vendi voucher a saldo su codici promo, traccia gli acquisti e lascia che gli ospiti li riscattino al checkout con incasso del residuo. I codici legacy vengono ri-generati nello spazio a 12 caratteri al salvataggio successivo.
- **Assistente ovunque** — l'assistente AI guadagna 23 strumenti di lettura e 20 strumenti di scrittura confermata che coprono ordini, personale, coda in sala, marketing e riconciliazione; ogni scrittura mostra un'anteprima e va confermata prima dell'esecuzione.

## Sicurezza

- **Audit di sicurezza completo** — ogni superficie staff e ospite è stata ri-verificata: le letture cross-tenant sono vincolate all'azienda montata, i prop Livewire lato server sono bloccati contro manomissioni e le azioni privilegiate ri-autorizzano a ogni richiesta.
- **Igiene di credenziali e token** — i token API hanno abilità limitate e scadono con TTL configurabile; i link di claim dei widget si legano al browser che li ha avviati; l'accesso social passa la verifica a due fattori; gli URL di reset password sono esclusi in robots.txt così un link trapelato non viene mai scansionato.
- **Protezione dei dati più profonda** — le richieste di cancellazione e accesso richiedono una mailbox verificata prima dell'esecuzione, le persona demo non possono creare sessioni o token API, e gli export finiscono su un disco privato con retention di 7 giorni invece di URL pubblici.
- **Integrazioni più sicure** — i webhook in uscita firmano i payload e ri-validano gli endpoint contro SSRF a ogni consegna, e il teardown di Google Calendar salta le eliminazioni remote quando la connessione è già assente invece di generare errori per ogni mirror.

## Operazioni

- **Piattaforma webhook** — webhook in uscita firmati con verifica HMAC, rotazione per segreto, replay e registro consegne; gli endpoint sono validati anti-SSRF in registrazione e ri-verificati a ogni consegna.
- **Stampa cucina** — ESC/POS tramite bridge locale o browser, instradamento per stazione, lease dei job con reaper autonomo e retention dei job di stampa.

## WhatsApp e messaggistica

- **WhatsApp in uscita** — invii con template approvati Meta per conferme prenotazione, promemoria e link di riconferma, gamba campagne con stato di consegna per destinatario e inbox che raggruppa i thread per controparte con risposte staff sicure per il consenso (STOP vince sempre).
- **Ricevute di consenso** — ogni concessione/revoca di canale scrive una ricevuta append-only; START riapre solo il canale — il marketing richiede un opt-in esplicito (toggle nella scheda ospite o casella nel form di prenotazione). Body e payload dei messaggi vengono ripuliti oltre l'orizzonte di retention.

## Widget ed embed

- **Builder di embed unificato** — un'unica schermata nelle impostazioni genera embed script, pulsante e iframe per ogni widget: calendario prenotazioni, voucher regalo, richieste di eventi privati e raccolta email. Stile e filtri per singolo widget restano, ora dietro un unico selettore.
- **Tutti i widget sulla pipeline sicura** — gli embed di richiesta e raccolta ora generano la stessa sessione a breve durata vincolata all'origine del calendario e si aprono dentro `/embed`, con lingua, attribuzione UTM e controlli kill-switch a ogni render.
- **Interruttori per singola superficie** — disattiva una superficie widget dalle impostazioni e ogni embed, snippet, URL diretto e pagina pubblica la rifiuta all'istante, senza toccare le altre.
- **Moduli diretti vincolati all'allowlist** — `/capture/{company}` e `/inquiry/{company}` restano raggiungibili pubblicamente, ma una volta configurati i domini consentiti possono essere incorporati solo da quei siti (frame-ancestors), chiudendo il varco di clickjacking su moduli contatti e iscrizioni. Anche l'iframe `/embed` è ora vincolato all'host validato, e l'URL stabile `/w/{key}` mostra una pagina "Widget non disponibile" leggibile invece di JSON grezzo quando piano, dominio o interruttore lo rifiutano.
- **Isolamento widget tra aziende** — un utente loggato a un'altra azienda vede il widget pubblico come un normale visitatore (nessun potere staff, il contesto azienda non cambia mai); l'origine embed validata viene riverificata contro un marcatore con timestamp fresco per sei ore di inattività mentre il token iframe scade sempre dopo 15 minuti; e `php artisan widget:allowlist-audit` elenca le integrazioni attive con funzionalità widget e lista domini vuota prima del rollout.

## Privacy e dati

- **Copertura export e cancellazione** — ordini aggregatori in entrata, righe documenti fornitore e righe stampa cucina entrano nell'archivio export aziendale e nei grafi di anonimizzazione.
- **Audit rafforzato** — mutazioni di conti bancari e stati di abbinamento, oltre alle decisioni di riscatto promo, ora sono auditate con l'attore registrato.


---
> Source: https://placeful-app.com/changelog/2.5.0


## Changelog — 2.4.0

# Placeful 2.4.0

## In evidenza

- **Programma loyalty** — registro punti con livelli che generano codici promo, sweep di scadenza e UI gestionale completa, attivabile per pacchetto.
- **Campi prenotazione tipizzati** — campi testo, area testo, numero, data, select e checkbox su eventi e aree, validati lato server contro un'impronta della definizione bloccata: invii obsoleti o falsificati vengono rifiutati in modo pulito; la sincronizzazione delle serie propaga tipo, opzioni e placeholder.
- **Inbox WhatsApp e bot prenotazioni** — webhook Cloud API con verifica della firma e deduplica dei retry, abbinamento automatico degli ospiti, inbox per lo staff e bot assistente prenotazioni.
- **Storefront asporto e consegna** — zone di consegna per sede (raggio o poligono), tariffe e ordine minimo, più PWA ospite installabile con branding whitelabel e landing page pubbliche su `/p/{company}/{slug}`.
- **Nuova navigazione** — sidebar, drawer, breadcrumb e palette comandi guidate da registry con icon rail, badge live e stato delle sezioni persistente; le voci rispecchiano l'autorizzazione delle pagine quindi i link non autorizzati non compaiono mai.

## CRM ospiti e lead

- **Ponte sul guest book** — la spesa ordini accredita il profilo ospite, i duplicati si fondono in sicurezza e le richieste si convertono in prenotazioni che si finalizzano invece di scadere.
- **Journey opt-in e automazioni** — journey primo-visit, VIP e detractor più automazioni per chiusura cassa, survey-detractor e conflitto hold, e un digest pre-turno.
- **Disiscrizione firmata** — link firmati per destinatario con opt-out one-click RFC 8058 su campagne e journey.

## Operazioni

- **Planner rinnovato** — planner riprogettato con sweep di retry sui rimborsi e compensazione dell'usage per la fatturazione.
- **Oggetti venue sulla mappa** — tipi, oggetti, assegnazioni ad aree e geometrie, spostabili da task staff e strumenti assistente, sincronizzati via API v1.
- **Approvazioni e pagamenti** — le richieste di approvazione senza risposta avvisano il cliente alla scadenza, gli hold approvati hanno una finestra di pagamento di 24 ore, e penali no-show, pagamenti tardivi, rate e checkout terminal sono blindati end-to-end.
- **Collegamento serie** — eventi esistenti raggruppabili in una serie ricorrente a posteriori.
- **Tip pooling** — il pool conta le legs pagate nel giorno di chiusura, e i dipendenti vedono le quote mance distribuite nel portale staff.

## Privacy, dati e visibilità

- **Pipeline di cancellazione** — anonimizzatori per utenti, dipendenti, ospiti e richieste, processore di richieste di eliminazione, cifratura PII dipendenti e copertura export.
- **Archivio tenant completo** — l'export aziendale ora include grafi CRM, lead e staff-ops; i tenant demo eliminano lo stesso traffico mantenendo la configurazione.
- **Superficie per agenti** — mirror markdown, `llms.txt`/`llms-full.txt`, telemetria crawler AI, ping IndexNow sui contenuti pubblici e grafo schema.org.


---
> Source: https://placeful-app.com/changelog/2.4.0


## Changelog — 2.3.0

# Placeful 2.3.0

## In evidenza

- **Regole di visualizzazione calendario** — i locali scelgono cosa mostra il widget pubblico per condizione (chiusi, sold-out, sospesi, bozze, in arrivo, vendite scadute, terminati, non disponibili): mostra o nascondi, se il pannello prenotazione si apre, e quale badge renderizza — etichetta di stato, posti rimasti, totale prenotati, prenotati/capacità, percentuale prenotata o testo personalizzato.
- **Cascata delle regole** — le regole si risolvono azienda → tipo evento → evento, così il locale imposta i default una volta e li restringe per tipo o per evento; posti, orari e aree seguono lo stesso modello, inclusa l'etichetta "Chiuso" per i giorni interamente chiusi del calendario aree.
- **Overlay per-embed** — un attributo JSON `data-cal-display` sul bottone del widget (o `cal_display` nell'API embed session) adatta visibilità e badge per una singola integrazione senza toccare i default aziendali; gli overlay sono sanificati con whitelist e non possono mai aggirare i controlli di prenotazione, tenant o capacità.
- **Promemoria prenotazioni, su attivazione** — i promemoria pre-evento automatici ora seguono interruttori espliciti: un interruttore principale aziendale, un default per tipo evento e un flag per evento (i locali esistenti partono disattivati — si abilita dalle impostazioni aziendali). Lo staff può sempre inviare un promemoria manuale per prenotazione o per evento.
- **Eliminazioni più sicure** — posti, aree, tavoli ed eventi rifiutano l'eliminazione solo mentre una prenotazione attiva (non terminale) li referenzia; le prenotazioni annullate, scadute o rimborsate non bloccano più la pulizia, e le entry in lista d'attesa su un elemento eliminato vengono chiuse tramite le proprie transizioni invece di restare appese.

## Eventi privati e vendite

- **Inbox lead** — un modulo pubblico raccoglie richieste di eventi privati in un inbox manager con stati e assegnazione.
- **Proposte e BEO** — un motore documentale genera proposte/banquet-event-order dalle prenotazioni, con firma elettronica e PDF.
- **Piani di pagamento** — caparre e rate sulle richieste, carta salvata e tracciamento del minimo F&B.
- **Hold provvisori, approvazioni, buffer, quote** — hold soft con scadenza e promemoria, workflow di approvazione per le aree, buffer di turnover per area e quote di prenotazione per utente.
- **Prenotazioni ricorrenti** — serie settimanali/mensili per prenotazioni create dallo staff, tutto-o-niente.

## Ricavi e distribuzione

- **Regole di prezzo dinamiche** — modificatori percentuali per giorno della settimana e giorni di anticipo, cumulabili moltiplicativamente, con scope su locale, area o evento.
- **Stripe Terminal** — registrazione dei lettori e pagamenti `card_present` direttamente sull'order pad.
- **Link canali** — URL di prenotazione con UTM per canale (Google Business Profile, Instagram, Facebook, custom) nella scheda widget.
- **Gruppi di locali** — gruppi multi-venue con guestbook condiviso su opt-in, fallback verso i locali gemelli nei giorni sold-out del widget e report aggregato cross-venue.
- **Reserve with Google** — feed merchants/services/availability più il booking server v2 (check, create, cancel, list) dietro flag opt-in.

## CRM ospiti

- **Sondaggi e recensioni** — motore di survey post-visita con instradamento delle recensioni.
- **Regole tag, segmenti, campagne, journey** — auto-tagging a regole, segmenti del guestbook, campagne one-shot e journey di ciclo di vita (compleanno, anniversario, win-back).
- **Raccolta email** — widget pubblico che alimenta il guestbook.
- **Gift card** — reinvio, saldo e card stampabile brandizzata.

## Operazioni

- **Porta e check-in** — liste porta, check-in eventi e add-on sulle prenotazioni, più recupero hold e attribuzione della sorgente.
- **Briefing pre-turno** — report per servizio con coperti, VIP e note per la sala.
- **Radio staff** — push-to-talk stile WhatsApp con clip vocali, conferme di lettura e composer nel dock PWA.
- **Pianificazione intelligente** — previsione domanda dallo storico prenotazioni alimenta il risolutore turni; pool di scambio con offerta → presa → approvazione; report costo-lavoro-vs-vendite con target del locale.
- **Pool mance** — le mance regolate del giorno divise in proporzione ai minuti lavorati approvati, congelate in quote verificabili.
- **Registro manager** — note di turno datate e categorizzate per il passaggio di consegne.


---
> Source: https://placeful-app.com/changelog/2.3.0


## Changelog — 2.2.1

# Placeful 2.2.1

## In evidenza

- **Self-service per gli ospiti** — gli ospiti cancellano o spostano la propria prenotazione tramite un link di gestione, secondo le politiche di cancellazione del locale con scadenze, penali e rimborsi.
- **Caparre e pre-autorizzazioni** — incassa una caparra o blocca la carta alla prenotazione, e addebita la penale no-show quando l'ospite non si presenta.
- **Notifiche SMS e WhatsApp** — conferme, promemoria e avvisi di cancellazione ora viaggiano via Twilio, con preferenza SMS per utente.
- **Riconferma o rilascio** — chiedi agli ospiti di riconfermare prima del turno; le prenotazioni non confermate si rilasciano automaticamente o vengono segnalate allo staff, con punteggio no-show per ospite.
- **Radio staff** — le stanze vocali diventano Radio: messaggi di testo oltre alle clip, stanze live WebRTC e autoplay nell'app membri.
- **Fix contabilità** — corretti gli incassi ordini, i totali prenotazione e la visualizzazione delle valute.


---
> Source: https://placeful-app.com/changelog/2.2.1


## Changelog — 2.2.0

# Placeful 2.2.0

## In evidenza

- **Account staff, un solo collegamento** — i dipendenti ora si collegano a un account utente con un unico percorso e lo staff cessato mantiene un portale in sola lettura invece di perdere lo storico.
- **Ciclo di vita delle aree** — elimina un'area di sala in sicurezza: i controlli sulle prenotazioni bloccano le eliminazioni distruttive, i posizionamenti tavoli vengono rimossi automaticamente e le aree eliminate si possono ripristinare.
- **Sala più robusta** — le assegnazioni multi-tavolo validano correttamente e i casi limite delle finestre di pin non passano più.
- **PWA più affidabile** — l'app installata gestisce meglio i fallback offline, gli aggiornamenti del service worker e i casi limite di attivazione/disattivazione push.
- **Fix tour planner** — il tour guidato non salta più un passaggio nei giorni senza attività.


---
> Source: https://placeful-app.com/changelog/2.2.0


## Changelog — 2.1.0

# Placeful 2.1.0

## In evidenza

- **Gestione del personale** — un'area HR completa: anagrafica dipendenti con posizioni e contratti, tracciamento documenti, pianificazione turni, timbrature, richieste e approvazioni ferie/permessi e cedolini — più un portale self-service dove lo staff vede turni, attività, presenze e documenti.
- **Attività staff e turni con AI** — assegna attività a persone o tavoli/aree e lascia che lo scheduler AI proponga una rosa ottimale da rivedere e applicare in un colpo solo.
- **Shop voucher e codici promo** — vendi voucher promozionali dallo shop incorporabile del widget e gestisci codici promo con obiettivi e limiti.
- **Tracciamento dei rimborsi** — ogni rimborso registra le sue tranche, un reaper recupera i rimborsi bloccati e i proprietari ricevono un avviso quando un rimborso richiede attenzione.
- **Pagamenti e valuta più sicuri** — i webhook Stripe sono protetti dai fallimenti obsoleti e le prenotazioni vengono sempre addebitate nella valuta di fatturazione dell'azienda.
- **Prenotazioni via email affidabili** — i link di conferma non possono più creare doppie prenotazioni su retry o race condition, e la posta in arrivo deduplica in sicurezza sotto concorrenza.
- **Widget rafforzato** — gli eventi archiviati si comportano come tombstone e i messaggi widget↔parent vanno solo a un'origine verificata.


---
> Source: https://placeful-app.com/changelog/2.1.0


## Changelog — 2.0.1

# Placeful 2.0.1

## In evidenza

- **Input vocale dell'assistente corretto** — un header di sicurezza bloccava silenziosamente il microfono, così la dettatura non chiedeva mai l'accesso. Ora il browser mostra la richiesta e ricorda la scelta.
- **Fix crash della dashboard su MySQL** — i widget prenotazioni per evento e per area potevano generare un errore 500 con la modalità strict group-by di MySQL; le etichette ora vengono raggruppate correttamente.
- **Link all'editor della mappa affidabile** — "Apri l'editor della mappa" dal seating plan non apre più un editor inizializzato a metà.
- **Ordinamento "seleziona tutto" nella matrice** — selezionare tutti i posti o tutte le fasce orarie ora si comporta in modo coerente su tutti i database.


---
> Source: https://placeful-app.com/changelog/2.0.1


## Changelog — 2.0.0

# Placeful 2.0.0

## Highlights

- **Mappa del locale e tavoli** — disegna la pianta, posiziona i tavoli fisici e fissa le prenotazioni ai tavoli. I tavoli si spostano tra aree su programmazione, quindi il layout di stasera non deve per forza essere quello della settimana prossima.
- **Mappa posti a sedere** — vista live della sala per giorno di servizio (`/venue/seating`): scegli una prenotazione, tocca i tavoli compatibili e i posti si ripartiscono da soli — un gruppo può sedere su più tavoli. L'assegnazione automatica propone il piano completo del giorno (spread o compact), e l'editor prenotazione e il planner linkano il giorno della prenotazione.
- **Assegnazione universale** — ogni tipo di prenotazione può prendere tavoli: le prenotazioni area si fissano nella loro area, quelle posto/orario seguono l'area risolta, quelle evento vanno ovunque in pianta.
- **Codici promo** — i clienti inviano un codice al checkout; la prenotazione si parcheggia per la revisione staff invece di addebitare la carta. Approva con copertura piena o parziale (il restante si paga tramite link Stripe), rifiuta con un fallback — e un codice si brucia in tutta l'azienda una volta onorato.
- **Prenotazione aree** — le aziende possono far prenotare un'area direttamente per una fascia oraria, con orari, giorni e capienza propri — oppure mescolare aree ed eventi fianco a fianco.
- **Calendario planner** — una griglia mensile su `/admin/planner` dipinge chiusure, prenotazioni, eventi e spostamenti tavoli per giorno, con azioni batch di chiusura/riapertura/spostamento direttamente dalla griglia. Nuove prenotazioni ed eventi — e la mappa posti — ora si aprono dentro la modale iframe del planner, così non perdi mai la griglia sotto.
- **Analitiche per area** — due nuove sezioni dashboard scompongono le prenotazioni per area e nel tempo, e finiscono nell'export.
- **Archiviazione a freddo** — gli eventi conclusi passano automaticamente a bundle cifrati, mantenendo l'app veloce con le dashboard intatte; il ripristino riporta tutto indietro.
- **Assistente più furbo** — l'assistente vede la pagina che hai aperta, apre i record per te e ora propone più modifiche con approvazione a un clic: tavoli e aree, collocazione e spostamenti, modifiche e cancellazioni di prenotazioni.
- **Sync live ovunque** — dashboard, planner, editor, widget e posti a sedere si riallineano in tempo reale quando qualcun altro modifica dati condivisi — niente più schermate stantie.
- **Prenotazioni più sicure** — chiusi i casi limite di overbooking, settlement e permessi in tutto il flusso di prenotazione.


---
> Source: https://placeful-app.com/changelog/2.0.0


## Changelog — 1.3.0

# Placeful 1.3.0

## In evidenza

- **Cronologia dell'assistente** — le conversazioni ora persistono tra pagine e ricaricamenti. L'icona a orologio nell'intestazione riapre le chat passate e puoi continuarle da dove eri rimasto.
- **Risposte con link** — quando l'assistente trova una prenotazione o un evento risponde con un link cliccabile, per aprirlo subito.
- **Avanzamento live e feedback** — vedi quali ricerche l'assistente esegue mentre elabora, valuta le risposte con pollice su/giù e inizia una nuova chat quando vuoi.
- **Più solido sotto il cofano** — l'uso dei token viene registrato per ogni richiesta per il controllo dei costi, e le vecchie conversazioni vengono eliminate automaticamente allo scadere del periodo di conservazione.
- **Fix contatti prenotazione** — chi apre la prenotazione di un cliente non vede più (né salva per errore) i propri recapiti nei campi dell'ospite.


---
> Source: https://placeful-app.com/changelog/1.3.0


## Changelog — 1.2.2

# Placeful 1.2.2

## In evidenza

- **Google Calendar per azienda** — le connessioni al calendario ora sono legate all'azienda in cui sono state create: collegandolo in un'azienda non si sincronizza più su tutte quelle di cui fai parte. Ogni tenant mantiene il proprio accesso, i propri mirror, preferenze e disconnessione.
- **Memoria e nuovi strumenti dell'assistente** — l'assistente integrato ripropone la conversazione recente, così le domande di follow-up funzionano, e ottiene strumenti di sola lettura: ricerca eventi, dettaglio prenotazione, prenotazioni non pagate e guida in-app.
- **Indicatore "Novità"** — il pallino nel menu ora appare solo per i rilasci che non hai ancora aperto.
- **Fix flash del tour guidato** — il popover del tour non lampeggia più nella posizione sbagliata prima di stabilizzarsi.


---
> Source: https://placeful-app.com/changelog/1.2.2


## Changelog — 1.2.1

# Placeful 1.2.1

## In evidenza

- **Fix logo del loader del widget** — il loader dell'embed richiedeva il logo dell'app dalla base API (`/api/icons/logo.png`), generando un 404 a ogni apertura del widget; ora lo carica dalla radice dell'app.
- **Fallback di versione accurato** — quando `APP_VERSION` non è impostata, l'app riporta il tag git più vicino invece del suffisso grezzo di `git describe`.
- **Fix ritaglio dei suggerimenti** — i tooltip non vengono più tagliati ai bordi delle card.


---
> Source: https://placeful-app.com/changelog/1.2.1


## Changelog — 1.2.0

# Placeful 1.2.0

## In evidenza

- **Mirror di calendario per utente** — i membri dello staff ora hanno un proprio evento Google aggregato per evento, i clienti mantengono i mirror per prenotazione, e cambi di ruolo, rimozioni ed eliminazione dell'account risincronizzano o eliminano i mirror automaticamente.
- **Ricerca eventi nel widget** — filtra gli eventi per nome, salta a una data e parti da un focus iniziale sensato.
- **Protezione eventi conclusi** — le prenotazioni si chiudono appena l'evento finisce, anche durante il checkout; l'editor suggerisce di spostare la data in avanti per riaprire le vendite.
- **Ripristini cronologia più sicuri** — il ripristino di un record ora ripercorre l'intera catena di audit per ricostruire lo stato reale nel tempo, e gli editor ricaricano il modulo dopo un ripristino.
- **Manifest dell'app localizzato** — il manifest PWA viene servito per lingua con l'URL di avvio corretto.

## Correzioni e miglioramenti

- I valori dinamici nei contesti JavaScript/Alpine ora vengono escapati tramite `@js()` in tutta l'app.


---
> Source: https://placeful-app.com/changelog/1.2.0


## Changelog — 1.1.0

# Placeful 1.1.0

## In evidenza

- **Assistente AI** — fai domande direttamente in-app, basato su Gemini con fallback automatico tra modelli e gestione dei limiti di frequenza.
- **Passkey** — accesso senza password con login passkey-first, dispositivi attendibili e flusso di recupero.
- **Conformità GDPR** — esportazione dei dati, tracciamento del consenso e controlli sulla privacy in tutta la piattaforma.
- **Sincronizzazione Google Calendar** — un evento aggregato per evento sul calendario aziendale, più una copia per prenotazione per i clienti.
- **API di sincronizzazione** — nuovi endpoint per sincronizzare aziende, aree ed eventi e per gestire i widget via API.
- **Vista elenco del widget** — il widget di prenotazione può mostrare gli eventi come elenco, non solo come calendario.
- **Telefono obbligatorio** — gli eventi possono richiedere il numero di telefono nel modulo di prenotazione.
- **Riepiloghi di pagamento** — i dati delle ricevute vengono salvati e mostrati sui pagamenti.

## Correzioni e miglioramenti

- Reindirizzamento all'host canonico e URL tag per la SEO.
- Callback OAuth del widget legato al token della richiesta di autenticazione, non alla sessione.
- Il gestore prenotazioni resta accessibile ai customer-member.
- Ripristini audit tenant-safe e correzione dei 404 del changelog.


---
> Source: https://placeful-app.com/changelog/1.1.0


## Changelog — 1.0.0

# Placeful 1.0.0

Benvenuto nel changelog di :app_name. Questa pagina tiene traccia di ogni rilascio del prodotto: nuove funzionalità, miglioramenti e correzioni.

## In evidenza

- **Calendario delle prenotazioni** — crea eventi, fasce posto e finestre a orario libero con tracciamento della capacità in tempo reale.
- **Widget integrabile** — aggiungi un widget di prenotazione a qualsiasi sito con un singolo tag script.
- **Pagamenti Stripe** — checkout, rimborsi, pagamenti in ritardo e payout Stripe Connect per le aziende.
- **Team e ruoli** — invita membri con ruoli owner, admin, manager o member.
- **Centro documentazione** — guide in-app per il tuo ruolo, in italiano e inglese.


---
> Source: https://placeful-app.com/changelog/1.0.0


## Legal — refund

# Informativa sui rimborsi

# Informativa sui Rimborsi

_Ultimo aggiornamento: 21/09/2026_

## 1. Introduzione

La presente Informativa sui Rimborsi descrive le condizioni alle quali possono essere emessi rimborsi per prenotazioni e pagamenti effettuati tramite **Placeful**, gestita da **Andrea Faccioli**.

Completando un pagamento, confermi di aver letto e compreso la presente Informativa sui Rimborsi.

## 2. Requisiti di ammissibilità

Può essere richiesto un rimborso per prenotazioni pagate che soddisfano tutte le seguenti condizioni:

- la prenotazione è stata pagata integralmente tramite il sistema di pagamento della piattaforma
- la richiesta di rimborso è inviata entro il periodo di rimborso applicabile (vedi Sezione 3)
- l'evento o il servizio non ha ancora avuto luogo, salvo diversa indicazione

## 3. Periodo di rimborso e diritto di recesso legale

Le richieste di rimborso devono essere inviate entro **14 giorni** dalla data di pagamento o prima della data dell'evento programmato, a seconda di quale si verifichi per primo.

**Nota sul diritto di recesso legale:** per i servizi di svago legati a una data o a un periodo di esecuzione specifico (eventi, spettacoli, prenotazioni datate), l'art. 59, comma 1, lett. n) del Codice del Consumo esclude il diritto di recesso legale di 14 giorni. Le condizioni di rimborso della presente informativa sono quindi offerte come **facoltà contrattuale** che può superare il minimo legale; laddove il diritto legale si applichi (es. contratti non legati a una data), resta in ogni caso impregiudicato.

Le richieste ricevute dopo il periodo di rimborso saranno valutate a discrezione del gestore e potrebbero essere rifiutate.

## 4. Come richiedere un rimborso

Per richiedere un rimborso, contattaci all'indirizzo **info@placeful-app.com** e includi le seguenti informazioni:

- nome e cognome
- riferimento o codice di conferma della prenotazione
- data della prenotazione
- motivo della richiesta di rimborso

Le richieste possono anche essere inviate tramite la funzionalità di rimborso dell'applicazione, ove disponibile.

## 5. Tempi di elaborazione

I rimborsi approvati vengono elaborati entro **10 giorni lavorativi** dalla data di approvazione.

L'importo rimborsato verrà restituito sul metodo di pagamento originale utilizzato al momento dell'acquisto. A seconda della banca o del provider di pagamento, potrebbe essere necessario ulteriore tempo prima che i fondi risultino disponibili sul conto.

## 6. Casi non rimborsabili

I seguenti casi non sono ammissibili al rimborso:

- richieste inviate dopo il periodo di rimborso applicabile
- prenotazioni per eventi o servizi già avvenuti
- assenze parziali o arrivi in ritardo
- commissioni o costi imposti da provider di pagamento di terze parti
- casi di frode, abuso o violazione dei Termini di Servizio

## 7. Valuta

Tutti i rimborsi sono emessi nella stessa valuta del pagamento originale. Le commissioni di conversione valutaria o le differenze di tasso di cambio applicate dalla banca o dal provider di pagamento non sono a carico del gestore.

## 8. Modifiche all'informativa

Il gestore può aggiornare la presente Informativa sui Rimborsi di volta in volta. Le modifiche saranno pubblicate su questa pagina con una data aggiornata.

## 9. Contatti

Per qualsiasi domanda relativa ai rimborsi, puoi contattare:

**info@placeful-app.com**


## Legal — imprint

# Dati del titolare

# Dati del titolare / Impressum

_Ultimo aggiornamento: 22/07/2026_

## 1. Dati del titolare

Il titolare e gestore dell'applicazione è **Andrea Faccioli**, con domicilio in **Via Madonnina 2505A, 40024, Castel S. Pietro Terme (BO), Italia**.

## 2. Sede legale

**Via Madonnina 2505A, 40024, Castel S. Pietro Terme (BO), Italia**

## 3. Codice fiscale

**FCCNDR89E12A944E**

## 4. Partita IVA

_P.IVA: da inserire — vedi config/legal.php_

## 5. PEC (Posta Elettronica Certificata)

_PEC: da inserire — vedi config/legal.php_

## 6. Codice Destinatario (SDI)

_Codice SDI: da inserire — vedi config/legal.php_

## 7. Registro delle Imprese / REA

Non iscritto al Registro delle Imprese — persona fisica. Qualora l'attività comporti ricavi rilevanti ai fini commerciali, sarà necessaria l'iscrizione e l'apertura di Partita IVA.

## 8. Contatti

- Email: **info@placeful-app.com**
- Telefono: **+39 351 3301200**

## 9. Responsabile

Il responsabile dell'applicazione e dei relativi contenuti è **Andrea Faccioli**.

## 10. Legge applicabile

Il presente avviso legale è disciplinato dalla legge italiana. Qualsiasi controversia sarà devoluta al foro competente di **Bologna**.


## Legal — cookie-policy

# Cookie Policy

# Cookie Policy

_Ultimo aggiornamento: 21/09/2026_

## 1. Introduzione

La presente Cookie Policy descrive i tipi di cookie e tecnologie simili utilizzati da **Placeful**, gestita da **Andrea Faccioli** (di seguito "Titolare"), nonché le modalità di gestione del consenso dell'utente.

Per "cookie" si intendono sia i cookie HTTP tradizionali sia altre tecnologie di tracciamento equivalenti (localStorage, sessionStorage, fingerprinting) ove applicabili.

## 2. Titolare del trattamento

Il Titolare del trattamento dei dati è **Andrea Faccioli**, con sede in **Via Madonnina 2505A, 40024, Castel S. Pietro Terme (BO), Italia**, Codice Fiscale **FCCNDR89E12A944E**, e-mail **info@placeful-app.com**.

## 3. Categorie di cookie utilizzate

**Stato attuale: nessun cookie opzionale è installato.** Le categorie sotto descrivono il quadro di consenso — oggi sono impostati solo cookie essenziali.

L'applicazione classifica i cookie in quattro categorie:

### Cookie essenziali (tecnici)

Necessari al corretto funzionamento dell'applicazione: autenticazione, sessione, sicurezza CSRF, preferenze di lingua e tema. Non richiedono consenso ai sensi dell'art. 122 del Codice Privacy (D.Lgs. 196/2003) e del GDPR.

Esempi:

- cookie di sessione e di autenticazione
- token CSRF
- cookie di consenso (`app_cookie_consent`) per memorizzare le preferenze espresse dall'utente

### Cookie funzionali

Migliorano l'esperienza ricordando preferenze e personalizzazioni. Vengono attivati solo previo consenso.

### Cookie analitici

Raccogliono informazioni aggregate sull'utilizzo dell'applicazione per migliorarne le prestazioni e l'usabilità. Vengono attivati solo previo consenso. Se gestiti da terze parti, si applicano le rispettive informative.

### Cookie marketing

Utilizzati per tracciare l'utente su più siti al fine di mostrare annunci pertinenti. Vengono attivati solo previo consenso.

## 4. Base giuridica

- Cookie essenziali: esecuzione di un contratto o adempimento di obblighi legali (art. 6, c. 1, lett. b e c del GDPR) e art. 122 del Codice Privacy.
- Cookie funzionali, analitici e marketing: consenso libero, specifico, informato e revocabile (art. 6, c. 1, lett. a del GDPR e art. 122 del Codice Privacy).

## 5. Modalità di consenso

Al primo accesso viene mostrato un banner che permette all'utente di:

- accettare tutti i cookie
- rifiutare tutti i cookie opzionali
- personalizzare le preferenze per singola categoria

Le preferenze vengono memorizzate nel cookie `app_cookie_consent` per un periodo di 180 giorni. L'utente può modificare le proprie preferenze in qualsiasi momento tramite il link "Preferenze cookie" presente nel footer.

Il consenso può essere revocato in qualsiasi momento senza pregiudizio della liceità del trattamento basato sul consenso prestato prima della revoca.

## 6. Cookie di terze parti

L'applicazione può integrare servizi di terze parti (es. login social tramite Google o Facebook, provider di pagamento, provider di e-mail transazionali) che possono impostare propri cookie. Tali servizi operano come titolari autonomi per i trattamenti effettuati attraverso le rispettive piattaforme.

Si invitano gli utenti a consultare le informative dei singoli provider:

- [Google Privacy Policy](https://policies.google.com/privacy)
- [Facebook Privacy Policy](https://www.facebook.com/privacy/policy)

### 6.1 Widget incorporato

Il widget di prenotazione può essere incorporato in siti di terze parti tramite iframe. All'interno dell'incorporamento la piattaforma imposta solo cookie tecnicamente necessari (sessione, registrazione del consenso) in forma partizionata (CHIPS) — funzionano nel contesto dell'incorporamento e non possono tracciare il visitatore tra siti diversi. I siti che incorporano il widget dovrebbero menzionarlo nella propria informativa sui cookie.

## 7. Gestione dei cookie tramite browser

L'utente può gestire o disabilitare i cookie direttamente tramite le impostazioni del browser. Si segnala che la disabilitazione dei cookie essenziali può compromettere il funzionamento dell'applicazione.

Informazioni su come gestire i cookie nei principali browser:

- [Google Chrome](https://support.google.com/chrome/answer/95647)
- [Mozilla Firefox](https://support.mozilla.org/kb/cookies-information-websites-store-on-your-computer)
- [Apple Safari](https://support.apple.com/guide/safari/manage-cookies-and-website-data-sfri11471/mac)
- [Microsoft Edge](https://support.microsoft.com/microsoft-edge/delete-cookies-in-microsoft-edge-63947706-40ac-c3b8-57b9-76a258fd7aca)

## 8. Periodo di conservazione

- i cookie essenziali di sessione vengono eliminati alla chiusura del browser, salvo quelli necessari al mantenimento della sessione persistente
- il cookie di consenso (`app_cookie_consent`) ha durata di 180 giorni
- gli altri cookie opzionali seguono le durate specifiche di ciascun provider, attivate solo previo consenso

## 9. Diritti dell'utente

Ai sensi del GDPR e del Codice Privacy, l'utente ha diritto di:

- accedere ai propri dati personali
- richiedere la rettifica o la cancellazione
- opporsi al trattamento o richiederne la limitazione
- revocare il consenso prestato
- proporre reclamo al Garante per la protezione dei dati personali

Per esercitare i diritti, scrivere a: **info@placeful-app.com**.

## 10. Modifiche

Il Titolare si riserva di aggiornare la presente Cookie Policy. Le modifiche saranno pubblicate su questa pagina con data di aggiornamento revisionata.


## Legal — dpa

# Addendum sul trattamento dei dati

# Accordo sul Trattamento dei Dati (DPA)

_Ultimo aggiornamento: 13/10/2026_

Il presente Accordo sul Trattamento dei Dati ("DPA") integra i Termini di Servizio tra **Andrea Faccioli** ("Responsabile del trattamento", gestore di Placeful) e ciascuna azienda che utilizza la piattaforma per gestire prenotazioni ("Titolare", l'"Azienda"). Si applica ogni volta che il Responsabile tratta dati personali per conto dell'Azienda nell'erogazione del servizio di prenotazione, ai sensi dell'**articolo 28 GDPR**.

Creando o utilizzando uno spazio aziendale, il legale rappresentante accetta il presente DPA per conto dell'Azienda.

## 1. Oggetto, ambito, durata

- **Oggetto:** hosting e gestione dello spazio di prenotazione dell'Azienda: eventi, disponibilità, prenotazioni, dati di contatto dei clienti finali, schede della rubrica clienti (CRM), richieste commerciali (lead), registri del personale (HR), notifiche (email, SMS/WhatsApp, web push), pagamenti tramite l'account Stripe Connect dell'Azienda.
- **Durata:** per tutto il tempo in cui l'Azienda utilizza la piattaforma, fatte salve le condizioni di cancellazione della Sezione 8.
- **Natura e finalità:** conservazione, organizzazione, visualizzazione, trasmissione (email, SMS/WhatsApp, widget incorporati, web push) e facilitazione dei pagamenti dei dati di prenotazione, esclusivamente secondo le istruzioni impartite tramite le funzionalità dell'applicazione.

## 2. Categorie di dati e interessati

- **Interessati:** clienti e ospiti dell'Azienda (chi prenota, i partecipanti, i contatti della rubrica clienti, i lead commerciali), il personale dell'Azienda (utenti e registri dipendenti).
- **Categorie di dati:** nomi, indirizzi email, numeri di telefono, dettagli delle prenotazioni (date, numero di persone, note inserite da chi prenota), dati del profilo in rubrica (tag, statistiche su visite/spesa, timestamp del consenso marketing, eventuali campi data di nascita/anniversario/dieta-allergie), messaggi delle richieste e documenti allegati, dati HR dei dipendenti (data di nascita, codice fiscale — conservato cifrato —, contratti, documenti, turni), metadati sullo stato dei pagamenti, endpoint delle sottoscrizioni push, dati di autenticazione degli utenti staff.
- **Categorie particolari:** la piattaforma non è progettata per categorie particolari di dati, con un'eccezione strutturata: la rubrica clienti offre un campo esplicito per dieta/allergie compilabile dai clienti tramite il locale. Per quel campo e per ogni altra categoria particolare che l'Azienda o i suoi clienti inseriscono volontariamente (es. esigenze di accessibilità nelle note), l'Azienda resta responsabile della base giuridica ai sensi dell'articolo 9 GDPR; il Responsabile li tratta unicamente su istruzione.

## 3. Obblighi del Responsabile

Il Responsabile si impegna a:

1. trattare i dati personali solo su istruzione documentata dell'Azienda, incluse questo DPA e l'uso delle funzionalità della piattaforma, salvo diverso obbligo di legge UE o nazionale;
2. garantire che le persone autorizzate al trattamento siano vincolate da obblighi di riservatezza;
3. attuare e mantenere le misure tecniche e organizzative descritte nella Sezione 9;
4. ricorrere a sub-responsabili solo tra quelli elencati nella Sezione 5, con obblighi equivalenti, e notificare all'Azienda le modifiche previste (l'Azienda può opporsi entro 14 giorni);
5. assistere l'Azienda, con misure tecniche adeguate, nell'evasione delle richieste degli interessati (accesso, rettifica, cancellazione, portabilità) — la piattaforma fornisce strumenti self-service di esportazione e cancellazione;
6. assistere l'Azienda nel garantire il rispetto degli artt. 32–36 GDPR (sicurezza, notifica delle violazioni, supporto DPIA) nei limiti ragionevolmente possibili;
7. notificare all'Azienda senza ingiustificato ritardo ogni violazione dei dati personali che riguardi dati dell'Azienda.

## 4. Obblighi del Titolare

L'Azienda garantisce che:

1. dispone di una base giuridica per il trattamento dei dati dei propri clienti raccolti tramite la piattaforma;
2. fornisce ai propri clienti una propria informativa privacy (la piattaforma offre un `privacy_url` configurabile mostrato ai clienti prima e dopo la prenotazione);
3. è responsabile dell'esattezza e liceità dei dati il cui trattamento impartisce alla piattaforma, incluse note di prenotazione e campi informativi personalizzati;
4. non utilizzerà la piattaforma per trattare dati che non è legittimata a trattare.

## 5. Sub-responsabili

L'Azienda autorizza i sub-responsabili elencati nell'Informativa Privacy della piattaforma (sezione "Destinatari dei dati" / elenco sub-responsabili), mantenuti in `config/legal.php`. Ogni modifica sarà notificata tramite l'applicazione; l'uso continuato dopo il periodo di preavviso costituisce accettazione.

Stripe agisce sull'account proprio dell'Azienda per l'elaborazione dei pagamenti; i dati di pagamento dei clienti dell'Azienda sono trattati nell'ambito del rapporto diretto tra l'Azienda e Stripe.

## 6. Trasferimenti internazionali

Qualora i sub-responsabili siano stabiliti fuori dal SEE, i trasferimenti sono coperti da decisioni di adeguatezza o Clausole Contrattuali Standard, secondo quanto previsto dalla sezione 8 dell'Informativa Privacy.

## 7. Verifiche e informazioni

Il Responsabile renderà disponibili le informazioni ragionevolmente necessarie a dimostrare la conformità al presente DPA (questo documento, le misure di sicurezza della Sezione 9, l'elenco dei sub-responsabili). Le verifiche in loco sono sostituite da questionari scritti e documentazione, salvo diversa richiesta dell'autorità di controllo.

## 8. Restituzione e cancellazione dei dati

- L'Azienda può esportare in qualsiasi momento prenotazioni e dati dei clienti tramite le funzionalità di esportazione della piattaforma.
- Alla cessazione dello spazio aziendale, i dati personali trattati per suo conto sono cancellati o anonimizzati entro **90 giorni**, salvo obblighi di conservazione di legge (es. registrazioni fiscali, art. 2220 c.c. — max 10 anni).
- I backup degli account eliminati si esauriscono secondo il normale ciclo di conservazione (vedi Informativa Privacy §9).

## 9. Misure tecniche e organizzative (TOM)

- TLS in transito; cookie di sessione `Secure`/`HttpOnly`; cookie partizionati (CHIPS) negli iframe incorporati
- Hashing delle password (bcrypt), 2FA (TOTP) e passkey opzionali per gli account staff; applicazione obbligatoria della configurazione di sicurezza per i ruoli privilegiati
- Token OAuth delle integrazioni di terze parti (Google Calendar) conservati cifrati a riposo
- Controllo degli accessi basato su ruoli e permessi all'interno di ogni spazio aziendale
- Registro cronologico (audit) delle azioni di creazione/modifica/cancellazione con attore, timestamp e IP; gli eventi di impersonificazione sono tracciati
- Backup notturni del database cifrati (AES-256) con conservazione limitata; riapplicazione delle cancellazioni in caso di ripristino
- Pulizia automatica della retention di log, righe di audit, thread email, payload webhook, log di utilizzo AI, thread dell'assistente e richieste commerciali obsolete
- Pipeline di anonimizzazione con periodo di grazia per account, schede della rubrica clienti, registri del personale e richieste eliminati (finestra di ripristino di 30 giorni, poi pseudonimizzazione irreversibile che preserva le registrazioni fiscali)
- Evasione automatica delle richieste pubbliche di cancellazione dati (corrispondenza di account utente e schede cliente per email, con avvisi al titolare sulle richieste in scadenza)
- Codici fiscali dei dipendenti cifrati a riposo; estratti dei prompt nei log AI mascherati per rimuovere email/numeri di telefono
- Sottoscrizioni alle notifiche push e pacchetti di eventi archiviati inclusi nella cancellazione (gli archivi cifrati vengono riscritti atomicamente per rimuovere le identità cancellate)
- Strumenti di esportazione (Art. 15) e cancellazione/anonimizzazione (Art. 17) integrati nell'applicazione

## 10. Responsabilità e prevalenza

La responsabilità è disciplinata dai Termini di Servizio. In caso di conflitto tra questo DPA e i Termini, prevale il DPA per le questioni di protezione dei dati.

## 11. Contatti

Contatto privacy del Responsabile: **info@placeful-app.com**.

Contatto dell'Azienda: l'email legale registrata nelle impostazioni dello spazio aziendale.


## Legal — accessibility

# Dichiarazione di accessibilità

# Dichiarazione di Accessibilità

_Ultimo aggiornamento: 21/09/2026_

**Placeful** si impegna a rendere la propria piattaforma di prenotazione accessibile a tutti gli utenti, in conformità con l'**European Accessibility Act (Direttiva (UE) 2019/882)** recepita in Italia dal **D.Lgs. 82/2022**, applicabile ai servizi di commercio elettronico — inclusi i flussi di prenotazione online — dal 28 giugno 2025.

## Obiettivo di conformità

L'applicazione mira alla conformità **WCAG 2.1 Livello AA**, includendo:

- flussi di prenotazione e widget navigabili da tastiera
- indicatori di focus visibili e nomi accessibili sui controlli interattivi
- contrasto cromatico sufficiente nei temi chiaro e scuro
- layout responsive utilizzabili da 320px e con zoom fino al 400%
- campi dei moduli con etichette associate e identificazione degli errori
- supporto alla riduzione del movimento dove sono presenti animazioni

## Limitazioni note

- Alcuni contenuti di terze parti (es. le pagine di pagamento incorporate servite da Stripe) non sono sotto il nostro controllo diretto.
- L'applicazione evolve continuamente; alcune viste meno recenti potrebbero non soddisfare ancora pienamente l'obiettivo di conformità.

## Feedback e ricorsi

Se incontri una barriera di accessibilità, contattaci — forniremo le informazioni in formato accessibile e correggeremo il problema:

- Email: **info@placeful-app.com**
- Telefono: **+39 351 3301200**

Ci impegniamo a rispondere alle segnalazioni di accessibilità entro **15 giorni**.

Se la risposta non è soddisfacente, è possibile presentare un reclamo all'autorità di vigilanza competente (in Italia: AgID — Agenzia per l'Italia Digitale, per i servizi in ambito EAA).


## Legal — trust

# Sicurezza e affidabilità

# Sicurezza e affidabilità

_Ultimo aggiornamento: 2026-10_

Questa pagina riassume come **Placeful** protegge i dati delle aziende che gestiscono le prenotazioni sulla piattaforma e dei loro clienti. I dettagli vincolanti sono nell'[Informativa privacy](/policy) e nel [Data Processing Agreement](/dpa).

## Hosting e posizione dei dati

- L'applicazione e i database girano sull'infrastruttura del provider indicato nell'elenco dei sub-responsabili dell'Informativa privacy (`config/legal.php`, pubblico).
- I dati personali risiedono su quell'infrastruttura; se un sub-responsabile è fuori dal SEE, i trasferimenti si basano su decisioni di adeguatezza o Clausole Contrattuali Standard (DPA §6).

## Cifratura

- **In transito:** TLS ovunque; cookie di sessione `Secure`/`HttpOnly`; il widget prenotazioni usa cookie partizionati CHIPS negli iframe.
- **A riposo:** token OAuth delle integrazioni (es. Google Calendar), codici fiscali dei dipendenti e credenziali API sono cifrati; i backup sono cifrati AES-256.
- **Password:** hashing bcrypt; i segreti non finiscono mai nei log né nell'audit trail.

## Sicurezza degli account

- Gli account del personale supportano **autenticazione a due fattori (TOTP)** e **passkey** (WebAuthn).
- Ogni azienda può rendere obbligatoria la configurazione di sicurezza per ruolo; i ruoli privilegiati devono completarla entro un periodo di grazia.
- Dispositivi attendibili, rotazione dei remember-token e revoca lato server delle sessioni sono integrati; il titolare può chiudere sessioni, token API e dispositivi attendibili di un membro dal centro sicurezza aziendale.

## Controllo accessi e tracciabilità

- Ogni spazio di lavoro è isolato per tenant: i membri vedono solo i dati della propria azienda, con controlli di ruolo/permesso su ogni query e azione.
- Accessi, esportazioni, cambi di ruolo, visualizzazioni delle schede ospite e modifiche ai record finiscono in un **registro attività** immutabile e leggibile dal titolare, con attore, timestamp e IP.
- I clienti dispongono di strumenti self-service GDPR: esportazione dati (art. 15), cancellazione/anonimizzazione con finestra di ripristino di 30 giorni (art. 17) e consenso per canale di notifica.

## Pagamenti

- I pagamenti passano da **Stripe Connect**: ogni azienda incassa sul proprio account Stripe. I dati delle carte sono raccolti da Stripe e non toccano mai i server di Placeful; la piattaforma conserva solo metadati sullo stato dei pagamenti.
- Stripe agisce come gestore dei pagamenti nel rapporto diretto con l'azienda — Placeful non detiene i dati delle carte dei clienti.

## Sub-responsabili

L'elenco aggiornato dei sub-responsabili (hosting, invio email, notifiche, funzioni AI dove attive) è mantenuto in `config/legal.php` e pubblicato nell'[Informativa privacy](/policy). Le aziende sono avvisate in anticipo delle modifiche e possono opporsi entro 14 giorni (DPA §5).

## Backup e disponibilità

- **Backup notturni del database cifrati** (AES-256) con retention limitata; le richieste di cancellazione vengono riapplicate ai dati ripristinati.
- La pulizia automatica limita la retention di log, righe di audit e archivi dei messaggi.

## Segnalare una vulnerabilità

Applichiamo una politica di divulgazione responsabile:

- Segnala i problemi di sicurezza a **info@placeful-app.com** (pubblicato anche in [`/.well-known/security.txt`](/.well-known/security.txt), RFC 9116).
- Non sfruttare una vulnerabilità oltre il necessario per dimostrarla, non accedere ai dati di altri tenant e concedici un tempo ragionevole per rimediare prima della divulgazione.
- Confermiamo la ricezione delle segnalazioni tempestivamente e riconosciamo il contributo dei ricercatori che seguono questa politica.


## Legal — terms-of-service

# Termini di servizio

# Termini di Servizio

_Ultimo aggiornamento: 21/09/2026_

## 1. Introduzione

I presenti Termini di Servizio disciplinano l’accesso e l’utilizzo di **Placeful**, gestita da **Andrea Faccioli**.

Registrandoti, accedendo all’applicazione o utilizzandone le funzionalità, accetti di essere vincolato dai presenti Termini.

Se non accetti i presenti Termini, non devi utilizzare l’applicazione.

## 2. Il servizio

L’applicazione consente agli utenti autenticati di accedere a uno o più spazi aziendali e ai relativi strumenti, che possono includere:

- gestione dell’account e del profilo
- gestione delle appartenenze aziendali
- assegnazione di ruoli e permessi
- gestione di eventi e risorse
- gestione di token API
- notifiche tecniche e comunicazioni di servizio

Il servizio può evolvere nel tempo e le funzionalità possono essere aggiunte, modificate, limitate o rimosse.

## 2.1 Piani a pagamento e fatturazione

Gli spazi aziendali possono essere offerti con piani gratuiti o a pagamento ("pacchetti").

- **I piani gratuiti** sono forniti senza costi e possono essere limitati nelle funzionalità o nell'utilizzo.
- **I piani a pagamento**, quando attivati, sono fatturati in anticipo con cadenza ricorrente (mensile o annuale) tramite Stripe e **si rinnovano automaticamente** fino a cancellazione.
- **Periodi di prova**: ove offerto un periodo di prova, il piano si converte in abbonamento a pagamento alla scadenza della prova salvo cancellazione preventiva.
- **Cancellazione**: è possibile cancellare un piano a pagamento in qualsiasi momento dalla sezione fatturazione; la cancellazione ha effetto al termine del periodo di fatturazione corrente. Non sono dovuti rimborsi parziali salvo obbligo di legge.
- **Variazioni di prezzo**: daremo un preavviso di almeno **30 giorni** prima di modificare il prezzo di un piano a pagamento; l'uso continuato dopo la data di efficacia costituisce accettazione, ed è possibile cancellare prima dell'applicazione.
- **Pagamenti non riusciti**: in caso di mancato pagamento ripetuto, le funzionalità a pagamento possono essere sospese fino a regolarizzazione.
- **Commissioni per prenotazione**: alcuni piani possono prevedere una commissione per prenotazione riscossa tramite application fee di Stripe Connect, indicata nella pagina dei prezzi prima dell'attivazione.

## 2.2 Aziende e dati dei clienti (DPA)

Ogni azienda è **titolare del trattamento** dei dati di prenotazione dei propri clienti; la piattaforma tratta tali dati in qualità di **responsabile** ai sensi del Data Processing Agreement pubblicato su `/dpa`, che è incorporato nei presenti Termini per ogni azienda ospitata.

Alla cessazione dello spazio aziendale, i dati dell'azienda sono restituiti (tramite gli strumenti di esportazione della piattaforma) e/o cancellati o anonimizzati entro 90 giorni, salvo obblighi di conservazione di legge (es. registrazioni fiscali).

## 3. Requisiti e responsabilità dell’account

Per registrarti e utilizzare l’applicazione devi avere almeno 16 anni. Se hai meno di 16 anni, puoi utilizzare l’applicazione solo con il consenso di un genitore o tutore legale, che accetta i presenti Termini per tuo conto.

Per utilizzare l’applicazione, devi fornire informazioni accurate, complete e aggiornate.

Sei responsabile di:

- mantenere riservate le tue credenziali di accesso
- tutte le attività effettuate tramite il tuo account
- garantire che l’utilizzo del servizio avvenga nel rispetto della legge applicabile e dei presenti Termini

Devi informare tempestivamente il gestore del servizio se ritieni che il tuo account sia stato utilizzato senza autorizzazione.

## 4. Modalità di autenticazione

L’applicazione può consentire l’autenticazione tramite:

- e-mail e password
- provider esterni di login social come Google e Facebook

Se scegli il login social, sei responsabile del mantenimento dell’accesso al relativo account esterno e della comprensione dei termini e delle regole privacy del provider.

## 5. Spazi aziendali, ruoli e permessi

L’applicazione può consentire agli utenti di appartenere a uno o più spazi aziendali.

L’accesso ai dati e alle funzionalità può dipendere da:

- azienda attiva selezionata dall’utente
- ruolo assegnato all’utente
- permessi concessi all’interno di quella specifica azienda

Gli utenti possono accedere, modificare o gestire esclusivamente le risorse per cui risultano autorizzati.

È severamente vietato tentare di aggirare i controlli di accesso, visualizzare contenuti non autorizzati o manipolare il sistema di permessi.

## 6. Uso consentito

Accetti di non:

- utilizzare l’applicazione per scopi illeciti, fraudolenti o abusivi
- interferire con il funzionamento, la stabilità o la sicurezza dell’applicazione
- tentare accessi non autorizzati ad account, aziende, dati, API o infrastruttura
- caricare, trasmettere o memorizzare codice dannoso o contenuti nocivi
- copiare, decodificare, aggirare o usare impropriamente il servizio oltre quanto consentito dalla legge
- utilizzare l’applicazione in modo da violare i diritti di altri utenti o di terzi

## 7. Responsabilità sui contenuti e sui dati

Rimani responsabile dei contenuti e dei dati che crei, carichi, gestisci o trasmetti tramite l’applicazione.

Dichiari e garantisci di avere il diritto di utilizzare tali contenuti e che essi non violano la legge applicabile né diritti di terzi.

Il gestore del servizio non rivendica diritti di proprietà sui contenuti dell’utente, salvo quanto necessario per ospitarli, elaborarli, memorizzarli, mostrarli e trasmetterli ai fini dell’erogazione del servizio.

## 8. Disponibilità e manutenzione

Il servizio è fornito “così com’è” e “secondo disponibilità”.

Pur adottando misure ragionevoli per garantirne l’affidabilità, il gestore non garantisce disponibilità continua o funzionamento privo di errori.

Il servizio può essere sospeso, limitato o interrotto per manutenzione, aggiornamenti, interventi di sicurezza, guasti infrastrutturali o cause fuori dal ragionevole controllo del gestore.

## 9. E-mail e comunicazioni di servizio

Utilizzando l’applicazione, riconosci che il servizio può inviare comunicazioni transazionali e operative necessarie per l’accesso all’account, la sicurezza, il reset password, gli inviti, le conferme e le notifiche tecniche.

Tali comunicazioni sono considerate parte integrante del servizio e potrebbero non essere disattivabili quando necessarie per il funzionamento o la sicurezza.

## 10. Token API e sicurezza

Se l’applicazione consente la creazione di token API, gli utenti sono esclusivamente responsabili di:

- generare token solo quando necessario
- conservarli in modo sicuro
- revocare token compromessi o non più utilizzati
- impedire divulgazioni non autorizzate

Il gestore può revocare o invalidare token quando necessario per motivi di sicurezza, prevenzione degli abusi o integrità del sistema.

## 11. Sospensione e cessazione

Il gestore può sospendere, limitare o terminare l’accesso al servizio, con o senza preavviso, quando ragionevolmente necessario, incluso in caso di:

- violazione dei presenti Termini
- uso improprio della piattaforma
- rischio per la sicurezza o l’integrità dell’applicazione
- obblighi legali o richieste da parte di autorità competenti

Gli utenti possono cessare di utilizzare il servizio in qualsiasi momento, fatti salvi eventuali obblighi contrattuali o legali di conservazione dei dati.

## 12. Proprietà intellettuale

L’applicazione, il suo design, il codice, la struttura, i marchi e i materiali correlati sono protetti dalle leggi applicabili in materia di proprietà intellettuale.

Salvo quanto espressamente consentito, non viene concessa alcuna licenza o diritto di copiare, modificare, distribuire o sfruttare qualsiasi parte del servizio oltre quanto necessario al normale utilizzo.

## 13. Limitazione di responsabilità

Nella misura massima consentita dalla legge applicabile, il gestore non sarà responsabile per danni indiretti, incidentali, consequenziali o speciali, inclusi perdita di dati, interruzione dell’attività, mancato guadagno o incidenti di sicurezza derivanti da uso improprio, azioni di terzi o circostanze fuori dal ragionevole controllo del gestore.

Nulla nei presenti Termini esclude responsabilità laddove tale esclusione non sia consentita dalla legge.

## 14. Privacy

I dati personali sono trattati in conformità con la Privacy Policy dell’applicazione.

Utilizzando il servizio, riconosci che alcuni dati tecnici e personali devono essere trattati per consentire autenticazione sicura, controllo accessi basato sulle aziende, logging tecnico e comunicazioni di servizio.

## 14.1 Diritti dei consumatori (D.Lgs. 206/2005 — Codice del Consumo)

Se l’utente agisce come consumatore (persona fisica che agisce per scopi estranei all’attività imprenditoriale o professionale eventualmente svolta), si applicano i diritti previsti dal Codice del Consumo italiano (D.Lgs. 206/2005), in particolare:

- **Diritto di recesso**: per i contratti a distanza stipulati tramite la piattaforma, l’utente ha diritto di recedere dal contratto entro **14 giorni** dalla data di conclusione del contratto o di erogazione del servizio, senza dover fornire alcuna motivazione e senza penalità, fatti salvi i casi di esclusione previsti dall’articolo 59 del Codice del Consumo.
- Per esercitare il diritto di recesso, l’utente può inviare una comunicazione a **info@placeful-app.com** indicando la volontà di recedere dal contratto e il riferimento della prenotazione o del servizio.
- Le modalità di rimborso in caso di recesso sono disciplinate dalla **Informativa sui Rimborsi** della piattaforma.
- **Informazioni precontrattuali**: l’utente ha diritto a ricevere, prima della conclusione del contratto, le informazioni essenziali sull’identità del gestore, sulle caratteristiche del servizio, sul prezzo, sulle modalità di pagamento e sul diritto di recesso, come previsto dall’articolo 13 del Codice del Consumo.

Per le prenotazioni effettuate presso un’azienda ospitata, il rapporto contrattuale si instaura tra l’utente e l’azienda ospitata, che è responsabile degli obblighi di informazione e del rispetto dei diritti del consumatore per la propria parte. Si noti che per i servizi di svago prenotati per una data o un periodo specifico, il diritto di recesso legale può non essere applicabile (art. 59, comma 1, lett. n) del Codice del Consumo); le condizioni di rimborso dell'azienda disciplinano le cancellazioni.

**Foro per i consumatori**: se l'utente agisce come consumatore, è competente in via obbligatoria il giudice del luogo di residenza o domicilio del consumatore (art. 66-bis Codice del Consumo), in deroga alla clausola generale sul foro che segue.

## 15. Modifiche al servizio o ai Termini

Il gestore può aggiornare i presenti Termini di volta in volta per riflettere modifiche legali, tecniche o organizzative.

Quando opportuno, gli utenti potranno essere informati delle modifiche rilevanti tramite l’applicazione o con altri mezzi ragionevoli.

L’uso continuato del servizio dopo l’entrata in vigore delle modifiche costituisce accettazione dei Termini aggiornati, salvo quanto diversamente richiesto dalla legge applicabile.

## 16. Legge applicabile e foro competente

I presenti Termini sono disciplinati dalla legge di **Italia**, salvo l’applicazione di norme inderogabili diverse in base allo status o alla localizzazione dell’utente.

Qualsiasi controversia relativa ai presenti Termini sarà devoluta alla competenza del foro di **Bologna**, salvo diversa previsione inderogabile di legge.

## 17. Contatti

Per domande relative ai presenti Termini, puoi contattare:

**info@placeful-app.com**

## Legal — privacy-policy

# Informativa sulla privacy

# Informativa sulla Privacy

_Ultimo aggiornamento: 13/10/2026_

## Avviso importante

La presente Informativa sulla Privacy descrive le modalità con cui vengono trattati i dati personali nell’ambito dell’accesso all’applicazione, della gestione dell’account, degli spazi aziendali, dell’autenticazione, dei log tecnici, dei cookie e delle comunicazioni automatiche di servizio.

Questo documento deve essere completato con i dati reali del Titolare del trattamento e verificato da un professionista legale prima della pubblicazione in produzione.

## 1. Titolare del trattamento

Il Titolare del trattamento è **Andrea Faccioli**, con sede in **Via Madonnina 2505A, 40024, Castel S. Pietro Terme (BO), Italia**, Codice Fiscale **FCCNDR89E12A944E**, e-mail di contatto **info@placeful-app.com**.

Per qualsiasi richiesta relativa alla privacy o al trattamento dei dati personali, gli utenti possono scrivere a: **info@placeful-app.com**.

## 2. Dati personali trattati

A seconda delle modalità di utilizzo dell’applicazione, possono essere trattate le seguenti categorie di dati personali:

- Dati di account, come nome, indirizzo e-mail, password cifrata ed eventuale immagine del profilo
- Dati relativi alle aziende, come nome dell’azienda, appartenenze dell’utente, ruolo interno e permessi assegnati
- Dati di autenticazione e sicurezza, inclusi sessioni attive, timestamp di accesso, token API e log relativi alla sicurezza
- Dati ricevuti tramite login social da Google o Facebook, come identificativo del provider, nome, indirizzo e-mail ed eventuale immagine del profilo
- Dati tecnici di log, come indirizzo IP, user agent, URL richiesto, timestamp e informazioni diagnostiche sugli errori
- Dati relativi alle e-mail automatiche di servizio inviate tramite infrastruttura SMTP
- Ricevute di consenso — registrazioni dei documenti legali accettati (termini, privacy), della scelta di opt-in/opt-out marketing e delle preferenze sui cookie, con timestamp, versione del documento, indirizzo IP e user agent
- Richieste di cancellazione dei dati inviate tramite la pagina `/data-deletion` (indirizzo e-mail, stato della richiesta, timestamp)
- Dati di prenotazione inseriti prenotando tramite il widget di un'azienda — nome, e-mail, telefono, note ed eventuali campi personalizzati definiti dall'azienda
- Dati della rubrica clienti (CRM) che un'azienda mantiene sui propri clienti — nome, e-mail, telefono, statistiche su visite/spesa, tag, note, timestamp del consenso marketing, ed eventualmente data di nascita, anniversario e informazioni su dieta/allergie condivise dal cliente con il locale
- Dati dei lead commerciali (richieste) inviati a un'azienda — nome, e-mail, telefono, dettagli dell'evento e messaggi liberi, oltre a note del personale e documenti di proposta allegati alla richiesta
- Dati del personale (HR) che un'azienda registra sui propri dipendenti — nome, contatti, data di nascita, codice fiscale (conservato cifrato), contatti di emergenza, contratti, documenti, turni e timbrature
- Dati di sottoscrizione alle notifiche push — URL endpoint del browser e chiavi usati per recapitare le notifiche web-push ai dispositivi dell'utente
- Dati delle notifiche SMS/WhatsApp — numero di telefono e metadati del messaggio necessari a recapitare le notifiche di prenotazione tramite il provider configurato

L’applicazione non è destinata al trattamento di categorie particolari di dati personali, **ad eccezione** delle informazioni su dieta/allergie che il cliente fornisce volontariamente al locale nella rubrica clienti — tali dati sono conferiti al locale (titolare) e trattati su sua istruzione. Ogni altra categoria particolare di dati è limitata a quanto gli utenti inseriscano volontariamente nei contenuti gestiti nel sistema.

### 2.1 Dati di fatturazione delle aziende ospitate

Per le aziende ospitate che attivano abbonamenti a pagamento o che utilizzano il sistema di pagamento Stripe Connect, la piattaforma tratta i seguenti dati di fatturazione dell’azienda:

- ragione sociale o nome dell’azienda
- Partita IVA o codice fiscale dell’azienda
- indirizzo della sede legale
- codice destinatario (SDI) e indirizzo PEC per la fatturazione elettronica
- importo delle commissioni applicate e dei canoni di abbonamento
- dati di transazione Stripe (identificativo conto, stato degli addebiti)

**Base giuridica:** esecuzione di un contratto ai sensi dell’articolo 6, paragrafo 1, lettera b) del GDPR e adempimento di obblighi legali (fatturazione, art. 6, c. 1, lett. c) del GDPR e D.P.R. 633/1972).

Tali dati sono conservati per i termini previsti dalla normativa fiscale italiana (10 anni per le fatture, art. 2220 Codice Civile).

## 3. Finalità e basi giuridiche

I dati personali possono essere trattati per le seguenti finalità:

### Creazione dell’account e utilizzo dell’applicazione

Per consentire agli utenti di registrarsi, autenticarsi, gestire il proprio account, accedere agli spazi aziendali, usare le funzionalità dell’applicazione e interagire con le risorse disponibili in base ai permessi assegnati.

**Base giuridica:** esecuzione di un contratto o misure precontrattuali ai sensi dell’articolo 6, paragrafo 1, lettera b) del GDPR.

### Gestione di ruoli, appartenenze e permessi

Per associare gli utenti a una o più aziende, definire ruoli, assegnare permessi e applicare regole di controllo degli accessi all’interno dell’applicazione.

**Base giuridica:** esecuzione di un contratto ai sensi dell’articolo 6, paragrafo 1, lettera b) del GDPR e interesse legittimo ai sensi dell’articolo 6, paragrafo 1, lettera f) del GDPR per ragioni di sicurezza e organizzazione interna.

### Sicurezza tecnica e prevenzione degli abusi

Per proteggere la piattaforma, rilevare anomalie, analizzare errori, prevenire utilizzi impropri e mantenere affidabile il servizio.

**Base giuridica:** interesse legittimo ai sensi dell’articolo 6, paragrafo 1, lettera f) del GDPR.

### Invio di e-mail automatiche di servizio

Per inviare e-mail di verifica account, reset password, inviti, notifiche di sicurezza e altre comunicazioni operative.

**Base giuridica:** esecuzione di un contratto ai sensi dell’articolo 6, paragrafo 1, lettera b) del GDPR e interesse legittimo ai sensi dell’articolo 6, paragrafo 1, lettera f) del GDPR.

### Login social

Per autenticare l’utente tramite Google o Facebook, quando l’utente sceglie volontariamente tale modalità di accesso.

**Base giuridica:** esecuzione di un contratto ai sensi dell’articolo 6, paragrafo 1, lettera b) del GDPR.

### Adempimenti di legge

Per adempiere a obblighi legali, fiscali, amministrativi o giudiziari.

**Base giuridica:** adempimento di un obbligo legale ai sensi dell’articolo 6, paragrafo 1, lettera c) del GDPR.

### Cookie opzionali o futuri strumenti di analisi

Qualora vengano attivati cookie opzionali o strumenti di analytics non essenziali, questi saranno utilizzati solo dove richiesto e solo previo consenso valido.

**Base giuridica:** consenso ai sensi dell’articolo 6, paragrafo 1, lettera a) del GDPR.

### Comunicazioni di marketing (facoltative)

Se l'utente aderisce (in registrazione o dalle impostazioni del profilo), possiamo inviare aggiornamenti commerciali sul servizio. Il consenso è registrato con timestamp e versione del documento, ed è revocabile in qualsiasi momento dal profilo — la revoca interrompe i messaggi futuri e non pregiudica la liceità dei trattamenti precedenti.

**Base giuridica:** consenso ai sensi dell’articolo 6, paragrafo 1, lettera a) del GDPR.

### Widget incorporato su siti di terze parti

Quando si prenota tramite un widget incorporato nel sito di un'azienda, il widget viene eseguito in un iframe servito da questa piattaforma. I cookie tecnicamente necessari (sessione, registrazione del consenso) sono impostati in forma partizionata (CHIPS) in modo da funzionare all'interno dell'incorporamento senza tracciare l'utente tra siti diversi. Il sito ospitante è responsabile dell'informativa sull'incorporamento; l'azienda che lo gestisce è titolare dei dati di prenotazione (vedi §6.1).

## 4. Login social e API di Google

Gli utenti possono accedere tramite **Google** o **Facebook**. In tal caso, l’applicazione riceve solo i dati necessari a identificare l’utente e creare o collegare l’account locale, sulla base dei permessi concessi al provider.

Google e Facebook operano come titolari autonomi per i trattamenti effettuati attraverso le rispettive piattaforme, inclusi i propri cookie e la propria infrastruttura di autenticazione.

Gli utenti dovrebbero consultare anche le informative privacy dei rispettivi provider:

- [Informativa sulla privacy di Google](https://policies.google.com/privacy)
- [Informativa sulla privacy di Facebook](https://www.facebook.com/privacy/policy)

### 4.1 Dati Google: a cosa accediamo e come li usiamo

L’applicazione richiede i seguenti ambiti (scope) OAuth di Google:

- **`openid`, `email`, `profile`** — usati per autenticare gli utenti tramite Google Sign-In e per creare o collegare l’account locale (nome, indirizzo e-mail, immagine del profilo).
- **`calendar.events`** (lettura e scrittura) — concesso solo quando un membro dello staff collega esplicitamente il proprio Google Calendar. Usato per:
  - leggere gli eventi del calendario dell’utente che ha effettuato il collegamento, per mostrarli accanto alle prenotazioni della piattaforma e rilevare conflitti di orario;
  - creare, aggiornare ed eliminare eventi di calendario che replicano le prenotazioni confermate sul calendario scelto dall’utente;
  - inviare al cliente che prenota le e-mail di invito e cancellazione gestite da Google per l’evento replicato.
- **`calendar.calendarlist.readonly`** — usato per elencare i calendari dell’utente che ha effettuato il collegamento, così che possa scegliere su quale calendario scrivere gli eventi delle prenotazioni.

I dati Google dell’utente vengono utilizzati esclusivamente per le finalità sopra descritte e solo dopo che l’utente ha prestato il consenso nella schermata di autorizzazione di Google.

### 4.2 Come vengono conservati i dati Google

- I token OAuth di accesso e di refresh per la connessione al calendario sono conservati sui nostri server, associati esclusivamente all’account del membro dello staff che ha effettuato il collegamento.
- I dati degli eventi di Google Calendar vengono recuperati su richiesta e mantenuti in cache per pochi minuti a fini di visualizzazione; non vengono conservati in modo permanente.
- Per ogni prenotazione replicata conserviamo l’identificativo dell’evento Google, per mantenere la replica sincronizzata in caso di aggiornamenti e cancellazioni.

### 4.3 Condivisione, trasferimento e Limited Use

- I dati Google degli utenti **non vengono mai venduti, ceduti o condivisi** con terze parti e **non vengono mai utilizzati per finalità pubblicitarie** né per scopi estranei all’erogazione del servizio di prenotazione.
- I dati di Google Calendar sono visibili esclusivamente al membro dello staff che ha collegato il proprio calendario.
- L’uso e il trasferimento verso qualsiasi altra app delle informazioni ricevute dalle API di Google sono conformi alle [Norme sui dati utente dei servizi API di Google](https://developers.google.com/terms/api-services-user-data-policy), inclusi i requisiti di Limited Use.

### 4.4 Revoca dell’accesso e cancellazione dei dati Google

- I membri dello staff possono scollegare Google Calendar in qualsiasi momento dalla pagina di amministrazione del calendario; la disconnessione elimina i token OAuth conservati e interrompe ogni sincronizzazione.
- L’accesso può essere revocato anche dalla pagina delle autorizzazioni dell’account Google (<https://myaccount.google.com/permissions>). Dopo la revoca la connessione viene contrassegnata come non più valida e non viene effettuato alcun ulteriore accesso ai dati.
- Per richiedere la cancellazione dei dati residui, scrivere a **info@placeful-app.com** o utilizzare la [pagina di cancellazione dei dati](/data-deletion).

## 5. E-mail e consegna SMTP

L’applicazione può inviare e-mail automatiche di servizio, come:

- e-mail di verifica account
- e-mail di reimpostazione password
- inviti
- avvisi di sicurezza
- notifiche operative relative all’account o allo spazio aziendale

Queste e-mail vengono inviate tramite infrastruttura SMTP configurata o tramite un provider equivalente di e-mail transazionali.

Il trattamento può includere:

- indirizzo e-mail del destinatario
- metadati di consegna
- timestamp di invio
- esito della consegna o dell’errore

Tale trattamento è limitato a quanto necessario per il funzionamento del servizio, il supporto tecnico e la sicurezza.

## 6. Log tecnici e log viewer

L’applicazione mantiene log tecnici e diagnostici per garantire la stabilità del sistema, rilevare errori, analizzare anomalie e proteggere la piattaforma da usi impropri o accessi non autorizzati.

Se è attivo un log viewer, l’accesso ai contenuti dei log deve essere limitato esclusivamente al personale autorizzato.

I log possono contenere dati tecnici e di sicurezza, come:

- indirizzo IP
- percorso o URL richiesto
- timestamp
- browser / user agent
- messaggi di errore
- identificativo dell’utente autenticato, ove applicabile

I log devono essere configurati in modo da evitare l’esposizione non necessaria di contenuti riservati o di dati personali eccedenti.

## 6.1 Piattaforma multi-tenant e ruoli dei titolari

Placeful è una piattaforma multi-tenant: ogni azienda ospitata (di seguito "azienda") utilizza lo spazio a sé riservato per gestire i propri eventi, le proprie prenotazioni e i propri clienti.

Si distingue tra:

- **Titolare della piattaforma** (Andrea Faccioli): tratta i dati degli utenti della piattaforma (account, autenticazione, appartenenze, log tecnici, sicurezza) per l’erogazione e la manutenzione del servizio.
- **Aziende ospitate**: ciascuna azienda agisce come **titolare autonomo** del trattamento per i dati dei propri clienti raccolti tramite le funzionalità della piattaforma (prenotazioni, dati di contatto del cliente finale, comunicazioni relative all’evento). Ogni azienda è responsabile della propria informativa privacy nei confronti dei propri clienti e del rispetto degli obblighi GDPR applicabili.

Laddove un’azienda ospitati elabori pagamenti tramite un proprio account Stripe Connect, l’azienda è titolare del trattamento anche per i dati di pagamento dei propri clienti, secondo i termini del proprio rapporto con Stripe.

Per i dati lato locale — rubrica clienti, richieste commerciali, registri del personale — la piattaforma agisce come **responsabile del trattamento** ai sensi dell’articolo 28 GDPR, su istruzione documentata di ciascuna azienda (vedi il Data Processing Agreement su `/dpa`). La piattaforma fornisce gli strumenti di cancellazione e conservazione descritti alla Sezione 9 affinché ogni azienda possa rispettare i propri obblighi; la cancellazione di una scheda cliente anonimizza i dati personali sottostanti dopo una finestra di ripristino di 30 giorni.

Gli utenti che effettuano una prenotazione presso un’azienda ospitata devono fare riferimento all’informativa privacy dell’azienda stessa, ove disponibile, per i trattamenti effettuati dall’azienda. La presente informativa copre esclusivamente i trattamenti effettuati dal Titolare della piattaforma.

## 7. Destinatari dei dati

I dati personali possono essere trattati da:

- personale interno autorizzato
- amministratori e operatori tecnici incaricati della manutenzione dell’applicazione
- fornitori terzi coinvolti nell’hosting, nella gestione dell’infrastruttura, nella consegna SMTP, nei servizi di autenticazione, nel monitoraggio della sicurezza e nella manutenzione

In particolare, i seguenti fornitori operano come Responsabili del trattamento ai sensi dell’articolo 28 del GDPR o, ove indicato, come titolari autonomi:

:subprocessors

- **Google LLC / Facebook (Meta Platforms, Inc.)** — provider di autenticazione social, operanti come titolari autonomi per i trattamenti effettuati attraverso le rispettive piattaforme
- **Provider di hosting e infrastruttura** — individuati nella documentazione contrattuale del gestore
- **Provider di consegna e-mail transazionali (SMTP)** — configurati per ciascuna installazione

Le funzionalità AI (assistente in-app, coordinatore di prenotazioni via e-mail, triage dei feedback), quando abilitate, trattano i contenuti di utenti e clienti tramite il provider AI elencato sopra — vincolato da un accordo sul trattamento dei dati e mai autorizzato a usare i dati per addestrare modelli. Le funzionalità AI sono attualmente disattivate salvo annuncio esplicito nell'applicazione.

Tali soggetti sono vincolati da adeguate garanzie contrattuali. L'elenco dei sub-responsabili è mantenuto aggiornato; le aziende ospitate sono informate delle modifiche come previsto dal Data Processing Agreement disponibile su `/dpa`.

## 8. Trasferimenti internazionali

Se uno dei fornitori coinvolti nell’hosting, nell’invio e-mail, nell’autenticazione o nell’infrastruttura si trova al di fuori dello Spazio Economico Europeo, i dati personali potranno essere trasferiti all’esterno del SEE solo nel rispetto degli articoli 44 e seguenti del GDPR, mediante garanzie adeguate, come decisioni di adeguatezza o Clausole Contrattuali Standard.

## 9. Periodo di conservazione

I dati personali sono conservati solo per il tempo necessario alle finalità sopra descritte. Finestre di conservazione applicate:

| Dati | Conservazione |
|---|---|
| Dati di account e azienda | Durata del rapporto di servizio; anonimizzati 30 giorni dopo la cancellazione dell'account |
| Registrazioni di prenotazione e dettagli fiscali | 10 anni ove richiesto dalla normativa fiscale (art. 2220 c.c., D.P.R. 633/1972); l'identità di chi prenota è pseudonimizzata in caso di cancellazione |
| Cronologia dei record (audit trail) | 24 mesi, poi eliminata |
| Thread e-mail di prenotazione in ingresso | 12 mesi, poi eliminati |
| Payload dei webhook di pagamento | 90 giorni, poi eliminati |
| Ricevute di invio delle notifiche | fino a 24 mesi, poi eliminate |
| Log tecnici e di sicurezza | il periodo minimo necessario a manutenzione e sicurezza; accesso al log viewer limitato al personale autorizzato |
| Ricevute di consenso | conservate per la durata del trattamento che provano (ricevute di ospiti: max 10 anni) |
| Richieste di cancellazione | conservate come prova di conformità; contenuto pseudonimizzato una volta evase |
| Schede della rubrica clienti (CRM) | finché l'azienda non le elimina; dati personali anonimizzati 30 giorni dopo la cancellazione, o subito su richiesta di cancellazione verificata |
| Richieste commerciali (lead) | anonimizzate 30 giorni dopo l'eliminazione, o automaticamente ~24 mesi dopo la creazione se il lead non si è mai convertito |
| Registri del personale (HR) | anonimizzati 30 giorni dopo l'eliminazione del record; contratti e cedolini restano nella conservazione fiscale del datore di lavoro |
| Registro di utilizzo AI (estratti dei prompt, tracce degli strumenti) | 12 mesi, poi eliminato; gli estratti sono mascherati per rimuovere e-mail/telefoni |
| Thread della chat dell'assistente | 6 mesi, poi eliminati |
| Sottoscrizioni alle notifiche push | finché rimosse dall'utente/browser o finché l'account non viene cancellato |
| Dati di consegna SMS/WhatsApp | metadati di consegna conservati secondo il provider; i numeri di telefono dei destinatari transitano solo al momento dell'invio |
| Cookie di consenso | 180 giorni |
| Backup cifrati | notturni, cifrati (AES-256), esauriti entro ~3 settimane; in caso di ripristino le cancellazioni pendenti sono riapplicate |

Al termine del periodo applicabile, i dati personali sono cancellati o anonimizzati, salvo che un’ulteriore conservazione sia richiesta dalla legge.

## 10. Diritti dell’utente

Ai sensi del GDPR, gli utenti possono avere il diritto di:

- accedere ai propri dati personali
- richiedere la rettifica dei dati inesatti
- richiedere la cancellazione dei dati personali
- richiedere la limitazione del trattamento
- opporsi al trattamento, ove applicabile
- ricevere i dati in formato portabile, ove applicabile
- revocare in qualsiasi momento il consenso prestato per trattamenti opzionali

Strumenti self-service disponibili nell'applicazione:

- **Esporta i tuoi dati (Art. 15):** Profilo → esportazione dati personali (JSON con account, prenotazioni, sessioni, token, preferenze, consensi e altro).
- **Elimina il tuo account (Art. 17):** Profilo → elimina account. La cancellazione è immediata; i dati personali nelle registrazioni storiche sono anonimizzati dopo un periodo di grazia di 30 giorni per il ripristino, salvo i dati da conservare per legge (es. registrazioni fiscali).
- **Ospiti / senza login:** invia una richiesta su `/data-deletion` — riceverai un codice di tracciamento; la pipeline automatica anonimizza le schede cliente corrispondenti (e avvia il flusso di cancellazione account se l'e-mail appartiene a un utente registrato), e la pagina di stato mostra l'esito una volta evasa la richiesta.
- **Consenso cookie:** link "Preferenze cookie" nel footer.

Le richieste possono anche essere inviate a: **info@placeful-app.com**.

Gli utenti hanno inoltre il diritto di proporre reclamo all’Autorità di controllo competente (in Italia: Garante per la protezione dei dati personali — <https://www.garanteprivacy.it>; altrove nell'UE: l'autorità locale).

### Utenti al di fuori di UE/SEE

A seconda della residenza, possono applicarsi diritti obbligatori aggiuntivi (es. UK GDPR per i residenti nel Regno Unito, leggi statali USA sulla privacy). Onoriamo le richieste di accesso e cancellazione alle stesse condizioni indipendentemente dalla posizione — contattare l'indirizzo sopra. I trasferimenti di dati personali al di fuori del SEE avvengono solo con le garanzie descritte nella Sezione 8.

## 11. Cookie

L’applicazione utilizza cookie essenziali necessari per la gestione della sessione, l’autenticazione, la protezione CSRF e le preferenze tecniche, nonché cookie opzionali suddivisi in categorie (funzionali, analitici, marketing) che vengono attivati solo previo consenso dell’utente tramite il banner di consenso visualizzato al primo accesso.

A titolo esemplificativo, i cookie utilizzati includono:

| Cookie | Finalità | Tipo |
|---|---|---|
| `XSRF-TOKEN` | Protezione CSRF | Essenziale |
| `laravel_session` / `app_session` | Gestione della sessione autenticata | Essenziale |
| `remember_web_*` | Accesso persistente se è attiva l’opzione “ricordami” | Essenziale |
| `app_cookie_consent` | Memorizza la scelta dell’utente sui cookie (180 giorni) | Essenziale / registrazione preferenza |

I cookie opzionali (funzionali, analitici, marketing) sono disattivati per impostazione predefinita e vengono attivati solo se l’utente presta il proprio consenso tramite il banner. L’utente può modificare o revocare il consenso in qualsiasi momento tramite il link "Preferenze cookie" presente nel footer.

Se l’utente sceglie il login social, Google o Facebook possono impostare propri cookie sotto la loro responsabilità autonoma.

Per informazioni dettagliate sui cookie e sulla gestione del consenso, consultare la **Cookie Policy** dedicata.

## 12. Modifiche alla presente Informativa

La presente Informativa sulla Privacy può essere aggiornata periodicamente per riflettere modifiche legali, tecniche o organizzative.

Eventuali aggiornamenti sostanziali potranno essere comunicati tramite l’applicazione o con altri mezzi appropriati.