Fluxo de integração

O caminho completo do caso de uso principal, do envio de alunos à conciliação de liquidações.

Esta página descreve o fluxo ponta a ponta de uma integração típica, na mesma ordem recomendada pelo guia de integração da Principia. Ajuste conforme o caso de uso da sua instituição.

Visão geral do fluxo

Se quiser que o aluno chegue do portal da sua IES ao portal da Principia sem logar de novo, implemente o Login via SSO antes ou em paralelo ao restante da integração: é independente do fluxo de dados abaixo.

Envie os alunos

Inclua os alunos com POST /v1/aluno, sempre dentro do array alunos (mande vários de uma vez quando puder). Campos obrigatórios mínimos: cpf e nomeCompleto do aluno, mais os dados do responsavelFinanceiro. Se o aluno for seu próprio responsável financeiro, repita os dados dele nos dois lugares. Como é assíncrono, você recebe um id de lote para acompanhar.

Aluno com mais de uma matrícula (dois cursos simultâneos, por exemplo) deve ser enviado uma única vez, não duplique o cadastro por curso.

Testar sem escrever código

Teste POST /v1/aluno nas Rotas da API.

Envie as parcelas

Inclua as parcelas com POST /v1/parcela, dentro do array parcelas, referenciando o aluno pelo alunoCpf/alunoRa. Cadastre a parcela sempre com idParcela: é o identificador que você usa depois pra atualizar valor, cancelar ou dar baixa manual nessa mesma parcela (upsert: se o idParcela já existir, atualiza; se não existir, cria).

Bloqueie a emissão de boleto na sua IES

Depois que uma parcela é enviada para a Principia, o sistema da sua instituição não pode gerar ou manter um boleto próprio para ela, nem manual nem automático. Se já existia um boleto emitido, cancele-o. Sem esse bloqueio, o aluno é cobrado em duplicidade (Principia + IES): evite esse cenário.

Testar sem escrever código

Teste POST /v1/parcela nas Rotas da API.

Acompanhe o processamento

Use GET /v1/processamento/status/{lote} (ou as rotas v2) até o lote concluir. A resposta traz, por item, um array validacao com o motivo de cada falha. Reenvie apenas os itens que falharam, não o lote inteiro.

Testar sem escrever código

Teste GET /v1/processamento/status/{lote} nas Rotas da API.

Confira o que foi importado

Valide com GET /importacao/enviados/alunos e GET /importacao/enviados/parcelas que os dados chegaram como esperado.

Testar sem escrever código

Teste GET /importacao/enviados/alunos e GET /importacao/enviados/parcelas nas Rotas da API.

Atualize, cancele ou dê baixa manual em uma parcela

Os três casos usam o mesmo POST /v1/parcela, reenviando o idParcela já existente:

Atualizar valor/vencimento: reenvie a parcela com novo valorBoleto, dataVencimento ou descontosAdimplencia.
Cancelar (ex.: trancamento/cancelamento de matrícula): reenvie com situacaoBaixa: "CANCELADA".
Baixa manual como "pago na IES" (aluno pagou direto pra instituição, fora do boleto Principia): reenvie com situacaoBaixa: "LIQUIDADA".

Para cadastro de aluno, a mesma rota (POST /v1/aluno) faz patch parcial na atualização: só os campos que você enviar são alterados, os demais permanecem como estavam.

Gere links de pagamento (opcional)

Quando precisar cobrar, gere o link com POST /v1/parcela/link_pagamento, informando alunoCpf ou alunoRa, responsavelFinanceiroDocumento e o parcelaOriginalIdExterno (o idParcela enviado na criação).

Testar sem escrever código

Teste POST /v1/parcela/link_pagamento nas Rotas da API.

Concilie liquidações e acordos

Periodicamente (recomendado: pelo menos 1x/dia), consulte GET /v3/liquidacoes para saber o que foi pago e GET /v2/acordos para acompanhar acordos. Esses dois pontos têm pegadinha: veja Acordos e Liquidações antes de implementar, especialmente o caso de pagamento via cartão de crédito. Use os extratos para o fechamento financeiro.

Testar sem escrever código

Teste GET /v3/liquidacoes e GET /v2/acordos nas Rotas da API.

Boas práticas

Idempotência: use um idParcela estável (o mesmo identificador da parcela no seu sistema) para evitar duplicidade em reenvios: é ele que decide se a Principia cria uma parcela nova ou atualiza a existente.
Processamento assíncrono: nunca assuma que a inclusão foi concluída na resposta imediata, confirme pelo status do lote.
Reprocessamento: em caso de falha parcial, reenvie apenas os itens que falharam (identificados pelo array validacao da resposta de status).
Versões de rota: prefira sempre a versão mais recente disponível (ex.: v3/liquidacoes, v2/acordos). As versões antigas são mantidas por compatibilidade.

Dúvidas sobre uma rota específica?

Abra a página da rota nas Rotas da API para ver todos os campos, ou pergunte ao assistente de IA.

Nesta página