1. Clientes
AgRisk
  • AgRisk
    • Documentação
      • AgRisk
    • API - AgRisk
      • Login
        • Atualizar token
        • Autenticar usuário
      • Consultas
        • Solicitar consulta
        • Listar consultas
        • Listar consultas da empresa
      • Listagem de Produtos
        • Listar produtos
      • Clientes
        • Listar clientes
        • Criar cliente
        • Listar contadores de clientes
        • Deletar cliente
        • Listar contadores de clientes no grupo
      • Dados Cadastrais
        • Buscar dados cadastrais
      • Grupos
        • Listar grupos
        • Criar grupo
        • Listar clientes em grupo
        • Criar cliente em grupo
        • Atualizar nome do grupo
        • Deletar grupo
        • Inserir cliente em grupo
        • Remover cliente de grupo
      • Análise de Matrícula
        • Listar análises de matrículas
        • Criar análise de matrícula
        • Buscar análise de matrícula
        • Deletar análise de matrícula
      • Contatos
        • Listar contatos
      • BNDES
        • Listar BNDES
      • Boa Vista
        • Listar Boa Vista
      • Compliance
        • Listar compliance
      • CPRs
        • Listar CPRs
        • Buscar CPR
      • Grupo econômico
        • familiar
          • Listar grupo econômico
          • Listar grupo familiar
      • Imposto de Renda
        • Criar ativo financeiro
        • Listar ativos financeiros
        • Criar dívida
        • Importar dívidas
        • Listar dívidas
        • Atualizar dívida
        • Deletar dívida
        • Criar ativo móvel
        • Listar ativos móveis
        • Atualizar ativo móvel
        • Deletar ativo móvel
        • Criar imóvel urbano
        • Listar imóveis urbanos
        • Atualizar imóvel urbano
        • Deletar imóvel urbano
      • Judicial
        • Listar processos judiciais
        • Buscar processo judicial
        • Solicitar análise por IA
      • Protestos
        • Listar protestos
      • Imóveis Rurais - Simples
        • Criar imóvel rural
        • Listar imóveis rurais
        • Buscar imóvel rural
      • Endividamento
        • Listar SCR (endividamento)
      • Imóveis Rurais - CAR
        • Listar CAR (Cadastro Ambiental Rural)
        • Buscar CAR
        • Deletar CAR
        • Criar CAR
        • Download certidão CAR
      • QUOD
        • Buscar Quod
      • Restritivo Nacional
        • Buscar Restritivo Nacional
      • Veicular
        • Buscar Patrimônio Veicular
      • Sintegra
        • Listar Sintegras
    • APIs
    • Raiz
    • Esquemas
      • API Requests
        • ClientResponse
  • AgFlow
    • 🇧🇷 Português
      • Aprovação
        • Aprovação — Visão Geral
        • Consultar configuração de aprovação
        • Criar configuração de aprovação
        • Atualizar configuração de aprovação
        • Adicionar regra de aprovação
        • Atualizar regra de aprovação
        • Remover configuração de aprovação
        • Consultar aprovação do card
        • Registrar voto de aprovação
        • Atualizar voto de aprovação
      • Fluxo
        • Fluxo — Visão Geral
        • Verificar disponibilidade
        • Criar fluxo
        • Listar fluxos
        • Obter fluxo
        • Atualizar fluxo
        • Remover fluxo
        • Adicionar usuário ao fluxo
        • Remover usuário do fluxo
        • Listar caminhos de campos dinâmicos
      • Consulta a Bureau
        • Consulta a Bureau — Visão Geral
        • Obter configuração de consulta a bureau
        • Criar configuração de consulta a bureau
        • Atualizar configuração de consulta a bureau
      • Campos
        • Campos — Visão Geral
        • Listar campos da fase
        • Atualizar campos da fase
        • Atualizar regras de campos da fase
      • Conversa
        • Conversa — Visão Geral
        • Obter configuração de conversa
        • Criar configuração de conversa
        • Remover configuração de conversa
      • Motores
        • Motores — Visão Geral
        • Consultar resultado do motor de decisão do card
        • Executar motor de decisão no card
        • Consultar inputs do motor de crédito para o card
        • Consultar resultado do motor de crédito do card
        • Executar motor de crédito no card
        • Consultar configuração do motor de decisão
        • Criar configuração do motor de decisão
        • Atualizar configuração do motor de decisão
        • Remover configuração do motor de decisão
        • Consultar detalhe da configuração do motor de crédito
        • Criar configuração do motor de crédito
        • Listar configurações do motor de crédito do flow
        • Listar políticas de crédito aplicáveis a um card
        • Atualizar configuração do motor de crédito
        • Remover configuração do motor de crédito
      • Parecer
        • Parecer — Visão Geral
        • Consultar configuração do parecer técnico
        • Criar configuração do parecer técnico
        • Atualizar configuração do parecer técnico
        • Consultar parecer registrado no card
        • Registrar parecer no card
        • Atualizar parecer no card
      • Formulário Inicial
        • Formulário Inicial — Visão Geral
        • Criar formulário inicial
        • Definir regras condicionais do formulário
        • Atualizar metadados do formulário
        • Consultar formulário inicial
        • Consultar formulário público
        • Atualizar campos do formulário
        • Remover formulário inicial
      • Filtros
        • Filtros — Visão Geral
        • Listar filtros salvos
        • Criar filtro salvo
        • Atualizar filtro salvo
        • Buscar cards do flow
        • Busca global de cards
      • AgRisk
        • AgRisk — Visão Geral
        • Listar produtos de consulta AgRisk
      • Gatilhos
        • Gatilhos — Visão Geral
        • Listar gatilhos do flow
        • Criar gatilho
        • Atualizar gatilho
        • Remover gatilho
        • Listar gatilhos da fase
      • Autenticação
        • Autenticação — Visão Geral
        • Autenticar usuário
      • Mensageria
        • Mensageria — Visão Geral
        • Configurar telefone
        • Consultar configuração de mensageria
        • Criar configuração de mensageria
        • Atualizar configuração de mensageria
        • Criar regras de mensageria
        • Atualizar regra de mensageria
        • Remover configuração de mensageria
      • Empresas e Papéis
        • Empresas e Papéis — Visão Geral
        • Listar usuários da empresa
        • Listar papéis da empresa
        • Atualizar papel
        • Listar catálogo de permissões
        • Criar papel
        • Gerar URL de upload do logotipo
        • Gerar URL de download do logotipo
        • Atribuir papéis a um usuário
      • Documentos
        • Documentos — Visão Geral
        • Criar configuração de geração automática de documento
        • Remover configuração de geração automática de documento
        • Consultar configuração de geração automática de documento
        • Atualizar configuração de geração automática de documento
        • Consultar campos para geração do documento
        • Gerar documento a partir de template
        • Consultar template por ID
        • Listar templates do card
        • Ativar template
        • Criar template de documento
        • Remover template
        • Listar templates
        • Definir campos do template
        • Configurar regras condicionais do template
        • Atualizar arquivo do template
      • Cards
        • Cards — Visão Geral
        • Listar cards de uma fase
        • Mover card de fase
        • Criar card
        • Listar cards do flow
        • Criar card via link público
        • Buscar cards
        • Obter card
        • Atualizar card
        • Atualizar responsável do card
        • Atualizar campos via link público
        • Atualizar campos de fase do card
        • Remover cards em lote
        • Atualizar Ficha Cadastral do card
        • Obter responsável do card
        • Listar etiquetas do card
        • Listar campos de uma fase do card
        • Listar campos de uma fase do card (link público)
        • Obter histórico do card
        • Listar clientes do card
        • Criar comentário no card
        • Listar comentários do card
        • Remover comentário do card
        • Listar anexos do card
        • Cadastrar anexo no card
        • Remover anexo do card
        • Remover vínculo do anexo com campo de fase
        • Adicionar membros ao grupo do card
        • Remover membro do grupo do card
      • Configuração de Cliente
        • Configuração de Cliente — Visão Geral
        • Obter configuração de cliente por empresa
        • Criar configuração de cliente
        • Atualizar configuração de cliente
        • Obter configuração de cliente
        • Remover configuração de cliente
        • Listar seções
        • Criar seções
        • Obter seção
        • Atualizar seção
        • Atualizar seção parcialmente
        • Remover seção
        • Listar campos
        • Criar campos
        • Obter campo
        • Atualizar campo
        • Atualizar campo parcialmente
        • Remover campo
        • Listar regras
        • Criar regra
        • Obter regra
        • Atualizar regra
        • Atualizar regra parcialmente
        • Remover regra
      • Fase
        • Fase — Visão Geral
        • Criar ação de fase
        • Criar fase
        • Remover ação de fase
        • Remover fase
        • Listar ações da fase
        • Listar fases
        • Atualizar ação de fase
        • Atualizar fase
    • 🇺🇸 English
      • Phase
        • Phase — Overview
        • Create phase action
        • Create phase
        • Delete phase action
        • Delete phase
        • List phase actions
        • List phases
        • Update phase action
        • Update phase
      • Approval
        • Approval — Overview
        • Get approval configuration
        • Create approval configuration
        • Update approval configuration
        • Add approval rule
        • Update approval rule
        • Delete approval configuration
        • Get card approval
        • Register approval vote
        • Update approval vote
      • Flow
        • Flow — Overview
        • Health check
        • Create flow
        • List flows
        • Get flow
        • Update flow
        • Delete flow
        • Add user to flow
        • Remove user from flow
        • List dynamic field paths
      • Bureau Query
        • Bureau Query — Overview
        • Get bureau query configuration
        • Create bureau query configuration
        • Update bureau query configuration
      • Fields
        • Fields — Overview
        • List phase fields
        • Update phase fields
        • Update phase field rules
      • Engines
        • Engines — Overview
        • Get card decision engine result
        • Run card decision engine
        • Get card credit engine inputs
        • Get card credit engine result
        • Run card credit engine
        • Get decision engine configuration
        • Create decision engine configuration
        • Update decision engine configuration
        • Delete decision engine configuration
        • Get credit engine configuration detail
        • Create credit engine configuration
        • List flow credit engine configurations
        • List credit policies applicable to a card
        • Update credit engine configuration
        • Delete credit engine configuration
      • Conversation
        • Conversation — Overview
        • Get conversation configuration
        • Create conversation configuration
        • Delete conversation configuration
      • Opinion
        • Opinion — Overview
        • Get opinion configuration
        • Create opinion configuration
        • Update opinion configuration
        • Get card opinion
        • Create card opinion
        • Update card opinion
      • Start Form
        • Start Form — Overview
        • Create start form
        • Set start form conditional rules
        • Update start form metadata
        • Get start form
        • Get public start form
        • Update start form fields
        • Delete start form
      • Filters
        • Filters — Overview
        • List saved filters
        • Create saved filter
        • Update saved filter
        • Search flow cards
        • Search cards across flows
      • AgRisk
        • AgRisk — Overview
        • List AgRisk query products
      • Triggers
        • Triggers — Overview
        • List flow triggers
        • Create trigger
        • Update trigger
        • Delete trigger
        • List phase triggers
      • Authentication
        • Authentication — Overview
        • Authenticate user
      • Messaging
        • Messaging — Overview
        • Configure phone
        • Get messaging config
        • Create messaging config
        • Update messaging config
        • Create messaging rules
        • Update messaging rule
        • Delete messaging config
      • Companies & Roles
        • Companies & Roles — Overview
        • List company users
        • List company roles
        • Update role
        • List permissions catalog
        • Create role
        • Generate company logo upload URL
        • Generate company logo download URL
        • Assign roles to a user
      • Documents
        • Documents — Overview
        • Create automatic document configuration
        • Delete automatic document configuration
        • Get automatic document configuration
        • Update automatic document configuration
        • Get fields for document generation
        • Generate document from template
        • Get template by ID
        • List card templates
        • Activate template
        • Create document template
        • Delete template
        • List templates
        • Set template fields
        • Configure template conditional rules
        • Update template file
      • Cards
        • Cards — Overview
        • List cards in a phase
        • Move card to another phase
        • Create card
        • List flow cards
        • Create card via public link
        • Search cards
        • Get card
        • Update card
        • Update card assignee
        • Update fields via public link
        • Update card phase fields
        • Delete cards in bulk
        • Update card registration record
        • Get card assignee
        • List card labels
        • List card phase fields
        • List card phase fields (public link)
        • Get card history
        • List card clients
        • Create card comment
        • List card comments
        • Delete card comment
        • List card attachments
        • Register card attachment
        • Delete card attachment
        • Delete attachment's phase-field link
        • Add members to card group
        • Remove card group member
      • Client Configuration
        • Client Configuration — Overview
        • Get client configuration by company
        • Create client configuration
        • Update client configuration
        • Get client configuration
        • Delete client configuration
        • List sections
        • Create sections
        • Get section
        • Update section
        • Partially update section
        • Delete section
        • List fields
        • Create fields
        • Get field
        • Update field
        • Partially update field
        • Delete field
        • List rules
        • Create rule
        • Get rule
        • Update rule
        • Partially update rule
        • Delete rule
    • 💼 Visão de Negócio
      • Fase
      • Fluxo
      • Campos — Visão de Negócio
      • Aprovação
      • Parecer
      • Motores
      • Empresas e Papéis
      • Gatilhos
      • Conversa
      • Documentos
      • Mensageria
      • Filtros
      • Autenticação
      • Configuração de Cliente
      • Cards
      • AgRisk
      • Formulário Inicial
      • Consulta a Bureau
    • 💼 Business Overview
      • Phase
      • Flow
      • Approval
      • Fields — Business Overview
      • Opinion
      • Engines
      • Companies & Roles
      • Documents
      • Triggers
      • Messaging
      • Conversation
      • Filters
      • Authentication
      • Client Configuration
      • Cards
      • AgRisk
      • Start Form
      • Bureau Query
  • Portfolio
    • Documentação
      • Empresa
      • Gestão de portfolio
        • Análise geral
        • Dicionário de campos base (Necessário validar)
        • [Desatualizado]Fluxo de funcionamento
        • Carteiras
          • Gestão da carteira
        • Contratos
          • Contratos
          • Template Contratos
        • Pagamentos
          • Pagamentos
        • Baixas
          • Baixas
        • Clientes
          • Devedores e credores (Participantes)
          • Informações dos clientes
        • Importação de dados
          • Importação de dados
        • Garantia
          • Colaterais
      • Gestão de Cobrança
        • Régua de cobrança
          • Regras da régua por empresa
        • Atividades
          • Regras das Atividades
  1. Clientes

