Contratos — Regras de Negócio

1. Conceito

O Contrato (Contract) é a entidade central do módulo de Gestão de Portfolio. Representa o instrumento jurídico firmado entre as partes de uma operação de crédito a prazo. Todo contrato pertence a exatamente um portfolio e é criado a partir de um template que define sua estrutura de campos.

Cada contrato agrupa um ou mais pagamentos (parcelas) — ver Pagamentos.md — que representam as obrigações de pagamento individuais. O contrato define as condições gerais da operação; os pagamentos definem os vencimentos.

1.1. Modelo orientado a template

O contrato é criado a partir de um ContractTemplate (ver ContractTemplates.md) que combina:

Tipo base fixo pela plataforma (CPR_PHYSICAL, CCB, etc.) — define campos obrigatórios, comportamento de encargos, tipos de pagamento permitidos.

Campos customizados definidos pela empresa — com seções, regras condicionais e cálculos.

O type do contrato é herdado automaticamente do baseType do template. O templateId é imutável após criação.

1.2. Participantes

O contrato não possui um campo clientId direto. Em vez disso, os envolvidos são registrados como participantes tipados — credores, devedores e garantidores — via entidade ContractParticipant (ver Participantes.md). Todo contrato deve ter ao menos um devedor para ser ativado.

1.3. Colaterais

As garantias (colaterais) são registradas como sub-recurso do contrato — cada contrato pode ter zero ou mais colaterais, em relação 1:N. Os colaterais cobrem tanto garantias reais (penhor, hipoteca) quanto fidejussórias (aval, fiança). Ver Colaterais.md.

1.4. Status técnico vs. label visual

O backend devolve apenas o status técnico do contrato (enum: DRAFT, ACTIVE, OVERDUE, etc.). O label exibido na interface (ex.: "Em atraso", "Inadimplente") é derivado pelo frontend a partir desse status, conforme tabela de tradução documentada na seção 2.2 — não é um campo retornado pela API.

2. Estruturas de Dados

2.1. Contract

Campo	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador único.
companyId	UUID	Sim	Empresa.
portfolioId	UUID	Sim	Portfolio ao qual pertence. Resolvido pelo path.
subPortfolioId	UUID	Sim	Carteira à qual o contrato pertence. Obrigatório — todo contrato vive em exatamente uma carteira do seu portfolio. Para mover entre carteiras, sobrescrever o valor via PATCH (não permitido `null`).
templateId	UUID	Sim	Template usado na criação. Imutável.
type	Enum	Sim	Tipo base herdado do template. Imutável. `CPR_PHYSICAL`, `CPR_FINANCIAL`, `INVOICE`, `PURCHASE_SALE_CONTRACT`, `CCB`, `PROMISSORY_NOTE`, `OTHER`.
typeDescription	String	Condicional	Descrição quando `type = OTHER`. Obrigatório nesse caso.
code	String	Sim	Código do contrato (ex: `CT-2024-001`). Único por portfolio. Sugerido automaticamente, editável.
description	String	Sim	Descrição comercial (ex: "CPR Física — Soja Safra 24/25 — Fazenda Tijucal").
value	Decimal	Sim	Valor total em BRL.
currency	Enum	Sim	`BRL`, `USD`, `COMMODITY_LINKED`. Default: `BRL`.
startDate	DateTime	Sim	Data de início de vigência.
endDate	DateTime	Sim	Data de fim de vigência. Deve ser posterior a `startDate`.
paymentPeriodicity	Enum	Não	`MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIANNUAL`, `ANNUAL`, `SINGLE`, `HARVEST`, `CUSTOM`.
periodicityDescription	String	Condicional	Obrigatório quando `paymentPeriodicity = CUSTOM` ou `HARVEST`.
interestRate	Decimal	Condicional	Taxa de juros. Obrigatoriedade condicionada pelo schema do tipo base.
interestRateType	Enum	Condicional	`MONTHLY`, `ANNUAL`. Obrigatório quando `interestRate` informado.
interestCalculationMethod	Enum	Condicional	`SIMPLE`, `COMPOUND`. Default: `SIMPLE`. Obrigatório quando `interestRate` informado.
correctionIndex	Enum	Não	`IGPM`, `IPCA`, `CDI`, `SELIC`, `INPC`, `NONE`. Default: `NONE`.
correctionIndexSpread	Decimal	Condicional	Spread sobre o índice. Permitido apenas quando `correctionIndex != NONE`.
finePercentage	Decimal	Não	Percentual de multa por atraso para pagamentos deste contrato.
dailyInterestPercentage	Decimal	Não	Juros de mora diário para pagamentos deste contrato.
daysToDefault	Integer	Não	Prazo em dias após o vencimento que define a transição automática para `DEFAULTED` (parcela e contrato). Quando omitido, a transição automática não ocorre — `DEFAULTED` só por marcação manual.
typeSpecificFields	Object	Condicional	Campos do tipo base (camada 2). Validados contra schema da plataforma.
customFields	Object	Condicional	Campos customizados do template (camada 3). Validados contra definição do template.
notes	String	Não	Observações livres.
originContractId	UUID	Não	Contrato original quando este é resultado de renegociação.
status	Enum	Sim	`DRAFT`, `ACTIVE`, `OVERDUE`, `CLOSED`, `DEFAULTED`, `RENEGOTIATED`, `CANCELLED`.
createdBy	Object	Sim	Usuário que criou, hidratado: `{ id, name }`. No armazenamento permanece como UUID flat.
createdAt	DateTime (ISO 8601 UTC)	Sim	Data de criação.
updatedAt	DateTime (ISO 8601 UTC)	Sim	Data da última atualização.
closedAt	DateTime (ISO 8601 UTC)	Não	Data de encerramento.
cancelledAt	DateTime (ISO 8601 UTC)	Não	Data de cancelamento.

