--- title: 5.2. Listar contratos 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.2.%20Listar%20contratos/ --- # 5.2. Listar contratos ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ------------------------------------ | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/public/api/v1.1/cartao/contratos` | --- ## 🧾 Descrição Retorna a **lista paginada dos contratos de recebíveis de cartão** do grupo econômico, com os filtros informados na query string. Use este endpoint para localizar o `identificador` de um contrato, acompanhar em que estágio do ciclo com a registradora ele está (`status`) e conciliar contratos com o ERP do cliente (`contratoErp`) ou com as tags de rastreabilidade da operação (`tags`). Como a criação é assíncrona — ver [5.1. Criar contratos](5.1.%20Criar%20contratos.md) —, esta listagem é o caminho natural para verificar se os contratos enviados foram efetivamente registrados. --- ## 📤 Requisição ### 🔍 Filtros (query string) | Parâmetro | Tipo | Obrigatório | Descrição | | -------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------- | | cnpj | string | Não | CNPJ do estabelecimento comercial (somente números, sem formatação). | | idOperacao | number | Não | ID da operação atrelada ao contrato (valor definido pelo time de implantação). | | idAgenda | string | Não | GUID da agenda que originou o contrato. | | status | number | Não | Filtra pelo status do contrato. Ver tabela **Status do contrato**. | | tipoContrato | number | Não | Filtra pelo tipo do contrato: `1` = Troca de titularidade, `2` = Garantia. | | contratoErp | string | Não | Código do contrato no ERP do cliente. | | tags | string[] | Não | Tags de rastreabilidade. Repita o parâmetro para informar mais de uma (ex.: `tags=PA_01&tags=PA_02`). | | dataInicial | string | Não | Considera contratos com `dataAssinatura` a partir desta data, no formato `YYYY-MM-DD`. | | dataFinal | string | Não | Considera contratos com `dataAssinatura` até esta data, no formato `YYYY-MM-DD`. | | dataVencimentoInicio | string | Não | Considera contratos com `dataVencimento` a partir desta data, no formato `YYYY-MM-DD`. | | dataVencimentoFim | string | Não | Considera contratos com `dataVencimento` 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.: `dataAssinatura`, `dataVencimento`, `valor`). | | direcaoOrdem | string | Não | — | Direção da ordenação: `asc` ou `desc`. | **Regras e formatos** * Datas no formato `YYYY-MM-DD`. * `cnpj`: somente dígitos (ex.: `12345678000199`). * Filtros são combinados entre si (E lógico). Quando nenhum filtro é informado, retorna todos os contratos do grupo econômico, do mais recente para o mais antigo. * `dataInicial` e `dataFinal` filtram pela **assinatura**; `dataVencimentoInicio` e `dataVencimentoFim` filtram pelo **vencimento**. Os dois intervalos podem ser combinados. --- ## 🧪 Exemplo de cURL ```bash curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/contratos?cnpj=12345678000199&tipoContrato=2&status=4&dataInicial=2025-08-01&dataFinal=2025-08-31&tags=PA_01&indicePagina=1&tamanhoDaPagina=20&ordem=dataAssinatura&direcaoOrdem=desc" \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Content-Type: application/json" ``` --- ## 📥 Responses ### ✅ 200 OK ```json { "registros": [ { "identificador": "5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6", "cnpj": "12345678000199", "tipoContrato": 1, "status": 4, "dataAssinatura": "2025-08-08", "dataVencimento": "2025-09-15", "valor": 48750.00, "contratoErp": "CTR-2025-0912", "tags": ["PA_01"] }, { "identificador": "9E3C7A21-4B58-4D93-8A6F-2C1D0E9B8A77", "cnpj": "12345678000199", "tipoContrato": 2, "status": 1, "dataAssinatura": "2025-08-08", "dataVencimento": "2026-02-10", "valor": 120000.00, "contratoErp": "CTR-2025-0913", "tags": ["PA_01", "GARANTIA"] } ], "paginacao": { "paginaAtual": 1, "paginaTotal": 3, "paginaQuantidadeRegistro": 20, "quantidadeRegistros": 47, "temPaginaAnterior": false, "temProximaPagina": true }, "mensagem": "Contratos listados com sucesso!" } ``` ### 🧾 Detalhamento dos Campos #### 🔹 registros | Campo | Tipo | Descrição | | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | identificador | string | GUID do contrato. Use-o nos demais endpoints da seção 5. | | cnpj | string | CNPJ do estabelecimento comercial titular das URs. | | tipoContrato | number | Tipo do contrato: `1` = Troca de titularidade, `2` = Garantia. Ver tabela **Tipo de contrato**. | | status | number | Status atual do contrato. Ver tabela **Status do contrato**. | | dataAssinatura | string | Data de assinatura do contrato (`YYYY-MM-DD`). | | dataVencimento | string | Data de vencimento final do contrato (`YYYY-MM-DD`). | | valor | number | Valor do contrato. Em contratos de troca de titularidade corresponde ao valor de aquisição pactuado; em contratos de garantia, ao valor garantido. | | contratoErp | string | Código do contrato no ERP do cliente, quando informado. | | tags | string[] | Tags de rastreabilidade associadas ao contrato. | #### 🔹 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. | --- ### 🔢 Tipo de contrato | Código | Significado | O que está registrado na registradora | | ------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------- | | 1 | Troca de titularidade | Troca de titularidade da UR — houve cessão ao fundo. É a única modalidade com deságio. | | 2 | Garantia | Ônus de cessão fiduciária sobre a UR. A titularidade permanece com o EC e **não há deságio**, portanto não há `taxa` nem valores de nominal, desconto e aquisição. | A configuração de **fumaça** (prazo estendido, somente URs performadas e regra de retenção) é uma variação da garantia: o contrato continua com `tipoContrato` igual a `2`. A **promessa de cessão** nunca é criada pela API — ela aparece apenas em leitura, como ônus de terceiro sobre a UR. --- ### 🔢 Status do contrato | Código | Significado | O que fazer | | ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------ | | 1 | Aguardando registro | Contrato recebido e na fila de envio à registradora. Aguarde a atualização por webhook. | | 2 | Registrando | Envio em andamento na registradora. | | 3 | Falha no registro | O registro não foi aceito. Verifique o motivo na notificação e refaça a operação a partir do carrinho. | | 4 | Aguardando liquidação | Contrato registrado com sucesso, aguardando as datas previstas de liquidação das URs. | | 5 | Cancelado | Contrato cancelado. Ocorre também quando as URs rejeitadas impedem o contrato de atingir o valor solicitado. | | 6 | Em liquidação | Já houve liquidação de parte das URs vinculadas. | | 7 | Liquidado | Todas as URs do contrato foram liquidadas. O contrato está encerrado. | | 8 | Em cancelamento | Pedido de cancelamento enviado, aguardando confirmação da registradora. | | 9 | Falha no cancelamento | O cancelamento não foi aceito pela registradora. O contrato permanece no estado anterior ao pedido. | | 10 | Incluindo UR | Inclusão de UR em andamento no contrato já registrado. | | 11 | Substituindo URs | Substituição de URs em andamento — típico da recomposição de garantia. | | 12 | Processando contrato | Processamento interno em andamento. Estado transitório: aguarde a próxima atualização antes de novas ações. | --- ### ❌ 400 Bad Request ```json { "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 'tipoContrato' inválido. Valores aceitos: 1 ou 2.", "Campo 'status' inválido. Valores aceitos: 1 a 12." ] } ``` --- ## 🕒 Observações * O contrato aparece nesta listagem assim que é criado em [5.1. Criar contratos](5.1.%20Criar%20contratos.md), ainda com `status` `1` (Aguardando registro) — antes, portanto, do retorno da registradora. * Os status `2`, `8`, `10`, `11` e `12` são **transitórios**: indicam processamento em andamento. Evite disparar novas ações sobre o contrato enquanto ele estiver em um desses estados. * Cada item do carrinho gera um contrato independente. Contratos originados da mesma agenda são recuperados pelo filtro `idAgenda`. * A janela de operação **09:00 às 18:00 em dias úteis** vale para a criação e o cancelamento de contratos, que dependem da registradora. Esta listagem pode ser consultada a qualquer momento. * As mudanças de `status` são notificadas por webhook — ver [3.2. Atualizações do contrato](../../3.%20Notificações%20-%20WebHook/3.2.%20Atualizações%20do%20contrato.md). Use esta listagem para conciliação, não como mecanismo de *polling* frequente. * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md). --- ## 🔄 Mudanças em relação à documentação anterior * Endpoint **novo**: antes não havia listagem de contratos — só era possível consultar um contrato por vez, pelo `identificador`. * A tabela **Status do contrato** documentava apenas os códigos `1` a `9`. Foram incluídos os códigos `10` (Incluindo UR), `11` (Substituindo URs) e `12` (Processando contrato), totalizando **doze** status. * A paginação segue o padrão da API: `indicePagina` e `tamanhoDaPagina`, com envelope `registros` + `paginacao` + `mensagem`.