🔐 Autenticação JWT

A API utiliza autenticação baseada em JWT (JSON Web Token). Antes de consumir os endpoints protegidos, o integrador deve solicitar um token de acesso.

Gerar Token de Acesso

Request

Copiar



{
    "username": "usuario_api",
    "password": "senha"
}

Resposta

Copiar




{
    "refresh": "token_refresh",
    "access": "token_access",

    "integrador": {
        "nome": "Integração FACMA",
        "ativo": true
    }
}

Utilização do Token

Todas as requisições protegidas devem enviar o token no Header HTTP:

Authorization: Bearer TOKEN_ACCESS

Renovar Token

Copiar




{
    "refresh":"token_refresh"
}

Integração Malta

Endpoint destinado à integração com o CRM iCode no modelo Portal do Aluno, utilizado para sincronização de matrículas acadêmicas.

Endpoint

Parâmetros

Exemplo

GET /api/integracao/malta/matriculas/?periodoletivo=2026.2&enviado=false&page=0&size=200

Resposta

{
    "content": [
        {
            "Unidade": 1,
            "Matricula": "202600123",
            "NomeAluno": "Maria Aparecida de Souza",
            "Cpf": "12345678909",
            "DataNascimento": "1998-04-12",
            "Email": "[email protected]",
            "Celular": "44999999999",
            "Curso": "DIR",
            "CursoNome": "Direito",
            "Serie": 3,
            "SerieNome": "3º Período",
            "Ano": 2026,
            "PeriodoLetivo": 1,
            "NivelEnsino": 5,
            "NivelEnsinoDescricao": "Graduação",
            "Polo": 10,
            "PoloNome": "Polo Centro",
            "IDMoodle": "48217",
            "DataMatricula": "2026-01-20",
            "SitFinal": 0,
            "SitFinalDescricao": "ATIVA",
            "SitEscolar": "MT",
            "SitEscolarDescricao": "MATRICULADO",
            "TipoMatricula": "N",
            "TipoMatriculaDescricao": "Novato",
            "Endereco": "Rua das Flores",
            "Numero": "123",
            "Complemento": "Apto 4",
            "Bairro": "Centro",
            "CEP": "64000000",
            "Municipio": 2211001,
            "MunicipioNome": "Teresina",
            "UF": "PI",
            "Campanha": "VEST2026",
            "CampanhaDescricao": "Vestibular 2026",
            "TipoIngresso": "V",
            "TipoIngressoDescricao": "Vestibular",
            "Operacao": "I"
        }
    ],
    "last": true,
    "totalElements": 1,
    "size": 200,
    "number": 0
}

Observações

• Autenticação realizada via JWT.
• Os campos seguem o layout esperado pelo CRM para sincronização de matrículas.
• O endpoint apenas consulta informações, não realiza alterações no RM.

📚 Matrícula Acadêmica

Endpoint responsável pelo processo completo de integração acadêmica com o TOTVS RM. O consumidor envia todas as informações necessárias para criação do aluno, cliente/fornecedor, habilitação, matrícula acadêmica e contrato em uma única requisição.

Fluxo interno executado pela API

1 - Validação dos dados recebidos

        ↓

2 - Cadastro Cliente / Fornecedor

        ↓

3 - Cadastro do Aluno

        ↓

4 - Criação da Habilitação

        ↓

5 - Execução da Matrícula Acadêmica

        ↓

6 - Atualização do Contrato

        ↓

7 - Retorno consolidado do processo

Payload

{
    "nome":"joão Miguel Alves de Sousa",
    "sobrenome":"Miguel Alves de Sousa",

    "cpf":"123.456.789-00",

    "data_nascimento":"2000-01-01",

    "email":"[email protected]",

    "email_pessoal":"",

    "telefone":"86999999999",

    "telefone2":"",

    "cep":"64000000",

    "endereco":"Rua Principal",

    "numero":"100",

    "bairro":"Centro",

    "cidade":"Teresina",

    "estado":"PI",

    "nacionalidade":10,

    "naturalidade":"Teresina",

    "estado_natal":"PI",


    "periodo_letivo":"2026.2",

    "cod_status":1,

    "cod_tipo_matricula":1,

    "cod_curso":"01",

    "cod_turno":1,

    "cod_plano_pgto":"BOLSA100%",

    "cod_bolsa":"36"
}

Campos da requisição

Resposta

{
    "cliente_fornecedor": true,

    "aluno": {
        "RA":"2610020906"
    },

    "matricula": {
        "status":"sucesso"
    },

    "contrato": {
        "CODCONTRATO":"85656"
    }
}

🔎 Consultas SQL

A API possui um módulo de Consultas SQL responsável por consultar informações diretamente no TOTVS RM antes da execução de determinados processos. Essas consultas são reutilizadas internamente pelos módulos de cadastro e matrícula, eliminando a necessidade de o integrador conhecer códigos internos do RM.

Endpoint Genérico

Executa uma Consulta SQL previamente cadastrada no TOTVS RM. O parâmetro codigo_consulta identifica a consulta que será executada. O código do sistema (G) é utilizado automaticamente pela API e não precisa ser informado pelo consumidor.

Parâmetros

Exemplo

Resposta

[
    {
        "CODMUNICIPIO": "11001",
        "NOMEMUNICIPIO": "Teresina",
        "CODETDMUNICIPIO": "PI"
    }
]

            

