4.18. Listar URs do item¶

🔗 Endpoint¶

Método	URL
	`/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 ou de ajustá-lo em 4.16. Adicionar URs ao item.

📋 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¶

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¶

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

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

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