--- title: 7.5. Posição por estabelecimento url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/7.%20Concilia%C3%A7%C3%A3o/v1.1/7.5.%20Posi%C3%A7%C3%A3o%20por%20estabelecimento/ --- # 7.5. Posição por estabelecimento ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ---------------------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/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 ```bash 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 ```json { "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 ```json { "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 ```json { "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](7.4.%20Divergências.md), 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](7.1.%20Posição%20do%20contrato.md); para acompanhar a evolução diária, [7.2. Posições diárias](7.2.%20Posições%20diárias.md); para auditar uma UR, [7.3. Extrato de conciliação da UR](7.3.%20Extrato%20de%20conciliação%20da%20UR.md). * O `cnpj` consolidado aqui é o mesmo informado na solicitação da agenda — ver [4.1. Solicitar agenda](../../4.%20Agenda%20de%20recebíveis/v1.1/4.1.%20Solicitar%20agenda.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).