Integração de sistemas: o que é uma API e quando vale integrar

Publicado em 26 de outubro de 2026 · Equipe Spartan TI

Você provavelmente já viveu esta cena: o pedido chega pelo site, alguém imprime, digita no sistema de gestão, confere o estoque na planilha, abre o emissor de nota e digita tudo de novo. Quatro telas, três digitações do mesmo dado e uma chance enorme de um deles sair errado. Quando você pergunta se não dá para "ligar os sistemas", a resposta do fornecedor vem com uma palavra que ninguém explica: API.

Este artigo explica o que é uma API em português claro, mostra as formas de ligar dois sistemas e por que uma delas é perigosa, lista o que você precisa perguntar antes de assinar qualquer coisa e, no fim, ensina a fazer a conta: quantas horas por mês essa integração devolve para a sua equipe. Porque integrar não é sempre a resposta certa — às vezes é só caro.

O que é uma API, sem jargão

API é a sigla de Application Programming Interface, ou interface de programação. Esquece a tradução. Pense num restaurante.

Você senta à mesa e não entra na cozinha. Você fala com o garçom, usando o menu: um cardápio que diz exatamente o que pode ser pedido e como. O garçom leva o pedido, a cozinha prepara e ele volta com o prato. Você não sabe quantas panelas existem lá dentro, nem precisa saber. Só precisa do cardápio e de alguém para levar e trazer.

A API é esse conjunto: o cardápio mais o garçom. É a porta oficial pela qual um sistema pede algo a outro sistema e recebe a resposta. O cardápio é a documentação: a lista do que dá para pedir ("me dê o estoque do produto X", "crie um pedido com estes itens", "me diga se esta nota foi autorizada"). A cozinha é o banco de dados e a lógica do outro sistema, que continua trancada — e é exatamente isso que torna a API segura.

Dois detalhes que aparecem na prática. Primeiro: toda API decente exige identificação. Você recebe uma chave ou um token — uma senha longa que o seu sistema manda em cada pedido para provar quem é. Segundo: a conversa acontece num formato padronizado, quase sempre JSON, que é só texto organizado em pares de nome e valor. Você não precisa ler JSON, mas vale saber que é texto, não um arquivo misterioso.

Três exemplos que você já usa sem saber

O site que consulta o CEP

Você digita o CEP no formulário de entrega e, num segundo, rua, bairro e cidade aparecem preenchidos. O site não tem a lista de todos os CEPs do Brasil guardada. Ele perguntou a um serviço de consulta de endereços, por API, e recebeu a resposta. Ganhos: o cliente digita menos, erra menos e abandona menos o carrinho. É o tipo de integração pequena que paga sozinha — veja outras no artigo sobre formulário de contato que funciona.

A loja que puxa o estoque do ERP

ERP é o sistema de gestão da empresa: cadastro de produtos, compras, estoque, financeiro. Numa loja virtual integrada, o site não mantém um estoque próprio na mão de alguém. Ele pergunta ao ERP, a cada poucos minutos, quantas unidades existem — ou o ERP avisa o site quando o número muda. Resultado: você não vende o que não tem. Essa é, de longe, a integração que mais evita briga com cliente em quem monta uma loja virtual do zero.

O sistema que emite a nota fiscal

Emitir nota é conversar com a Secretaria da Fazenda do seu estado por meio de serviços oficiais. Nenhuma empresa pequena fala direto com a Sefaz: ela usa um intermediário, que oferece uma API simples do lado de quem emite e cuida da parte complicada — certificado digital, formato do arquivo, retentativa quando o serviço do governo cai. Você manda os dados do pedido, recebe o número da nota e o PDF.

As quatro formas de ligar dois sistemas

Integração não é uma coisa só. Existem caminhos diferentes, com custos e riscos bem diferentes. Entender qual está sendo proposto é metade da decisão.

1. API (você pergunta)

O seu sistema chama o outro quando precisa: "qual o estoque agora?". Funciona para consulta e para escrita. É o caminho padrão, o mais documentado e o mais fácil de depurar, porque cada chamada deixa rastro. A desvantagem é que você só sabe o que mudou se perguntar — e perguntar a toda hora consome o limite de chamadas.

2. Webhook (o outro te avisa)

É o contrário. Você entrega ao outro sistema um endereço seu e ele chama você quando algo acontece: "pagamento aprovado", "pedido cancelado", "nota autorizada". Economiza chamadas e é quase instantâneo. Em troca, exige disciplina: o seu lado tem que estar de pé para receber, precisa responder rápido, tratar aviso repetido (o mesmo evento pode chegar duas vezes) e validar que quem chamou é realmente o parceiro, não um curioso. Um webhook sem validação de origem é um buraco de segurança — tema do artigo sobre o que exigir no contrato de criação de site, onde segurança precisa estar escrita.

3. Importação de arquivo

