API, webhook e integração: o que cada palavra significa

Em qualquer projeto que envolva dois sistemas, essas palavras aparecem. Entender o que significam muda a qualidade da conversa: você para de aceitar prazo sem entender o motivo e passa a fazer as perguntas certas.

API

É a porta de entrada de um sistema para outro sistema. Se o site é a vitrine para pessoas, a API é o balcão para programas. Ela define o que pode ser pedido, em que formato e com qual permissão.

Na prática: "o CRM tem API?" quer dizer "esse sistema tem um jeito documentado de outro programa consultar e gravar informação nele?". Se a resposta é não, a integração vai custar mais e ser mais frágil.

Endpoint

Cada endereço específico dentro de uma API. /imoveis devolve a lista de imóveis; /imoveis/1234 devolve um imóvel. É o "cardápio" da API.

REST

O estilo mais comum de API na web. Usa os verbos do próprio protocolo HTTP: GET para ler, POST para criar, PUT para atualizar, DELETE para remover. Não é uma tecnologia, é uma convenção - e é bom que exista uma.

JSON

O formato de texto em que os dados viajam. É legível por humanos e fácil para máquinas. Substituiu o XML na maior parte das integrações novas, embora o XML siga firme no mercado imobiliário por tradição dos portais.

Webhook

O caminho inverso da API. Em vez do seu sistema perguntar "tem novidade?" a cada minuto, o outro sistema avisa assim que a novidade acontece.

Na prática: integração por API costuma ser "puxar de tempos em tempos"; webhook é "receber na hora". Para lead novo ou pagamento confirmado, webhook é muito melhor - e mais barato, porque elimina milhares de consultas inúteis.

Token / chave de API

A credencial que identifica quem está chamando a API. Equivale a uma senha de sistema: não se compartilha por e-mail, não se coloca no código versionado e se troca periodicamente.

Rate limit

O limite de chamadas permitidas por período. Ultrapassou, o outro lado começa a recusar. É por isso que sincronização de catálogo grande precisa ser planejada, e não disparada de uma vez.

Sincronização

Manter dois sistemas com a mesma informação. Duas perguntas definem o projeto inteiro:

• Qual é a fonte da verdade? Se o dado divergir, quem manda? Sem essa definição, a integração vira ping-pong de sobrescrita.
• É de mão única ou dupla? Do CRM para o site é bem mais simples do que dos dois lados.

Middleware

Uma camada no meio que traduz e organiza. Quando dois sistemas falam "línguas" diferentes, essa camada converte formato, trata erro e guarda o registro do que passou. Todo projeto de integração séria tem algo assim.

Sandbox e produção

Sandbox é o ambiente de teste, com dados falsos; produção é o real. Toda integração deveria ser construída e testada em sandbox antes de encostar em dado de cliente.

As perguntas que valem em qualquer reunião de integração

1. Existe documentação da API? Posso ver antes de fechar o escopo?
2. Tem ambiente de teste?
3. Qual o limite de chamadas?
4. O que acontece se o outro sistema ficar fora do ar?
5. Como vamos saber que a sincronização falhou?

A quinta é a mais importante e a mais esquecida. Integração sem monitoramento falha em silêncio - e você descobre pelo cliente.

Fazemos integrações entre sites, CRMs, ERPs e gateways. Veja como trabalhamos.