--- title: 4.18. Listar URs do item 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.18.%20Listar%20URs%20do%20item/ --- # 4.18. Listar URs do item ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ------------------------------------------------------------------------ | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/{idItem}/urs` | --- ## 🧾 Descrição Retorna a **lista paginada das URs vinculadas a um item de carrinho**, com o quanto de cada UR está alocado nesse item. Cada registro mostra os dois lados do saldo: os valores da **fase de agenda** da UR (`valorConstituido`, `valorLivre` e `valorDisponivel`), que dizem o quanto daquela UR ainda pode ser usado, e o `valorGarantido`, da **fase de carrinho/contrato**, que diz o quanto dela está alocado neste item. Use este endpoint para conferir a composição do item depois de montá-lo em [4.10. Adicionar item](4.10.%20Adicionar%20item.md) ou de ajustá-lo em [4.16. Adicionar URs ao item](4.16.%20Adicionar%20URs%20ao%20item.md). ### 📋 Parâmetros de rota | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | -------------------------------------------------------------------- | | idAgenda | string | Sim | GUID da agenda, devolvido como `identificador` em **4.1** e **4.2**. | | idItem | string | Sim | GUID do item de carrinho, devolvido na criação do item em **4.10**. | --- ## 📤 Requisição ### 🔍 Filtros (query string) | Parâmetro | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | ------------------------------------------------------------------------------------------ | | credenciadora | string | Não | CNPJ da credenciadora (somente números). Filtra as URs do item por credenciadora. | | arranjo | string | Não | Sigla do arranjo de pagamento (ex.: `MCC`, `VCC`). | | dataInicial | string | Não | Considera URs com `dataPrevistaLiquidacao` a partir desta data, no formato `YYYY-MM-DD`. | | dataFinal | string | Não | Considera URs com `dataPrevistaLiquidacao` até esta data, no formato `YYYY-MM-DD`. | ### 📄 Paginação e ordenação | Parâmetro | Tipo | Obrigatório | Padrão | Descrição | | --------------- | ------ | ----------- | ------ | ------------------------------------------------------------------------------------------------------ | | indicePagina | number | Não | `1` | Página desejada do resultado. | | tamanhoDaPagina | number | Não | `20` | Quantidade de registros por página. | | ordem | string | Não | — | Campo usado para ordenar o resultado (ex.: `dataPrevistaLiquidacao`, `valorGarantido`, `credenciadora`). | | direcaoOrdem | string | Não | — | Direção da ordenação: `asc` ou `desc`. | **Regras e formatos** * Datas no formato `YYYY-MM-DD`. * `credenciadora`: somente dígitos (ex.: `10293847560102`). * Filtros são combinados entre si (E lógico). Sem filtros, retorna todas as URs do item ordenadas por `dataPrevistaLiquidacao`. --- ## 🧪 Exemplo de cURL ```bash curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/AEB4EA8C-BEF4-4E4E-A009-0A94AF172EAB/urs?arranjo=MCC&indicePagina=1&tamanhoDaPagina=20&ordem=dataPrevistaLiquidacao&direcaoOrdem=asc" \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Content-Type: application/json" ``` --- ## 📥 Responses ### ✅ 200 OK ```json { "registros": [ { "id": "7D121577-3C5A-494D-B052-291D9E100D0D", "credenciadora": { "cnpj": "10293847560102", "nome": "CREDENCIADORA EXEMPLO S.A." }, "arranjo": { "sigla": "MCC", "nome": "Mastercard Crédito" }, "dataPrevistaLiquidacao": "2025-08-12", "valorConstituido": 5000.00, "valorLivre": 4200.00, "valorDisponivel": 2700.00, "valorGarantido": 1500.00, "tipoValor": 1 } ], "paginacao": { "paginaAtual": 1, "paginaTotal": 1, "paginaQuantidadeRegistro": 12, "quantidadeRegistros": 12, "temPaginaAnterior": false, "temProximaPagina": false }, "mensagem": "URs do item listadas com sucesso!" } ``` ### 🧾 Detalhamento dos Campos #### 🔹 registros | Campo | Tipo | Descrição | | ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | id | string | GUID da UR. Use-o em [4.17. Remover URs do item](4.17.%20Remover%20URs%20do%20item.md). | | 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`, `ELO`). | | arranjo.nome | string | Nome do arranjo de pagamento (ex.: Mastercard Crédito). | | dataPrevistaLiquidacao | string | Data prevista de liquidação da UR (`YYYY-MM-DD`), conforme informada pela registradora. | | valorConstituido | number | Valor total da UR conforme registro na registradora. | | valorLivre | number | Valor da UR não onerado por terceiros nem por contratos anteriores, isto é, o constituído menos o `valorComprometido`. | | valorDisponivel | number | O que sobra do `valorLivre` depois de descontar tudo o que já está alocado em itens de carrinho. | | valorGarantido | number | Valor da UR alocado **neste item**. | | tipoValor | integer | Como o `valorGarantido` foi informado na alocação. Ver tabela **Tipo de valor**. | #### 🔹 paginacao | Campo | Tipo | Descrição | | ------------------------ | ------- | ------------------------------------------------------------ | | paginaAtual | number | Página retornada nesta resposta. | | paginaTotal | number | Total de páginas disponíveis com os filtros informados. | | paginaQuantidadeRegistro | number | Quantidade de registros nesta página. | | quantidadeRegistros | number | Total de registros que atendem aos filtros. | | temPaginaAnterior | boolean | Indica se existe página anterior. | | temProximaPagina | boolean | Indica se existe próxima página. | #### 🔹 mensagem | Campo | Tipo | Descrição | | -------- | ----------- | ----------------------------------------------- | | mensagem | string-null | Mensagem informativa da consulta. | --- ### 🔢 Tipo de valor | Código | Significado | Como o `valorGarantido` foi informado na alocação | | ------ | -------------- | ------------------------------------------------------------------------------- | | 1 | Valor absoluto | Valor em reais, com até 2 casas decimais. | | 2 | Percentual | Percentual do `valorDisponivel` da UR, de `0` a `100`, com até 4 casas decimais. | Independentemente do `tipoValor`, o campo `valorGarantido` deste retorno sempre vem **em reais**: é o valor efetivamente alocado no item. --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "Campo 'dataInicial' inválido. Formato esperado: YYYY-MM-DD.", "Campo 'direcaoOrdem' inválido. Valores aceitos: asc ou desc." ] } ``` --- ### ❌ 404 Not Found Retornado quando a agenda ou o item informados não existem no grupo econômico. Item existente e sem URs vinculadas devolve `200` com `registros` vazio. ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Atenção", "status": 404, "erros": [ "Item de carrinho não encontrado na agenda informada." ] } ``` --- ## 🔄 Mudanças nesta versão | O que mudou | Detalhe | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `pagina` e `quantidade` viraram `indicePagina` e `tamanhoDaPagina` | Os nomes de paginação passaram a ser os mesmos de toda a API, com padrões `1` e `20`, mais `ordem` e `direcaoOrdem`. | | `dataLiquidacao` virou `dataPrevistaLiquidacao` | O nome ficou igual ao de [4.4. Listar URs da agenda](4.4.%20Listar%20URs%20da%20agenda.md) e ao dos webhooks. Trata-se da data **prevista** informada pela registradora, não da liquidação realizada. | | `guid` virou `id` | O identificador da UR no registro passou a se chamar `id`. | | `tipoValor` passou a ter enum documentado | Antes o texto remetia a um "enum interno da aplicação". Os valores são `1` (Valor absoluto) e `2` (Percentual). | | Entrou `valorDisponivel` | Permite ver, na própria listagem do item, quanto ainda resta da UR para alocar em outros itens do carrinho. | --- ## 🕒 Observações * Uma mesma UR pode aparecer em mais de um item do carrinho, por causa do rateio parcial. Nesta listagem, `valorGarantido` é sempre o valor alocado **no item consultado**, enquanto `valorDisponivel` é o saldo da UR como um todo. * O item pode conter URs performadas e futuras, conforme o escopo com que foi montado. Quando a garantia usa a configuração de **fumaça** — prazo estendido, somente URs performadas e regra de retenção —, o item traz apenas URs performadas. * Esta é uma listagem de **alocação**. Ela não traz valores de antecipação: `valorNominal`, `valorDesconto` e `valorAquisicao` existem somente em contratos de **troca de titularidade** (`tipoContrato` igual a `1`), porque só ali houve cessão ao fundo, e são consultados na seção 5. Contratos de **garantia** (`tipoContrato` igual a `2`) não têm deságio. * URs com **promessa de cessão** têm o ônus de terceiro refletido em `valorComprometido`, o que reduz o `valorLivre`. A promessa de cessão aparece apenas em leitura, nunca é criada pela API. * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).