Liquidações

A rota GET /v3/liquidacoes (veja as Rotas da API) retorna todas as liquidações, tanto de parcelas originais quanto de parcelas de acordo. Este guia explica como separar os dois casos sem contar o mesmo dinheiro duas vezes.

Liquidação não vinculada a acordo

É o caso simples: o aluno pagou a parcela original diretamente (PIX, boleto), sem nenhuma negociação. Identifique pelo campo acordo.id: se ele for null, a liquidação não está vinculada a um acordo.

Recomendamos implementar esse caso primeiro: cobre a maior parte dos pagamentos.

1. Consulte GET /v3/liquidacoes periodicamente (no mínimo 1x/dia), filtrando por data_inicial_liquidacao (ex.: d-3) e data_final_liquidacao (d0).
2. Use apenas os registros com acordo.id = null.
3. Lance a baixa no sistema de gestão da IES.

Liquidação vinculada a acordo

Quando o aluno paga uma parcela do acordo, isso gera uma liquidação com categoria_parcela = "ACORDO", e pode gerar 1 ou mais liquidações "secundárias" com categoria_parcela = "ORIGINAL" nas parcelas originais que o acordo cobria (o pagamento é "rateado" entre elas).

Exemplo: um aluno tem duas mensalidades vencidas, id 123 (R$ 300) e id 456 (R$ 300), e faz um acordo (acd_999) parcelando a dívida em 3x de R$ 200. Ao pagar a 1ª parcela do acordo (R$ 200), a API retorna 3 registros:

As 3 estratégias possíveis

• Só considerar categoria_parcela = "ACORDO", ignorando as liquidações "ORIGINAL" que têm acordo.id preenchido. Funciona bem se sua IES também consome GET /v2/acordos e "espelha" os acordos no seu sistema. Só fique atento a ajustar manualmente se o acordo for quebrado.
• Só considerar categoria_parcela = "ORIGINAL", ignorando as "ACORDO". Mais simples, indicada para quem não espelha os acordos da Principia.
• Considerar as duas, replicando exatamente a lógica interna da Principia. Dá mais automação em casos de acordo quebrado, mas exige cuidado redobrado para não somar em duplicidade.

Caso especial: pagamento via cartão de crédito

Quando o aluno paga com cartão de crédito, a Principia cria um acordo internamente por motivo de sistema, mas isso não representa uma negociação real e pode ser ignorado na integração.

Nesse caso, uma parcela paga via cartão gera 2 registros de liquidação, ambos com forma_liquidacao = "LINK_PAGAMENTO":

• Um com categoria_parcela = "ORIGINAL" e parcela_original_id_externo preenchido: é este que você deve considerar.
• Outro com categoria_parcela = "ACORDO" e parcela_original_id_externo = null: ignore este.

Regra prática: ignore liquidações com categoria_parcela = "ACORDO" e forma_liquidacao = "LINK_PAGAMENTO"; trate como liquidação normal as com categoria_parcela = "ORIGINAL" e forma_liquidacao = "LINK_PAGAMENTO" (mesmo com acordo.id preenchido).