5.5. Detalhes da UR do contrato¶

🔗 Endpoint¶

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

🧾 Descrição¶

Retorna os detalhes de uma UR (Unidade de Recebível) vinculada a um contrato.

O registro é o mesmo de 5.4. Listar URs do contrato, acrescido de dois arrays que explicam a posição da UR:

liquidacoes — os créditos que a plataforma casou com esta UR: o que entrou, quando e por qual movimentação.
efeitos — os ônus que existem sobre a UR, inclusive os de terceiros, com quanto cada um compromete e até quando.

Como na listagem, a UR carrega dois eixos de status independentes:

Campo	Pergunta que responde	Natureza
`statusSolicitacao`	A registradora aceitou esta UR neste contrato?	Estado do vínculo na registradora.
`statusLiquidacao`	O dinheiro entrou?	Estado de caixa, apurado na conciliação.

São coisas diferentes e não se substituem: uma UR pode ter vínculo perfeito (statusSolicitacao = 0) e ainda estar Aguardando o crédito; e pode ter o crédito integral em conta e, mesmo assim, ter tido o vínculo removido depois. Sempre leia os dois campos juntos.

📤 Requisição¶

📋 Parâmetros de rota¶

Parâmetro	Tipo	Obrigatório	Descrição
idContrato	string	Sim	GUID do contrato.
idUr	string	Sim	GUID da UR, devolvido em 5.4. Listar URs do contrato.

Este endpoint não possui query params: ele devolve sempre a posição vigente da UR no contrato informado.

🧪 Exemplo de cURL¶

curl -X GET https://api.veflow.com/public/api/v1.1/cartao/contratos/5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6/urs/7D121577-3C5A-494D-B052-291D9E100D0D \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

📥 Responses¶

✅ 200 OK¶

{
  "id": "7D121577-3C5A-494D-B052-291D9E100D0D",
  "credenciadora": {
    "cnpj": "11223344000155",
    "nome": "CREDENCIADORA EXEMPLO S.A."
  },
  "arranjo": {
    "sigla": "MCC",
    "nome": "Mastercard Crédito"
  },
  "dataPrevistaLiquidacao": "2025-08-14",
  "statusSolicitacao": 0,
  "statusLiquidacao": "LiquidadaParcialmente",
  "valorContratado": 5000.00,
  "valorGarantido": 5000.00,
  "valorLiquidado": 4200.00,
  "valorChargeback": 300.00,
  "valorEmAberto": 500.00,
  "motivoRejeicao": null,
  "idEfeitoContrato": "9F3C71B2-88D4-4A55-B0E1-2C6A9D7E4F10",
  "liquidacoes": [
    {
      "data": "2025-08-14",
      "valor": 3000.00,
      "identificadorMovimentacao": "1B428B23-C0A8-46D5-AF2C-1AFFAFAAC653",
      "tipo": 1
    },
    {
      "data": "2025-08-15",
      "valor": 1200.00,
      "identificadorMovimentacao": "9C55D0B1-77A4-4F2E-9C0B-3D51A2E9B7A2",
      "tipo": 1
    },
    {
      "data": "2025-08-18",
      "valor": 300.00,
      "identificadorMovimentacao": "4E7B1F60-2A93-48C5-BD11-7C0A5E9D3B22",
      "tipo": 2
    }
  ],
  "efeitos": [
    {
      "tipoEfeito": 2,
      "tipoOnus": 1,
      "dataVencimentoEfeito": "2025-12-30",
      "idEfeitoContrato": "9F3C71B2-88D4-4A55-B0E1-2C6A9D7E4F10",
      "documentoTitular": "12345678000199",
      "titularEhVoce": true,
      "valorComprometido": 5000.00
    },
    {
      "tipoEfeito": 3,
      "tipoOnus": 2,
      "dataVencimentoEfeito": "2026-01-15",
      "idEfeitoContrato": "5C90E1AA-33B7-42D8-9E64-1F8C7A2B4D06",
      "documentoTitular": "***456780***",
      "titularEhVoce": false,
      "valorComprometido": 800.00
    }
  ]
}

🧾 Detalhamento dos campos¶

🔹 Nível raiz¶

