5.4. Listar URs do contrato¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1.1/cartao/contratos/{idContrato}/urs`

🧾 Descrição¶

Retorna, de forma paginada, as URs (Unidades de Recebíveis) vinculadas a um contrato, com os valores contratados e a posição de caixa de cada uma.

Cada UR carrega dois eixos de status independentes, e essa é a informação mais importante desta página:

Campo	Pergunta que responde	Natureza
`statusSolicitacao`	A registradora aceitou esta UR neste contrato?	Estado do vínculo na registradora.
`statusLiquidacao`	O dinheiro entrou?	Estado de caixa, apurado na conciliação.

São coisas diferentes e não se substituem: uma UR pode ter vínculo perfeito (statusSolicitacao = 0) e ainda estar Aguardando o crédito; e pode ter o crédito integral em conta e, mesmo assim, ter tido o vínculo removido depois. Sempre leia os dois campos juntos.

Correção em relação à documentação anterior: a v1 afirmava que o status da UR poderia ser usado para "identificar títulos liquidados". Isso estava errado — aquele enum é de vínculo e não possui valor de liquidada. A partir da v1.1 existem dois campos, um para cada eixo.

📤 Requisição¶

📋 Parâmetros de rota¶

Parâmetro	Tipo	Obrigatório	Descrição
idContrato	string	Sim	GUID do contrato.

🔍 Query params¶

Todos são opcionais. A paginação possui valores padrão.

Parâmetro	Tipo	Descrição
statusSolicitacao	integer	Filtra pelo status do vínculo. Aceita os códigos da tabela statusSolicitacao (ex.: `?statusSolicitacao=1` traz as falhas).
statusLiquidacao	string	Filtra pelo status de caixa. Aceita os nomes da tabela statusLiquidacao (ex.: `?statusLiquidacao=Liquidada`).
dataLiquidacaoInicio	string	Início do intervalo de `dataPrevistaLiquidacao`, inclusivo. Formato `YYYY-MM-DD`.
dataLiquidacaoFim	string	Fim do intervalo de `dataPrevistaLiquidacao`, inclusivo. Formato `YYYY-MM-DD`.
siglaArranjo	string	Sigla do arranjo de pagamento (ex.: `MCC`, `VCC`).
cnpjCredenciadora	string	CNPJ da credenciadora, somente dígitos.
indicePagina	integer	Página desejada, base 1. Padrão `1`.
tamanhoDaPagina	integer	Quantidade de registros por página. Padrão `20`.
ordem	string	Campo de ordenação. Padrão `dataPrevistaLiquidacao`. Aceita também `valorGarantido`, `valorEmAberto` e `statusLiquidacao`.
direcaoOrdem	string	Direção da ordenação: `asc` ou `desc`. Padrão `asc`.

🧪 Exemplo de cURL¶

curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/contratos/5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6/urs?statusLiquidacao=Aguardando&dataLiquidacaoInicio=2025-08-01&dataLiquidacaoFim=2025-08-31&siglaArranjo=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": "11223344000155",
        "nome": "CREDENCIADORA EXEMPLO S.A."
      },
      "arranjo": {
        "sigla": "MCC",
        "nome": "Mastercard Crédito"
      },
      "dataPrevistaLiquidacao": "2025-08-14",
      "statusSolicitacao": 0,
      "statusLiquidacao": "LiquidadaParcialmente",
      "valorContratado": 5000.00,
      "valorGarantido": 5000.00,
      "valorLiquidado": 4200.00,
      "valorChargeback": 300.00,
      "valorEmAberto": 500.00,
      "motivoRejeicao": null,
      "idEfeitoContrato": "9F3C71B2-88D4-4A55-B0E1-2C6A9D7E4F10"
    },
    {
      "id": "1C4D2288-77B6-4E31-9A05-33ADEF9012BB",
      "credenciadora": {
        "cnpj": "10293847560102",
        "nome": "OUTRA CREDENCIADORA LTDA"
      },
      "arranjo": {
        "sigla": "VCC",
        "nome": "Visa Crédito"
      },
      "dataPrevistaLiquidacao": "2025-08-15",
      "statusSolicitacao": 1,
      "statusLiquidacao": "NaoAplicavel",
      "valorContratado": 1800.00,
      "valorGarantido": 0.00,
      "valorLiquidado": 0.00,
      "valorChargeback": 0.00,
      "valorEmAberto": 0.00,
      "motivoRejeicao": 2,
      "idEfeitoContrato": null
    }
  ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 6,
    "paginaQuantidadeRegistro": 20,
    "quantidadeRegistros": 118,
    "temPaginaAnterior": false,
    "temProximaPagina": true
  },
  "mensagem": null
}

🧾 Detalhamento dos campos¶

🔹 registros¶

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`, `VCC`).
arranjo.nome	string	Nome do arranjo (ex.: Mastercard Crédito).
dataPrevistaLiquidacao	string	Data prevista de liquidação da UR (`YYYY-MM-DD`).
statusSolicitacao	integer	Estado do vínculo da UR na registradora. Ver a tabela statusSolicitacao.
statusLiquidacao	string	Estado de caixa da UR. Ver a tabela statusLiquidacao.
valorContratado	number	Valor da UR que a plataforma enviou para vincular ao contrato.
valorGarantido	number	Valor efetivamente comprometido pela UR neste contrato, conforme o aceite da registradora. Pode ser menor que `valorContratado` quando a registradora acata parcialmente.
valorLiquidado	number	Valor já creditado e conciliado para esta UR.
valorChargeback	number	Redução detectada na conciliação (chargeback ou ajuste da credenciadora).
valorEmAberto	number	Quanto ainda se espera receber: `valorGarantido - valorLiquidado - valorChargeback`.
motivoRejeicao	integer/null	Preenchido quando `statusSolicitacao = 1` (Falha). `null` nos demais casos. Ver a tabela motivoRejeicao.
idEfeitoContrato	string/null	Identificador do efeito que este contrato exerce sobre a UR na registradora. É a chave que amarra a UR ao ônus ou à cessão registrada, e reaparece no array `efeitos` em 5.5. Detalhes da UR do contrato. Vem `null` enquanto o vínculo não é confirmado.