O sistema A gera um arquivo (CSV, XML, planilha) e o sistema B lê, em horário marcado. É a opção mais simples e a mais antiga, e continua perfeitamente válida em dois casos: quando o volume é grande e não urgente (lista de preços do dia, folha de pagamento) e quando um dos lados simplesmente não tem API. O problema é a latência: se o arquivo roda às 2h da manhã, o estoque do site passa o dia desatualizado. E arquivo falha em silêncio — ninguém percebe que não rodou até o cliente reclamar.

4. Banco a banco (o caminho arriscado)

Aqui alguém propõe acessar diretamente o banco de dados do outro sistema: ler as tabelas, às vezes até escrever nelas. É tentador porque parece rápido e barato, e dispensa esperar a boa vontade do fornecedor. Não faça, e vou dizer exatamente por quê.

• Você está passando por cima das regras. O sistema não é só a tabela: é a tabela mais a lógica que valida, calcula imposto, atualiza três outras tabelas e grava o histórico. Escrever direto no banco pula tudo isso e gera dado inconsistente que ninguém entende seis meses depois.
• Quebra na próxima atualização. O fornecedor pode renomear uma coluna à vontade, porque o contrato dele com você é a API, não o banco. Numa terça-feira qualquer, a integração para.
• Costuma violar o contrato e a garantia. Muitos fornecedores suspendem o suporte ao identificar acesso externo direto à base.
• Trava e corrompe. Consulta pesada feita de fora derruba o desempenho de quem está trabalhando, e escrita concorrente é receita de dado corrompido.

A única versão aceitável desse caminho é somente leitura, contra uma réplica ou um banco de relatórios, com o aval por escrito do fornecedor. Fora disso, é dívida técnica com juros altos.

O que perguntar ao fornecedor do sistema

Antes de contratar o desenvolvimento, faça estas perguntas por escrito a quem fornece o sistema que você quer integrar. Guarde as respostas: elas definem o orçamento e evitam surpresa no meio do projeto.

• Existe API? E ela cobre o que eu preciso, ou só parte? Muita API lê bem e escreve mal.
• A documentação é pública? Peça o link. Documentação que só existe em PDF enviado por e-mail, desatualizada, é mau sinal.
• Tem ambiente de teste? Chamado homologação ou sandbox. Integrar testando na base real é como trocar pneu com o carro andando.
• Qual o limite de chamadas? Por minuto, por hora, por dia. E o que acontece quando estoura: a chamada falha, entra na fila ou vira cobrança?
• Custa quanto? Existe módulo de integração à parte, licença por conexão, cobrança por volume?
• Como funciona a autenticação? Chave fixa ou token que expira? Quem gera e onde fica guardado?
• Como são anunciadas as mudanças de versão? Com quantos dias de aviso? Existe compromisso de manter a versão antiga funcionando por um período?
• Quem é o contato técnico? Nome e canal. Projeto de integração trava por falta de interlocutor com mais frequência do que por dificuldade técnica.

Se o fornecedor não responde essas oito perguntas, o problema do projeto não é técnico. Vale considerar se o sistema certo para a sua empresa não é outro — discussão que está no artigo sobre sistema sob medida ou pronto.

Sinais de que vale integrar

Integração não se faz porque é moderno. Se faz porque existe dor medível. Estes são os sinais honestos:

• O mesmo dado é digitado duas vezes. Clássico e definitivo. Toda digitação repetida é tempo pago duas vezes e uma oportunidade de erro.
• Divergência de estoque. Se o número do site e o do depósito nunca batem, você está escolhendo entre vender o que não tem e deixar de vender o que tem.
• Alguém monta relatório na mão. Se a segunda-feira de alguém começa copiando dados de dois sistemas para uma planilha, a integração já tem um dono de interesse.
• O atraso custa dinheiro. Pagamento que só aparece no sistema no dia seguinte atrasa expedição e gera reclamação.
• Erro de digitação com consequência fiscal. Nota emitida com NCM ou valor errado dá retrabalho e risco.

E os sinais de que não vale agora: volume baixo (dez pedidos por semana resolvidos em vinte minutos não justificam projeto), processo que ainda vai mudar (integrar processo instável é refazer duas vezes) e, principalmente, processo quebrado. Automatizar bagunça só faz a bagunça acontecer mais rápido.

Os riscos que ninguém conta no começo

Limite de requisições

Quase toda API tem teto. Quando a sua integração passa do limite, ela começa a receber recusa — e, se o código não estiver preparado, para de funcionar sem avisar. Integração bem feita respeita o teto, espera e tenta de novo, com intervalo crescente.

Mudança de versão

O fornecedor lança a versão 2 da API e, um ano depois, desliga a versão 1. Isso é normal e previsível. O erro é não ter ninguém responsável por acompanhar o aviso. Integração não é obra entregue: é algo que precisa de manutenção contínua, igual ao site.

Dado duplicado

O risco mais chato de todos. Um webhook chega duas vezes, a rede cai no meio de uma chamada e o seu sistema repete, e de repente existem dois pedidos iguais ou dois lançamentos financeiros. A proteção se chama idempotência: cada operação carrega um identificador único e, se o mesmo identificador chegar de novo, o sistema reconhece e ignora. Pergunte se a integração que estão te vendendo tem isso.

Quem é a fonte da verdade

