Integre o extrato TudoAzul ao seu sistema

A API do extratomilhas entrega, em JSON, CSV ou Excel, o saldo e o extrato das contas TudoAzul que você cadastrou. A gente cuida do login na Azul, da sincronização e da limpeza dos dados. Seu sistema só consulta.

URL base
https://extratomilhas.trevis.app/api/v1
Formato
JSON (UTF-8), datas AAAA-MM-DD
Autenticação
Bearer com chave cm_live_…

Início rápido

  1. Entre no painel, cadastre suas contas TudoAzul e crie uma chave em API e plano.
  2. Guarde a chave num cofre de segredos. Ela só aparece uma vez.
  3. Chame a API com a chave no header Authorization:
curl https://extratomilhas.trevis.app/api/v1/accounts \
  -H "Authorization: Bearer $EXTRATOMILHAS_KEY"
{
  "data": [
    {
      "id": "0193a7c2-…",
      "label": "Cliente Ana",
      "cpf_masked": "***.***.*47-25",
      "customer_number": "1234567890",
      "name_on_account": "Ana Souza",
      "tier": "SAFIRA",
      "status": "active",
      "status_message": null,
      "points_balance": 152340,
      "last_sync_at": "2026-11-18T13:00:00.000Z"
    }
  ]
}

Autenticação

Toda requisição leva Authorization: Bearer cm_live_…. A chave pertence ao seu usuário e enxerga todas as suas contas. Guardamos só um hash: se perder a chave, revogue-a e crie outra no painel. Uma chave revogada passa a receber 401 na hora.

Nunca use a chave no navegador ou em apps móveis. Chame a API a partir do seu servidor.

Cadastrar contas

O cadastro é assíncrono. A API responde 202 na hora, com a conta em pending_login, e valida o login na Azul em segundo plano. Isso leva de 10 a 30 segundos. Consulte a conta até o status mudar.

curl -X POST https://extratomilhas.trevis.app/api/v1/accounts \
  -H "Authorization: Bearer $EXTRATOMILHAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cpf": "529.982.247-25", "password": "senha-tudoazul", "label": "Cliente Ana"}'

Status de uma conta

statusO que significaO que fazer
pending_loginValidando o login na Azul.Aguardar.
activeConta válida e sincronizando.Consultar saldo e extrato.
invalid_credentialsA Azul recusou a senha. A conta parou de sincronizar.PATCH /accounts/{id} com { "password": "…" }.
login_errorInstabilidade na Azul. Tentamos de novo sozinhos.Nada. O status volta para active quando der certo.

Para remover, use DELETE /accounts/{id}. O CPF e a senha cifrados são apagados na hora.

Consultar o extrato

GET /transactions traz o extrato de todas as contas, e GET /accounts/{id}/transactions traz o de uma conta. Os resultados vêm do mais recente para o mais antigo. Sem from, o período padrão é dos últimos 90 dias.

ParâmetroExemploDescrição
from / to2026-11-01Período (inclusive), AAAA-MM-DD.
account_iduuidFiltra uma conta (só em /transactions).
categoryflight_redemptionUma das categorias abaixo.
directioncredit | debitSó entradas ou só saídas.
qHLJZHJBusca na descrição e no localizador.
page / page_size1 / 100Paginação. page_size vai até 500.
formatjson | csv | xlsxCSV e Excel trazem tudo de uma vez (até 50.000 linhas).
curl "https://extratomilhas.trevis.app/api/v1/transactions?from=2026-11-01&category=flight_redemption" \
  -H "Authorization: Bearer $EXTRATOMILHAS_KEY"
{
  "data": [
    {
      "id": "0193a7d1-…",
      "account_id": "0193a7c2-…",
      "account_label": "Cliente Ana",
      "date": "2026-11-10",
      "datetime": "2026-11-10T08:15:00",
      "description": "Booking: HLJZHJ | From Fortaleza to Viracopos International Airport",
      "category": "flight_redemption",
      "points": -12000,
      "booking_code": "HLJZHJ",
      "origin_iata": "FOR",
      "destination_iata": "VCP",
      "partner_name": "Azul"
    }
  ],
  "page": 1,
  "page_size": 100,
  "total": 1,
  "totals": { "credits": 0, "debits": -12000 }
}
  • points é positivo para crédito e negativo para débito. datetime está no horário de Brasília.
  • description é o texto original da Azul. Localizador e trecho (códigos IATA) já vêm extraídos.
  • A Azul devolve no máximo 100 transações por dia e por conta. Em dias com mais movimento que isso, o extrato daquele dia pode vir incompleto.

Sincronização

Cada conta é sincronizada automaticamente, no intervalo do seu plano. A primeira importação traz todo o histórico que a Azul guarda e pode levar alguns minutos em contas grandes. O campo last_sync_at diz quando o dado foi atualizado, e o saldo vem da própria Azul.

Para forçar uma atualização, use POST /accounts/{id}/sync, no máximo uma vez a cada 5 minutos por conta.

Categorias

categoryNome no painelQuando aparece
flight_redemptionResgate de vooPontos usados para emitir passagem
flight_accrualEmissão / vooEmissão de voo registrada (geralmente 0 pontos)
refundReembolsoPontos devolvidos por cancelamento
transferTransferênciaTransferência de programas como Livelo, Esfera e bancos
purchaseCompra de pontosCompra de pontos na Azul
clubClube TudoAzulPontuação mensal do Clube TudoAzul
partnerParceiroAcúmulo em parceiros (cartões, varejo)
expirationExpiraçãoPontos expirados
adjustmentAjusteEstornos, correções e reprocessamentos
otherOutrosDemais lançamentos, como aceite de campanha

Erros

Todo erro vem no mesmo formato:

{
  "error": {
    "code": "validation_error",
    "message": "Dados inválidos.",
    "details": [{ "path": "from", "message": "Use o formato AAAA-MM-DD." }]
  }
}
codeHTTPQuando
unauthorized401Chave ausente, inválida ou revogada.
not_found404A conta não existe ou não pertence à sua chave.
validation_error422Parâmetro ou corpo inválido. Veja `details`.
account_limit_reached409Seu plano não comporta mais contas.
duplicate_account409Este CPF já está cadastrado.
sync_too_soon429Sincronização manual pedida há menos de 5 minutos.
quota_exceeded429A cota mensal de requisições acabou.
rate_limited429Muitas requisições no mesmo minuto. Respeite `Retry-After`.
internal_error500Erro do nosso lado. Pode tentar de novo.

Limites e cota

Cada resposta informa a cota do mês nos headers X-Quota-Limit, X-Quota-Remaining e X-Quota-Reset. A cota renova no dia 1, à meia-noite de Brasília. Requisições recusadas por limite não contam.

FreeProBusiness
Requisições por mês1.00050.000500.000
Requisições por minuto30120600
Contas TudoAzul225200
Sincronização automáticaa cada 24 ha cada 4 ha cada 1 h

Você acompanha o consumo em API e plano ou por GET /usage.

Referência completa

Todos os endpoints, schemas e um console para testar requisições.

Abrir a referência