Informações dos clientes

Clientes na Carteira — Regras de Negócio#

1. Conceito#

O módulo de Clientes na Carteira oferece uma visão agregada dos clientes devedores dentro do contexto da Gestão de Portfolio. Não cria uma entidade nova — opera como uma camada de leitura sobre a entidade Client já existente na plataforma, enriquecida com indicadores financeiros calculados a partir dos contratos e títulos vinculados ao cliente.
Um cliente aparece na carteira automaticamente quando possui ao menos um contrato com status != CANCELLED na empresa. Não existe vínculo manual — a presença é derivada da existência de contratos. Se todos os contratos de um cliente forem cancelados, ele deixa de aparecer na listagem da carteira.

1.1. Visão 360° do cliente#

A Visão 360° é a tela de detalhe do cliente no contexto da carteira. Agrega em um único lugar:
Dados cadastrais — lidos diretamente da entidade Client existente (nome, taxId, e-mail, telefone, endereço).
Resumo financeiro — indicadores calculados: quantidade de contratos, valor total, valor em aberto, status de cobrança.
Contratos — listagem dos contratos do cliente na carteira.
Títulos/Faturas — listagem transversal de todos os títulos do cliente, independente do contrato.

1.2. Status de cobrança#

O status de cobrança (status no contexto deste módulo) é um campo derivado que classifica a situação do cliente na carteira com base nos status das parcelas e contratos vinculados a ele. É calculado em tempo de leitura e exibido na listagem e no detalhe do cliente.
A regra de derivação reusa os status já existentes nas entidades Contract e ContractPayment — não há configuração de limiar de dias separada para este módulo. As transições para OVERDUE e DEFAULTED ocorrem no nível das parcelas e contratos, conforme regras do contrato (ver Visão Geral, seções 5 e 11).

