Integração de sistema de terceiros com estudamais
Este artigo tem como objetivo demonstrar como outros sistemas podem se integrar com o Estudamais. O processo de integração entre esses dois sistemas segue os modelos de requisição e resposta descritos abaixo.
A integração opera da seguinte maneira: sempre que o LMS enviar uma requisição para o sistema de terceiros, ele incluirá um parâmetro na URL chamado API, que indica o tipo de ação ou pergunta que está sendo feita para o sistema de terceiros. Portanto, é crucial ter o modelo de resposta implementado previamente.
O sistema de terceiro não precisa alimentar a estrutura do LMS. A própria aplicação vai entrar em contato com o sistema de terceiro e buscar as informações.
Abaixo é possível ver as principais chaves para integrar a pessoa, curso, turma, matrícula e realizar o login no LMS.
| Chave | Obrigatório | Descrição |
|---|---|---|
| ApiUnimMoodleCursos | Sim | Ação responsável por recuperar a lista de cursos que devem ser integrados. Evite trazer listas enormes de registros. Utilize alguma lógica de período. |
| lms.ApiPessoa | Sim | Ação responsável por recuperar as informações da pessoa no cadatro do terceiro. É essa ação que trás a pessoa para dentro do LMS ou vincula a pessoa ao curso EAD como professor, coordenador ou tutor. |
| ApiUnimMoodleCursosMatriculas | Sim | Ação responsável por recuperar todas as matriculas de uma pessoa. Nela também é possível visualizar informações importantes do curso e da turma. É nesse momento que a turma é criada no LMS e a pessoa é matriculada. |
| lms.ApiMatricula | Sim | Ação responsável por recuperar a quantidade de matrículas do aluno |
| lms.ApiFichaIndividual | Sim | Ação responsável por atualizar a situação da matrícula no LMS. O LMS executa essa chamada para o sistema de terceiro a cada 15min. |
| ApiLiberacaoCursoLms | Sim | Ação responsável por consultar se a pessoa tem alguma liberação financeira em alguma disciplina especifica. |
Importante: Mesmo que a chave não seja utilizada para os fins mencionados acima, é necessário implementá-la. No caso de não ser utilizada, é importante implementar um retorno vazio.
Requisitos
A partir de agora, vamos usar como exemplo a URL http://sistema.terceiro.com.br como sendo a URL de integração. Antes de iniciar, é importante ter a integração do lado do LMS configurada pela equipe de serviços. É por esse passo que eles vão pegar a URL de exemplo e cadastrar para que o LMS saiba por onde ele deve se comunicar.
Integração do curso
A integração de cursos sempre vai esperar como resposta um array de objetos no formato JSON. Cada registro é um curso diferente. Essa integração acontece sempre automaticamente pelo agendamento que acontece a cada 15m ou mais.
[GET] http://sistema.terceiro.com.br/exemplo.php?api=ApiUnimMoodleCursos
Exemplo de como a resposta DEVE ser
[
{
"cd_moodle_curso": "2",
"ds_descricao": "CURSO TESTE INTEGRAÇÃO - 07/05/2024",
"ds_sigla": "CTI",
"dt_revisao": "2024-05-06 17:50:59",
"sn_separar_turma": "1",
"sn_curso_modelo": null,
"cd_curso_modelo": null,
"nr_grau": "1",
"nr_serie": "1",
"ds_grau": "ENSFUND",
"ds_hash_md5": "79cdb28f5c1f94045e0b8403450ea53d",
"ds_metodo_importacao": "parcial",
"cd_avaliacao_tipo": "1",
"cd_coordenador": "248827",
"cd_tutor": "510287"
},
{
"... próximo curso"
}
]
Campos
Abaixo segue a descrição dos campos mais relevantes.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| cd_moodle_curso | integer | Sim | Código único para o curso | |
| ds_descricao | string | Sim | Nome do curso | |
| sn_separar_turma | smallint | Sim | 1 | Define como as turmas vão ser organizadas dentro do curso. 1 = Todas as turmas do curso vão para uma única turma do LMS chamada turma geral. 2 = Organizar os alunos cada um em sua respectiva turma de acordo com a matrícula dele. 3 = Organizar os alunos em turmas mensais. Serão criadas turmas de Janeiro a Dezembro e os alunos serão organizados de acordo com o mês da matrícula. |
| ds_hash_md5 | string | Sim | Chave responsável por definir a integridade do curso. Para informar ele, você deve gerar um hash que compõe os campos cd_moodle_curso, ds_descricao,ds_sigla,ds_metodo_importacao,cd_avaliacao_tipo,sn_separar_turma e grau. |
|
| nr_grau | integer | Sim | Define o grau do curso, ver a tabela de referência abaixo. | |
| ds_metodo_importacao | string | Sim | parcial | Define como as notas serão devolvidas para o sistema de terceiro. parcial = Cada atividade avaliativa será enviada individualmente. media = Somente a média será integrada. nao_importar = Não integra nenhuma atividade. |
| cd_avaliacao_tipo | smallint | Sim | 1 | Define um código especifico para o tipo de avaliação que deve ser retornado para o sistema de terceiro. |
Tabela de referência para os graus do curso
| Código | Grau | Chave |
|---|---|---|
| 1 | Educação Infantil | EI |
| 2 | 1º ano (Ensino Fundamental I) | EF1 |
| 3 | 2º ano (Ensino Fundamental I) | EF2 |
| 4 | 3º ano (Ensino Fundamental I) | EF3 |
| 5 | 4º ano (Ensino Fundamental I) | EF4 |
| 6 | 5º ano (Ensino Fundamental I) | EF5 |
| 7 | 6º ano (Ensino Fundamental II) | EF6 |
| 8 | 7º ano (Ensino Fundamental II) | EF7 |
| 9 | 8º ano (Ensino Fundamental II) | EF8 |
| 10 | 9º ano (Ensino Fundamental II) | EF9 |
| 11 | 1ª série do Ensino Médio | EM1 |
| 12 | 2ª série do Ensino Médio | EM2 |
| 13 | 3ª série do Ensino Médio | EM3 |
| 14 | 4º ano Ensino Médio | EM4 |
| 16 | Cursos Livres | CL |
| 18 | Olimpíada+ | OLI |
| 19 | Graduação | G |
| 20 | Pós Graduação | PG |
| 21 | Mestrado | M |
| 22 | Doutorado | D |
Integração da pessoa
Essa api é responsável por perguntar ao sistema de terceiro se a pessoa que está sendo requisitada existe. Se existir, faz a integração dela para o LMS.
A integração de pessoa é feito exclusivamente sob demanda no momento do login de cada usuário.
Parâmetros
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| ds_login | string | Sim | Usuário único | |
| ds_senha | string | Sim | Senha do usuário em formato texto ou hash encriptada |
Exemplo de como a resposta DEVE ser
{
"success": true,
"message": "",
"result": {
"cd_pessoa": "248827",
"nm_pessoa": "ULISSES TESTE",
"ds_cpf": "03455537440",
"ds_sexo": "M",
"cd_estado_civil": "5",
"dt_nascimento": "1981-02-28 00:00:00",
"ds_login": "ulisses",
"cd_pais": 1,
"nm_pai": "Luiz Teste",
"nm_mae": "Miriam Teste",
"ds_identidade": "12340000",
"ds_identidade_orgao_exp": "SESP",
"dt_identidade_expedicao": "2003-01-08 00:00:00",
"ds_cep": "88318200",
"ds_estado": "SC",
"ds_pais": "Brasil",
"cd_estado": "42",
"ds_cidade": "Blumenau",
"ds_bairro": "BRILHANTE I",
"ds_logradouro": "RUA MOISÉS GAMBA",
"ds_logradouro_nro": "134",
"ds_complemento": "",
"ds_senha": "3343197f6927b267bd765361341e9cb3",
"ds_pais_nascimento": "BRASIL",
"cd_pais_nascimento": "10",
"ds_estado_nascimento": "SC",
"cd_estado_nascimento": "42",
"ds_cidade_nascimento": "Brusque",
"cd_pessoa_antigo": null,
"arrContatos": [
{
"cd_pessoa": "248827",
"ds_contato": "47999249293",
"ds_tipo_original": "Telefone Celular"
},
{
"cd_pessoa": "248827",
"ds_contato": "ulisses@amaiseducacao.com.br",
"ds_tipo_original": "E-mail"
},
{
"cd_pessoa": "248827",
"ds_contato": "47 11111-6666",
"ds_tipo_original": "Telefone Comercial"
}
],
"arrGrupos": [
{
"cd_grupo": "2",
"ds_nome_grupo": "Estudantes",
"ds_papel": "ALUNO",
"cd_coligada": "1",
"nm_coligada": "Escola Teste - Unidade CENTRO"
},
{
"cd_grupo": "3",
"ds_nome_grupo": "Professores",
"ds_papel": "PROFESSOR",
"cd_coligada": "1",
"nm_coligada": "Escola Teste - Unidade CENTRO"
},
{
"cd_grupo": "4",
"ds_nome_grupo": "Coordenação",
"ds_papel": "COORDENADOR",
"cd_coligada": "1",
"nm_coligada": "Escola Teste - Unidade CENTRO"
}
]
}
}
Campos
Abaixo segue a descrição dos campos mais relevantes.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| cd_pessoa | integer | Sim | Código único da pessoa | |
| ds_sexo | char | Não | M | F = Feminino e M = Masculino. |
| cd_estado_civil | integer | Sim | Valores de referẽncia em estado civil da pessoa | |
| arrContatos.ds_tipo_original | string | Sim | Valores de referẽncia em tipos de contatos da pessoa | |
| arrGrupos.ds_papel | string | Sim | Valores de referẽncia em tipos de contatos da pessoa |
Tabela de referência para os grupos dos usuários
Na lista de grupos da pessoa, o campo ds_papel pode ser preenchido com os valores da coluna Papel abaixo.
| Papel | Perfil do LMS |
|---|---|
| ALUNO | ESTUDANTES |
| ADMIN | ADMINISTRADOR |
| PROFESSOR | PROFESSORES |
| COORDENADOR | COORDENACAO |
| ADMINISTRADOR | ADMINISTRADOR |
| TUTOR | TUTOR |
| TUTORIA | TUTOR |
Tabela de referência para o estado civil da pessoa
Na api de pessoa, o campo cd_estado_civil pode ser preenchido com os valores da coluna Código abaixo.
| Código | Descrição |
|---|---|
| 1 | Solteiro(a) |
| 2 | União civil estável |
| 3 | Casado(a) |
| 4 | Separado(a) Judicialmente |
| 5 | Divorciado(a) |
| 6 | Viúvo(a) |
Tabela de referência para os tipos de contatos da pessoa
Na api de pessoa, o campo ds_tipo_original pode ser preenchido com os valores da coluna Código abaixo.
| Código | Chave |
|---|---|
| Site | SITE |
| Telefone Celular | TELEFONE-CELULAR |
| Telefone comercial | TELEFONE-COMERCIAL |
| Telefone residencial | TELEFONE |
Integração da matrícula e turma
Essa api é responsável por perguntar ao sistema de terceiro quais são as matrículas da pessoa.
[GET] http://sistema.terceiro.com.br/exemplo.php?api=ApiUnimMoodleCursosMatriculas&cd_pessoa=1554172
Parâmetros
O LMS vai acrescentar na URL automaticamente o código da pessoa.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| cd_pessoa | integer | Sim | Código da pessoa do sistema de terceiro. Acrescentado automaticamente pelo LMS no momento do login |
Exemplo de como a resposta DEVE ser
[
{
"cd_pessoa" : "320854",
"cd_moodle_curso" : "2",
"cd_curso_disciplina" : "82",
"ds_descricao" : "CURSO TESTE INTEGRAÇÃO - 06/05/2024",
"ds_turma_descricao" : "9.5 - 9º ANO ENSINO FUNDAMENTAL VESPERTINO",
"cd_matricula_situacao" : "1",
"ds_curso_md5" : "f183246ea1e053cb85a8a753c5bb0e89",
"ds_turma_md5" : "8de28bda3b341ce78f044eb05cb02cde",
"ds_metodo_importacao" : "parcial",
"cd_avaliacao_tipo" : "1",
"sn_separar_turma" : "1",
},
{
"... próxima matrícula"
}
]
Campos
Abaixo segue a descrição dos campos.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| cd_pessoa | integer | Sim | Código da pessoa | |
| cd_moodle_curso | integer | Sim | Código do curso que foi integrado | |
| cd_curso_disciplina | integer | Sim | Código da disciplina que foi vinculada no curso EAD | |
| ds_descricao | string | Sim | Nome do curso para controle interno. Não é o nome que aparece no LMS. em alguns casos, é usado para agrupamento das disciplinas EAD. | |
| ds_turma_descricao | string | Sim | Nome da turma | |
| cd_matricula_situacao | smallint | Sim | 9 | Código que define a situação da matrícula |
| ds_curso_md5 | string | Sim | Define a integridade das informações do curso. Se alterar o hash ele atualiza o título do curso. | |
| ds_turma_md5 | string | Sim | Define a integridade das informações da turma. Se alterar o hash ele atualiza o título da turma. | |
| ds_metodo_importacao | smallint | Sim | parcial | Define o método de importação que foi selecionado na integração do curso. parcial, media ou nao_importar. |
| cd_avaliacao_tipo | smallint | Sim | 1 | Define o código do tipo de avaliação que deve voltar para o sistema de terceiro. |
| sn_separar_turma | smallint | Sim | null | Define o tipo de organização das turmas. Mesmo valor escolhido na integração do curso. |
Tabela de referência para a situação da matrícula
| Códigos | Situação |
|---|---|
| -8,3,4,5,6,7,8 | Cancelada |
| 14,13,12,11,0 | Concluído |
| 2,18,15,1 | Cursando |
| 9 | Reprovado |
| 10,100 | Reservado |
Total de matrículas da pessoa
[GET] http://sistema.terceiro.com.br/exemplo.php?api=lms.ApiMatricula&cd_pessoa=219477
Parâmetros
O LMS vai acrescentar na URL automaticamente o código da pessoa.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| cd_pessoa | integer | Sim | Código da pessoa do sistema de terceiro. Acrescentado automaticamente pelo LMS no momento do login |
Exemplo de como a resposta DEVE ser
[
{
"nr_matriculas": "1"
}
]
Integração da ficha individual
Parâmetros
O LMS vai acrescentar na URL automaticamente a data da última consulta da fichaindividual.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| dt_base | date | Sim | Data da última consulta para otimizar a resposta. |
Exemplo de como a resposta DEVE ser
A implementação do retorno preenchido não é obrigatória, porém a implementação da API sim. Abaixo, apresentamos exemplos tanto preenchidos quanto vazios.
Preenchido:
{
"success": true,
"message": "",
"result": {
"fichasindividuais": [
{
"cd_pessoa": "320854",
"nr_anosemestre": "20241",
"cd_curso": "FUNDAMENTAL II",
"cd_turma_matricula": "9.5",
"cd_disciplina": "204",
"nr_situacao": "3",
"dt_base": "2024-05-06 17:50:11",
"id_disciplina": "297",
"cd_moodle_curso": "2"
}
],
"ds_chave": "dev"
}
}
Vazio:
{
"success": true,
"message": "",
"result": {
"fichasindividuais": [],
"ds_chave": "dev"
}
}
Campos
Abaixo segue a descrição dos campos mais relevantes.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| ds_chave | string | Sim | Chave de acesso ao cliente informada pela equipe de serviços |
Integração da liberação financeira do aluno em uma disciplina
Parâmetros
O LMS vai acrescentar na URL automaticamente a data da última consulta da fichaindividual.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| cd_pessoa | integer | Sim | Código da pessoa preenchido automaticamente pelo LMS | |
| ds_chave | string | Sim | Chave fixa que é passada do lms para o sistema de terceiro |
Exemplo de como a resposta DEVE ser
A implementação do retorno preenchido não é obrigatória, porém a implementação da API sim. Abaixo, apresentamos exemplos tanto preenchidos quanto vazios.
Preenchido:
[
{
"cd_liberacao_curso_lms" : "1",
"cd_pessoa" : "320854",
"cd_turma" : "9.5",
"id_disciplina" : "295",
"cd_usuario" : "1",
"dt_liberacao" : "2024-05-07 16:18:00",
"sn_ativo" : "1",
"cd_curso" : "FUNDAMENTAL II",
"cd_moodle_curso" : "2"
}
]
Vazio:
[
{}
]
Campos
Abaixo segue a descrição dos campos mais relevantes.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| ds_chave | string | Sim | Chave de acesso ao cliente informada pela equipe de serviços |
Como logar no LMS
[POST] -> https://lms.unimestre.com/api/auth
Parâmetros
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| user | string | Sim | Usuário | |
| password | string | Sim | Senha | |
| portal | boolean | Não | false | Define se o menu superior do LMS deve ser exibido. Normalmente é definido como true quando o LMS vai ser exibido embedado. |
Parâmetros do header
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Api-Token | string | Sim | Chave que será informada ao cliente após a equipe de serviço ter configurado a integração. |
| Api-Cliente | string | Sim | Código do cliente que será informado ao cliente após a equipe de serviço ter configurado a integração. |
Exemplo de requisição
curl --location 'https://lms.unimestre.com/api/auth' \
--header 'Content-Type: application/json' \
--header 'Api-Token: d8dce264b30dbce346ed3754435a652x' \
--header 'Api-Cliente: uc' \
--data '{
"user": "amaiseducacao",
"password": "unimestre",
"portal" : false
}'
Exemplo de como a resposta DEVE ser
{
"success":true,
"message":"Pessoa encontrada.",
"url":"http://lms.unimestre.com/dev/valida-ticket/NDAzMjQwYTRiY2Nmo="
}
O campo URL é para onde o usuário deve ser redirecionado.
Resultado final
Lista de cursos
Home do aluno
Sala de aula
Baixar exemplo em PHP
Abaixo é possível ver um exemplo de implementação de todas as APIs descritas acima.
