Índice do artigofaltam 6 min de leitura
A API existe, o fornecedor confirmou que existe, e mesmo assim o dado não aparece na tela. Esse é o ponto exato em que a maioria dos projetos de integração descobre que o problema nunca foi tecnológico.
A cena se repete em empresa de médio porte. O ERP tem o cadastro do cliente. O CRM tem a negociação. O e-commerce tem o pedido. O aplicativo tem o consumidor final. Os quatro funcionam bem, cada um no seu canto, e ninguém consegue ver a operação inteira em lugar nenhum.
Este artigo é sobre o que precisa ser decidido antes de alguém escrever a primeira linha de código de integração. Não é um manual técnico: é o conjunto de perguntas que separa um projeto de integração que entra em produção de um que vira discussão de escopo no terceiro mês.
Resumo do artigo
- Existir uma API não significa que ela entrega o campo que você precisa. Nos projetos que executamos, campo ausente trava mais integrações do que falha de conexão.
- O que define prazo não é a dificuldade técnica: é quem tem permissão para alterar cada lado da conexão. Quando só o fornecedor do ERP pode publicar um campo, o cronograma é dele.
- Existem cinco modos de ligar dois sistemas, e a escolha errada aparece meses depois, na conta de manutenção.
- O documento que evita a maior parte das disputas de escopo é o contrato de dados, e ele precisa existir antes do orçamento, não depois.
A API existe e o dado continua não chegando
O erro de leitura mais caro desse assunto é achar que integração é conectar um cabo. A conversa costuma terminar em "o sistema tem API, então dá para integrar", e essa frase esconde três perguntas diferentes que precisam de três respostas diferentes.
Ter API significa que existe uma porta. Não diz nada sobre o que passa por ela. Num projeto de aplicativo para uma rede de pneus, o ERP tinha a API publicada, o time tinha as credenciais, a conexão respondia, e o app não conseguia localizar clientes por CPF. O CPF estava cadastrado no ERP. Ele simplesmente não vinha na resposta, porque o campo não fazia parte do recurso publicado. Meses depois, o mesmo projeto precisou de DDD e data de nascimento, e quem alterou a API foi o fornecedor do ERP, não a equipe do aplicativo.
Essa é a forma real do problema. Não é falha de conexão, é ausência de campo. E a correção não estava do lado de quem construía o app.
O que trava não é a tecnologia, é quem pode mudar o quê
Toda integração tem dois lados, e quase nunca a mesma pessoa manda nos dois. Essa assimetria é a variável que mais influencia o cronograma e a que menos aparece nas propostas comerciais.
Na prática existem três fronteiras de controle, e vale mapear cada uma antes de prometer data. A primeira é o lado que você controla, normalmente o app, o site ou a plataforma nova, onde qualquer ajuste entra na próxima entrega. A segunda é o lado que um fornecedor controla, o ERP ou o CRM de mercado, onde publicar um campo novo depende de abrir chamado, aguardar fila e às vezes contratar horas. A terceira é o lado que ninguém controla mais, o sistema legado cujo autor saiu da empresa, onde a única fonte confiável é o banco de dados.
A consequência para o negócio é direta: quando as três fronteiras estão mapeadas, o cronograma para de ser uma estimativa técnica e vira uma soma de dependências com nome e responsável. É a diferença entre "quatro semanas" e "quatro semanas depois que a TOTVS publicar o campo, o que depende do chamado aberto em tal data".
O desenho acima é a forma que encontramos com mais frequência: um núcleo que a empresa consegue evoluir na velocidade dela, cercado de sistemas que evoluem na velocidade de terceiros. Reconhecer isso não é pessimismo, é o que permite planejar.
Os cinco modos de ligar dois sistemas
Existem cinco caminhos, e a diferença entre eles não aparece na entrega. Aparece na manutenção, seis meses depois, quando alguém precisa mudar alguma coisa.
| Modo | Quando serve | O preço que se paga depois |
|---|---|---|
| Arquivo em lote | Carga grande e periódica: catálogo, folha, fechamento contábil | Atraso estrutural. O dado é sempre de ontem, e ninguém percebe até um cliente reclamar |
| API do fornecedor | Consulta e escrita pontual, quando o campo necessário já está publicado | Dependência do calendário do fornecedor para qualquer campo novo |
| Leitura direta no banco | Sistema legado sem API e sem quem o mantenha | Quebra silenciosa a cada atualização de versão, e normalmente perda de suporte |
| Evento e webhook | Reação imediata: pedido criado, pagamento aprovado, status alterado | Exige tratar reenvio, ordem e duplicidade. Sem isso, o dado diverge devagar |
| Plataforma de integração | Muitas conexões simples entre sistemas de mercado | Custo por volume e limite de controle quando a regra fica complexa |
A coluna do meio é a que o time comercial lê. A da direita é a que decide se o projeto vai dar orgulho ou vergonha no ano seguinte. Na maioria dos casos reais a resposta certa é uma combinação: lote para o volume, API para a consulta, evento para o que precisa ser imediato.
Tempo real custa caro e quase nunca é necessário inteiro
A decisão que mais infla orçamento sem melhorar operação é tratar toda a integração como tempo real. Ela raramente precisa ser.
Vale separar o que o usuário está olhando na tela do que a empresa concilia depois. Saldo, status de pedido e disponibilidade de horário precisam ser imediatos, porque o cliente está esperando a resposta. Catálogo de produto, tabela de preço e fechamento contábil funcionam perfeitamente com uma carga noturna, e ninguém do outro lado nota diferença.
Há ainda um caso intermediário que costuma ser esquecido: o mesmo fornecedor pode oferecer as duas coisas. Numa integração de consulta de débitos veiculares, a mesma empresa expunha uma rota síncrona e uma rota assíncrona, com semânticas diferentes. Escolher a errada não gera erro, gera uma experiência ruim que só aparece com o app já em produção e volume real.
O contrato de dados evita a maior parte das disputas
Antes de orçamento, antes de cronograma e antes de escolher tecnologia, existe um documento curto que define se o projeto vai correr bem: o contrato de dados.
Ele responde, por escrito, quais campos trafegam, em que formato, com que frequência, quem é a fonte da verdade de cada campo e o que o sistema deve fazer quando o dado não existe do outro lado. Parece burocracia e é a peça que impede a conversa mais desagradável de todas, aquela em que uma parte diz que a integração estava no escopo e a outra diz que não.
Vale registrar que esse risco é real e comercial, não hipotético. Em um projeto de varejo com crediário, a linha "integração com o ERP" constava do planejamento formal e do kickoff, e mesmo assim virou divergência, porque o que estava escrito era o nome do sistema, e não quais consultas exatas o app faria nele.
- Cada campo listado com nome, tipo e qual sistema é a fonte da verdade dele
- A frequência definida campo a campo, e não uma frequência única para tudo
- O comportamento esperado quando o dado não existe, está vazio ou vem em formato antigo
- O nome do responsável, de cada lado, por publicar alteração na conexão
- O ambiente de homologação nomeado, com quem libera o acesso a ele
O último item parece detalhe e não é. Ambiente de teste liberado tarde é uma das causas mais comuns de atraso, e às vezes o bloqueio nem é técnico: em uma integração de meio de pagamento, o ambiente de testes recusava as chamadas com erro de permissão até que o estabelecimento fosse habilitado comercialmente do outro lado.
Integrar, substituir ou conviver
Nem todo sistema que incomoda precisa ser integrado, e quase nenhum precisa ser substituído com urgência. Vale posicionar cada caso antes de decidir.
O quadrante superior esquerdo é o mais delicado: sistema do qual a operação depende e que ninguém mais evolui. Ali a resposta não é integrar nem trocar de imediato, é colocar uma camada por fora que isole o resto da empresa dele, e ganhar tempo para decidir a substituição sem pressa. Essa camada é o que protege o investimento nas outras frentes, e é o assunto da arquitetura API-first.
Quem responde quando a integração quebra
Integração é um sistema em produção que depende de outro sistema em produção. Ela vai quebrar, e o momento de definir quem atende é antes, não durante.
Três combinados resolvem quase tudo. O primeiro é ter registro de cada chamada, com o que foi enviado e o que voltou, porque sem isso a conversa entre os dois fornecedores vira palavra contra palavra. O segundo é definir o comportamento do produto quando o outro lado está fora do ar: mostrar dado antigo com aviso costuma ser melhor do que uma tela de erro. O terceiro é combinar o canal e o prazo de acionamento com o fornecedor do outro lado, por escrito.
Vale a honestidade aqui: uma camada de integração bem desenhada reduz o número de falhas, torna cada falha diagnosticável e barateia a correção. Ela não garante que o sistema do outro lado fique no ar.
Por onde começar sem parar a operação
O caminho que funciona é começar por uma fatia vertical estreita, com valor real, e não por um projeto de integração completo.
Escolha uma pergunta que a operação faz todo dia e que hoje exige abrir dois sistemas. Consultar o saldo do cliente. Ver se o pedido faturou. Saber se a peça está em estoque. Integre só o suficiente para responder essa pergunta ponta a ponta, coloque em produção e meça.
O que se aprende no primeiro caminho completo vale mais do que qualquer levantamento de seis semanas, porque ele revela os campos que faltam antes de o orçamento inteiro estar comprometido.
A partir daí, cada nova fatia é mais barata que a anterior, porque a camada de autenticação, o registro de chamadas e o tratamento de erro já existem.
Seu ERP tem o dado e o resto da empresa não enxerga?
Solicite um orçamento e comece por uma fatia com valor real, não por um projeto de integração inteiro.
Perguntas frequentes
Quase nunca. Na maioria dos casos o ERP continua sendo a fonte da verdade e ganha uma camada de integração por fora. Trocar o ERP é um projeto muito maior, com risco muito maior, e resolve um problema diferente.
Resolve a metade fácil. Ter API significa que existe uma porta. Não significa que a porta expõe os campos que você precisa, na frequência que você precisa, com permissão para quem vai consumir. Essas três coisas são o que define prazo e custo.
É o acordo escrito sobre quais campos trafegam entre os dois sistemas, em que formato, com que frequência, quem é a fonte da verdade de cada um e o que acontece quando o dado não existe. É o documento que evita a maior parte das disputas de escopo.
Tecnicamente costuma ser possível e é o caminho mais rápido de curto prazo. O custo aparece depois: você passa a depender do formato interno das tabelas, que muda em atualização de versão sem aviso, e normalmente perde a garantia de suporte do fornecedor.
A pergunta certa não é quem constrói, é quem pode alterar cada lado. Se só o fornecedor do ERP pode publicar um campo novo, o cronograma do projeto depende do calendário dele, e isso precisa estar no contrato antes de a data ser prometida.
Raramente toda ela. Consulta de saldo e de status costuma pedir tempo real; carga de catálogo e fechamento contábil funcionam bem em lote noturno. Tratar tudo como tempo real multiplica o custo de infraestrutura sem ganho de operação.
Fontes e método
Este artigo é baseado em integrações executadas pelo time da X-Apps entre 2023 e 2026, envolvendo TOTVS Protheus, TOTVS Fluig, VTEX, Salesforce, HubSpot, ERPs de varejo e provedores de pagamento e consulta. Os casos citados foram despersonalizados quando a relação entre cliente e sistema não é pública.
As afirmações sobre comportamento de plataformas foram conferidas na documentação oficial de cada fornecedor em 31 de agosto de 2026. Preços, limites de chamada e níveis de serviço não foram apurados e por isso não aparecem no texto.
