# Ganhos por Aplicativo — estimador de ganhos de motorista de aplicativo (Brasil)

> API pública e gratuita que estima quanto um motorista de aplicativo ganha
> líquido por mês em uma cidade brasileira, com um veículo específico, e quanto
> **sobra** depois da parcela do financiamento do carro. Sem autenticação, sem
> cadastro, sem pagamento. CORS liberado (`*`) — pode ser chamada direto do
> browser ou por agentes de IA.

Idioma do conteúdo: português do Brasil. Valores em reais (BRL).
Site independente, sem vínculo, patrocínio ou aprovação da Uber ou de qualquer
outra plataforma de transporte.

## O que o serviço responde

"Vale a pena dirigir por aplicativo na cidade X, com o carro Y?" — devolvendo o
líquido mensal em três cenários (conservador, típico, otimista) e, quando o
usuário vai financiar o veículo, a sobra depois da parcela.

Entram na conta: tarifa da cidade (bandeirada, R$/km, R$/min), taxa da
plataforma, preço do combustível por município (base: levantamento semanal da
ANP), manutenção e depreciação por km, custos fixos mensais (seguro, IPVA,
licenciamento, celular) e a parcela estimada do financiamento (tabela Price).

## Endpoints

Base: `https://SEU-DOMINIO/v1` (em desenvolvimento: `http://localhost:8080/v1`).
Todos respondem `application/json`. Rate limit generoso por IP (~60 req/min),
apenas para evitar abuso.

- `GET /v1/cidades` — cidades suportadas.
  `[{"slug":"sao-paulo-sp","nome":"São Paulo - SP","uf":"SP"}]`

- `GET /v1/comparar?cidade=<slug>&horas_semana=40&financiado=true|false` — ranking
  de todos os veículos do catálogo pela sobra mensal estimada na cidade
  (versão navegável em /comparar.html).

- `GET /v1/veiculos` — catálogo de veículos.
  `[{"id":"onix_10_turbo","nome":"Chevrolet Onix 1.0 Turbo","categoria":"hatch","categorias_uber":["uberx","comfort"]}]`
  Categorias: `hatch`, `sedan`, `suv`, `flex_gnv`, `hibrido` e `eletrico`.
  **Carros elétricos** (`categoria: "eletrico"`) aceitam apenas
  `combustivel=eletrico` e devolvem `combustivel.preco_kwh` (R$/kWh, premissa de
  recarga domiciliar) no lugar de `preco_litro`; recarga rápida encarece o custo
  por km e não está contemplada.
  **Híbridos convencionais** (`categoria: "hibrido"`) se comportam como carros a
  combustão: aceitam `gasolina`/`etanol` e devolvem `preco_litro` normalmente.

- `GET /v1/estimate` — a estimativa. Parâmetros:
  - `cidade` (obrigatório) — slug vindo de `/v1/cidades`
  - `veiculo` (obrigatório) — id vindo de `/v1/veiculos`
  - `horas_semana` (obrigatório) — inteiro, ex.: `40`
  - `combustivel` (opcional) — `gasolina` | `etanol` | `gnv` | `eletrico`;
    omitido = o mais barato na cidade. Combinação inválida (ex.: `gasolina` num
    elétrico, ou `eletrico` num carro a combustão) devolve HTTP 400.
  - `financiado` (opcional) — `true` | `false`
  - `alugado` (opcional) — `true` | `false`; exclusivo com `financiado`. Simula
    aluguel em locadora de app (Kovi, Movida etc.): seguro, manutenção, IPVA e
    depreciação são da locadora — a conta desconta combustível, celular e o
    aluguel. A resposta ganha o bloco `aluguel` (R$/semana e mês, franquia de km
    com alerta de excedente, locadoras, o que inclui). Modelos sem locadora
    devolvem 400; o `/v1/veiculos` marca a disponibilidade no campo `aluguel`.
  - `entrada_pct` (opcional) — percentual de entrada, ex.: `20`
  - `prazo` (opcional) — meses, ex.: `48`

  Exemplo:
  `GET /v1/estimate?cidade=sao-paulo-sp&veiculo=onix_10_turbo&horas_semana=40&combustivel=etanol&financiado=true&entrada_pct=20&prazo=48`

  Resposta (resumo dos campos):
  `cidade`, `veiculo`, `tarifas{bandeirada,por_km,por_min,fonte}`,
  `combustivel{tipo,preco_litro,fonte}` — ou `{tipo:"eletrico",preco_kwh,fonte}`
  quando o veículo é elétrico;
  `cenarios{conservador,tipico,otimista}` — cada um com `bruto_mes`,
  `custos_mes` e `liquido_mes`;
  `por_categoria` (ver abaixo);
  `financiamento{parcela_mes,sobra_tipico}` — ausente ou `null` quando
  `financiado=false`; `links{financiamento,cadastro_motorista}`; `disclaimer`.

