4.5. Volume em Aberto

Volume em Aberto¶

Endpoints de agregação que retornam o volume em aberto de títulos do fundo, agrupados por cedente ou por sacado, com quebra por faixas de vencimento (a vencer e vencidos).

Útil para dashboards de exposição, dossiês de crédito por cedente/sacado e análise de concentração.

Os endpoints consideram apenas títulos em aberto no fundo: portador igual ao fundo, sem data de liquidação e com data de aquisição menor ou igual à data de referência. Filtros adicionais podem ser combinados via query string.

Por Cedente¶

Método	URL
	`https://BASE_URL/public/v1/recebiveis/titulos/volume-em-aberto/cedente`

Retorna o volume em aberto agregado por cedente (empresa originadora dos recebíveis).

Por Sacado¶

Método	URL
	`https://BASE_URL/public/v1/recebiveis/titulos/volume-em-aberto/sacado`

Retorna o volume em aberto agregado por sacado (devedor dos recebíveis).

Por Documento do Cedente¶

Método	URL
	`https://BASE_URL/public/v1/recebiveis/titulos/volume-em-aberto/cedente/por-documento/{cpfCnpj}`

Retorna o volume em aberto de um cedente, identificado pelo CPF ou CNPJ em vez do id. O cálculo e o formato da resposta são os mesmos do endpoint Por Cedente, restritos a esse cedente: registros traz no máximo um item.

Path param	Tipo	Descrição
`cpfCnpj`	string	CPF (11 dígitos) ou CNPJ (14 dígitos) do cedente, com ou sem máscara (pontos, traço e barra são removidos).

Exemplo de cURL

curl -X GET "https://BASE_URL/public/v1/recebiveis/titulos/volume-em-aberto/cedente/por-documento/12345678000190?DataReferencia=2026-11-02" \
  -H "Authorization: Bearer {token}" \
  -H "GrupoEconomico: {grupo}"

Cedente sem título em aberto

Quando o documento é de um cadastro do grupo econômico, mas não há título em aberto para ele (com os filtros informados), a resposta é 200 OK com registros vazio. O 404 fica só para o documento que não tem cadastro no grupo econômico.

Query parameters (todos)¶

Parâmetro	Tipo	Obrigatório	Descrição
`DataReferencia`	string (date)	Não	Data-base para o cálculo. Quando omitida, usa a data atual (UTC). Formato `YYYY-MM-DD`.
`IdCessionario`	long	Não	Filtra pelo identificador do cessionário (fundo) da operação dos títulos.
`IdOperacao`	long	Não	Filtra pelo identificador da operação.
`IndicePagina`	int	Não	Página (base 1). Padrão `1`.
`TamanhoDaPagina`	int	Não	Tamanho da página. Padrão `20`.
`Ordem`	string	Não	Campo de ordenação. Padrão `ValorNominalTotal`.
`DirecaoOrdem`	string	Não	`asc` ou `desc`. Padrão `desc`.

Query parameters são case-insensitive (indicePagina ou IndicePagina funcionam).

No endpoint Por Documento do Cedente, Ordem e DirecaoOrdem não têm efeito: a resposta tem no máximo um registro.

Resposta (200 OK)¶

Ambos os endpoints retornam o envelope padrão de paginação (RetornoPaginado<T>) com a diferença sendo a estrutura de cada item em registros[].

Estrutura do envelope¶

{
  "registros": [ /* itens VolumeEmAbertoCedenteDto ou VolumeEmAbertoSacadoDto */ ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 1,
    "paginaQuantidadeRegistro": 1,
    "quantidadeRegistros": 1,
    "temPaginaAnterior": false,
    "temProximaPagina": false
  },
  "mensagem": null
}

Item — `VolumeEmAbertoCedenteDto` / `VolumeEmAbertoSacadoDto`¶

