Carteiras (Portfolios) — Regras de Negócio

1. Conceito

O Portfolio é a entidade de agrupamento de carteiras e operações de crédito dentro da plataforma. Uma empresa pode criar múltiplos portfolios independentes, organizando sua carteira conforme a estrutura que fizer sentido para o negócio — por unidade/filial, por safra, por tipo de operação, por produto, ou livremente.

Cada portfolio é um silo isolado: contratos pertencem a exatamente um portfolio, e não existe visão consolidada. Os indicadores, relatórios e filtros operam sempre dentro do escopo de um portfolio específico.

Dentro de cada portfolio, a empresa pode criar Carteiras — agrupamentos nomeados que permitem segmentar contratos para fins operacionais e de controle de acesso.

1.1. Modelo de organização

Empresa (Company)
├── Portfolio "Safra 2024/2025"
│   ├── Carteira "Analista A — Região Sul"
│   │   ├── Contrato CPR-001
│   │   └── Contrato CPR-002
│   └── Carteira "Analista B — Região Norte"
│       └── Contrato CPR-003
├── Portfolio "Duplicatas — SP"
│   └── Carteira "Padrão"
│       ├── Contrato CT-001
│       └── Contrato CT-002
└── Portfolio "CCBs — Crédito Rural"
    └── Carteira "Padrão"
        └── Contrato CCB-001

Hierarquia: Empresa → Portfolio (1..N) → Carteira (1..N por portfolio) → Contratos.

Todo contrato pertence a exatamente uma carteira, e toda carteira pertence a exatamente um portfolio. Não há acesso direto a contratos pelo portfolio — contratos vivem dentro de carteiras. O portfolio é uma camada de agrupamento e apresentação consolidada das suas carteiras.

1.2. Modelo de acesso

A visibilidade dos portfolios, carteiras e demais recursos do módulo é determinada pela combinação de duas dimensões independentes:

Permissão RBAC sobre o resource — portfolio:read, contract:read, etc. Define o que o usuário pode fazer.

Atribuição direta do usuário a portfolios e/ou carteiras — define em quais carteiras o usuário atua. Gerenciada via action portfolio:assign_user.

A atribuição opera em dois níveis:

Nível	Entidade	Efeito
Portfolio	`PortfolioUser`	Usuário enxerga todos os contratos do portfolio, em qualquer carteira filha.
Carteira	`SubPortfolioUser`	Usuário enxerga apenas os contratos da(s) carteira(s) à(s) qual(is) está atribuído (escopo restrito dentro do portfolio).

Um usuário pode ser atribuído ao portfolio inteiro, a carteiras específicas, ou a ambos (na prática, a atribuição ao portfolio já cobre tudo). A regra composta é:

Recurso visível ⇔ (usuário tem permissão RBAC sobre o resource) AND (usuário está atribuído ao portfolio do recurso OU a alguma carteira que contenha o recurso).

Sobre UNIT_RESTRICTED. O escopo de unit usado em outros módulos da plataforma (separação matriz/filial) não se aplica ao módulo de Portfolio Management. A visibilidade aqui é independente da estrutura organizacional de units.

Carteiras são obrigatórias para receber contratos. Um portfolio pode existir vazio (recém-criado, sem carteiras), mas não é possível vincular contratos a um portfolio diretamente — a empresa precisa criar ao menos uma carteira antes. Carteiras são as entidades que efetivamente armazenam os vínculos com contratos, pagamentos e baixas, permitindo segmentação operacional (por gestor, região, produto, etc.) e atribuição de visibilidade a usuários específicos.

2. Estruturas de Dados

2.1. Portfolio

Criado por ação explícita do usuário. Uma empresa pode ter múltiplos portfolios ativos simultaneamente.

Campo	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador único do portfolio.
companyId	UUID	Sim	Empresa à qual o portfolio pertence.
name	String	Sim	Nome do portfolio (ex: "Safra 2024/2025", "Duplicatas — Filial SP"). Único por empresa.
description	String	Não	Descrição do propósito ou critério de agrupamento do portfolio.
status	Enum	Sim	Estado: `ACTIVE`, `INACTIVE`.
createdBy	Object	Sim	Usuário que criou o portfolio, hidratado: `{ id, name }`. No armazenamento permanece como UUID flat.
createdAt	DateTime	Sim	Data de criação.
updatedAt	DateTime	Sim	Data da última atualização.

2.2. PortfolioSummary (objeto calculado)

Calculado sob demanda a partir dos contratos e pagamentos (parcelas) do portfolio dentro do período informado. Não é armazenado — derivado em tempo de leitura. Todos os campos numéricos acompanham um campo delta em relação ao período anterior equivalente.

