Visitantes
Cadastro de visitantes e controle de visitas da portaria: agendamento, entrada, saída e cancelamento — os mesmos passos da tela de recepção. Integre com apps de agendamento, totens de portaria ou sistemas de condomínio.
O modelo visita
id
uuid
Identificador da visita.
status
string
PENDING → ONGOING → COMPLETED, ou CANCELLED.
visitor / visit_type
object
Visitante e tipo de visita.
access_mode
string
SINGLE (acesso único) ou SCHEDULE (período).
scheduled_date / valid_from / valid_until
date|null
Agendamento e validade.
check_in_at / check_out_at
datetime|null
Entrada e saída registradas.
{ "id": "01a2b3c4-0000-7000-8000-000000000501", "status": "PENDING", "status_label": "Pendente", "visitor": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725" }, "visit_type": { "id": "01a2b3c4-0000-7000-8000-000000000502", "name": "Prestador de serviço" }, "access_mode": "SINGLE", "access_mode_label": "Único", "scheduled_date": "2026-10-02", "valid_from": null, "valid_until": null, "check_in_at": null, "check_out_at": null, "notes": "Manutenção do ar-condicionado.", "created_at": "2026-10-01T17:40:00-03:00", "updated_at": "2026-10-01T17:40:00-03:00" }
/v1/partners/school/{cnpj}/visitors/all
Listar visitantes
Cadastro de visitantes da escola, em ordem alfabética, com a quantidade de visitas. Paginado (25 por página).
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
Filtros (query string)
search
string
opcional
Parte do nome, CPF ou e-mail.
Códigos de resposta
200
Sucesso.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
422
Parâmetros inválidos — veja errors.
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
$response = $client->get('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitors/all', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitors/all', { method: 'GET', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, });
{ "data": [ { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725", "birthdate": "1985-01-01", "email": "carlos.tecnico@email.com", "visits_count": 3, "created_at": "2026-08-13T23:11:32-03:00", "updated_at": "2026-08-13T23:11:32-03:00" } ], "links": { /* first, prev, next */ }, "meta": { "current_page": 1, "per_page": 25 } }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visitor/{id}
Obter visitante
Um visitante.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
uuid
obrigatório
UUID do visitante.
Códigos de resposta
200
Sucesso.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
$response = $client->get('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitor/{id}', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitor/{id}', { method: 'GET', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, });
{ "data": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725", "birthdate": "1985-01-01", "email": "carlos.tecnico@email.com", "visits_count": 3, "created_at": "2026-08-13T23:11:32-03:00", "updated_at": "2026-08-13T23:11:32-03:00" } }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visitor
Cadastrar visitante
Cadastra um visitante — por exemplo, a partir do seu app de portaria ou de agendamento. Dispara o webhook visitor.created.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
Parâmetros do corpo
name
string
obrigatório
Nome completo (até 150 caracteres).
cpf
string
opcional
CPF — único entre os visitantes da escola.
birthdate
date
opcional
Nascimento (AAAA-MM-DD).
email
string
opcional
E-mail.
Códigos de resposta
201
Recurso criado.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
422
Dados inválidos, ou CPF já cadastrado nesta escola (DUPLICATE_CPF).
-X POST \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}" \
-H "Content-Type: application/json" \
-d '{"name":"Carlos Técnico","cpf":"52998224725","email":"carlos.tecnico@email.com"}'
$response = $client->post('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitor', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client 'json' => json_decode('{"name":"Carlos Técnico","cpf":"52998224725","email":"carlos.tecnico@email.com"}', true), ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitor', { method: 'POST', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, body: JSON.stringify({"name":"Carlos Técnico","cpf":"52998224725","email":"carlos.tecnico@email.com"}), });
{ "data": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725", "birthdate": "1985-01-01", "email": "carlos.tecnico@email.com", "visits_count": 3, "created_at": "2026-08-13T23:11:32-03:00", "updated_at": "2026-08-13T23:11:32-03:00" } }
{ "success": false, "message": "Já existe um visitante com este CPF nesta escola." }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visitor/{id}
Editar visitante
Atualiza um visitante. Somente os campos enviados são alterados. Dispara o webhook visitor.updated.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
uuid
obrigatório
UUID do visitante.
Parâmetros do corpo
name
string
opcional
Nome completo (até 150 caracteres).
cpf
string
opcional
CPF — único entre os visitantes da escola.
birthdate
date
opcional
Nascimento (AAAA-MM-DD).
email
string
opcional
E-mail.
Códigos de resposta
200
Sucesso.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
422
Dados inválidos, ou CPF já cadastrado nesta escola (DUPLICATE_CPF).
-X PUT \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}" \
-H "Content-Type: application/json" \
-d '{"email":"carlos@novoemail.com"}'
$response = $client->put('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitor/{id}', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client 'json' => json_decode('{"email":"carlos@novoemail.com"}', true), ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitor/{id}', { method: 'PUT', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, body: JSON.stringify({"email":"carlos@novoemail.com"}), });
{ "data": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725", "birthdate": "1985-01-01", "email": "carlos.tecnico@email.com", "visits_count": 3, "created_at": "2026-08-13T23:11:32-03:00", "updated_at": "2026-08-13T23:11:32-03:00" } }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visit-types/all
Listar tipos de visita
Tipos de visita configurados pela escola e o comportamento de cada um no controle de acesso: CONTINUOUS (saída manual), SPECIFIC_DATE ou FIXED_PERIOD. Não paginado.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
Códigos de resposta
200
Sucesso.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
$response = $client->get('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit-types/all', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit-types/all', { method: 'GET', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, });
{ "data": [ { "id": "01a2b3c4-0000-7000-8000-000000000502", "name": "Prestador de serviço", "description": null, "visit_behavior_type": "SPECIFIC_DATE", "visit_behavior_label": "Data específica" } ] }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visits/all
Listar visitas
Visitas da escola, da mais recente para a mais antiga. Paginado.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
Filtros (query string)
status
string
opcional
PENDING, ONGOING, COMPLETED ou CANCELLED.
visitor_id
uuid
opcional
Somente as visitas de um visitante.
date
date
opcional
Visitas agendadas, iniciadas ou válidas na data (AAAA-MM-DD).
Códigos de resposta
200
Sucesso.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
422
Parâmetros inválidos — veja errors.
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
$response = $client->get('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visits/all', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visits/all', { method: 'GET', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, });
{ "data": [ { "id": "01a2b3c4-0000-7000-8000-000000000501", "status": "PENDING", "status_label": "Pendente", "visitor": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725" }, "visit_type": { "id": "01a2b3c4-0000-7000-8000-000000000502", "name": "Prestador de serviço" }, "access_mode": "SINGLE", "access_mode_label": "Único", "scheduled_date": "2026-10-02", "valid_from": null, "valid_until": null, "check_in_at": null, "check_out_at": null, "notes": "Manutenção do ar-condicionado.", "created_at": "2026-10-01T17:40:00-03:00", "updated_at": "2026-10-01T17:40:00-03:00" } ], "links": { /* first, prev, next */ }, "meta": { "current_page": 1, "per_page": 25 } }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visit/{id}
Obter visita
Uma visita.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
uuid
obrigatório
UUID da visita.
Códigos de resposta
200
Sucesso.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
$response = $client->get('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}', { method: 'GET', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, });
{ "data": { "id": "01a2b3c4-0000-7000-8000-000000000501", "status": "PENDING", "status_label": "Pendente", "visitor": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725" }, "visit_type": { "id": "01a2b3c4-0000-7000-8000-000000000502", "name": "Prestador de serviço" }, "access_mode": "SINGLE", "access_mode_label": "Único", "scheduled_date": "2026-10-02", "valid_from": null, "valid_until": null, "check_in_at": null, "check_out_at": null, "notes": "Manutenção do ar-condicionado.", "created_at": "2026-10-01T17:40:00-03:00", "updated_at": "2026-10-01T17:40:00-03:00" } }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visit
Registrar visita
Agenda uma visita, que nasce PENDING. Dispara o webhook visit.created.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
Parâmetros do corpo
visitor_id
uuid
obrigatório
Visitante (da própria escola).
visit_type_id
uuid
obrigatório
Tipo de visita (da própria escola).
access_mode
string
obrigatório
SINGLE (acesso único) ou SCHEDULE (período).
scheduled_date
date
opcional
Data agendada (AAAA-MM-DD).
valid_from
date
opcional
Início da validade (AAAA-MM-DD).
valid_until
date
opcional
Fim da validade — igual ou posterior a valid_from.
notes
string
opcional
Observações (até 1000 caracteres).
Códigos de resposta
201
Recurso criado.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola, visitante ou tipo de visita não encontrado.
422
Parâmetros inválidos — veja errors.
-X POST \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}" \
-H "Content-Type: application/json" \
-d '{"visitor_id":"019ffe09-f3e7-721e-98c2-c0d31da711df","visit_type_id":"01a2b3c4-0000-7000-8000-000000000502","access_mode":"SINGLE","scheduled_date":"2026-10-02","notes":"Manutenção do ar-condicionado."}'
$response = $client->post('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client 'json' => json_decode('{"visitor_id":"019ffe09-f3e7-721e-98c2-c0d31da711df","visit_type_id":"01a2b3c4-0000-7000-8000-000000000502","access_mode":"SINGLE","scheduled_date":"2026-10-02","notes":"Manutenção do ar-condicionado."}', true), ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit', { method: 'POST', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, body: JSON.stringify({"visitor_id":"019ffe09-f3e7-721e-98c2-c0d31da711df","visit_type_id":"01a2b3c4-0000-7000-8000-000000000502","access_mode":"SINGLE","scheduled_date":"2026-10-02","notes":"Manutenção do ar-condicionado."}), });
{ "data": { "id": "01a2b3c4-0000-7000-8000-000000000501", "status": "PENDING", "status_label": "Pendente", "visitor": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725" }, "visit_type": { "id": "01a2b3c4-0000-7000-8000-000000000502", "name": "Prestador de serviço" }, "access_mode": "SINGLE", "access_mode_label": "Único", "scheduled_date": "2026-10-02", "valid_from": null, "valid_until": null, "check_in_at": null, "check_out_at": null, "notes": "Manutenção do ar-condicionado.", "created_at": "2026-10-01T17:40:00-03:00", "updated_at": "2026-10-01T17:40:00-03:00" } }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visit/{id}/check-in
Check-in da visita
Registra a entrada do visitante: PENDING → ONGOING, com check_in_at no horário atual. Dispara o webhook visit.checked_in.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
uuid
obrigatório
UUID da visita.
Códigos de resposta
200
Sucesso.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
422
A visita não está pendente (INVALID_STATUS).
-X PATCH \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
$response = $client->patch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}/check-in', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}/check-in', { method: 'PATCH', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, });
{ "data": { "id": "01a2b3c4-0000-7000-8000-000000000501", "status": "ONGOING", "status_label": "Em andamento", "visitor": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725" }, "visit_type": { "id": "01a2b3c4-0000-7000-8000-000000000502", "name": "Prestador de serviço" }, "access_mode": "SINGLE", "access_mode_label": "Único", "scheduled_date": "2026-10-02", "valid_from": null, "valid_until": null, "check_in_at": "2026-10-02T09:03:11-03:00", "check_out_at": null, "notes": "Manutenção do ar-condicionado.", "created_at": "2026-10-01T17:40:00-03:00", "updated_at": "2026-10-01T17:40:00-03:00" } }
{ "success": false, "message": "Apenas visitas pendentes podem receber check-in." }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visit/{id}/check-out
Check-out da visita
Registra a saída: ONGOING → COMPLETED, com check_out_at no horário atual. Dispara o webhook visit.checked_out.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
uuid
obrigatório
UUID da visita.
Códigos de resposta
200
Sucesso.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
422
A visita não está em andamento (INVALID_STATUS).
-X PATCH \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
$response = $client->patch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}/check-out', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}/check-out', { method: 'PATCH', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, });
{ "data": { "id": "01a2b3c4-0000-7000-8000-000000000501", "status": "COMPLETED", "status_label": "Concluída", "visitor": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725" }, "visit_type": { "id": "01a2b3c4-0000-7000-8000-000000000502", "name": "Prestador de serviço" }, "access_mode": "SINGLE", "access_mode_label": "Único", "scheduled_date": "2026-10-02", "valid_from": null, "valid_until": null, "check_in_at": "2026-10-02T09:03:11-03:00", "check_out_at": "2026-10-02T10:41:52-03:00", "notes": "Manutenção do ar-condicionado.", "created_at": "2026-10-01T17:40:00-03:00", "updated_at": "2026-10-01T17:40:00-03:00" } }
{ "success": false, "message": "Escola não encontrada." }
/v1/partners/school/{cnpj}/visit/{id}/cancel
Cancelar visita
Cancela uma visita pendente ou em andamento. Dispara o webhook visit.cancelled.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
uuid
obrigatório
UUID da visita.
Códigos de resposta
200
Sucesso.
401
Credenciais inválidas (X-Partner, X-Client ou X-Authorization).
404
Escola ou recurso não encontrado.
422
A visita já foi concluída ou cancelada (INVALID_STATUS).
-X PATCH \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
$response = $client->patch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}/cancel', [ 'headers' => $headers, // X-Authorization, X-Partner, X-Client ]);
const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}/cancel', { method: 'PATCH', headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' }, });
{ "data": { "id": "01a2b3c4-0000-7000-8000-000000000501", "status": "CANCELLED", "status_label": "Cancelada", "visitor": { "id": "019ffe09-f3e7-721e-98c2-c0d31da711df", "name": "Carlos Técnico", "cpf": "52998224725" }, "visit_type": { "id": "01a2b3c4-0000-7000-8000-000000000502", "name": "Prestador de serviço" }, "access_mode": "SINGLE", "access_mode_label": "Único", "scheduled_date": "2026-10-02", "valid_from": null, "valid_until": null, "check_in_at": null, "check_out_at": null, "notes": "Manutenção do ar-condicionado.", "created_at": "2026-10-01T17:40:00-03:00", "updated_at": "2026-10-01T17:40:00-03:00" } }
{ "success": false, "message": "Escola não encontrada." }