Colaterais — Regras de Negócio

1. Conceito

O Colateral (ContractCollateral) é o registro de uma garantia oferecida como lastro dentro de uma operação de crédito. Colaterais existem como sub-recurso do contrato — cada contrato pode ter zero ou mais colaterais vinculados, em uma relação 1:N.

O colateral cobre dois tipos de garantia:

Garantia real — lastro sobre um ativo: penhor de safra, alienação fiduciária de bem móvel ou imóvel, hipoteca, seguro agrícola, etc.

Garantia fidejussória — lastro sobre uma pessoa: aval, fiança. Neste caso, o avalista/fiador também pode aparecer como participante do contrato com type = GUARANTOR. As duas entidades são complementares: o participante GUARANTOR registra quem está garantindo; o colateral registra os termos da garantia (valor, condições, documentos).

O colateral é descritivo: registra tipo, descrição, valor estimado e documentação. Não possui ciclo de vida próprio — acompanha o contrato ao qual pertence.

1.1. Modelo

Contrato CPR-2024-001
├── Colateral: Penhor safra soja — 500 ha (garantia real)
├── Colateral: Alienação fiduciária — Trator John Deere (garantia real)
├── Colateral: Aval João Silva — até R$ 500.000 (garantia fidejussória)
└── Colateral: Seguro agrícola — apólice XYZ (garantia real)

1.2. Colateral vs. Participante GUARANTOR

Aspecto	Participante GUARANTOR	Colateral fidejussório
O que registra	Quem é o garantidor (Client)	Os termos da garantia (valor, condições, docs)
Onde vive	`ContractParticipant`	`ContractCollateral`
Obrigatório	Não	Não
Relação	Client ↔ Contract	Dentro do Contract

É válido ter um participante GUARANTOR sem colateral correspondente (apenas registra quem é o avalista, sem detalhar os termos) e também ter um colateral fidejussório sem participante GUARANTOR (registra a garantia mas o avalista não foi adicionado como participante formal).

2. Estruturas de Dados

2.1. ContractCollateral

Campo	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador único.
contractId	UUID	Sim	Contrato ao qual pertence.
companyId	UUID	Sim	Empresa. Desnormalizado.
category	Enum	Sim	Categoria: `REAL` (garantia real) ou `FIDEJUSSORY` (garantia fidejussória).
type	Enum	Sim	Tipo específico. Ver seção 2.2.
typeDescription	String	Condicional	Descrição quando `type = OTHER`. Obrigatório nesse caso.
name	String	Sim	Nome identificador (ex: "Penhor safra soja 24/25 — Fazenda Tijucal").
description	String	Não	Descrição detalhada (imóvel, área, matrícula, condições).
estimatedValue	Decimal	Não	Valor estimado em BRL.
expirationDate	Date (ISO `YYYY-MM-DD`)	Não	Data de validade, quando aplicável.
registrationNumber	String	Não	Número de registro em cartório, órgão ou sistema.
guarantor	Object	Não	Referência ao `Client` garantidor apresentando informações do cliente (nome, id e taxId) . Usado para colaterais fidejussórios (aval/fiança). Permite cruzar com participante `GUARANTOR`. Quando informado, o response enriquece com o objeto `guarantor` aninhado (ver seção 2.3).
attachments	Array<AttachmentRef>	Não	Documentos vinculados (matrículas, laudos, apólices).
notes	String	Não	Observações livres.
createdBy	Object	Sim	Usuário que criou, hidratado no contrato de API: `{ id, name }`. No armazenamento (doc 12) permanece UUID flat.
createdAt	DateTime (ISO 8601 UTC)	Sim	Data de criação.
updatedAt	DateTime (ISO 8601 UTC)	Sim	Data da última atualização.
deletedAt	DateTime (ISO 8601 UTC)	Não	Data do soft-delete (ver RN-COL-008). `null` para colaterais ativos.

2.2. Tipos de colateral

Garantia real (`category = REAL`)

