Participantes do Contrato — Regras de Negócio

1. Conceito

O Participante (ContractParticipant) representa uma parte envolvida em um contrato — credor, devedor ou garantidor. Um contrato pode ter múltiplos participantes de cada tipo, refletindo a realidade de operações de crédito no agro onde é comum ter múltiplos devedores solidários, avalistas e até credores compartilhados.

Todos os participantes são entidades Client existentes na plataforma. O módulo de Gestão de Portfolio não cria Clients — quando o Client informado não existe, o sistema retorna erro orientando o usuário a cadastrar pelo módulo de Clientes do AgRisk antes de adicionar o participante.

1.1. Empresa como participante

A própria empresa pode figurar como participante do contrato — em geral no papel de CREDITOR (caso comum) ou em outros papéis quando aplicável. Para isso, a empresa possui um Client espelho associado (isCompany = true), criado automaticamente na ativação do módulo, que a representa em participações de contrato. Esse Client espelho é referenciado normalmente via clientId nos endpoints — não há tratamento polimórfico.

1.2. Papéis e cardinalidade

Papel	Código	Cardinalidade	Descrição
Credor	`CREDITOR`	1..N	A entidade que concede o crédito. Obrigatório — pode ser a própria empresa (via Client espelho, ver 1.1) ou outro Client. Suporta múltiplos credores em operações de cessão, cofinanciamento ou securitização.
Devedor	`DEBTOR`	1..N	A entidade que assume a obrigação de pagamento. Obrigatório — ao menos um devedor é necessário para ativar o contrato. Múltiplos devedores são suportados (devedor solidário).
Garantidor	`GUARANTOR`	0..N	A entidade que oferece garantia pessoal (aval, fiança) à operação. Opcional. Diferente da garantia real, que é registrada como `Colateral` (ver `Colaterais.md`).
Testemunha

1.3. Modelo

Contrato CPR-2024-001
├── Credor: Cooperativa AgroVale (CREDITOR, primary)
├── Credor: Banco do Brasil (CREDITOR)
├── Devedor: Fazenda Tijucal (DEBTOR, primary)
├── Devedor: Fazenda Rio Verde (DEBTOR) — devedor solidário
├── Garantidor: João Silva (GUARANTOR) — avalista
└── Garantidor: Maria Silva (GUARANTOR) — avalista

2. Estruturas de Dados

2.1. ContractParticipant

Campo	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador único do vínculo participante-contrato.
contractId	UUID	Sim	Contrato ao qual o participante está vinculado.
clientId	UUID	Sim	Referência ao `Client` na plataforma (existente — não é criado automaticamente).
type	Enum	Sim	Papel no contrato: `CREDITOR`, `DEBTOR`, `GUARANTOR`.
isPrimary	Boolean	Sim	Se este é o participante principal do seu papel. Apenas um participante por `type` pode ser `primary` em cada contrato. Default: `false`.
notes	String	Não	Observações sobre a participação (ex: "Devedor solidário", "Avalista até R$ 500.000").
addedBy	UUID	Sim	Usuário que adicionou o participante.
addedAt	DateTime (ISO 8601 UTC)	Sim	Data e hora da adição.
createdAt	DateTime (ISO 8601 UTC)	Sim	Data de criação do registro.

2.2. Campos enriquecidos na resposta

Nos endpoints de listagem e detalhe, cada participante retorna dados do Client num objeto aninhado para contexto:

Campo	Tipo	Descrição
`client.id`	UUID	Mesmo valor de `clientId` (espelhado dentro do objeto para conveniência da UI).
`client.name`	String	Nome/Razão social do Client.
`client.taxId`	String	CPF (11 dígitos) ou CNPJ (14 dígitos) — apenas dígitos, sem máscara.
`client.email`	String	E-mail. `null` se não cadastrado.
`client.phone`	String	Telefone — apenas dígitos, sem máscara. `null` se não cadastrado.
`client.isCompany`	Boolean	`true` quando o Client é o espelho da própria empresa (ver seção 1.1). `false` para Clients regulares.

2.3. Mensagem de erro para Client não encontrado

Quando o clientId informado não existe na plataforma, o sistema retorna erro orientando o usuário:

{
  "error": "CLIENT_NOT_FOUND",
  "message": "O cliente informado não foi encontrado na plataforma. Cadastre o cliente pelo módulo de Clientes do AgRisk antes de adicioná-lo como participante do contrato.",
  "details": {
    "clientId": "client-999"
  }
}

3. Regras de Negócio

Obrigatoriedade

