--- title: 7.1. Posição do contrato 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.1.%20Posi%C3%A7%C3%A3o%20do%20contrato/ --- # 7.1. Posição do contrato ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ------------------------------------------------------------ | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/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](7.2.%20Posições%20diárias.md). --- ## 🧪 Exemplo de cURL ```bash 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 ```json { "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 ```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 '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](../../5.%20Contrato%20de%20recebíveis/v1.1/5.3.%20Detalhes%20do%20contrato.md). * `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](../../3.%20Notificações%20-%20WebHook/3.3.%20Atualizações%20da%20UR.md). * 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](7.3.%20Extrato%20de%20conciliação%20da%20UR.md). Para tratar as exceções, use [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).