Se o estoque pode ser alterado no site e no ERP, qual vale? Essa pergunta precisa ter uma resposta única, escrita, antes da primeira linha de código. Sem ela, os dois sistemas ficam se corrigindo em loop.

Como medir o retorno em horas economizadas

Esta é a parte que transforma a conversa técnica em decisão de negócio. A conta é simples e você consegue fazer hoje, com cronômetro e papel.

Primeiro, meça. Escolha a tarefa (lançar pedido, conferir estoque, emitir nota) e cronometre três ou quatro repetições reais. Anote a média e a frequência por mês. Depois aplique:

No exemplo, a integração devolve 32 horas por mês. Multiplique pelo custo real da hora de quem faz esse trabalho (salário mais encargos, dividido pelas horas úteis) e você tem a economia mensal. Compare com o custo do projeto mais a manutenção e você tem o prazo de retorno. Projeto de integração com retorno acima de doze meses merece uma segunda olhada; abaixo de seis, costuma ser decisão fácil.

Não esqueça os ganhos que não entram na planilha de horas: venda que não se perde por estoque errado, cliente que não desiste, e a possibilidade de a sua equipe passar a atender gente em vez de digitar. Esse último argumento vale tanto quanto o primeiro — é o mesmo raciocínio de um site que converte em clientes, onde cada atrito removido aparece no faturamento.

Por onde começar na prática

Escolha um processo. Um. Escreva em cinco linhas o que entra, o que sai e quem é a fonte da verdade. Peça ao fornecedor as respostas das oito perguntas. Teste em homologação, faça a carga inicial conferindo totais, e rode duas semanas com a conferência manual em paralelo — é chato, mas é o que pega o erro de mapeamento antes que ele contamine o histórico. Por último, e sem negociar essa parte: deixe log de tudo que falhou e um alerta que chegue a uma pessoa de verdade.

Se quiser ver exemplos de sistemas e integrações já no ar, dê uma olhada no portfólio. Para entender como a gente trabalha com sistemas sob medida e APIs, o guia tem o caminho completo, e dúvidas pontuais costumam estar nas perguntas frequentes. A Spartan TI é do Espírito Santo e atende todo o Brasil; se você quiser discutir um caso concreto, mande o cenário pelo contato que a gente responde se vale integrar ou não — inclusive quando a resposta é "ainda não".

Uma última ideia para levar: integração boa é invisível. Ninguém elogia a integração que funciona, porque ela se manifesta como ausência — ausência de digitação dupla, ausência de divergência, ausência da planilha de segunda-feira. Se depois de três meses sua equipe esqueceu que existe uma integração ali, deu certo. Antes de partir para projetos grandes, veja também as tarefas que dão para automatizar neste mês e, se o seu caso envolve dado de cliente, confira o mínimo de LGPD que o seu site precisa ter — integração move dado pessoal de um lado para o outro, e isso tem regra.

Perguntas frequentes

Qualquer sistema pode ser integrado?

Na prática, não. Dá para integrar com conforto o sistema que oferece API documentada ou, no mínimo, importação e exportação de arquivo. Sistemas antigos, instalados só no computador da empresa e sem nenhuma dessas portas, só aceitam caminhos frágeis. Nesses casos costuma sair mais barato trocar o sistema do que insistir na integração.

Qual a diferença entre API e webhook?

Na API, o seu sistema pergunta: ele chama o outro quando precisa da informação. No webhook, o outro sistema avisa: ele chama um endereço seu no instante em que algo acontece. Webhook é mais rápido e gasta menos chamadas, mas exige que o seu lado esteja sempre disponível e saiba tratar aviso repetido. A maioria dos projetos usa os dois juntos.

Preciso trocar meu ERP para integrar a loja?

Não necessariamente. Primeiro descubra se o ERP atual tem API e se ela cobre produtos, estoque, pedidos e notas. Se cobrir, a integração é um projeto normal. Se a API existir só para leitura, ou se o módulo de integração custar mais que a economia esperada, aí a troca entra na conta.

Quanto tempo leva uma integração?

Uma integração simples e bem documentada, como consulta de CEP ou envio de lead para um CRM, sai em poucos dias. Ligar loja e ERP com produtos, estoque, pedidos e notas é um projeto de semanas, e boa parte do prazo é mapeamento de campos e teste, não programação. Fornecedor que promete tudo em dois dias provavelmente não leu a documentação ainda.

E se o outro sistema sair do ar?

Isso vai acontecer, então a integração precisa ser feita esperando isso. O comportamento correto é guardar a operação numa fila, tentar de novo com intervalo crescente e registrar a falha num log com alerta. O que não pode é perder o dado em silêncio nem travar o atendimento porque um serviço de terceiro ficou indisponível por dez minutos.

Integração exige manutenção depois de pronta?

Sim, e esse é o ponto mais esquecido. APIs mudam de versão, chaves expiram, limites de chamada são revistos e regras fiscais são atualizadas. Reserve desde o começo quem acompanha os avisos do fornecedor e quem recebe o alerta quando algo falha, do mesmo jeito que se faz com a manutenção do site.