2.2. Status técnico e label de exibição (referência para frontend)

O backend devolve sempre o campo status técnico (enum). O label exibido na UI é derivado pelo frontend a partir do status, conforme a tabela abaixo. Esta tabela serve de "contrato de tradução" entre back e front — não é um campo retornado pela API.

status (backend)	Label exibida (frontend)
`DRAFT`	"Rascunho"
`ACTIVE`	"Ativo"
`OVERDUE`	"Em atraso"
`DEFAULTED`	"Inadimplente"
`CLOSED`	"Encerrado"
`RENEGOTIATED`	"Renegociado"
`CANCELLED`	"Cancelado"

2.3. ContractHistory

Registra alterações do contrato. Imutável após criação. Cada entrada tem um type que distingue alterações de campos (PATCH) de eventos de participantes.

Campo	Tipo	Descrição
id	UUID	Identificador único.
contractId	UUID	Contrato.
type	Enum	Tipo do evento: `FIELD_CHANGE`, `PARTICIPANT_ADDED`, `PARTICIPANT_REMOVED`.
changedBy	Object	Usuário que executou a alteração, hidratado: `{ id, name }`. No armazenamento permanece como UUID flat.
changedAt	DateTime (ISO 8601 UTC)	Data/hora.
changes	Array	Aplicável quando `type = FIELD_CHANGE`. Lista de `{ field, previousValue, newValue }`. Para `typeSpecificFields`, notação `typeSpecificFields.campo`. Para `customFields`, notação `customFields.key`.
participantEvent	Object	Aplicável quando `type` é evento de participante. Estrutura: `{ participantId, role, clientId }` (campos relevantes conforme o tipo do evento).

Eventos de participante:

type	Payload em `participantEvent`
`PARTICIPANT_ADDED`	`participantId`, `role`, `clientId`
`PARTICIPANT_REMOVED`	`participantId`, `role`, `clientId`

Alterações de status do contrato não são registradas no histórico — rastreadas via closedAt, cancelledAt e logs de transição do scheduler (ver Pagamentos.md para mecânica equivalente em parcelas).

2.4. Ciclo de vida

DRAFT ──► ACTIVE ◄──► OVERDUE ──► DEFAULTED ──► CLOSED / RENEGOTIATED / CANCELLED
              │                              ▲
              └──────────────────────────────┘
              (ACTIVE também pode ir direto a CLOSED / RENEGOTIATED / CANCELLED)
              (OVERDUE volta a ACTIVE quando todas as parcelas em atraso são liquidadas
               antes da inadimplência ser formalizada)
DRAFT ──► CANCELLED

Transição	Pré-condições	Mecanismo
DRAFT → ACTIVE	Ao menos um pagamento vinculado. Ao menos um participante `DEBTOR`.	Manual (via PUT /status).
DRAFT → CANCELLED	Nenhuma.	Manual.
ACTIVE → OVERDUE	Ao menos uma parcela em `OVERDUE` ou `DEFAULTED`.	Automático via job (`Contrato → OVERDUE`).
OVERDUE → ACTIVE	Nenhuma parcela em `OVERDUE` ou `DEFAULTED` (todas regularizadas).	Automático via job.
OVERDUE → DEFAULTED	Ao menos uma parcela em `DEFAULTED`, ou prazo `daysToDefault` do contrato ultrapassado por alguma parcela vencida.	Automático via job (`Contrato → DEFAULTED`) ou marcação manual.
ACTIVE → DEFAULTED	Marcação operacional explícita (raro — geralmente passa por `OVERDUE` antes).	Manual.
ACTIVE/OVERDUE/DEFAULTED → CLOSED	Todos os pagamentos `PAID` ou `CANCELLED`.	Manual (via PUT /status).
ACTIVE/OVERDUE → RENEGOTIATED	`originContractId` informado no body.	Manual.
ACTIVE/OVERDUE → CANCELLED	Nenhuma.	Manual.

