--- title: 5.4. Listar URs do contrato url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/5.%20Contrato%20de%20receb%C3%ADveis/v1.1/5.4.%20Listar%20URs%20do%20contrato/ --- # 5.4. Listar URs do contrato ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ----------------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/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 ```bash 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 ```json { "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](5.5.%20Detalhes%20da%20UR%20do%20contrato.md). 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`. ```json { "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](../../3.%20Notificações%20-%20WebHook/3.3.%20Atualizações%20da%20UR.md). * 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](5.5.%20Detalhes%20da%20UR%20do%20contrato.md). * Totais consolidados do contrato: [5.3. Detalhes do contrato](5.3.%20Detalhes%20do%20contrato.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).