# Visitas

Muitos clientes visitam o espaço antes de fechar um evento. Estas rotas devolvem as **visitas** da empresa: quando acontecem, em que situação estão, de quem são e a que oportunidade do CRM pertencem. Servem para montar agenda, medir a taxa de comparecimento e cruzar visitas com vendas.

**Escopo exigido:** `visits:read`. Sem ele, as rotas respondem [`scope_missing`](https://developers.festero.com.br/errors.md#scope_missing).

[Testar na referência interativa](https://developers.festero.com.br/referencia/)

## Listar visitas

### `GET /v1/visits`

Lista as visitas da empresa, da alteração mais antiga para a mais recente, com [paginação por cursor](https://developers.festero.com.br/paginacao.md).

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `status` | texto | Filtra pela situação: `requested`, `scheduled`, `completed`, `noshow` ou `cancelled`. Outro valor responde `400`. |
| `startFrom` | data `yyyy-MM-dd` | Início agendado a partir do qual listar (inclusive), no horário de Brasília. |
| `startTo` | data `yyyy-MM-dd` | Início agendado até o qual listar (inclusive), no horário de Brasília. |
| `updatedSince` | data e hora ISO 8601 | Só as visitas alteradas a partir deste instante. |
| `limit` | inteiro | Tamanho da página, de 1 a 100 (padrão 25). |
| `cursor` | texto | O `nextCursor` da página anterior. |

```bash
curl "https://platform.festero.com.br/v1/visits?status=scheduled&startFrom=2026-10-22&startTo=2026-10-31" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "data": [
    {
      "id": "4e9a1c68-d205-4b73-8f1e-b6c0a3d95e27",
      "status": "scheduled",
      "channel": "public",
      "scheduledStart": "2026-10-24T10:00:00-03:00",
      "scheduledEnd": "2026-10-24T11:00:00-03:00",
      "opportunityId": "8d3f6b1e-52a4-4c7e-9a18-0b6c2f4d7e31",
      "client": { "id": "2a7b5c90-31de-4f68-b4a2-6e0d8c19f533", "name": "Marina Albuquerque" },
      "cancelledAt": null,
      "createdAt": "2026-10-18T14:05:33-03:00",
      "updatedAt": "2026-10-18T14:05:33-03:00"
    }
  ],
  "nextCursor": null
}
```

## Buscar uma visita

### `GET /v1/visits/{id}`

Devolve uma visita pelo identificador, com os mesmos campos da lista. Responde `404` ([`not_found`](https://developers.festero.com.br/errors.md#not_found)) se ela não existe ou é de outra empresa. A resposta traz `ETag`: veja [Paginação e datas](https://developers.festero.com.br/paginacao.md#recurso-individual-etag).

| Parâmetro | Onde | Descrição |
|---|---|---|
| `id` | caminho | Identificador da visita (GUID). |

```bash
curl https://platform.festero.com.br/v1/visits/4e9a1c68-d205-4b73-8f1e-b6c0a3d95e27 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Campos da visita

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | GUID | Identificador da visita. |
| `status` | texto | `requested`, `scheduled`, `completed`, `noshow` ou `cancelled`. |
| `channel` | texto ou `null` | Canal de origem do agendamento: `manual`, `public` ou `salesbot`. |
| `scheduledStart` | instante ou `null` | Início agendado. |
| `scheduledEnd` | instante ou `null` | Fim agendado. |
| `opportunityId` | GUID ou `null` | Oportunidade vinculada ([CRM](https://developers.festero.com.br/api/crm.md)). |
| `client` | `{ id, name }` ou `null` | Cliente da visita. |
| `cancelledAt` | instante ou `null` | Quando foi cancelada. |
| `createdAt` | instante | Criação. |
| `updatedAt` | instante ou `null` | Última alteração. |

## Campos que pedem atenção

- **Horários no fuso de Brasília.** `scheduledStart` e `scheduledEnd` vêm com o deslocamento de Brasília (`-03:00`). Os filtros `startFrom` e `startTo` também usam o horário de Brasília. Já os [webhooks](https://developers.festero.com.br/webhooks/eventos.md) de visita trazem `scheduled_start` em UTC.
- **`requested` não é `scheduled`.** `requested` é um pedido de visita que a empresa ainda precisa confirmar ou recusar. Os avisos [`visit.confirmed`](https://developers.festero.com.br/webhooks/eventos.md#visit-confirmed) e [`visit.cancelled`](https://developers.festero.com.br/webhooks/eventos.md#visit-cancelled) (este também cobre o pedido recusado) acompanham essas decisões.
- **Sem contato.** Telefone, e-mail e nome do contato, link de reunião, anotações e motivos em texto livre não existem na API. A visita se liga ao cliente só por `id` e nome.
- **`channel`** diz de onde veio o agendamento: `manual` (a equipe cadastrou), `public` (o cliente agendou pela página pública) ou `salesbot` (pelo atendimento automático do Festero).
- **`noshow`** marca a visita a que o cliente não compareceu.

## Erros possíveis

| Código | HTTP | Quando |
|---|---|---|
| [`validation_failed`](https://developers.festero.com.br/errors.md#validation_failed) | 400 | `status` inválido, data fora do formato `yyyy-MM-dd`, `limit` fora de 1 a 100 ou `cursor` inválido. |
| [`scope_missing`](https://developers.festero.com.br/errors.md#scope_missing) | 403 | A credencial não tem `visits:read`. |
| [`not_found`](https://developers.festero.com.br/errors.md#not_found) | 404 | Visita inexistente ou de outra empresa. |

[Testar na referência interativa](https://developers.festero.com.br/referencia/)