To Aqui - O app que descomplica a comunicação escolar

O modelo professor

id uuid

Identificador do usuário.

email string

E-mail de acesso.

name string

Nome completo.

birthdate date|null

Data de nascimento (YYYY-MM-DD).

role string

Sempre "teacher".

school_cnpj string

CNPJ da escola.

Modelo professor

{
  "id": "...",
  "email": "prof@escola.com",
  "name": "Carlos Pereira",
  "role": "teacher"
}

GET /v1/partners/school/{cnpj}/teachers/all

Listar Professores

Lista todos os professores da escola.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos, sem formatação).

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Escola ou recurso não encontrado.

Requisição GET

GET /v1/partners/school/{cnpj}/teachers/all

curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/teachers/all \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$client->get('.../v1/partners/school/{cnpj}/teachers/all');

await fetch('.../v1/partners/school/{cnpj}/teachers/all');

Resposta

{
  "data": [
    {
    "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
      "email": "carlos.lima@escola.com.br",
      "name": "Carlos Lima",
      "birthdate": "1978-11-05",
      "role": "teacher",
      "school_cnpj": "26019466000122"
    }
  ],
  "links": { /* paginação */ },
  "meta": { /* paginação */ }
}

{
  "message": "Autenticação inválida. Verifique os cabeçalhos X-Authorization, X-Partner e X-Client."
}

{
  "message": "Escola ou recurso não encontrado."
}

GET /v1/partners/school/{cnpj}/teacher/{id}

Obter Professor

Retorna um professor pelo UUID.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos, sem formatação).

id uuid obrigatório

UUID do professor.

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Escola ou recurso não encontrado.

Requisição GET

GET /v1/partners/school/{cnpj}/teacher/{id}

curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/teacher/{id} \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$client->get('.../v1/partners/school/{cnpj}/teacher/{id}');

await fetch('.../v1/partners/school/{cnpj}/teacher/{id}');

Resposta

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
    "email": "carlos.lima@escola.com.br",
    "name": "Carlos Lima",
    "birthdate": "1978-11-05",
    "role": "teacher",
    "school_cnpj": "26019466000122"
  }
}

{
  "message": "Autenticação inválida. Verifique os cabeçalhos X-Authorization, X-Partner e X-Client."
}

{
  "message": "Escola ou recurso não encontrado."
}

POST /v1/partners/school/{cnpj}/teacher

Criar Professor

Cria um professor.

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.

email string obrigatório

E-mail único na plataforma.

birthdate date opcional

Data de nascimento (YYYY-MM-DD).

Códigos de resposta

201

Recurso criado com sucesso.

400

Dados inválidos.

401

Autenticação inválida.

404

Escola ou recurso não encontrado.

Requisição POST

POST /v1/partners/school/{cnpj}/teacher

curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/teacher \
  -X POST \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -H "Content-Type: application/json" \
  -d '{ "name"*: "...", "email"*: "...", "birthdate": "..." }'

$client->post('.../v1/partners/school/{cnpj}/teacher', ['json' => [/* ... */]]);

await fetch('.../v1/partners/school/{cnpj}/teacher', {
  method: 'POST',
  body: JSON.stringify({/* ... */})
});

Resposta

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
    "email": "carlos.lima@escola.com.br",
    "name": "Carlos Lima",
    "birthdate": "1978-11-05",
    "role": "teacher",
    "school_cnpj": "26019466000122"
  }
}

{
  "message": "Os dados fornecidos são inválidos.",
  "errors": {
    "name": ["O campo nome é obrigatório."]
  }
}

{
  "message": "Autenticação inválida. Verifique os cabeçalhos X-Authorization, X-Partner e X-Client."
}

{
  "message": "Escola ou recurso não encontrado."
}

PUT /v1/partners/school/{cnpj}/teacher/{id}

Editar Professor

Atualiza um professor.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos, sem formatação).

id uuid obrigatório

UUID do professor.

Parâmetros do corpo

name string opcional

Nome completo.

email string opcional

Novo e-mail.

birthdate date opcional

Data de nascimento (YYYY-MM-DD).

Códigos de resposta

200

Sucesso.

400

Dados inválidos.

401

Autenticação inválida.

404

Escola ou recurso não encontrado.

Requisição PUT

PUT /v1/partners/school/{cnpj}/teacher/{id}

curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/teacher/{id} \
  -X PUT \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "email": "...", "birthdate": "..." }'

$client->put('.../v1/partners/school/{cnpj}/teacher/{id}', ['json' => [/* ... */]]);

await fetch('.../v1/partners/school/{cnpj}/teacher/{id}', {
  method: 'PUT',
  body: JSON.stringify({/* ... */})
});

Resposta

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
    "email": "carlos.lima@escola.com.br",
    "name": "Carlos Lima",
    "birthdate": "1978-11-05",
    "role": "teacher",
    "school_cnpj": "26019466000122"
  }
}

{
  "message": "Os dados fornecidos são inválidos.",
  "errors": {
    "name": ["O campo nome é obrigatório."]
  }
}

{
  "message": "Autenticação inválida. Verifique os cabeçalhos X-Authorization, X-Partner e X-Client."
}

{
  "message": "Escola ou recurso não encontrado."
}

DELETE /v1/partners/school/{cnpj}/teacher/{id}

Excluir Professor

Remove um professor.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos, sem formatação).

id uuid obrigatório

UUID do professor.

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Escola ou recurso não encontrado.

Requisição DELETE

DELETE /v1/partners/school/{cnpj}/teacher/{id}

curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/teacher/{id} \
  -X DELETE \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$client->delete('.../v1/partners/school/{cnpj}/teacher/{id}');

await fetch('.../v1/partners/school/{cnpj}/teacher/{id}', {
  method: 'DELETE'
});

Resposta

{
  "message": "Recurso removido com sucesso."
}

{
  "message": "Autenticação inválida. Verifique os cabeçalhos X-Authorization, X-Partner e X-Client."
}

{
  "message": "Escola ou recurso não encontrado."
}

GET /school/teacher/{id}/availability

Obter disponibilidade do professor

Retorna a grade de disponibilidade semanal de um professor. Os períodos são agrupados por dia da semana (1 = Segunda-feira … 7 = Domingo), ordenados por posição dentro de cada dia. Cada entrada inclui o horário de início e os dados do tipo de aula associado.

Parâmetros de rota

id uuid obrigatório

UUID do professor.

Campos da resposta — períodos

id uuid

Identificador único do período.

position integer

Posição do período dentro do dia (0-based).

start_time string

Horário de início no formato HH:MM.

class_period_type_id uuid

UUID do tipo de aula associado.

class_period_type object

Dados do tipo de aula: id, name, duration_minutes.

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Professor não encontrado.

Requisição GET

GET /school/teacher/{id}/availability

curl https://toakiescola.com.br/administrative/school/teacher/a1b2c3d4-.../availability \
-H "Accept: application/json" \
-H "X-XSRF-TOKEN: {csrf_token}"

use GuzzleHttp\Client;

$client = new Client();
$response = $client->get('https://toakiescola.com.br/administrative/school/teacher/{id}/availability', [
    'headers' => [
        'Accept'       => 'application/json',
        'X-XSRF-TOKEN' => '{csrf_token}',
    ],
]);
$availability = json_decode($response->getBody(), true);

const response = await fetch('/administrative/school/teacher/{id}/availability', {
    headers: {
        'Accept':       'application/json',
        'X-XSRF-TOKEN': getCookie('XSRF-TOKEN'),
    },
});
const availability = await response.json();

Resposta

{
  "teacher": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Carlos Lima"
  },
  "periods": {
    "1": [
      {
        "id": "b2c3d4e5-...",
        "position": 0,
        "start_time": "07:00",
        "class_period_type_id": "c3d4e5f6-...",
        "class_period_type": {
          "id": "c3d4e5f6-...",
          "name": "Padrão",
          "duration_minutes": 50
        }
      }
    ],
    "2": [],
    /* ... dias 3 a 7 ... */
  }
}

{
  "message": "Autenticação inválida."
}

{
  "message": "Professor não encontrado."
}

POST /school/teacher/{id}/availability

Salvar disponibilidade do professor

Substitui a grade de disponibilidade semanal de um professor de forma atômica. Todos os períodos existentes são removidos e recriados com base no payload enviado. O corpo deve conter um objeto periods com as chaves 1 a 7 (dias da semana ISO: 1 = Segunda … 7 = Domingo). Dias não informados ou com array vazio são apagados.

⚠ Regra — Horário semanal obrigatório

A grade de disponibilidade (Disponibilidade) do professor só pode ser configurada se a escola estiver utilizando o horário semanal. Se a escola estiver configurada com o horário global, a requisição será rejeitada com 422 e uma mensagem orientando a alterar o tipo de horário da escola para "Semanal".

Parâmetros de rota

id uuid obrigatório

UUID do professor.

Corpo da requisição

periods object obrigatório

Objeto com chaves 1–7. Cada chave é um array de períodos para aquele dia.

periods.*.*.start_time string obrigatório

Horário de início no formato HH:MM.

periods.*.*.class_period_type_id uuid obrigatório

UUID do tipo de aula. Deve pertencer à mesma escola do professor.

Códigos de resposta

200

Disponibilidade salva com sucesso.

422

Dados inválidos (start_time fora do formato, UUID desconhecido, tipo de aula de outra escola).

401

Autenticação inválida.

404

Professor não encontrado.

Requisição POST

POST /school/teacher/{id}/availability

curl https://toakiescola.com.br/administrative/school/teacher/a1b2c3d4-.../availability \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: {csrf_token}" \
  -d '{"periods":{"1":[{"start_time":"07:00","class_period_type_id":"c3d4..."},{"start_time":"07:50","class_period_type_id":"c3d4..."}],"2":[],"3":[],"4":[],"5":[],"6":[],"7":[]}}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://toakiescola.com.br/administrative/school/teacher/{id}/availability', [
    'headers' => [
        'Content-Type' => 'application/json',
        'X-XSRF-TOKEN' => '{csrf_token}',
    ],
    'json' => [
        'periods' => [
            '1' => [
                ['start_time' => '07:00', 'class_period_type_id' => 'c3d4...'],
                ['start_time' => '07:50', 'class_period_type_id' => 'c3d4...'],
            ],
            '2' => [],
            /* ... */
        ],
    ],
]);

const response = await fetch('/administrative/school/teacher/{id}/availability', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-XSRF-TOKEN': getCookie('XSRF-TOKEN'),
    },
    body: JSON.stringify({
        periods: {
            '1': [
                { start_time: '07:00', class_period_type_id: 'c3d4...' },
                { start_time: '07:50', class_period_type_id: 'c3d4...' },
            ],
            '2': [],
            /* ... dias 3 a 7 */
        },
    }),
});

Resposta

{
  "message": "Disponibilidade do professor salva."
}

{
  "message": "O horário de início deve estar no formato HH:MM.",
  "errors": { ... }
}

{
  "message": "Autenticação inválida."
}

{
  "message": "Professor não encontrado."
}