Código	Nome	Descrição
`AGRICULTURAL_PLEDGE`	Penhor agrícola	Penhor sobre safra, produção ou estoque.
`CROP_LIEN`	Penhor de safra futura	Penhor sobre produção ainda não colhida.
`CHATTEL_MORTGAGE`	Alienação fiduciária (móvel)	Alienação de veículos, máquinas, equipamentos.
`FIDUCIARY_REAL_ESTATE`	Alienação fiduciária (imóvel)	Alienação fiduciária sobre imóvel.
`REAL_ESTATE_MORTGAGE`	Hipoteca	Hipoteca sobre imóvel rural ou urbano.
`INSURANCE`	Seguro	Apólice de seguro (agrícola, crédito, etc.).
`OTHER`	Outro (real)	Demais garantias reais. Requer `typeDescription`.

Garantia fidejussória (`category = FIDEJUSSORY`)

Código	Nome	Descrição
`SURETY`	Aval	Aval pessoal.
`BAIL`	Fiança	Fiança de terceiro.
`BANK_GUARANTEE`	Fiança bancária	Carta de fiança de instituição financeira.
`OTHER`	Outro (fidejussório)	Demais. Requer `typeDescription`.

2.3. Guarantor enriquecido na resposta

Quando o colateral é fidejussório e tem guarantor.clientId preenchido, o response inclui um objeto guarantor aninhado com dados do Client para contexto:

Campo	Tipo	Descrição
`guarantor.id`	UUID	Mesmo valor de `guarantorClientId`.
`guarantor.name`	String	Nome/Razão social do Client garantidor.
`guarantor.taxId`	String	CPF (11 dígitos) ou CNPJ (14 dígitos) — apenas dígitos, sem máscara.

Quando guarantor.clientId é null, o objeto guarantor também é null.

2.4. AttachmentRef

Referência a um arquivo vinculado ao colateral. Os metadados do arquivo vivem dentro do objeto file; quem fez o upload é hidratado para { id, name }.

{
  "file": {
    "id": "file-uuid-001",
    "name": "matricula_fazenda_tijucal.pdf",
    "size": 245000,
    "mimeType": "application/pdf"
  },
  "uploadedBy": {
    "id": "8c3f1a2b-...",
    "name": "João Silva"
  },
  "uploadedAt": "2025-03-17T09:00:00.000+00:00"
}

Campo	Tipo	Descrição
`file`	Object	Metadados do arquivo no storage.
`file.id`	UUID	Referência ao arquivo no storage (S3/blob). Não é o conteúdo, é o ponteiro.
`file.name`	String	Nome do arquivo.
`file.size`	Integer	Tamanho em bytes.
`file.mimeType`	String	Tipo MIME (ex: `application/pdf`, `image/jpeg`).
`uploadedBy`	Object	Usuário que fez o upload, hidratado: `{ id, name }`.
`uploadedBy.id`	UUID	ID do usuário.
`uploadedBy.name`	String	Nome do usuário, hidratado pelo backend.
`uploadedAt`	DateTime (ISO 8601 UTC)	Data/hora do upload.

3. Regras de Negócio

RN-COL-001: Vínculo com contrato
Todo colateral pertence a um contrato. Criado como sub-recurso via /contracts/:contractId/collaterals.

RN-COL-002: Sem limite de colaterais
Um contrato pode ter zero ou N colaterais. Não há limite.

RN-COL-003: Tipo OTHER requer descrição
Quando type = OTHER, o campo typeDescription é obrigatório. Erro: MISSING_TYPE_DESCRIPTION.

RN-COL-004: Category define tipos disponíveis
O type selecionado deve ser compatível com a category informada. Ex: SURETY só é válido com category = FIDEJUSSORY. Erro: COLLATERAL_TYPE_CATEGORY_MISMATCH.

RN-COL-005: guarantor.clientId opcional
Para colaterais fidejussórios, o guarantor.clientId permite vincular ao Client que é o avalista/fiador. Deve referenciar um Client existente na empresa. Erro: CLIENT_NOT_FOUND. O campo é informativo — não cria vínculo automático como participante GUARANTOR.

RN-COL-006: Edição livre
Todos os campos podem ser editados a qualquer momento, independente do status do contrato.