O período de referência é informado via query params (startDate / endDate). Quando omitido, o sistema assume todas as informações do portfolio.

Indicadores principais

Campo	Tipo	Descrição
totalReceivable	Decimal	Soma do valor em aberto de todos os pagamentos (parcelas) com status `PENDING` ou `PARTIALLY_PAID` no período.
totalReceivableDelta	Decimal	Variação percentual em relação ao período anterior.
totalOverdue	Decimal	Soma do valor em aberto de todos os pagamentos (parcelas) com status `OVERDUE`.
totalOverdueDelta	Decimal	Variação percentual em relação ao período anterior.
defaulters	Integer	Número de devedores únicos com ao menos um pagamento (parcela) `OVERDUE`.
defaultersDelta	Integer	Variação absoluta.
activeContracts	Integer	Contratos com `status = ACTIVE`.
activeContractsDelta	Integer	Variação absoluta.
overdueContracts	Integer	Contratos com ao menos um pagamento (parcela) `OVERDUE`.
overdueContractsDelta	Integer	Variação absoluta.
overduePayments	Integer	Total de pagamentos (parcelas) com status `OVERDUE`.
overduePaymentsDelta	Integer	Variação absoluta.

Análise de efetividade

Campo	Tipo	Descrição
recoveryRate	Decimal	Percentual do valor vencido efetivamente recebido no período.
recoveryRateDelta	Decimal	Variação em pontos percentuais.
averageReceivingDays	Integer	Tempo médio em dias entre vencimento e liquidação.
averageReceivingDaysDelta	Integer	Variação absoluta em dias.

2.3. SubPortfolio (Carteira)

Agrupamento nomeado obrigatório criado dentro de um portfolio. É a entidade onde os contratos efetivamente são vinculados — todo contrato pertence a exatamente uma carteira (subPortfolioId). O nome técnico da entidade no código permanece SubPortfolio (refletindo a hierarquia: portfolio é a carteira-pai); o rótulo PT-BR exibido na UI e na documentação de negócio é "Carteira".

Campo	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador único da carteira.
companyId	UUID	Sim	Empresa à qual a carteira pertence.
portfolioId	UUID	Sim	Portfolio ao qual a carteira pertence.
name	String	Sim	Nome da carteira. Único dentro do portfolio.
description	String	Não	Descrição opcional do critério de agrupamento.
user	Object	Não	Usuário responsável (gestor) pela carteira, hidratado: `{ id, name }`. No armazenamento permanece como UUID flat.
status	Enum	Sim	Estado: `ACTIVE`, `INACTIVE`.
createdBy	Object	Sim	Usuário que criou a carteira, 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.

2.3.1. SubPortfolioSummary (objeto calculado)

Calculado sob demanda a partir dos contratos e parcelas da carteira. Mesma estrutura do PortfolioSummary (seção 2.2), mas no escopo de uma única carteira. Acessado via GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId no campo summary da resposta.

O PortfolioSummary é a agregação dos SubPortfolioSummary das carteiras filhas do portfolio — todos os indicadores numéricos do portfolio são a soma dos respectivos indicadores das suas carteiras.

2.4. Vínculo Contrato ↔ Carteira

A relação entre contrato e carteira é representada como o campo subPortfolioId obrigatório na entidade Contract (ver Contratos.md). Não existe entidade de vínculo separada. O contrato é criado já indicando a carteira de destino, e o campo pode ser alterado posteriormente para mover o contrato entre carteiras do mesmo portfolio via PATCH .../contracts/:contractId.

Não é permitido subPortfolioId = null em um contrato — todo contrato precisa estar atribuído a exatamente uma carteira do seu portfolio.

2.5. PortfolioUser (Vínculo Usuário ↔ Portfolio)

Atribui um usuário do tenant a um portfolio inteiro. Usuários atribuídos enxergam todos os contratos do portfolio, independentemente de carteira.

Campo	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador único do vínculo.
portfolioId	UUID	Sim	Referência ao portfolio.
user	Object	Sim	Usuário tenant vinculado, hidratado: `{ id, name }`. No armazenamento permanece como UUID flat.
assignedBy	Object	Sim	Usuário que realizou a atribuição, hidratado: `{ id, name }`. No armazenamento permanece como UUID flat.
assignedAt	DateTime	Sim	Data e hora da atribuição.
createdAt	DateTime	Sim	Data de criação do registro.

2.6. SubPortfolioUser (Vínculo Usuário ↔ Carteira)

Atribui um usuário do tenant a uma carteira específica. Usuários atribuídos enxergam apenas os contratos daquela carteira (refinamento do escopo de visibilidade dentro do portfolio).

