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.

Testar na referência interativa

Listar visitas

GET /v1/visits

Lista as visitas da empresa, da alteração mais antiga para a mais recente, com paginação por cursor.

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.

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

{
  "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) se ela não existe ou é de outra empresa. A resposta traz ETag: veja Paginação e datas.

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

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).
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 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 e 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	400	status inválido, data fora do formato yyyy-MM-dd, limit fora de 1 a 100 ou cursor inválido.
scope_missing	403	A credencial não tem visits:read.
not_found	404	Visita inexistente ou de outra empresa.

Testar na referência interativa