RN-COL-007: Exclusão
Colaterais podem ser removidos individualmente. A remoção não afeta o contrato.

RN-COL-008: Exclusão lógica
Colaterais nunca são deletados fisicamente. Soft-delete via deletedAt.

4. Padrão de Erros

Status	Código	Descrição
404	`COLLATERAL_NOT_FOUND`	Colateral não encontrado no contrato.
422	`MISSING_TYPE_DESCRIPTION`	`type = OTHER` sem descrição.
422	`COLLATERAL_TYPE_CATEGORY_MISMATCH`	Tipo incompatível com a categoria.
404	`CLIENT_NOT_FOUND`	`guarantor.clientId` não encontrado.

5. Endpoints

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

POST .../collaterals

Cria um colateral no contrato.

Permissão: contract:update

Request body — garantia real:

{
  "category": "REAL",
  "type": "AGRICULTURAL_PLEDGE",
  "name": "Penhor safra soja 24/25 — Fazenda Tijucal",
  "description": "Penhor agrícola sobre safra de soja em 500 hectares, matrícula 12345 do CRI de Lucas do Rio Verde/MT.",
  "estimatedValue": 1950000.00,
  "expirationDate": "2025-03-17T09:00:00.000+00:00",
  "registrationNumber": "REG-2024-78945",
  "notes": "Penhor registrado em 15/03/2024."
}

Request body — garantia fidejussória:

{
  "category": "FIDEJUSSORY",
  "type": "SURETY",
  "name": "Aval João Silva",
  "description": "Aval pessoal do sócio majoritário da Fazenda Tijucal.",
  "estimatedValue": 500000.00,
  "guarantor": [ 
	  {
	  "clientId: "1234asddas"
	  }
	],
  "notes": "Aval limitado a R$ 500.000."
}

Response 201 Created — garantia real (sem garantidor):

{
  "id": "col-001",
  "contractId": "contract-001",
  "companyId": "company-001",
  "category": "REAL",
  "type": "AGRICULTURAL_PLEDGE",
  "typeDescription": null,
  "name": "Penhor safra soja 24/25 — Fazenda Tijucal",
  "description": "Penhor agrícola sobre safra de soja em 500 hectares, matrícula 12345 do CRI de Lucas do Rio Verde/MT.",
  "estimatedValue": 1950000.00,
  "expirationDate": "2025-06-30",
  "registrationNumber": "REG-2024-78945",
  "guarantor": [],
  "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",
  "deletedAt": null
}

Response 201 Created — garantia fidejussória (com garantidor enriquecido):

