1. Baixas
AgRisk
  • AgRisk
    • Documentação
      • AgRisk
    • API - AgRisk
      • Login
        • Atualizar token
        • Autenticar usuário
      • Consultas
        • Solicitar consulta
        • Listar consultas
        • Listar consultas da empresa
      • Listagem de Produtos
        • Listar produtos
      • Clientes
        • Listar clientes
        • Criar cliente
        • Listar contadores de clientes
        • Deletar cliente
        • Listar contadores de clientes no grupo
      • Dados Cadastrais
        • Buscar dados cadastrais
      • Grupos
        • Listar grupos
        • Criar grupo
        • Listar clientes em grupo
        • Criar cliente em grupo
        • Atualizar nome do grupo
        • Deletar grupo
        • Inserir cliente em grupo
        • Remover cliente de grupo
      • Análise de Matrícula
        • Listar análises de matrículas
        • Criar análise de matrícula
        • Buscar análise de matrícula
        • Deletar análise de matrícula
      • Contatos
        • Listar contatos
      • BNDES
        • Listar BNDES
      • Boa Vista
        • Listar Boa Vista
      • Compliance
        • Listar compliance
      • CPRs
        • Listar CPRs
        • Buscar CPR
      • Grupo econômico
        • familiar
          • Listar grupo econômico
          • Listar grupo familiar
      • Imposto de Renda
        • Criar ativo financeiro
        • Listar ativos financeiros
        • Criar dívida
        • Importar dívidas
        • Listar dívidas
        • Atualizar dívida
        • Deletar dívida
        • Criar ativo móvel
        • Listar ativos móveis
        • Atualizar ativo móvel
        • Deletar ativo móvel
        • Criar imóvel urbano
        • Listar imóveis urbanos
        • Atualizar imóvel urbano
        • Deletar imóvel urbano
      • Judicial
        • Listar processos judiciais
        • Buscar processo judicial
        • Solicitar análise por IA
      • Protestos
        • Listar protestos
      • Imóveis Rurais - Simples
        • Criar imóvel rural
        • Listar imóveis rurais
        • Buscar imóvel rural
      • Endividamento
        • Listar SCR (endividamento)
      • Imóveis Rurais - CAR
        • Listar CAR (Cadastro Ambiental Rural)
        • Buscar CAR
        • Deletar CAR
        • Criar CAR
        • Download certidão CAR
      • QUOD
        • Buscar Quod
      • Restritivo Nacional
        • Buscar Restritivo Nacional
      • Veicular
        • Buscar Patrimônio Veicular
      • Sintegra
        • Listar Sintegras
    • APIs
    • Raiz
    • Esquemas
      • API Requests
        • ClientResponse
  • AgFlow
    • 🇧🇷 Português
      • Aprovação
        • Aprovação — Visão Geral
        • Consultar configuração de aprovação
        • Criar configuração de aprovação
        • Atualizar configuração de aprovação
        • Adicionar regra de aprovação
        • Atualizar regra de aprovação
        • Remover configuração de aprovação
        • Consultar aprovação do card
        • Registrar voto de aprovação
        • Atualizar voto de aprovação
      • Fluxo
        • Fluxo — Visão Geral
        • Verificar disponibilidade
        • Criar fluxo
        • Listar fluxos
        • Obter fluxo
        • Atualizar fluxo
        • Remover fluxo
        • Adicionar usuário ao fluxo
        • Remover usuário do fluxo
        • Listar caminhos de campos dinâmicos
      • Consulta a Bureau
        • Consulta a Bureau — Visão Geral
        • Obter configuração de consulta a bureau
        • Criar configuração de consulta a bureau
        • Atualizar configuração de consulta a bureau
      • Campos
        • Campos — Visão Geral
        • Listar campos da fase
        • Atualizar campos da fase
        • Atualizar regras de campos da fase
      • Conversa
        • Conversa — Visão Geral
        • Obter configuração de conversa
        • Criar configuração de conversa
        • Remover configuração de conversa
      • Motores
        • Motores — Visão Geral
        • Consultar resultado do motor de decisão do card
        • Executar motor de decisão no card
        • Consultar inputs do motor de crédito para o card
        • Consultar resultado do motor de crédito do card
        • Executar motor de crédito no card
        • Consultar configuração do motor de decisão
        • Criar configuração do motor de decisão
        • Atualizar configuração do motor de decisão
        • Remover configuração do motor de decisão
        • Consultar detalhe da configuração do motor de crédito
        • Criar configuração do motor de crédito
        • Listar configurações do motor de crédito do flow
        • Listar políticas de crédito aplicáveis a um card
        • Atualizar configuração do motor de crédito
        • Remover configuração do motor de crédito
      • Parecer
        • Parecer — Visão Geral
        • Consultar configuração do parecer técnico
        • Criar configuração do parecer técnico
        • Atualizar configuração do parecer técnico
        • Consultar parecer registrado no card
        • Registrar parecer no card
        • Atualizar parecer no card
      • Formulário Inicial
        • Formulário Inicial — Visão Geral
        • Criar formulário inicial
        • Definir regras condicionais do formulário
        • Atualizar metadados do formulário
        • Consultar formulário inicial
        • Consultar formulário público
        • Atualizar campos do formulário
        • Remover formulário inicial
      • Filtros
        • Filtros — Visão Geral
        • Listar filtros salvos
        • Criar filtro salvo
        • Atualizar filtro salvo
        • Buscar cards do flow
        • Busca global de cards
      • AgRisk
        • AgRisk — Visão Geral
        • Listar produtos de consulta AgRisk
      • Gatilhos
        • Gatilhos — Visão Geral
        • Listar gatilhos do flow
        • Criar gatilho
        • Atualizar gatilho
        • Remover gatilho
        • Listar gatilhos da fase
      • Autenticação
        • Autenticação — Visão Geral
        • Autenticar usuário
      • Mensageria
        • Mensageria — Visão Geral
        • Configurar telefone
        • Consultar configuração de mensageria
        • Criar configuração de mensageria
        • Atualizar configuração de mensageria
        • Criar regras de mensageria
        • Atualizar regra de mensageria
        • Remover configuração de mensageria
      • Empresas e Papéis
        • Empresas e Papéis — Visão Geral
        • Listar usuários da empresa
        • Listar papéis da empresa
        • Atualizar papel
        • Listar catálogo de permissões
        • Criar papel
        • Gerar URL de upload do logotipo
        • Gerar URL de download do logotipo
        • Atribuir papéis a um usuário
      • Documentos
        • Documentos — Visão Geral
        • Criar configuração de geração automática de documento
        • Remover configuração de geração automática de documento
        • Consultar configuração de geração automática de documento
        • Atualizar configuração de geração automática de documento
        • Consultar campos para geração do documento
        • Gerar documento a partir de template
        • Consultar template por ID
        • Listar templates do card
        • Ativar template
        • Criar template de documento
        • Remover template
        • Listar templates
        • Definir campos do template
        • Configurar regras condicionais do template
        • Atualizar arquivo do template
      • Cards
        • Cards — Visão Geral
        • Listar cards de uma fase
        • Mover card de fase
        • Criar card
        • Listar cards do flow
        • Criar card via link público
        • Buscar cards
        • Obter card
        • Atualizar card
        • Atualizar responsável do card
        • Atualizar campos via link público
        • Atualizar campos de fase do card
        • Remover cards em lote
        • Atualizar Ficha Cadastral do card
        • Obter responsável do card
        • Listar etiquetas do card
        • Listar campos de uma fase do card
        • Listar campos de uma fase do card (link público)
        • Obter histórico do card
        • Listar clientes do card
        • Criar comentário no card
        • Listar comentários do card
        • Remover comentário do card
        • Listar anexos do card
        • Cadastrar anexo no card
        • Remover anexo do card
        • Remover vínculo do anexo com campo de fase
        • Adicionar membros ao grupo do card
        • Remover membro do grupo do card
      • Configuração de Cliente
        • Configuração de Cliente — Visão Geral
        • Obter configuração de cliente por empresa
        • Criar configuração de cliente
        • Atualizar configuração de cliente
        • Obter configuração de cliente
        • Remover configuração de cliente
        • Listar seções
        • Criar seções
        • Obter seção
        • Atualizar seção
        • Atualizar seção parcialmente
        • Remover seção
        • Listar campos
        • Criar campos
        • Obter campo
        • Atualizar campo
        • Atualizar campo parcialmente
        • Remover campo
        • Listar regras
        • Criar regra
        • Obter regra
        • Atualizar regra
        • Atualizar regra parcialmente
        • Remover regra
      • Fase
        • Fase — Visão Geral
        • Criar ação de fase
        • Criar fase
        • Remover ação de fase
        • Remover fase
        • Listar ações da fase
        • Listar fases
        • Atualizar ação de fase
        • Atualizar fase
    • 🇺🇸 English
      • Phase
        • Phase — Overview
        • Create phase action
        • Create phase
        • Delete phase action
        • Delete phase
        • List phase actions
        • List phases
        • Update phase action
        • Update phase
      • Approval
        • Approval — Overview
        • Get approval configuration
        • Create approval configuration
        • Update approval configuration
        • Add approval rule
        • Update approval rule
        • Delete approval configuration
        • Get card approval
        • Register approval vote
        • Update approval vote
      • Flow
        • Flow — Overview
        • Health check
        • Create flow
        • List flows
        • Get flow
        • Update flow
        • Delete flow
        • Add user to flow
        • Remove user from flow
        • List dynamic field paths
      • Bureau Query
        • Bureau Query — Overview
        • Get bureau query configuration
        • Create bureau query configuration
        • Update bureau query configuration
      • Fields
        • Fields — Overview
        • List phase fields
        • Update phase fields
        • Update phase field rules
      • Engines
        • Engines — Overview
        • Get card decision engine result
        • Run card decision engine
        • Get card credit engine inputs
        • Get card credit engine result
        • Run card credit engine
        • Get decision engine configuration
        • Create decision engine configuration
        • Update decision engine configuration
        • Delete decision engine configuration
        • Get credit engine configuration detail
        • Create credit engine configuration
        • List flow credit engine configurations
        • List credit policies applicable to a card
        • Update credit engine configuration
        • Delete credit engine configuration
      • Conversation
        • Conversation — Overview
        • Get conversation configuration
        • Create conversation configuration
        • Delete conversation configuration
      • Opinion
        • Opinion — Overview
        • Get opinion configuration
        • Create opinion configuration
        • Update opinion configuration
        • Get card opinion
        • Create card opinion
        • Update card opinion
      • Start Form
        • Start Form — Overview
        • Create start form
        • Set start form conditional rules
        • Update start form metadata
        • Get start form
        • Get public start form
        • Update start form fields
        • Delete start form
      • Filters
        • Filters — Overview
        • List saved filters
        • Create saved filter
        • Update saved filter
        • Search flow cards
        • Search cards across flows
      • AgRisk
        • AgRisk — Overview
        • List AgRisk query products
      • Triggers
        • Triggers — Overview
        • List flow triggers
        • Create trigger
        • Update trigger
        • Delete trigger
        • List phase triggers
      • Authentication
        • Authentication — Overview
        • Authenticate user
      • Messaging
        • Messaging — Overview
        • Configure phone
        • Get messaging config
        • Create messaging config
        • Update messaging config
        • Create messaging rules
        • Update messaging rule
        • Delete messaging config
      • Companies & Roles
        • Companies & Roles — Overview
        • List company users
        • List company roles
        • Update role
        • List permissions catalog
        • Create role
        • Generate company logo upload URL
        • Generate company logo download URL
        • Assign roles to a user
      • Documents
        • Documents — Overview
        • Create automatic document configuration
        • Delete automatic document configuration
        • Get automatic document configuration
        • Update automatic document configuration
        • Get fields for document generation
        • Generate document from template
        • Get template by ID
        • List card templates
        • Activate template
        • Create document template
        • Delete template
        • List templates
        • Set template fields
        • Configure template conditional rules
        • Update template file
      • Cards
        • Cards — Overview
        • List cards in a phase
        • Move card to another phase
        • Create card
        • List flow cards
        • Create card via public link
        • Search cards
        • Get card
        • Update card
        • Update card assignee
        • Update fields via public link
        • Update card phase fields
        • Delete cards in bulk
        • Update card registration record
        • Get card assignee
        • List card labels
        • List card phase fields
        • List card phase fields (public link)
        • Get card history
        • List card clients
        • Create card comment
        • List card comments
        • Delete card comment
        • List card attachments
        • Register card attachment
        • Delete card attachment
        • Delete attachment's phase-field link
        • Add members to card group
        • Remove card group member
      • Client Configuration
        • Client Configuration — Overview
        • Get client configuration by company
        • Create client configuration
        • Update client configuration
        • Get client configuration
        • Delete client configuration
        • List sections
        • Create sections
        • Get section
        • Update section
        • Partially update section
        • Delete section
        • List fields
        • Create fields
        • Get field
        • Update field
        • Partially update field
        • Delete field
        • List rules
        • Create rule
        • Get rule
        • Update rule
        • Partially update rule
        • Delete rule
    • 💼 Visão de Negócio
      • Fase
      • Fluxo
      • Campos — Visão de Negócio
      • Aprovação
      • Parecer
      • Motores
      • Empresas e Papéis
      • Gatilhos
      • Conversa
      • Documentos
      • Mensageria
      • Filtros
      • Autenticação
      • Configuração de Cliente
      • Cards
      • AgRisk
      • Formulário Inicial
      • Consulta a Bureau
    • 💼 Business Overview
      • Phase
      • Flow
      • Approval
      • Fields — Business Overview
      • Opinion
      • Engines
      • Companies & Roles
      • Documents
      • Triggers
      • Messaging
      • Conversation
      • Filters
      • Authentication
      • Client Configuration
      • Cards
      • AgRisk
      • Start Form
      • Bureau Query
  • Portfolio
    • Documentação
      • Empresa
      • Gestão de portfolio
        • Análise geral
        • Dicionário de campos base (Necessário validar)
        • [Desatualizado]Fluxo de funcionamento
        • Carteiras
          • Gestão da carteira
        • Contratos
          • Contratos
          • Template Contratos
        • Pagamentos
          • Pagamentos
        • Baixas
          • Baixas
        • Clientes
          • Devedores e credores (Participantes)
          • Informações dos clientes
        • Importação de dados
          • Importação de dados
        • Garantia
          • Colaterais
      • Gestão de Cobrança
        • Régua de cobrança
          • Regras da régua por empresa
        • Atividades
          • Regras das Atividades
  1. Baixas

