7.5. Posição por estabelecimento¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1.1/cartao/posicao/estabelecimentos`

🧾 Descrição¶

Retorna, de forma paginada, a visão consolidada da carteira por estabelecimento comercial (EC): para cada CNPJ, quantos contratos existem, quanto foi contratado, quanto já liquidou, quanto está em aberto e como esse saldo em aberto se distribui em faixas de aging — o que está a vencer e o que já venceu.

É a visão de carteira: em vez de olhar contrato por contrato, o cliente vê o risco concentrado por EC e identifica rapidamente quem está atrasando crédito.

A consolidação soma os dois tipos de contrato (1 = Troca de titularidade e 2 = Garantia) do mesmo EC. Na antecipação a liquidação vem da baixa da UR cedida ao fundo; na garantia, da conciliação da movimentação bancária com a agenda — mas o número consolidado é lido da mesma forma.

📤 Requisição¶

🔎 Query Params¶

Parâmetro	Tipo	Obrigatório	Descrição
dataReferencia	string	Não	Data da posição, no formato `YYYY-MM-DD`. Se omitida, considera a data atual.
idOperacao	number	Não	ID da operação atrelada (valor definido pelo time de implantação). Restringe a carteira a uma operação.
cnpj	string	Não	CNPJ do estabelecimento comercial (somente números, sem formatação).
indicePagina	integer	Não	Página desejada (base 1). Padrão `1`.
tamanhoDaPagina	integer	Não	Quantidade de registros por página. Padrão `20`.
ordem	string	Não	Campo de ordenação. Valores aceitos: `nome`, `valorContratado`, `valorEmAberto`, `valorChargeback`. Padrão `valorEmAberto`.
direcaoOrdem	string	Não	Direção da ordenação: `asc` ou `desc`. Padrão `desc` (maior saldo em aberto primeiro).

Regras e formatos

dataReferencia define o corte do aging: o que vence depois dela entra em aVencer, o que venceu antes e segue sem crédito entra em vencido.
cnpj: somente dígitos (ex.: 12345678000199).
As faixas de aging são contadas em dias corridos a partir da dataReferencia, com base na dataPrevistaLiquidacao das URs em aberto.

🧪 Exemplo de cURL¶

curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/posicao/estabelecimentos?dataReferencia=2025-09-30&idOperacao=1&indicePagina=1&tamanhoDaPagina=20&ordem=valorEmAberto&direcaoOrdem=desc" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

📥 Responses¶

✅ 200 OK¶

{
  "registros": [
    {
      "cnpj": "12345678000199",
      "nome": "LOJA EXEMPLO LTDA",
      "quantidadeContratos": 4,
      "valorContratado": 150000.00,
      "valorLiquidado": 118800.00,
      "valorEmAberto": 29700.00,
      "valorChargeback": 1500.00,
      "aVencer": {
        "ate7Dias": 8000.00,
        "de8a15Dias": 6500.00,
        "de16a30Dias": 7000.00,
        "de31a60Dias": 3200.00,
        "acima60Dias": 0.00,
        "total": 24700.00
      },
      "vencido": {
        "ate7Dias": 3000.00,
        "de8a15Dias": 1200.00,
        "de16a30Dias": 800.00,
        "de31a60Dias": 0.00,
        "acima60Dias": 0.00,
        "total": 5000.00
      }
    }
  ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 3,
    "paginaQuantidadeRegistro": 20,
    "quantidadeRegistros": 47,
    "temPaginaAnterior": false,
    "temProximaPagina": true
  },
  "mensagem": null
}

🧾 Detalhamento dos Campos¶

🔹 registros¶

Campo	Tipo	Descrição
cnpj	string	CNPJ do estabelecimento comercial (somente números).
nome	string	Nome do estabelecimento comercial.
quantidadeContratos	integer	Quantidade de contratos ativos do EC considerados na posição, somando antecipação e garantia.
valorContratado	number	Soma do valor contratado dos contratos do EC.
valorLiquidado	number	Soma do que efetivamente entrou em conta e foi conciliado nos contratos do EC.
valorEmAberto	number	Soma do que falta liquidar. Equivale a `aVencer.total + vencido.total`.
valorChargeback	number	Soma das reduções de posição e estornos apurados nos contratos do EC.
aVencer	object	Distribuição do saldo em aberto a vencer, por faixa de aging (ver abaixo).
vencido	object	Distribuição do saldo em aberto já vencido, por faixa de aging (ver abaixo).

🔹 aVencer¶

Saldo em aberto de URs cuja dataPrevistaLiquidacao é posterior à dataReferencia. As faixas contam quantos dias faltam para o vencimento.

Campo	Tipo	Descrição
ate7Dias	number	Vence em até 7 dias corridos.
de8a15Dias	number	Vence entre 8 e 15 dias corridos.
de16a30Dias	number	Vence entre 16 e 30 dias corridos.
de31a60Dias	number	Vence entre 31 e 60 dias corridos.
acima60Dias	number	Vence em mais de 60 dias corridos.
total	number	Soma das faixas a vencer.

🔹 vencido¶

Saldo em aberto de URs cuja dataPrevistaLiquidacao é anterior à dataReferencia e que seguem sem crédito recebido. As faixas contam quantos dias já se passaram do vencimento.

Campo	Tipo	Descrição
ate7Dias	number	Vencido há até 7 dias corridos.
de8a15Dias	number	Vencido entre 8 e 15 dias corridos.
de16a30Dias	number	Vencido entre 16 e 30 dias corridos.
de31a60Dias	number	Vencido entre 31 e 60 dias corridos.
acima60Dias	number	Vencido há mais de 60 dias corridos.
total	number	Soma das faixas vencidas.

🔹 paginacao¶

Campo	Tipo	Descrição
paginaAtual	integer	Página atual do retorno (base 1).
paginaTotal	integer	Total de páginas disponíveis.
paginaQuantidadeRegistro	integer	Quantidade de registros por página.
quantidadeRegistros	integer	Total de registros encontrados.
temPaginaAnterior	boolean	Indica se existe página anterior.
temProximaPagina	boolean	Indica se existe próxima página.

🔹 mensagem¶

Campo	Tipo	Descrição
mensagem	string/null	Mensagem informativa opcional do retorno (`null` nos casos de sucesso simples).

❌ 400 Bad Request¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'cnpj' inválido. Informe somente números.",
    "Campo 'dataReferencia' inválido. Formato esperado: YYYY-MM-DD.",
    "Campo 'ordem' inválido. Valores aceitos: nome, valorContratado, valorEmAberto, valorChargeback."
  ]
}

❌ 404 Not Found¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "titulo": "Atenção",
  "status": 404,
  "erros": [
    "Operação não encontrada."
  ]
}

Retornado quando o idOperacao informado no filtro não existe. Filtros válidos sem resultado devolvem 200 OK com registros vazio.

🕒 Observações¶

valorEmAberto fecha exatamente com aVencer.total + vencido.total. Use essa igualdade como conferência da carteira.
O que aparece em vencido é o saldo que já deveria ter entrado em conta e não entrou. Cada linha vencida tem uma contrapartida na fila de exceções — ver 7.4. Divergências, tipo 1 (Agenda sem crédito).
A rodada de conciliação é recorrente ao longo do dia e a última é às 19:00. Uma UR vencida no dia corrente só migra de aVencer para vencido depois dessa rodada.
Os créditos que reduzem o saldo em aberto chegam pela integração de liquidações — ver 6.1. Envio dos créditos em conta — e devem ser enviados após as 10:05, por causa do processamento batch das agendas às 10:00.
valorLiquidado só considera crédito confirmado e conciliado. Agenda anunciada, sozinha, não reduz o saldo em aberto.
Contrato de garantia não tem deságio: a carteira consolidada nunca traz valor nominal, desconto, aquisição nem taxa. Esses valores existem somente em antecipação (troca de titularidade), onde houve cessão da UR ao fundo.
Para descer do EC para o contrato, use 7.1. Posição do contrato; para acompanhar a evolução diária, 7.2. Posições diárias; para auditar uma UR, 7.3. Extrato de conciliação da UR.
O cnpj consolidado aqui é o mesmo informado na solicitação da agenda — ver 4.1. Solicitar agenda.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.