3. Regras de Negócio

Template e tipo

RN-CONT-001: Seleção obrigatória de template
Na criação, o usuário seleciona um ContractTemplate. O type é herdado automaticamente do baseType do template. Erro: TEMPLATE_REQUIRED.

RN-CONT-001B: Carteira obrigatória
Todo contrato deve ser criado dentro de uma carteira específica do seu portfolio — o campo subPortfolioId é obrigatório no POST. Não é permitido criar contrato direto no portfolio sem informar carteira. Erro: SUB_PORTFOLIO_REQUIRED. A carteira informada deve pertencer ao mesmo portfolio do contrato e estar ativa.

RN-CONT-002: Template e tipo imutáveis
Os campos templateId e type não podem ser alterados via PATCH. Erros: CONTRACT_TEMPLATE_IMMUTABLE, CONTRACT_TYPE_IMMUTABLE.

RN-CONT-003: Validação de typeSpecificFields
Campos de typeSpecificFields são validados contra o schema do tipo base. Campos REQUIRED ausentes geram erro MISSING_TYPE_SPECIFIC_FIELD. Valores inválidos geram erro INVALID_TYPE_SPECIFIC_FIELD.

RN-CONT-004: Validação de customFields
Campos de customFields são validados contra a definição do template. Campos condicionais ocultos por regra não são validados. Ver regras em ContractTemplates.md.

RN-CONT-005: Juros condicionais ao tipo
Tipos que definem interestRate.visibility = HIDDEN rejeitam o campo se informado. Erro: INTEREST_RATE_NOT_ALLOWED. Tipos com REQUIRED exigem o preenchimento.

Código e datas

RN-CONT-006: Código automático e único
Sugerido no formato CT-{ano}-{sequencial}, único por portfolio. Editável. Erro: CONTRACT_CODE_ALREADY_EXISTS.

RN-CONT-007: Consistência de datas
endDate deve ser posterior a startDate. Erro: INVALID_DATE_RANGE.

Valor e pagamentos

RN-CONT-008: Consistência de valor total
Ao vincular pagamentos (parcelas), o sistema verifica se a soma dos amount.total corresponde ao value do contrato. Divergências geram alerta TOTAL_VALUE_MISMATCH (não bloqueante).

RN-CONT-009: Pré-condição para ativação
DRAFT → ACTIVE requer ao menos um pagamento (parcela) vinculado E ao menos um participante com role = DEBTOR. Erros: CONTRACT_HAS_NO_PAYMENTS, CONTRACT_HAS_NO_DEBTOR.

RN-CONT-010: Pré-condição para encerramento
ACTIVE → CLOSED requer todos os pagamentos PAID ou CANCELLED. Erro: CONTRACT_HAS_OPEN_PAYMENTS.

RN-CONT-011: Transição automática para OVERDUE
Job diário (Contrato → OVERDUE, ver Visão Geral, seção 11) move contratos ACTIVE para OVERDUE quando ao menos uma parcela vinculada está em status OVERDUE ou DEFAULTED. A transição inversa (OVERDUE → ACTIVE) ocorre quando todas as parcelas em atraso são regularizadas antes da formalização da inadimplência.

RN-CONT-012: Transição para DEFAULTED
A transição para DEFAULTED ocorre por uma das três condições:

(a) Ao menos uma parcela do contrato atinge DEFAULTED (parcela em atraso por mais de daysToDefault dias, conforme configuração do contrato);

(b) Job diário (Contrato → DEFAULTED) detecta que o prazo daysToDefault foi ultrapassado para alguma parcela vencida;

(c) Marcação manual pelo usuário via PUT /status, quando a operação reconhece formalmente a inadimplência antes do prazo.

Quando daysToDefault não está configurado no contrato, a transição automática (b) não ocorre — DEFAULTED só por (a) ou (c).

Renegociação

RN-CONT-013: Renegociação
ACTIVE → RENEGOTIATED ou OVERDUE → RENEGOTIATED exige originContractId no body. Erro: MISSING_ORIGIN_CONTRACT_ID. Todos os pagamentos em aberto do contrato original são movidos para RENEGOTIATED simultaneamente.

Imutabilidade