Baixas

Baixas — Regras de Negócio#

1. Conceito#

A Baixa (PaymentReceipt) representa o registro de uma liquidação total ou parcial de um pagamento (parcela). Um pagamento pode acumular múltiplas baixas ao longo do tempo — por exemplo, duas baixas parciais que juntas liquidam o valor total.
Cada baixa armazena um snapshot duplo dos valores no momento do registro: o calculado pelo sistema (com base nos percentuais de encargos do contrato e dias de atraso) e o efetivamente cobrado (que pode diferir quando há acordo comercial, desconto pontual ou perdão de mora). Esse snapshot duplo garante trilha de auditoria sobre o que o sistema sugeriu e o que foi registrado.
Cancelamento de baixa. Uma baixa registrada não é editada — ela é imutável. Para corrigir erros, cancela-se a baixa (motivo estruturado + observação) e registra-se nova baixa com os valores corretos. O cancelamento é soft delete: a baixa original fica visível no histórico mas não conta para o saldo do pagamento.
Escopo da v1: Registro manual de baixas e cancelamentos. Substituição atômica (cancela + cria nova em uma só operação), limite temporal para cancelamento e conciliação bancária automática ficam para versões futuras.

2. Estruturas de Dados#

2.1. PaymentReceipt#

Contrato de API (não confundir com armazenamento). Esta tabela descreve o payload das respostas e requisições. A estrutura aninhada (paymentMethod, snapshot, charges, cancellation, registeredBy) é resultado de serialização — o modelo de dados em 12. Modelo de Dados.md armazena os campos em colunas flat. O backend hidrata e agrupa na hora de devolver.

