--- title: 5.5. Detalhes da UR do contrato url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/5.%20Contrato%20de%20receb%C3%ADveis/v1.1/5.5.%20Detalhes%20da%20UR%20do%20contrato/ --- # 5.5. Detalhes da UR do contrato ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | -------------------------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/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](5.4.%20Listar%20URs%20do%20contrato.md), 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](5.4.%20Listar%20URs%20do%20contrato.md). | Este endpoint não possui query params: ele devolve sempre a posição vigente da UR no contrato informado. --- ## 🧪 Exemplo de cURL ```bash 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 ```json { "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 ```json { "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](../../7.%20Conciliação/v1.1/7.3.%20Extrato%20de%20conciliação%20da%20UR.md).** 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](../../3.%20Notificações%20-%20WebHook/3.3.%20Atualizações%20da%20UR.md). * Listagem paginada e filtrável das URs do contrato: [5.4. Listar URs do contrato](5.4.%20Listar%20URs%20do%20contrato.md). Totais consolidados do contrato: [5.3. Detalhes do contrato](5.3.%20Detalhes%20do%20contrato.md). * Headers obrigatórios e convenções gerais: [1.1. Primeiros Passos](../../1.%20Início/1.1.%20Primeiros%20Passos.md).