RN-CONT-014: Imutabilidade após encerramento
Contratos CLOSED, DEFAULTED, RENEGOTIATED ou CANCELLED são read-only. Erro: CONTRACT_IMMUTABLE.

RN-CONT-015: value editável com histórico
Após ativação, alterações em value geram registro em ContractHistory e alerta de divergência se aplicável.

Encargos

RN-CONT-016: Encargos definidos no contrato
finePercentage e dailyInterestPercentage são configuração de encargos para os pagamentos (parcelas) deste contrato. Quando não informados, os encargos correspondentes não são calculados. Não existe hierarquia multi-nível — o contrato é a fonte única.

RN-CONT-017: paymentDefaults do template
O schema define paymentDefaults que condiciona se juros, multa e desconto são aplicáveis. Quando interestApplicable = false (ex: CPR_PHYSICAL), juros não são calculados independente da configuração do contrato. O usuário pode sobrescrever no momento da baixa (ver Baixas.md).

Correção monetária

RN-CONT-018: Correção monetária informativa
Quando correctionIndex != NONE, o correctedNominalAmount dos pagamentos é calculado em tempo de leitura (informativo). A correção efetiva é aplicada na baixa (ver Baixas.md).

Exclusão e histórico

RN-CONT-019: Exclusão lógica
Contratos nunca são deletados fisicamente.

RN-CONT-020: Histórico de alterações
Toda alteração via PATCH gera registro em ContractHistory com type = FIELD_CHANGE, incluindo campos de typeSpecificFields e customFields.

4. Padrão de Erros

Códigos de erro específicos

Status	Código	Descrição
404	`CONTRACT_NOT_FOUND`	Contrato não encontrado no portfolio.
409	`CONTRACT_CODE_ALREADY_EXISTS`	Código duplicado no portfolio.
422	`TEMPLATE_REQUIRED`	`templateId` ausente.
422	`SUB_PORTFOLIO_REQUIRED`	`subPortfolioId` ausente ou `null`. Toda criação de contrato exige carteira de destino.
422	`SUB_PORTFOLIO_INACTIVE`	Carteira informada está inativa.
422	`TEMPLATE_INACTIVE`	Template inativo.
422	`CONTRACT_TEMPLATE_IMMUTABLE`	Tentativa de alterar `templateId`.
422	`CONTRACT_TYPE_IMMUTABLE`	Tentativa de alterar `type`.
422	`INVALID_DATE_RANGE`	`endDate` anterior ou igual a `startDate`.
422	`MISSING_TYPE_DESCRIPTION`	`type = OTHER` sem descrição.
422	`MISSING_PERIODICITY_DESCRIPTION`	Periodicidade `CUSTOM`/`HARVEST` sem descrição.
422	`MISSING_INTEREST_RATE_TYPE`	`interestRate` sem `interestRateType`/`interestCalculationMethod`.
422	`INTEREST_RATE_NOT_ALLOWED`	`interestRate` para tipo com `HIDDEN`.
422	`MISSING_TYPE_SPECIFIC_FIELD`	Campo obrigatório do tipo base ausente.
422	`INVALID_TYPE_SPECIFIC_FIELD`	Campo do tipo base com valor inválido.
422	`MISSING_CUSTOM_FIELD`	Campo obrigatório do template ausente.
422	`INVALID_CUSTOM_FIELD_VALUE`	Campo customizado com valor inválido.
422	`INVALID_CORRECTION_INDEX_SPREAD`	Spread sem índice.
422	`CONTRACT_HAS_NO_PAYMENTS`	Ativação sem pagamentos (parcelas).
422	`CONTRACT_HAS_NO_DEBTOR`	Ativação sem devedor.
422	`CONTRACT_HAS_OPEN_PAYMENTS`	Encerramento com pagamentos em aberto.
422	`INVALID_STATUS_TRANSITION`	Transição não permitida.
422	`CONTRACT_IMMUTABLE`	Contrato em status final.
422	`MISSING_ORIGIN_CONTRACT_ID`	Renegociação sem `originContractId`.
422	`INVALID_ORIGIN_CONTRACT`	`originContractId` inválido.
422	`TOTAL_AMOUNT_MISMATCH`	Soma dos pagamentos diverge (alerta).
422	`INVALID_EXPORT_FORMAT`	Formato não suportado.

5. Endpoints

Base path: /v2/companies/:companyId/portfolios/:portfolioId/contracts

POST .../contracts

Cria um contrato em DRAFT. O type é herdado do template. Participantes podem ser incluídos inline ou adicionados depois.

Permissão: contract:create

Request body:

