Integração de sistemas via API: guia prático para quem não é programador
ELPor Enzo Lima, Fundador e engenheiro de software, TB7 Business
Neste artigo (16 seções)
O que é uma API, sem jargão
Uma API é a "tomada" que um sistema oferece para outros se conectarem. O ERP, o marketplace e o gateway de pagamento publicam as suas regras: o que dá para pedir, como se identificar e em que formato receber a resposta. Quem integra escreve o código que usa essa tomada.
API, webhook e arquivo: as três formas de conectar
| Forma | Como funciona | Quando usar |
|---|---|---|
| API (consulta) | Seu sistema pergunta ao outro de tempos em tempos | Quando você precisa buscar dados sob demanda |
| Webhook | O outro sistema avisa o seu quando algo acontece | Quando você precisa reagir na hora (novo pedido, pagamento) |
| Arquivo (CSV/planilha) | Exportar e importar um arquivo | Quando não há API ou o volume é pequeno |
O webhook costuma ser mais rápido e econômico que ficar perguntando. Mas, como ele pode falhar ou chegar repetido, é comum combinar os dois: o webhook avisa e uma rotina periódica confere se nada ficou para trás.
O que uma boa integração precisa ter
- Autenticação segura. Chaves e tokens guardados com cuidado, nunca expostos no código ou em arquivos públicos.
- Idempotência. Receber o mesmo evento duas vezes não pode criar dois pedidos.
- Filas e novas tentativas. Se o outro sistema estiver fora do ar, a tarefa espera e tenta de novo.
- Limite de requisições. APIs limitam quantas chamadas por segundo aceitam; é preciso respeitar.
- Registro e alertas. Dá para ver o que foi enviado e ser avisado quando falha.
Exemplos reais de integração
- Loja e ERP: pedido vendido entra no ERP, o estoque baixa e a nota fiscal é gerada.
- ERP e marketplaces: preço e estoque atualizados em todos os canais.
- Gateway de pagamento e financeiro: pagamentos conciliados sem digitação.
- Fornecedor e catálogo: produtos, fotos e dados fiscais importados automaticamente.
Em projetos como o Dropp e o Turbcom, a integração com o ERP é parte central do produto.
As falhas mais comuns (e como evitar)
| Falha | Causa típica | Prevenção |
|---|---|---|
| Pedido duplicado | Evento recebido duas vezes | Chave única por evento (idempotência) |
| Estoque errado | Atualização perdida ou fora de ordem | Conferência periódica e reprocessamento |
| Integração "parou" | Token expirado ou limite excedido | Renovação automática e alertas |
| Dados diferentes entre sistemas | Dois cadastros editados em paralelo | Definir qual sistema é a fonte da verdade |
Perguntas para fazer antes de integrar
- O sistema tem API pública e documentada? Que tipo de permissão ela exige?
- Há limite de chamadas? Qual o plano necessário?
- Quem é a fonte da verdade de cada dado (produto, preço, estoque, cliente)?
- O que acontece quando a integração falha por horas?
Integrar, automatizar ou substituir?
Se os sistemas já funcionam bem separados, a integração costuma ser o caminho mais barato. Combine com automação de processos para eliminar também as tarefas manuais que sobram.
Como a TB7 trabalha
Mapeamos os sistemas, definimos a fonte da verdade, desenvolvemos a integração com filas, reprocessamento e logs, e acompanhamos o início da operação. Veja Integrações de Sistemas ou peça um orçamento.
Como uma integração é construída, etapa por etapa
- Levantamento: quais dados vão de onde para onde, em qual direção e com que frequência.
- Fonte da verdade: para cada dado, qual sistema manda. Sem isso, os dois se sobrescrevem.
- Credenciais e permissões: criar acesso com o mínimo necessário e guardar com segurança.
- Mapeamento de campos: o que se chama "SKU" em um sistema pode ser "código" em outro. Mapeie e trate diferenças de formato.
- Construção com testes: incluir casos de erro, dados incompletos e repetição de eventos.
- Homologação: testar com dados reais ou ambiente de testes do outro sistema.
- Entrada em produção com monitoramento: acompanhar os primeiros dias de perto.
Autenticação: como os sistemas se identificam
Dois modelos aparecem com frequência:
| Modelo | Como funciona | Cuidado |
|---|---|---|
| Chave de API | Um código secreto enviado em cada chamada | Nunca exponha em código público; troque se vazar |
| OAuth | O usuário autoriza o acesso e o sistema recebe um token que expira e é renovado | Planejar a renovação automática do token |
Em integrações com ERPs e marketplaces, o OAuth é comum. Tokens que expiram são uma causa clássica de "a integração parou do nada": o sistema precisa renovar sozinho e avisar quando isso falha.
Limites de uso: o que é rate limit
Quase toda API limita quantas chamadas aceita por segundo ou por minuto. Ultrapassar o limite gera erro e, em alguns casos, bloqueio temporário. Uma integração madura:
- Controla o ritmo das chamadas.
- Agrupa pedidos quando a API permite (lotes).
- Usa filas para absorver picos.
- Tenta de novo com espera crescente quando recebe erro de limite.
Dados em tempo real ou em lotes?
| Estratégia | Vantagem | Desvantagem |
|---|---|---|
| Tempo real (webhook) | Atualização imediata | Exige tratar falhas e repetições |
| Lotes periódicos | Simples e previsível | Dados podem ficar defasados por minutos ou horas |
| Combinação | Imediato com conferência periódica | Um pouco mais de construção |
Para estoque e preço em vários canais, a combinação costuma ser a mais segura: o evento atualiza na hora e uma varredura periódica corrige qualquer divergência.
Testando uma integração antes de confiar nela
Não basta "funcionou uma vez". Teste:
- Dados incompletos ou fora do padrão (campos vazios, caracteres especiais).
- O mesmo evento duas vezes.
- O outro sistema fora do ar por alguns minutos.
- Volume alto de eventos ao mesmo tempo.
- Expiração do token.
Custos e dependências
Integrar traz custos além do desenvolvimento: planos de API pagos, limites por plano e dependência da política do outro sistema, que pode mudar regras. Por isso as integrações devem ser desacopladas do restante do sistema, para trocar ou ajustar uma sem mexer em tudo. É assim que organizamos os módulos de integração dos nossos produtos, como o Dropp.
Integração ou sistema único?
Às vezes, a melhor resposta para sistemas que não conversam é unificar. Mas, na maioria dos casos, integrar o que já funciona é mais barato e menos arriscado do que substituir. Pese essa decisão junto com SaaS ou software sob medida e ERP personalizado.
Fontes e referências
Perguntas frequentes
O que é uma API em palavras simples?
É a forma que um sistema oferece para outros se conectarem a ele, com regras claras do que pode ser pedido e em qual formato. Integrar é usar essa conexão de maneira automática.
Qual a diferença entre API e webhook?
Na API, o seu sistema pergunta ao outro. No webhook, o outro avisa o seu quando algo acontece. O webhook costuma ser mais rápido, e muitas integrações combinam os dois.
E se o sistema que uso não tem API?
Avalia-se alternativas, como exportação de arquivos, webhooks ou automações. Quando algo não é viável, a equipe diz com clareza.
O que acontece se a integração falhar?
Uma boa integração usa filas, novas tentativas e registro de erros, reprocessando o que ficou pendente sem duplicar dados.
A TB7 integra ERP, marketplaces e gateways?
Sim. Desenvolvemos integrações com ERPs, marketplaces, gateways de pagamento e plataformas externas, com monitoramento e tratamento de falhas.
Próximo passo
Quer aplicar isso na sua empresa?
Conte o seu desafio. Você recebe um protocolo na hora e a nossa equipe volta com um caminho, sem compromisso.
Enzo Lima
Fundador e engenheiro de software, TB7 Business. Projeta e desenvolve sistemas, plataformas SaaS, integrações e soluções com inteligência artificial na TB7 Business. Atualizado em 19 de outubro de 2026.
