A API do Guia do Milheiro é gratuita?

Sim! Os endpoints públicos de cotação e consulta de promoções são 100% gratuitos com CORS aberto, permitindo uso em planilhas Google Sheets, bots e projetos pessoais.

Qual é o limite de requisições (Rate Limit)?

Endpoints públicos possuem limite de 60 requisições por minuto por endereço IP. O envio autenticado via POST permite até 120 requisições por minuto. Caso exceda, a API responde com código HTTP 429 Too Many Requests.

Developer Hub · API v1

Documentação da API do Milheiro

Q: Como importar as cotações diretamente no Google Sheets?

Basta colar a fórmula =IMPORTDATA("https://www.guiadomilheiro.com/api/v1/cotacao?format=csv") em qualquer célula da sua planilha.

Construa bots, dashboards e planilhas automatizadas com dados oficiais e em tempo real sobre cotações de milhas, bônus de transferência e comparações de passagens aéreas no Brasil.

🛡️ Políticas de Rate LimitJanela Deslizante de 60 segundos

Para garantir alta disponibilidade para toda a comunidade, implementamos limites automáticos por IP:

Tipo de Endpoint	Limite por IP	Autenticação	CORS
Leitura Pública (Cotação / Promoções)	60 requisições / minuto	Nenhuma (Livre)	Liberado (`*`)
Ingestão de Dados (POST Promoções)	120 requisições / minuto	`Bearer Token`	Protegido
Consulta de Referências de Rotas	100 requisições / minuto	Nenhuma	Liberado (`*`)

Headers HTTP retornados: Todas as respostas incluem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Caso excedido, a resposta será 429 Too Many Requests com o tempo de espera em Retry-After.

⚡ Início Rápido (Quickstart)

Escolha sua ferramenta favorita para começar a consumir a API em menos de 1 minuto:

1. Google Sheets (Sem código)

Cole esta fórmula exata na célula A1 de uma nova planilha Google Sheets:

=IMPORTDATA("https://www.guiadomilheiro.com/api/v1/cotacao?format=csv")

2. cURL / Terminal

curl -s https://www.guiadomilheiro.com/api/v1/cotacao

3. JavaScript / TypeScript

const response = await fetch('https://www.guiadomilheiro.com/api/v1/cotacao'); const { programs } = await response.json(); console.log('Cotação Smiles:', programs.smiles.price); console.log('Cotação LATAM Pass:', programs.latampass.price);

4. Python

import requests url = "https://www.guiadomilheiro.com/api/v1/cotacao" data = requests.get(url).json() for prog_id, info in data["programs"].items(): print(f"{info['name']}: R$ {info['price']:.2f} (24h: {info['change_24h']})")

Catálogo de Endpoints

GET/api/v1/cotacaoou/api/v1/cotacoes

Retorna as cotações de mercado atualizadas para Smiles, LATAM Pass, Azul Fidelidade, Livelo, Esfera e TAP. Suporta formato JSON padrão ou CSV para planilhas.

Parâmetros de Consulta (Query Params)

Parâmetro	Tipo	Padrão	Descrição
`program`	string	todos	Filtra por programa específico: `smiles`, `latampass`, `azul`, `livelo`, `esfera`, `tap`.
`format`	string	`json`	Use `format=csv` para obter retorno em formato compatível com Google Sheets (`=IMPORTDATA(...)`) ou Excel.

Exemplo de Resposta (200 OK)

{ "status": "ok", "updated_at": "2026-09-14T14:00:00.000Z", "attribution": "Guia do Milheiro — API Oficial do Milheiro", "currency": "BRL", "count": 6, "programs": { "smiles": { "name": "Smiles", "price": 15.20, "priceRef": "R$ 15,20", "range": "R$ 14,00 a R$ 17,50", "change24h": "+0,66%", "trend": "up", "liquidity": "Alta" }, "latampass": { "name": "LATAM Pass", "price": 23.80, "priceRef": "R$ 23,80", "range": "R$ 21,00 a R$ 26,50", "change24h": "-0,42%", "trend": "down", "liquidity": "Alta" } } }

GET/api/v1/promotions

Lista as promoções de milhas ativas detectadas pelo monitor do Guia do Milheiro.

Parâmetros de Consulta (Query Params)

Parâmetro	Tipo	Padrão	Descrição
`days`	number	`30`	Janela de dias para buscar ofertas (1 a 365).
`limit`	number	`100`	Quantidade máxima de itens retornados (1 a 500).
`program`	string	todos	Filtra ofertas por programa (ex: `Smiles`).

POST/api/v1/promotions

Ingestão de lotes de promoções coletadas via scripts parceiros ou cron jobs locais.

Header Obrigatório: Authorization: Bearer <SUA_CHAVE_API>

