5.2. Listar contratos¶

🔗 Endpoint¶

Método	URL
	`/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.

Contratos de um cedente específico, e os gerados automaticamente

Para listar os contratos de um único estabelecimento, filtre por cnpj. Para separar o que foi gerado pela antecipação automática do que foi criado manualmente ou por API, use origemAgenda. A configuração e o histórico de execuções do ciclo automático estão em Antecipação automática de cartão.

📤 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`).
origemAgenda	number	Não	Filtra pela origem da agenda que deu origem ao contrato: `1` = BATCH, `2` = ONLINE. Só se aplica a contratos gerados pela antecipação automática.
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"],
      "origemAgenda": 1
    },
    {
      "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"],
      "origemAgenda": null
    }
  ],
  "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.
origemAgenda	number	Origem da agenda que gerou o contrato: `1` = BATCH, `2` = ONLINE. Vem `null` em contratos criados manualmente ou por API, e só é preenchido nos gerados pela antecipação automática. Ver origemAgenda.

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