--- title: 4.5. Detalhes da UR url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/4.%20Agenda%20de%20receb%C3%ADveis/v1.1/4.5.%20Detalhes%20da%20UR/ --- # 4.5. Detalhes da UR ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ------------------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/public/api/v1.1/cartao/agendas/{idAgenda}/urs/{idUr}` | --- ## 🧾 Descrição Retorna os **detalhes de uma UR (Unidade de Recebível)** dentro do contexto de uma agenda: os mesmos valores da listagem, mais o array **`efeitos`** — a relação dos ônus registrados sobre aquela UR. O array `efeitos` responde à pergunta que a listagem não responde: **quem comprometeu esta UR, por qual contrato, com que ônus e até quando**. É também onde a **promessa de cessão** aparece, sempre como ônus de **terceiro**. Use esta consulta antes de alocar uma UR grande em um item de carrinho: `valorComprometido` diz *quanto* está onerado, `efeitos` diz *por que*. --- ## 📤 Requisição ### 🧭 Parâmetros de rota | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | ------------------------------------------------------------------------------------------- | | idAgenda | string | Sim | GUID da agenda, devolvido em [4.1. Solicitar agenda](4.1.%20Solicitar%20agenda.md). | | idUr | string | Sim | GUID da UR, obtido em [4.4. Listar URs da agenda](4.4.%20Listar%20URs%20da%20agenda.md). | --- ## 🧪 Exemplo de cURL ```bash curl -X GET https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/urs/7D121577-3C5A-494D-B052-291D9E100D0D \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Content-Type: application/json" ``` --- ## 📥 Responses ### ✅ 200 OK ```json { "id": "7D121577-3C5A-494D-B052-291D9E100D0D", "credenciadora": { "cnpj": "10293847560102", "nome": "CREDENCIADORA EXEMPLO S.A." }, "arranjo": { "sigla": "MCC", "nome": "Mastercard Cartão de Crédito" }, "dataPrevistaLiquidacao": "2025-08-14", "valorConstituido": 10000.00, "valorComprometido": 2500.00, "valorLivre": 7500.00, "valorDisponivel": 5000.00, "valorGarantido": 1200.00, "possuiPromessaCessao": true, "efeitos": [ { "tipoEfeito": 2, "tipoOnus": 1, "dataVencimentoEfeito": "2025-12-30", "idEfeitoContrato": "A7F1C2B4-9D30-4A11-8F55-6B2E7C1D0A93", "documentoTitular": "12345678000199", "titularEhVoce": true, "valorComprometido": 1500.00 }, { "tipoEfeito": 3, "tipoOnus": 2, "dataVencimentoEfeito": "2026-01-15", "idEfeitoContrato": "5C90E1AA-33B7-42D8-9E64-1F8C7A2B4D06", "documentoTitular": "***456780***", "titularEhVoce": false, "valorComprometido": 1000.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`). | | arranjo.nome | string | Nome do arranjo (ex.: `Mastercard Cartão de Crédito`). | | dataPrevistaLiquidacao | string | Data prevista de liquidação da UR (`YYYY-MM-DD`). | | valorConstituido | number | Valor que a registradora informa existir na UR. | | valorComprometido | number | Parte da UR já onerada, por contrato próprio ou de terceiro. Igual à soma de `efeitos[].valorComprometido`. | | valorLivre | number | Parte da UR disponível para uso (`valorConstituido` - `valorComprometido`). | | valorDisponivel | number | Valor livre já descontado o percentual máximo por UR configurado na operação. | | valorGarantido | number | Quanto desta UR está sendo utilizado pelos itens do carrinho. | | possuiPromessaCessao | boolean | `true` quando há promessa de cessão entre os `efeitos` — sempre ônus de terceiro. | | efeitos | array | Ônus registrados sobre a UR. Array vazio (`[]`) significa **UR livre de ônus**. | ### 🔹 efeitos | Campo | Tipo | Descrição | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | tipoEfeito | integer | Natureza do efeito registrado sobre a UR (ver tabela abaixo). | | 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 volta a compor o `valorLivre`, 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. | | 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. A soma dos efeitos é o `valorComprometido` da UR. | ### 🔢 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 * **Array vazio** (`"efeitos": []`) significa UR **livre de ônus**: todo o `valorConstituido` está livre, limitado apenas pelo percentual máximo por UR da operação (`valorDisponivel`). * **`tipoOnus` = 1 (próprio)**: o efeito vem de um contrato do seu grupo econômico. O `idEfeitoContrato` permite localizar o contrato correspondente em **5. Contrato de recebíveis**. * **`tipoOnus` = 2 (terceiro)**: outra instituição já onerou parte da UR. Você não tem acesso ao contrato dela — por isso `documentoTitular` vem mascarado. * **Promessa de cessão** (`tipoEfeito` = 3) aparece **apenas em leitura** e **sempre** como ônus de terceiro (`tipoOnus` = 2). Ela nunca pode ser criada pela API: não existe endpoint que registre promessa de cessão. Quando presente, `possuiPromessaCessao` vem `true` na UR e na listagem de [4.4. Listar URs da agenda](4.4.%20Listar%20URs%20da%20agenda.md). * **Penhor** (`tipoEfeito` = 4) é legado. Pode aparecer em URs com histórico antigo e não é gerado por nenhuma operação atual da plataforma **VeFlow**. * Para varrer a agenda inteira em busca de URs oneradas por terceiros, use o filtro `possuiEfeitoTerceiros=true` em [4.4. Listar URs da agenda](4.4.%20Listar%20URs%20da%20agenda.md). --- ### ❌ 404 Not Found ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Não encontrado", "status": 404, "erros": [ "UR '7D121577-3C5A-494D-B052-291D9E100D0D' não encontrada na agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51'." ] } ``` Retornado tanto quando a agenda não existe quanto quando a UR informada não pertence àquela agenda. --- ## 🕒 Observações * Os efeitos refletem o estado informado pelas registradoras no momento da consulta da agenda. Uma agenda vencida pode trazer ônus desatualizados — refaça a consulta em [4.7. Refazer consulta](4.7.%20Refazer%20consulta.md). * Alterações de ônus e de valores da UR também são notificadas por webhook — ver [3.3. Atualizações da UR](../../3.%20Notificações%20-%20WebHook/3.3.%20Atualizações%20da%20UR.md). * `valorComprometido` (ônus registrado) e `valorGarantido` (uso no carrinho) são grandezas diferentes: a primeira já está registrada nas registradoras; a segunda é a alocação em montagem na plataforma, que só se torna ônus quando o item vira contrato. * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).