Campo	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador único do vínculo.
subPortfolioId	UUID	Sim	Referência à carteira.
user	Object	Sim	Usuário tenant vinculado, hidratado: `{ id, name }`. No armazenamento permanece como UUID flat.
assignedBy	Object	Sim	Usuário que realizou a atribuição, hidratado: `{ id, name }`. No armazenamento permanece como UUID flat.
assignedAt	DateTime (ISO 8601 UTC)	Sim	Data e hora da atribuição.
createdAt	DateTime (ISO 8601 UTC)	Sim	Data de criação do registro.

3. Regras de Negócio

3.1. Portfolio

RN-PORT-001: Criação explícita
Portfolios são criados por ação explícita do usuário. Não existe portfolio auto-criado. Uma empresa pode ter N portfolios ativos simultaneamente.

RN-PORT-002: Nome único por empresa
O campo name deve ser único dentro da empresa. Erro: PORTFOLIO_NAME_ALREADY_EXISTS.

RN-PORT-003: Silo isolado
Cada portfolio é independente. Um contrato pertence a exatamente um portfolio (por meio da sua carteira). Não existe visão consolidada cross-portfolio. Indicadores são sempre calculados no escopo de um portfolio (agregando suas carteiras).

RN-PORT-003B: Acesso a contratos apenas via carteira
Não há acesso direto a contratos pelo portfolio. Contratos são listados, criados e gerenciados sempre no escopo de uma carteira. O endpoint de detalhe do portfolio retorna apenas metadados, lista de carteiras filhas e indicadores agregados — nunca a lista de contratos diretamente.

RN-PORT-004: Desativação
Um portfolio só pode ser desativado se não possuir contratos em estados não-terminais (DRAFT, ACTIVE, OVERDUE, DEFAULTED). Todos os contratos devem estar em estados terminais (CLOSED, CANCELLED ou RENEGOTIATED) antes da desativação. Erro: PORTFOLIO_HAS_ACTIVE_CONTRACTS.

RN-PORT-005: Desativação em cascata pela empresa
Quando uma empresa transita para INACTIVE, todos os seus portfolios são automaticamente desativados. Todas as carteiras e vínculos de usuários (tanto PortfolioUser quanto SubPortfolioUser) são removidos em cascata.

RN-PORT-006: Exclusão lógica
Portfolios nunca são deletados fisicamente. Desativação via status = INACTIVE.

3.2. Carteiras

RN-SUBPORT-001: Vínculo obrigatório ao portfolio + carteira como pré-condição para contratos
Toda carteira deve estar vinculada a um portfolio via portfolioId. Não é possível criar carteiras em portfolios com status = INACTIVE. Erro: PORTFOLIO_INACTIVE.

Para que um portfolio possa receber contratos, ele precisa ter ao menos uma carteira ativa. A carteira não é criada automaticamente — a empresa precisa criá-la explicitamente após criar o portfolio. Tentativas de criar contrato em portfolio sem carteira ativa retornam erro PORTFOLIO_HAS_NO_SUB_PORTFOLIO.

RN-SUBPORT-002: Nome único por portfolio
O campo name deve ser único dentro do portfolio (não da empresa). Carteiras de portfolios diferentes podem ter o mesmo nome. Erro: SUB_PORTFOLIO_NAME_ALREADY_EXISTS.

RN-SUBPORT-003: Pré-condições para desativação
Uma carteira só pode ser desativada se não houver contratos vinculados em estados não-terminais (DRAFT, ACTIVE, OVERDUE, DEFAULTED). O usuário deve mover ou encerrar todos os contratos ativos antes da desativação. Erro: SUB_PORTFOLIO_HAS_CONTRACTS.

RN-SUBPORT-004: Impacto sobre acesso de usuários
Ao desativar uma carteira, todos os vínculos de SubPortfolioUser são removidos automaticamente. Os contratos permanecem no portfolio.

RN-SUBPORT-005: Exclusão lógica
Carteiras nunca são deletadas fisicamente.

3.3. Vínculo Contrato ↔ Carteira

A relação contrato ↔ carteira é representada pelo campo subPortfolioId obrigatório na entidade Contract (não há entidade de vínculo separada).

RN-CONT-SUBPORT-001: subPortfolioId obrigatório
Todo contrato deve ter subPortfolioId preenchido — não é permitido null. O contrato é criado já indicando a carteira de destino. Erro: SUB_PORTFOLIO_REQUIRED.

RN-CONT-SUBPORT-002: Unicidade
Um contrato pertence a exatamente uma carteira por vez (subPortfolioId é um campo único, não uma lista). Mover entre carteiras é feito sobrescrevendo o subPortfolioId com o ID da nova carteira via PATCH .../contracts/:contractId.