{
  "id": "col-002",
  "contractId": "contract-001",
  "companyId": "company-001",
  "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": [{
    "clientId": "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:30:00.000+00:00",
  "updatedAt": "2025-03-17T09:30:00.000+00:00",
  "deletedAt": null
}

GET .../collaterals

Lista colaterais do contrato.

Permissão: contract:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
category	Enum	Não	`REAL` ou `FIDEJUSSORY`.
type	Enum (multi)	Não	Filtrar por tipo.

Response 200 OK:

{
  "items": [
    {
      "id": "col-001",
      "contractId": "contract-001",
      "category": "REAL",
      "type": "AGRICULTURAL_PLEDGE",
      "typeDescription": null,
      "name": "Penhor safra soja 24/25 — Fazenda Tijucal",
      "estimatedValue": 1950000.00,
      "expirationDate": "2025-06-30",
      "registrationNumber": "REG-2024-78945",
      "guarantor": [],
      "attachmentsCount": 2,
      "createdAt": "2025-03-17T09:00:00.000+00:00"
    },
    {
      "id": "col-002",
      "contractId": "contract-001",
      "category": "FIDEJUSSORY",
      "type": "SURETY",
      "typeDescription": null,
      "name": "Aval João Silva",
      "estimatedValue": 500000.00,
      "expirationDate": null,
      "registrationNumber": null,
      "guarantor": [{
        "id": "client-004",
        "name": "João Silva",
        "taxId": "12345678900"
      }],
      "attachmentsCount": 0,
      "createdAt": "2025-03-17T09:30:00.000+00:00"
    }
  ],
  "summary": {
    "total": 2,
    "real": 1,
    "fidejussory": 1,
    "value": 2450000.00
  }
}

O summary retorna as contagens (total, real, fidejussory) e o valor estimado total (totalEstimated) para exibição em cards. Não paginado — o número de colaterais por contrato é pequeno o suficiente para retornar todos de uma vez (sem offset/limit/nextPage).

GET .../collaterals/:collateralId

Detalhe completo com attachments.

Permissão: contract:read

Response 200 OK: Mesmo formato do POST response com attachments completo.

PATCH .../collaterals/:collateralId

Atualiza dados do colateral. Todos os campos editáveis.

Permissão: contract:update

Request body:

{
  "estimatedValue": 2100000.00,
  "notes": "Valor atualizado conforme reavaliação."
}

Response 200 OK: Colateral atualizado.

DELETE .../collaterals/:collateralId

Remove o colateral do contrato (soft-delete).

Permissão: contract:update

Response 204 No Content

6. Impacto nos Demais Módulos

6.1. Contratos

O detalhe do contrato (ver Contratos.md) inclui contador resumido collateralsCount no nível raiz. Para o breakdown completo (por categoria, valor estimado total), o frontend consulta o endpoint GET /collaterals deste módulo, que retorna o array items + objeto summary com as contagens.

Esta separação evita inflar o payload do contrato com dados que só interessam quando o usuário abre a aba de garantias.

6.2. Participantes

O participante GUARANTOR e o colateral fidejussório são complementares. O campo guarantor no colateral permite cruzar as duas entidades, mas não há vínculo automático — são gerenciados independentemente.

7. Roadmap

7.1. Busca de colaterais duplicados

Futuramente, o sistema poderá alertar quando um mesmo ativo (identificado por registro/matrícula) estiver sendo usado como colateral em múltiplos contratos da mesma empresa. Conforme discutido, isso pode ser implementado via regra de negócio com chave de duplicação, sem necessidade de entidade separada.

7.2. Colaterais com campos customizados (templates)

Templates de colateral por tipo, similar aos templates de contrato — com campos para coordenadas geográficas, área total, cultura específica, etc.

7.3. Consulta de garantias prestadas

Tela consolidada mostrando todas as garantias prestadas pelo client em todos os contratos da empresa.

Colaterais

Colaterais — Regras de Negócio#

1. Conceito#

1.1. Modelo#

1.2. Colateral vs. Participante GUARANTOR#

2. Estruturas de Dados#

2.1. ContractCollateral#

2.2. Tipos de colateral#

Garantia real (category = REAL)#

Garantia fidejussória (category = FIDEJUSSORY)#

2.3. Guarantor enriquecido na resposta#

2.4. AttachmentRef#

3. Regras de Negócio#

4. Padrão de Erros#

5. Endpoints#

POST .../collaterals#

GET .../collaterals#

GET .../collaterals/:collateralId#

PATCH .../collaterals/:collateralId#

DELETE .../collaterals/:collateralId#

6. Impacto nos Demais Módulos#

6.1. Contratos#

6.2. Participantes#

7. Roadmap#

7.1. Busca de colaterais duplicados#

7.2. Colaterais com campos customizados (templates)#

7.3. Consulta de garantias prestadas#

Colaterais — Regras de Negócio

1. Conceito

1.1. Modelo

1.2. Colateral vs. Participante GUARANTOR

2. Estruturas de Dados

2.1. ContractCollateral

2.2. Tipos de colateral

Garantia real (`category = REAL`)

Garantia fidejussória (`category = FIDEJUSSORY`)

2.3. Guarantor enriquecido na resposta

2.4. AttachmentRef

3. Regras de Negócio

4. Padrão de Erros

5. Endpoints

POST .../collaterals

GET .../collaterals

GET .../collaterals/:collateralId

PATCH .../collaterals/:collateralId

DELETE .../collaterals/:collateralId

6. Impacto nos Demais Módulos

6.1. Contratos

6.2. Participantes

7. Roadmap

7.1. Busca de colaterais duplicados

7.2. Colaterais com campos customizados (templates)

7.3. Consulta de garantias prestadas