Calendário Letivo

O calendário letivo registra todos os dias de um ano letivo, classificando-os como school_day, holiday ou event. Ao salvar o calendário, o campo school_days do ano letivo é recalculado automaticamente com base na contagem de dias do tipo school_day.

Todos os endpoints exigem os cabeçalhos X-Authorization, X-Partner e X-Client.

O modelo dia

Cada entrada no calendário representa um único dia do ano letivo com seu tipo e, opcionalmente, um nome descritivo.

date string (Y-m-d)

Data do dia no formato ISO 8601 (ex.: "2026-02-02").

type enum

Tipo do dia: school_day (dia letivo), holiday (feriado) ou event (evento).

name string|null

Nome descritivo. Obrigatório para holiday e event; nulo para school_day.

Modelo dia do calendário

{
  "date": "2026-02-02",
  "type": "school_day",
  "name": null
}

GET /v1/partners/school/{cnpj}/school-year/{id}/calendar

Obter calendário

Retorna todos os dias do calendário de um ano letivo, ordenados por data, junto com o total de dias letivos contabilizados.

Parâmetros de rota

cnpj string obrigatório

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

id string (uuid) obrigatório

ID do ano letivo.

Códigos de resposta

200

Calendário retornado com sucesso.

401

Autenticação inválida.

404

Ano letivo não encontrado.

Requisição GET

GET /v1/partners/school/{cnpj}/school-year/{id}/calendar

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}/calendar \
  -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/school-year/{id}/calendar', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
]);
$calendar = json_decode($response->getBody(), true);

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

Resposta

{
  "success": true,
  "data": {
    "school_year_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "school_days": 200,
    "days": [
      {
        "date": "2026-02-02",
        "type": "school_day",
        "name": null
      },
      {
        "date": "2026-02-16",
        "type": "holiday",
        "name": "Carnaval"
      }
    ]
  }
}

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

{
  "message": "Ano letivo não encontrado."
}

POST /v1/partners/school/{cnpj}/school-year/{id}/calendar

Salvar calendário

Substitui integralmente o calendário do ano letivo. Todos os dias existentes são removidos e recriados com base no array days enviado. Após salvar, o campo school_days do ano letivo é atualizado automaticamente com a contagem de entradas do tipo school_day. Eventos e feriados com nome também são recriados como eventos do calendário.

Parâmetros de rota

cnpj string obrigatório

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

id string (uuid) obrigatório

ID do ano letivo.

Corpo da requisição

days array obrigatório

Lista de dias do calendário. Pode ser vazia para limpar o calendário.

days[].date string (Y-m-d) obrigatório

Data do dia no formato Y-m-d.

days[].type enum obrigatório

Tipo do dia. Valores aceitos: school_day, holiday, event.

days[].name string|null opcional

Nome descritivo do dia. Recomendado para holiday e event.

Códigos de resposta

200

Calendário salvo com sucesso.

400

Erros de validação.

401

Autenticação inválida.

404

Ano letivo não encontrado.

Requisição POST

POST /v1/partners/school/{cnpj}/school-year/{id}/calendar

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}/calendar \
  -X POST \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -H "Content-Type: application/json" \
  -d '{"days":[{"date":"2026-02-02","type":"school_day","name":null},{"date":"2026-02-16","type":"holiday","name":"Carnaval"}]}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}/calendar', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
    'json' => [
        'days' => [
            ['date' => '2026-02-02', 'type' => 'school_day', 'name' => null],
            ['date' => '2026-02-16', 'type' => 'holiday', 'name' => 'Carnaval'],
        ],
    ],
]);
$result = json_decode($response->getBody(), true);

const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}/calendar', {
    method: 'POST',
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
        'Content-Type':    'application/json',
    },
    body: JSON.stringify({
        days: [
            { date: '2026-02-02', type: 'school_day', name: null },
            { date: '2026-02-16', type: 'holiday',    name: 'Carnaval' },
        ],
    }),
});
const result = await response.json();

Resposta

{
  "success": true,
  "data": {
    "school_year_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "school_days": 1
  }
}

{
  "message": "Erros de validação."
}

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

{
  "message": "Ano letivo não encontrado."
}