RN-CONT-SUBPORT-003: Consistência portfolio × contrato
A carteira indicada em subPortfolioId deve pertencer ao mesmo portfolio do contrato (portfolioId). Erro: CONTRACT_PORTFOLIO_MISMATCH.

RN-CONT-SUBPORT-004: Atribuição/movimentação manual
A movimentação entre carteiras é sempre explícita e manual, via PATCH .../contracts/:contractId informando o novo subPortfolioId. Permissão requerida: portfolio:assign_contract.

RN-CONT-SUBPORT-005: Movimentação não afeta dados do contrato
Mover o contrato para outra carteira não altera demais campos do contrato. O contrato permanece no mesmo portfolio (não é permitido mover entre portfolios).

RN-CONT-SUBPORT-006: Ciclo de vida do contrato não altera o vínculo
Transições de status do contrato não alteram o subPortfolioId. O contrato permanece atribuído à carteira até ser explicitamente movido.

3.4. Vínculo Usuário ↔ Portfolio

RN-PORT-USER-001: Consistência empresa × usuário
O usuário deve ser um tenant vinculado à mesma empresa do portfolio. Vínculos com usuários de outras empresas ou internos são bloqueados. Erro: USER_COMPANY_MISMATCH.

RN-PORT-USER-002: Visibilidade total no portfolio
Usuário atribuído a um portfolio enxerga todos os contratos daquele portfolio, incluindo os atribuídos a qualquer carteira.

RN-PORT-USER-003: Múltiplos portfolios por usuário
Um usuário pode estar atribuído a múltiplos portfolios da mesma empresa. Enxerga a união dos contratos de todos os portfolios aos quais está vinculado.

RN-PORT-USER-004: Remoção ao desativar usuário
Quando um usuário é desativado, todos os seus vínculos com portfolios são removidos.

3.5. Vínculo Usuário ↔ Carteira

RN-SUBPORT-USER-001: Consistência empresa × usuário
O usuário deve ser um tenant vinculado à mesma empresa do portfolio. Vínculos com usuários de outras empresas ou internos são bloqueados. Erro: USER_COMPANY_MISMATCH.

RN-SUBPORT-USER-002: Visibilidade restrita à carteira
Usuário atribuído apenas a carteira(s) específica(s) — sem atribuição direta ao portfolio que as contém — enxerga somente os contratos daquela(s) carteira(s).

RN-SUBPORT-USER-003: Atribuição cumulativa com portfolio
Usuário atribuído tanto ao portfolio quanto a carteiras do mesmo portfolio mantém a visibilidade ampla concedida pelo portfolio. A atribuição à carteira é redundante nesse cenário, mas permitida.

RN-SUBPORT-USER-004: Múltiplas carteiras por usuário
Um usuário pode estar vinculado a carteiras de portfolios diferentes. Enxerga a união dos contratos de todas as carteiras às quais está vinculado.

RN-SUBPORT-USER-005: Remoção ao desativar usuário
Quando um usuário é desativado, todos os seus vínculos com carteiras são removidos.

4. Padrão de Erros e Paginação

4.1. Formato padrão de erro

{
  "error": "CODIGO_DO_ERRO",
  "message": "Descrição legível do problema.",
  "details": {}
}

4.2. Códigos de erro comuns

Status	Código	Descrição
401 Unauthorized	`UNAUTHORIZED`	Token JWT ausente, expirado ou inválido.
403 Forbidden	`FORBIDDEN`	Permissão insuficiente.
404 Not Found	`PORTFOLIO_NOT_FOUND`	Portfolio não encontrado ou não pertence à empresa.
404 Not Found	`SUB_PORTFOLIO_NOT_FOUND`	Carteira não encontrada.
404 Not Found	`CONTRACT_NOT_FOUND`	Contrato não encontrado.
404 Not Found	`USER_NOT_FOUND`	Usuário não encontrado.
500 Internal Server Error	`INTERNAL_SERVER_ERROR`	Erro inesperado.

4.3. Códigos de erro específicos