RN-PART-001: Ao menos um devedor
Todo contrato deve ter ao menos um participante com type = DEBTOR. Não é possível ativar um contrato (DRAFT → ACTIVE) sem devedor. Erro: CONTRACT_HAS_NO_DEBTOR.

RN-PART-002: Devedor principal obrigatório
Quando há múltiplos devedores, exatamente um deve ter isPrimary = true. Se existe apenas um devedor, ele é automaticamente o principal. Erro: PRIMARY_DEBTOR_REQUIRED.

RN-PART-003: Ao menos um credor obrigatório
Todo contrato deve ter ao menos um participante com type = CREDITOR. O credor pode ser a própria empresa (via Client espelho com isCompany = true) ou outro Client (banco, cooperativa, fundo, securitizadora, etc.). A UI deve pré-selecionar o Client espelho da empresa como credor padrão no formulário de criação do contrato, permitindo ao usuário trocar ou adicionar outros credores. Erro na ativação: CONTRACT_HAS_NO_CREDITOR.

Criação de Client

RN-PART-004: Client deve existir na plataforma
Todos os participantes devem referenciar um Client já cadastrado na plataforma via clientId. Não é possível criar Clients automaticamente pelo módulo de Gestão de Portfolio. Quando o Client não é encontrado, o sistema retorna erro CLIENT_NOT_FOUND com mensagem orientando o usuário a realizar o cadastro pelo módulo de Clientes do AgRisk antes de adicionar o participante.

RN-PART-005: Client espelho da empresa
Quando o Client espelho da empresa (isCompany = true) é usado como participante (geralmente como CREDITOR), aplicam-se as mesmas regras dos demais Clients — não há tratamento especial. O Client espelho é criado uma única vez na ativação do módulo para a empresa.

Unicidade e consistência

RN-PART-006: Mesmo Client, papéis diferentes
Um Client pode ter múltiplos papéis no mesmo contrato — por exemplo, ser devedor E garantidor. Porém, o par (contractId, clientId, type) deve ser único. Erro: PARTICIPANT_ALREADY_EXISTS.

RN-PART-007: Mesma empresa
O contrato deve pertencer à mesma empresa do Client. Erro: PARTICIPANT_COMPANY_MISMATCH.

RN-PART-008: Um primary por type por contrato
Apenas um participante pode ter isPrimary = true para cada type em cada contrato. Ao marcar um novo participante como primary, o anterior é automaticamente desmarcado.

Remoção

RN-PART-009: Não pode remover último devedor de contrato ativo
Se o contrato está em ACTIVE ou OVERDUE, não é permitido remover o último participante com type = DEBTOR. Erro: CANNOT_REMOVE_LAST_DEBTOR.

RN-PART-010: Não pode remover último credor de contrato ativo
Se o contrato está em ACTIVE ou OVERDUE, não é permitido remover o último participante com type = CREDITOR. Erro: CANNOT_REMOVE_LAST_CREDITOR.

RN-PART-011: Remoção não afeta o Client
Remover um participante não exclui nem altera o Client. O Client permanece na plataforma.

RN-PART-012: Remoção de primary promove o próximo
Ao remover um participante isPrimary = true, se houver outro participante do mesmo type, o sistema promove automaticamente o mais antigo (addedAt mais antigo) como primary.

Histórico

RN-PART-013: Histórico de alterações de participantes
Adições, remoções e alterações de percentual de participação são registradas como eventos no ContractHistory (ver Contratos.md, seção 2.3):

PARTICIPANT_ADDED — quando um participante é adicionado.

PARTICIPANT_REMOVED — quando um participante é removido.

Cada evento registra participantId, type, clientId, valores antes/depois quando aplicável, usuário responsável (changedBy) e timestamp (changedAt).

Impacto nos indicadores

RN-PART-014: Devedor principal define os indicadores do cliente
Nos módulos de Clientes na Carteira e no PortfolioSummary, os indicadores de inadimplência e valores em aberto são atribuídos ao devedor principal (type = DEBTOR, isPrimary = true). Devedores secundários aparecem nos mesmos relatórios, mas a consolidação primária é pelo devedor principal.

4. Padrão de Erros

