O que é uma API? Entenda como funciona com exemplos

Você acaba de fechar uma venda no WhatsApp. O cliente pagou no Pix. O endereço caiu no Google Maps. O estoque baixou no sistema da loja. Nenhum desses programas fala a mesma língua: cada um é de uma empresa diferente. O que liga um ao outro é quase sempre uma API.

Se você não programa, isso ainda te afeta. Quando o checkout trava, o login com Google some ou a ferramenta de IA “não encontra” a planilha, o problema costuma estar nessa ponte, não no botão que você clicou. Entender o contrato por trás economiza tempo com suporte, evita colar chave secreta no lugar errado e ajuda a decidir se vale integrar dois sistemas ou se a planilha ainda resolve.

O que é uma API

API é a sigla de Application Programming Interface: interface de programação de aplicações. Aqui, “interface” não é tela. É o conjunto de regras que um sistema publica para outro sistema usar.

Pense num contrato, não num cabo. O contrato diz o que você pode pedir, o que precisa enviar, em que formato a resposta volta e o que acontece se algo der errado. Quem pede (o cliente) não precisa saber como o outro lado guarda o estoque ou autentica o cartão. Precisa só cumprir o contrato.

No dia a dia você já usa APIs sem ver o nome: Pix entre bancos, “continuar com Google”, mapa no aplicativo de entrega, mensagem no WhatsApp Business, o ChatGPT lendo um arquivo que você autorizou.

Um exemplo concreto: a loja consulta o estoque

O site precisa saber se a camiseta M azul ainda tem unidade. O estoque mora em outro sistema, o mesmo do balcão. Em vez de alguém ligar para o depósito, o site faz um pedido à API.

O pedido (a requisição), em linguagem comum:

• método: GET (só consultar, sem alterar nada)
• endereço: o endpoint `/estoque/camiseta-m-azul`
• identificação: um token que prova que aquele site pode ler estoque

A API responde em JSON, texto organizado em pares “nome: valor”. Uma resposta bem-sucedida pode ser:

• quantidade: 7
• sku: camiseta-m-azul
• disponivel: verdadeiro
• atualizadoEm: 2026-08-26T16:40:00

O site lê `quantidade` e mostra “comprar” ou “avise-me”. Ninguém abriu o banco do depósito. Se o token estiver errado, vem um 401: o site não inventa estoque.

O mesmo padrão vale para um formulário de lead. O visitante preenche nome e e-mail. O site envia um POST para `/leads`. A API grava o contato no CRM e devolve `id: 8841` e `status: criado`. O “recebemos seu pedido” na tela é a tradução humana dessa resposta.

O que é um endpoint

Endpoint é o endereço específico de uma operação. Não é o site inteiro. É a porta certa daquele prédio.

`https://api.lojaexemplo.com/estoque/camiseta-m-azul` é um endpoint. `https://api.lojaexemplo.com/leads` é outro. O começo (o host) diz qual serviço. O caminho (`/estoque/...`, `/leads`) diz qual recurso.

Na documentação, o endpoint quase sempre aparece junto do método: GET `/estoque/{sku}`, POST `/leads`. A parte entre chaves (`{sku}`) é um espaço que você preenche. Trocar o método no mesmo endereço muda o significado: GET `/leads/8841` consulta o lead; DELETE `/leads/8841` pede para apagá-lo. Se o suporte diz “o endpoint mudou na versão 2”, o botão na tela pode ser o mesmo. O pedido por baixo, não.

GET, POST, PUT, PATCH e DELETE no trabalho

HTTP é o protocolo da web para pedir e responder. Os verbos abaixo aparecem em quase toda integração. Não precisa decorar a RFC. Precisa saber quando cada um entra no trabalho.

• GET: consultar. Ver estoque, baixar relatório, listar pedidos do dia. GET não deveria mudar nada no outro sistema.
• POST: criar. Enviar um lead, emitir uma cobrança, mandar uma mensagem. Cada POST bem-sucedido costuma gerar um registro novo, com um id.
• PUT ou PATCH: atualizar. PUT manda o recurso inteiro. PATCH manda só o pedaço que mudou (“troque o telefone”). No trabalho: corrigir endereço, marcar pedido como enviado, atualizar ticket.
• DELETE: remover. Cancelar um webhook, apagar rascunho, revogar token. Em sistemas sérios, “apagar” às vezes só arquiva. Confirme na documentação o que de fato acontece.

O erro comum em ferramenta no-code (Make, Zapier, n8n) é usar POST quando se queria só consultar, e duplicar o lead. O verbo é a diferença entre “olhei” e “gravei de novo”.

O que os códigos de status dizem para quem usa a ferramenta

A resposta HTTP traz um número. Para quem usa a ferramenta, é o motivo pelo qual o botão funcionou ou falhou.

• 200: deu certo. A consulta voltou.
• 201: criado. O POST fez um registro novo. Costuma vir um id; guarde-o para consultar ou atualizar depois.
• 400: pedido malformado. Faltou campo, e-mail inválido, data no formato errado. Não é “o servidor caiu”. Corrija o dado.
• 401: não autenticado. Token ausente, expirado ou errado. Religue a conexão ou gere outra chave.
• 403: autenticado, mas sem permissão. Aquele endpoint é de outro plano ou de outro papel. Quase nunca se resolve tentando de novo.
• 404: não encontrado. Endpoint errado, id que não existe, versão antiga da API.
• 429: muitas requisições. O fornecedor cortou o ritmo. Espere; insistir em loop piora.
• 500: erro no lado do servidor. O contrato foi cumprido do seu lado; o outro sistema quebrou. Espere e, se persistir, acione o suporte com horário e o id da requisição.