Status	Código	Descrição
409 Conflict	`PORTFOLIO_NAME_ALREADY_EXISTS`	Nome de portfolio duplicado na empresa.
422 Unprocessable Entity	`PORTFOLIO_INACTIVE`	Portfolio inativo — operação não permitida.
422 Unprocessable Entity	`PORTFOLIO_HAS_ACTIVE_CONTRACTS`	Portfolio possui contratos ativos e não pode ser desativado.
422 Unprocessable Entity	`PORTFOLIO_HAS_NO_SUB_PORTFOLIO`	Tentativa de criar contrato em portfolio sem carteira ativa. Criar uma carteira primeiro.
409 Conflict	`SUB_PORTFOLIO_NAME_ALREADY_EXISTS`	Nome de carteira duplicado no portfolio.
422 Unprocessable Entity	`SUB_PORTFOLIO_HAS_CONTRACTS`	Carteira possui contratos em estados não-terminais e não pode ser desativada.
422 Unprocessable Entity	`SUB_PORTFOLIO_INACTIVE`	Carteira inativa.
422 Unprocessable Entity	`SUB_PORTFOLIO_REQUIRED`	Contrato sendo criado sem `subPortfolioId`. O campo é obrigatório.
422 Unprocessable Entity	`CONTRACT_PORTFOLIO_MISMATCH`	Carteira informada não pertence ao portfolio do contrato.
422 Unprocessable Entity	`USER_COMPANY_MISMATCH`	Usuário não pertence à empresa.
422 Unprocessable Entity	`INTERNAL_USER_NOT_ALLOWED`	Usuários internos não podem ser vinculados.
409 Conflict	`USER_ALREADY_ASSIGNED`	Usuário já vinculado ao portfolio ou à carteira.
404 Not Found	`USER_ASSIGNMENT_NOT_FOUND`	Vínculo usuário-portfolio ou usuário-carteira não encontrado.

4.4. Formato padrão de paginação

Todas as listagens da plataforma seguem o padrão offset/limit.

Parâmetros aceitos na request (query string):

Parâmetro	Tipo	Default	Descrição
`offset`	Integer	0	Quantidade de registros a pular antes de começar a retornar.
`limit`	Integer	20	Quantidade máxima de registros por página. Máximo: 100.

Estrutura padrão de response paginado:

{
  "items": [ ... ],
  "nextPage": true
}

items: array com os registros da página atual.

nextPage: indica se existe uma próxima página. true quando há mais registros após os retornados; false quando a página atual é a última.

Parâmetros offset e limit enviados na request não são retornados no response (o cliente já os conhece). Não há campo total no response da v1 — listagens não dependem de "página X de Y".

5. Endpoints

Base path para todos os endpoints deste módulo:

/v2/companies/:companyId/portfolios

5.1. CRUD de Portfolios

POST /v2/companies/:companyId/portfolios

Cria um novo portfolio.

Permissão requerida: portfolio:create

Request body:

{
  "name": "Safra 2024/2025",
  "description": "Contratos de crédito rural vinculados à safra 24/25."
}

No request, apenas user.id é necessário (e aceito).

Response 201 Created:

{
  "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "companyId": "a1b2c3d4-0000-0000-0000-000000000001",
  "name": "Safra 2024/2025",
  "description": "Contratos de crédito rural vinculados à safra 24/25.",
  "status": "ACTIVE",
  "createdBy": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "João Silva"
  },
  "createdAt": "2025-03-17T09:00:00.000+00:00",
  "updatedAt": "2025-03-17T09:00:00.000+00:00"
}

Erros: PORTFOLIO_NAME_ALREADY_EXISTS, USER_COMPANY_MISMATCH (quando user.id informado é inválido).

GET /v2/companies/:companyId/portfolios

Lista os portfolios da empresa.

Permissão requerida: portfolio:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
`status`	Enum	Não	Filtrar por `ACTIVE` ou `INACTIVE`.
`orderBy`	Enum	Não	Ordenação: `name`, `createdAt`. Default: `name`.
`order`	Enum	Não	`asc` ou `desc`. Default: `asc`.
`offset`	Integer	Não	Default: 0.
`limit`	Integer	Não	Default: 20. Máximo: 100.

Response 200 OK:

{
  "items": [
    {
      "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
      "companyId": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Safra 2024/2025",
      "description": "Contratos de crédito rural vinculados à safra 24/25.",
      "status": "ACTIVE",
      "summary": {
        "subPortfolios": 45,
        "value": 12500000.00
      },
      "createdBy": {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "name": "João Silva"
      },
      "createdAt": "2025-03-17T09:00:00.000+00:00",
      "updatedAt": "2025-03-17T09:00:00.000+00:00"
    }
  ],
    "summary": {
        "activeContracts": 45,
        "value": 12500000.00
        },
  "nextPage": false
}

A listagem retorna summary.activeContracts e summary.value como campos resumidos para contexto — sem o cálculo completo do PortfolioSummary (que vai no detalhe).

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

Retorna o detalhe do portfolio com indicadores consolidados.

Permissão requerida: portfolio:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
startDate	Datetime (UTC)	Não	Início do período para summary. Default: primeiro dia do ano corrente.
endDate	Datetime (UTC)	Não	Fim do período. Default: último dia do ano corrente.

