Ir para o conteúdo

5.2. Listar contratos

🔗 Endpoint

Método URL
GET /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 —, 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

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

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

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

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