2. Estruturas de Dados#

2.1. PortfolioClientSummary (objeto calculado)#

Retornado na listagem de clientes na carteira. Todos os campos são derivados — nenhum é armazenado como entidade.
Origem dos dados. Os indicadores são calculados em tempo de leitura via agregação sobre as entidades Contract (filtradas pelos participantes com role DEBTOR correspondente ao cliente) e ContractPayment (das parcelas dos contratos desse cliente). Não existe entidade PortfolioClient armazenada — é uma view derivada.
Estrutura do response (objeto aninhado):
{
  "client": {
    "id": "a3f1c2d4-0000-0000-0000-000000000010",
    "name": "Fazenda Tijucal",
    "taxId": "12345678000190"
  },
  "contracts": {
    "total": 3,
    "active": 2,
    "value": 730000.00,
    "open": 85000.00,
    "overdue": 85000.00,
    "overduePayments": 2,
    "maxOverdueDays": 45
  },
  "status": "OVERDUE"
}
Campos:
CampoTipoDescrição
client.idUUIDReferência ao Client existente.
client.nameStringNome/Razão social do cliente.
client.taxIdStringCPF (11 dígitos) ou CNPJ (14 dígitos) — apenas dígitos, sem máscara.
contracts.totalIntegerQuantidade de contratos do cliente na carteira (todos os status exceto CANCELLED).
contracts.activeIntegerQuantidade de contratos com status = ACTIVE.
contracts.valueDecimalSoma do value de todos os contratos não cancelados.
contracts.openDecimalSoma do amounts.remaining de todos os títulos em aberto (PENDING, PARTIALLY_PAID, OVERDUE).
contracts.overdueDecimalSoma do amounts.remaining dos títulos com status = OVERDUE.
contracts.overduePaymentsIntegerQuantidade de títulos com status = OVERDUE.
contracts.maxOverdueDaysIntegerMaior número de dias em atraso entre todos os títulos OVERDUE do cliente. 0 se nenhum título em atraso.
statusEnumStatus de cobrança derivado: ON_TRACK, OVERDUE, CRITICAL. Ver seção 2.2.