🔹 paginacao¶

Campo	Tipo	Descrição
paginaAtual	integer	Página atual do retorno (base 1).
paginaTotal	integer	Total de páginas disponíveis.
paginaQuantidadeRegistro	integer	Quantidade de registros por página.
quantidadeRegistros	integer	Total de registros encontrados no filtro.
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. Vem `null` nos retornos de sucesso limpos.

🔢 statusSolicitacao — estado do vínculo¶

Responde à pergunta "a registradora aceitou a UR neste contrato?". É o eixo registral: fala do vínculo entre a UR e o contrato, não de dinheiro.

Código	Significado	Aplicação
0	Sucesso	Vínculo aceito pela registradora. A UR está efetivamente dentro do contrato.
1	Falha	A registradora recusou o vínculo desta UR. O campo `motivoRejeicao` diz o porquê e `valorGarantido` fica em `0.00`.
2	Em processamento	Vínculo enviado à registradora, aguardando retorno. Estado transitório.
3	Pendente extensão	Vínculo aceito, mas dependente da prorrogação do prazo do contrato — situação típica da garantia fumaça, com prazo estendido.
999	Cancelada	Vínculo desfeito: cancelamento do contrato ou remoção da UR já confirmada pela registradora.
1000	Em remoção	Remoção da UR solicitada e aguardando retorno da registradora. Enquanto não confirmada, a UR continua constando no contrato.

O valor 1000 (Em remoção) nunca havia sido documentado. Ele existe para tornar visível a janela entre o pedido de remoção e a confirmação da registradora — antes, essa UR aparecia como se nada estivesse acontecendo.

🔢 statusLiquidacao — estado de caixa¶

Responde à pergunta "o dinheiro entrou?". É apurado pela conciliação bancária da plataforma, comparando o que foi creditado em conta com o que estava registrado no contrato.

