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

O modelo disciplina

O modelo disciplina identifica uma matéria oferecida por uma escola. Cada disciplina possui um nome único dentro da escola e pode opcionalmente estar vinculada a um componente da BNCC.

id uuid

Identificador único da disciplina.

name string

Nome da disciplina (até 50 caracteres).

abbreviation string|null

Abreviação da disciplina (até 4 caracteres). Deve ser única dentro da escola. Exemplo: "MAT", "PORT".

color string|null

Cor da disciplina em formato hexadecimal. Exemplo: "#4F46E5".

bncc_component_id uuid|null

UUID do componente BNCC vinculado, quando aplicável.

school_cnpj string

CNPJ da escola à qual a disciplina pertence.

Modelo disciplina

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Matemática",
  "abbreviation": "MAT",
  "color": "#4F46E5",
  "bncc_component_id": "f9e8d7c6-...",
  "school_cnpj": "26019466000122"
}

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

Listar disciplinas

Retorna todas as disciplinas de uma escola específica, identificada pelo CNPJ. A resposta é paginada, com os registros em data.

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 não encontrada.

Requisição GET

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

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

use GuzzleHttp\Client;

$client = new Client();
$response = $client->get('https://toakiescola.com.br/api/v1/partners/school/26019466000122/subjects/all', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
]);

const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/subjects/all', {
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    },
});

Resposta

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Matemática",
      "abbreviation": "MAT",
      "color": "#4F46E5",
      "bncc_component_id": null,
      "school_cnpj": "26019466000122"
    }
  ],
  "links": { /* URLs de paginação */ },
  "meta": { /* metadados */ }
}

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

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

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

Obter disciplina

Retorna os dados de uma disciplina específica.

Parâmetros de rota

cnpj string obrigatório

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

id string obrigatório

UUID da disciplina.

Códigos de resposta

200

Sucesso.

404

Escola ou disciplina não encontrada.

Requisição GET

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/subject/a1b2c3d4-... \
-H "X-Authorization: {api_token}"

$client->get('.../subject/{id}');

await fetch('.../subject/{id}');

Resposta

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
    "name": "Matemática",
    "abbreviation": "MAT",
    "color": "#4F46E5",
    "bncc_component_id": null,
    "school_cnpj": "26019466000122"
  }
}

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

{
  "message": "Escola ou disciplina não encontrada."
}

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

Criar disciplina

Cria uma nova disciplina em uma escola. O nome deve ser único dentro da escola.

Parâmetros do corpo

name string obrigatório

Nome da disciplina (até 50 caracteres).

abbreviation string obrigatório

Abreviação da disciplina (até 4 caracteres). Deve ser única dentro da escola. Exemplo: "MAT".

color string opcional

Cor da disciplina em formato hexadecimal. Exemplo: "#4F46E5".

bncc_component_id uuid opcional

UUID do componente BNCC (opcional).

Códigos de resposta

200

Disciplina criada com sucesso.

400

Erros de validação.

404

Escola não encontrada.

409

Já existe uma disciplina com este nome ou abreviação na escola.

Requisição POST

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/subject \
  -X POST \
  -H "X-Authorization: {api_token}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Matemática"}'

$client->post('.../subject', [
    'json' => ['name' => 'Matemática'],
]);

await fetch('.../subject', {
    method: 'POST',
    body: JSON.stringify({ name: 'Matemática' }),
});

Resposta

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Matemática",
    "abbreviation": "MAT",
    "color": "#4F46E5",
    "bncc_component_id": null,
    "school_cnpj": "26019466000122"
  }
}

{
  "success": false,
  "errors": [ /* mensagens de validação */ ]
}

{
  "message": "Escola não encontrada."
}

{
  "message": "Já existe uma disciplina com este nome ou abreviação na escola."
}

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

Editar disciplina

Atualiza os dados de uma disciplina. Todos os campos são opcionais; envie apenas os que deseja alterar.

Parâmetros do corpo

name string opcional

Novo nome da disciplina (até 50 caracteres).

abbreviation string opcional

Nova abreviação da disciplina (até 4 caracteres). Deve ser única dentro da escola. Envie null para remover.

color string opcional

Nova cor em formato hexadecimal. Envie null para remover.

bncc_component_id uuid opcional

UUID do componente BNCC (envie null para desvincular).

Códigos de resposta

200

Sucesso.

404

Escola ou disciplina não encontrada.

409

Já existe outra disciplina com este nome ou abreviação na escola.

Requisição PUT

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/subject/a1b2c3d4-... \
  -X PUT \
  -H "X-Authorization: {api_token}" \
  -d '{"name":"Matemática II"}'

$client->put('.../subject/{id}', ['json' => ['name' => 'Matemática II']]);

await fetch('.../subject/{id}', { method: 'PUT', body: JSON.stringify({ name: 'Matemática II' }) });

Resposta

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Matemática II",
    "abbreviation": "MAT",
    "color": "#4F46E5",
    "bncc_component_id": null,
    "school_cnpj": "26019466000122"
  }
}

{
  "message": "Escola ou disciplina não encontrada."
}

{
  "message": "Já existe outra disciplina com este nome ou abreviação na escola."
}

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

Excluir disciplina

Remove uma disciplina da escola. A operação é irreversível. Não é possível excluir uma disciplina que esteja vinculada a uma série, a um professor ou à matriz de horários de uma turma.

Códigos de resposta

200

Disciplina excluída com sucesso.

404

Escola ou disciplina não encontrada.

409

A disciplina está em uso (vinculada a série ou professor) e não pode ser removida.

Requisição DELETE

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/subject/a1b2c3d4-... \
-X DELETE \
-H "X-Authorization: {api_token}"

$client->delete('.../subject/{id}');

await fetch('.../subject/{id}', { method: 'DELETE' });

Resposta

{
  "success": true
}

{
  "message": "Escola ou disciplina não encontrada."
}

{
  "message": "A disciplina está em uso (vinculada a série ou professor) e não pode ser removida."
}

Disciplinas

O modelo disciplina

Listar disciplinas

Parâmetros de rota

Códigos de resposta

Obter disciplina

Parâmetros de rota

Códigos de resposta

Criar disciplina

Parâmetros do corpo

Códigos de resposta

Editar disciplina

Parâmetros do corpo

Códigos de resposta

Excluir disciplina

Códigos de resposta