Campos top-level#

CampoTipoObrigatórioDescrição
idUUIDSimIdentificador único da baixa.
paymentIdUUIDSimReferência ao pagamento (parcela) liquidado.
contractIdUUIDSimReferência ao contrato pai. Desnormalizado.
companyIdUUIDSimEmpresa. Desnormalizado.
receivedAmountDecimalSimValor efetivamente recebido neste registro. Deve ser maior que zero e menor ou igual ao amounts.remaining da parcela.
receivedAtDatetime (ISO YYYY-MM-DD)SimData efetiva da liquidação. Aceita retroativas, não aceita datas futuras.
statusEnumSimACTIVE (baixa válida que conta para o saldo) ou CANCELLED (baixa anulada, não conta).
paymentStatusEnumNãoApenas em responses. Reflete o status recalculado do pagamento (parcela) após esta baixa ou cancelamento. Evita roundtrip do frontend.
notesStringNãoObservações livres sobre a baixa.
paymentMethodObjectSimObjeto com forma de pagamento. Ver detalhe abaixo.
snapshotObjectSimSnapshot imutável do estado do contrato/parcela no momento da baixa. Ver detalhe abaixo.
chargesObjectSimEncargos com snapshot duplo. Ver detalhe abaixo.
cancellationObjectSimDados de cancelamento. Sempre presente, com null em todos os campos quando status = ACTIVE. Ver detalhe abaixo.
registeredByObjectSimUsuário que registrou, hidratado: { id, name }.
createdAtDateTime (ISO 8601 UTC)SimData de criação do registro.
updatedAtDateTime (ISO 8601 UTC)SimData da última atualização (geralmente igual a createdAt, exceto se cancelada).

