# Retornar os contratos por filtro

Permite consultar contratos existentes, com suporte a filtros que facilitam a busca e a gestão dos contratos criados (ex. por cliente, data, status, entre outros).
Os parâmetros de múltiplos valores (ex.: cliente_id, tipo_pagamento) aceitam dois formatos equivalentes: chaves repetidas (?cliente_id=&cliente_id=) ou valores separados por vírgula (?cliente_id=,).

Endpoint: GET /v1/contratos
Version: v1
Security: BearerAuth

## Query parameters:

  - `pagina` (integer)
    Página
    Example: 1

  - `tamanho_pagina` (integer)
    Tamanho da página (máximo 50)
    Example: 10

  - `campo_ordenado_ascendente` (string)
    Campo para ordenação ascendente. Se informado ele desconsidera o valor do campo_ordenado_descendente.
    Enum: "DATA_INICIO", "DATA_FIM"

  - `campo_ordenado_descendente` (string)
    Campo para ordenação descendente. Se este campo for utilizado, o campo campo_ordenado_ascendente não deverá ser informado.
    Enum: same as `campo_ordenado_ascendente` (2 values)

  - `busca_textual` (string)
    Busca textual por nome
    Example: "Contrato 1"

  - `cliente_id` (array)
    id do cliente
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `data_inicio` (string, required)
    Data inicio do intervalo de busca
    Example: "2026-08-15"

  - `data_fim` (string, required)
    Data fim do intervalo de busca
    Example: "2027-08-15"

  - `tipo_pagamento` (array)
    Tipos de pagamento
    Enum: "BOLETO_BANCARIO", "CARTAO_CREDITO", "CARTAO_DEBITO", "CARTEIRA_DIGITAL", "CASHBACK", "CHEQUE", "CREDITO_LOJA", "CREDITO_VIRTUAL", "DEPOSITO_BANCARIO", "DINHEIRO", "OUTRO", "DEBITO_AUTOMATICO", "LINK_PAGAMENTO", "PIX_PAGAMENTO_INSTANTANEO", "COBRANCA_PIX", "PROGRAMA_FIDELIDADE", "SEM_PAGAMENTO", "TRANSFERENCIA_BANCARIA", "VALE_ALIMENTACAO", "VALE_COMBUSTIVEL", "VALE_REFEICAO"

  - `status` (string)
    Status dos contratos
    Enum: "TODOS", "ATIVO", "INATIVO", "PROXIMO_AO_VENCIMENTO"

## Response 200 fields (application/json):

  - `itens` (array)
    Lista de contratos

  - `itens.cliente` (object)
    Dados do cliente

  - `itens.cliente.id` (string)
    ID do cliente
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `itens.cliente.nome` (string)
    Nome do cliente
    Example: "João da Silva"

  - `itens.conta_financeira` (object)
    Conta financeira vinculada

  - `itens.conta_financeira.id` (string)
    ID da conta
    Example: "b0ff3efe-a7fe-4432-81ac-62ca1085529b"

  - `itens.conta_financeira.tipo` (string)
    Tipo de conta
    Enum: "APLICACAO", "CAIXINHA", "CONTA_CORRENTE", "CARTAO_CREDITO", "INVESTIMENTO", "OUTROS", "MEIOS_RECEBIMENTO", "POUPANCA", "COBRANCAS_CONTA_AZUL", "RECEBA_FACIL_CARTAO"

  - `itens.data_inicio` (string)
    Data de início do contrato
    Example: "2026-08-15"

  - `itens.id` (string)
    ID do contrato
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `itens.numero` (integer)
    Número do contrato
    Example: 1014

  - `itens.proximo_vencimento` (string)
    Data do próximo vencimento
    Example: "2026-08-15"

  - `itens.status` (string)
    Status do contrato
    Enum: "ATIVO", "INATIVO", "DELETADO"

  - `itens.termos` (object)
    Termos de vigência

  - `itens.termos.data_fim` (string)
    Data de término do contrato
    Example: "2026-10-21"

  - `itens.termos.tipo_expiracao` (string)
    Tipo de expiração
    Enum: "DATA", "VEZES", "NUNCA"

  - `itens.termos.vigencia_atual` (integer)
    Número de cobranças realizadas
    Example: 6

  - `itens.termos.vigencia_total` (integer)
    Total de cobranças previstas
    Example: 12

  - `itens.tipo_pagamento` (string)
    Tipo de pagamento
    Enum: "BOLETO_BANCARIO", "CARTAO_CREDITO", "CARTAO_DEBITO", "CARTEIRA_DIGITAL", "CASHBACK", "CHEQUE", "CREDITO_LOJA", "CREDITO_VIRTUAL", "DEPOSITO_BANCARIO", "DINHEIRO", "OUTRO", "DEBITO_AUTOMATICO", "LINK_PAGAMENTO", "PIX_PAGAMENTO_INSTANTANEO", "COBRANCA_PIX", "PROGRAMA_FIDELIDADE", "SEM_PAGAMENTO", "TRANSFERENCIA_BANCARIA", "VALE_ALIMENTACAO", "VALE_COMBUSTIVEL", "VALE_PRESENTE", "VALE_REFEICAO"

  - `itens.total` (number)
    Valor total do contrato
    Example: 1000

  - `itens.total_proximo_vencimento` (number)
    Valor da próxima cobrança
    Example: 1000

  - `itens_totais` (integer)
    Total de contratos encontrados
    Example: 1

## Response 400 fields (application/json):

  - `error` (string)
    Mensagem de erro
    Example: "Mensagem de erro detalhada"