Níveis de Ensino

Retorna a lista de níveis de ensino cadastrados no TOTVS RM. Essa consulta é utilizada para que o sistema integrador obtenha os códigos disponíveis antes de realizar operações que dependam do nível de ensino.

Esta consulta não recebe parâmetros.

Exemplo

GET /api/consultasql/niveis-ensino/

Resposta

{
    "niveis_ensino": [
        {
            "CODCURSO": "01",
            "NOME": "PEDAGOGIA",
            "NIVEL_ENSINO": "GRADUAÇÃO",
            "CODTURNO": 1,
            "TURNO": "EAD"
        },
        {
            "CODCURSO": "02",
            "NOME": "TEOLOGIA",
            "NIVEL_ENSINO": "GRADUAÇÃO",
            "CODTURNO": 1,
            "TURNO": "EAD"
        },
        {
            "CODCURSO": "01",
            "NOME": "PEDAGOGIA",
            "NIVEL_ENSINO": "GRADUAÇÃO",
            "CODTURNO": 13,
            "TURNO": "INTEGRAL"
        }

        // Demais cursos...
    ]
}

Campos Retornados

Planos de Bolsas

Retorna os planos de bolsas disponíveis no TOTVS RM de acordo com o período letivo e o tipo de curso informado. Esta consulta deve ser utilizada pelo sistema integrador antes da realização da matrícula para identificar os códigos de bolsas válidos.

Parâmetros

Exemplo

GET /api/consultasql/planos-bolsas/
?periodo_letivo=2026.2
&cod_tipo_curso=1

Resposta

{
    "PlanosBolsas": [
        {
            "CODBOLSA": "36",
            "DESCRICAO": "BOLSA 100%"
        },
        {
            "CODBOLSA": "20",
            "DESCRICAO": "BOLSA 50%"
        }
    ]
}

Campos Retornados

Grade

Retorna as Grades curriculares correspondente aos parâmetros informados pelo integrador. Esta consulta é utilizada para identificar corretamente as grades disponíveis no TOTVS RM antes da criação da matrícula.

Parâmetros

Exemplo

GET /api/consultasql/grades/
?cod_tipo_curso=1
&cod_curso=01
&cod_turno=1

Resposta

{
    "Grades": {
        "cod_grade": "2024.1"
    }
}

Campos Retornados

Consultas Disponíveis

Fluxo de utilização

            Sistema envia "cidade": "Teresina"

                    ↓

            Consulta SQL (integracao.1)

                    ↓

            TOTVS RM retorna:

            CODMUNICIPIO
            NOMEMUNICIPIO
            CODETDMUNICIPIO

                    ↓

            API complementa automaticamente o payload

                    ↓

            Mapper gera o objeto esperado pelo TOTVS RM

                

🔄 Fluxo da Integração

1 - Sistema consumidor solicita JWT

        ↓

2 - API valida integrador

        ↓

3 - Consumidor envia payload único

        ↓

4 - Serializer valida matrícula completa

        ↓

5 - API executa:

    Cliente/Fornecedor

        ↓

    Aluno

        ↓

    Habilitação

        ↓

    Matrícula

        ↓

    Contrato


        ↓

6 - Retorno consolidado enviado ao consumidor

📌 Estrutura dos Endpoints

https://integracao.facma.edu.br

/api

├── token/
├── token/refresh/
│
├── integracao/
│
│   └── matricula-completa/
│
│
└── consultasql/
    └── niveis-ensino/

⚠️ Tratamento de Erros

400 - Bad Request

Dados enviados inválidos ou campos obrigatórios ausentes.

{
    "cpf":[
        "Este campo é obrigatório."
    ]
}

401 - Unauthorized

Token ausente, expirado ou inválido.

{
    "detail":
    "Authentication credentials were not provided."
}

403 - Forbidden

Integrador desativado ou sem permissão.

{
    "detail":
    "Integrador inativo ou não encontrado."
}

500 - Internal Server Error

Erro interno durante comunicação com TOTVS RM.

💻 Exemplos de Consumo

cURL - Gerar Token

Copiar





curl --location \
https://integracao.facma.edu.br/api/token/ \
--header "Content-Type: application/json" \
--data '
{
 "username":"usuario",
 "password":"senha"
}
'

JavaScript Fetch

Copiar






async function cadastrarAluno(){


const response =
await fetch(

"https://integracao.facma.edu.br/api/educacional/aluno/",

{

method:"POST",

headers:{

"Content-Type":"application/json",

"Authorization":
"Bearer TOKEN"

},


body:JSON.stringify({

nome:"João Silva",

cpf:"00000000000",

email:"[email protected]"

})


});


return await response.json();


}

Python Requests

Copiar






import requests



url = "

https://integracao.facma.edu.br/api/educacional/aluno/

"



headers = {

"Authorization":
"Bearer TOKEN",

"Content-Type":
"application/json"

}



payload = {

"nome":
"João Silva",

"cpf":
"00000000000",

"email":
"[email protected]"

}



response = requests.post(

url,

json=payload,

headers=headers

)

cURL - Consultar Níveis de Ensino

Copiar



curl --location \
https://integracao.facma.edu.br/api/consultasql/niveis-ensino/ \
--header "Authorization: Bearer TOKEN_ACCESS"

🔒 Segurança