Gestão Escolar - API de integração
Introdução
Este manual é utilizado para integração com o site de vendas/e-commerce da instituição de ensino de modo que o site de vendas possa cadastrar e matricular os alunos no sistema Ultramax.
Pré-Requisitos
- No endereço dos endopoints abaixo trocar o "(base)" pelo host da instituição, por exemplo: https://demo.ultramax.com.br/, já que cada instituição tem o seu host independente.
- Para gerar o codigoAPI e senhaAPI entre em contato com o suporte da Ultramax através do e-mail suporte@ultramax.com.br ou através de outros canais de atendimento do site www.ultramax.com.br
- Além do codigoAPI e senhaAPI entrar em contato com a Ultramax para solicitar a criação de um ambiente de testes.
- Ver o Wiki a seguir para fazer as configurações necessárias no sistema: Gestão Escolar - CFGAPI001 - Configuração do sistema para aceitar matrículas pela API de integração
Padrões
Cada endpoint executado retorna uma resposta com um wrap contendo:
· Os dados que foram processados
· A situação do processamento (OK, JAPROCESSADO, ERRO, CURSO_NAO_EXISTE, ALUNO_NAO_EXISTE)
· Response com o código http (200, 409,417, 500 e 204)
Endpoints da API
Gerar token de autenticação
Gera um token de autenticação para acessar os recursos da API de Integração do gestão escolar. Este token deve ser utilizado para consumir os demais endpoints.
Método: Post
(base)/gestaoescolar/services/login/login/autentica
Body
| Atributo | Descrição |
| senhaApi | Deve ter a senha que foi gerada ao cadastrar um registro de api no sistema gestão escolar |
| codigoApi | Deve ter o código de api que foi gerado ao cadastrar um registro de api no sistema gestão escolar |
Respostas esperadas
Status 200 , com o respectivo código de token gerado. Onde o código é composto por: Código da api, Data hora atual, Tempo de expiração em 15 minutos, Chave interna
Status 500. Caso algum erro interno ocorra durante o processamento
APIS para consultas
Estrutura da resposta
Cada resposta a uma requisição irá retornar uma estrutura de dados json do Seguinte formato:
| Campo | Descrição |
| acao | Mensagem de texto com o que foi retornado pela requisição |
| dados | Array com os dados que foram requisitados na consulta. Caso esteja tudo correto é desse campo que os dados devem ser retirados para a consulta. Em caso de algum erro irá retornar vazio. |
| response | Código HTTP que foi retornado (OK - 200, EXPECTATION_FAILED - 417 - Unauthorized - 401 , etc ) |
| statusProcessamento | Código interno Ultramax, para consultas (OK, ERRO) |
Todas as estruturas possíveis de retorno estão listadas abaixo:
Todo request precisa ter no header o token de autenticação, que é obtido através do endpoint de geração de token.
CURSOS: Obtendo dados:
Busca os cursos cadastrados na base de dados de acordo com os parâmetros informados na query string.
Método: GET
(base)/gestaoescolar/services/v1/cursos?codigoUnidadeEnsino=1&periodoLetivo=2022
Query String (Parâmetros)
| Campo | Descrição |
| codigoUnidadeEnsino | Código da unidade de ensino |
| periodoLetivo | Descrição do período letivo, deve ter o mesmo valor da descrição definida na Gestão Escolar. Por exemplo, se deve considerar apenas matrículas do período letivo de 2012, deve ser informado “2012”, exatamente como está cadastrado na gestão Escolar |
| nomeTurma | Texto para localizar parcialmente os registros usando a descrição da turma |
| codigoCurso | Código do curso que deve ter as matrículas retorna |
| nomeCurso | Texto para localizar parcialmente os registros usando a descrição da curso |
| numeroSequenciaSerie | Representa um número inteiro que define a ordem de sequência de uma série no curso. EX:
Ao definir o curso Robótica com três séries (1º, 2º, 3º), no cadastro de séries da Gestão Escolar é definida a ordem de sequência de cada série para o curso, para que seja possível saber para qual série o Aluno vai ao fim de cada período letivo. Informando o número exato, será retornada as matrículas especificas daquela série |
| codigoIntegracaoCurso | Identificador de integração entre o Sistema de terceiros e o da Ultramax no cadastro de cursos de EAD. Vai servir também para identificar qualquer outro sistema de terceiro que utilizar a API de integração de cursos para criar cursos no Gestão Escolar
Informando o código, irá retornar a série correspondente cadastrada |
| pagina (paginação) | Indica qual página está listando na sequência |
| registros (paginação) | Quantidade de registros que devem ser retornados em cada página |
Respostas esperadas
Status 200: : OK (Exemplo)
Status 417:: Caso não seja informado o código da unidade de negócio e a descrição do período letivo (Exemplo)
Status 401: : Caso o token de autenticação não esteja no header da requisição ou esteja expirado (Exemplo)
| Atributo | Descrição | Tipo | Tamanho |
| id | Identificador interno (id) | Número | |
| codigoUnidade | Código da unidade de ensino | Número | |
| periodoLetivo | Descrição do período Letivo | Texto | 20 |
| codigoCurso | Código do curso | Texto | 15 |
| nomeCurso | Nome do curso | Texto | 70 |
| itemServico | Código do item de serviço do curso | Texto | 9 |
| codigoIntegracao | Código sku de integração entre sistemas de terceiro | Texto | 255 |
| modalidadeCurso | Modalidade do Curso (EAD, Presencial) | Texto | 50 |
| naturezaOperacao | Natureza de operação que o curso permite | Texto | 70 |
| statusCurso | Situação do curso (A, I) Onde A = Ativo,I = Inativo | Texto | 1 |
SÉRIES: Obtendo dados:
Busca os cursos cadastrados na base de dados de acordo com os parâmetros informados na query string.
Método: GET
(base)/gestaoescolar/services/v1/series?codigoUnidadeEnsino=1&periodoLetivo=2022
Query String (Parâmetros)
| Obrigatório | Campo | Descrição | |
| Sim | codigoUnidadeEnsino | Código da unidade de ensino | |
| periodoLetivo | Descrição do período letivo, deve ter o mesmo valor da descrição definida na Gestão Escolar. Por exemplo, se deve considerar apenas matrículas do período letivo de 2012, deve ser informado “2012”, exatamente como está cadastrado na gestão Escolar | ||
| codigoCurso | Código do curso que deve ter as matrículas retorna | ||
| numeroSequenciaSerie | Representa um número inteiro que define a ordem de sequência de uma série no curso. EX:
Ao definir o curso Robótica com três séries (1º, 2º, 3º), no cadastro de séries da Gestão Escolar é definida a ordem de sequência de cada série para o curso, para que seja possível saber para qual série o Aluno vai ao fim de cada período letivo. Informando o número exato, será retornada as matrículas especificas daquela série |
||
| nomeSerie | Nome da série será avaliado no campo da série se o valor contém o registro | ||
| Status | Indica a situação da série que deve ser considerada (ATIVO, INATIVO) | ||
| codigoIntegracaoCurso | Identificador de integração entre o Sistema da ASAS e o da Ultramax no cadastro de cursos de EAD. Vai servir também para identicar qualquer outro sistema de terceiro que utilizar a API de integração de cursos para criar cursos no Gestão Escolar
Informando o código, irá retornar a série correspondente cadastrada |
||
| pagina (paginação) | Indica qual página está listando na sequência | ||
| registros (paginação) | Quantidade de registros que devem ser retornados em cada página |
Respostas esperadas
Status 200: : OK (Exemplo)
Status 417: : Caso não seja informado o código da unidade de negócio e a descrição do período letivo (Exemplo)
Status 401: : Caso o token de autenticação não esteja no header da requisição ou esteja expirado (Exemplo)
| Atributo | Descrição | Tipo | Tamanho |
| codigoIntegracaoCurso | Código identificador do Curso | Texto | 255 |
| codigoUnidade | Código da unidade de ensino que o curso pertence. | Número | |
| descricaoUnidade | Descrição com o nome da unidade de ensino | Texto | 40 |
| periodoLetivo | Descrição do período Letivo atual | Texto | 20 |
| codigoCurso | Código do curso | Texto | 15 |
| nomeCurso | Nome do curso | Texto | 70 |
| numeroSequenciaSerie | Numero inteiro indicando com a sequência da série no curso que a matrícula deve ser feita. Ex: um curso que tenha | Número | |
| nomeSerie | Nome da série | Texto | 70 |
| Status | Situação da série (ATIVO, INATIVO, etc..) | Texto | 10 |
TURMAS: Obtendo dados:
Busca os cursos cadastrados na base de dados de acordo com os parâmetros informados na query string.
Método: GET
(base)/gestaoescolar/services/v1/turmas?codigoUnidadeEnsino=1&periodoLetivo=2022
Query String (Parâmetros)
| Obrigatório | Campo | Descrição |
| codigoUnidadeEnsino | Código da unidade de ensino | |
| periodoLetivo | Descrição do período letivo, deve ter o mesmo valor da descrição definida na Gestão Escolar. Por exemplo, se deve considerar apenas matrículas do período letivo de 2012, deve ser informado “2012”, exatamente como está cadastrado na gestão Escolar | |
| nomeTurma | Texto para localizar parcialmente os registros usando a descrição da turma | |
| codigoCurso | Código do curso que deve ter as matrículas retorna | |
| nomeCurso | Nome do curso para verificação se existe no cadastro de curso | |
| numeroSequenciaSerie | Representa um número inteiro que define a ordem de sequência de uma série no curso. EX:
Ao definir o curso Robótica com três séries (1º, 2º, 3º), no cadastro de séries da Gestão Escolar é definida a ordem de sequência de cada série para o curso, para que seja possível saber para qual série o Aluno vai ao fim de cada período letivo. Informando o número exato, será retornada as matrículas especificas daquela série | |
| status | Situação possíveis para busca da turma (VIG, FOR,ENC, TODAS) | |
| codigoIntegracaoCurso | Identificador de integração entre o Sistema de terceiros e o da Ultramax no cadastro de cursos de EAD. Vai servir também para identificar qualquer outro sistema de terceiro que utilizar a API de integração de cursos para criar cursos no Gestão Escolar
Informando o código, irá retornar a série correspondente cadastrada | |
| pagina (paginação) | Indica qual página está listando na sequência | |
| registros (paginação) | Quantidade de registros que devem ser retornados em cada página |
Respostas esperadas
Status 200: : OK (Exemplo)
Status 417: : Caso não seja informado o código da unidade de negócio e a descrição do período letivo (Exemplo)
Status 401: : Caso o token de autenticação não esteja no header da requisição ou esteja expirado (Exemplo)
| Atributo | Descrição | Tipo | Tamanho |
| codigoUnidade | Código da unidade de ensino que o curso pertence. | Número | |
| periodoLetivo | Descrição do período Letivo atual | Texto | 20 |
| id | Código identificador interno do Gestão Escolar representando o ID único da turma | Númerico | |
| codigoCurso | Código do curso | Texto | 15 |
| nomeCurso | Nome do curso | Texto | 70 |
| numeroSequenciaSerie | Numero inteiro indicando com a sequência da série no curso que a matrícula deve ser feita. Ex: um curso que tenha | Número | |
| nomeSerie | Nome da série | Texto | 70 |
| nomeTurma | Nome da turma | Texto | 65 |
| status | Situação possíveis para busca da turma (VIG, FOR,ENC) onde VIG = Vigência, FOR = Em formação e ENC = ENCERRADA | Texto | 3 |
MATRÍCULAS: Obtendo dados:
Busca os cursos cadastrados na base de dados de acordo com os parâmetros informados na query string.
Método: GET
(base)/gestaoescolar/services/v1/matriculas?codigoUnidadeEnsino=1&periodoLetivo=2022
Query String (Parâmetros)
| Obrigatório | Campo | Descrição |
| codigoUnidadeEnsino | Código da unidade de ensino | |
| periodoLetivo | Descrição do período letivo, deve ter o mesmo valor da descrição definida na Gestão Escolar. Por exemplo, se deve considerar apenas matrículas do período letivo de 2012, deve ser informado “2012”, exatamente como está cadastrado na gestão Escolar | |
| codigoCurso | Código do curso que deve ter as matrículas retornas | |
| numeroSequenciaSerie | Representa um número inteiro que define a ordem de sequência de uma série no curso. EX:
Ao definir o curso Robótica com três séries (1º, 2º, 3º), no cadastro de séries da Gestão Escolar é definida a ordem de sequência de cada série para o curso, para que seja possível saber para qual série o Aluno vai ao fim de cada período letivo. Informando o número exato, será retornada as matrículas especificas daquela série | |
| nomeTurma | Nome da turma exato que deve ser considerado | |
| nomeAluno | Irá retornar todas as matrículas que contém a parte informada do nome | |
| cpf | Deve ter o valor numérico exato do CPF do aluno | |
| rm | Deve ter a String exata que representa a Registro de Matrícula do aluno | |
| statusMatricula | Status da matrícula que deve ser considerada na busca. Opções: MAT(Matrículado), ATI(Ativo), PRE (Pré matrícula) | |
| pagina (paginação) | Indica qual página está listando na sequência | |
| registros (paginação) | Quantidade de registros que devem ser retornados em cada página |
Respostas esperadas
Status 200: : OK (Exemplo)
Status 417: : Caso não seja informado o código da unidade de negócio e a descrição do período letivo (Exemplo)
Status 401: : Caso o token de autenticação não esteja no header da requisição ou esteja expirado (Exemplo)
| Atributo | Descrição | Tipo | Tamanho |
| id | Código identificador único (id) | Número | |
| codigoMatriculaUnico | Código de integração para busca de uma matrícula ou para criar uma nova gerado pela Integração com terceiros | Texto | 255 |
| origem | Origem da matrícula, como padrão "Plataforma EAD" | Texto | 20 |
| Aluno | Dados básicos do aluno que devem ser considerados no retorno da matricula | Aluno* | 1..1 |
| StatusMatricula | Status atual da matrícula
PRE Pré Matricula ATI Ativa MAT Matriculado CON Concluída TRF Transferido TRI Transf. interno TRC Trancada DES Desistência/Evasão CAN Cancelada erro operacional CAL Cancelada pelo aluno |
StatusMatricula | 1..1 |
| Turmas | Turmas que pertencem a matrícula | Turma* | 0..N |
| Serie | Dados da série relacionado a matrícula | Serie | 1.1 |
| Curso | Dados do curso relacionado a matrícula | Curso | 1..1 |
*Os tipos de dados estão definidos abaixo
StatusMatricula:
| Atributo | Descrição | Tipo | Tamanho |
| codigo | Identificador ATI = Ativa, CAN = Cancelada, CAL = Cancelada pelo aluno, CON = Concluída, DES = Desistência aluno, MAT = Matrículado, PRE = Pré matrícula | String | 3 |
| descricao | Descrição do status matrícula | String | 30 |
Sexo:
| Atributo | Descrição | Tipo | Tamanho |
| codigo | Identificador do Sexo (F feminino, M Masculino, N Não declarado) | String | 1 |
| descricao | Descrição do sexo | String | 15 |
Estado Civil:
| Atributo | Descrição | Tipo | Tamanho |
| codigo | Número identificador
1 = Solteiro , 2 = Casado, 3 = Separado, 4 = Desquitado,5 = Divorciado, 6 = VIÚVO, 7 = OUTROs,8= União estável, 9 = Não informado |
String | 1 |
| descricao | Descrição do sexo | String | 30 |
Responsável:
| Atributo | Descrição | Tipo | Tamanho |
| id | Identificador interno (id) | Número | |
| celular | Número do celular do aluno | Texto | 15 |
| cpf | C.P.F do aluno | Número | |
| nome | Nome do aluno | Texto | 70 |
| nascimento | Data de nascimento do aluno | Data | |
| E-mail do aluno | Texto | 255 | |
| endereco | Endereço do Aluno | Endereco | 0..1 |
| estadoCivil | Estado cívil do aluno | EstadoCivil | 0..1 |
| sexo | Sexo do aluno | Sexo | 0..1 |
| rg | R.G. do responsável | Texto | 25 |
| nacionalidade | Nacionalidade do responsável | Texto | 30 |
| falecido | indica se o responsável já faleceu | bit | 1 |
Aluno:
| Atributo | Descrição | Tipo | Tamanho |
| id | Identificador interno (id) | Número | |
| celular | Número do celular do aluno | Texto | 15 |
| cpf | C.P.F do aluno | Número | |
| nome | Nome do aluno | Texto | 70 |
| nascimento | Data de nascimento do aluno | Data | |
| E-mail do aluno | Texto | 255 | |
| endereco | Endereço do Aluno | Endereco | 1..1 |
| estadoCivil | Estado cívil do aluno | EstadoCivil | 0..1 |
| rm | Registro de matrícula do aluno | Texto | 20 |
| filiacao1 | Filiação 1 (mãe) do aluno | Responsavel | 0..1 |
| filiacao2 | Filiação 2 (pai) do aluno | Responsavel | 0..1 |
| responsavelFinanceiro (I) | Responsável financeiro do aluno | Responsável | 1..1 |
| sexo | Sexo do aluno | Sexo | 0..1 |
Estado:
| Atributo | Descrição | Tipo | Tamanho |
| sigla | Identificador para o Estado | Texto | 2 |
| descricao | Descrição do Estado | Texto | 30 |
Endereco:
| Atributo | Descrição | Tipo | Tamanho |
| bairro | Bairro que o aluno mora | Texto | 60 |
| cep | CEP que o aluno mora | Texto | 15 |
| cidade | Cidade que o aluno mora | Texto | 20 |
| complemento | Complemento do endereço onde o aluno mora | Texto | 60 |
| numero | Número do endereço que o aluno mora | Texto | 7 |
| logradouro | Nome do logradouro que o aluno mora | Texto | 60 |
| estado | Estado da Federação que o aluno mora | Estado* |
Resumo financeiro: Obtendo dados:
Busca o resumo financeiro sumarizado por tipo de movimentação financeira ("Receber" e "Pagar") e contas contábeis dentro do intervalo de datas informado.
Método: GET
(base)/gestaoescolar/services/v1/resumofinanceiro?inicio=01/01/2022&periodoLetivo=31/12/2021
Query String (Parâmetros)
| Obrigatório | Campo | Descrição |
| Sim | inicio | Data de inicio considerando o data de faturamento da movimentação financeira no formato dd/MM/aaaa |
| Sim | fim | Data de termino considerando o data de faturamento da movimentação financeira no formato dd/MM/aaaa |
| pagina (paginação) | Indica qual página está listando na sequência | |
| registros (paginação) | Quantidade de registros que devem ser retornados em cada página |
Respostas esperadas
Status 200: : OK
Status 417: : Caso não seja informado o código da unidade de negócio e a descrição do período letivo
Status 401: : Caso o token de autenticação não esteja no header da requisição ou esteja expirado
| Atributo | Descrição | Tipo | Tamanho |
| mes | Representação numérica com o mês que foi contabilizado (Exemplo: janeiro = 1) | Número | |
| ano | Ano que foi contabilizado | Número | |
| codigoContaContabil | Código com a conta contábil contabilizada | Texto | 15 |
| codigoContaContabilExterna | Código utilizada por um sistema externo com a conta contábil contabilizada, esse caso é para associar um "de para" entre a conta contágio do Ultramax Gestão Escolar e um sistema externo | Texto | 255 |
| tipo | Tipo da movimentação financeira contabilizada. Os tipos podem ser "Receber" e "Pagar" | Texto | 7 |
| valor | Valor total sumarizado por mês/Ano/Tipo/Conta Contábil | Número | |
| percentualValorRelacaoTotal | O quanto equivale em percentual em relação ao Total geral por Tipo dentro do intervalo pesquisado | Número |
APIS para manutenção da base de dados
Manutenção de cursos
Faz a manutenção de um curso. Através do código de integração será localizado um curso existente para alteração ou, caso não exista, será criado um novo curso
Método: Post
(base)/gestaoescolar/services/curso/rest/add
Body
| Atributo | Descrição | Tipo | Mínimo | Máximo |
| sigla | Código identificador do Curso | S | 1 | 15 |
| codigoUnidade | Código da unidade de ensino que o curso pertence. Fixo "1" | N | 1 | 3 |
| nome | Descrição do curso | S | 1 | 70 |
| itemServico | Código do serviço para emissão de NFS-e. Depende de cada instituição e do curso. Por exemplo: 05673. Ver com a instituição qual código usar para cada curso | S | 4 | 9 |
| codigoIntegracao | Código único de integração, será a chave entre os diferentes sistemas | S | 1 | 255 |
| modalidadeCurso | ‘EAD’ fixo | S | 1 | 30 |
| naturezaOperacao | Natureza de operação será usada na geração das notas fiscais
Valores válidos: CANCELADO("Cancelado"), EXIGIBILIDADE_SUSPENSAO_DECISAO_JUDICAL( "Exigibilidade por suspensão de decisão judicial - Válido até 22/02/2015"), EXIGIBILIDADE_SUSPENSAO_DECISAO_JUDICAL_2( "Exigibilidade por suspensão de decisão judicial"), EXIGIBILIDADE_SUSPENSAO_PROCEDIMENTO_ADM( "Exigibilidade por suspensão de procedimento administrativo - Válido até 22/02/2015"), EXIGIBILIDADE_SUSPENSAO_PROCEDIMENTO_ADM_2( "Exigibilidade por suspensão de procedimento administrativo"), EXIGIBILIDADE_SUSPENSAO_TRIBUTADO_FORA_MUNICIPIO( "Tributado fora do Munícipio, porém Exigibilidade Suspensa - Válido a partir de 23/02/2015"), EXIGIBILIDADE_SUSPENSAO_TRIBUTADO_MUNICIPIO( "Tributado no Munícipio, porém Exigibilidade Suspensa - Válido a partir de 23/02/2015"), EXPORTACAO( "Exportação"), EXPORTACAO_SERVICO( "Exportação de serviços - Válido a partir de 23/02/2015"), EXTRAVIADO("Extraviado - Válido até 22/02/2015"), IMUNE("Imune - Válido até 22/02/2015"), IMUNIDADE("Imunidade"), ISENCAO("Isenção - Válido até 22/02/2015"), ISENCAO_ATUAL("Isenção"), MICRO_EMPREENDEDOR_INDIVIDUAL("Micro Empreendedor Individual (MEI)"), SIMPLES("Simples Nacional"), TRIBUTACAO_FORA_MUNICIPIO("Tributação fora do munipio"), TRIBUTACAO_MUNICIPIO("Tributação no municipio"), TRIBUTADO_FORA_MUNICIPIO_IMUNE() "Tributado fora do município, porém Imune - Válido a partir de 23/02/2015"), TRIBUTADO_FORA_MUNICIPIO_ISENTO( "Tributado fora do município, porém Isento - Válido a partir de 23/02/2015"), TRIBUTADO_MUNICIPIO_IMUNE("Tributado no município, porém Imune - Válido a partir de 23/02/2015"), TRIBUTADO_MUNICIPIO_ISENTO("Tributado no município, porém Isento - Válido a partir de 23/02/2015"); |
N | 1 | 50 |
Respostas esperadas
Status 200: Status Processamento: OK
Status 417: Status Processamento: JACADASTRADO. Quando a mesma sigla de curso está cadastrado em mais de um registro.
Status 500: Status Processamento: ERRO
Exemplo:
Requisição
{"sigla":"Curso","codigoUnidade":1,"nome":"Curso teste","itemServico":"545454","codigoIntegracao":"SA-KJ-AD-NB","modalidadeCurso":"EAD"}
Resposta
{
"dados": {
"sigla": "Curso",
"codigoUnidade":1,
"nome": "Curso teste",
"itemServico": "545454",
"codigoIntegracao": "SA-KJ-AD-NB",
"modalidadeCurso": "EAD"
},
"statusProcessamento": "OK",
"response": "ACCEPTED",
"acao": "Manutenção OK"
}
Manutenção de alunos
Adiciona ou altera um aluno. Através do C.P.F informado será localizado na base de dados do gestão escolar o aluno correspondente. Caso encontre, será atualizado todos os campos bases enviados no header, por outro lado, caso não encontre, será incluído um novo registro para o aluno.
Método: Post
(base)/gestaoescolar/services/aluno/rest/responsavelfinanceiro
Body
| Atributo | Descrição | Tipo | Mínimo | Máximo |
| nome | Nome do aluno. | S | 1 | 70 |
| celular | Número de telefone celular Ex: 11998465521 ou (11) 99999-9999 | S | 11 | 15 |
| cpf | Sequencia numérica com o CPF do aluno Ex. 65696655565 | N | 11 | 11 |
| Email do aluno Ex: aluno@aluno.com.br | S | >1 | 255 | |
| enderecoBairro | Bairro do end residencial do aluno Ex. vila didi | S | 1 | 60 |
| enderecoCep | CEP do end residencial do aluno Ex. 13203320 | S | 8 | 8 |
| enderecoCidade | Cidade do end residencial do aluno Ex. jundiai | S | 1 | 20 |
| enderecoComplemento | Complemento do end residencial do aluno Ex. casa | S | 0 | 60 |
| enderecoEstado | Estado do end residencial do aluno Ex. SP Max 2 caracteres deve ser a sigla correspondente ao Estado | S | 2 | 2 |
| enderecoLogradouro | Logradouro do end residencial do aluno Ex. rua guapore | S | 1 | 60 |
| enderecoNumero | Número do end residencial do aluno Ex. 521 | S | 0 | 7 |
| nascimento | Date com a data de nascimento do aluno dd/MM/yyyy | S | 10 | 10 |
| rg | RG do aluno Ex: 584245999 | S | >1 | 25 |
| sexo | Indicador do gênero do aluno Ex MASCULINO.
MASCULINO/FEMININO/NAODECLARADO |
S | 8 | 15 |
| nacionalidade | Nacionalidade do aluno | S | 0 | 30 |
| filiacao1 | Filiação 1 do aluno (Detalhes tabela pessoa) | PessoaRemote | ||
| filiacao2 | Filiação 2 do aluno (Detalhes tabela pessoa) | PessoaRemote | ||
| rm | Código de matrícula que deve ser informado apenas quando o autonumeração de RM está desligada no Gestão Escolar | S | 0* | 20 |
Respostas esperadas
Status 200: Status Processamento: OK
Status 417: Status Processamento: ERRO, JACADASTRADO
Status 500: Status Processamento: ERRO
Exemplo
Requisição
{"celular":"11998465521","cpf":2865474325,"email":"wescleyfcosta@gmail.com","enderecoBairro":"vila didi","enderecoCep":"13203320","enderecoCidade":"jundiai","enderecoComplemento":"casa","enderecoEstado":"SP","enderecoLogradouro":"rua guapore","enderecoNumero":"521","nascimento":319518000000,"nome":"wescley","rg":"584245999","sexo":"MASCULINO"}
Resposta
{
"dados": {
"celular": "11998465521",
"cpf": 2865474325,
"email": "wescleyfcosta@gmail.com",
"enderecoBairro": "vila didi",
"enderecoCep": "13203320",
"enderecoCidade": "jundiai",
"enderecoComplemento": "casa",
"enderecoEstado": "SP",
"enderecoLogradouro": "rua guapore",
"enderecoNumero": "521",
"nascimento": 319518000000,
"nome": "wescley",
"rg": "584245999",
"sexo": "MASCULINO"
},
"statusProcessamento": "OK",
"response": "ACCEPTED",
"acao": "Manutenção OK"
}
Validações possíveis:
Existem diversas validações internas que podem retornar uma falha ao cadastrar um aluno. São elas:
- Trocar senha com perfil de autenticação inválido
- O cadastro do aluno não está mais ativo
*- O formato do CPF é inválido
- Informou uma senha que não está dentro das regras definidas na configuração
- Quando a configuração não for autonumeração de RM e passar um RM que já existe para outro CPF (Vai dar o JACADASTRADO)
* - O responsável financeiro for menor que 18 anos
* - Quando o endereço residencial do aluno não é fornecido
Os marcados com * são os que podem ocorrer usando essa API
Manutenção de matrículas
Adiciona ou altera uma matrícula. Pelo código da matrícula único, código de integração entre os sistemas, será possível atualizar os dados de uma matrícula, caso ela exista, ou incluir uma nova.
Método: Post
(base)/gestaoescolar/services/matricula/rest/add
Body
| Atributo | Descrição | Tipo | Mínimo | Máximo |
| cpf_cnpj | CPF do aluno que será gerada a matrícula, apenas numeros | N | 11 | 11 |
| codigoIntegracao | Código de integração para um Curso existente | S | 1 | 255 |
| codigoMatriculaUnico | Código de integração para busca de uma matrícula ou para criar uma nova | S | 1 | 255 |
| codigoUnidade | Código da unidade de ensino que o curso pertence. Fixo "1" | N | 1 | 3 |
| numeroSerieDeMatricula | numero inteiro indicando com a sequência da série no curso que a matrícula deve ser feita. Ex: um curso que tenha três séries e a matrícula deve ser feita no primeira delas, deve passar 1 | N | 1 | 3 |
| valor | Valor total do curso. Ex. 1000.0 | N | ||
| quantidadeParcelas | Quantidade de parcelas. Ex 1 | N | 1 | 3 |
| formaPagamento | Forma de pagamento que deve usado na baixa do título.
Valores válidos: DINHEIRO, CHEQUE, C_CREDITO,C_DEBITO, BOLETO, DEB_AUTOMATICO,TRANSFERENCIA, DOC,OUTRO_BAIXA_ADM,DEPOSITO,DUPLICADA, FIES, PREFEITURA,PROUNI, FOLHA_DE_PGTO, CHEQUE_PRE,PAGAMENTO_ONLINE, PERMUTA, PIX |
S | 3 | 20 |
| origem | Origem da matrícula, como padrão "Plataforma EAD" | S | 1 | 50 |
| titulos | Lista de títulos que foram gerados e que precisam ser compartilhados com o Gestão Escolar. Eles ficarão marcados no sistema Gestão Escolar como "pagamento de terceiro" e a sua baixa, alteração ou cancelamento devem ser feitas pelas Apis que serão descritas na parte financeira desse documento
Detalhes da api na tabela TituloRemote |
Titulo |
Respostas esperadas
Status 200: Status Processamento: OK
Status 417: Status Processamento: JACADASTRADO (quando existe uma outra matrícula não cancelada no mesmo período letivo)
Status 417: Status Processamento: CURSO_NAO_EXISTE (quando o código de integração informado não encontrou um curso correspondente cadastrado)
Status 417: Status Processamento: ALUNO_NAO_EXISTE (quando o C.P.F informado não encontrou um aluno correspondente cadastrado)
Status 417: Status Processamento: TITULO_NAO_EXISTE (Quando o título informado não existe)
Status 500: Status Processamento: ERRO
Exemplo
Requisição
{"cpf_cnpj":2865474325,"codigoIntegracao":"SA-KJ-AD-NB","codigoMatriculaUnico":"201254", "codigoUnidade":"1","numeroSerieDeMatricula":1,"valor":1000.0,"quantidadeParcelas":1,"formaPagamento":"DINHEIRO"}
Resposta
{
"dados": {
"pagamentoCartao": false,
"cpf_cnpj": 2865474325,
"codigoIntegracao": "SA-KJ-AD-NB",
"codigoMatriculaUnico": "201254",
"codigoUnidade":1,
"numeroSerieDeMatricula": 1,
"valor": 1000.0,
"quantidadeParcelas": 1,
"formaPagamento": "DINHEIRO", },
"statusProcessamento": "OK",
"response": "ACCEPTED",
"acao": "Manutenção OK"
}
Manutenção de Pessoas
Usado nos dados do aluno para representar uma filiação.
| Atributo | Descrição | Tipo | Mínimo | Máximo |
| nome | Nome do aluno. | S | 1 | 70 |
| celular | Número de telefone celular Ex: 11998465521 ou (11) 99999-9999 | S | 11 | 15 |
| cpf | Sequencia numérica com o CPF do aluno Ex. 65696655565 | N | 11 | 11 |
| Email do aluno Ex: aluno@aluno.com.br | S | >1 | 255 | |
| enderecoBairro | Bairro do end residencial do aluno Ex. vila didi | S | 1 | 60 |
| enderecoCep | CEP do end residencial do aluno Ex. 13203320 | S | 8 | 8 |
| enderecoCidade | Cidade do end residencial do aluno Ex. jundiai | S | 1 | 20 |
| enderecoComplemento | Complemento do end residencial do aluno Ex. casa | S | 0 | 60 |
| enderecoEstado | Estado do end residencial do aluno Ex. SP Max 2 caracteres deve ser a sigla correspondente ao Estado | S | 2 | 2 |
| enderecoLogradouro | Logradouro do end residencial do aluno Ex. rua guapore | S | 1 | 60 |
| enderecoNumero | Número do end residencial do aluno Ex. 521 | S | 0 | 7 |
| nascimento | Date com a data de nascimento do aluno dd/MM/yyyy | S | 10 | 10 |
| rg | RG do aluno Ex: 584245999 | S | >1 | 25 |
| sexo | Indicador do gênero do aluno Ex MASCULINO.
MASCULINO/FEMININO |
S | 8 | 15 |
| nacionalidade | Nacionalidade do aluno | S | 0 | 30 |
Financeiro: Criação de título na matrícula (Titulo)
Usada na API de matrícula do aluno. Cada título deve ser adicionado na API da Matrícula do aluno. A API de matrículas foi alterada para permitir incluir títulos na alteração. Com isso, será possível adicionar novos títulos para matrículas já existentes, desde que o código "nosso número" já não esteja associado a outro títulos no sistema gestão escolar.
| Atributo | Descrição | Tipo | Mínimo | Máximo |
| dataVencimento | Data de vencimento do título | S | 10 | 10 |
| nossoNumero | Número gerado pelo sistema interno que criou o título e que deve ser compartilhado com o Gestão Escolar para que cada interação funcione de forma correta | S | 1 | 50 |
| valorDocumento | Valor que representa o título | N |
Financeiro: Alteração de títulos
Método: Post
(base)/gestaoescolar/services/financeiro/rest/titulo
Ao fazer um POST com indicando o campo de integração (Nosso número) , o valor do documento e a data de vencimento o Web Service irá fazer alteração dos campos correspondentes no boleto já gerado durante a fase da matricula do aluno permitindo assim que os dados desses campos fiquem sincronizados entre os sistemas.
| Atributo | Descrição | Tipo | Mínimo | Máximo |
| dataVencimento | Data de vencimento do título | S | 10 | 10 |
| nossoNumero | Número gerado pelo sistema interno que criou o título e que deve ser compartilhado com o Gestão Escolar para que cada interação funcione de forma correta | S | 1 | 50 |
| valorDocumento | Valor que representa o título | N |
Respostas esperadas
Status 200: Status Processamento: OK
Status 417: Status Processamento: TITULO_NAO_EXISTE (Quando o título informado não existe)
tatus 417: Status Processamento: ERRO: Erro genérico de negócio
Status 500: Status Processamento: ERRO
Exemplo
Requisição
Body:
{"nossoNumero":"58745876","valorDocumento":"1100.0", "dataVencimento":"11/07/2021"}
Resposta
{
"acao": "Manutenção OK",
"dados": {
"nomeSacado": "Aluno teste",
"numeroDocumento": 8597757,
"valorAbatimentoConcedido": 0.0,
"valorDescontoConcedido": 0.0,
"valorDespesaCobranca": 0.0,
"valorDocumento": 1100.0,
"valorLiquido": 0.0,
"valorMoraMulta": 0.0,
"valorOutrasDespesas": 0.0,
"valorOutrosCreditos": 0.0,
"dataVencimento": "10/07/2021",
"nossoNumero": "58745876"
},
"response": "OK",
"statusProcessamento": "OK"
}
Financeiro: Baixa Título.
Método: Post
(base)/gestaoescolar/services/financeiro/rest/titulo
| Atributo | Descrição | Tipo | Mínimo | Máximo |
| nossoNumero | Número gerado pelo sistema interno que criou o título e que deve ser compartilhado com o Gestão Escolar para que cada interação funcione de forma correta | S | 1 | 50 |
| formaPagamento | Forma de pagamento para execução da baixa.
Valores válidos: DINHEIRO, CHEQUE, C_CREDITO,C_DEBITO, BOLETO, DEB_AUTOMATICO,TRANSFERENCIA, DOC,OUTRO_BAIXA_ADM,DEPOSITO,DUPLICADA, FIES, PREFEITURA,PROUNI, FOLHA_DE_PGTO, CHEQUE_PRE,PAGAMENTO_ONLINE, PERMUTA, PIX |
S | 3 | 20 |
| dataOcorrencia | Data de aconteceu a baixa do título, essa data será usada como referência pela baixa no gestão escolar e deve ser incluída, | S | 10 | 10 |
| valorPagamento | Valor do pagamento que deve ser executado no gestão escolar | N |
A diferença entre as duas APIs acima é o campo "valorPagamento", caso ele seja informado será obrigatório ter os dados de forma de pagamento e data da ocorrência. Caso não seja informado o valor do pagamento, será feita a tentativa de alterar o titulo com o valor do campo valorDocumento ou dataVencimento.
Respostas esperadas
Status 200: Status Processamento: OK
Status 417: Status Processamento: TITULO_JA_CANCELADO (Quando tenta cancelar um titulo que já foi cancelado)
Status 417: Status Processamento: TITULO_JA_BAIXADO (Quando tenta cancelar um titulo que já foi baixado)
Status 417: Status Processamento: TITULO_NAO_EXISTE (Quando o título informado não existe)
tatus 417: Status Processamento: ERRO: Erro genérico de negócio
Status 500: Status Processamento: ERRO
Exemplo
Requisição
Body:
{"nossoNumero":"58745876","formaPagamento":"BOLETO","valorPagamento":1100.0,"dataOcorrencia":"11/06/2021"}
Resposta
{
"acao": "Manutenção OK",
"dados": {
"formaPagamento": "BOLETO",
"nomeSacado": "Aluno teste",
"numeroDocumento": 8597757,
"valorAbatimentoConcedido": 0.0,
"valorDescontoConcedido": 0.0,
"valorDespesaCobranca": 0.0,
"valorDocumento": 1000.0,
"valorLiquido": 0.0,
"valorMoraMulta": 0.0,
"valorOutrasDespesas": 0.0,
"valorOutrosCreditos": 0.0,
"valorPagamento": 1100.0,
"dataOcorrencia": "11/06/2021",
"nossoNumero": "58745876"
},
"response": "OK",
"statusProcessamento": "OK"
}
Financeiro: Cancela Título.
Método: Delete
(base)/gestaoescolar/services/financeiro/rest/titulo
Executa o cancelamento do título
| Atributo | Descrição | Tipo | Mínimo | Máximo |
| nossoNumero | Número gerado pelo sistema interno que criou o título e que deve ser compartilhado com o Gestão Escolar para que cada interação funcione de forma correta | S | 1 | 50 |
Respostas esperadas
Status 200: Status Processamento: OK
Status 417: Status Processamento: TITULO_JA_CANCELADO (Quando tenta cancelar um titulo que já foi cancelado)
Status 417: Status Processamento: TITULO_JA_BAIXADO (Quando tenta cancelar um titulo que já foi baixado)
Status 417: Status Processamento: TITULO_NAO_EXISTE (Quando o título informado não existe)
tatus 417: Status Processamento: ERRO: Erro genérico de negócio
Status 500: Status Processamento: ERRO
Exemplo
Requisição
Param:
nossoNumero=[numero]
Resposta
{
"acao": "Manutenção OK",
"dados": {
"nomeSacado": "Aluno teste",
"numeroDocumento": 8597756,
"valorAbatimentoConcedido": 0.0,
"valorDescontoConcedido": 0.0,
"valorDespesaCobranca": 0.0,
"valorDocumento": 1000.0,
"valorLiquido": 0.0,
"valorMoraMulta": 0.0,
"valorOutrasDespesas": 0.0,
"valorOutrosCreditos": 0.0,
"nossoNumero": "58745875"
},
"response": "OK",
"statusProcessamento": "OK"
}
Financeiro: Consulta Títulos.
Método: GET
(base)/gestaoescolar/services/financeiro/rest/titulo
Executa a consulta determinados do título
| Atributo | Descrição | Tipo | Mínimo | Máximo |
| skumatricula | Identificador único da matrícula (padrão) EAD | S | 1 | |
| idmatricula | Identifcador interno da matricula | N | 11 | |
| cpf | CPF do aluno, irá trazer todos os títulos relacionados | N | 11 | |
| exibecancelados | Exibe ou não os títulos cancelados , padrão false, informe true para ligar o parâmetro | S |
Use o parâmetro skumatricula, idinternomatricula ou cpf, caso informe os três, será usado o skumatricula como
padrão e se localizar uma matrícula para o id informado irá retornar os títulos ligados a ela, usando o cpf
irá retornar os títulos localizados para o aluno para qualquer matrícula.
O parâmetro skumatricula é referene ao código da matrícula feito em um sistema externo EAD que está ligado ao gestão escolar, ao informar esse código
será retornada apenas as títulos referentes a essa matrícula. Se passar o idmatricula, é referente ao identificador interno do Gestão Escolar, utilize a API de consultas de matrículas para obter esse código para usar aqui e informado esse parâmetro será carregado os títulos referentes a essa matrícula.
No caso, o CPF do aluno, quando informado, vai pegar todos os títulos, de qualquer matrícula, que esteja associado ao CPF do aluno
Respostas esperadas
Status 200: Status Processamento: OK
Status 500: Status Processamento: ERRO
Exemplo
Requisição
Param:
cpf=[numero] ou skumatricula=[numero], exibecancelados=[texto]
Resposta
"acao": "Manutenção OK",
"dados": [
{
"tituloSituacaoRemote": "ATRASADO",
"dataVencimento": "30/07/2021",
"nomeSacado": "Luíza da Silva",
"numeroDocumento": 430114,
"valorDocumento": 1400.02
},
{
"tituloSituacaoRemote": "PENDENTE",
"dataVencimento": "30/08/2021",
"nomeSacado": "Luíza da Silva",
"numeroDocumento": 430092,
"valorDocumento": 1400.02
}
],
"response": "OK",
"statusProcessamento": "OK"
}