Response 200 OK:

{
  "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "companyId": "a1b2c3d4-0000-0000-0000-000000000001",
  "name": "Safra 2024/2025",
  "description": "Contratos de crédito rural vinculados à safra 24/25.",
  "status": "ACTIVE",
  "createdBy": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "João Silva"
  },
  "createdAt": "2025-03-17T13:32:32.209+00:00",
  "updatedAt": "2025-03-17T13:32:32.209+00:00",
  "summary": {
/**    "period": {
      "startDate": "2025-01-01T13:32:32.209+00:00",
      "endDate": "2025-12-31T13:32:32.209+00:00"
    },**/
    "Receivable": 2847350.00,
    "ReceivableDelta": 5.2,
    "Overdue": 892150.00,
    "OverdueDelta": 2.1,
    "defaulters": 127,
    "defaultersDelta": -3,
    "activeContracts": 45,
    "activeContractsDelta": 12,
    "overdueContracts": 8,
    "overdueContractsDelta": 2,
    "overduePayments": 23,
    "overduePaymentsDelta": 3,
    "recoveryRate": 68.5,
    "recoveryRateDelta": 2.3,
    "averageReceivingDays": 18,
    "averageReceivingDaysDelta": -3
  }
}

No detalhe do portfolio, o summary é a agregação dos SubPortfolioSummary das carteiras filhas. O portfolio não devolve a lista de contratos — a UI obtém essa informação via GET .../sub-portfolios/:subPortfolioId/contracts ou GET .../portfolios/:portfolioId/contracts?subPortfolioId=....

Erros: PORTFOLIO_NOT_FOUND, INVALID_DATE_RANGE.

PATCH /v2/companies/:companyId/portfolios/:portfolioId

Atualiza atributos editáveis do portfolio: name, description

Permissão requerida: portfolio:update

Request body:

{
  "name": "Safra 2024/2025 — Soja e Milho",
  "description": "Contratos de crédito rural para soja e milho, safra 24/25."
}

Response 200 OK: Retorna o portfolio atualizado (mesmo formato do GET detalhe).

Erros: PORTFOLIO_NAME_ALREADY_EXISTS, PORTFOLIO_INACTIVE, USER_COMPANY_MISMATCH (quando user.id é informado e o usuário não pertence à empresa).

PUT /v2/companies/:companyId/portfolios/:portfolioId/status

Ativa ou desativa um portfolio (substituição completa do status).

Permissão requerida: portfolio:delete

Request body:

{
  "status": "INACTIVE"
}

Response 200 OK:

{
  "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "status": "INACTIVE",
  "updatedAt": "2025-03-17T11:00:00.000+00:00"
}

Erros: PORTFOLIO_HAS_ACTIVE_CONTRACTS.

5.2. Carteiras

POST /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios

Cria uma carteira dentro do portfolio.

Permissão requerida: portfolio:create

Request body:

{
  "name": "Analista João — Região Sul",
  "description": "Contratos da região Sul sob responsabilidade do analista João.",
  "user": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
  }
}

Response 201 Created:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "companyId": "a1b2c3d4-0000-0000-0000-000000000001",
  "portfolioId": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "name": "Analista João — Região Sul",
  "description": "Contratos da região Sul sob responsabilidade do analista João.",
  "user": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "João Silva"
  },
  "status": "ACTIVE",
  "createdBy": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "João Silva"
  },
  "createdAt": "2025-03-17T13:32:32.209+00:00",
  "updatedAt": "2025-03-17T13:32:32.209+00:00"
}

Erros: SUB_PORTFOLIO_NAME_ALREADY_EXISTS, PORTFOLIO_INACTIVE, USER_COMPANY_MISMATCH (quando user.id informado é inválido).

GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios

Lista carteiras do portfolio com indicadores resumidos para cada uma. Esta é a porta de entrada padrão da UI quando o gestor abre um portfolio.

Permissão requerida: portfolio:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
`status`	Enum	Não	Filtrar por `ACTIVE` ou `INACTIVE`.
`orderBy`	Enum	Não	Ordenação: `name`, `createdAt`. Default: `name`.
`order`	Enum	Não	`asc` ou `desc`. Default: `asc`.
`offset`	Integer	Não	Default: 0.
`limit`	Integer	Não	Default: 20. Máximo: 100.

Response 200 OK:

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "portfolioId": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
      "name": "Analista João — Região Sul",
      "description": "Contratos da região Sul sob responsabilidade do analista João.",
      "user": {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "name": "João Silva"
      },
      "status": "ACTIVE",
      "summary": {
        "activeContracts": 12,
        "value": 3500000.00,
        "overdue": 100000.00
      },
      "createdAt": "2025-03-17T13:32:32.209+00:00"
    }
  ],
  "nextPage": false
}

GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId

Detalhe da carteira com SubPortfolioSummary completo (mesma estrutura do PortfolioSummary, ver seção 2.2/2.3.1, mas no escopo desta carteira).

Permissão requerida: portfolio:read

Query params:

Parâmetro	Tipo	Obrigatório	Descrição
`startDate`	Datetime (UTC)	Não	Início do período para summary. Default: primeiro dia do ano corrente.
`endDate`	Datetime (UTC)	Não	Fim do período. Default: último dia do ano corrente.

Response 200 OK: Mesma estrutura do GET /portfolios/:portfolioId, mas restrita aos contratos desta carteira (ver PortfolioSummary em 2.2 para os campos do summary).

PATCH /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId

Atualiza atributos editáveis da carteira: name, description, user (envia apenas { "user": { "id": "..." } }).

Erros: SUB_PORTFOLIO_NAME_ALREADY_EXISTS, SUB_PORTFOLIO_INACTIVE, USER_COMPANY_MISMATCH.

PUT /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/status

Ativa ou desativa a carteira (substituição completa do status).

Erros: SUB_PORTFOLIO_HAS_CONTRACTS.

5.3. Vinculação de contratos a carteiras

A vinculação de um contrato a uma carteira não é feita por endpoint próprio neste módulo. É representada como o campo subPortfolioId (obrigatório) na entidade Contract e definida no POST do contrato (ver Contratos.md). Para mover um contrato entre carteiras do mesmo portfolio, atualiza-se o campo via PATCH .../portfolios/:portfolioId/contracts/:contractId informando o novo subPortfolioId.

Criação: o subPortfolioId é obrigatório no POST do contrato (POST .../portfolios/:portfolioId/contracts).

Movimentação: PATCH .../contracts/:contractId com novo subPortfolioId no body.

Listar contratos de uma carteira específica: GET .../portfolios/:portfolioId/contracts?subPortfolioId=... ou via endpoint dedicado da carteira (ver Contratos.md).

Não é permitido subPortfolioId = null — todo contrato sempre pertence a uma carteira.

Permissão requerida: portfolio:assign_contract.

5.4. Vínculos de Usuários — Portfolio

Atribui usuários do tenant a portfolios inteiros. Usuários atribuídos enxergam todos os contratos do portfolio (incluindo carteiras).

POST /v2/companies/:companyId/portfolios/:portfolioId/assigned-users

Vincula um usuário a um portfolio.

Permissão requerida: portfolio:assign_user

Request body:

{
  "user": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "role": "d290f1..."
  }
}

Response 201 Created:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "portfolioId": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "user": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "João Silva"
  },
  "assignedBy": {
    "id": "a1b2c3d4-1111-2222-3333-444455556666",
    "name": "Maria Santos"
  },
  "assignedAt": "2025-03-17T13:32:32.209+00:00",
  "createdAt": "2025-03-17T13:32:32.209+00:00"
}

Erros: USER_ALREADY_ASSIGNED, USER_COMPANY_MISMATCH, INTERNAL_USER_NOT_ALLOWED.

GET /v2/companies/:companyId/portfolios/:portfolioId/assigned-users

Lista usuários vinculados ao portfolio. Paginação padrão. Cada item segue o formato do response do POST.

DELETE /v2/companies/:companyId/portfolios/:portfolioId/assigned-users/:userId

Remove vínculo do usuário com o portfolio. O :userId na rota é o user.id.

Response 204 No Content

Erros: USER_ASSIGNMENT_NOT_FOUND.

5.5. Vínculos de Usuários — Carteira (subPortfolio)

Atribui usuários do tenant a uma carteira específica. Usuários atribuídos apenas a carteira(s) — sem atribuição direta ao portfolio que as contém — enxergam somente os contratos daquela(s) carteira(s).

POST /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users

Vincula um usuário a uma carteira.

Permissão requerida: portfolio:assign_user

Request body:

{
  "user": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "role": "d290f1..."
  }
}

Response 201 Created:

{
  "id": "b9d3f1aa-22cc-4e72-b430-1e45a3d6e001",
  "subPortfolioId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "user":[
   {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "João Silva",
    "role": "d290f1..."
  },  
   {
    "id": "d2901...",
    "name": "Pedro Henrique",
    "role": "d290f1..."
  }
  ],
  "assignedBy": {
    "id": "a1b2c3d4-1111-2222-3333-444455556666",
    "name": "Maria Santos"
  },
  "assignedAt": "2025-03-17T13:32:32.209+00:00",
  "createdAt": "2025-03-17T13:32:32.209+00:00"
}

