4.4. Listar URs da agenda¶

🔗 Endpoint¶

Método	URL
	`/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.

📤 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.

🔎 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 — use os dois juntos para conferir o total do que está sendo listado.

🧪 Exemplo de cURL¶

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¶

{
  "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 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¶

{
  "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¶

{
  "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.
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.
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). Depois de vencida é necessário refazer a consulta — ver 4.7. Refazer consulta.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.