paymentMethod (objeto)#

CampoTipoObrigatórioDescrição
paymentMethod.typeEnumSimForma: BOLETO, PIX, BANK_TRANSFER, CASH, CHECK, OTHER.
paymentMethod.descriptionStringCondicionalDescrição livre quando type = OTHER. Obrigatório nesse caso.
paymentMethod.referenceStringNãoReferência externa: endToEndId do PIX, número do boleto, número do cheque, ID da transação. Formato livre.

snapshot (objeto, imutável após criação)#

Snapshot dos valores do contrato/parcela no momento da baixa — preserva trilha de auditoria mesmo se o contrato ou parcela forem alterados depois.
CampoTipoObrigatórioDescrição
snapshot.valueDecimalSimSnapshot do amounts.value do pagamento no momento da baixa.
snapshot.correctedDecimalNãoSnapshot do amounts.corrected. null quando sem correção monetária.
snapshot.correctionIndexEnumNãoSnapshot do correctionIndex do contrato. null quando sem correção.
snapshot.interestCalculationMethodEnumNãoMétodo aplicado: SIMPLE ou COMPOUND. Snapshot do contrato. null quando juros não aplicáveis.

charges (objeto)#

Cada encargo segue o padrão snapshot duplo: calculated (o que o sistema calculou — imutável) e charged (o que foi efetivamente cobrado — editável apenas na criação).
CampoTipoObrigatórioDescrição
charges.interestObjectSimJuros de mora. Objeto { calculated, charged }.
charges.interest.calculatedDecimalNãoCalculado pelo sistema (snapshot, imutável). null quando não aplicável.
charges.interest.chargedDecimalNãoEfetivamente cobrado. Default = calculated. Editável apenas na criação.
charges.fineObjectSimMulta por atraso. Objeto { calculated, charged }.
charges.fine.calculatedDecimalNãoCalculado pelo sistema. null quando não aplicável.
charges.fine.chargedDecimalNãoEfetivamente cobrado. Default = calculated. Editável apenas na criação.
charges.discountObjectSimDesconto. Objeto { calculated, charged }.
charges.discount.calculatedDecimalNãoCalculado pelo sistema. null quando não aplicável (ex: baixa após o vencimento — RN-REC-010).
charges.discount.chargedDecimalNãoEfetivamente aplicado. Default = calculated. Editável apenas na criação. Pode ser informado mesmo quando calculated = null (acordo pontual).

