# Strumenti · Visitatori

> Gli strumenti MCP del modulo Visitatori (coworking): registrare, elencare, leggere, modificare e annullare ospiti, gli attesi di oggi, cercare l'ospitante e segnare o annullare l'arrivo alla reception.

Il modulo [Visitatori](/espacos/visitantes) tramite l'assistente: registrare l'ospite in anticipo, modificare e annullare, vedere chi è atteso oggi alla reception e segnare l'arrivo con avviso all'ospitante. Il chiosco del visitatore è una schermata dell'iPad; l'assistente **non** lo usa.

Ogni strumento ha un'etichetta: <span class="tool-kind tool-kind-read">Solo lettura</span> non cambia nulla, <span class="tool-kind tool-kind-write">Modifica</span> crea o cambia qualcosa subito, e <span class="tool-kind tool-kind-confirm">Chiede conferma</span> agisce solo dopo il tuo sì a un riepilogo. Vedi [Denaro e conferma](/mcp/dinheiro-e-confirmacao).

## In breve

| Strumento | Cosa fa | Ruolo minimo | Tipo |
|---|---|---|---|
| [`create_visitor_invitation`](#create-visitor-invitation) | Registra un ospite | Chiunque abbia accesso allo spazio (la configurazione può limitare); il team, a nome di un altro ospitante | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`list_visitor_invitations`](#list-visitor-invitations) | Elenca e cerca gli ospiti | Qualsiasi (il membro vede i propri) | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`get_visitor_invitation`](#get-visitor-invitation) | Una registrazione | Proprietario della registrazione o team | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`update_visitor_invitation`](#update-visitor-invitation) | Modifica prima dell'arrivo | Proprietario della registrazione o team | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`cancel_visitor_invitation`](#cancel-visitor-invitation) | Annulla una registrazione | Proprietario della registrazione o team | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`list_visitors_today`](#list-visitors-today) | Gli attesi e gli arrivati di oggi | Moderatore o finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`search_visitor_hosts`](#search-visitor-hosts) | Trova l'ospitante | Moderatore o finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`mark_visitor_arrived`](#mark-visitor-arrived) | Segna l'arrivo | Moderatore o finanza | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`undo_visitor_arrival`](#undo-visitor-arrival) | Annulla un arrivo | Moderatore o finanza | <span class="tool-kind tool-kind-write">Modifica</span> |

I ruoli sono quelli delle rotte: l'assistente non fa mai più di quanto farebbe sulla schermata la persona collegata. Il team, qui, è il proprietario, l'amministratore, il moderatore e la finanza; il moderatore e la finanza agiscono **solo sugli ospiti di oggi**. Lo spazio si crea con [`create_space`](/mcp/ferramentas-comunidade#create-space) e `module: "visitors"`; [`update_space`](/mcp/ferramentas-comunidade#update-space) cambia solo ciò che invii.

## La configurazione dello spazio

L'argomento `visitors` di `create_space` e `update_space` accetta:

| Campo | Tipo | Descrizione |
|---|---|---|
| `attendance_space_id` | id | Lo spazio [Presenze](/mcp/ferramentas-presenca) in cui vengono registrati gli arrivi. Obbligatorio alla creazione (`list_spaces`) |
| `who_can_invite` | `members`, `staff` o `group` | Chi registra: qualsiasi membro con accesso, solo il team, o il gruppo di `inviter_group_id` più il team |
| `inviter_group_id` | id o `null` | Il gruppo di chi registra (`list_groups`); obbligatorio con `group` |
| `fields` | `{company, email, phone}`, ciascuno `off`, `optional` o `required` | Cosa chiede il modulo sull'ospite |
| `notify_host_on_register` | vero o falso | Conferma la registrazione all'ospitante via e-mail (predefinito: sì) |
| `email_guest` | `off`, `optional` o `always` | L'[e-mail all'ospite](/espacos/visitantes#e-mail-all-ospite) (predefinito: `off`) |
| `arrival_instructions` | testo fino a 500 caratteri, o `null` | Dove andare e per chi chiedere |
| `max_expected_per_host_per_day` | da 1 a 1000, o `null` | Limite di ospiti per ospitante al giorno |

## `create_visitor_invitation`

<span class="tool-kind tool-kind-write">Modifica</span>

**Registrare un ospite.** Non crea un account per l'ospite. Chi la configurazione lo permette registra per sé; il team passa `host_profile_id` per registrare a nome di un altro. Azienda, e-mail e telefono seguono la configurazione (un campo disattivato viene ignorato; uno obbligatorio mancante viene rifiutato). L'ospitante può ricevere un'e-mail di conferma e l'ospite un'altra, secondo `notify_guest` e la configurazione; l'assistente avvisa la persona. Sono dati personali di una terza persona. *Ruolo: qualsiasi con accesso allo spazio.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | Lo spazio Visitatori |
| `guest_name` | testo | Sì | Fino a 100 caratteri |
| `expected_date` | `AAAA-MM-GG` | Sì | Nel fuso della community; non può essere passato |
| `start_time` | `HH:mm` | Sì | Orario di inizio, nel fuso della community |
| `end_time` | `HH:mm` | No | Dopo l'inizio |
| `guest_company`, `guest_email`, `guest_phone` | testo | Secondo la configurazione | |
| `notify_guest` | vero o falso | No | Avvisa l'ospite via e-mail; vale solo con l'e-mail e secondo `email_guest` |
| `host_profile_id` | id | No | Solo il team: l'ospitante (`search_visitor_hosts`). Senza, sei tu |

**Chiedi così:** *"Registra Maria Souza (maria@memberfy.net) come mia ospite domani, dalle 14 alle 15."*

## `list_visitor_invitations`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Elencare gli ospiti.** Per orario atteso. Il membro vede solo i propri (come ospitante o come chi ha registrato), di qualsiasi data; moderatore e finanza vedono anche tutti quelli di oggi; amministratore e proprietario vedono qualsiasi data. Ogni voce dice cosa puoi fare (`canEdit`, `canCancel`, `canArrive`, `canUndoArrival`). *Ruolo: qualsiasi con accesso allo spazio.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `status` | `EXPECTED`, `ARRIVED`, `CANCELED` o `NO_SHOW` | No | `EXPECTED` vale da oggi in poi; `NO_SHOW` è l'atteso di un giorno passato |
| `from`, `to` | `AAAA-MM-GG` | No | Periodo, estremi inclusi, nel fuso della community |
| `q` | testo | No | Parte del nome o dell'azienda |
| `page`, `limit` | numeri | No | Paginazione (fino a 100) |

**Chiedi così:** *"Quali ospiti ho registrato per questa settimana?"*

## `get_visitor_invitation`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Una registrazione.** L'ospitante e chi ha registrato leggono la propria; il team legge quella di oggi; proprietario e amministratore, qualsiasi. Un'altra registrazione, un'altra community o un id sconosciuto: `404`. *Ruolo: qualsiasi.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `invitation_id` | id | Sì | Da `list_visitor_invitations` o `list_visitors_today` |

## `update_visitor_invitation`

<span class="tool-kind tool-kind-write">Modifica</span>

**Modificare prima dell'arrivo.** Dopo l'arrivo, o se annullata, la risposta è `409`. Invia solo ciò che cambia; `host_profile_id` è del team. Cambiare il giorno, l'orario o l'ospitante invia una nuova conferma all'ospitante, una volta per modifica. Il proprietario della registrazione e il team modificano (moderatore e finanza, solo quelle di oggi). *Ruolo: qualsiasi, secondo chi può modificare.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `invitation_id` | id | Sì | |
| `guest_name`, `guest_company`, `guest_email`, `guest_phone` | testo | No | |
| `expected_date`, `start_time`, `end_time` | data e orari | No | Stessi formati di `create_visitor_invitation` |
| `notify_guest` | vero o falso | No | |
| `host_profile_id` | id | No | Solo il team |

**Chiedi così:** *"Sposta la visita di Maria alle 15."*

## `cancel_visitor_invitation`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Annullare una registrazione.** Diventa **Annullato**; nulla viene cancellato. Chi ha registrato, l'ospitante o il team (moderatore e finanza, solo quelle di oggi). Già annullata: nulla cambia. Già arrivato: `409`, annulla prima l'arrivo. *Ruolo: qualsiasi, secondo chi può annullare.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `invitation_id` | id | Sì | |

**Restituisce:** alla prima chiamata, il riepilogo (ospite, ospitante, giorno e orario) e il codice di conferma.

## `list_visitors_today`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**La vista della reception.** Gli attesi e quelli già arrivati oggi (fuso della community), di tutti gli ospitanti, con i conteggi. Annullati e "non si è presentato" non compaiono. `alreadyMember` indica che l'e-mail dell'ospite è di un membro. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `q` | testo | No | Nome o azienda, senza accenti né maiuscole |

**Chiedi così:** *"Chi aspetto oggi alla reception?"*

## `search_visitor_hosts`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Trovare l'ospitante.** Membri dello spazio il cui nome (o una parola di esso) inizia con `q`, con 3 lettere o più. Restituisce solo id, nome, foto e iniziali; l'id è il `host_profile_id` di `create_visitor_invitation`. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `q` | testo | Sì | Da 3 a 100 caratteri |

## `mark_visitor_arrived`

<span class="tool-kind tool-kind-write">Modifica</span>

**Segnare l'arrivo.** Crea la visita nelle Presenze collegate (metodo reception, con il nome della registrazione) oppure collega quella che il team aveva già registrato. L'ospitante viene avvisato via e-mail quando le Presenze sono impostate così; `hostNotified` dice se l'avviso è andato in coda, e l'assistente lo riferisce alla persona. È idempotente: la seconda chiamata restituisce `alreadyArrived: true`. Solo nel giorno della registrazione (altro giorno: `409`); fuori dalla fascia oraria vale; annullata: `409`. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `invitation_id` | id | Sì | Da `list_visitors_today` |

**Restituisce:** `invitation`, `visit`, `hostNotified` e `alreadyArrived`.

**Chiedi così:** *"Maria Souza è arrivata."*

## `undo_visitor_arrival`

<span class="tool-kind tool-kind-write">Modifica</span>

**Annullare un arrivo segnato per errore.** Nello stesso giorno e prima dell'uscita dell'ospite. La visita sparisce dagli elenchi e dall'affluenza (resta nel registro delle Presenze) e la registrazione torna **Atteso**. Senza arrivo, altro giorno o già uscito: `409`. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `invitation_id` | id | Sì | |

## Correlati

- [Visitatori](/espacos/visitantes)
- [Strumenti: Presenze](/mcp/ferramentas-presenca)
- [Strumenti](/mcp/ferramentas)
- [Denaro e conferma](/mcp/dinheiro-e-confirmacao)
- [Ricette](/mcp/receitas)