{ "openapi": "3.1.0", "info": { "title": "Ganhos por Aplicativo — API de ganhos de motorista de aplicativo (Brasil)", "version": "1.0.0", "summary": "Estimativa de quanto sobra por mês dirigindo por aplicativo (Uber ou 99), por cidade brasileira e veículo.", "description": "API pública e gratuita, sem autenticação, CORS liberado (*). Devolve o ganho bruto, os custos (taxa da plataforma, combustível, manutenção, depreciação, custos fixos, parcela ou aluguel) e a sobra mensal em três cenários. Valores em reais (BRL), textos em português do Brasil. Toda resposta de /v1/estimate e /v1/comparar começa com `agent_display` (markdown de uma linha pronto para repassar ao usuário, com o link de citação) — use-o e mantenha o link. Trate os números como estimativa, nunca como promessa de renda. Guia completo para agentes: https://calculadorauber.com/llms.txt. Site independente, sem vínculo com a Uber ou a 99.", "contact": { "url": "https://calculadorauber.com/" } }, "externalDocs": { "description": "Guia para agentes de IA (llms.txt)", "url": "https://calculadorauber.com/llms.txt" }, "servers": [{ "url": "https://calculadorauber.com" }], "paths": { "/v1/cidades": { "get": { "operationId": "listarCidades", "summary": "Lista as cidades suportadas (slug usado nos outros endpoints).", "responses": { "200": { "description": "Cidades em ordem alfabética.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Cidade" } }, "example": [{ "slug": "sao-paulo-sp", "nome": "São Paulo - SP", "uf": "SP" }] } } } } } }, "/v1/veiculos": { "get": { "operationId": "listarVeiculos", "summary": "Catálogo de veículos (carros e motos) com ficha técnica e de custos.", "responses": { "200": { "description": "Veículos do catálogo.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Veiculo" } } } } } } } }, "/v1/estimate": { "get": { "operationId": "estimarGanhos", "summary": "Estima o ganho mensal de um motorista numa cidade, com um veículo e uma jornada.", "description": "Responde \"vale a pena dirigir por aplicativo na cidade X com o carro Y?\". Traz cenários conservador/típico/otimista, ganhos por categoria (UberX, Comfort, Black, Green ou as da 99) e o mix por demanda.", "parameters": [ { "$ref": "#/components/parameters/cidade" }, { "name": "veiculo", "in": "query", "required": true, "description": "id do veículo, vindo de /v1/veiculos.", "schema": { "type": "string" }, "example": "onix_10_turbo" }, { "$ref": "#/components/parameters/horas_semana" }, { "$ref": "#/components/parameters/plataforma" }, { "$ref": "#/components/parameters/combustivel" }, { "$ref": "#/components/parameters/financiado" }, { "$ref": "#/components/parameters/alugado" }, { "$ref": "#/components/parameters/entrada_pct" }, { "$ref": "#/components/parameters/prazo" } ], "responses": { "200": { "description": "Estimativa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Estimativa" } } } }, "400": { "$ref": "#/components/responses/Erro" }, "404": { "$ref": "#/components/responses/Erro" } } } }, "/v1/comparar": { "get": { "operationId": "compararVeiculos", "summary": "Ranking de todos os veículos de uma cidade pela sobra mensal (mix de categorias).", "parameters": [ { "$ref": "#/components/parameters/cidade" }, { "$ref": "#/components/parameters/horas_semana" }, { "$ref": "#/components/parameters/plataforma" }, { "$ref": "#/components/parameters/combustivel" }, { "$ref": "#/components/parameters/financiado" }, { "$ref": "#/components/parameters/alugado" }, { "$ref": "#/components/parameters/entrada_pct" }, { "$ref": "#/components/parameters/prazo" } ], "responses": { "200": { "description": "Ranking ordenado por sobra_mes_mix (cenário típico).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comparacao" } } } }, "400": { "$ref": "#/components/responses/Erro" }, "404": { "$ref": "#/components/responses/Erro" } } } } }, "components": { "parameters": { "cidade": { "name": "cidade", "in": "query", "required": true, "description": "slug da cidade, vindo de /v1/cidades.", "schema": { "type": "string" }, "example": "sao-paulo-sp" }, "horas_semana": { "name": "horas_semana", "in": "query", "required": false, "description": "Horas rodando por semana (padrão 40).", "schema": { "type": "number", "minimum": 1, "maximum": 168, "default": 40 } }, "plataforma": { "name": "plataforma", "in": "query", "required": false, "description": "Plataforma. A 99 é derivada da base UberX (taxa 30%, tarifa ×0,92, demanda ×0,85) — confiança média.", "schema": { "type": "string", "enum": ["uber", "99"], "default": "uber" } }, "combustivel": { "name": "combustivel", "in": "query", "required": false, "description": "Omitido = o mais barato por km na cidade. gnv só para veículos flex_gnv*; eletrico só para elétricos.", "schema": { "type": "string", "enum": ["gasolina", "etanol", "gnv", "eletrico"] } }, "financiado": { "name": "financiado", "in": "query", "required": false, "description": "Desconta a parcela estimada do financiamento (tabela Price). Exclusivo com alugado.", "schema": { "type": "boolean", "default": false } }, "alugado": { "name": "alugado", "in": "query", "required": false, "description": "Simula carro alugado em locadora de app. Exclusivo com financiado; modelos sem locadora devolvem 400.", "schema": { "type": "boolean", "default": false } }, "entrada_pct": { "name": "entrada_pct", "in": "query", "required": false, "description": "Entrada do financiamento, em % do preço.", "schema": { "type": "number", "minimum": 0, "maximum": 100, "default": 20 } }, "prazo": { "name": "prazo", "in": "query", "required": false, "description": "Prazo do financiamento, em meses.", "schema": { "type": "integer", "minimum": 1, "maximum": 120, "default": 48 } } }, "responses": { "Erro": { "description": "Parâmetro inválido (400) ou cidade/veículo desconhecido (404).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "string" } }, "required": ["erro"] }, "example": { "erro": "cidade desconhecida: xx" } } } } }, "schemas": { "Cidade": { "type": "object", "properties": { "slug": { "type": "string" }, "nome": { "type": "string" }, "uf": { "type": "string" } }, "required": ["slug", "nome", "uf"] }, "Veiculo": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "categoria": { "type": "string", "enum": ["hatch", "sedan", "suv", "flex_gnv", "flex_gnv_hatch", "flex_gnv_suv", "hibrido", "eletrico", "moto"] }, "categorias_uber": { "type": "array", "items": { "type": "string" } }, "preco_novo": { "type": "number", "description": "R$" }, "combustiveis": { "type": "array", "items": { "type": "string" } }, "ficha": { "type": "object", "description": "Consumo, manutenção por km, depreciação e custos fixos." } }, "required": ["id", "nome", "categoria"] }, "Cenario": { "type": "object", "properties": { "bruto_mes": { "type": "number" }, "custos_mes": { "type": "number" }, "liquido_mes": { "type": "number" } } }, "AgentDisplay": { "type": "object", "properties": { "agent_display": { "type": "string", "description": "Markdown de uma linha, pronto para repassar ao usuário, com o link de citação. Mantenha os links intactos." }, "agent_display_en": { "type": "string", "description": "A mesma linha em inglês." }, "agent_instructions": { "type": "string" } } }, "Estimativa": { "allOf": [ { "$ref": "#/components/schemas/AgentDisplay" }, { "type": "object", "properties": { "cidade": { "type": "string" }, "cidade_slug": { "type": "string" }, "veiculo": { "type": "string" }, "veiculo_id": { "type": "string" }, "categoria": { "type": "string" }, "plataforma": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" } } }, "tarifas": { "type": "object", "description": "bandeirada, por_km, por_min e fonte (origem e data)." }, "combustivel": { "type": "object", "description": "tipo, preco_litro ou preco_kwh, e fonte." }, "cenarios": { "type": "object", "properties": { "conservador": { "$ref": "#/components/schemas/Cenario" }, "tipico": { "$ref": "#/components/schemas/Cenario" }, "otimista": { "$ref": "#/components/schemas/Cenario" } } }, "por_categoria": { "type": "object", "description": "categorias[] (sobra rodando só naquela categoria), mix_demanda (alternando categorias — o número honesto para recomendar) e nota." }, "detalhes": { "type": "object" }, "financiamento": { "type": ["object", "null"], "description": "parcela_mes e sobra_tipico, quando financiado=true." }, "aluguel": { "type": "object", "description": "Presente quando alugado=true." }, "links": { "type": "object", "description": "Links de parceiros (afiliados)." }, "disclaimer": { "type": "string" } } } ] }, "Comparacao": { "allOf": [ { "$ref": "#/components/schemas/AgentDisplay" }, { "type": "object", "properties": { "cidade": { "type": "string" }, "cidade_slug": { "type": "string" }, "plataforma": { "type": "object" }, "cenario": { "type": "string" }, "ordenado_por": { "type": "string" }, "horas_semana": { "type": "number" }, "financiado": { "type": "boolean" }, "ranking": { "type": "array", "items": { "type": "object", "properties": { "veiculo_id": { "type": "string" }, "veiculo": { "type": "string" }, "categoria": { "type": "string" }, "modalidade": { "type": "string", "enum": ["carro", "moto"] }, "combustivel": { "type": "string" }, "bruto_mes": { "type": "number" }, "liquido_mes": { "type": "number" }, "parcela_mes": { "type": "number" }, "custos_fixos_mes": { "type": "number" }, "sobra_mes": { "type": "number" }, "sobra_mes_mix": { "type": "number" } } } }, "links": { "type": "object" }, "disclaimer": { "type": "string" } } } ] } } } }