cancellation (objeto, sempre presente)#

Objeto sempre presente no payload, com todos os campos null quando status = ACTIVE.
CampoTipoObrigatórioDescrição
cancellation.atDateTime (ISO 8601 UTC)NãoData/hora do cancelamento. null quando status = ACTIVE.
cancellation.byObjectNãoUsuário que cancelou, hidratado: { id, name }. null quando status = ACTIVE.
cancellation.reasonEnumNãoMotivo do cancelamento (ver seção 2.2). null quando status = ACTIVE.
cancellation.notesStringNãoObservações livres do cancelamento. null quando status = ACTIVE.

registeredBy (objeto)#

CampoTipoObrigatórioDescrição
registeredBy.idUUIDSimID do usuário que registrou a baixa.
registeredBy.nameStringSimNome do usuário, hidratado pelo backend.

2.2. Motivos pré-definidos de cancelamento#

Lista de motivos aceitos em cancellation.reason:
CódigoSignificado
INCORRECT_VALUEValor recebido foi registrado incorretamente.
INCORRECT_DATEData da baixa foi registrada incorretamente.
WRONG_PAYMENTBaixa foi registrada na parcela errada.
TYPING_ERRORErro de digitação em qualquer campo da baixa.
OTHEROutros motivos. Recomenda-se preencher cancellation.notes com detalhe.

2.3. Snapshot de encargos (snapshot duplo)#

No momento do registro da baixa, o sistema executa:
Passo 1 — Cálculo dos encargos (charges.*.calculated):
Sistema calcula charges.interest.calculated, charges.fine.calculated e charges.discount.calculated com base nos percentuais do contrato (finePercentage, dailyInterestPercentage, configuração de desconto da parcela) e nas regras de aplicabilidade do template (paymentDefaults). Esses campos ficam imutáveis após criação.
Passo 2 — Valores efetivos (charges.*.charged):
Os campos charges.interest.charged, charges.fine.charged e charges.discount.charged são preenchidos pelo usuário no body da requisição. Quando ausentes, recebem o valor de calculated correspondente (default). Quando informados, podem diferir — refletindo acordos comerciais, descontos pontuais ou perdão de mora.
Passo 3 — Elegibilidade de desconto:
Desconto por pagamento antecipado só é calculado automaticamente quando receivedAt <= dueDate. Após o vencimento, charges.discount.calculated é null. O usuário pode ainda informar charges.discount.charged manualmente para um acordo pontual.
Passo 4 — Snapshots de valor value:
snapshot.value, snapshot.corrected, snapshot.correctionIndex e snapshot.interestCalculationMethod são preenchidos automaticamente e são imutáveis.

2.4. Impacto no status do pagamento#

O status do pagamento (parcela) é recalculado automaticamente após cada baixa ativa ou cancelamento.
CondiçãoStatus da parcela
amounts.received acumulado (de baixas ACTIVE) = 0 e dueDate não ultrapassadoPENDING
amounts.received acumulado = 0 e dueDate ultrapassado, sem daysToDefault ultrapassadoOVERDUE
amounts.received acumulado = 0 e daysToDefault do contrato ultrapassadoDEFAULTED (via job)
0 < amounts.received acumulado < amounts.duePARTIALLY_PAID
amounts.received acumulado >= amounts.duePAID
O amounts.received acumulado da parcela é a soma dos receivedAmount de todas as baixas com status = ACTIVE. Baixas CANCELLED são ignoradas no cálculo do saldo.
Reversão de status no cancelamento. Quando uma baixa é cancelada, o saldo é recalculado e o status da parcela pode reverter (ex.: PAID → PARTIALLY_PAID, PARTIALLY_PAID → PENDING/OVERDUE).