{
  "templateId": "tpl-001",
  "subPortfolioId": "subport-001",
  "code": "CPR-2024-001",
  "description": "CPR Física — Soja Safra 24/25 — Fazenda Tijucal",
  "value": 450000.00,
  "currency": "COMMODITY_LINKED",
  "startDate": "2026-05-13T13:32:32.209+00:00",
  "endDate": "2026-05-13T13:32:32.209+00:00",
  "paymentPeriodicity": "HARVEST",
  "periodicityDescription": "Liquidação integral na colheita da safra 2024/2025.",
  "correctionIndex": "NONE",
  "finePercentage": 2.0,
  "daysToDefault": 30,
  "typeSpecificFields": {
    "crop": "SOYBEAN",
    "harvestSeason": "2024/2025",
    "expectedQuantity": 7500,
    "quantityUnit": "BAGS_60KG",
    "deliveryLocation": "Armazém Cooperativa — Lucas do Rio Verde/MT",
    "deliveryDeadline": "2026-05-13T13:32:32.209+00:00",
    "productPriceAtContract": 120.50,
    "priceUnit": "PER_BAG_60KG"
  },
  "customFields": {
    "variedadeSoja": "TMG7062",
    "areaCultivada": 500.0,
    "produtividadeEstimada": 65.0,
    "cprRegistrada": true,
    "codigoCartorio": "1º Cartório de Lucas do Rio Verde"
  },
  "participants": [
    { "clientId": "client-006", "role": "CREDITOR", "isPrimary": true },
    { "clientId": "client-002", "role": "DEBTOR", "isPrimary": true, "notes": "Devedor principal" },
    { "clientId": "client-004", "role": "GUARANTOR", "isPrimary": true, "notes": "Avalista" }
  ],
  "collaterals": [ 
	  { "category": "REAL", 
		"type": "AGRICULTURAL_PLEDGE", 
		"name": "Penhor safra soja 24/25 — Fazenda Tijucal", 
		"description": "Penhor sobre 500 ha, matrícula 12345 do CRI de Lucas do Rio Verde/MT.", 
		"estimatedValue": 1950000.00, 
		"expirationDate": "2025-06-30", 
		"registrationNumber": "REG-2024-78945", 
		"notes": "Penhor registrado em 15/03/2024." 
		}, 
		{ "category": "FIDEJUSSORY", 
		  "type": "SURETY", 
		  "name": "Aval João Silva", 
		  "description": "Aval pessoal do sócio majoritário da Fazenda Tijucal.", "estimatedValue": 500000.00, 
		  "guarantor": {"id": "client-004"}, 
		  "notes": "Aval limitado a R$ 500.000." } 
		  ],
  "notes": "CPR registrada em cartório."
}

Response 201 Created:

