Ir para o conteúdo

Contratos propostos

Visão geral

Este documento propõe um contrato de integração com o sistema Sincronizador, cujo objetivo é compatibilizar com o FaceSchool as informações de escolas, turmas, alunos e responsáveis presentes nos ERP, além de notificar esses ERPs sobre as presenças dos alunos.

A autenticação poderá ser feita via API Key e JWT. Outras formas de autenticação podem ser discutidas conforme necessário.

Endpoints da API

1. Leitura de Escolas e Turmas

Rota: GET /schools

Este endpoint retorna todas as escolas e turmas cadastradas no sistema. A resposta pode ser paginada, utilizando os parâmetros page e pageSize como query string. Caso a paginação não seja utilizada, todas as escolas e turmas serão retornadas de uma vez.

Parâmetros de Paginação (opcionais): - page: Número da página (padrão: 1) - pageSize: Quantidade de itens por página (padrão: 10)

Exemplo de Requisição Paginada:

1
GET /schools?page=1&pageSize=10

Exemplo de Resposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "currentPage": 1,
  "pageSize": 10,
  "totalItems": 50,
  "totalPages": 5,
  "schools": [
    {
      "id": "451", // Campo obrigatório
      "name": "EMEF MARECHAL HENRIQUE TEIXEIRA LOTT", // Campo obrigatório
      "cnpj": "",
      "address": {
        "zipCode": "12010-123",
        "state": "MG",
        "city": "Belo Horizonte",
        "district": "Ouro Preto",
        "street": "Rua da Saudade",
        "number": "123 ABC",
        "complement": ""
      },
      "courses": [ // Campo obrigatório
        {
          "id": "12548", // Campo obrigatório
          "name": "1° ANO A", // Campo obrigatório
          "turn": "afternoon"  // Campo obrigatório
        },
        {
          "id": "12549", // Campo obrigatório
          "name": "1° ANO B", // Campo obrigatório
          "turn": "morning" // Campo obrigatório
        }
      ]
    }
  ]
}

2. Leitura de Alunos

Rota: GET /students?schoolId={schoolId}

Este endpoint retorna todos os alunos de uma escola específica, identificada pelo schoolId passado como query string. A resposta pode ser paginada, utilizando os parâmetros page e pageSize. Caso a paginação não seja utilizada, todos os alunos serão retornados de uma vez.

Parâmetros de Paginação (opcionais): - page: Número da página (padrão: 1) - pageSize: Quantidade de itens por página (padrão: 10)

Exemplo de Requisição Paginada:

1
GET /students?schoolId=451&page=2&pageSize=10

Exemplo de Resposta:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "currentPage": 2,
  "pageSize": 10,
  "totalItems": 50,
  "totalPages": 5,
  "students": [
    {
      "id": "90032", // Campo obrigatório
      "name": "CARLOS EDUARDO RIBEIRO DE LIMA", // Campo obrigatório
      "email": "[email protected]",
      "cpf": "54207147101",
      "sex": "M",
      "birthDate": "2015-03-26",
      "courses": [ // Campo obrigatório
        {
          "schoolId": "451", // Campo obrigatório
          "schoolName": "EMEF MARECHAL HENRIQUE TEIXEIRA LOTT", // Campo obrigatório
          "courseId": "12548", // Campo obrigatório
          "courseName": "1° ANO A", // Campo obrigatório
          "courseTurn": "afternoon" // Campo obrigatório
        }
      ],
      "responsibles": [
        {
          "id": "110181", // Campo obrigatório
          "cpf": "94124693222", // Campo obrigatório
          "name": "LAUDECI RIBEIRO", // Campo obrigatório
          "mail": "[email protected]",
          "phone1": "19912349418",
          "phone2": "1912347567"
        }
      ]
    }
  ]
}

3. Entrega de Webhook de Presença

Rota: POST /webhooks/presence

Esta rota é utilizada pelo Sincronizador para notificar o sistema externo sobre a presença de um aluno em uma turma. O sistema externo deve responder com um status 2xx para indicar sucesso. Caso contrário, o Sincronizador tentará reenviar a notificação por um período limitado.

Abaixo estão os detalhes de cada item presente no corpo da requisição enviada pelo webhook:

Campo Obrigatoriedade Descrição
studentId Obrigatório Identificador único do aluno no ERP.
date Obrigatório Data da presença no formato YYYY-MM-DD.
device Obrigatório Identificador do dispositivo que capturou a presença.
checkIn Opcional Data e hora do registro de entrada do aluno no formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.SSSZ).
undetermined Opcional Data e hora de um registro de presença que não está no período de entrada ou de saída. Pode ser null se não houver o reconhecimento nesse intervalo.
checkOut Opcional Data e hora do registro de saída do aluno, no formato ISO 8601. Será null se não for um registro de saída.
RegisteredByUserAt Opcional Data e hora de um registro de presença manual para um aluno, no formato ISO 8601. Será null se não houver registro manual.

Exemplo do body de uma Request:

1
2
3
4
5
6
7
8
9
{
  "studentId": "137347", // Campo obrigatório
  "date": "2023-10-10", // Campo obrigatório
  "checkIn": "2023-10-10T10:00:00.000Z",
  "undetermined": null,
  "RegisteredByUserAt": null,
  "checkOut": null,
  "device": "1234567890"
}

Observação sobre Autenticação: Efetuar uma autenticação completa (como a validação via API Key ou JWT) a cada notificação de presença pode ser custoso para o destinatário dos eventos, pois duplicaria o número de solicitações. Para evitar esse overhead, recomendamos o uso de um token fixo enviado junto com a notificação, que identifica o sistema remetente.