Integração Financeira ILEVA

Visão geral

Todo o financeiro do associado vive na API ILEVA. A partir do CPF do cliente, dois endpoints cobrem quase tudo; um terceiro traz o histórico de pagamento.

CPF do cliente
      │
      ├─ GET /associado/buscar?cpf_cnpj=<CPF>              → cod_associado, cadastro, veículos
      │
      └─ GET /cobranca/listar-associado-veiculo?cpf=<CPF>  → boletos + PIX + linha digitável + PDF
                                                             (endpoint principal: payload completo)
            │
            └─ GET /cobranca/listar?cod_associado=&situacao=Liquidado  → histórico de pagamento

Todos os endpoints, parâmetros e payloads desta página foram testados em produção em 16/10/2026 via Postman.

Credenciais

Três valores, fornecidos pela equipe responsável pela integração. Nenhum deles aparece nesta página.

Autenticação

POST /oauth/token devolve um Bearer token.

curl -X POST "https://api.ileva.com.br/oauth/token" \
  -H "app_key: $ILEVA_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"'"$ILEVA_USERNAME"'","password":"'"$ILEVA_PASSWORD"'"}'

{ "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 86400 }

Headers em toda chamada seguinte:

Authorization: Bearer <access_token>
app_key: <APP_KEY>

Comportamento do token

Declara expires_in: 86400 (24h) e no teste de 16/10/2026 aceitou 6 chamadas seguidas com o mesmo token. Porém a API invalida tokens de forma imprevisível: uma chamada voltou {"status":401,"mensagem":"Token..."} e a chamada idêntica seguinte, com token novo, funcionou. Historicamente o comportamento era de 1 token = 1 chamada.

Boletos + PIX

GET /cobranca/listar-associado-veiculo — o endpoint principal. Boleto, PIX, linha digitável, PDF, dados do associado e veículos num payload só.

Pelo menos um filtro é obrigatório — sem nenhum, volta 400 "Pelo menos um parâmetro dever ser informado". Para filtrar por situação, filtre no cliente ou use /cobranca/listar.

curl "https://api.ileva.com.br/cobranca/listar-associado-veiculo?inicio_paginacao=0&quantidade_por_pagina=100&cpf=00000000000" \
  -H "app_key: $ILEVA_APP_KEY" -H "Authorization: Bearer $TOKEN"

Resposta

{
  "total_encontrados": 13,
  "boletos": [{
    "cod_cobranca": 100001,
    "linha_digitavel": "75691.23453 00000.123455 67890.000176 1 16210000012359",
    "apresentar_boleto": 1,
    "valor_boleto": "123.59",
    "valor_pagamento": "0.00",
    "referencia": "2026-10",
    "dt_vencimento": "2026-11-05",
    "dt_pagamento": null,
    "dt_criacao": "2026-10-15",
    "situacao_boleto": "Aberto",
    "nosso_numero": "000001",
    "dt_vencimento_original": null,
    "url_boleto": "https://<conta>.ileva.com.br/api/associado/boleto/<hash>",
    "url_boleto_web": "https://<conta>.ileva.com.br/associado/cobranca/<hash>",
    "nome_associado": "NOME DO ASSOCIADO",
    "cpf": "00000000000",
    "telefone": "85900000000",
    "cod_associado": 1001,
    "situacao_associado": "ATIVO",
    "tipo_boleto": "Fechamento",
    "pix": "00020101021226950014br.gov.bcb.pix2573pix.sicoob.com.br/qr/payload/v2/cobv/<uuid>5204000053039865802BR5909PIXSICOOB6006CIDADE62070503***6304<CRC16>",
    "veiculos": [{
      "cod_veiculo": 2001,
      "placa": "ABC1D23",
      "chassi": "<chassi>",
      "ano_fabricacao": 2015,
      "ano_modelo": "2015-5",
      "dt_contrato": "2026-10-15",
      "modelo": "CG 150 START FLEXONE",
      "situacao_veiculo": "ATIVO",
      "marca": "Honda",
      "valor": "123.59"
    }]
  }]
}

Histórico

GET /cobranca/listar — listagem por situação. É o único que respeita situacao, por isso é o caminho do histórico de pagamento.

Alguns campos mudam de nome em relação ao endpoint principal: aqui é valor (não valor_boleto), situacao (não situacao_boleto) e associado (não nome_associado). placa, cod_veiculo e cod_boleto_veiculo vêm na raiz, sem o array veiculos. Normalize os dois formatos numa camada de modelo só.

Cadastro

GET /associado/buscar aceita cod_associado ou cpf_cnpj (ambos validados).

curl "https://api.ileva.com.br/associado/buscar?cpf_cnpj=00000000000" \
  -H "app_key: $ILEVA_APP_KEY" -H "Authorization: Bearer $TOKEN"

{ "associado": {
  "nome": "NOME DO ASSOCIADO", "cpf": "00000000000", "tel_whatsapp": "85900000000",
  "tel_celular": null, "tel_comercial": null, "dt_nascimento": "1990-01-01",
  "email": "cliente@exemplo.com", "rg": "0000000", "orgao_expedidor_rg": "SSP CE",
  "cnh": "00000000000", "categoria_cnh": "AB", "dt_vencimento_cnh": null,
  "logradouro": "Rua Exemplo", "bairro": "Centro", "numero": "100", "complemento": ".",
  "cep": "60000-000", "sexo": "M", "cod_regional": 1, "regional": "Regional Exemplo",
  "cod_associado": 1001, "cidade": "Fortaleza", "estado": "Ceará", "uf": "CE",
  "dt_cadastro": "2026-10-15", "situacao": "ATIVO", "situacao_tipo": "ATIVO", "cod_situacao": 1,
  "cod_conta": null, "conta_descricao": null, "conta_beneficiario_ndoc": null,
  "veiculos": [{ "placa": "ABC1D23", "modelo": "CG 150 START FLEXONE", "cod_veiculo": 2001,
                 "situacao": "ATIVO", "situacao_tipo": "ATIVO", "cod_situacao": 1 }]
} }

Endpoints complementares

Código de barras

A API não devolve o código de barras (44 dígitos) — só a linha_digitavel (47). A conversão é determinística e foi validada contra um boleto real.

Layout da linha digitável

47 dígitos, depois de remover pontos e espaços:

Montagem do barcode

barcode = d[0:4] + d[32] + d[33:47] + d[4:9] + d[10:20] + d[21:31]
          └banco+moeda  └DV  └fator+valor  └─── campo livre (25 díg.) ───┘

def linha_para_barcode(linha_digitavel: str) -> str:
    d = "".join(c for c in linha_digitavel if c.isdigit())   # 47 digitos
    return d[0:4] + d[32] + d[33:47] + d[4:9] + d[10:20] + d[21:31]

def dv_geral(barcode44: str) -> int:
    base = barcode44[:4] + barcode44[5:]        # tira o DV da posicao 5
    pesos, soma = [2,3,4,5,6,7,8,9], 0
    for i, c in enumerate(reversed(base)):
        soma += int(c) * pesos[i % 8]
    r = 11 - (soma % 11)
    return 1 if r in (0, 1, 10, 11) else r      # modulo 11, resto 0/1/10 -> DV 1

Exemplo verificado

linha  : 75691.23453 00000.123455 67890.000259 5 19250000012359
47 dig : 75691234530000012345567890000259519250000012359
barcode: 75695192500000123591234500000123456789000025   (44 digitos)
DV calculado = 5   |  DV na linha = 5                      ✓
valor no barcode = 123.59                                  ✓
fator 1925 -> 2027-09-05                                   ✓

Boleto fictício com dígitos verificadores válidos — mesmo algoritmo do teste contra o boleto real.

PIX

O campo pix já vem pronto como payload EMV copia-e-cola (BR Code, Sicoob).

00020101021226950014br.gov.bcb.pix2573pix.sicoob.com.br/qr/payload/v2/cobv/<uuid>5204000053039865802BR5909PIXSICOOB6006CIDADE62070503***6304<CRC16>

PDF e página do boleto

As duas são públicas, sem autenticação (hash na URL). url_boleto tem CORS liberado — dá para embutir ou baixar direto do app. Vêm null em boletos antigos.

Dicionário de campos

Fluxos recomendados

Boletos em aberto

1. CPF do cliente (cadastro/login do app)
2. GET /cobranca/listar-associado-veiculo?inicio_paginacao=0&quantidade_por_pagina=100&cpf=<CPF>
3. filtrar no cliente: situacao_boleto == "Aberto" && apresentar_boleto == 1
4. ordenar por dt_vencimento asc; marcar vencido = dt_vencimento < hoje
5. por boleto exibir: valor_boleto, dt_vencimento, linha_digitavel (copiar),
   barcode44 (para o widget de código de barras), pix (copiar / QR), url_boleto (PDF)

Histórico de pagamentos

1. GET /associado/buscar?cpf_cnpj=<CPF>  ->  cod_associado
2. GET /cobranca/listar?inicio_paginacao=0&quantidade_por_pagina=500&cod_associado=<ID>&situacao=Liquidado
3. ordenar por dt_pagamento desc; exibir valor, valor_pagamento, dt_vencimento, dt_pagamento, referencia
   (desconto/acréscimo = valor_pagamento - valor)

Financeiro por veículo

1. GET /associado/buscar?cpf_cnpj=<CPF>  ->  veiculos[].cod_veiculo / placa
2. GET /cobranca/listar-associado-veiculo?inicio_paginacao=0&quantidade_por_pagina=100&placa=<PLACA>
   (ou GET /cobranca/listar?inicio_paginacao=0&quantidade_por_pagina=500&cod_veiculo=<ID>)

Limitações e pontos de atenção