Um 400 pede que você corrija o envio. Um 500 pede que você espere ou escale.

API não é o banco de dados

O banco guarda a informação. A API decide como outro sistema chega nela, e se chega.

Essa diferença importa por quatro motivos. Permissão: o vendedor vê o próprio estoque, não o salário do sócio. Formato: a API devolve um padrão que o outro sistema entende. Histórico: registra quem pediu o quê. Limite: ninguém deveria puxar a base inteira de clientes num GET só.

Por isso “me dá acesso ao banco” e “me dá uma API” não são o mesmo pedido. O segundo é mais estreito, mais auditável e, na maior parte das empresas, o único que deveria sair para um parceiro.

Pública, privada e de terceiro

Três tipos aparecem no trabalho, misturados.

Pública. Qualquer pessoa (ou qualquer conta) pode chamar, às vezes com cadastro grátis: feriado, CEP, previsão do tempo. Continua havendo limite e, muitas vezes, chave.

Privada. Só sistemas da própria empresa. Estoque interno, RH, financeiro. Se um fornecedor pede “a API privada de vocês”, isso é decisão de segurança, não de marketing.

De terceiro. Você usa o contrato de outra empresa: Mercado Pago, Google, Meta, OpenAI. O risco extra é dependência: se o terceiro muda o endpoint, cai a sua operação.

A maior parte das automações no escritório é API de terceiro costurada em ferramenta no-code. O ChatGPT que “fala com a planilha” não milagrou uma conexão. Chamou uma API.

Autenticação e segredos

Quase toda API útil pede prova de identidade: uma chave, um token, um OAuth (“entrar com Google” e autorizar o app). Essa prova é segredo, no mesmo nível de senha de banco.

Nunca cole chave de API em código que roda no navegador, em repositório no GitHub (mesmo “só um teste”), nem em chat de IA, Slack, e-mail ou planilha compartilhada.

O mesmo princípio vale quando a ferramenta é um chat de inteligência artificial. Colar um token “só para a IA configurar a integração” vaza o token. No Camada Prática já tratamos o caso vizinho: resumir reunião e e-mail sem mandar dado de cliente para o modelo errado. A regra se aplica aqui com mais força: uma chave de API não é um nome, é uma porta aberta.

Se a chave vazar: revogue na hora no painel do fornecedor, gere outra, avise quem cuida de segurança. Não “troque uma letra e torça”.

Como ler uma documentação simples de API sem ser engenheiro

Na primeira página a doc parece hostil. Você precisa de seis blocos. O resto é detalhe.

1. URL base. O começo de todos os endereços, por exemplo `https://api.fornecedor.com/v1`.
2. Autenticação. Onde vai a chave: cabeçalho Authorization, query string, OAuth. Copie o exemplo da doc.
3. Lista de endpoints. Método, caminho, o que faz. Procure a ação que você quer (“criar cobrança”, “listar contatos”) antes de ler o resto.
4. Parâmetros e corpo. Campos obrigatórios, tipo (texto, número, data) e um exemplo. Se a doc pede `email` e você manda `e-mail`, leva 400.
5. Resposta de sucesso. O JSON de 200 ou 201. É dali que a ferramenta puxa `id`, `status`, `quantidade`.
6. Erros. A lista de 400, 401, 403, 404, 429. Alguns fornecedores devolvem um `code` interno além do status HTTP. Anote os dois.

Ignore no começo SDKs e webhooks avançados. Copie o exemplo de Request da página, troque só a chave e o dado real, e rode no Postman, no Insomnia ou no painel do fornecedor. Se o exemplo oficial falha, o problema é credencial, ambiente (sandbox versus produção) ou a doc desatualizada.

Limites, rate limit e quando a planilha ainda basta

Toda API séria tem teto. Rate limit é o máximo de pedidos por minuto ou dia. Passou, vem 429. Antes de consultar estoque a cada segundo, leia a cota: uma vez por minuto quase sempre chega.

Há também o limite inverso: quando não usar API.

• A lista tem 40 linhas, muda duas vezes por semana, e só uma pessoa usa. Planilha resolve.
• O dado não pode sair da empresa e o fornecedor é conta pessoal. Não integre.
• Você quer a informação “ao vivo” só por hábito, não por decisão. Atualizar de manhã basta.
• Ninguém na equipe vai olhar o erro 401 às 23h. Integração sem dono vira fogo silencioso.

API é custo de manutenção: chave, versão, limite, pessoa que entende o contrato. Use quando dois sistemas precisam se falar com frequência, com regra e com registro. Não use para parecer moderno.

O que fazer agora

Hoje: abra uma ferramenta que você já usa, o checkout, o WhatsApp Business, o login do escritório. Em “integrações”, “desenvolvedores” ou “API”, anote a URL base, o tipo de autenticação e um endpoint que faça sentido para o seu trabalho. Não precisa chamar nada ainda. Só identificar.

Nesta semana: escolha uma integração real, formulário do site para o CRM, pagamento aprovado para o WhatsApp. Escreva o contrato em uma frase: “quando X acontecer, o sistema A avisa o sistema B com os campos Y”. Se a frase não sai, ainda não é hora de ligar a API.

Se for usar inteligência artificial no meio, a ponte entre sistemas não autoriza colar chave nem ata crua no chat.

API é só um contrato publicado. Quem se dá bem com ela não é quem decora JSON. É quem sabe o que está pedindo, o que pode vazar, e quando a planilha ainda é o instrumento certo.