Todos os planos Leitura e escrita

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.

O modelo visita
{
  "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"
}
GET /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.

Requisição GET
GET /v1/partners/school/{cnpj}/visitors/all
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitors/all \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"
Resposta
{
  "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 }
}
GET /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.

Requisição GET
GET /v1/partners/school/{cnpj}/visitor/{id}
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitor/{id} \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"
Resposta
{
  "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"
  }
}
POST /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).

Requisição POST
POST /v1/partners/school/{cnpj}/visitor
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitor \
  -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"}'
Resposta
{
  "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"
  }
}
PUT /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).

Requisição PUT
PUT /v1/partners/school/{cnpj}/visitor/{id}
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visitor/{id} \
  -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"}'
Resposta
{
  "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"
  }
}
GET /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.

Requisição GET
GET /v1/partners/school/{cnpj}/visit-types/all
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit-types/all \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"
Resposta
{
  "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"
    }
  ]
}
GET /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.

Requisição GET
GET /v1/partners/school/{cnpj}/visits/all
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visits/all \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"
Resposta
{
  "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 }
}
GET /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.

Requisição GET
GET /v1/partners/school/{cnpj}/visit/{id}
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id} \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"
Resposta
{
  "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"
  }
}
POST /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.

Requisição POST
POST /v1/partners/school/{cnpj}/visit
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit \
  -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."}'
Resposta
{
  "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"
  }
}
PATCH /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).

Requisição PATCH
PATCH /v1/partners/school/{cnpj}/visit/{id}/check-in
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}/check-in \
  -X PATCH \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"
Resposta
{
  "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"
  }
}
PATCH /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).

Requisição PATCH
PATCH /v1/partners/school/{cnpj}/visit/{id}/check-out
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}/check-out \
  -X PATCH \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"
Resposta
{
  "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"
  }
}
PATCH /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).

Requisição PATCH
PATCH /v1/partners/school/{cnpj}/visit/{id}/cancel
curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/visit/{id}/cancel \
  -X PATCH \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"
Resposta
{
  "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"
  }
}