2.2. Status de cobrança (collectionStatus)#

O status é derivado dos status das parcelas e contratos do cliente. Não há configuração de limiar de dias separada neste módulo — as transições para OVERDUE e DEFAULTED já estão definidas no nível das parcelas e contratos (regra do contrato, ver Visão Geral, seção 11).
status (do cliente)Condição
ON_TRACKCliente sem nenhuma parcela em OVERDUE ou DEFAULTED e sem nenhum contrato em OVERDUE ou DEFAULTED.
OVERDUECliente com ao menos uma parcela ou contrato em OVERDUE (e nenhum em DEFAULTED).
CRITICALCliente com ao menos uma parcela ou contrato em DEFAULTED.
CRITICAL prevalece sobre OVERDUE quando ambos coexistem — basta um DEFAULTED em parcela ou contrato para o cliente ser classificado como crítico.
Tradução do status para exibição (referência para frontend). O backend devolve sempre o status técnico. O frontend deriva o label conforme a tabela abaixo:
status (backend)Label exibida (frontend)
ON_TRACK"Em dia"
OVERDUE"Em atraso"
CRITICAL"Crítico"

2.3. PortfolioClientDetail (objeto calculado)#

Retornado no endpoint de detalhe. Estrutura aninhada com dados cadastrais completos e indicadores detalhados.
Estrutura do response:
{
  "client": {
    "id": "a3f1c2d4-0000-0000-0000-000000000010",
    "name": "Fazenda Tijucal",
    "taxId": "98765432000110",
    "email": "contato@fazendatijucal.com.br",
    "phone": "11999999999",
    "address": "Fazenda Horizonte, Km 15, Zona Rural - Ribeirão Preto/SP"
  },
  "contracts": {
    "total": 3,
    "active": 2,
    "closed": 1,
    "defaulted": 0,
    "value": 730000.00,
    "open": 85000.00,
    "overdue": 85000.00,
    "paid": 645000.00,
    "overduePayments": 2,
    "pendingPayments": 3,
    "paidPayments": 8,
    "maxOverdueDays": 45,
    "averageOverdueDays": 30,
    "items": { [
        {
          "key": "CPR_PHYSICAL",
          "total": 1,
          "value": 450000.00,
          "open": 0.00
        },
        {
          "key": "INVOICE",
          "total": 2,
          "value": 280000.00,
          "open": 85000.00
        }
      ]
    }
  },
  "status": "OVERDUE"
}
Campos adicionais (em relação ao Summary):
CampoTipoDescrição
client.emailStringE-mail do cliente. null se não cadastrado.
client.phoneStringTelefone do cliente (apenas dígitos, sem máscara). null se não cadastrado.
client.addressStringEndereço completo. null se não cadastrado.
contracts.closedIntegerContratos encerrados.
contracts.defaultedIntegerContratos inadimplentes.
contracts.paidDecimalValor total já pago (soma de baixas confirmadas).
contracts.pendingPaymentsIntegerTítulos pendentes (não vencidos).
contracts.paidPaymentsIntegerTítulos pagos.
contracts.averageOverdueDaysIntegerMédia de dias em atraso dos títulos OVERDUE.
contracts.groupedByObjectBreakdown dos contratos por dimensão. Chave é a dimensão de agrupamento (ex: type). Valor é array de buckets. Permite expansão futura para outras dimensões (status, subPortfolio, etc.) sem mudar a forma do payload.
contracts.groupedBy.type[]ArrayBreakdown dos contratos agrupados por tipo. Um item por valor distinto de type que o cliente possui em contratos não cancelados.
contracts.groupedBy.type[].keyEnumValor do tipo do contrato (ex: CPR_PHYSICAL, INVOICE). Os valores possíveis seguem o enum de Contract.type (ver doc 3).
contracts.groupedBy.type[].totalIntegerQuantidade de contratos do cliente com esse tipo.
contracts.groupedBy.type[].valueDecimalSoma do value dos contratos dessa quebra.
contracts.groupedBy.type[].openDecimalSoma do valor em aberto dos contratos dessa quebra.

