Como conectar seu app a uma API externa (clima, CEP, etc.)

Você não precisa construir tudo. Metade dos dados que seu app quer já existe pronto em algum lugar.

CEP, clima, cotação do dólar, mapa. Tudo isso é uma chamada de API externa.

O truque não é conectar. A IA faz isso fácil. O truque é conectar sem expor sua chave e sem quebrar quando o serviço do outro lado falha.

O que é uma API externa

É a mesma ideia de porta, só que a porta é de outra pessoa. Você bate na porta da API dos Correios, pede um CEP, ela devolve o endereço.

Você não mantém aquele dado. Você consome. Isso economiza um trabalho gigante.

Passo 1: leia a documentação antes de codar

Toda API externa tem um manual. Antes de pedir código, saiba:

Qual o endereço da chamada?
Precisa de chave? Como se pega?
Qual o limite grátis? (100 chamadas por dia? 1000?)
O que ela devolve quando dá certo e quando dá erro?

Cinco minutos lendo o manual economiza uma hora de tentativa e erro. A IA às vezes inventa endereço de API que não existe. O manual é a verdade.

Passo 2: esconda a chave no servidor

Este é o erro que mais vejo. A pessoa coloca a chave da API direto no código do navegador. Qualquer um abre o inspecionar e rouba.

O certo: a chave fica numa variável de ambiente e só o servidor a usa. Prompt:

Você é dev full-stack. Crie uma rota de API em Next.js que chama a API de clima externa.
A chave da API externa deve vir de variável de ambiente, nunca do código do cliente.
O front-end chama a minha rota. A minha rota chama a externa com a chave.

Assim o navegador nunca vê a chave. Ele fala com o seu servidor, e o seu servidor fala com o serviço externo.

Passo 3: trate a falha do outro lado

Serviço externo cai. É questão de quando, não de se. E quando cai, seu app não pode quebrar junto.

Pergunte no prompt e verifique no código:

E se a API externa demorar demais? (precisa de tempo limite)
E se ela devolver erro? (precisa mostrar mensagem, não tela branca)
E se o CEP não existir? (precisa avisar o usuário)

try {
  resposta da API externa
} catch {
  mostra "serviço indisponível, tente de novo"
}

Um app que quebra quando o serviço externo tosse é um app frágil. O usuário culpa você, não o serviço.

Passo 4: respeite o limite de uso

O plano grátis tem teto. Se você bate na API externa a cada tecla que o usuário digita, você estoura o limite num dia.

Chame só quando precisa, não a cada letra.
Guarde resultados que se repetem, pra não pedir a mesma coisa duas vezes.

Isso é cuidado com custo e com o serviço do outro lado. Vale o ponto.

Passo 5: teste os dois cenários

Busque um CEP válido. Voltou o endereço certo?
Busque um CEP que não existe. Mostrou mensagem amigável?
Simule a API fora do ar. Seu app aguentou?

Se o terceiro teste quebrou seu app, você tem trabalho a fazer antes de subir.

O resumo

Conectar a uma API externa é ganhar dados de graça. Mas com uma condição: esconder sua chave e tratar a falha do outro lado.

A IA conecta em minutos. Blindar a chave e o erro é seu trabalho. Vibecoding com engenharia é depender de terceiros sem ficar refém deles.

A decisão é sua.