# Strumenti · Presenze

> Gli strumenti MCP del modulo Presenze (coworking): l'affluenza, Sono arrivato e Me ne vado, chi è presente, visitatori, storico, correzione e rimozione delle visite e i link del chiosco della reception.

Il modulo [Presenze](/espacos/presenca) tramite l'assistente: vedere l'affluenza, segnare l'arrivo e l'uscita (tuoi, di un membro o di un visitatore), elencare chi è nello spazio e lo storico, correggere o rimuovere visite e generare e revocare i link del chiosco. Il chiosco in sé è una schermata per il visitatore sull'iPad della reception; l'assistente **gestisce** i link, non usa il chiosco.

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 sintesi

| Strumento | Cosa fa | Ruolo minimo | Tipo |
|---|---|---|---|
| [`get_attendance_overview`](#get-attendance-overview) | L'affluenza e la tua visita aperta | Chiunque veda lo spazio | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`check_in`](#check-in) | Registra l'arrivo, il tuo o quello di un membro | Qualsiasi (il tuo); moderatore o finanza (di un altro) | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`check_out`](#check-out) | Registra l'uscita | Qualsiasi (la tua); moderatore o finanza (di un altro) | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`list_present`](#list-present) | Chi è nello spazio ora | Moderatore o finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`list_visits`](#list-visits) | Lo storico delle visite, con filtri | Moderatore o finanza (oggi); amministratore (qualsiasi giorno) | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`list_my_visits`](#list-my-visits) | Le tue visite e il riepilogo del mese | Qualsiasi | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`update_visit`](#update-visit) | Corregge l'arrivo o l'uscita di una visita | Moderatore o finanza (oggi); amministratore (qualsiasi giorno) | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`delete_visit`](#delete-visit) | Rimuove una visita | Amministratore | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`check_guest_in`](#check-guest-in) | Registra l'arrivo di un visitatore | Moderatore o finanza | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`list_attendance_kiosks`](#list-attendance-kiosks) | I dispositivi chiosco dello spazio | Moderatore o finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`create_attendance_kiosk`](#create-attendance-kiosk) | Genera il link di un chiosco (compare una volta) | Moderatore | <span class="tool-kind tool-kind-write">Modifica</span> |
| [`revoke_attendance_kiosk`](#revoke-attendance-kiosk) | Revoca il link di un chiosco | Moderatore | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |

Lo spazio si crea con [`create_space`](/mcp/ferramentas-comunidade#create-space) e `module: "attendance"`, con l'argomento `attendance` per la configurazione; [`update_space`](/mcp/ferramentas-comunidade#update-space) cambia solo ciò che invii e mantiene il resto.

Il team, qui, è il proprietario, l'amministratore, il moderatore e la finanza; la finanza legge e segna, ma non genera né revoca link del chiosco. I ruoli sono quelli delle rotte: l'assistente non fa mai più di quanto la persona connessa farebbe nella schermata.

## La configurazione dello spazio

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

| Campo | Tipo | Descrizione |
|---|---|---|
| `self_check_in` | `off`, `button` o `code` | Chi segna l'arrivo: `off`, solo il team; `button`, il membro, con il pulsante **Sono arrivato** (`code` non è ancora disponibile) |
| `capacity` | numero da 1 a 100000, o `null` | La capienza, informativa. `null` toglie il limite |
| `auto_checkout_time` | `HH:MM` | L'[uscita automatica](/espacos/presenca#uscita-automatica), nel fuso della community (predefinito `23:59`) |
| `show_who_is_here` | `staff` | Chi vede i nomi: solo il team |
| `kiosk.guest_fields` | `{company, phone}`, ciascuno `off`, `optional` o `required` | Cosa chiede la schermata del chiosco oltre al nome |
| `kiosk.notify_host` | vero o falso | Avvisa l'ospitante per e-mail all'arrivo del visitatore (predefinito: sì) |
| `kiosk.reset_seconds` | da 5 a 60 | In quanti secondi la schermata del chiosco torna all'inizio (predefinito: 10) |

## `get_attendance_overview`

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

**Affluenza dello spazio.** Solo il numero di persone e la capienza (mai nomi), la visita aperta di chi chiede e la modalità di check-in (`off`, `button` o `code`). *Ruolo minimo: chiunque veda lo spazio.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | Lo spazio Presenze |

**Chiedi così:** *"Quante persone ci sono ora nella Sede Centro?"*

## `check_in`

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

**Registrare l'arrivo.** Senza `profile_id`, è il **tuo** arrivo, e solo se lo spazio lascia segnare al membro (il team può sempre segnarsi). Con `profile_id`, il team registra l'arrivo di **un altro membro**; il membro comune viene rifiutato. Chi non ha accesso allo spazio (piano scaduto, gruppo escluso) viene rifiutato, anche dal team. È **idempotente**: con una visita già aperta, restituisce quella visita (`already_checked_in: true`). Un visitatore senza account è [`check_guest_in`](#check-guest-in). *Ruolo: qualsiasi (il tuo); moderatore o finanza (di un altro).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `profile_id` | id | No | Solo il team: il membro da segnare (`list_members`). Senza, sei tu |

**Restituisce:** `visit` e `already_checked_in`.

**Chiedi così:** *"Registra il mio arrivo nella Sede Centro."* · *"Segna l'arrivo di Maria nel coworking."*

## `check_out`

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

**Registrare l'uscita.** Senza parametri oltre allo spazio, chiude la **tua** visita aperta. Il team chiude quella di un membro (`profile_id`) o qualsiasi visita aperta (`visit_id`, da `list_present`). Senza una visita aperta, la risposta è `409`. *Ruolo: qualsiasi (la tua); moderatore o finanza (di un altro).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `profile_id` | id | No | Solo il team: il membro di cui chiudere la visita |
| `visit_id` | id | No | La visita aperta da chiudere (il team; il membro, solo la sua) |

**Chiedi così:** *"Sto uscendo."*

## `list_present`

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

**Chi è presente.** Le visite aperte, di membri e di visitatori, dalla più recente alla più vecchia, con il nome e l'ora di arrivo, più il conteggio e la capienza. Il membro vede solo il numero, in `get_attendance_overview`. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `page`, `limit` | numeri | No | Paginazione (fino a 100 per pagina) |

**Chiedi così:** *"Chi è in sede adesso?"*

## `list_visits`

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

**Lo storico.** Le visite dello spazio, dalla più recente alla più vecchia: chi, arrivo, uscita, il tipo (membro o visitatore), se è aperta o è stata chiusa automaticamente. L'amministratore e il proprietario leggono qualsiasi periodo; il moderatore e la finanza vedono **solo oggi** (l'API restringe l'intervallo). *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `profile_id` | id | No | Solo questo membro |
| `kind` | `member` o `guest` | No | Membri o visitatori |
| `open` | vero o falso | No | `true`: solo chi è ancora presente |
| `from`, `to` | data | No | `AAAA-MM-GG` o ISO 8601, letti nel fuso della community |
| `page`, `limit` | numeri | No | Paginazione |

**Chiedi così:** *"Quanti visitatori sono venuti la settimana scorsa?"*

## `list_my_visits`

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

**Le tue visite.** Il tuo storico, dalla più recente alla più vecchia, con il riepilogo del mese (visite, giorni e minuti) nel fuso della community. *Ruolo minimo: qualsiasi.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | No | Solo questo spazio Presenze |
| `page`, `limit` | numeri | No | Paginazione |

**Chiedi così:** *"Quanti giorni sono andato al coworking questo mese?"*

## `update_visit`

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

**Correggere una visita.** Cambia l'arrivo (`check_in_at`) e/o l'uscita (`check_out_at`). L'uscita non può essere prima dell'arrivo né nel futuro; inviare l'uscita su una visita aperta la **chiude**. L'amministratore e il proprietario correggono qualsiasi giorno; il moderatore e la finanza, solo la visita di oggi e con le date entro oggi (ieri restituisce `403`). La correzione entra nel [registro attività](/membros/registros-de-atividades) con chi l'ha fatta. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `visit_id` | id | Sì | Da `list_visits` o `list_present` |
| `check_in_at` | data e ora | No | ISO 8601 |
| `check_out_at` | data e ora | No | ISO 8601 |

**Chiedi così:** *"Pietro si è dimenticato di segnare l'uscita: è uscito alle 18. Chiudi la sua visita."*

## `delete_visit`

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

**Rimuovere una visita.** La visita esce dagli elenchi e dai conteggi (una visita aperta smette di contare nell'affluenza) e la rimozione entra nel registro attività. Il membro non viene eliminato. *Ruolo minimo: amministratore.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `visit_id` | id | Sì | Da `list_visits` |

**Restituisce:** alla prima chiamata, il riepilogo e il codice di conferma.

## `check_guest_in`

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

**Registrare un visitatore.** Il team registra l'arrivo di chi **non ha un account**, con il membro che lo riceve (l'ospitante, che deve avere accesso allo spazio). L'azienda e il telefono vengono chiesti o rifiutati secondo la configurazione del chiosco. È idempotente per **nome e ospitante**: con la visita aperta, restituisce `already_checked_in: true`. Se lo spazio avvisa gli ospitanti, l'ospitante riceve [un'e-mail](/espacos/presenca#e-mail-al-residente). Il visitatore conta nell'affluenza. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `guest_name` | testo | Sì | Il nome del visitatore (fino a 100 caratteri) |
| `host_profile_id` | id | Sì | Il membro che lo riceve (`list_members`) |
| `guest_company` | testo | No | L'azienda |
| `guest_phone` | testo | No | Il telefono |

**Chiedi così:** *"Registra il visitatore Pietro Neri, di Acme, venuto a trovare Anna."*

## `list_attendance_kiosks`

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

**I chioschi.** I dispositivi dello spazio, attivi e revocati: nome, chi lo ha creato, quando, l'ultimo uso e lo stato. **Mai il link**, che compare solo alla creazione. *Ruolo minimo: moderatore (o finanza).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |

## `create_attendance_kiosk`

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

**Generare il link di un chiosco.** Uno per iPad o luogo. Restituisce `kiosk`, la `url` e un `warning`: l'URL compare **una sola volta** ed è **segreta**, come una password. Chi la possiede registra visitatori. L'assistente chiede alla persona di aprirla sul dispositivo e di non condividerla; se la perde, deve revocarla e generarne un'altra. *Ruolo minimo: moderatore (proprietario, amministratore o moderatore; la finanza no).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `name` | testo | Sì | Il nome del dispositivo, fino a 80 caratteri (per esempio, "Tablet della reception") |

**Chiedi così:** *"Genera il link del chiosco per l'iPad della reception della Sede Centro."*

## `revoke_attendance_kiosk`

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

**Revocare un chiosco.** Il link smette di funzionare **subito** e non torna (generane un altro). Le visite già registrate restano. *Ruolo minimo: moderatore (proprietario, amministratore o moderatore).*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `space` | id o link | Sì | |
| `kiosk_id` | id | Sì | Da `list_attendance_kiosks` |

**Restituisce:** alla prima chiamata, il riepilogo (il nome e l'ultimo uso del dispositivo) e il codice di conferma.

## Correlati

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