3. Regras de Negócio#

Visibilidade na carteira#

RN-PCLI-001: Presença automática por contrato
Um cliente aparece na listagem da carteira automaticamente quando possui ao menos um contrato com status != CANCELLED. Não existe operação de vínculo ou desvínculo manual de clientes à carteira. A visibilidade é puramente derivada dos dados.
RN-PCLI-002: Remoção automática
Se todos os contratos de um cliente forem cancelados (status = CANCELLED), o cliente deixa de aparecer na listagem da carteira. Os dados do Client não são afetados — ele continua existente no módulo de Clientes da plataforma.
RN-PCLI-003: Escopo de acesso
A listagem de clientes na carteira respeita o modelo de visibilidade do módulo (ver Visão Geral, seção 9): a permissão RBAC sobre o resource contract combinada com a atribuição do usuário a portfolios e/ou carteiras determina quais clientes são visíveis. Um cliente aparece para o usuário quando o usuário enxerga ao menos um dos contratos daquele cliente.

Status de cobrança#

RN-PCLI-004: Cálculo do status (collectionStatus)
O status do cliente é calculado em tempo de leitura combinando os status das parcelas e contratos vinculados a ele:
ON_TRACK quando não há parcela nem contrato em OVERDUE ou DEFAULTED.
OVERDUE quando há ao menos uma parcela ou contrato em OVERDUE (e nenhum em DEFAULTED).
CRITICAL quando há ao menos uma parcela ou contrato em DEFAULTED.
Não há configuração de limiar separada neste módulo — todas as regras de transição vivem no contrato.
RN-PCLI-005: Detecção de transições via job programado
Embora o status seja calculado em tempo de leitura, o job programado Cliente → collectionStatus (ver seção 6) avalia diariamente o status efetivo de cada cliente e detecta transições (ex.: cliente passou de OVERDUE para CRITICAL), emitindo eventos de domínio para consumo por outros módulos (notificações, integrações com Gestão de Cobrança).
RN-PCLI-006: Clientes sem títulos em aberto
Cliente que possui contratos ACTIVE mas com todos os títulos PAID é classificado como ON_TRACK com contracts.open = 0. Não há ação manual envolvida — é cálculo direto sobre os dados.

