# Modelo de integração de cadastro O objetivo desse documento é oferecer uma proposta de modelo para a integração dos cadastros entre parceiros e o SAE Digital. Integrações que sigam esse modelo devem funcionar através de API REST, a ser chamada pelos sistemas SAE a cada atualização de dados. Uma requisição é efetuada a cada evento de cadastro/alteração/inativação de usuário, contendo os dados necessários. Para a carga inicial de usuários é preferível utilizar a própria integração. Nesses casos essa carga é feita fora de horário útil, visando minimizar impactos no desempenho dos serviços. Caso não seja possível, pode ser proposta outra forma de carga. ## ENTIDADES As entidades a serem mantidas são: **Escolas, Turmas, Coordenadores, Professores e Alunos**. Os usuários são agrupados em turmas, de acordo com as seguintes regras: * Alunos são vinculados a uma única turma * Professores podem ser vinculados a uma ou mais turmas, e cada vínculo de professor com turma também inclui um vínculo com um componente curricular. Um professor pode estar, ainda, vinculado mais de uma vez com a mesma turma, desde que através de componentes curriculares diferentes * Coordenadores podem ser vinculados a uma ou mais turmas, sem vínculo com componentes curriculares ## AUTENTICAÇÃO Uma chave de integração deve ser usada para autorizar cada requisição. Essa chave deve ser gerada e fornecida pela empresa parceira, passível de renovação mediante solicitação à equipe técnica responsável. A tecnologia da chave gerada é de definição da empresa parceira. O envio da chave é feito em todas as requisições, através do cabeçalho X-API-Key ```javascript headers = { "x-api-key": "abcd1234abcd1234" } ``` ## ROTAS **Todas** as entidades possuem rotas nos seguintes métodos HTTP: **POST:** Cadastrar Recebe no corpo da requisição o payload da entidade Retorna `{ "success": true }` **PATCH:** Editar Recebe no corpo da requisição o payload da entidade Retorna `{ "success": true }` **GET:** Obter uma entidade pelo id Recebe nos parâmetros da URL o id da entidade a ser retornada Retorna o payload da entidade **DELETE:** Inativar Recebe nos parâmetros da URL o id da entidade a ser inativada Retorna `{ "success": true }` ***Atenção: O método DELETE deve executar uma exclusão lógica do dado, ou seja, a informação deve ser devidamente sinalizada e não mais apresentada aos usuários. Dado algum deve ser apagado de forma definitiva. O mesmo registro pode ser posteriormente reativado caso seja chamado o método PATCH contendo o id correspondente, e caso isso ocorra, devem ser restaurados os vínculos de quaisquer atividades que tenham sido agendadas/realizadas. Professores e coordenadores podem possuir vínculo com mais de uma turma. Ao inativar um desses usuários, essa inativação vale para todos os vínculos.*** Não há necessidade sistêmica de uma rota que retorne *todos* os registros de uma certa entidade, pois pode haver grande quantidade de registros, seja com ou sem paginação. --- ### ESCOLA Rota: `POST /school` Rota: `PATCH /school` Rota: `GET /school/{school_id}` Rota: `DELETE /school/{school_id}` ```javascript payload = { id : 1234, // Int name : "Escola X" // String } ``` ### TURMA Rota: `POST /team` Rota: `PATCH /team` Rota: `GET /team/{team_id}` Rota: `DELETE /team/{team_id}` ```javascript payload = { id : 23456, // Int name : "3 serie C", // String school_id : 1234, // Int segment_id : 3, // Int, vide ENUMERADORES grade_id : 3 // Int, vide ENUMERADORES } ``` ### COORDENADOR Rota: `POST /coordinator` Rota: `PATCH /coordinator` Rota: `GET /coordinator/{coordinator_id}` Rota: `DELETE /coordinator/{coordinator_id}` ```javascript payload = [ { id : 98765, // Int name : "Fulano de Tal", // String email : "p.98765@prof.sae.digital", // String password : "coordenador@2021", // String team_id : 23456 // Int }, { id : 98765, // Int name : "Fulano de Tal", // String email : "p.98765@prof.sae.digital", // String password : "coordenador@2021", // String team_id : 23456 // Int }, ] ``` ***OBS: Em virtude de outras integrações, professores e coordenadores usam o mesmo padrão de e-mail. Como professores e coordenadores podem ter vínculo com mais de uma turma, os cada item do array contido no payload representa vínculo com uma turma. Quaisquer vínculos já existentes com turmas que não sejam contemplados no payload devem ser inativados, ou seja, o payload sempre carrega a totalidade de turmas daquele professor ou coordenador.*** ### PROFESSOR Rota: `POST /teacher` Rota: `PATCH /teacher` Rota: `GET /teacher/{teacher_id}` Rota: `DELETE /teacher/{teacher_id}` ```javascript payload = [ { id : 98765, // Int name : "Sicrano de Tal", // String email : "p.98765@prof.sae.digital", // String password : "professor@2021", // String team_id : 23456, // Int subject_id : 42 // Int, vide ENUMERADORES }, { id : 98765, // Int name : "Sicrano de Tal", // String email : "p.98765@prof.sae.digital", // String password : "professor@2021", // String team_id : 23456, // Int subject_id : 40 // Int, vide ENUMERADORES }, { id : 98765, // Int name : "Sicrano de Tal", // String email : "p.98765@prof.sae.digital", // String password : "professor@2021", // String team_id : 23458, // Int subject_id : 42 // Int, vide ENUMERADORES }, ] ``` ***OBS: Em virtude de outras integrações, professores e coordenadores usam o mesmo padrão de e-mail. Como professores e coordenadores podem ter vínculo com mais de uma turma, os cada item do array contido no payload representa vínculo com uma turma. Quaisquer vínculos já existentes com turmas que não sejam contemplados no payload devem ser inativados, ou seja, o payload sempre carrega a totalidade de turmas daquele professor ou coordenador.*** ### ALUNO Rota: `POST /student` Rota: `PATCH /student` Rota: `GET /student/{student_id}` Rota: `DELETE /student/{student_id}` ```javascript payload = { id : 98765, // Int name : "Beltrano de Tal", // String email : "a.98765@aluno.sae.digital", // String password : "professor@2021", // String team_id : 23456, // Int } ``` ## ENUMERADORES ### Segmentos (segment) ``` 1 = Ensino Fundamental I 2 = Ensino Fundamental II 3 = Ensino Médio 4 = Extensivo 8 = Ensino Infantil 9 = Extensivo Mega 10 = Semiextensivo ``` ### Séries (grade) ``` 1 = 1º ano 2 = 2º ano 3 = 3º ano 4 = 4º ano 5 = 5º ano 6 = 6º ano 7 = 7º ano 8 = 8º ano 9 = 9º ano 10 = 1ª série 11 = 2ª série 13 = 3ª série - Aprova + 14 = Demonstrativo 15 = Infantil I 16 = Infantil II 17 = Infantil III 18 = Infantil IV 19 = Infantil V 20 = Extensivo Mega 21 = Semiextensivo ``` ### Componentes curriculares (subject) ``` 34 = Artes 35 = Biologia 36 = Ciências 37 = Educação Física 38 = Espanhol 39 = Filosofia 40 = Física 41 = Geografia 42 = Matemática 43 = Informática 44 = Língua inglesa 45 = Literatura 46 = Língua Portuguesa 47 = História 48 = Química 49 = Produção de Texto 50 = Sociologia 51 = Não categorizado 52 = Plataforma Literária 59 = Projeto de Vida ```