Status	Código	Descrição
404 Not Found	`PARTICIPANT_NOT_FOUND`	Participante não encontrado no contrato.
404 Not Found	`CLIENT_NOT_FOUND`	Client informado não existe na plataforma. Cadastre pelo módulo de Clientes.
409 Conflict	`PARTICIPANT_ALREADY_EXISTS`	Client já é participante com este papel noTcontrato.
422 Unprocessable Entity	`CONTRACT_HAS_NO_DEBTOR`	Contrato sem devedor na ativação.
422 Unprocessable Entity	`CONTRACT_HAS_NO_CREDITOR`	Contrato sem credor na ativação.
422 Unprocessable Entity	`PRIMARY_DEBTOR_REQUIRED`	Múltiplos devedores sem um primary definido.
422 Unprocessable Entity	`CANNOT_REMOVE_LAST_DEBTOR`	Remoção do último devedor em contrato ativo/em atraso.
422 Unprocessable Entity	`CANNOT_REMOVE_LAST_CREDITOR`	Remoção do último credor em contrato ativo/em atraso.
422 Unprocessable Entity	`PARTICIPANT_COMPANY_MISMATCH`	Client não pertence à mesma empresa.
422 Unprocessable Entity	`INVALID_PARTICIPANT_TYPE`	Type informado não é válido.

5. Endpoints

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

POST .../participants

Adiciona um participante ao contrato. O Client deve existir na plataforma.

Permissão: contract:update

Request body — devedor principal:

{
  "clientId": "client-001",
  "type": "DEBTOR",
  "isPrimary": true,
  "notes": "Devedor principal — tomador do crédito."
}

Response 201 Created:

{
  "id": "part-001",
  "contractId": "contract-001",
  "clientId": "client-001",
  "type": "DEBTOR",
  "isPrimary": true,
  "participationPercentage": null,
  "notes": "Devedor principal — tomador do crédito.",
  "createdBy": "user-001",
  "createdAt": "2025-03-17T09:00:00.000+00:00",
  "createdAt": "2025-03-17T09:00:00.000+00:00",
  "client": {
    "id": "client-001",
    "name": "Fazenda Tijucal",
    "taxId": "12345678000190",
    "email": "contato@fazendatijucal.com.br",
    "phone": "11999999999",
    "isCompany": false
  }
}

Erros: CLIENT_NOT_FOUND, PARTICIPANT_ALREADY_EXISTS, PARTICIPANT_COMPANY_MISMATCH, INVALID_PARTICIPANT_TYPE, PARTICIPATION_PERCENTAGE_EXCEEDS_100.

GET .../participants

Lista participantes do contrato, agrupados por papel.

Permissão: contract:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
type	Enum	Não	Filtrar por `CREDITOR`, `DEBTOR`, `GUARANTOR`.

Response 200 OK:

{
  "items": [
    {
      "id": "part-001",
      "contractId": "contract-001",
      "clientId": "client-001",
      "type": "CREDITOR",
      "isPrimary": true,
      "participationPercentage": 100.0,
      "notes": null,
      "createdBy": "user-001",
      "createdAt": "2025-03-17T09:00:00.000+00:00",
      "client": {
        "id": "client-001",
        "name": "Cooperativa AgroVale",
        "taxId": "01234567000100",
        "email": "financeiro@agrovale.com.br",
        "phone": "6733334444",
        "isCompany": false
      }
    },
    {
      "id": "part-002",
      "contractId": "contract-001",
      "clientId": "client-002",
      "type": "DEBTOR",
      "isPrimary": true,
      "participationPercentage": null,
      "notes": "Devedor principal.",
      "createdBy": "user-001",
      "createdAt": "2025-03-17T09:00:00.000+00:00",
      "client": {
        "id": "client-002",
        "name": "Fazenda Tijucal",
        "taxId": "12345678000190",
        "email": "contato@fazendatijucal.com.br",
        "phone": "11999999999",
        "isCompany": false
      }
    },
    {
      "id": "part-003",
      "contractId": "contract-001",
      "clientId": "client-003",
      "type": "DEBTOR",
      "isPrimary": false,
      "participationPercentage": null,
      "notes": "Devedor solidário.",
      "createdBy": "user-001",
      "createdAt": "2025-03-17T09:02:00.000+00:00",
      "client": {
        "id": "client-003",
        "name": "Fazenda Rio Verde",
        "taxId": "98765432000110",
        "email": null,
        "phone": "67988887777",
        "isCompany": false
      }
    },
    {
      "id": "part-004",
      "contractId": "contract-001",
      "clientId": "client-004",
      "type": "GUARANTOR",
      "isPrimary": true,
      "participationPercentage": null,
      "notes": "Avalista — sócio majoritário.",
      "createdBy": "user-001",
      "createdAt": "2025-03-17T09:05:00.000+00:00",
      "client": {
        "id": "client-004",
        "name": "João Silva",
        "taxId": "12345678900",
        "email": "joao@email.com",
        "phone": "11999990000",
        "isCompany": false
      }
    }
  ],
  "summary": {
    "creditors": 1,
    "debtors": 2,
    "guarantors": 1,
    "total": 4
  }
}