Indicadores financeiros#

RN-PCLI-007: Cálculo sob demanda
Todos os indicadores do PortfolioClientSummary e PortfolioClientDetail são calculados sob demanda por agregação sobre Contract (filtrando por participantes do cliente) e ContractPayment (das parcelas desses contratos). Não são armazenados.
RN-PCLI-008: Período de referência na listagem de clientes
O endpoint GET .../portfolio/clients aceita filtro de período (startDate / endDate). Quando informado, os indicadores financeiros (contracts.value, contracts.open, contracts.overdue, contracts.maxOverdueDays, etc.) consideram apenas títulos com dueDate dentro do período. Quando omitido, considera todos os títulos em aberto independente da data.

Dados cadastrais#

RN-PCLI-009: Dados do Client são read-only neste módulo
Os dados cadastrais (nome, taxId, e-mail, telefone, endereço) são lidos da entidade Client existente. Este módulo não oferece endpoints para edição de dados cadastrais — a edição é feita pelo módulo de Clientes da plataforma. Qualquer alteração no Client é refletida automaticamente na carteira.

4. Padrão de Erros#

Erros comuns herdados#

Todos os erros de autenticação, autorização e servidor seguem Carteiras.md.

Códigos de erro específicos#

StatusCódigoDescrição
404 Not FoundCLIENT_NOT_FOUNDCliente não encontrado ou não pertence à empresa.
404 Not FoundCLIENT_NOT_IN_PORTFOLIOCliente existe mas não possui contratos na carteira.

5. Endpoints#

5.1. Listagem de Clientes na Carteira#

GET /v2/companies/:companyId/portfolios/:portfolioId/clients#

