7.1. Posição do contrato¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1.1/cartao/contratos/{idContrato}/posicao`

🧾 Descrição¶

Retorna a posição consolidada de um contrato em uma data de referência: quanto foi contratado, quanto a agenda ainda garante hoje, quanto já entrou em conta e quanto falta liquidar.

Este é o endpoint que responde a pergunta operacional do dia a dia — "esta UR liquidou ou está em aberto?" — no nível do contrato. A resposta é a mesma para os dois tipos de contrato (1 = Troca de titularidade e 2 = Garantia); muda apenas a origem do dado de liquidação, que a plataforma resolve internamente:

Na troca de titularidade (antecipação), a liquidação vem da baixa da UR cedida ao fundo.
Na garantia, a liquidação vem da conciliação da movimentação bancária com a agenda.

Quem consome a API não precisa tratar essa diferença: os campos e os significados são idênticos 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
dataReferencia	string	Não	Data da posição, no formato `YYYY-MM-DD`. Se omitida, considera a data atual.

Regras e formatos

dataReferencia não pode ser anterior à data de assinatura do contrato.
dataReferencia recorta o campo totais.esperado: só entra no esperado o que a agenda anunciou para liquidar até essa data (inclusive).
Para acompanhar a evolução dia a dia em vez de um único retrato, use 7.2. Posições diárias.

🧪 Exemplo de cURL¶

curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/contratos/19710560-04CD-4E48-881D-D38350B39079/posicao?dataReferencia=2025-09-30" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

📥 Responses¶

✅ 200 OK¶

{
  "identificador": "19710560-04CD-4E48-881D-D38350B39079",
  "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
  },
  "parcelas": [
    {
      "numero": 1,
      "data": "2025-09-10",
      "valor": 50000.00,
      "garantido": 50000.00,
      "liquidado": 50000.00,
      "emAberto": 0.00,
      "situacao": 3
    },
    {
      "numero": 2,
      "data": "2025-10-10",
      "valor": 50000.00,
      "garantido": 49500.00,
      "liquidado": 48800.00,
      "emAberto": 700.00,
      "situacao": 2
    },
    {
      "numero": 3,
      "data": "2025-11-10",
      "valor": 50000.00,
      "garantido": 49000.00,
      "liquidado": 20000.00,
      "emAberto": 29000.00,
      "situacao": 1
    }
  ],
  "dataUltimaLiquidacao": "2025-09-29"
}

🧾 Detalhamento dos Campos¶

🔹 Nível raiz¶

Campo	Tipo	Descrição
identificador	string	GUID do contrato consultado.
dataReferencia	string	Data da posição retornada (`YYYY-MM-DD`).
status	integer	Status do contrato na data de referência (ver tabela abaixo).
totais	object	Totais financeiros do contrato (ver abaixo).
urs	object	Contadores de URs do contrato por situação de liquidação (ver abaixo).
parcelas	array	Posição por parcela. Preenchido apenas em contrato de garantia parcelada; vazio nos demais.
dataUltimaLiquidacao	string/null	Data do último crédito conciliado no contrato. `null` quando nenhuma UR liquidou ainda.

🔹 totais¶

Campo	Tipo	Descrição
contratado	number	O que foi contratado: o valor fechado na assinatura do contrato. Não muda ao longo da vida do contrato.
comprometido	number	O que a agenda diz hoje: soma do valor das URs efetivamente comprometidas com o contrato na posição mais recente da registradora. Cai quando há redução de posição.
esperado	number	O que a agenda anunciou que liquidaria até a `dataReferencia`. É a promessa de crédito, não o crédito.
liquidado	number	O que efetivamente entrou em conta e foi conciliado. Só cresce quando existe crédito confirmado — nunca por previsão.
emAberto	number	O que falta liquidar: `comprometido - liquidado`.
chargeback	number	Redução de posição ou estorno: valor que a agenda tinha anunciado e deixou de existir, por chargeback da venda ou ajuste da credenciadora/registradora.
divergencia	number	Diferença entre o que entrou e o que era esperado: `liquidado - esperado`. Negativa quando entrou menos do que a agenda anunciou; positiva quando entrou mais.
percentualLiquidado	number	`liquidado / comprometido`, em percentual, com 4 casas decimais.

🔹 urs¶

Campo	Tipo	Descrição
total	integer	Quantidade total de URs vinculadas ao contrato.
liquidadas	integer	URs cujo crédito entrou integralmente e foi conciliado.
liquidadasParcialmente	integer	URs com crédito conciliado menor que o esperado.
emAberto	integer	URs cuja `dataPrevistaLiquidacao` ainda não venceu (ou cujo dia ainda não fechou).
naoLiquidadas	integer	URs cuja data prevista já passou, o dia já fechou e o crédito não chegou. Geram divergência do tipo Agenda sem crédito.
removidas	integer	URs retiradas do contrato antes da liquidação.
rejeitadas	integer	URs recusadas no registro do contrato (indisponíveis ou já oneradas por terceiro).
canceladas	integer	URs canceladas na registradora após o registro.

🔹 parcelas¶

Campo	Tipo	Descrição
numero	integer	Número da parcela.
data	string	Data de vencimento da parcela (`YYYY-MM-DD`).
valor	number	Valor da parcela definido no contrato.
garantido	number	Valor de URs comprometido para cobrir a parcela, conforme a posição atual da agenda.
liquidado	number	Quanto da parcela já foi coberto por crédito efetivamente recebido e conciliado.
emAberto	number	Quanto ainda falta para cobrir a parcela: `garantido - liquidado`.
situacao	integer	Situação da parcela (ver tabela abaixo).

🔢 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

🔢 Situação da parcela¶

Código	Significado	Aplicação
1	Em aberto	Parcela ainda não vencida e sem cobertura integral por crédito recebido.
2	Parcialmente coberta	Parte do valor garantido já entrou em conta e foi conciliado.
3	Coberta	Crédito recebido cobre integralmente o valor garantido da parcela.
4	Vencida em aberto	Data da parcela já passou e o crédito recebido não cobriu o valor garantido.

❌ 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 'dataReferencia' inválido. Formato esperado: YYYY-MM-DD.",
    "dataReferencia não pode ser anterior à data de assinatura do contrato."
  ]
}

🕒 Observações¶

A posição vale para qualquer tipo de contrato. tipoContrato tem somente dois valores: 1 = Troca de titularidade e 2 = Garantia. O retorno deste endpoint é idêntico nos dois casos.
Contrato de garantia não tem deságio. Por isso a posição 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, e são consultados em 5.3. Detalhes do contrato.
liquidado nunca é preenchido por previsão. Enquanto o crédito não é confirmado, o valor permanece em emAberto.
O motor de conciliação roda de forma recorrente ao longo do dia e o último processamento é às 19:00. Só depois dessa rodada uma UR vencida passa de emAberto para naoLiquidadas, e a posição do dia é considerada fechada.
Os créditos em conta usados na conciliação são recebidos pela integração de liquidações — ver 6.1. Envio dos créditos em conta. Eles devem ser enviados após as 10:05, por causa do processamento batch das agendas às 10:00.
Cada mudança de posição de UR apurada na conciliação também é notificada por webhook — ver 3.3. Atualizações da UR.
Para investigar uma UR específica desta posição (o que a agenda anunciou, quais créditos chegaram e quais ônus existiam sobre ela), use 7.3. Extrato de conciliação da UR. Para tratar as exceções, use 7.4. Divergências.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.