Campo	Tipo	Descrição
id	string	GUID da UR.
credenciadora.cnpj	string	CNPJ da credenciadora responsável pela UR.
credenciadora.nome	string	Nome da credenciadora.
arranjo.sigla	string	Sigla do arranjo de pagamento (ex.: `MCC`, `VCC`).
arranjo.nome	string	Nome do arranjo (ex.: Mastercard Crédito).
dataPrevistaLiquidacao	string	Data prevista de liquidação da UR (`YYYY-MM-DD`).
statusSolicitacao	integer	Estado do vínculo da UR na registradora. Ver a tabela statusSolicitacao.
statusLiquidacao	string	Estado de caixa da UR. Ver a tabela statusLiquidacao.
valorContratado	number	Valor da UR que a plataforma enviou para vincular ao contrato.
valorGarantido	number	Valor efetivamente comprometido pela UR neste contrato, conforme o aceite da registradora. Pode ser menor que `valorContratado` quando a registradora acata parcialmente.
valorLiquidado	number	Valor já creditado e conciliado para esta UR. É a soma das linhas de `liquidacoes` com `tipo` = `1`.
valorChargeback	number	Redução detectada na conciliação (chargeback ou ajuste da credenciadora). É a soma das linhas de `liquidacoes` com `tipo` = `2`.
valorEmAberto	number	Quanto ainda se espera receber: `valorGarantido - valorLiquidado - valorChargeback`.
motivoRejeicao	integer/null	Preenchido quando `statusSolicitacao = 1` (Falha). `null` nos demais casos. Ver a tabela motivoRejeicao.
idEfeitoContrato	string/null	Identificador do efeito que este contrato exerce sobre a UR na registradora. É a chave que amarra a UR ao ônus ou à cessão registrada, e reaparece dentro do array `efeitos`. Vem `null` enquanto o vínculo não é confirmado.
liquidacoes	array	Créditos que a plataforma casou com esta UR. Vem vazio (`[]`) enquanto nada foi conciliado.
efeitos	array	Ônus registrados sobre a UR, próprios e de terceiros. Array vazio (`[]`) significa UR sem ônus vigente.

🔹 liquidacoes¶

Cada linha é um crédito conciliado atribuído a esta UR.

Campo	Tipo	Descrição
data	string	Data do crédito ou do lançamento (`YYYY-MM-DD`).
valor	number	Parte do crédito atribuída a esta UR. Um mesmo crédito pode ser rateado entre várias URs.
identificadorMovimentacao	string	Identificador da movimentação no sistema de origem, o mesmo enviado na integração de liquidações. É a chave de auditoria da linha.
tipo	integer	Natureza do lançamento. Ver a tabela tipo da liquidação.

🔹 efeitos¶

Campo	Tipo	Descrição
tipoEfeito	integer	Natureza do efeito registrado sobre a UR. Ver a tabela tipoEfeito.
tipoOnus	integer	Origem do ônus: `1` = próprio (contrato seu), `2` = terceiro (contrato de outra instituição).
dataVencimentoEfeito	string	Até quando o efeito onera a UR (`YYYY-MM-DD`). Depois dessa data o valor deixa de estar comprometido, se o efeito não for renovado.
idEfeitoContrato	string	ID de efeito de contrato — identificador que permite às registradoras reconhecerem o mesmo contrato no ambiente de interoperabilidade. Quando igual ao `idEfeitoContrato` do nível raiz, é o efeito deste contrato.
documentoTitular	string	Documento (CNPJ/CPF) do titular do efeito. Vem mascarado quando `titularEhVoce` é `false`.
titularEhVoce	boolean	`true` quando o efeito é de um contrato do seu grupo econômico; `false` quando pertence a terceiro.
valorComprometido	number	Quanto este efeito onera a UR.

🔢 statusSolicitacao — estado do vínculo¶

Responde à pergunta "a registradora aceitou a UR neste contrato?". É o eixo registral: fala do vínculo entre a UR e o contrato, não de dinheiro.

Código	Significado	Aplicação
0	Sucesso	Vínculo aceito pela registradora. A UR está efetivamente dentro do contrato.
1	Falha	A registradora recusou o vínculo desta UR. O campo `motivoRejeicao` diz o porquê e `valorGarantido` fica em `0.00`.
2	Em processamento	Vínculo enviado à registradora, aguardando retorno. Estado transitório.
3	Pendente extensão	Vínculo aceito, mas dependente da prorrogação do prazo do contrato — situação típica da garantia fumaça, com prazo estendido.
999	Cancelada	Vínculo desfeito: cancelamento do contrato ou remoção da UR já confirmada pela registradora.
1000	Em remoção	Remoção da UR solicitada e aguardando retorno da registradora. Enquanto não confirmada, a UR continua constando no contrato.

🔢 statusLiquidacao — estado de caixa¶

Responde à pergunta "o dinheiro entrou?". É apurado pela conciliação bancária da plataforma, comparando o que foi creditado em conta com o que estava registrado no contrato.

Valor	Significado
Aguardando	UR dentro do prazo e sem nenhuma informação de crédito ainda. Estado inicial.
Anunciada	O pagamento da UR foi anunciado (credenciadora/registradora informou a expectativa de crédito), mas o dinheiro não entrou.
LiquidadaParcialmente	Parte do valor foi creditada e conciliada; o restante segue em `valorEmAberto`.
Liquidada	Valor integral creditado e conciliado. Ciclo de caixa encerrado para esta UR.
NaoLiquidada	A data prevista passou e não houve crédito compatível no último processamento do dia.
EmAnalise	Divergência entre o valor esperado e o creditado, em apuração (chargeback, ajuste da credenciadora, crédito de terceiro).
NaoAplicavel	A UR não gera expectativa de caixa neste contrato — vínculo com falha, cancelado ou em remoção.