3. Regras de Negócio#

Elegibilidade da baixa#

RN-REC-001: Pagamentos elegíveis para baixa
Baixas só podem ser registradas em pagamentos com status = PENDING, PARTIALLY_PAID, OVERDUE ou DEFAULTED. Erro: PAYMENT_NOT_RECEIVABLE.

Valor e data#

RN-REC-002: Valor positivo
O receivedAmount deve ser maior que zero. Erro: INVALID_RECEIVED_AMOUNT.
RN-REC-003: Valor não excede saldo aberto
O receivedAmount deve ser menor ou igual ao amounts.remaining da parcela no momento do registro. Não é permitida baixa que cause "saldo negativo" (excedente). Erro: RECEIVED_AMOUNT_EXCEEDS_REMAINING.
RN-REC-004: Múltiplas baixas até liquidar
Um pagamento pode acumular múltiplas baixas ativas. O amounts.received acumulado é a soma do receivedAmount de todas as baixas ACTIVE. O status da parcela é recalculado após cada registro (ver seção 2.4).
RN-REC-005: Data retroativa permitida; futura não
O receivedAt pode ser anterior à data atual (retroativo é aceito). Não aceita datas futuras. Erro: FUTURE_RECEIPT_DATE.
RN-REC-006: Referência de pagamento
O paymentMethod.reference é opcional e de formato livre.

Encargos (snapshot duplo)#

RN-REC-007: Snapshot calculado é imutável
O sistema captura charges.interest.calculated, charges.fine.calculated e charges.discount.calculated no momento da criação. Esses campos não são editáveis depois — representam "o que o sistema calculou no momento da baixa".
RN-REC-008: Valores cobrados podem diferir do calculado
charges.interest.charged, charges.fine.charged e charges.discount.charged recebem como default os respectivos calculated. O usuário pode informar valores diferentes na criação para refletir acordos comerciais ou descontos pontuais. Após criada, esses valores também ficam imutáveis (para alterar, cancela a baixa e cria nova).
RN-REC-009: Encargos condicionados ao tipo
Quando paymentDefaults.interestApplicable = false, charges.interest.calculated é null. Quando o contrato não tem dailyInterestPercentage configurado, idem. O usuário pode informar charges.interest.charged manualmente nesse caso (acordo). Mesma lógica para multa e desconto.
RN-REC-010: Desconto apenas antes do vencimento (cálculo automático)
charges.discount.calculated só é diferente de null quando receivedAt <= dueDate da parcela. Após vencimento, null. charges.discount.charged pode ser informado manualmente em qualquer caso.
RN-REC-011: Correção monetária
Para contratos com correctionIndex != NONE, o amounts.corrected é base para cálculo de encargos. Registrado em snapshot.corrected.

Cancelamento de baixa#

RN-REC-012: Cancelamento via soft delete
Baixas são imutáveis após criação. Para corrigir erros, cancela-se a baixa (status = CANCELLED). O registro original permanece visível no histórico. Para registrar valores corretos, cria-se nova baixa.
RN-REC-013: Motivo obrigatório no cancelamento
cancellation.reason é obrigatório no cancelamento e deve ser um dos códigos pré-definidos (INCORRECT_VALUE, INCORRECT_DATE, WRONG_PAYMENT, TYPING_ERROR, OTHER). cancellation.notes é opcional para texto livre. Erro: CANCELLATION_REASON_REQUIRED.
RN-REC-014: Recálculo do saldo após cancelamento
Cancelar uma baixa exclui seu receivedAmount do total acumulado da parcela (amounts.received). O status da parcela é recalculado conforme regras da seção 2.4 — pode reverter (ex.: PAID → PARTIALLY_PAID/OVERDUE).
RN-REC-015: Imutabilidade após cancelamento
Baixa com status = CANCELLED não pode ser reativada nem editada. Para registrar nova liquidação, criar nova baixa. Erro: RECEIPT_ALREADY_CANCELLED.
RN-REC-016: Permissão de cancelamento
O cancelamento utiliza a mesma permissão da criação (payment_receipt:create) na v1. Não há action separada para cancelamento. A separação pode ser revisada em versões futuras se houver demanda operacional (ex.: separar operador que registra vs. supervisor que cancela).

Forma de pagamento#

RN-REC-017: Forma customizada
Quando paymentMethod.type = OTHER, paymentMethod.description é obrigatório. Erro: MISSING_PAYMENT_METHOD_DESCRIPTION.

Exclusão#

RN-REC-018: Exclusão lógica
Baixas nunca são deletadas fisicamente. Anulação se dá via cancelamento (status = CANCELLED).

4. Padrão de Erros#