Lista os clientes que possuem contratos na carteira da empresa, com indicadores financeiros agregados.
Permissão requerida: portfolio:read
Query params:
ParâmetroTipoObrigatórioDescrição
searchStringNãoBusca textual por nome, razão social ou taxId do cliente.
statusEnum (multi)NãoFiltrar por status de cobrança: ON_TRACK, OVERDUE, CRITICAL. Aceita múltiplos valores.
startDateDatetime (ISO)NãoInício do período para cálculo dos indicadores.
endDateDatetime (ISO)NãoFim do período para cálculo dos indicadores.
subPortfolioIdUUIDNãoFiltrar por carteira específica (clientes com ao menos um contrato naquela carteira).
orderByEnumNãoOrdenação: clientName, contracts.open, contracts.maxOverdueDays. Default: clientName.
orderEnumNãoasc ou desc. Default: asc.
offsetIntegerNãoDefault: 0.
limitIntegerNãoDefault: 20. Máximo: 100.
typeStringNãoCampo para buscar pelo tipo do cliente (DEBTOR, CREDOR, GUARANTOR, WITNESS)
Response 200 OK:
{
  "items": [
    {
      "client": {
        "id": "a3f1c2d4-0000-0000-0000-000000000010",
        "name": "Fazenda Tijucal",
        "taxId": "12345678000190"
      },
      "contracts": {
        "total": 3,
        "active": 2,
        "value": 730000.00,
        "open": 85000.00,
        "overdue": 85000.00,
        "overduePayments": 2,
        "maxOverdueDays": 45
      },
      "status": "OVERDUE"
    },
    {
      "client": {
        "id": "b4g2d3e5-0000-0000-0000-000000000020",
        "name": "Fazenda Rio Verde",
        "taxId": "98765432000110"
      },
      "contracts": {
        "total": 1,
        "active": 1,
        "value": 200000.00,
        "open": 0.00,
        "overdue": 0.00,
        "overduePayments": 0,
        "maxOverdueDays": 0
      },
      "status": "ON_TRACK"
    },
    {
      "client": {
        "id": "c5h3e4f6-0000-0000-0000-000000000030",
        "name": "Fazenda Cocal",
        "taxId": "55666777000188"
      },
      "contracts": {
        "total": 2,
        "active": 1,
        "value": 520000.00,
        "open": 320000.00,
        "overdue": 320000.00,
        "overduePayments": 5,
        "maxOverdueDays": 92
      },
      "status": "CRITICAL"
    }
  ],
  "nextPage": false
}

5.2. Detalhe do Cliente na Carteira (Visão 360°)#

GET /v2/companies/:companyId/portfolios/:portfolioId/clients/:clientId#

Retorna a visão completa do cliente no contexto da carteira, incluindo dados cadastrais, resumo financeiro detalhado e breakdown dos contratos (por tipo na v1; outras dimensões podem ser adicionadas em contracts.groupedBy no futuro).
Permissão requerida: portfolio:read
Query params:
ParâmetroTipoObrigatórioDescrição
startDateDatetime (ISO)NãoPeríodo para indicadores. Default: primeiro dia do ano corrente.
endDateDatetime (ISO)NãoDefault: último dia do ano corrente.
Response 200 OK:
{
  "client": {
    "id": "a3f1c2d4-0000-0000-0000-000000000010",
    "name": "Fazenda Tijucal",
    "taxId": "98765432000110",
    "email": "contato@fazendatijucal.com.br",
    "phone": "11999999999",
    "address": "Fazenda Horizonte, Km 15, Zona Rural - Ribeirão Preto/SP"
  },
  "contracts": {
    "total": 3,
    "active": 2,
    "closed": 1,
    "defaulted": 0,
    "value": 730000.00,
    "open": 85000.00,
    "overdue": 85000.00,
    "paid": 645000.00,
    "overduePayments": 2,
    "pendingPayments": 3,
    "paidPayments": 8,
    "maxOverdueDays": 45,
    "averageOverdueDays": 30,
    "items":[
        {
          "key": "CPR_PHYSICAL",
          "total": 1,
          "value": 450000.00,
          "open": 0.00
        },
        {
          "key": "INVOICE",
          "total": 2,
          "value": 280000.00,
          "open": 85000.00
        }
      ]
  },
  "status": "OVERDUE"
}
Erros específicos:
StatusCódigo
404CLIENT_NOT_FOUND
404CLIENT_NOT_IN_PORTFOLIO

5.3. Contratos do Cliente#

GET /v2/companies/:companyId/portfolios/:portfolioId/clients/:clientId/contracts#

Lista os contratos do cliente na carteira. Atalho de conveniência para a UI — equivale a GET /portfolios/:portfolioId/contracts com filtro implícito por clientId, mas aninhado na rota do cliente para acesso direto sem passar o ID via query param.
Permissão requerida: contract:read
Query params:
ParâmetroTipoObrigatórioDescrição
searchStringNãoBusca por code ou description.
statusEnum (multi)NãoFiltrar por status do contrato.
typeEnum (multi)NãoFiltrar por tipo do contrato.
startDateDatetime (ISO)NãoContratos com startDate >= esta data.
endDateDatetime (ISO)NãoContratos com endDate <= esta data.
offsetIntegerNãoDefault: 0.
limitIntegerNãoDefault: 20. Máximo: 100.
Response 200 OK:
{
  "items": [
    {
      "id": "b9d3f1aa-22cc-4e72-b430-1e45a3d6e001",
      "code": "CT-2024-001",
      "client": {
        "id": "a3f1c2d4-0000-0000-0000-000000000010",
        "name": "Fazenda Tijucal"
      },
      "type": "PURCHASE_SALE_CONTRACT",
      "description": "Financiamento Safra Soja 2024",
      "value": 450000.00,
      "currency": "BRL",
      "startDate": "2024-03-14T00:00:00.000+00:00",
      "endDate": "2024-03-14T00:00:00.000+00:00",
      "status": "OVERDUE",
      "typeSpecificFields": {
        "product": "Insumos agrícolas"
      },
      "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"
    }
  ],
  "nextPage": false
}
Nota técnica: typeSpecificFields é um objeto JSON cuja estrutura interna varia conforme o type do contrato. Cada tipo base define seu próprio schema (camada 2 do template — ver Visão Geral, seção 4.3). A validação é feita contra esse schema no momento da criação/edição do contrato.

