O que é API: como funciona, na prática, com APIs públicas brasileiras

API (Application Programming Interface) é a porta pela qual um programa pede dados ou ações a outro. Quando o formulário de uma loja preenche o seu endereço sozinho depois que você digita o CEP, o site fez uma pergunta a um serviço de CEP e recebeu a resposta em um formato que o código entende.

A melhor forma de entender é fazer uma chamada. Todos os exemplos abaixo usam serviços públicos brasileiros que funcionam sem cadastro, conferidos em 16 de outubro de 2026.

Sua primeira chamada, em 10 segundos

Cole este endereço na barra do navegador:

https://viacep.com.br/ws/01001000/json/

A ViaCEP devolve o endereço do CEP 01001-000, a Praça da Sé, em São Paulo:

{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "estado": "São Paulo",
  "regiao": "Sudeste",
  "ibge": "3550308",
  "ddd": "11"
}

Isso foi uma chamada de API. O navegador enviou uma requisição HTTP do tipo GET para um endereço (o endpoint), e o servidor respondeu com dados em JSON em vez de uma página para pessoas lerem. O campo ibge é o código oficial do município, usado para cruzar esse dado com outras bases públicas.

As quatro partes de uma requisição

Toda chamada a uma API web tem as mesmas peças, definidas pelo protocolo HTTP:

A resposta volta com um código de status, cabeçalhos e um corpo. Os métodos mais usados são GET (ler), POST (criar), PUT e PATCH (alterar) e DELETE (remover). Por baixo, tudo isso viaja pelas mesmas camadas da web que levam qualquer página até você.

O mesmo pedido em curl, Python e JavaScript

Agora usando a BrasilAPI, um projeto aberto que reúne CEP, CNPJ, bancos, feriados e outras bases em um só lugar.

Terminal (curl):

curl https://brasilapi.com.br/api/cep/v2/01001000

Python (instale antes com pip install requests):

import requests

url = "https://brasilapi.com.br/api/cep/v2/01001000"
resposta = requests.get(url, timeout=10)
resposta.raise_for_status()

dados = resposta.json()
print(dados["street"], "-", dados["city"], "/", dados["state"])

JavaScript (navegador ou Node.js 18+, em um arquivo .mjs):

const resposta = await fetch("https://brasilapi.com.br/api/cep/v2/01001000");
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);

const dados = await resposta.json();
console.log(dados.street, "-", dados.city, "/", dados.state);

Os três imprimem Praça da Sé - São Paulo / SP. Repare que a BrasilAPI usa nomes de campo em inglês (street, city) e a ViaCEP em português (logradouro, localidade): cada API define o seu próprio contrato, e é a documentação que diz quais campos esperar. Se você está decidindo entre as duas linguagens, veja Python ou JavaScript.

APIs públicas brasileiras para praticar

No SGS do Banco Central, cada série tem um número: 433 é o IPCA mensal, 432 é a meta da Selic definida pelo Copom e 11 é a Selic diária. Uma chamada que busca os últimos 12 meses do IPCA cabe em uma linha de Python:

import requests

url = "https://api.bcb.gov.br/dados/serie/bcdata.sgs.433/dados/ultimos/12?formato=json"
for item in requests.get(url, timeout=10).json():
    print(item["data"], item["valor"] + "%")

Note que o SGS devolve datas no formato brasileiro (01/09/2026) e os valores como texto ("0.82"). Antes de fazer contas, converta com float(item["valor"]).

Os erros que essas APIs devolvem de verdade

Tratar erro é o que separa um script de teste de um programa confiável. Alguns comportamentos reais, observados em outubro de 2026:

CEP com formato inválido na ViaCEP. Um CEP com menos de 8 dígitos, letras ou espaço gera o status 400 (Bad Request). A própria documentação pede que você valide o formato antes de chamar.

CEP com formato válido, mas inexistente na ViaCEP. O status é 200, e não 404, com o corpo {"erro": "true"}. Quem verifica só o código de status vai achar que deu certo e quebrar ao ler logradouro. O certo é checar o campo:

dados = requests.get("https://viacep.com.br/ws/99999999/json/", timeout=10).json()
if dados.get("erro"):
    print("CEP não encontrado")

Período longo demais no Banco Central. Pedir a Selic diária (série 11) de 2000 a 2026 devolve 406 com a mensagem "O sistema aceita uma janela de consulta de, no máximo, 10 anos em séries de periodicidade diária". A solução é dividir a consulta em blocos de até 10 anos.

Excesso de chamadas. A ViaCEP avisa na página inicial que o uso massivo para validar bases de dados locais pode bloquear o acesso por tempo indeterminado. Em outras APIs, o limite aparece como status 429 (Too Many Requests). Guarde em cache o que já consultou e espace as chamadas.

Chaves, tokens e o que nunca fazer com eles

APIs que mexem com dados pessoais, dinheiro ou cotas pagas exigem identificação. As formas mais comuns são a chave de API (um código fixo enviado em cada chamada), o token Bearer (temporário, obtido por login) e o OAuth 2.0, padrão que permite a um aplicativo agir em seu nome em outro serviço sem receber sua senha. É o OAuth que está por trás do botão "Entrar com Google".

Os erros mais caros acontecem aqui:

• Chave dentro do código publicado. Robôs varrem repositórios públicos atrás de segredos; use variáveis de ambiente (os.environ["MINHA_CHAVE"] no Python) e um arquivo .env listado no .gitignore. O guia de Git e GitHub mostra como configurar.
• Chave no JavaScript do navegador. Qualquer visitante vê o código-fonte. A chamada com credencial deve sair do servidor, nunca do front-end.
• Confiar cegamente na resposta. Valide tipos e tamanhos antes de gravar no banco.
• Ignorar a LGPD. Se a API devolve dados pessoais, como os sócios de uma empresa na consulta de CNPJ, o uso e o armazenamento seguem as regras da Lei Geral de Proteção de Dados.

REST, GraphQL, webhooks: o vocabulário

• REST: estilo descrito por Roy Fielding em 2000, em que cada recurso tem uma URL e os métodos HTTP dizem a ação. As APIs deste artigo seguem esse modelo.
• GraphQL: um único endpoint em que o cliente descreve exatamente os campos que quer.
• gRPC: formato binário, comum entre serviços internos de grandes sistemas.
• SOAP: padrão mais antigo, em XML, ainda presente em integrações governamentais e bancárias.
• Webhook: o contrário de uma chamada; o serviço avisa o seu sistema quando algo acontece, como um pagamento aprovado.
• OpenAPI: especificação usada para documentar APIs REST; o Portal da Transparência, por exemplo, publica a sua documentação em Swagger, que segue esse padrão.

Onde as APIs aparecem no seu dia

O Pix e o Open Finance funcionam sobre APIs padronizadas pelo Banco Central entre instituições, como explica o guia de Open Finance. Apps de entrega usam APIs de mapas para calcular rotas, e lojas usam APIs de pagamento e de frete. Modelos de IA também são oferecidos por API, e rodar um modelo localmente com o Ollama expõe uma API no seu próprio computador.

Para ver onde a API se encaixa em um sistema completo, entre a tela e o banco de dados, leia front-end, back-end e banco de dados.

Fontes

• ViaCEP. Documentação e regras de uso (base de 16/10/2026).
• BrasilAPI. Repositório oficial e documentação.
• Banco Central do Brasil. Dados abertos: série 11, Taxa Selic.
• IBGE. API de localidades.
• Controladoria-Geral da União. API do Portal da Transparência (Swagger).
• Mozilla. Visão geral do HTTP e métodos de requisição.
• Mozilla. Códigos de status HTTP.
• Fielding, R. Architectural Styles and the Design of Network-based Software Architectures (2000).
• IETF. RFC 6749: OAuth 2.0.
• OpenAPI Initiative. Especificação OpenAPI.