Visitantes
Controle de acesso de visitantes: cadastro do visitante, agendamento/registro de uma visita e o check-in/check-out na portaria. O provisionamento de dispositivos e portões de acesso fica fora desta API — é configuração de hardware, não dado de integração.
O modelo visitante
id
uuid
Identificador único do visitante.
name
string
Nome completo.
cpf
string|null
CPF, único por escola.
birthdate
date|null
Data de nascimento.
email
string|null
E-mail de contato.
visits_count
integer
Total de visitas registradas.
created_at
datetime
Data de cadastro.
{ "id": "v1s2i3t4-0000-0000-0000-000000000001", "name": "Carlos Entregador", "cpf": "12345678900", "email": null, "visits_count": 3 }
O modelo visita
status percorre
PENDING →
ONGOING →
COMPLETED, ou
CANCELLED a partir de
PENDING/ONGOING (cancelamento não é exposto nesta API).
id
uuid
Identificador único da visita.
visitor
object
id, name e cpf do visitante.
visit_type
object
id, name e visit_behavior_type do tipo de visita.
status
string
PENDING, ONGOING, COMPLETED ou CANCELLED.
access_mode
string
SINGLE (visita única) ou SCHEDULE (agendada).
scheduled_date
date|null
Data agendada, quando aplicável.
valid_from
date|null
Início da validade de acesso.
valid_until
date|null
Fim da validade de acesso.
check_in_at
datetime|null
Data/hora do check-in.
check_out_at
datetime|null
Data/hora do check-out.
notes
string|null
Observações.
created_at
datetime
Data de criação.
{ "id": "...", "visitor": { "id": "...", "name": "Carlos Entregador" }, "visit_type": { "id": "...", "name": "Entrega" }, "status": "ONGOING", "access_mode": "SINGLE", "check_in_at": "2026-09-02T09:00:00-03:00", "check_out_at": null }
/v1/partners/school/{cnpj}/visit-types/all
Listar tipos de visita
Referência de leitura — os tipos de visita configurados na escola (entrega, prestador de serviço, evento, etc.).
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/school/{cnpj}/visitors/all
Listar visitantes
Cadastro de visitantes da escola, paginado.
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/school/{cnpj}/visitor
Cadastrar visitante
Cria um visitante. Corpo: name (obrigatório), cpf, birthdate, email.
Códigos de resposta
201
Sucesso.
404
Não encontrado.
/v1/partners/school/{cnpj}/visits/all
Listar visitas
Visitas da escola, paginadas. Filtro opcional por query string status=PENDING|ONGOING|COMPLETED|CANCELLED.
Códigos de resposta
200
Sucesso.
404
Não encontrado.
/v1/partners/school/{cnpj}/visit
Registrar visita
Cria uma visita com status PENDING. Corpo: visitor_id, visit_type_id, access_mode (obrigatórios); scheduled_date, valid_from, valid_until, notes (opcionais).
Códigos de resposta
201
Sucesso.
404
Não encontrado.
/v1/partners/school/{cnpj}/visit/{id}/check-in
Check-in
Marca a entrada do visitante — só válido a partir de PENDING.
Códigos de resposta
200
Sucesso.
422
Status atual não permite esta transição.
404
Não encontrado.
/v1/partners/school/{cnpj}/visit/{id}/check-out
Check-out
Marca a saída do visitante — só válido a partir de ONGOING.
Códigos de resposta
200
Sucesso.
422
Status atual não permite esta transição.
404
Não encontrado.