--- title: 4.4. Listar URs da agenda 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.4.%20Listar%20URs%20da%20agenda/ --- # 4.4. Listar URs da agenda ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ------------------------------------------------ | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/public/api/v1.1/cartao/agendas/{idAgenda}/urs` | --- ## 🧾 Descrição Lista, de forma **paginada**, as **URs (Unidades de Recebíveis)** que a consulta de agenda trouxe das registradoras. Cada registro é uma UR — a combinação de **data prevista de liquidação**, **arranjo**, **credenciadora** e **estabelecimento comercial (EC)** — acompanhada dos valores que dizem quanto daquela UR existe, quanto já está onerado e quanto ainda pode ser usado para montar um item de carrinho. Esta é a vitrine da operação: é a partir desta lista que se escolhem as URs que vão para o carrinho — ver [4.10. Adicionar item](4.10.%20Adicionar%20item.md). --- ## 📤 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). | ### 🔎 Query params | Parâmetro | Tipo | Obrigatório | Descrição | | --------------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | | dataLiquidacaoInicio | string | Não | Filtra URs com `dataPrevistaLiquidacao` maior ou igual à data informada (`YYYY-MM-DD`). | | dataLiquidacaoFim | string | Não | Filtra URs com `dataPrevistaLiquidacao` menor ou igual à data informada (`YYYY-MM-DD`). | | siglaArranjo | string | Não | Sigla do arranjo de pagamento (ex.: `MCC`, `VCC`, `ECC`). A relação completa está em **2.2. Dicionário de dados**. | | cnpjCredenciadora | string | Não | CNPJ da credenciadora, somente dígitos (ex.: `10293847560102`). | | possuiValorLivre | boolean | Não | `true` retorna apenas URs com `valorLivre` maior que zero; `false` retorna apenas URs totalmente comprometidas. | | possuiEfeitoTerceiros | boolean | Não | `true` retorna apenas URs com ao menos um ônus de terceiro (inclusive promessa de cessão); `false` retorna apenas URs sem ônus de terceiro. | | indicePagina | integer | Não | Página desejada. Default `1`. | | tamanhoDaPagina | integer | Não | Quantidade de registros por página. Default `20`. | | ordem | string | Não | Campo de ordenação (ex.: `dataPrevistaLiquidacao`, `valorDisponivel`, `valorConstituido`). | | direcaoOrdem | string | Não | Direção da ordenação: `ASC` ou `DESC`. | **Regras e formatos** * Datas no formato `YYYY-MM-DD`. * `cnpjCredenciadora`: somente dígitos, sem pontuação. * Os filtros são combinados com **E** (todos precisam ser satisfeitos). * Os mesmos filtros são aceitos em [4.6. Totais da agenda](4.6.%20Totais%20da%20agenda.md) — use os dois juntos para conferir o total do que está sendo listado. --- ## 🧪 Exemplo de cURL ```bash curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/urs?dataLiquidacaoInicio=2025-08-09&dataLiquidacaoFim=2025-08-31&siglaArranjo=MCC&possuiValorLivre=true&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 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": false } ], "paginacao": { "paginaAtual": 1, "paginaTotal": 3, "paginaQuantidadeRegistro": 20, "quantidadeRegistros": 47, "temPaginaAnterior": false, "temProximaPagina": true }, "mensagem": null } ``` --- ## 🧾 Detalhamento dos Campos ### 🔹 registros | Campo | Tipo | Descrição | | ---------------------- | ------- | ------------------------------------------------------------------------------------------------ | | id | string | GUID da UR. Use-o em [4.5. Detalhes da UR](4.5.%20Detalhes%20da%20UR.md) e nos campos `idsUrs`. | | 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`) — quando o valor cai na conta do EC. | | valorConstituido | number | Valor que a registradora informa existir na UR. Ver quadro de valores abaixo. | | valorComprometido | number | Parte da UR já onerada, por contrato próprio ou de terceiro. | | valorLivre | number | Parte da UR disponível para uso. | | 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 existe promessa de cessão registrada sobre a UR — sempre um ônus de **terceiro**. | ### 💰 Como ler os valores da UR | Valor | O que significa | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | valorConstituido | O que a **registradora informa que existe** na UR. É o ponto de partida, o valor bruto registrado da venda a receber. | | valorComprometido | A parte **já onerada** da UR — por um contrato seu ou por contrato de terceiro (outra instituição). Sai do que você pode usar. | | valorLivre | O que **sobra para uso**: `valorConstituido` menos `valorComprometido`. | | valorDisponivel | O `valorLivre` já descontado o **percentual máximo por UR** configurado na operação. É o teto real de alocação: nenhum item de carrinho pode ultrapassá-lo. | | valorGarantido | Quanto da UR **está sendo utilizado** — a soma do que os itens do carrinho já alocaram nela. | > Compare sempre contra `valorDisponivel`, não contra `valorLivre`: o percentual máximo por UR é uma trava da operação e a alocação é recusada quando o item passa desse teto. ### 🔹 paginacao | Campo | Tipo | Descrição | | ------------------------ | ------- | ------------------------------------------ | | paginaAtual | integer | Página atual do retorno. | | paginaTotal | integer | Total de páginas disponíveis. | | paginaQuantidadeRegistro | integer | Quantidade máxima de registros por página. | | quantidadeRegistros | integer | Total de registros encontrados. | | temPaginaAnterior | boolean | Indica se há página anterior. | | temProximaPagina | boolean | Indica se há próxima página. | ### 🔹 mensagem | Campo | Tipo | Descrição | | -------- | ----------- | ---------------------------------------------------------------------------- | | mensagem | string/null | Mensagem informativa opcional. Em caso de sucesso normalmente vem `null`. | --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "Campo 'dataLiquidacaoInicio' inválido. Formato esperado: YYYY-MM-DD.", "Campo 'direcaoOrdem' inválido. Valores aceitos: ASC ou DESC." ] } ``` --- ### ❌ 404 Not Found ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Não encontrado", "status": 404, "erros": [ "Agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51' não encontrada." ] } ``` --- ## 🕒 Observações * A agenda só tem URs para listar depois que a consulta assíncrona termina. A conclusão é notificada por webhook — ver [3.1. Listagem de URs](../../3.%20Notificações%20-%20WebHook/3.1.%20Listagem%20de%20URs.md). * A lista traz tanto URs **performadas** (venda já realizada) quanto **futuras**, conforme o intervalo de datas da solicitação original. * Um `valorLivre` alto com `valorDisponivel` baixo significa trava da operação, não ônus de terceiro. Um `valorComprometido` alto significa ônus — para saber **quem** onerou e **por qual contrato**, consulte [4.5. Detalhes da UR](4.5.%20Detalhes%20da%20UR.md). * Valores de deságio (`valorNominal`, `valorDesconto`, `valorAquisicao`) não pertencem à fase de agenda: eles aparecem apenas na antecipação (troca de titularidade), porque só ali houve cessão ao fundo. Contrato de garantia não tem deságio. * A agenda tem prazo de validade (`dataValidade`, devolvido em [4.3. Detalhes da agenda](4.3.%20Detalhes%20da%20agenda.md)). Depois de vencida é necessário refazer a consulta — ver [4.7. Refazer consulta](4.7.%20Refazer%20consulta.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).