curl -X POST https://www.guiadomilheiro.com/api/v1/promotions \ -H "Authorization: Bearer SUA_CHAVE_SECRETA" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "program": "Smiles", "text": "Transfira pontos e ganhe até 100% de bônus.", "bonus_pct": 100, "source_name": "Página Oficial", "source_url": "https://www.smiles.com.br/promocoes" } ] }'

GET/api/v1/comparador/lookup?mode=route&route=GRU-THE

Consulta benchmarks históricos de emissões para pares de aeroportos (ex: GRU-THE, CGH-SDU, GRU-MIA).

POST/api/v1/calculations/cpm

Calcula o Custo por Milheiro (CPM) real com base no investimento financeiro e no total de milhas geradas.

// Requisição curl -X POST https://www.guiadomilheiro.com/api/v1/calculations/cpm \ -H "Content-Type: application/json" \ -d '{"investment": 300.0, "miles": 20000}' // Resposta (200 OK) { "cpm": 15.0 }

POST/api/v1/calculations/compare

Compara uma passagem emitida com milhas versus preço em dinheiro, retornando recomendação oficial, economia real e o Break-Even CPM.

// Requisição curl -X POST https://www.guiadomilheiro.com/api/v1/calculations/compare \ -H "Content-Type: application/json" \ -d '{ "miles": 50000, "cpm": 16.50, "taxes": 120.0, "cash_price": 1200.0, "passengers": 1, "basis": "total" }' // Resposta (200 OK) { "recommendation": "EMITIR COM MILHAS", "savings": 255.0, "break_even_cpm": 21.60, "award_total": 945.0, "cash_total": 1200.0 }

POST/api/v1/calculations/transfer

Simula transferências bonificadas de pontos de cartão/banco para programas de milhas aéreos.

// Requisição curl -X POST https://www.guiadomilheiro.com/api/v1/calculations/transfer \ -H "Content-Type: application/json" \ -d '{ "points": 10000, "price_per_thousand": 33.0, "bonus_pct": 100, "transfer_ratio": 1.0, "fees": 0 }' // Resposta (200 OK) { "final_miles": 20000, "effective_cpm": 16.50, "total_cost": 330.0 }

GET/api/v1/programs

Lista todos os programas de fidelidade monitorados com slugs padronizados e nomes de exibição.

// Resposta (200 OK) { "items": [ { "slug": "smiles", "name": "Smiles" }, { "slug": "latam-pass", "name": "Latam Pass" }, { "slug": "azul-fidelidade", "name": "Azul Fidelidade" }, { "slug": "skypass-(tap)", "name": "Skypass (TAP)" }, { "slug": "multi-(agregador)", "name": "Multi (agregador)" } ] }

GET/api/v1/clubs

Retorna os benchmarks de clubes de fidelidade (Clube Smiles, LATAM Pass, Azul, Livelo, Esfera, TAP) com planos, CPM médio padrão, CPM promocional e veredito estratégico se compensa assinar.

Parâmetros opcionais: ?program=smiles (filtra por programa) e ?format=csv (exporta para Google Sheets via =IMPORTDATA()).

// Requisição JSON curl -X GET "https://www.guiadomilheiro.com/api/v1/clubs?program=smiles" // Resposta (200 OK) { "status": "ok", "item": { "id": "smiles", "name": "Clube Smiles", "marketPrice": 15.20, "avgStandardCpm": 42.00, "avgPromoCpm": 14.50, "verdictType": "promocao_apenas", "verdictTitle": "Compensa apenas em campanhas de adesão bonificada", "plans": [ { "name": "Plano 1.000", "monthlyPrice": 42.00, "standardCpm": 42.00, "promoCpm": 14.50 } ] } }

Termos de Uso da API

A API Pública do Guia do Milheiro é fornecida gratuitamente com as seguintes diretrizes de boa convivência:

Atribuição Simples: Ao utilizar nossos dados em ferramentas abertas, sites ou planilhas públicas, mencione a fonte com um link para guiadomilheiro.com.
Respeito ao Rate Limit: Não utilize múltiplos IPs ou proxies rotativos para burlar o limite de 60 requisições por minuto.
Cache Recomendado: As cotações e promoções têm validade estável; recomendamos armazenar em cache por pelo menos 15 a 30 minutos em sua aplicação para obter máxima performance.

Dúvidas Frequentes de Desenvolvedores

Como lidar com o erro 429 (Rate Limit)?

Quando receber HTTP 429, inspecione o cabeçalho Retry-After na resposta. Ele indica exatamente quantos segundos seu cliente deve aguardar antes de realizar a próxima chamada.

A API funciona diretamente no frontend (navegador)?

Sim! Os endpoints de leitura possuem cabeçalhos Access-Control-Allow-Origin: * habilitados, portanto você pode chamar via fetch() diretamente no React, Vue, Angular ou vanilla JS sem erros de CORS.

Como solicitar limites maiores ou parcerias?

Caso necessite de volumes elevados de requisições ou feeds dedicados para empresas de turismo e fintechs, entre em contato através da nossa página de Contato.