StatusCódigoDescrição
404PAYMENT_NOT_FOUNDPagamento (parcela) não encontrado.
404RECEIPT_NOT_FOUNDBaixa não encontrada.
422PAYMENT_NOT_RECEIVABLEPagamento em status que não permite baixa.
422INVALID_RECEIVED_AMOUNTreceivedAmount deve ser > 0.
422RECEIVED_AMOUNT_EXCEEDS_REMAININGreceivedAmount excede o saldo aberto da parcela.
422FUTURE_RECEIPT_DATEreceivedAt é data futura.
422MISSING_PAYMENT_METHOD_DESCRIPTIONpaymentMethod.type = OTHER sem descrição.
422RECEIPT_ALREADY_CANCELLEDBaixa já cancelada.
422CANCELLATION_REASON_REQUIREDMotivo do cancelamento ausente ou inválido.

5. Endpoints#

Base path: /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/payments/:paymentId/receipts

POST .../receipts#

Registra uma baixa. Recalcula status do pagamento.
Permissão: payment_receipt:create
Request body — baixa com defaults dos encargos calculados:
{
  "receivedAmount": 153225.00,
  "receivedAt": "2024-03-14T00:00:00.000+00:00",
  "notes": "Pagamento confirmado via comprovante PIX.",
  "paymentMethod": {
    "type": "PIX",
    "reference": "E12345678202503201234abcdef123456"
  }
}
Neste exemplo, o objeto charges não é informado — o sistema preenche cada charged com o respectivo calculated.
Request body — baixa com sobrescrita de encargos cobrados:
{
  "receivedAmount": 152000.00,
  "receivedAt": "2025-03-20",
  "notes": "Acordo negociado com desconto sobre multa.",
  "paymentMethod": {
    "type": "BANK_TRANSFER",
    "reference": "TED-001-20250320"
  },
  "charges": {
    "interest": { "charged": 200.00 },
    "fine": { "charged": 1000.00 },
    "discount": { "charged": 500.00 }
  }
}
No request, apenas charged é aceito em cada componente de charges (o calculated é sempre derivado pelo backend). Enviar calculated resulta no campo ser ignorado.
Response 201 Created:
{
  "id": "rec-001",
  "paymentId": "pay-001",
  "contractId": "contract-001",
  "companyId": "company-001",
  "receivedAmount": 153225.00,
  "receivedAt": "2025-03-20",
  "status": "ACTIVE",
  "paymentStatus": "PAID",
  "notes": "Pagamento confirmado via comprovante PIX.",
  "paymentMethod": {
    "type": "PIX",
    "description": null,
    "reference": "E12345678202503201234abcdef123456"
  },
  "snapshot": {
    "value": 150000.00,
    "corrected": null,
    "correctionIndex": null,
    "interestCalculationMethod": "SIMPLE"
  },
  "charges": {
    "interest": { "calculated": 225.00, "charged": 225.00 },
    "fine": { "calculated": 3000.00, "charged": 3000.00 },
    "discount": { "calculated": null, "charged": null }
  },
  "cancellation": {
    "at": null,
    "by": null,
    "reason": null,
    "notes": null
  },
  "registeredBy": {
    "id": "8c3f1a2b-...",
    "name": "João Silva"
  },
  "createdAt": "2025-03-20T10:00:00.000+00:00",
  "updatedAt": "2025-03-20T10:00:00.000+00:00"
}
O campo paymentStatus reflete o novo status do pagamento (parcela) após o registro, evitando roundtrip do frontend.
Erros: PAYMENT_NOT_RECEIVABLE, INVALID_RECEIVED_AMOUNT, RECEIVED_AMOUNT_EXCEEDS_REMAINING, FUTURE_RECEIPT_DATE, MISSING_PAYMENT_METHOD_DESCRIPTION.

GET .../receipts#

Lista baixas do pagamento em ordem cronológica inversa.
Permissão: payment_receipt:read
Query params:
ParâmetroTipoObrigatórioDescrição
statusEnum (multi)NãoFiltrar por status: ACTIVE, CANCELLED.
orderByEnumNãoOrdenação: receivedAt, createdAt. Default: receivedAt.
orderEnumNãoasc ou desc. Default: desc.
offsetIntegerNãoDefault: 0.
limitIntegerNãoDefault: 20. Máximo: 100.
Response 200 OK:
{
  "items": [
    {
      "id": "rec-001",
      "paymentId": "pay-001",
      "contractId": "contract-001",
      "receivedAmount": 153225.00,
      "receivedAt": "2025-03-20",
      "status": "ACTIVE",
      "notes": "Pagamento confirmado via comprovante PIX.",
      "paymentMethod": {
        "type": "PIX",
        "description": null,
        "reference": "E12345678202503201234abcdef123456"
      },
      "snapshot": {
        "value": 150000.00,
        "corrected": null,
        "correctionIndex": null,
        "interestCalculationMethod": "SIMPLE"
      },
      "charges": {
        "interest": { "calculated": 225.00, "charged": 225.00 },
        "fine": { "calculated": 3000.00, "charged": 3000.00 },
        "discount": { "calculated": null, "charged": null }
      },
      "cancellation": {
        "at": null,
        "by": null,
        "reason": null,
        "notes": null
      },
      "registeredBy": {
        "id": "8c3f1a2b-...",
        "name": "João Silva"
      },
      "createdAt": "2025-03-20T10:00:00.000+00:00",
      "updatedAt": "2025-03-20T10:00:00.000+00:00"
    }
  ],
  "nextPage": false
}

