7.2. Posições diárias¶

🔗 Endpoint¶

Método	URL
	`/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.

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¶

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¶

{
  "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¶

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

❌ 400 Bad Request¶

{
  "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.
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.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.