O summary é retornado junto com a lista para os cards de contagem na interface. Não paginado — o número de participantes por contrato é pequeno o suficiente para retornar todos de uma vez (sem offset/limit/nextPage).

PATCH .../participants/:participantId

Atualiza isPrimary ou notes de um participante. O type e clientId são imutáveis — para mudar, remover e adicionar novo.

Permissão: contract:update

Request body — promoção a primary:

{
  "isPrimary": true,
  "notes": "Promovido a devedor principal após renegociação."
}

Response 200 OK: Participante atualizado com dados do Client.

DELETE .../participants/:participantId

Remove o participante do contrato. Não afeta o Client.

Permissão: contract:update

Response 204 No Content

Erros: PARTICIPANT_NOT_FOUND, CANNOT_REMOVE_LAST_DEBTOR.

6. Impacto nos Demais Módulos

6.1. Contratos

O contrato não possui campo clientId direto — todos os envolvidos vêm do modelo de participantes. O detalhe e a listagem de contratos (ver Contratos.md) trazem o devedor principal e contadores resumidos:

{
  "primaryDebtor": {
    "client": {
      "id": "client-002",
      "name": "Fazenda Tijucal",
      "taxId": "12345678000190"
    }
  },
  "summary": {
    "creditors": 1,
    "debtors": 2,
    "guarantors": 1
  }
}

O filtro clientId na listagem de contratos (GET /portfolios/:portfolioId/contracts?clientId=...) busca contratos onde o Client informado é participante em qualquer type.

6.2. Clientes na Carteira

O módulo de Clientes na Carteira (quando implementado) passará a considerar todos os types: um Client que aparece como devedor em 3 contratos e garantidor em 2 terá ambas as visões consolidadas no seu perfil.

6.3. Importação

O payload de importação inclui participantes:

Na API: array participants no objeto do contrato (clientId + type + isPrimary + opcional participationPercentage + opcional notes).

6.4. Templates de contrato

O template não define participantes — participantes são adicionados por contrato, independente do template. O schema do template não inclui campos de participante.

7. Permissões RBAC

A gestão de participantes utiliza o resource contract — não possui resource próprio. As permissões contract:update cobrem adição e remoção de participantes, e contract:read cobre a listagem.

8. Roadmap

8.1. Tipo detalhado de garantidor

Subtipos de garantidor: AVALISTA, FIADOR, INTERVENIENTE_ANUENTE, CODEVEDORA. Na v1, todos são GUARANTOR com distinção via notes.

8.2. Granularidade de permissões sobre participantes

Resource RBAC próprio para participantes (em vez de usar contract:update), permitindo separar permissões de "editar dados do contrato" de "adicionar/remover participantes". Avaliar quando demanda operacional surgir.

Devedores e credores (Participantes)

Participantes do Contrato — Regras de Negócio#

1. Conceito#

1.1. Empresa como participante#

1.2. Papéis e cardinalidade#

1.3. Modelo#

2. Estruturas de Dados#

2.1. ContractParticipant#

2.2. Campos enriquecidos na resposta#

2.3. Mensagem de erro para Client não encontrado#

3. Regras de Negócio#

Obrigatoriedade#

Criação de Client#

Unicidade e consistência#

Remoção#

Histórico#

Impacto nos indicadores#

4. Padrão de Erros#

5. Endpoints#

POST .../participants#

GET .../participants#

PATCH .../participants/:participantId#

DELETE .../participants/:participantId#

6. Impacto nos Demais Módulos#

6.1. Contratos#

6.2. Clientes na Carteira#

6.3. Importação#

6.4. Templates de contrato#

7. Permissões RBAC#

8. Roadmap#

8.1. Tipo detalhado de garantidor#

8.2. Granularidade de permissões sobre participantes#

Participantes do Contrato — Regras de Negócio

1. Conceito

1.1. Empresa como participante

1.2. Papéis e cardinalidade

1.3. Modelo

2. Estruturas de Dados

2.1. ContractParticipant

2.2. Campos enriquecidos na resposta

2.3. Mensagem de erro para Client não encontrado

3. Regras de Negócio

Obrigatoriedade

Criação de Client

Unicidade e consistência

Remoção

Histórico

Impacto nos indicadores

4. Padrão de Erros

5. Endpoints

POST .../participants

GET .../participants

PATCH .../participants/:participantId

DELETE .../participants/:participantId

6. Impacto nos Demais Módulos

6.1. Contratos

6.2. Clientes na Carteira

6.3. Importação

6.4. Templates de contrato

7. Permissões RBAC

8. Roadmap

8.1. Tipo detalhado de garantidor

8.2. Granularidade de permissões sobre participantes