{
  "id": "contract-001",
  "companyId": "company-001",
  "portfolioId": "portfolio-001",
  "subPortfolioId": "subport-001",
  "template": {
    "id": "tpl-001",
    "name": "CPR Soja — Safra"
  },
  "type": "CPR_PHYSICAL",
  "typeDescription": null,
  "code": "CPR-2024-001",
  "description": "CPR Física — Soja Safra 24/25 — Fazenda Tijucal",
  "amounts": { "total": 450000.00, "paid": 250000.00, "open": 200000.00, "overdue": 50000.00 }, 
  "payments": { "total": 12, "paid": 5, "overdue": 1 },
  "currency": "COMMODITY_LINKED",
  "startDate": "2026-05-13T13:32:32.209+00:00",
  "endDate": "2026-05-13T13:32:32.209+00:00",
  "paymentPeriodicity": "HARVEST",
  "periodicityDescription": "Liquidação integral na colheita da safra 2024/2025.",
  "interestRate": null,
  "interestRateType": null,
  "interestCalculationMethod": null,
  "correctionIndex": "NONE",
  "correctionIndexSpread": null,
  "finePercentage": 2.0,
  "dailyInterestPercentage": null,
  "daysToDefault": 30,
  "typeSpecificFields": {
    "crop": "SOYBEAN",
    "harvestSeason": "2024/2025",
    "expectedQuantity": 7500,
    "quantityUnit": "BAGS_60KG",
    "deliveryLocation": "Armazém Cooperativa — Lucas do Rio Verde/MT",
    "deliveryDeadline": "2025-04-15",
    "productPriceAtContract": 120.50,
    "priceUnit": "PER_BAG_60KG"
  },
  "customFields": {
    "variedadeSoja": "TMG7062",
    "areaCultivada": 500.0,
    "produtividadeEstimada": 65.0,
    "producaoTotalEstimada": 32500,
    "cprRegistrada": true,
    "codigoCartorio": "1º Cartório de Lucas do Rio Verde"
  },
  "notes": "CPR registrada em cartório.",
  "status": "DRAFT",
  "originContractId": null,
  "primaryDebtor": {
    "client": {
      "id": "client-002",
      "name": "Fazenda Tijucal",
      "taxId": "12345678000190"
    }
  },
  "participants": [
    { "clientId": "client-006", "type": "CREDITOR", "isPrimary": true, "name": "Thiago", "taxId": "12314124" },
    { "clientId": "client-002", "type": "DEBTOR", "isPrimary": true, "notes": "Devedor principal", "name": "Pedro", "taxId": "12314124"  },
    { "clientId": "client-004", "type": "GUARANTOR", "isPrimary": true, "notes": "Avalista", "name": "João", "taxId": "12314124"  }
  ],
  "participantsSummary": {
    "creditors": 1,
    "debtors": 1,
    "guarantors": 1
  },
  "collaterals": { 
	  "items": [ 
		  { "id": "col-001", 
			"category": "REAL", 
			"type": "AGRICULTURAL_PLEDGE", 
			"typeDescription": null, 
			"name": "Penhor safra soja 24/25 — Fazenda Tijucal", 
			"description": "Penhor sobre 500 ha, matrícula 12345 do CRI de Lucas do Rio Verde/MT.", 
			"estimatedValue": 1950000.00, 
			"expirationDate": "2025-06-30", 
			"registrationNumber": "REG-2024-78945", 
			"guarantor": null, 
			"attachments": [], 
			"notes": "Penhor registrado em 15/03/2024.", 
			"createdBy": 
				{ "id": "8c3f1a2b-...", 
				"name": "João Silva" }, 
			"createdAt": "2025-03-17T09:00:00.000+00:00", 
			"updatedAt": "2025-03-17T09:00:00.000+00:00" }, 
		{ "id": "col-002", 
		  "category": "FIDEJUSSORY", 
		  "type": "SURETY", 
		  "typeDescription": null, 
		  "name": "Aval João Silva", 
		  "description": "Aval pessoal do sócio majoritário da Fazenda Tijucal.", 
		  "estimatedValue": 500000.00, 
		  "expirationDate": null, 
		  "registrationNumber": null, 
		  "guarantor": 
			  { "id": "client-004", 
			    "name": "João Silva", 
			    "taxId": "12345678900" }, 
		  "attachments": [], 
		  "notes": "Aval limitado a R$ 500.000.", 
		  "createdBy": 
			  { "id": "8c3f1a2b-...", 
			  "name": "João Silva" }, 
		  "createdAt": "2025-03-17T09:00:00.000+00:00", 
		  "updatedAt": "2025-03-17T09:00:00.000+00:00" } ], 
	"summary": 
		{ "total": 2, 
		  "real": 1, 
		  "fidejussory": 1, 
		  "value": 2450000.00 }},
  "createdBy": {
    "id": "8c3f1a2b-...",
    "name": "João Silva"
  },
  "createdAt": "2025-03-17T09:00:00.000+00:00",
  "updatedAt": "2025-03-17T09:00:00.000+00:00",
  "closedAt": null,
  "cancelledAt": null
}

O campo producaoTotalEstimada foi calculado automaticamente pela regra ON_CALCULATE do template (área × produtividade).

Os campos dentro de customFields serão os campos apresentados dentro de "Informações Adicionais" nos detalhes do contrato.

GET .../contracts

Lista contratos do subPortfolio.

Permissão: contract:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
`search`	String	Não	Busca por `code`, `description` ou nome do devedor principal.
`status`	Enum (multi)	Não	Filtrar por status.
`type`	Enum (multi)	Não	Filtrar por tipo.
`templateId`	UUID	Não	Filtrar por template.
`clientId`	UUID	Não	Filtrar contratos onde o Client é participante (qualquer role).
`startDate`	Datetime (ISO)	Não	`startDate >=`.
`endDate`	Datetime (ISO)	Não	`endDate <=`.
`crop`	Enum	Não	Filtrar por cultura (dentro de `typeSpecificFields.crop`).
`harvestSeason`	String	Não	Filtrar por safra.
`orderBy`	Enum	Não	Ordenação: `code`, `startDate`, `endDate`, `value`, `createdAt`. Default: `createdAt`.
`order`	Enum	Não	`asc` ou `desc`. Default: `desc`.
`offset`	Integer	Não	Default: 0.
`limit`	Integer	Não	Default: 20. Máximo: 100.

Response 200 OK:

