Duas empresas nunca combinaram nada entre si, não conhecem o código uma da outra, e ainda assim seus sistemas trabalham juntos. Isso funciona porque existe um contrato publicado no meio: uma API. Ela é uma das formas de fazer integração de sistemas, e a mais usada quando os dados precisam circular em tempo real.
Este texto explica como esse contrato funciona, quais formas você vai encontrar na prática, o que dá errado em integração, e o que mudou desde que agentes de IA passaram a ser consumidores de API como qualquer outro.
O que é uma API
API é a sigla de Application Programming Interface, ou interface de programação de aplicações. É um conjunto de regras publicadas que define como um sistema pode pedir dados ou ações a outro: quais endereços chamar, o que enviar, o que volta e o que acontece quando dá erro.
A palavra que importa na definição é interface. Uma API existe justamente para você não precisar saber como o outro sistema funciona por dentro. Se você quer mostrar um mapa no seu site, não precisa entender como o serviço de mapas calcula rota: você chama o endereço documentado, manda a origem e o destino, e recebe a rota. O que existe atrás disso é problema de quem publicou a API, e pode até mudar sem te avisar, desde que o contrato continue o mesmo.
É a mesma lógica de um caixa eletrônico. Você não precisa saber como o banco registra a transação; você precisa saber quais botões existem e o que cada um faz.
Como funciona: pedido, resposta e contrato
Na prática, uma chamada de API tem quatro partes: um endereço (endpoint), um método (buscar, criar, atualizar, apagar), um corpo ou parâmetros com o que você está mandando, e uma resposta em formato que a máquina lê, quase sempre JSON.
A melhor forma de ver isso é comparar a mesma informação nas duas formas. Abaixo, um perfil público do GitHub como uma pessoa o vê:
E o mesmo perfil, pelo endereço de API do GitHub, na forma que um sistema consome:
São a mesma informação. A diferença é que a segunda forma é previsível: o campo tem sempre o mesmo nome, no mesmo lugar. É isso que permite programar em cima dela sem que uma mudança visual quebre a integração.
REST, GraphQL e webhook
Você vai encontrar três formatos na prática, e a diferença entre eles muda a conta de esforço da integração.
| Formato | Como funciona | Quando aparece |
|---|---|---|
| REST | Você chama um endereço por recurso e recebe o que ele devolve, inteiro | É o padrão mais comum. Simples de começar, às vezes traz mais dado que o necessário |
| GraphQL | Você chama um único endereço e descreve exatamente quais campos quer | Útil quando a tela precisa de dado de várias fontes e você quer evitar chamadas em série |
| Webhook | Inverte a direção: em vez de você perguntar, o outro sistema avisa você quando algo acontece | Pagamento aprovado, pedido atualizado, mensagem recebida |
O webhook é o que mais economiza e o menos entendido. Sem ele, o padrão é ficar perguntando de minuto em minuto se algo mudou, o que gasta chamada e chega atrasado. Com ele, você recebe o aviso no momento em que acontece. A contrapartida é que você precisa ter um endereço público pronto para receber, e precisa lidar com aviso repetido, porque o remetente reenvia quando não tem confirmação.
Segurança de API não é senha de usuário
Aqui vale corrigir uma confusão comum, e a versão anterior deste texto a cometia: PIN, biometria e autenticação em dois fatores servem para provar quem é a pessoa. API não autentica pessoa, autentica quem está chamando, que normalmente é outro sistema. São mecanismos diferentes:
- Chave de API. Um segredo que identifica a aplicação chamadora. Simples e frágil: quem tem a chave, é você. Nunca no código do front-end, nunca no repositório.
- OAuth 2.0 e tokens. O padrão quando a chamada acontece em nome de um usuário. O token tem prazo e tem escopo, ou seja, permissão para fazer só aquilo.
- Escopo mínimo. A credencial deve poder fazer exatamente o necessário. Chave com permissão total para uma integração que só lê é o erro mais frequente.
- Limite de chamadas. Protege quem publica e revela abuso. Do lado de quem consome, é o que obriga a tratar recusa por excesso em vez de ignorá-la.
- Transporte cifrado e rotação de segredo. HTTPS sempre, e uma rotina para trocar credencial. Chave que nunca foi trocada em três anos é chave que provavelmente já vazou em algum lugar.
Vale registrar também que dado pessoal trafegando por API continua sob a mesma lei: quem controla responde pelo tratamento, inclusive pelo que o fornecedor faz com o que recebeu. É o assunto de LGPD e segurança da informação, e é onde integração feita às pressas costuma criar passivo.
O que dá errado em integração
- Assumir que a API é estável para sempre. APIs têm versão, e versão é descontinuada. Integração sem alguém acompanhando aviso de mudança quebra num dia qualquer, sem que ninguém tenha mexido no seu código.
- Tratar erro como exceção improvável. A chamada vai falhar: rede cai, limite estoura, o outro lado fica fora do ar. O que decide a qualidade da integração é o que acontece depois da falha, não o caminho felizardo.
- Ignorar o limite de chamadas até ele doer. Funciona no teste com dez registros e para de funcionar na carga real.
- Não ter onde ver o que aconteceu. Sem registro de chamada e resposta, investigar problema de integração é adivinhação.
- Dependência sem plano B. Se a operação para quando um fornecedor para, isso é decisão de risco, e precisa ser tomada de propósito e não por descuido.
Um caso concreto de integração bem delimitada, de um produto que a Northern desenvolveu: o Decode Juris traduz textos jurídicos usando inteligência artificial. A aplicação web cuida de cadastro, conta, plano e da tela de envio de texto; o modelo que faz a tradução vive separado. A API é o que liga os dois: a plataforma envia o texto, o serviço processa e devolve o resultado. Duas peças com responsabilidades distintas, cada uma podendo evoluir sem reescrever a outra, que é exatamente o ganho que uma interface bem definida entrega.
APIs e agentes de IA: o que mudou
Até pouco tempo, quem consumia API era software escrito por gente: um site, um aplicativo, um script de integração. Isso mudou. Modelos de IA passaram a chamar ferramentas por conta própria, decidindo quando buscar um dado ou executar uma ação, o que é a base da IA agêntica. E o meio pelo qual eles agem é a API.
Três consequências práticas para quem publica ou consome:
- A documentação virou requisito, não cortesia. Um agente decide o que chamar lendo a descrição de cada operação. Descrição ambígua produz chamada errada, e chamada errada agora significa ação errada num sistema, e não só uma tela feia.
- O escopo mínimo deixou de ser boa prática e passou a ser contenção. Se um agente pode chamar, a credencial dele precisa poder fazer exatamente o combinado, e nada além.
- Volume e custo mudam de comportamento. Agente que erra insiste, e insistir custa chamada. Limite e registro deixam de ser detalhe operacional.
Essa mudança de patamar dos modelos, de especialistas estreitos para uso geral, é o que descrevemos na evolução da inteligência artificial. Para o negócio, a leitura é direta: a empresa que já expõe as próprias operações por API está pronta para automatizar com agente; a que só tem tela, não está.
Onde achar APIs úteis
Uma nota antes da lista: o ProgrammableWeb, que por anos foi o diretório mais citado de APIs e aparecia na versão anterior deste texto, foi encerrado em 2022. Vale saber, porque ele ainda é recomendado em muito material antigo. O que existe hoje:
- Catálogos abertos e comunitários, que mantêm listas por categoria e são o caminho mais rápido para descobrir se existe API para o que você precisa.
- Marketplaces de API, onde é possível testar a chamada antes de integrar, comparando o que cada fornecedor devolve.
- Governo federal, no catálogo de serviços do Conecta gov.br, com APIs de dados públicos. Vale checar também município e estado.
- Documentação direta do fornecedor. É a fonte mais confiável, e a única que reflete a versão atual. Diretório envelhece; documentação oficial, não.
Antes de integrar qualquer coisa, duas perguntas resolvem metade dos problemas: o que acontece com a minha operação se essa API sair do ar por um dia, e quem no time vai receber o aviso quando a versão mudar. Se as respostas não existirem, a integração está sendo feita como aposta.
E uma ressalva sobre onde a integração roda: plataformas visuais integram bem com o que já suportam de fábrica e mal com o resto, o que limita justamente os casos de legado e de protocolo próprio. É a discussão de low code. Para o vocabulário dos tipos de aplicação envolvidos, o ponto de partida é software aplicativo; para delimitar o que entra na primeira integração, como definir escopo. E o exemplo mais comum de API que uma empresa passa a usar sem perceber é a de mensagem: está em como automatizar o atendimento no WhatsApp.
Perguntas frequentes
O que é uma API?
API é a sigla de Application Programming Interface, ou interface de programação de aplicações. É um conjunto de regras publicadas que define como um sistema pode pedir dados ou ações a outro: quais endereços chamar, o que enviar, o que volta e o que acontece quando dá erro. A palavra que importa é interface: a API existe para você não precisar saber como o outro sistema funciona por dentro.
Como funciona uma API na prática?
Uma chamada tem quatro partes: um endereço (endpoint), um método (buscar, criar, atualizar, apagar), um corpo ou parâmetros com o que você está mandando, e uma resposta em formato que a máquina lê, quase sempre JSON. A vantagem do formato é a previsibilidade: o campo tem sempre o mesmo nome, no mesmo lugar, então uma mudança visual no outro sistema não quebra a integração.
Qual a diferença entre REST, GraphQL e webhook?
Em REST você chama um endereço por recurso e recebe o que ele devolve inteiro; é o padrão mais comum e às vezes traz mais dado que o necessário. Em GraphQL você chama um único endereço e descreve exatamente quais campos quer. Webhook inverte a direção: em vez de você perguntar, o outro sistema avisa quando algo acontece, como pagamento aprovado ou pedido atualizado.
Para que serve um webhook?
Para receber aviso no momento em que algo acontece, em vez de ficar perguntando de minuto em minuto se mudou, o que gasta chamada e chega atrasado. A contrapartida é que você precisa ter um endereço público pronto para receber, e precisa lidar com aviso repetido, porque o remetente reenvia quando não recebe confirmação.
Como funciona a segurança de uma API?
API não autentica pessoa, autentica quem está chamando, que normalmente é outro sistema. Os mecanismos são chave de API, OAuth 2.0 com tokens que têm prazo e escopo, escopo mínimo de permissão, limite de chamadas, transporte cifrado por HTTPS e rotação periódica de segredo. PIN, biometria e autenticação em dois fatores servem para provar quem é a pessoa, que é um problema diferente.
Onde não devo guardar uma chave de API?
Nunca no código do front-end, porque qualquer visitante consegue ler, e nunca no repositório de código. Quem tem a chave é você, para todos os efeitos. Vale também dar à credencial apenas a permissão necessária: chave com permissão total para uma integração que só lê é o erro mais frequente.
O que costuma dar errado numa integração por API?
Cinco coisas. Assumir que a API é estável para sempre, quando ela tem versão e versão é descontinuada. Tratar erro como exceção improvável, quando rede cai e limite estoura. Ignorar o limite de chamadas até a carga real. Não ter registro de chamada e resposta, o que torna a investigação adivinhação. E criar dependência sem plano B, o que precisa ser decisão consciente e não descuido.
O que mudou nas APIs com os agentes de IA?
O consumidor mudou. Antes, quem chamava API era software escrito por gente; hoje modelos de IA chamam ferramentas por conta própria, decidindo quando buscar um dado ou executar uma ação, e o meio pelo qual eles agem é a API. Três consequências: documentação virou requisito porque o agente decide o que chamar lendo a descrição; escopo mínimo passou de boa prática a contenção; e volume e custo mudam, porque agente que erra insiste, e insistir custa chamada.
O ProgrammableWeb ainda existe?
Não. O ProgrammableWeb, que por anos foi o diretório de APIs mais citado, foi encerrado em 2022. Ele continua aparecendo em muito material antigo. Hoje o caminho são catálogos abertos e comunitários, marketplaces onde é possível testar a chamada antes de integrar, o catálogo do Conecta gov.br para dados públicos, e principalmente a documentação direta do fornecedor, que é a única fonte que reflete a versão atual.
Minha empresa precisa expor uma API?
Depende do que você quer permitir. Se o objetivo é que parceiros ou clientes integrem, ou que suas próprias operações possam ser automatizadas por agentes, então sim: a empresa que só tem tela não pode ser automatizada, e a que expõe operações por API pode. Antes de integrar qualquer coisa, duas perguntas resolvem metade dos problemas: o que acontece com a operação se essa API sair do ar por um dia, e quem no time recebe o aviso quando a versão mudar.
