Devedores e credores (Participantes)
Participantes do Contrato — Regras de Negócio
1. Conceito
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.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
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) — avalista2. 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
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
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
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.Quando há múltiplos devedores, exatamente um deve ter
isPrimary = true. Se existe apenas um devedor, ele é automaticamente o principal. Erro: PRIMARY_DEBTOR_REQUIRED.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
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.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
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.O contrato deve pertencer à mesma empresa do Client. Erro:
PARTICIPANT_COMPANY_MISMATCH.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
Se o contrato está em
ACTIVE ou OVERDUE, não é permitido remover o último participante com type = DEBTOR. Erro: CANNOT_REMOVE_LAST_DEBTOR.Se o contrato está em
ACTIVE ou OVERDUE, não é permitido remover o último participante com type = CREDITOR. Erro: CANNOT_REMOVE_LAST_CREDITOR.Remover um participante não exclui nem altera o
Client. O Client permanece na plataforma.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
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.participantId, type, clientId, valores antes/depois quando aplicável, usuário responsável (changedBy) e timestamp (changedAt).Impacto nos indicadores
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
/v2/companies/:companyId/portfolios/:portfolioId/contracts/:contractId/participantsPOST .../participants
contract:update{
"clientId": "client-001",
"type": "DEBTOR",
"isPrimary": true,
"notes": "Devedor principal — tomador do crédito."
}{
"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
}
}CLIENT_NOT_FOUND, PARTICIPANT_ALREADY_EXISTS, PARTICIPANT_COMPANY_MISMATCH, INVALID_PARTICIPANT_TYPE, PARTICIPATION_PERCENTAGE_EXCEEDS_100.GET .../participants
contract:read| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| type | Enum | Não | Filtrar por CREDITOR, DEBTOR, GUARANTOR. |
{
"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
}
}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
isPrimary ou notes de um participante. O type e clientId são imutáveis — para mudar, remover e adicionar novo.contract:update{
"isPrimary": true,
"notes": "Promovido a devedor principal após renegociação."
}DELETE .../participants/:participantId
contract:updatePARTICIPANT_NOT_FOUND, CANNOT_REMOVE_LAST_DEBTOR.6. Impacto nos Demais Módulos
6.1. Contratos
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
}
}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
6.3. Importação
participants no objeto do contrato (clientId + type + isPrimary + opcional participationPercentage + opcional notes).6.4. Templates de contrato
7. Permissões RBAC
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
AVALISTA, FIADOR, INTERVENIENTE_ANUENTE, CODEVEDORA. Na v1, todos são GUARANTOR com distinção via notes.8.2. Granularidade de permissões sobre participantes
contract:update), permitindo separar permissões de "editar dados do contrato" de "adicionar/remover participantes". Avaliar quando demanda operacional surgir.Modificado em 2026-06-02 15:01:21