Gestão Escolar - API de integração - Webhook
Introdução
Este manual orienta como configurar webhooks no Ultramax Gestão Escolar para uma outra aplicação receber eventos do Ultramax.
Atualmente os eventos disponíveis são:
- Cadastro de alunos (tipos de eventos: INCLUSAO, ALTERACAO, EXCLUSAO)
- Matrículas (tipos de eventos: INCLUSAO, ALTERACAO, EXCLUSAO)
- Boletos (tipos de eventos: INCLUSAO, ALTERACAO, EXCLUSAO, LIQUIDACAO, ESTORNO)
- NFS-e (tipos de eventos: INCLUSAO, ALTERACAO, EXCLUSAO)
Regras para envio e reenvio das mensagens
Imediatamente após a inclusão ou alteração de um dos cadastros suportados, será enviado um webhook.
As mensagens são enviadas em ordem em uma fila FIFO.
Você pode configurar o número máximo de tentativas, máximo de 3.
Caso uma mensagem não seja enviada em até 24 horas, ela será descartada.
O histórico de mensagens enviadas fica disponível 3 meses. Após esse período não estarão mais disponíveis para consulta ou reenvio.
Como configurar
Acesse o menu Tabelas -> Webhook - Config. de webhook's:
Inclua im webhook como este do exemplo abaixo:
No campo URL preencha com a URL da sua aplicação.
Sua aplicação precisa estar preparada para receber um POST.
Como ver as mensagens enviadas e reenviar
O histórico de mensagens enviadas fica disponível 3 meses. Após esse período não estarão mais disponíveis para consulta ou reenvio.
Para ver as mensagens enviadas acesse o menu Tabelas -> Webhooks - Histórico de envios
Caso ocorra falha no envio de alguma mensagem irá ficar disponível o botão de reenviar.
Quando o status está em branco é porque ainda não esgotou todas as tentativas de envio.
Quanto o status tiver como FALHA as tentativas já se esgotaram e não será reenviado automaticamente. Você pode usar o botão de reenviar.
Exemplos de mensagens enviadas
Aluno
Possíveis tipos de contato:
| Id | Contato |
|---|---|
| 1 | Tel.Residencial |
| 5 | Celular |
| 10 | Tel.Trabalho |
| 15 | |
| 20 | Fax |
| 25 | Site |
| 50 | Push mobile |
| 999 | Outro |
Possíveis tipos:
| Tipo | Descrição |
|---|---|
| F | Pessoa física |
| J | Pssoa jurídica |
{
"evento": "ALTERACAO",
"data": {
"id": 1796,
"pessoa": {
"contatos": [
{
"tipoContatoDescricao": "Celular",
"tipoContatoId": 5,
"valor": "(11) 91234-1234"
},
{
"tipoContatoDescricao": "E-Mail",
"tipoContatoId": 15,
"valor": "teste@teste.com"
}
],
"cpf_cnpj": "999.913.690-13",
"id": 14188,
"nome": "Luisa",
"tipo": "F",
"inscricaoEstadual": null,
"endereco": {
"bairro": "Centro",
"cep": "13200-000",
"cidade": "Jundiaí",
"complemento": "apt 72",
"estado": "SP",
"logradouro": "Rua teste",
"numero": "123"
}
},
"responsavelFinanceiro": {
"contatos": [
{
"tipoContatoDescricao": "Celular",
"tipoContatoId": 5,
"valor": "(11) 91234-1234"
},
{
"tipoContatoDescricao": "E-Mail",
"tipoContatoId": 15,
"valor": "teste@teste.com"
}
],
"cpf_cnpj": "999.913.690-13",
"id": 14188,
"nome": "Luisa",
"tipo": "F",
"inscricaoEstadual": null,
"endereco": {
"bairro": "Centro",
"cep": "13200-000",
"cidade": "Jundiaí",
"complemento": "apt 72",
"estado": "SP",
"logradouro": "Rua teste",
"numero": "123"
}
},
"ra": "U1"
},
"tipo": "ALUNO"
}
Matrícula
Possíveis status de matrícula:
| Stauts | Descrição |
|---|---|
| ATI | Ativa |
| C | Cancelada pelo aluno |
| CA | Cancelado outro motivo |
| CAN | Cancelada erro operacional |
| CON | Concluida |
| DES | Desistencia/Evasao |
| JUB | Jubilado |
| MAT | Matriculado |
| PRE | Pre-Matricula |
| REM | Transf. interno |
| T | Transferido |
| TRA | Trancada |
{
"evento": "ALTERACAO",
"data": {
"aluno": {
"id": 1796,
"pessoa": {
"cpf_cnpj": "999.913.690-13",
"id": 14188,
"nome": "Luisa",
"tipo": "F",
"inscricaoEstadual": null
},
"ra": "U1"
},
"cursoCodigo": "U1",
"cursoId": 16,
"cursoNome": "Ultramax",
"dataMatricula": "2021-06-30",
"id": 27652,
"periodoLetivoDescricao": "2025",
"periodoLetivoId": 27,
"serieId": 787,
"serieNome": "Ultramax 1",
"status": "ATI",
"unidadeEnsinoDescricao": "Teste",
"unidadeEnsinoId": 2
},
"tipo": "MATRICULA"
}
Boleto/Título
Possíveis ids de formas de pagamento:
| ID | Descrição |
|---|---|
| 1 | Dinheiro |
| 2 | Cheque |
| 3 | Cartão de Crédito |
| 4 | Cartão de Débito |
| 5 | Boleto |
| 6 | Débito Automático |
| 7 | Transferência |
| 8 | DOC |
| 9 | Outro / Baixa Adm |
| 10 | Depósito |
| 11 | Duplicada |
| 12 | FIES |
| 13 | Prefeitura |
| 14 | Prouni |
| 15 | Folha de Pagamento |
| 16 | Cheque Pré |
| 17 | Pagamento Online |
| 18 | Permuta |
| 19 | PIX |
| 20 | Vale |
| 21 | Cashback |
Tipos de espécie:
| Código | Descrição |
|---|---|
| DM | Duplicata mercantil |
| DS | Duplicata de serviço |
| ME | Mensalidade escolar |
{
"evento": "LIQUIDACAO",
"data": {
"contaCorrente": {
"agencia": "4201",
"numeroConta": "6936679",
"bancoCodigo": "033",
"descricao": "Santander com Registro",
"codigoExterno": null
},
"contasReceber": [
{
"contaContabilDescricao": "Mercado (compras em geral)",
"contaContabilCodigo": "002.043",
"contaContabilCodigoExterno": null,
"contaContabilId": 299,
"dataVencimento": "2025-02-15",
"dataFaturamento": "2025-02-15",
"dataEmissao": "2025-02-15",
"dataDesconto": "2025-02-15",
"dataDesconto2": null,
"dataDesconto3": null,
"id": 611936,
"numeroDocumento": 592664,
"valorDocumento": 2693,
"valorComDesconto": 2423.71,
"valorComDesconto2": 0,
"valorComDesconto3": 0
}
],
"dataEmissao": "2025-02-15",
"dataVencimento": "2025-02-15",
"dataFaturamento": "2025-02-15",
"dataDesconto": "2025-02-15",
"dataDesconto2": null,
"dataDesconto3": null,
"id": 432179,
"matricula": {
"aluno": {
"id": 1258,
"pessoa": {
"cpf_cnpj": null,
"id": 7519,
"nome": "Ana"
},
"ra": "1291"
},
"cursoCodigo": "MED",
"cursoId": 5,
"cursoNome": "Ensino Médio",
"dataMatricula": "2024-09-23",
"id": 26843,
"periodoLetivoDescricao": "2025",
"periodoLetivoId": 27,
"serieId": 754,
"serieNome": "1ª série",
"status": "ATI",
"unidadeEnsinoDescricao": "Teste",
"unidadeEnsinoId": 2
},
"numeroDocumento": 9366334,
"observacao": "",
"especie": "DS",
"instrucaoCobranca": null,
"descricaoNotaFiscal": null,
"pagador": {
"cpf_cnpj": "666.444.328-06",
"id": 7521,
"nome": "Renata"
},
"pagamento": {
"dataPagamento": "2025-02-26",
"parcelas": [
{
"bandeira": null,
"data": "2025-02-26",
"dataDisponibilidade": "2025-02-27",
"formaPagamentoDescricao": "Dinheiro",
"formaPagamentoId": 1,
"porcentagemTaxaAdministracao": null,
"valor": 56.73,
"valorCreditado": 56.73,
"valorDespesaCobranca": null
},
{
"bandeira": null,
"data": "2025-02-26",
"dataDisponibilidade": "2025-02-26",
"formaPagamentoDescricao": "PIX",
"formaPagamentoId": 19,
"porcentagemTaxaAdministracao": null,
"valor": 2700,
"valorCreditado": 2700,
"valorDespesaCobranca": null
}
],
"valorCobrado": 2756.73,
"valorMulta": 63.73,
"valorCobradoAdicional": 63.73,
"valorDescontoProgramado": 0,
"valorDescontoExtra": 0,
"totalDesconto": 0,
"totalAcrescimo": 333.02
},
"valorDocumento": 2693,
"valorComDesconto": 2423.71,
"valorComDesconto2": 0,
"valorComDesconto3": 0
},
"tipo": "BOLETO"
}
NFS-e:
{
"data": {
"dataCompetencia": "2025-01-28",
"dataEmissao": "2025-01-28",
"dataEmissaoRPS": "2025-01-28",
"dataHoraCancelado": null,
"id": 6,
"identificacaoNFSe": {
"codigoVerificacao": "XXXXXXXX",
"numero": 15347
},
"identificacaoRPS": {
"numeroRPS": 4,
"serieRPS": "1",
"tipoRPS": 1
},
"prestadorCNPJ": "12.999.999/0001-99",
"servico": {
"aliquota": 2.0,
"baseCalculo": 86.62,
"codigoCnae": "",
"codigoTributacao": "801.01/97",
"discriminacao": "Mensalidade Escolar (R$ 86,62) - Pedro RM 43333 - 5º Ano A - Referente a 01/2025",
"issRetido": false,
"itemListaServico": "801",
"valorDeducoes": 0.0,
"valorLiquido": 86.62,
"valorServicos": 86.62
},
"tituloId": 3461,
"tituloNumeroDocumento": 1076,
"tomador": {
"cpf_cnpj": "999.999.169-99",
"id": 4992,
"nome": "Bruna"
},
"urlVisualizacao": null
},
"evento": "INCLUSAO",
"tipo": "NFSE"
}