Gestão de Portfolio — Visão Geral#
1. Conceito#
A Gestão de Portfolio é o módulo para cadastro, acompanhamento e gestão de carteiras de recebíveis. Foco no agronegócio, com instrumentos variados — CPRs (Físicas e Financeiras), contratos de compra e venda, duplicatas, CCBs, notas promissórias, entre outros.Cada tipo de contrato possui um schema de campos base fixo pela plataforma, extensível pela empresa via templates customizados com campos dinâmicos, seções visuais e regras condicionais (inspirado no modelo AgFlow start-forms / phase-fields).O módulo distingue duas entidades centrais: o template de contrato (ContractTemplate) — entidade abstrata que define o schema, as regras e os comportamentos padrão de um tipo de contrato — e o contrato (Contract) propriamente dito — entidade concreta que representa uma operação jurídico-financeira real, criada a partir de um template. Essa separação permite que uma mesma definição seja reaproveitada em múltiplas operações sem duplicação, e que o schema evolua de forma independente dos contratos já emitidos.1.1. Escopo#
Foco na visão gerencial e operacional:Múltiplos portfolios por empresa com carteiras.
Templates de contrato dinâmicos (tipo base + campos customizáveis).
Contratos com participantes tipados (credores, devedores, garantidores).
Colaterais (garantias reais e fidejussórias) como sub-recurso do contrato.
Pagamentos (parcelas) com cálculo de encargos.
Baixas (recebimentos) manuais com snapshot de encargos.
Listagem básica de clientes na carteira.
Company): Portfolios, templates e configurações pertencem à empresa.Usuários Tenant (User): O acesso ao módulo é controlado pela combinação de duas dimensões:1.
Permissões RBAC do próprio módulo — resources e actions descritos na seção 9 definem o que o usuário pode fazer (ler, criar, editar, etc.).
2.
Atribuição direta do usuário a portfolios e/ou carteiras (via portfolio:assign_user) — define em quais carteiras o usuário atua.
UNIT_RESTRICTED). Em outros módulos da plataforma, o escopo UNIT_RESTRICTED é usado para limitar a visibilidade de um usuário aos recursos das unit(s) à(s) qual(is) ele pertence (separação matriz/filial em sistemas que segmentam a empresa por unidades operacionais). Esse escopo não se aplica ao módulo de Portfolio Management. Aqui, a visibilidade é determinada exclusivamente pela combinação RBAC + atribuição a portfolios/carteiras descrita acima. Um usuário com contract:read, por exemplo, enxerga todos os contratos dos portfolios aos quais foi atribuído, independentemente da unit a que pertence.Clientes (Client): Todos os participantes de contratos devem ser Clients já cadastrados na plataforma. O módulo não cria Clients — quando não encontrado, orienta o usuário a cadastrar pelo módulo de Clientes do AgRisk.RBAC: Novos resources e actions específicos do módulo.
2. Estrutura do Módulo#
| Sub-módulo | Arquivo | Descrição |
|---|
| Portfolios | Gestão de carteira.md | Múltiplos por empresa. Cada portfolio tem uma ou mais carteiras (obrigatórias para receber contratos). |
| Templates | ContractTemplates.md | Tipo base + campos customizáveis. Seções, regras, cálculos. |
| Contratos | Contratos.md | Instrumentos de crédito orientados a template. |
| Participantes | Participantes.md | Credores, devedores, garantidores. Client ↔ Contract. |
| Colaterais | Colaterais.md | Garantias reais e fidejussórias. Sub-recurso do contrato (1:N). |
| Pagamentos | Pagamentos.md | Parcelas/obrigações com vencimento. |
| Baixas | Baixas.md | Registro de recebimento de pagamento com snapshot de encargos. |
| Clientes | Informações dos clientes.md | Listagem básica de devedores com indicadores. |
| Importação | Importacao.md | Ingestão via API. Fluxo em duas fases. |
3. Hierarquia de Entidades#
Empresa (Company)
├── Template de contrato (ContractTemplate) [1..N] ─── entidade abstrata (schema reutilizável)
│ └── Tipo base + campos customizados + regras
│
└── Portfolio (1..N por empresa)
└── Carteira (SubPortfolio) [1..N por portfolio]
│
└── Contrato (Contract) ─── entidade concreta, referencia 1 template via templateId
├── Participante (ContractParticipant) ─── CREDITOR / DEBTOR / GUARANTOR
│ └── → Client já cadastrado na plataforma
├── Colateral (ContractCollateral) [0..N] ─── REAL / FIDEJUSSORY
│
└── Pagamento (ContractPayment) [1..N] ─── parcela
└── Baixa (PaymentReceipt) [0..N] ─── registro de recebimento
Um contrato pertence a exatamente um portfolio (silo isolado).
Um contrato referencia exatamente um template; um template pode originar múltiplos contratos.
Um contrato tem 1..N pagamentos (parcelas).
Um contrato tem ao menos um participante CREDITOR (a própria empresa ou outro Client) e ao menos um participante DEBTOR para ser ativado.
Tipo do pagamento restrito pelo contrato (allowedPaymentTypes).
Colaterais são sub-recurso do contrato (1:N), não entidade independente.
Todos os participantes são Clients existentes na plataforma.
CREDITOR (caso comum) ou em outros papéis. Para isso, a empresa possui um Client espelho associado (isCompany = true), criado automaticamente ao ativar o módulo, que a representa em participações de contrato.
4. Modelo de Templates#
4.1. Template vs. Contrato: abstração e instância#
O template é a definição abstrata e reutilizável de um tipo de contrato: especifica quais campos existem, quais regras se aplicam, quais defaults de comportamento valem. Não representa nenhuma operação real — é um molde.O contrato é a instância concreta criada a partir de um template: representa uma operação jurídico-financeira específica, com participantes, valores, datas, colaterais e pagamentos reais. O vínculo se dá pelo campo templateId no contrato.| Aspecto | Template (ContractTemplate) | Contrato (Contract) |
|---|
| Natureza | Abstrata — define a estrutura de um tipo de contrato | Concreta — representa uma operação real |
| Papel | Molde / schema reutilizável | Instância com dados preenchidos |
| Cardinalidade | Pode originar N contratos | Criado a partir de 1 template |
| Composição | Campos, regras condicionais, seções, defaults | Participantes, valores, colaterais, pagamentos |
| Ciclo de vida | Próprio (edição, publicação, arquivamento) | Próprio (DRAFT → ACTIVE → CLOSED/DEFAULTED/...) |
| Gera obrigações financeiras | Não | Sim (via pagamentos) |
| Arquivo de especificação | ContractTemplates.md | Contratos.md |
Ciclos de vida independentes. O template e o contrato possuem ciclos de vida próprios e distintos. As regras específicas de versionamento e do impacto de alterações no template sobre contratos já criados estão definidas em Template de Contratos.md.| Código | Nome |
|---|
CPR_PHYSICAL | CPR Física |
CPR_FINANCIAL | CPR Financeira |
INVOICE | Duplicata / Nota Fiscal |
PURCHASE_SALE_CONTRACT | Contrato de Compra e Venda |
CCB | Cédula de Crédito Bancário |
PROMISSORY_NOTE | Nota Promissória |
OTHER | Outro (empresa define 100% dos campos) |
4.3. Composição do template em 3 camadas#
Um template é montado pela combinação de três camadas, aplicadas em sequência. As duas primeiras são nativas da plataforma — garantem que qualquer contrato tenha as informações mínimas necessárias para representar um instrumento de crédito. A terceira é configurada pela empresa e permite personalizar o template com os campos operacionais do seu negócio.| Camada | Fonte | Quando aplica | Conteúdo |
|---|
| 1. Campos comuns do contrato | Plataforma (fixa) | Sempre | Informações estruturais presentes em todo contrato: código, datas (emissão, vencimento), valor principal, status. |
| 2. Campos do tipo base | Plataforma (fixa) | Quando type != OTHER | Campos específicos do instrumento jurídico (typeSpecificFields). Ex.: safra e cultura para CPR, dados bancários para CCB. |
| 3. Campos customizados | Empresa (configurável) | Definidos pela empresa no template | Campos livres (customFields) que compõem a personalização do template, com seções, regras condicionais e cálculos. |
Um contrato criado a partir de um template deve preencher os campos obrigatórios das camadas aplicáveis. A obrigatoriedade dentro de cada camada é definida pela plataforma (camadas 1 e 2) e pela empresa (camada 3).Composição com tipo OTHER. Quando o tipo base é OTHER, a camada 2 fica vazia — não há campos fixos do instrumento — e toda a especificidade do contrato reside na camada 3. Isso permite modelar instrumentos não contemplados pela plataforma, mantendo a estrutura mínima garantida pela camada 1.Múltiplos templates por empresa. Uma empresa pode ter vários templates, inclusive para o mesmo tipo base. O que varia entre eles é a camada 3 — as camadas 1 e 2 são idênticas para todos os templates do mesmo tipo. Templates padrão da plataforma podem servir como fallback quando a empresa ainda não configurou nenhum.Responsabilidade de gestão por camada.Camadas 1 e 2 (geridas pela plataforma): os campos comuns do contrato (camada 1) e os campos do tipo base (camada 2) são modelados como uma coleção única de campos. Esta coleção é gerida pela plataforma com endpoints CRUD próprios — campos da camada 1 são sempre obrigatórios; campos da camada 2 são mapeados como aplicáveis ao tipo base correspondente (CPR, CCB, etc.). Para o tipo OTHER, apenas os campos da camada 1 se aplicam.
Camada 3 (gerida pela empresa): os campos customizados, seções, regras condicionais e cálculos são geridos pela empresa via os endpoints documentados na seção 10.
5. Ciclos de Vida#
5.1. Contrato#
DRAFT ──► ACTIVE ◄──► OVERDUE ──► DEFAULTED ──► CLOSED / RENEGOTIATED / CANCELLED
│ ▲
└──────────────────────────────┘
(ACTIVE também pode ir direto a CLOSED / RENEGOTIATED / CANCELLED)
(OVERDUE volta a ACTIVE quando a parcela em atraso é liquidada
antes da inadimplência ser formalizada)
DRAFT ──► CANCELLED
| Status | Significado |
|---|
DRAFT | Em elaboração, ainda não ativo. |
ACTIVE | Vigente, com parcelas em dia. |
OVERDUE | Vigente com ao menos uma parcela vencida (em atraso). Estado transitório — volta a ACTIVE se a parcela for liquidada antes da formalização da inadimplência. |
DEFAULTED | Inadimplência formal. Configurada por regra (ex.: parcela em atraso há mais de N dias) ou marcação operacional. |
CLOSED | Encerrado por liquidação total. |
RENEGOTIATED | Encerrado por substituição via renegociação. |
CANCELLED | Cancelado (a partir de DRAFT ou ACTIVE). |
5.2. Pagamento (parcela)#
PENDING ◄──► OVERDUE ──► DEFAULTED ──► PAID / PARTIALLY_PAID / RENEGOTIATED / CANCELLED
│ ▲
└──────────────────────────┘
(PENDING também pode ir direto a PAID / PARTIALLY_PAID / RENEGOTIATED / CANCELLED)
(OVERDUE volta a PENDING quando a parcela é liquidada antes da
formalização da inadimplência)
| Status | Significado |
|---|
PENDING | Em aberto, ainda dentro do prazo. |
OVERDUE | Vencida (dueDate ultrapassado), sem liquidação. Estado transitório. |
DEFAULTED | Inadimplência formal da parcela. Configurada por regra (ex.: vencida há mais de N dias) ou marcação operacional. |
PAID | Liquidada integralmente. |
PARTIALLY_PAID | Liquidada parcialmente. |
RENEGOTIATED | Substituída por renegociação. |
CANCELLED | Cancelada antes da liquidação. |
Relação contrato ↔ parcela. O status OVERDUE do contrato é derivado: o contrato passa a OVERDUE quando ao menos uma parcela está em OVERDUE ou DEFAULTED. O DEFAULTED do contrato é independente — pode ser configurado por regra própria do contrato (prazo de N dias) ou por marcação operacional manual.Pagamento parcial e vencimento. Uma parcela em PARTIALLY_PAID que ultrapassa o dueDate é movida automaticamente para OVERDUE. A trilha histórica de que houve baixas parciais é preservada via dischargedAmount e via auditoria das transições de status. Múltiplas baixas parciais são permitidas até a liquidação integral; o cálculo de encargos sobre o saldo aberto é detalhado na seção 6 e em Pagamentos.md.Configuração do prazo de inadimplência (N dias). O prazo após o vencimento que define a transição para DEFAULTED é configurado no contrato. A transição pode ocorrer das duas formas:Automática: job programado (ver seção 11) lê o N dias do contrato e movimenta a parcela/contrato quando o prazo é ultrapassado.
Manual: usuário pode marcar inadimplência formal antes do prazo, conforme a operação reconhecer a situação.
6. Encargos#
Encargos representam acréscimos cobrados em pagamentos atrasados. No escopo da v1 são dois:| Encargo | Campo no contrato | Cálculo |
|---|
| Multa | finePercentage | Percentual aplicado uma única vez sobre o valor da parcela quando há atraso. |
| Juros de mora | dailyInterestPercentage | Percentual aplicado por dia de atraso sobre o valor da parcela. |
A definição e o uso desses encargos passam por três fases, cada uma com responsabilidade clara:Fase 1 — Aplicabilidade (template)#
O template define se faz sentido cobrar encargos para aquele tipo de contrato, via paymentDefaults. É uma regra de domínio: alguns instrumentos não comportam multa e juros de mora pela própria natureza.| Tipo base | Encargos aplicáveis? | Justificativa |
|---|
CPR_PHYSICAL | Não | Obrigação é entrega de produto, não pagamento financeiro. |
CPR_FINANCIAL, CCB, PROMISSORY_NOTE, INVOICE, PURCHASE_SALE_CONTRACT | Sim | Operações financeiras com previsão de mora. |
OTHER | Configurável | Empresa decide ao montar o template. |
Quando o template indica que encargos não são aplicáveis, os campos finePercentage e dailyInterestPercentage ficam ocultos no contrato e nenhum cálculo é feito.Fase 2 — Parâmetros (contrato)#
Quando os encargos são aplicáveis, o contrato preenche os percentuais que serão usados no cálculo. Os campos são opcionais:Se finePercentage não for informado, multa não é calculada.
Se dailyInterestPercentage não for informado, juros de mora não são calculados.
Se ambos não forem informados, nenhum encargo é calculado, mesmo que aplicáveis pelo template.
Fase 3 — Cobrança efetiva (baixa)#
No momento de registrar a baixa de uma parcela em atraso, o sistema calcula os valores de multa e juros com base nos percentuais do contrato e nos dias de atraso. O usuário pode sobrescrever os valores calculados com os valores efetivamente cobrados — por exemplo, conceder desconto comercial, perdoar parte da mora, ou registrar um acordo pontual.| Campo na baixa | Origem | Comportamento |
|---|
calculatedFineAmount | Sistema | Valor calculado a partir de finePercentage. Não editável. |
calculatedInterestAmount | Sistema | Valor calculado a partir de dailyInterestPercentage × dias de atraso. Não editável. |
chargedFineAmount | Usuário | Valor de multa efetivamente cobrado. Default = calculatedFineAmount. |
chargedInterestAmount | Usuário | Valor de juros efetivamente cobrado. Default = calculatedInterestAmount. |
A baixa armazena ambos (calculado e cobrado) como snapshot, garantindo trilha de auditoria sobre o que o sistema sugeriu e o que foi efetivamente registrado.
7. Participantes#
| Papel | Código | Cardinalidade | Descrição |
|---|
| Credor | CREDITOR | 1..N | Quem concede o crédito. Obrigatório — pode ser a própria empresa (via Client espelho) ou outro Client. Suporta múltiplos credores em operações de cessão, cofinanciamento ou securitização. |
| Devedor | DEBTOR | 1..N | Quem assume a obrigação. Ao menos um obrigatório. |
| Garantidor | GUARANTOR | 0..N | Garantia pessoal (aval/fiança). Complementar ao colateral fidejussório. |
Todos os devedores devem ser Clients já cadastrados na plataforma. Client não encontrado → erro com orientação para cadastrar no AgRisk.UX default. No formulário de criação de contrato, o campo CREDITOR vem pré-selecionado com a empresa (Client espelho da empresa, ver seção 3). O usuário pode trocar para outro Client ou adicionar credores adicionais conforme a operação, adicionando os dados do novo credor..
8. Colaterais#
Garantias reais e fidejussórias como sub-recurso do contrato (1:N):| Categoria | Tipos |
|---|
REAL | Penhor agrícola, penhor de safra futura, alienação fiduciária (móvel/imóvel), hipoteca, seguro, outro. |
FIDEJUSSORY | Aval, fiança, fiança bancária, outro. |
Colateral fidejussório complementa o participante GUARANTOR: o participante registra quem garante; o colateral registra os termos.
9. Permissões RBAC#
| Resource | Domínio | Actions |
|---|
portfolio | TENANT | create, read, update, delete, assign_contract, assign_user |
contract_template | TENANT | create, read, update, delete |
contract | TENANT | create, read, update |
payment | TENANT | create, read, update |
payment_receipt | TENANT | create, read |
portfolio_report | TENANT | read, export |
portfolio_import | TENANT | create, read |
Participantes e colaterais usam contract:update. Não possuem resource próprio.A action delete em portfolio corresponde a desativação (soft delete via status = INACTIVE), bloqueada quando o portfolio possui contratos em estados não-terminais (regra detalhada em Carteiras.md).9.1. Modelo de visibilidade#
A visibilidade dos recursos do módulo (portfolios, contratos, pagamentos, baixas, etc.) é determinada pela combinação de duas dimensões independentes:1.
Permissão sobre o resource (RBAC) — contract:read, portfolio:read, etc. Define o que o usuário pode fazer.
2.
Atribuição do usuário a portfolios e/ou carteiras — define em quais carteiras o usuário atua. Gerenciada via action portfolio:assign_user.
| Nível | Entidade | Efeito |
|---|
| Portfolio | PortfolioUser | Usuário enxerga todos os contratos do portfolio, incluindo os de qualquer carteira. |
| Carteira | SubPortfolioUser | Usuário enxerga apenas os contratos da(s) carteira(s) à(s) qual(is) está atribuído. |
Um usuário pode ser atribuído ao portfolio inteiro, a carteiras específicas, ou a ambos (na prática, a atribuição ao portfolio já cobre tudo). A regra de visibilidade composta é:Recurso visível ⇔ (usuário tem permissão RBAC sobre o resource) AND (usuário está atribuído ao portfolio do recurso OU a alguma carteira que contenha o recurso).
Sobre o escopo de unit (UNIT_RESTRICTED). Em outros módulos da plataforma, esse escopo limita a visibilidade do usuário aos recursos da(s) unit(s) à(s) qual(is) ele pertence (separação matriz/filial). Esse escopo não se aplica ao módulo de Portfolio Management. A visibilidade aqui é determinada exclusivamente pela combinação RBAC + atribuição descrita acima — independente da estrutura organizacional de units.
10. Endpoints — Mapa Geral#
Templates#
| Método | Rota | Arquivo |
|---|
| POST | /v2/companies/:companyId/contract-templates | ContractTemplates.md |
| GET | /v2/companies/:companyId/contract-templates | ContractTemplates.md |
| GET | /v2/companies/:companyId/contract-templates/:templateId | ContractTemplates.md |
| GET | /v2/companies/:companyId/contract-templates/:templateId/schema | ContractTemplates.md |
| PATCH | /v2/companies/:companyId/contract-templates/:templateId | ContractTemplates.md |
| PUT | /v2/companies/:companyId/contract-templates/:templateId/status | ContractTemplates.md |
| POST | /v2/companies/:companyId/contract-templates/:templateId/sections | ContractTemplates.md |
| PATCH | /v2/companies/:companyId/contract-templates/:templateId/sections/:sectionId | ContractTemplates.md |
| DELETE | /v2/companies/:companyId/contract-templates/:templateId/sections/:sectionId | ContractTemplates.md |
| POST | /v2/companies/:companyId/contract-templates/:templateId/fields | ContractTemplates.md |
| PATCH | /v2/companies/:companyId/contract-templates/:templateId/fields/:fieldId | ContractTemplates.md |
| DELETE | /v2/companies/:companyId/contract-templates/:templateId/fields/:fieldId | ContractTemplates.md |
| POST | /v2/companies/:companyId/contract-templates/:templateId/rules | ContractTemplates.md |
| PATCH | /v2/companies/:companyId/contract-templates/:templateId/rules/:ruleId | ContractTemplates.md |
| DELETE | /v2/companies/:companyId/contract-templates/:templateId/rules/:ruleId | ContractTemplates.md |
Portfolios e carteiras#
| Método | Rota | Arquivo |
|---|
| POST | /v2/companies/:companyId/portfolios | Carteiras.md |
| GET | /v2/companies/:companyId/portfolios | Carteiras.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId | Carteiras.md |
| PATCH | /v2/companies/:companyId/portfolios/:portfolioId | Carteiras.md |
| PUT | /v2/companies/:companyId/portfolios/:portfolioId/status | Carteiras.md |
| POST | /v2/companies/:companyId/portfolios/:portfolioId/assigned-users | Carteiras.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/assigned-users | Carteiras.md |
| DELETE | /v2/companies/:companyId/portfolios/:portfolioId/assigned-users/:userId | Carteiras.md |
| POST | /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios | Carteiras.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios | Carteiras.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId | Carteiras.md |
| PATCH | /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId | Carteiras.md |
| PUT | /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/status | Carteiras.md |
| POST | /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users | Carteiras.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users | Carteiras.md |
| DELETE | /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users/:userId | Carteiras.md |
A vinculação de um contrato a uma carteira é representada como o campo obrigatório subPortfolioId no contrato, informado no POST de criação (POST .../portfolios/:portfolioId/contracts). Para mover um contrato entre carteiras do mesmo portfolio, atualiza-se o subPortfolioId via PATCH .../contracts/:contractId. Não é permitido subPortfolioId = null — todo contrato sempre pertence a uma carteira. Listar contratos de uma carteira específica: GET .../portfolios/:portfolioId/contracts?subPortfolioId=....Contratos#
| Método | Rota | Arquivo |
|---|
| POST | /v2/companies/:companyId/portfolios/:portfolioId/contracts | Contratos.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts | Contratos.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/export | Contratos.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId | Contratos.md |
| PATCH | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId | Contratos.md |
| PUT | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/status | Contratos.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/history | Contratos.md |
Participantes#
| Método | Rota | Arquivo |
|---|
| POST | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/participants | Participantes.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/participants | Participantes.md |
| PATCH | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/participants/:participantId | Participantes.md |
| DELETE | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/participants/:participantId | Participantes.md |
Colaterais#
| Método | Rota | Arquivo |
|---|
| POST | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/collaterals | Colaterais.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/collaterals | Colaterais.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/collaterals/:collateralId | Colaterais.md |
| PATCH | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/collaterals/:collateralId | Colaterais.md |
| DELETE | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/collaterals/:collateralId | Colaterais.md |
Pagamentos (parcelas)#
| Método | Rota | Arquivo |
|---|
| POST | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/payments | Pagamentos.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/payments | Pagamentos.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/payments/:paymentId | Pagamentos.md |
| PATCH | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/payments/:paymentId | Pagamentos.md |
| PUT | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/payments/:paymentId/status | Pagamentos.md |
Baixas#
| Método | Rota | Arquivo |
|---|
| POST | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/payments/:paymentId/receipts | Baixas.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/payments/:paymentId/receipts | Baixas.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/payments/:paymentId/receipts/:receiptId | Baixas.md |
Clientes#
| Método | Rota | Arquivo |
|---|
| GET | /v2/companies/:companyId/portfolios/:portfolioId/clients | ClientesCarteira.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/clients/:clientId | ClientesCarteira.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/clients/:clientId/contracts | ClientesCarteira.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/clients/:clientId/receivables | ClientesCarteira.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/clients/export | ClientesCarteira.md |
Importação#
| Método | Rota | Arquivo |
|---|
| POST | /v2/companies/:companyId/portfolios/:portfolioId/imports | Importacao.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/imports | Importacao.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/imports/:importId | Importacao.md |
| GET | /v2/companies/:companyId/portfolios/:portfolioId/imports/:importId/errors | Importacao.md |
| POST | /v2/companies/:companyId/portfolios/:portfolioId/imports/:importId/confirm | Importacao.md |
| POST | /v2/companies/:companyId/portfolios/:portfolioId/imports/:importId/cancel | Importacao.md |
11. Jobs Programados#
A atualização automática de status no módulo é feita por jobs programados (scheduler puro). As regras de transição de status executadas pelo scheduler são:| Job | Descrição |
|---|
| Pagamento → OVERDUE | Move pagamentos PENDING ou PARTIALLY_PAID com dueDate ultrapassado para OVERDUE. Recalcula encargos. |
| Pagamento → DEFAULTED | Move pagamentos OVERDUE que ultrapassem o prazo de inadimplência (N dias) configurado no contrato. |
| Contrato → OVERDUE | Move contratos ACTIVE para OVERDUE quando ao menos uma parcela está em OVERDUE ou DEFAULTED. |
| Contrato → DEFAULTED | Move contratos OVERDUE para DEFAULTED conforme regra de inadimplência formal (parcela em DEFAULTED ou prazo configurado no contrato ultrapassado). |
| Cliente → collectionStatus | Avalia o status de cobrança derivado de cada cliente da carteira (ON_TRACK / OVERDUE / CRITICAL) com base nas parcelas e contratos vinculados. Detecta transições e emite eventos de domínio para consumo por outros módulos (ver 7. Informações dos clientes.md). |
Transição manual. A transição para DEFAULTED (parcela e contrato) também pode ser realizada manualmente pelo usuário antes do prazo configurado, quando a operação reconhece a inadimplência formalmente. A transição via job e a manual são complementares.
12. Glossário#
| Termo | Definição |
|---|
| Portfolio | Agrupamento de contratos. Múltiplos por empresa, silos isolados. |
| Carteira | Agrupamento obrigatório dentro de um portfolio, atribuído a um gestor. Todo contrato vive em exatamente uma carteira (nome técnico: SubPortfolio). |
| Template | Tipo base (plataforma) + campos customizados (empresa). Define o formulário. |
| Tipo base | Instrumento jurídico fixo pela plataforma (CPR, CCB, etc.). |
| customFields | Campos definidos pela empresa no template (camada 3). |
| typeSpecificFields | Campos do tipo base fixos pela plataforma (camada 2). |
| Contrato | Instrumento jurídico criado a partir de um template. |
| Participante | Parte do contrato: credor, devedor ou garantidor. Referência a Client. |
| Colateral | Garantia vinculada ao contrato (real ou fidejussória). Sub-recurso 1:N. |
| Pagamento (parcela) | Obrigação com vencimento. Unidade mínima de cobrança. |
| Baixa | Registro de recebimento de um pagamento (PaymentReceipt). |
| paymentDefaults | Config do template que define se encargos são aplicáveis. |
| displayStatus | Referência de tradução do status técnico para label exibido na interface. Derivado no frontend a partir do status retornado pelo backend — não é um campo retornado pela API. Tabela de mapeamento documentada em Contratos.md e Pagamentos.md. |
| taxId | Identificador fiscal do Client. CPF (11 dígitos) ou CNPJ (14 dígitos), armazenado apenas com dígitos (sem máscara). |
| Snapshot | Cópia dos valores no momento de uma operação, para auditoria. |
Modificado em 2026-05-15 21:15:52