Valor	Significado
Aguardando	UR dentro do prazo e sem nenhuma informação de crédito ainda. Estado inicial.
Anunciada	O pagamento da UR foi anunciado (credenciadora/registradora informou a expectativa de crédito), mas o dinheiro não entrou.
LiquidadaParcialmente	Parte do valor foi creditada e conciliada; o restante segue em `valorEmAberto`.
Liquidada	Valor integral creditado e conciliado. Ciclo de caixa encerrado para esta UR.
NaoLiquidada	A data prevista passou e não houve crédito compatível no último processamento do dia.
EmAnalise	Divergência entre o valor esperado e o creditado, em apuração (chargeback, ajuste da credenciadora, crédito de terceiro).
NaoAplicavel	A UR não gera expectativa de caixa neste contrato — vínculo com falha, cancelado ou em remoção.

statusLiquidacao tem a mesma semântica nos dois fluxos, antecipação e garantia. Os valores, as transições e o significado de cada um são idênticos; muda apenas a origem do dado:

Em troca de titularidade (tipoContrato = 1), o crédito é esperado na conta do cessionário, porque a UR foi cedida ao fundo.
Em garantia (tipoContrato = 2), o crédito ocorre na conta do EC ou na conta vinculada, e a conciliação serve para comprovar o cumprimento da garantia.

Em nenhum dos dois casos o enum muda. Se o seu sistema já trata statusLiquidacao para antecipação, o mesmo tratamento vale para garantia.

🔢 Lendo os dois eixos juntos¶

statusSolicitacao	statusLiquidacao	Leitura
0 Sucesso	Aguardando	UR vinculada e saudável; o crédito ainda não é esperado.
0 Sucesso	LiquidadaParcialmente	Vínculo em ordem, parte do dinheiro entrou; acompanhe `valorEmAberto`.
0 Sucesso	Liquidada	Ciclo completo: vínculo aceito e caixa realizado.
0 Sucesso	EmAnalise	Vínculo em ordem, valor divergente. Verifique `valorChargeback`.
3 Pendente extensão	Aguardando	UR presa à prorrogação do prazo (fumaça); o caixa depende da extensão.
1 Falha	NaoAplicavel	A UR não entrou no contrato. Consulte `motivoRejeicao`.
1000 Em remoção	Aguardando	Remoção em andamento; a UR ainda consta e não deve ser reaproveitada.
999 Cancelada	NaoAplicavel	Vínculo desfeito. O registro permanece apenas para auditoria.

🔢 motivoRejeicao¶

Preenchido somente quando statusSolicitacao = 1 (Falha).

Código	Significado	Aplicação
1	Falha ao vincular ao contrato	A registradora recusou o vínculo da UR (valor livre insuficiente, ônus concorrente, UR inexistente ou já comprometida).
2	Não performado corretamente	A UR não atingiu a condição de performada exigida pela operação — recusa típica de garantia fumaça, que só aceita URs performadas.

❌ 404 Not Found¶

Contrato inexistente, ou fora do grupo econômico informado no header GrupoEconomico.

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "titulo": "Atenção",
  "status": 404,
  "erros": [
    "Contrato não encontrado."
  ]
}

Filtro que não encontra nenhuma UR não é erro: devolve 200 OK com registros: [] e quantidadeRegistros: 0.

🕒 Observações¶

valorLiquidado e valorChargeback vêm do motor de conciliação bancária, que roda de forma recorrente ao longo do dia. O status NaoLiquidada só é atribuído no último processamento do dia (19h), para não classificar como não liquidada uma UR cujo crédito ainda pode chegar.
Atualizações de posição das URs são notificadas por webhook — ver 3.3. Atualizações da UR.
URs canceladas, rejeitadas ou liquidadas permanecem na listagem para fins de auditoria. Use statusSolicitacao e statusLiquidacao para separar o que está vivo do que é histórico.
A remoção de uma UR do contrato exige que a data de liquidação da UR esteja ao menos D+3 dias úteis à frente da data atual, e é processada somente entre 09:00 e 18:00 em dias úteis — ver Remover UR do contrato. Esta listagem, por ser leitura, não tem restrição de horário.
Para ver o extrato de liquidações e os ônus incidentes sobre uma UR específica, use 5.5. Detalhes da UR do contrato.
Totais consolidados do contrato: 5.3. Detalhes do contrato.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.