Os dois eixos são independentes. statusSolicitacao é registral e nunca informa liquidação; statusLiquidacao é caixa e nunca informa vínculo. O array liquidacoes é a prova documental do segundo eixo, e o array efeitos a do primeiro.

statusLiquidacao tem a mesma semântica nos dois fluxos, antecipação e garantia. Muda apenas a origem do dado:

Em troca de titularidade (tipoContrato = 1), o crédito é esperado na conta do cessionário, porque a UR foi cedida ao fundo.
Em garantia (tipoContrato = 2), o crédito ocorre na conta do EC ou na conta vinculada, e a conciliação serve para comprovar o cumprimento da garantia.

🔢 tipo da liquidação¶

Código	Significado	Aplicação
1	Liquidação	Crédito conciliado com a UR. Soma em `valorLiquidado` e reduz o `valorEmAberto`.
2	Chargeback	Redução do valor anunciado, por chargeback da venda ou ajuste da credenciadora. Soma em `valorChargeback`.
3	Ajuste da operação	Lançamento manual feito pela operação para corrigir uma atribuição, sempre rastreável pelo `identificadorMovimentacao`.

🔢 tipoEfeito¶

Código	Significado
1	Troca de titularidade — a UR foi cedida; o titular do recebível passou a ser o cessionário.
2	Garantia — a UR está travada em favor do credor, sem cessão definitiva.
3	Promessa de cessão — compromisso de cessão futura registrado sobre a UR. Somente leitura.
4	Penhor — efeito legado, mantido apenas para leitura de registros antigos.

Como interpretar os efeitos

tipoOnus = 1 (próprio): o efeito vem de um contrato do seu grupo econômico. Quando o idEfeitoContrato do efeito é igual ao do nível raiz, ele é o efeito deste contrato sobre a UR.
tipoOnus = 2 (terceiro): outra instituição já onerou parte da UR. Você não tem acesso ao contrato dela — por isso documentoTitular vem mascarado (ex.: "***456780***") e titularEhVoce vem false.
Promessa de cessão (tipoEfeito = 3) aparece apenas em leitura e nunca pode ser criada pela API: não existe endpoint que registre promessa de cessão. Ela explica por que parte do crédito pode não chegar ao seu contrato.
Penhor (tipoEfeito = 4) é legado e não é gerado por nenhuma operação atual da plataforma VeFlow.

🔢 motivoRejeicao¶

Preenchido somente quando statusSolicitacao = 1 (Falha).

Código	Significado	Aplicação
1	Falha ao vincular ao contrato	A registradora recusou o vínculo da UR (valor livre insuficiente, ônus concorrente, UR inexistente ou já comprometida).
2	Não performado corretamente	A UR não atingiu a condição de performada exigida pela operação — recusa típica de garantia fumaça, que só aceita URs performadas.

❌ 404 Not Found¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "titulo": "Atenção",
  "status": 404,
  "erros": [
    "UR '7D121577-3C5A-494D-B052-291D9E100D0D' não encontrada no contrato '5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6'."
  ]
}

É o mesmo retorno quando o contrato não existe, quando ele está fora do grupo econômico informado no header GrupoEconomico, ou quando a UR existe na plataforma mas não está vinculada a este contrato.

🕒 Observações¶

Para o extrato completo de conciliação da UR, use 7.3. Extrato de conciliação da UR. Esta página mostra a posição da UR dentro de um contrato; a 7.3 mostra a UR inteira — o que a agenda anunciou, cada crédito recebido com origem e situação, e todos os ônus, inclusive os de outros contratos.
valorLiquidado e valorChargeback vêm do motor de conciliação bancária, que roda de forma recorrente ao longo do dia. O status NaoLiquidada só é atribuído no último processamento do dia (19h), para não classificar como não liquidada uma UR cujo crédito ainda pode chegar.
A soma de efeitos[].valorComprometido pode ser maior que o valorGarantido deste contrato: os demais efeitos são ônus de outros contratos, seus ou de terceiros, sobre a mesma UR.
Contrato de garantia não tem deságio: esta página 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.
Atualizações de posição da UR são notificadas por webhook — ver 3.3. Atualizações da UR.
Listagem paginada e filtrável das URs do contrato: 5.4. Listar URs do contrato. Totais consolidados do contrato: 5.3. Detalhes do contrato.
Headers obrigatórios e convenções gerais: 1.1. Primeiros Passos.