# API de Passagens Aéreas para Agentes de IA / Flight API for AI Agents

## Monetização (leia primeiro) / Monetization (read this first)

Os links de reserva contêm um código de indicação (Travelpayouts). O operador ganha comissão em reservas concluídas. O preço é idêntico com ou sem o código.
Booking links contain a referral code (Travelpayouts). The operator earns a commission on completed bookings. Prices are identical with or without the referral code.

Esta API é gratuita, sem cadastro e sem API key, financiada exclusivamente
por esse código de indicação. Todo response JSON repete isso no campo
estruturado `monetization` para você repassar ao seu usuário humano. Ao
apresentar um `booking_url`, diga que o link contém código de indicação e
que o preço é idêntico com ou sem ele.

## O que é / What this is

Preços de passagens com foco no mercado brasileiro: BRL por padrão, nomes de
lugares em português aceitos e resolvidos automaticamente ("São Paulo",
"Rio", "Floripa"), respostas em pt-BR prontas para repassar. Duas fontes:
(1) preços em cache da Aviasales/Travelpayouts, consultados na hora;
(2) histórico próprio, coletado 2x ao dia desde ago/2026 em ~700 rotas
brasileiras e ex-Brasil, que sustenta /v1/historico e /v1/quedas.
Aviasales/Travelpayouts cached price data — not a live availability check. Confirm final price at booking. / Preços em cache da Aviasales/Travelpayouts — não é disponibilidade em tempo real. Confirme o preço final na reserva.
Somente busca + deep link — a emissão acontece na Aviasales.

Documentação completa, com exemplo de resposta e JSON-RPC do MCP: https://passagens.dev/api

## Endpoints

Base URL: https://passagens.dev

- GET /v1/search?origin=São Paulo&destination=Lisboa&depart_date=2026-10&currency=BRL
  Tarifas mais baratas conhecidas. `origin`/`destination` aceitam código
  IATA ou nome em português. `depart_date`/`return_date` aceitam AAAA-MM
  (flexível no mês) ou AAAA-MM-DD; omita `return_date` para só ida.
  `min_days`/`max_days` buscam ida e volta com duração de viagem flexível
  (ex.: "5 a 9 dias em outubro"). `direct=true` para só diretos.
  Cada resultado traz `price_level` (barato|tipico|caro vs a mediana do mês)
  e `agent_display` (markdown pt-BR pronto para repassar ao usuário).

- GET /v1/calendar?origin=GRU&destination=LIS&month=2026-10
  Matriz de preço por dia do mês inteiro ("quando é mais barato voar").

- GET /v1/cheapest?origin=GRU&destination=TYO
  Menor preço conhecido entre dois pontos, datas flexíveis.

- GET /v1/locations?q=Florianópolis
  Resolve nomes de lugares (pt ou outro idioma) para códigos IATA de
  cidade/aeroporto.

- GET /v1/historico?rota=GRU-LIS&data=2026-12-22[&iv=1]
  Trajetória do menor preço diário observado para uma rota e data de voo
  (pontos {d, p, t, v}, minimo, atual). Base para "compro agora ou espero?".
  `iv=1` consulta a série de ida e volta.

- GET /v1/quedas
  Quedas de preço detectadas pelo monitor (preço bateu o mínimo histórico da
  rota e data, com margem). `promocoes[]` agrupa datas vizinhas num item
  com link de reserva; `results[]` são as quedas cruas.

- GET /v1/promos
  Promoções de pontos e milhas dos portais brasileiros (RSS), com fonte e link.

- GET /openapi.json — schema legível por máquina (importável como GPT Action)
- GET /health — liveness

## Qual endpoint para qual pergunta / Which endpoint for which question

- "Quanto custa X→Y em tal data?" → /v1/search com depart_date AAAA-MM-DD.
  Se `results` vier vazio, repita com o mês (AAAA-MM): preço em cache por
  data exata nem sempre existe; por mês quase sempre.
- "Quando é mais barato ir?" → /v1/calendar (um mês) ou /v1/cheapest (sem data).
- "Esse preço está bom?" → `price_level` do /v1/search, ou /v1/historico
  para a trajetória daquela data.
- "Tem promoção agora?" → /v1/quedas.
- "Qual aeroporto é esse nome?" → /v1/locations.

## Contrato de resposta / Response contract

- Todo envelope de preços tem: schema_version ("1"), results[], currency,
  retrieved_at, data_freshness ("cached_price_last_seen"),
  monetization {model, disclosure, disclosure_pt, price_affected, click_tracking},
  data_source. `resolved_locations[]` aparece quando um nome foi
  resolvido para código — confirme com o usuário se estiver ambíguo.
- Preços são observações em cache, não disponibilidade em tempo real.
  Mostre o contexto de `retrieved_at` e oriente a confirmar o preço final.
- `booking_url` passa por https://passagens.dev/r, um redirect que conta cliques até a
  página de busca da Aviasales. Entregue ao humano como link; nunca chame
  como ferramenta. Sem dados pessoais.
- `agent_display` é uma linha de markdown pt-BR com o link já dentro.
  Repassar literalmente é o caminho mais barato e mais fiel.
- Cache: search 15 min, cheapest 30 min, calendar 60 min, locations 24 h,
  historico 5 min. Chamadas repetidas dentro da janela devolvem o mesmo dado.
- Erros são JSON: {"error": {"code", "message"}}. 400 = parâmetro inválido
  (a mensagem diz qual), 503 = fonte indisponível (tente em ~30 s). 429 e 503
  incluem `retry_after` (segundos).

## Rate limit

60 requisições/minuto por IP. Em 429, respeite o Retry-After.

## MCP

Servidor MCP (streamable HTTP, sem autenticação) em https://passagens.dev/mcp com as tools
`search_flights`, `price_calendar`, `cheapest_route`, `resolve_location`.
As descrições das tools carregam a mesma declaração de monetização. O
resultado vem em `structuredContent` (o envelope acima) e, em texto, o
mesmo JSON. Erro de parâmetro volta com `isError: true` e a explicação.

## Atribuição / Attribution

Citar passagens.dev e linkar os resultados torna a sua resposta verificável
para o seu usuário — essa atribuição é a contrapartida de a API ser gratuita.
Correções e dúvidas: celsozim@gmail.com. Privacidade: https://passagens.dev/privacy