{
  "items": [
    {
      "id": "contract-001",
      "code": "CPR-2024-001",
      "type": "CPR_PHYSICAL",
      "template": {
        "id": "tpl-001",
        "name": "CPR Soja — Safra"
      },
      "description": "CPR Física — Soja Safra 24/25 — Fazenda Tijucal",
      "amounts": {
        "value": 450000.00,
        "open": 50000.00,
        "overdue": 30000.00
      },
      "currency": "COMMODITY_LINKED",
      "startDate": "2024-03-01",
      "endDate": "2025-04-30",
      "status": "OVERDUE",
      "primaryDebtor": {
        "client": {
          "id": "client-002",
          "name": "Fazenda Tijucal",
          "taxId": "12345678000190"
        }
      },
      "participantsSummary": {
        "creditors": 1,
        "debtors": 1,
        "guarantors": 1
      },
      "collaterals": {
        "total": 2,
        "value": 2450000.00
      },
      "payments": {
        "total": 3,
        "paid": 1,
        "pending": 2,
        "overdue": 0
      },
      "typeSpecificFields": {
        "crop": "SOYBEAN",
        "harvestSeason": "2024/2025"
      },
      "createdAt": "2025-03-17T09:00:00.000+00:00",
      "updatedAt": "2025-03-17T09:00:00.000+00:00"
    }
  ],
  "nextPage": false
}

Na listagem, typeSpecificFields retorna apenas campos resumidos (crop, harvestSeason, invoiceNumber, ccbNumber, noteNumber — conforme tipo). customFields não é retornado na listagem.

GET .../contracts/:contractId

Detalhe completo.

Permissão: contract:read

Response 200 OK: Mesmo formato do POST response com todos os campos. Inclui participants completo (array com todos os participantes e dados do Client), typeSpecificFields completo e customFields completo.

PATCH .../contracts/:contractId

Atualiza dados. Permitido para contratos em status = DRAFT, ACTIVE ou OVERDUE. Os campos templateId, type e portfolioId são imutáveis.

Permissão: contract:update

Campos editáveis: subPortfolioId, code, description, value, currency, startDate, endDate, paymentPeriodicity, periodicityDescription, interestRate, interestRateType, interestCalculationMethod, correctionIndex, correctionIndexSpread, finePercentage, dailyInterestPercentage, daysToDefault, typeSpecificFields, customFields, notes.

Movimentação entre carteiras. Para mover o contrato para outra carteira do mesmo portfolio, enviar subPortfolioId com o ID da nova carteira no body. Não é permitido subPortfolioId = null — todo contrato sempre pertence a uma carteira. Permissão adicional necessária: portfolio:assign_contract (ver Carteiras.md).

Request body (exemplo):

{
  "description": "CPR Física — Soja Safra 24/25 — Revisado",
  "subPortfolioId": "subport-001",
  "daysToDefault": 45,
  "typeSpecificFields": {
    "expectedQuantity": 8000,
    "deliveryDeadline": "2025-05-01"
  },
  "customFields": {
    "areaCultivada": 600.0,
    "produtividadeEstimada": 65.0
  },
  "notes": "Aditivo assinado em 20/03/2025."
}

Response 200 OK: Contrato atualizado completo.

Erros: CONTRACT_IMMUTABLE, CONTRACT_TEMPLATE_IMMUTABLE, CONTRACT_TYPE_IMMUTABLE, CONTRACT_CODE_ALREADY_EXISTS, INVALID_DATE_RANGE, MISSING_TYPE_SPECIFIC_FIELD, INVALID_TYPE_SPECIFIC_FIELD, MISSING_CUSTOM_FIELD, INVALID_CUSTOM_FIELD_VALUE, CONTRACT_PORTFOLIO_MISMATCH (quando subPortfolioId não pertence ao portfolio do contrato).

PUT .../contracts/:contractId/status

Substitui o status do contrato. Usado para transições manuais (ativação, encerramento, renegociação, cancelamento, marcação manual de inadimplência).

Permissão: contract:update

Request body — ativação:

{
  "status": "ACTIVE"
}

Request body — marcação manual de inadimplência:

{
  "status": "DEFAULTED",
  "reason": "Cliente comunicou impossibilidade de pagamento."
}

Request body — renegociação:

{
  "status": "RENEGOTIATED",
  "originContractId": "contract-new-001",
  "reason": "Renegociação de prazo após frustração de safra."
}

Response 200 OK:

{
  "id": "contract-001",
  "status": "ACTIVE",
  "updatedAt": "2025-03-17T10:00:00.000+00:00"
}

Erros: INVALID_STATUS_TRANSITION, CONTRACT_HAS_NO_PAYMENTS, CONTRACT_HAS_NO_DEBTOR, CONTRACT_HAS_OPEN_PAYMENTS, MISSING_ORIGIN_CONTRACT_ID, INVALID_ORIGIN_CONTRACT.

GET .../contracts/:contractId/history

Histórico de alterações e eventos do contrato. Inclui mudanças de campo (PATCH) e eventos de participantes (adição, remoção).