Erros: USER_ALREADY_ASSIGNED, USER_COMPANY_MISMATCH, INTERNAL_USER_NOT_ALLOWED.

GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users

Lista usuários vinculados à carteira. Paginação padrão. Cada item segue o formato do response do POST.

DELETE /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users/:userId

Remove vínculo do usuário com a carteira. O :userId na rota é o user.id.

Response 204 No Content

Erros: USER_ASSIGNMENT_NOT_FOUND.

Gestão da carteira

Carteiras (Portfolios) — Regras de Negócio#

1. Conceito#

1.1. Modelo de organização#

1.2. Modelo de acesso#

2. Estruturas de Dados#

2.1. Portfolio#

2.2. PortfolioSummary (objeto calculado)#

Indicadores principais#

Análise de efetividade#

2.3. SubPortfolio (Carteira)#

2.3.1. SubPortfolioSummary (objeto calculado)#

2.4. Vínculo Contrato ↔ Carteira#

2.5. PortfolioUser (Vínculo Usuário ↔ Portfolio)#

2.6. SubPortfolioUser (Vínculo Usuário ↔ Carteira)#

3. Regras de Negócio#

3.1. Portfolio#

3.2. Carteiras#

3.3. Vínculo Contrato ↔ Carteira#

3.4. Vínculo Usuário ↔ Portfolio#

3.5. Vínculo Usuário ↔ Carteira#

4. Padrão de Erros e Paginação#

4.1. Formato padrão de erro#

4.2. Códigos de erro comuns#

4.3. Códigos de erro específicos#

4.4. Formato padrão de paginação#

5. Endpoints#

5.1. CRUD de Portfolios#

POST /v2/companies/:companyId/portfolios#

GET /v2/companies/:companyId/portfolios#

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

PATCH /v2/companies/:companyId/portfolios/:portfolioId#

PUT /v2/companies/:companyId/portfolios/:portfolioId/status#

5.2. Carteiras#

POST /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios#

GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios#

GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId#

PATCH /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId#

PUT /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/status#

5.3. Vinculação de contratos a carteiras#

5.4. Vínculos de Usuários — Portfolio#

POST /v2/companies/:companyId/portfolios/:portfolioId/assigned-users#

GET /v2/companies/:companyId/portfolios/:portfolioId/assigned-users#

DELETE /v2/companies/:companyId/portfolios/:portfolioId/assigned-users/:userId#

5.5. Vínculos de Usuários — Carteira (subPortfolio)#

POST /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users#

GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users#

DELETE /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users/:userId#

Carteiras (Portfolios) — Regras de Negócio

1. Conceito

1.1. Modelo de organização

1.2. Modelo de acesso

2. Estruturas de Dados

2.1. Portfolio

2.2. PortfolioSummary (objeto calculado)

Indicadores principais

Análise de efetividade

2.3. SubPortfolio (Carteira)

2.3.1. SubPortfolioSummary (objeto calculado)

2.4. Vínculo Contrato ↔ Carteira

2.5. PortfolioUser (Vínculo Usuário ↔ Portfolio)

2.6. SubPortfolioUser (Vínculo Usuário ↔ Carteira)

3. Regras de Negócio

3.1. Portfolio

3.2. Carteiras

3.3. Vínculo Contrato ↔ Carteira

3.4. Vínculo Usuário ↔ Portfolio

3.5. Vínculo Usuário ↔ Carteira

4. Padrão de Erros e Paginação

4.1. Formato padrão de erro

4.2. Códigos de erro comuns

4.3. Códigos de erro específicos

4.4. Formato padrão de paginação

5. Endpoints

5.1. CRUD de Portfolios

POST /v2/companies/:companyId/portfolios

GET /v2/companies/:companyId/portfolios

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

PATCH /v2/companies/:companyId/portfolios/:portfolioId

PUT /v2/companies/:companyId/portfolios/:portfolioId/status

5.2. Carteiras

POST /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios

GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios

GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId

PATCH /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId

PUT /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/status

5.3. Vinculação de contratos a carteiras

5.4. Vínculos de Usuários — Portfolio

POST /v2/companies/:companyId/portfolios/:portfolioId/assigned-users

GET /v2/companies/:companyId/portfolios/:portfolioId/assigned-users

DELETE /v2/companies/:companyId/portfolios/:portfolioId/assigned-users/:userId

5.5. Vínculos de Usuários — Carteira (subPortfolio)

POST /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users

GET /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users

DELETE /v2/companies/:companyId/portfolios/:portfolioId/sub-portfolios/:subPortfolioId/assigned-users/:userId