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
- Entre no painel, cadastre suas contas TudoAzul e crie uma chave em API e plano.
- Guarde a chave num cofre de segredos. Ela só aparece uma vez.
- 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
| status | O que significa | O que fazer |
|---|---|---|
pending_login | Validando o login na Azul. | Aguardar. |
active | Conta válida e sincronizando. | Consultar saldo e extrato. |
invalid_credentials | A Azul recusou a senha. A conta parou de sincronizar. | PATCH /accounts/{id} com { "password": "…" }. |
login_error | Instabilidade 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âmetro | Exemplo | Descrição |
|---|---|---|
from / to | 2026-11-01 | Período (inclusive), AAAA-MM-DD. |
account_id | uuid | Filtra uma conta (só em /transactions). |
category | flight_redemption | Uma das categorias abaixo. |
direction | credit | debit | Só entradas ou só saídas. |
q | HLJZHJ | Busca na descrição e no localizador. |
page / page_size | 1 / 100 | Paginação. page_size vai até 500. |
format | json | csv | xlsx | CSV 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.datetimeestá 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
| category | Nome no painel | Quando aparece |
|---|---|---|
flight_redemption | Resgate de voo | Pontos usados para emitir passagem |
flight_accrual | Emissão / voo | Emissão de voo registrada (geralmente 0 pontos) |
refund | Reembolso | Pontos devolvidos por cancelamento |
transfer | Transferência | Transferência de programas como Livelo, Esfera e bancos |
purchase | Compra de pontos | Compra de pontos na Azul |
club | Clube TudoAzul | Pontuação mensal do Clube TudoAzul |
partner | Parceiro | Acúmulo em parceiros (cartões, varejo) |
expiration | Expiração | Pontos expirados |
adjustment | Ajuste | Estornos, correções e reprocessamentos |
other | Outros | Demais 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." }]
}
}| code | HTTP | Quando |
|---|---|---|
unauthorized | 401 | Chave ausente, inválida ou revogada. |
not_found | 404 | A conta não existe ou não pertence à sua chave. |
validation_error | 422 | Parâmetro ou corpo inválido. Veja `details`. |
account_limit_reached | 409 | Seu plano não comporta mais contas. |
duplicate_account | 409 | Este CPF já está cadastrado. |
sync_too_soon | 429 | Sincronização manual pedida há menos de 5 minutos. |
quota_exceeded | 429 | A cota mensal de requisições acabou. |
rate_limited | 429 | Muitas requisições no mesmo minuto. Respeite `Retry-After`. |
internal_error | 500 | Erro 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.
| Free | Pro | Business | |
|---|---|---|---|
| Requisições por mês | 1.000 | 50.000 | 500.000 |
| Requisições por minuto | 30 | 120 | 600 |
| Contas TudoAzul | 2 | 25 | 200 |
| Sincronização automática | a cada 24 h | a cada 4 h | a 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.