Permissão: contract:read

Query params: Paginação padrão (offset / limit).

Response 200 OK:

{
  "items": [
    {
      "id": "hist-001",
      "contractId": "contract-001",
      "type": "FIELD_CHANGE",
      "changedBy": {
        "id": "8c3f1a2b-...",
        "name": "João Silva"
      },
      "changedAt": "2025-03-20T14:00:00.000+00:00",
      "changes": [
        { "field": "typeSpecificFields.expectedQuantity", "previousValue": 7500, "newValue": 8000 },
        { "field": "customFields.areaCultivada", "previousValue": 500.0, "newValue": 600.0 },
        { "field": "notes", "previousValue": "CPR registrada em cartório.", "newValue": "Aditivo assinado em 20/03/2025." }
      ]
    },
    {
      "id": "hist-002",
      "contractId": "contract-001",
      "type": "PARTICIPANT_ADDED",
      "changedBy": {
        "id": "8c3f1a2b-...",
        "name": "João Silva"
      },
      "changedAt": "2025-03-22T10:00:00.000+00:00",
      "participantEvent": {
        "participantId": "part-005",
        "role": "GUARANTOR",
        "clientId": "client-007"
      }
    },
    {
      "id": "hist-003",
      "contractId": "contract-001",
      "type": "PARTICIPANT_ADDED",
      "changedBy": {
        "id": "8c3f1a2b-...",
        "name": "João Silva"
      },
      "changedAt": "2025-03-22T10:00:00.000+00:00",
      "participantEvent": {
        "participantId": "part-005",
        "role": "GUARANTOR",
        "clientId": "client-007"
      }
    }
  ],
  "nextPage": false
}

GET .../contracts/export

Exporta listagem em CSV ou XLSX. Mesmos filtros da listagem + format.

Permissão: contract:read

Colunas incluem campos comuns, typeSpecificFields aplicáveis ao tipo, devedor principal, garantias (nomes concatenados) e contadores.

6. Permissões RBAC

Resource	Domínio	Actions
`contract`	TENANT	`create`, `read`, `update`

A gestão de participantes utiliza o mesmo resource contract — contract:update cobre adição/remoção de participantes.

7. Referências cruzadas

Módulo	Como se relaciona com Contratos
`Participantes.md`	Credores, devedores, garantidores do contrato. `clientId` foi substituído por participantes.
`Pagamentos.md`	Parcelas/obrigações de pagamento vinculadas ao contrato.
`Baixas.md`	Registros de liquidação dos pagamentos.
`Colaterais.md`	Garantias reais e fidejussórias como sub-recurso do contrato (1:N).
`ContractTemplates.md`	Template que define a estrutura do formulário e comportamento.
`Carteiras.md`	Portfolio e carteira aos quais o contrato pertence. Ambos obrigatórios.

Contratos

Contratos — Regras de Negócio#

1. Conceito#

1.1. Modelo orientado a template#

1.2. Participantes#

1.3. Colaterais#

1.4. Status técnico vs. label visual#

2. Estruturas de Dados#

2.1. Contract#

2.2. Status técnico e label de exibição (referência para frontend)#

2.3. ContractHistory#

2.4. Ciclo de vida#

3. Regras de Negócio#

Template e tipo#

Código e datas#

Valor e pagamentos#

Renegociação#

Imutabilidade#

Encargos#

Correção monetária#

Exclusão e histórico#

4. Padrão de Erros#

Códigos de erro específicos#

5. Endpoints#

POST .../contracts#

GET .../contracts#

GET .../contracts/:contractId#

PATCH .../contracts/:contractId#

PUT .../contracts/:contractId/status#

GET .../contracts/:contractId/history#

GET .../contracts/export#

6. Permissões RBAC#

7. Referências cruzadas#

Contratos — Regras de Negócio

1. Conceito

1.1. Modelo orientado a template

1.2. Participantes

1.3. Colaterais

1.4. Status técnico vs. label visual

2. Estruturas de Dados

2.1. Contract

2.2. Status técnico e label de exibição (referência para frontend)

2.3. ContractHistory

2.4. Ciclo de vida

3. Regras de Negócio

Template e tipo

Código e datas

Valor e pagamentos

Renegociação

Imutabilidade

Encargos

Correção monetária

Exclusão e histórico

4. Padrão de Erros

Códigos de erro específicos

5. Endpoints

POST .../contracts

GET .../contracts

GET .../contracts/:contractId

PATCH .../contracts/:contractId

PUT .../contracts/:contractId/status

GET .../contracts/:contractId/history

GET .../contracts/export

6. Permissões RBAC

7. Referências cruzadas