5.4. Títulos do Cliente (visão transversal)#

GET /v2/companies/:companyId/portfolios/:portfolioId/clients/:clientId/payments#

Lista todos os títulos do cliente, independente do contrato — visão transversal. É o endpoint que alimenta a aba "Títulos/Faturas" da Visão 360°.
Permissão requerida: payment:read
Query params:
ParâmetroTipoObrigatórioDescrição
statusEnum (multi)NãoFiltrar por status do título.
contractIdUUIDNãoFiltrar por contrato específico.
dueDateStartDatetime (ISO)NãoTítulos com dueDate >= esta data.
dueDateEndDatetime (ISO)NãoTítulos com dueDate <= esta data.
orderByEnumNãoOrdenação: dueDate, amounts.value, overdueDays, status. Default: dueDate.
orderEnumNãoasc ou desc. Default: asc.
offsetIntegerNãoDefault: 0.
limitIntegerNãoDefault: 20. Máximo: 100.
Response 200 OK:
{
  "items": [
    {
      "id": "r1a2b3c4-0000-0000-0000-000000000001",
      "contract": {
        "id": "b9d3f1aa-22cc-4e72-b430-1e45a3d6e001",
        "code": "CT-2024-001"
      },
      "code": "NF-001",
      "type": "INVOICE",
      "description": null,
      "dueDate": "2024-03-14T00:00:00.000+00:00",
      "status": "OVERDUE",
      "overdueDays": 45,
      "amounts": {
        "value": 150000.00,
        "corrected": null,
        "due": 156750.00,
        "received": 71750.00,
        "remaining": 85000.00
      },
      "charges": {
        "interest": 3750.00,
        "fine": 3000.00,
        "discount": {
          "type": null,
          "value": null,
          "calculatedAmount": null
        }
      },
      "createdBy": {
        "id": "8c3f1a2b-...",
        "name": "João Silva"
      },
      "createdAt": "2025-03-17T09:00:00.000+00:00"
    }
  ],
  "nextPage": false
}
A diferença principal em relação ao GET /contracts/:contractId/payments é que este endpoint não exige contractId na rota — traz títulos de todos os contratos do cliente. O objeto contract é incluído na resposta para contexto. A estrutura do título segue a mesma definição de ContractPayment do doc 5 (amounts, charges, createdBy hidratado).

5.5. Exportar Lista de Clientes#

GET /v2/companies/:companyId/portfolios/:portfolioId/clients/export#

Exporta a listagem de clientes da carteira em CSV ou XLSX. Respeita os mesmos filtros da listagem.
Permissão requerida: portfolio:read
Query params: Mesmos filtros do GET /portfolio/clients, acrescidos de:
ParâmetroTipoObrigatórioDescrição
formatEnumSimCSV ou XLSX.
Response 200 OK: Arquivo binário.

6. Jobs Programados#

JobDescrição
Cliente → collectionStatusAvalia diariamente o status de cobrança de cada cliente da carteira (derivado das parcelas e contratos). Detecta transições entre ON_TRACK, OVERDUE e CRITICAL, e emite eventos de domínio para consumo por outros módulos (notificações, integrações com Gestão de Cobrança quando implementada).

7. Impacto em Outros Módulos#

7.1. Contratos#

O endpoint GET /portfolios/:portfolioId/contracts já suporta filtro clientId. O endpoint GET /portfolios/:portfolioId/clients/:clientId/contracts é um atalho de conveniência para a UI — internamente pode reutilizar a mesma lógica com o filtro implícito.

7.2. Visão Geral (Carteira)#

Os indicadores da Carteira Global (PortfolioSummary em Carteiras.md) incluem defaultersCount — número de clientes com ao menos um título OVERDUE. Esse indicador é coerente com status != ON_TRACK deste módulo.
Modificado em 2026-06-02 15:01:13
Página anterior
Devedores e credores (Participantes)
Próxima página
Importação de dados
Built with