--- title: 7.2. Posições diárias 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.2.%20Posi%C3%A7%C3%B5es%20di%C3%A1rias/ --- # 7.2. Posições diárias ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ---------------------------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/public/api/v1.1/cartao/contratos/{idContrato}/posicoes-diarias` | --- ## 🧾 Descrição Retorna a **série histórica de posições de um contrato**, de forma paginada. Cada registro é a posição do contrato em um dia, com os **mesmos totais** de [7.1. Posição do contrato](7.1.%20Posição%20do%20contrato.md). Serve para **acompanhar a evolução** do contrato: quanto a agenda comprometia em cada dia, quanto era esperado, quanto entrou em conta e como o saldo em aberto foi caindo (ou não). É a base natural para gráficos de curva de liquidação, fechamento contábil e conferência retroativa. Vale para os dois tipos de contrato (`1` = Troca de titularidade e `2` = Garantia). 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. O retorno é o mesmo nos dois casos. --- ## 📤 Requisição ### 🔎 Path Params | Parâmetro | Tipo | Obrigatório | Descrição | | ---------- | ------ | ----------- | --------------------------------------------------------- | | idContrato | string | Sim | GUID do contrato na plataforma **VeFlow**. | ### 🔎 Query Params | Parâmetro | Tipo | Obrigatório | Descrição | | ---------------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------- | | dataInicio | string | Não | Início do intervalo (inclusivo), no formato `YYYY-MM-DD`. Se omitido, considera os últimos 30 dias corridos. | | dataFim | string | Não | Fim do intervalo (inclusivo), no formato `YYYY-MM-DD`. Se omitido, considera a data atual. | | 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: `dataReferencia`, `liquidado`, `emAberto`. Padrão `dataReferencia`. | | direcaoOrdem | string | Não | Direção da ordenação: `asc` ou `desc`. Padrão `desc` (dia mais recente primeiro). | **Regras e formatos** * Datas no formato `YYYY-MM-DD`; `dataFim` >= `dataInicio`. * O intervalo não pode ultrapassar **366 dias**. * Só existem registros a partir da data de assinatura do contrato; dias anteriores são ignorados no recorte. * A posição de cada dia é **fechada após a rodada de conciliação das 19:00**. O registro do dia corrente reflete o último processamento já concluído e pode mudar até esse horário. --- ## 🧪 Exemplo de cURL ```bash curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/contratos/19710560-04CD-4E48-881D-D38350B39079/posicoes-diarias?dataInicio=2025-09-01&dataFim=2025-09-30&indicePagina=1&tamanhoDaPagina=20&ordem=dataReferencia&direcaoOrdem=desc" \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" ``` --- ## 📥 Responses ### ✅ 200 OK ```json { "registros": [ { "dataReferencia": "2025-09-30", "status": 6, "totais": { "contratado": 150000.00, "comprometido": 148500.00, "esperado": 120000.00, "liquidado": 118800.00, "emAberto": 29700.00, "chargeback": 1500.00, "divergencia": -1200.00, "percentualLiquidado": 80.0000 }, "urs": { "total": 320, "liquidadas": 240, "liquidadasParcialmente": 8, "emAberto": 60, "naoLiquidadas": 4, "removidas": 3, "rejeitadas": 2, "canceladas": 3 }, "dataUltimaLiquidacao": "2025-09-29" }, { "dataReferencia": "2025-09-29", "status": 6, "totais": { "contratado": 150000.00, "comprometido": 148500.00, "esperado": 115000.00, "liquidado": 113900.00, "emAberto": 34600.00, "chargeback": 1500.00, "divergencia": -1100.00, "percentualLiquidado": 76.6997 }, "urs": { "total": 320, "liquidadas": 231, "liquidadasParcialmente": 8, "emAberto": 69, "naoLiquidadas": 4, "removidas": 3, "rejeitadas": 2, "canceladas": 3 }, "dataUltimaLiquidacao": "2025-09-29" } ], "paginacao": { "paginaAtual": 1, "paginaTotal": 2, "paginaQuantidadeRegistro": 20, "quantidadeRegistros": 30, "temPaginaAnterior": false, "temProximaPagina": true }, "mensagem": null } ``` ### 🧾 Detalhamento dos Campos #### 🔹 registros | Campo | Tipo | Descrição | | -------------------- | ----------- | ------------------------------------------------------------------------------------------- | | dataReferencia | string | Dia a que a posição se refere (`YYYY-MM-DD`). | | status | integer | Status do contrato naquele dia (ver tabela abaixo). | | totais | object | Totais financeiros do contrato no dia (ver abaixo). | | urs | object | Contadores de URs por situação de liquidação no dia (ver abaixo). | | dataUltimaLiquidacao | string/null | Data do último crédito conciliado até aquele dia. `null` enquanto nenhuma UR liquidou. | #### 🔹 registros[].totais | Campo | Tipo | Descrição | | ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | contratado | number | O que foi contratado na assinatura. Constante em toda a série. | | comprometido | number | O que a agenda dizia naquele dia: valor das URs efetivamente comprometidas com o contrato. | | esperado | number | O que a agenda havia anunciado que liquidaria até aquele dia. | | liquidado | number | O que efetivamente havia entrado em conta e sido conciliado até aquele dia. | | emAberto | number | O que faltava liquidar: `comprometido - liquidado`. | | chargeback | number | Redução de posição ou estorno acumulado até aquele dia. | | divergencia | number | `liquidado - esperado` no dia. Negativa quando entrou menos do que a agenda anunciou. | | percentualLiquidado | number | `liquidado / comprometido`, em percentual, com 4 casas decimais. | #### 🔹 registros[].urs | Campo | Tipo | Descrição | | ---------------------- | ------- | ---------------------------------------------------------------------------------- | | total | integer | Quantidade total de URs vinculadas ao contrato naquele dia. | | liquidadas | integer | URs com crédito integral conciliado. | | liquidadasParcialmente | integer | URs com crédito conciliado menor que o esperado. | | emAberto | integer | URs cuja data prevista ainda não havia vencido (ou cujo dia não havia fechado). | | naoLiquidadas | integer | URs vencidas, com o dia fechado, sem crédito recebido. | | removidas | integer | URs retiradas do contrato antes da liquidação. | | rejeitadas | integer | URs recusadas no registro do contrato. | | canceladas | integer | URs canceladas na registradora após o registro. | #### 🔹 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). | --- ### 🔢 Status do contrato | Código | Significado | | ------ | --------------------- | | 1 | Aguardando registro | | 2 | Registrando | | 3 | Falha no registro | | 4 | Aguardando liquidação | | 5 | Cancelado | | 6 | Em liquidação | | 7 | Liquidado | | 8 | Em cancelamento | | 9 | Falha no cancelamento | --- ### ❌ 404 Not Found ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Atenção", "status": 404, "erros": [ "Contrato não encontrado." ] } ``` --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "Campo 'dataFim' deve ser maior ou igual a 'dataInicio'.", "O intervalo entre 'dataInicio' e 'dataFim' não pode ultrapassar 366 dias.", "Campo 'direcaoOrdem' inválido. Valores aceitos: asc, desc." ] } ``` --- ## 🕒 Observações * Um contrato sem nenhuma posição no intervalo devolve `200 OK` com `registros` vazio e `paginacao.quantidadeRegistros` igual a `0`. Contrato inexistente devolve `404`. * A quebra por parcela **não** é retornada aqui. Para ver quanto de cada parcela de uma garantia parcelada já foi coberto por crédito recebido, consulte [7.1. Posição do contrato](7.1.%20Posição%20do%20contrato.md). * Dias sem movimento também aparecem na série: repetem os totais do dia anterior, o que permite plotar a curva sem tratar lacunas. * `liquidado` só cresce com crédito confirmado e conciliado. Uma agenda que anuncia liquidação move `esperado`, nunca `liquidado`. * Os créditos em conta que alimentam a série são recebidos 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. * Quedas de `comprometido` de um dia para o outro, acompanhadas de aumento de `chargeback`, indicam **redução de posição da agenda**. Essas ocorrências ficam detalhadas em [7.4. Divergências](7.4.%20Divergências.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).