Campo	Tipo	Descrição
`id`	long	Identificador da empresa cedente (ou sacado).
`nome`	string	Nome do cedente (ou sacado).
`cnpj` / `cpfCnpj`	string	Documento, apenas dígitos. No endpoint por cedente o campo se chama `cnpj`; no endpoint por sacado, `cpfCnpj`.
`tipoPessoa`	int (enum)	`1` = Pessoa Física, `2` = Pessoa Jurídica (derivado pelo tamanho do documento).
`qtdTitulos`	int	Quantidade total de títulos em aberto.
`qtdSacados` / `qtdCedentes`	int	Quantidade distinta de contraparte (sacados no endpoint de cedente; cedentes no endpoint de sacado).
`valorNominalTotal`	decimal	Soma do valor nominal em aberto.
`valorPresenteTotal`	decimal	Soma do valor presente em aberto.
`valorAquisicaoTotal`	decimal	Soma do valor de aquisição em aberto.
`valorSaldoDevedorTotal`	decimal	Soma do saldo devedor em aberto.
`totalAVencerAte5Dias`	decimal	Total a vencer entre 0 e 5 dias.
`totalAVencerAte30Dias`	decimal	Total a vencer entre 6 e 30 dias.
`totalAVencerAte60Dias`	decimal	Total a vencer entre 31 e 60 dias.
`totalAVencerAte90Dias`	decimal	Total a vencer entre 61 e 90 dias.
`totalAVencerAcima90Dias`	decimal	Total a vencer acima de 90 dias.
`totalVencidosAte5Dias`	decimal	Total vencido entre 1 e 5 dias.
`totalVencidosAte30Dias`	decimal	Total vencido entre 6 e 30 dias.
`totalVencidosAte60Dias`	decimal	Total vencido entre 31 e 60 dias.
`totalVencidosAte90Dias`	decimal	Total vencido entre 61 e 90 dias.
`totalVencidosAcima90Dias`	decimal	Total vencido acima de 90 dias.
`qtdAVencerAte5Dias` … `qtdVencidosAcima90Dias`	int	Mesmas faixas em quantidade de títulos.

Exemplo (200 OK)¶

{
  "registros": [
    {
      "id": 301,
      "nome": "Cedente Exemplo LTDA",
      "cnpj": "12345678000190",
      "tipoPessoa": 2,
      "qtdTitulos": 152,
      "qtdSacados": 28,
      "valorNominalTotal": 1850000.00,
      "valorPresenteTotal": 1812345.67,
      "valorAquisicaoTotal": 1740000.00,
      "valorSaldoDevedorTotal": 1850000.00,
      "totalAVencerAte5Dias": 50000.00,
      "totalAVencerAte30Dias": 320000.00,
      "totalAVencerAte60Dias": 480000.00,
      "totalAVencerAte90Dias": 320000.00,
      "totalAVencerAcima90Dias": 500000.00,
      "totalVencidosAte5Dias": 15000.00,
      "totalVencidosAte30Dias": 80000.00,
      "totalVencidosAte60Dias": 50000.00,
      "totalVencidosAte90Dias": 30000.00,
      "totalVencidosAcima90Dias": 5000.00,
      "qtdAVencerAte5Dias": 8,
      "qtdAVencerAte30Dias": 35,
      "qtdAVencerAte60Dias": 42,
      "qtdAVencerAte90Dias": 30,
      "qtdAVencerAcima90Dias": 25,
      "qtdVencidosAte5Dias": 3,
      "qtdVencidosAte30Dias": 6,
      "qtdVencidosAte60Dias": 2,
      "qtdVencidosAte90Dias": 1,
      "qtdVencidosAcima90Dias": 0
    }
  ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 1,
    "paginaQuantidadeRegistro": 1,
    "quantidadeRegistros": 1,
    "temPaginaAnterior": false,
    "temProximaPagina": false
  },
  "mensagem": null
}

Erros (Por Documento do Cedente)¶

Status	Quando	Mensagem
`404 Not Found`	O documento não tem cadastro no grupo econômico.	`Cedente com o documento {cpfCnpj} não encontrado.`
`422 Unprocessable Entity`	CPF com dígito verificador inválido.	`O CPF '{cpfCnpj}' é inválido.`
`422 Unprocessable Entity`	CNPJ com dígito verificador inválido.	`O CNPJ '{cpfCnpj}' é inválido.`
`422 Unprocessable Entity`	Documento que, sem a máscara, não tem 11 nem 14 caracteres.	`O documento '{cpfCnpj}' deve ter 11 dígitos (CPF) ou 14 dígitos (CNPJ).`
`400 Bad Request`	Falha inesperada na consulta.	`Erro ao consultar volume em aberto por documento do cedente` (no envelope `RetornoPadrao`)

Em 404 e 422, {cpfCnpj} é o documento como foi enviado na rota, com a máscara, se houver.

Corpo do 404 e do 422

Nestes dois casos o corpo traz só o texto da mensagem, sem o envelope RetornoPadrao: em text/plain, ou como uma string JSON quando a requisição envia Accept: application/json.

Response Body — 422 Unprocessable Entity

O CNPJ '12.345.678/0001-00' é inválido.