GET .../receipts/:receiptId#

Detalhe completo da baixa.
Permissão: payment_receipt:read
Response 200 OK (baixa cancelada):
{
  "id": "rec-001",
  "paymentId": "pay-001",
  "contractId": "contract-001",
  "companyId": "company-001",
  "receivedAmount": 153225.00,
  "receivedAt": "2025-03-20",
  "status": "CANCELLED",
  "notes": "Pagamento confirmado via comprovante PIX.",
  "paymentMethod": {
    "type": "PIX",
    "description": null,
    "reference": "E12345678202503201234abcdef123456"
  },
  "snapshot": {
    "value": 150000.00,
    "corrected": null,
    "correctionIndex": null,
    "interestCalculationMethod": "SIMPLE"
  },
  "charges": {
    "interest": { "calculated": 225.00, "charged": 225.00 },
    "fine": { "calculated": 3000.00, "charged": 3000.00 },
    "discount": { "calculated": null, "charged": null }
  },
  "cancellation": {
    "at": "2025-03-20T11:00:00.000+00:00",
    "by": {
      "id": "8c3f1a2b-...",
      "name": "João Silva"
    },
    "reason": "INCORRECT_VALUE",
    "notes": "Valor incorreto registrado. Nova baixa será criada com valor correto."
  },
  "registeredBy": {
    "id": "8c3f1a2b-...",
    "name": "João Silva"
  },
  "createdAt": "2025-03-20T10:00:00.000+00:00",
  "updatedAt": "2025-03-20T11:00:00.000+00:00"
}

POST .../receipts/:receiptId/cancel#

Cancela uma baixa (soft delete). Recalcula status do pagamento. A baixa original permanece no histórico com status = CANCELLED e o objeto cancellation preenchido.
Permissão: payment_receipt:create (mesma da criação na v1)
Request body:
{
  "cancellation": {
    "reason": "INCORRECT_VALUE",
    "notes": "Valor incorreto registrado. Nova baixa será criada com valor correto."
  }
}
Response 200 OK:
{
  "id": "rec-001",
  "status": "CANCELLED",
  "paymentStatus": "OVERDUE",
  "cancellation": {
    "at": "2025-03-20T11:00:00.000+00:00",
    "by": {
      "id": "8c3f1a2b-...",
      "name": "João Silva"
    },
    "reason": "INCORRECT_VALUE",
    "notes": "Valor incorreto registrado. Nova baixa será criada com valor correto."
  },
  "updatedAt": "2025-03-20T11:00:00.000+00:00"
}
O campo paymentStatus reflete o status recalculado da parcela após o cancelamento.
Erros: RECEIPT_NOT_FOUND, RECEIPT_ALREADY_CANCELLED, CANCELLATION_REASON_REQUIRED.

6. Permissões RBAC#

ResourceDomínioActions
payment_receiptTENANTcreate, read
A action create cobre tanto a criação de baixa quanto seu cancelamento na v1 — não há action separada para cancelamento (RN-REC-016). Caso surja necessidade operacional de granularidade (operador registra, supervisor cancela), uma action cancel pode ser introduzida em versão futura.

7. Roadmap#

7.1. Substituição atômica (cancelar + criar nova em uma operação)#

Endpoint POST /receipts/:receiptId/replace que executa em uma única transação o cancelamento da baixa antiga e a criação de uma nova com os dados corretos. Reduz risco de "esqueceu de criar nova após cancelar". Decisão registrada no consolidado para reavaliação futura.

7.2. Limite temporal para cancelamento#

Restringir cancelamento de baixas com mais de X dias (ex.: 90 dias) exigindo permissão elevada. Proteção contra alterações fora do período fiscal corrente. Útil quando houver integração contábil que feche períodos.

7.3. Conciliação bancária automática#

Integração com bancos e gateways para identificar pagamentos recebidos e vincular automaticamente aos pagamentos (parcelas). Dashboard de conciliação, fila manual, processamento de CNAB.

7.4. Baixa em lote (batch)#

Registrar uma única baixa que cobre múltiplos pagamentos (parcelas) de uma vez. Comum quando o cliente faz um depósito único cobrindo várias parcelas em aberto.
Modificado em 2026-06-02 15:00:58
Página anterior
Pagamentos
Próxima página
Devedores e credores (Participantes)
Built with