Como colocar consulta de placa num app feito na Lovable

A Lovable virou o jeito mais rápido de tirar um app do papel: em poucas horas sai o sistema da oficina, a ficha de avaliação da revenda ou o controle de entrada do estacionamento. Boa parte desses apps precisa de uma coisa que a Lovable não tem: os dados do veículo a partir da placa.

Neste tutorial você liga um app da Lovable à Simples API com um prompt e entende o único cuidado que faz diferença: onde fica a API key.

O que o app vai fazer

Você escolhe a consulta pela placa, a leitura pela foto ou as duas:

A consulta não traz multas, débitos, restrições nem dados do proprietário.

Antes de começar

1. Crie sua conta em simplesapi.com.br/register. Você ganha R$ 5 em créditos grátis, sem cartão de crédito.
2. Copie a sua API key no painel. Ela começa com sk_live_.
3. Tenha um projeto na Lovable com backend: o Lovable Cloud ou o Supabase ligado. É nele que roda a função que chama a API. Se o projeto ainda não tiver, a Lovable oferece ligar quando precisar.

Passo 1: cole o prompt

Os prompts prontos estão na página Apps feitos na Lovable, com um botão para copiar. Cada um tem três partes:

• API: endereço, endpoint, autenticação, exemplo de corpo e de resposta, os erros possíveis e o link da documentação. É o formato que a própria Lovable pede para integrar uma API.
• Segurança: onde a chamada roda e onde a chave fica (o motivo está mais abaixo).
• Tela: o que o usuário vê e quando a consulta acontece.

A parte de segurança é esta:

Segurança (obrigatório)
- Chame a Simples API só no servidor, numa Edge Function ou server function que lê o segredo SIMPLES_API_KEY. O frontend chama essa função, nunca a Simples API direto.
- A API key não pode aparecer no código do frontend nem voltar na resposta da função.
- Se o app tem login, a função só atende usuários logados: sem isso, qualquer pessoa que descobrir o endereço da função gasta o saldo da conta.
- Se a Simples API responder 403 BROWSER_API_KEY, a chamada saiu do navegador: mova-a para o servidor.

Cole o prompt no chat do projeto e envie.

Passo 2: guarde a chave como segredo

A Lovable vai pedir o segredo SIMPLES_API_KEY. Cole a sua API key no formulário de segredos que ela mostrar, nunca na mensagem do chat: o histórico do chat fica salvo no projeto, e o segredo fica guardado à parte, fora do código.

Passo 3: teste na prévia

Na prévia do app, digite uma placa ou tire uma foto. A consulta aparece no histórico de requisições do painel da Simples API, com o status e, se der errado, o motivo.

Por que a chamada precisa ficar no servidor

A Simples API aceita chamadas de qualquer site. Por isso, um código que chama a API direto do navegador funciona de primeira, e essa é a armadilha: para funcionar, a chave vai junto no JavaScript da página. Qualquer visitante abre as ferramentas do navegador, vê o header Authorization: Bearer sk_live_... e passa a consultar placas com o seu saldo.

Com a chamada no servidor, o caminho fica assim:

Navegador ──► sua função (lê SIMPLES_API_KEY) ──► Simples API

O navegador só conhece o endereço da sua função. A chave nunca sai do servidor.

Como conferir

1. Abra a prévia, aperte F12 e vá na aba Rede (Network).
2. Faça uma consulta.
3. A requisição deve ir para a sua função (em projetos com Supabase, um endereço terminado em .supabase.co/functions/v1/...), nunca para api.simplesapi.com.br.

Se aparecer api.simplesapi.com.br, peça à Lovable: "mova a chamada da Simples API para uma Edge Function que lê o segredo SIMPLES_API_KEY". Se a chave já foi publicada no código do site, gere outra no painel.

A função também precisa de proteção

Mover a chave para o servidor resolve o vazamento, mas a função continua sendo um endereço público. Se ela atende qualquer um, quem descobrir o endereço consegue consultar placas pelo seu app e gastar o seu saldo do mesmo jeito.

Num app com login, a função deve atender só usuários logados. Uma Edge Function do Supabase que faz isso fica mais ou menos assim:

// supabase/functions/consultar-placa/index.tsimport{ createClient }from'npm:@supabase/supabase-js@2'const corsHeaders ={'Access-Control-Allow-Origin':'*','Access-Control-Allow-Headers':'authorization, x-client-info, apikey, content-type',}Deno.serve(async(req)=>{if(req.method ==='OPTIONS'){returnnewResponse('ok',{ headers: corsHeaders })}// Só usuários logados no app consultamconst supabase =createClient(Deno.env.get('SUPABASE_URL')!, Deno.env.get('SUPABASE_ANON_KEY')!)const token = req.headers.get('Authorization')?.replace('Bearer ','')??''const{ data:{ user }}=await supabase.auth.getUser(token)if(!user){return Response.json({ message:'Faça login para consultar.'},{ status:401, headers: corsHeaders })}const{ plate }=await req.json()const response =awaitfetch('https://api.simplesapi.com.br/v1/vehicle/plate',{ method:'POST', headers:{ Authorization:`Bearer ${Deno.env.get('SIMPLES_API_KEY')}`,'Content-Type':'application/json',}, body:JSON.stringify({ plate }),})// Repassa os dados do veículo ou o erro, que traz "code" e "message"returnnewResponse(await response.text(),{ status: response.status, headers:{...corsHeaders,'Content-Type':'application/json'},})})

E o app chama a função assim:

import{ FunctionsHttpError }from'@supabase/supabase-js'import{ supabase }from'@/integrations/supabase/client'const{ data, error }=await supabase.functions.invoke('consultar-placa',{ body:{ plate:'ABC1D23'},})if(error instanceofFunctionsHttpError){const{ message }=await error.context.json()// mostre a message ao usuário}

Você não precisa escrever esse código: o prompt pede isso à Lovable. Ele serve para você saber o que procurar quando revisar o que ela gerou. Num app sem login, ligue o alerta de saldo baixo no painel e recarregue aos poucos.

Erros que o app deve tratar

Toda resposta de erro da Simples API traz um code e uma message em português, que o app pode mostrar direto ao usuário:

Para não gastar à toa, o prompt também pede que o app consulte só quando o usuário clicar em "Consultar" ou confirmar a foto, nunca enquanto ele digita.

E se a chave vazar?

Gere uma nova API key no painel: a antiga para de funcionar na hora. Depois, atualize o segredo SIMPLES_API_KEY na Lovable com a chave nova. Como o saldo é pré-pago, o gasto nunca passa do que você recarregou.

Funciona em outros construtores?

Sim. O prompt descreve a API e a regra de segurança sem depender da Lovable, então serve também para Bolt, v0, Replit e para o agente de código que você já usa. Em qualquer um deles, confira as mesmas duas coisas: a chave num segredo e a chamada saindo de uma função no servidor.

Próximos passos

• Copie os prompts em Apps feitos na Lovable.
• Veja os campos de cada resposta na documentação da API.
• Confira os preços e exemplos de custo em Preços.