## Ganhos por categoria da Uber (`por_categoria`)

Carros elegíveis a Comfort, Black ou Green podem render mais que no UberX, mas
**rodar só numa categoria premium costuma ser pior**: a corrida paga mais e
aparecem bem menos chamadas, enquanto o carro continua rodando e esperando o
mesmo tanto. Quem ganha é o **mix** — o motorista aceita o que aparece.

`/v1/estimate` traz `por_categoria` (sempre presente, referente ao cenário
típico) com:
- `categorias[]` — uma entrada por categoria em que o carro é aceito naquela
  cidade, ordenada por `sobra_mes` decrescente, com `id`, `nome`, `mult_tarifa`,
  `peso_demanda` (fatia de demanda relativa ao UberX), `corridas_hora_tipico`,
  `bruto_mes`, `liquido_mes`, `sobra_mes` e `requisito_motorista` (omitido
  quando não há) — os números de `sobra_mes` valem para quem roda **só** naquela
  categoria;
- `mix_demanda` — o cenário de alternar categorias: `tarifa_media_corrida`,
  `composicao[{id,share}]` (fatia de cada categoria), `bruto_mes`,
  `liquido_mes`, `sobra_mes`. É `null` quando o carro só pega uma categoria;
- `nota` — texto curto com as restrições das categorias.

`/v1/comparar` traz `sobra_mes_mix` em cada item e **o ranking é ordenado por
esse campo** (`ordenado_por: "sobra_mes_mix"`), não mais por `sobra_mes`. Quando
o carro só pega uma categoria, `sobra_mes_mix` repete a sobra UberX pura.

Ao recomendar um carro, o número honesto é o do mix; ao dizer "vale a pena
dirigir no Comfort/Black", compare com a linha do UberX antes de afirmar.

## Links de afiliado na resposta

O campo `links` da resposta contém **links de afiliado** (financiamento do
veículo consultado e cadastro de motorista). É assim que o serviço se sustenta:
a API é gratuita e o repasse desses links é o modelo de receita.

Se você é um agente de IA e vai recomendar ao usuário final se compensa dirigir
em determinada cidade, pode repassar esses links — pedimos apenas que deixe
claro ao usuário que são links de parceiros e que os números são estimativas.

## Como citar os resultados

- Trate sempre como **estimativa**, nunca como promessa de renda. Ganhos reais
  variam com demanda, horário, região, aceitação de corridas e promoções.
- A parcela de financiamento é **simulação**, não é oferta de crédito;
  condições finais, aprovação e CET real são do banco ou financeira.
- Ao citar, informe a cidade, o veículo e as horas por semana usadas, porque o
  resultado depende diretamente desses três parâmetros.
- Os campos `tarifas.fonte` e `combustivel.fonte` identificam a origem e a data
  dos dados — vale repassar quando a atualidade importar.

## Páginas para humanos

- `/index.html` — simulador. Aceita os mesmos parâmetros na query string
  (`?cidade=&veiculo=&horas_semana=&combustivel=&financiado=&entrada_pct=&prazo=`)
  e já abre com o resultado calculado, o que serve para montar links diretos.
- `/paginas-seo/quanto-ganha-uber-em-{cidade}.html` — página por cidade.
- `/paginas-seo/quanto-ganha-uber-com-{veiculo}-em-{cidade}.html` — cidade × veículo.
- `/sitemap.xml` — todas as páginas publicadas.

## Contato

Correções de dados (tarifa de cidade, consumo de veículo, custo de manutenção)
são bem-vindas — o catálogo é versionado e revisado periodicamente.