Bastidores de uma integração via API: como uma empresa parou de vender o que não tinha

São quatro da tarde de uma sexta-feira de movimento. O cliente escolhe o produto, leva até o caixa, o vendedor confere no sistema — tem, aparecem três unidades disponíveis. Fecha a venda, embala, agradece. Vinte minutos depois, alguém do estoque vai separar o pedido para despacho e não encontra nada. A última peça tinha saído há dois dias. Ninguém tinha atualizado a planilha, ou o sistema, ou o que quer que estivesse fazendo as vezes de controle de estoque naquele momento.

Essa cena, com pequenas variações, se repetia várias vezes por semana numa empresa que nos procurou há alguns meses. Não era um caso isolado, um erro de um funcionário distraído num dia ruim. Era rotina. E foi exatamente isso que chamou nossa atenção quando começamos a olhar o problema de perto: o que parecia falha humana era, na verdade, uma consequência quase inevitável da forma como os sistemas da empresa estavam montados.

O sintoma que todo mundo vê primeiro

Quando uma empresa vende um produto que não tem, o primeiro impulso é procurar culpado. Foi o vendedor que não conferiu o estoque físico. Foi quem fez a última contagem e errou. Foi o cliente que demorou pra avisar que ia devolver. A gente ouve essas explicações com frequência, e entendemos por que fazem sentido no calor do momento — só que raramente resolvem o problema de verdade.

No caso dessa empresa, o diagnóstico mostrou algo bem mais simples de explicar e bem mais chato de resolver: o PDV e o controle de estoque viviam em universos separados. O PDV registrava a venda na hora. O estoque só era atualizado depois, manualmente, por alguém que exportava um relatório, abria uma planilha, cruzava número e lançava tudo num sistema à parte. Esse "depois" podia ser horas. Em dias de pico, virava o dia seguinte.

Todo esse intervalo entre a venda acontecer e o estoque saber que ela aconteceu é o que chamamos de zona cega. E é exatamente nessa zona cega que mora o overselling — vender o que não existe fisicamente na prateleira.

Por que "problema de vendas" é o diagnóstico errado

Aqui vai uma opinião que defendemos com convicção: quando uma empresa vende o que não tem, quase nunca é um problema de vendas. É um problema de arquitetura de sistemas disfarçado de problema de vendas. O time comercial está fazendo exatamente o que foi treinado pra fazer — confiar no número que aparece na tela. O erro não é confiar nesse número. O erro é a empresa ter, sem perceber, dois números diferentes competindo pela verdade: o que o PDV acha que existe e o que existe de fato no depósito.

Isso importa porque muda completamente onde você aponta o esforço de correção. Treinar vendedor pra "conferir melhor" não resolve nada quando o sistema que ele consulta está desatualizado por natureza. Cobrar mais atenção do time de estoque também não resolve, porque o gargalo não é atenção — é a ausência de um caminho automático entre um sistema e outro. Enquanto a atualização depender de alguém lembrar de fazer, vai falhar. Não é questão de se, é questão de quando.

A gente já viu gestor demitir vendedor bom por causa disso. Demitir a pessoa errada não conserta o sistema, só troca quem vai cometer o mesmo erro daqui a algumas semanas. É desconfortável falar isso pra quem está dentro do problema, mas alguém precisa.

O que fomos checar antes de propor qualquer coisa

Antes de falar em API, webhook ou qualquer coisa técnica, o trabalho começou em outro lugar: entender o fluxo real, não o fluxo que o dono da empresa achava que existia. Isso significa sentar com quem opera o caixa, acompanhar uma rotina de reposição, olhar como as planilhas eram preenchidas e, principalmente, descobrir onde ficavam os pontos de reentrada manual de dado — porque é ali, invariavelmente, que o erro nasce.

Encontramos três coisas que se repetem em praticamente todo negócio com esse tipo de problema, e vale nomear porque ajuda quem está lendo a reconhecer o próprio cenário:

• Sistemas que não conversam nativamente entre si e dependem de exportação e importação manual de planilha;
• Nenhum gatilho automático para avisar quando um item crítico está perto de zerar;
• Uma cultura interna que trata a divergência de estoque como "normal", quase como custo do negócio.

Esse último ponto talvez seja o mais delicado. Quando a divergência vira rotina, ninguém mais mede o impacto dela. A empresa para de perguntar quanto isso custa em vendas perdidas, em cliente insatisfeito, em hora de trabalho gasta corrigindo lançamento errado. O problema fica invisível justamente por ser constante.

Por que API e não outra abordagem

Existem várias formas de tentar resolver esse tipo de desconexão. Algumas empresas tentam contornar com planilha compartilhada na nuvem, achando que sincronizar arquivo resolve o que na real é um problema de sistemas que não falam a mesma língua. Outras compram um ERP gigante prometendo resolver tudo de uma vez, o que costuma custar caro, demorar meses pra implantar e, no fim, ainda deixar pontas soltas porque nenhum ERP genérico entende as particularidades de cada operação sem alguma camada de customização.

No caso dessa empresa, optamos por construir uma camada de integração via API que conecta o PDV diretamente ao banco de dados do estoque. Na prática, isso significa que, no instante em que uma venda é fechada no caixa, uma chamada REST dispara e atualiza o estoque em tempo real, sem intermediário humano, sem planilha, sem espera. O PDV não precisa "saber" nada sobre estoque — ele só precisa avisar que algo aconteceu, e a camada de integração cuida do resto.

Escolhemos o modelo baseado em webhook por um motivo bem prático: ele reage a eventos, não a horários. Uma integração que roda de hora em hora, ou uma vez por dia, ainda deixa uma janela de risco — e é justamente nessa janela que o cliente compra o item que já não existe mais. Com webhook, o evento "venda concluída" já carrega consigo a atualização do estoque. Não tem intervalo pra furo acontecer, porque não tem espera.

Junto com essa camada, montamos fluxos de automação em n8n pra cobrir a outra ponta do problema: reposição. Sempre que um item crítico cruza um limite mínimo definido junto com a operação, o fluxo dispara notificação automática pra quem precisa agir — comprador, gestor de estoque, fornecedor, dependendo do caso. Isso tira da cabeça de alguém a responsabilidade de lembrar de olhar um relatório todo santo dia. O sistema lembra por ela.

As armadilhas que ninguém conta antes de começar

Integração de PDV com estoque parece simples no papel e raramente é. Um dos erros mais comuns que vemos é tratar a integração como projeto de TI isolado, sem envolver quem realmente usa o sistema no dia a dia. Dá certo tecnicamente e falha na prática, porque ninguém perguntou como o vendedor lida com devolução, com venda cancelada, com produto reservado que não foi retirado.

Outro ponto que costuma pegar quem tenta resolver isso sozinho é subestimar o volume de exceção. Venda normal é fácil de sincronizar. O difícil é o estorno, a troca, o item composto por vários componentes de estoque, a promoção que baixa mais de uma unidade por venda. Se a integração não prevê esses casos desde o desenho inicial, ela quebra silenciosamente — e "quebra silenciosa" é pior do que erro visível, porque ninguém percebe até o próximo furo aparecer.

E tem o erro clássico de achar que integração é projeto com data de entrega e ponto final. Não é. Sistema de venda muda, catálogo de produto muda, forma de precificar muda. A integração precisa ser pensada como algo vivo, com manutenção prevista, não como instalação que você faz uma vez e esquece.

Por isso a implantação, nesse caso, não foi um botão que se aperta numa sexta à noite e pronto, segunda todo mundo acorda com o problema resolvido. Rodamos em paralelo por um período — PDV e estoque sincronizando via API, mas com a planilha antiga ainda ativa como rede de segurança — justamente pra pegar esses casos de exceção antes que eles virassem incêndio em produção. Um estorno que não batia, um item composto que descontava errado do estoque principal, coisas assim. É trabalho de formiguinha, sem glamour nenhum, mas é o que separa uma integração que aguenta o dia a dia real de uma que só funciona na demonstração.

O que mudou, na prática

Depois da integração no ar, o resultado mais imediato foi a sincronização em tempo real entre venda e estoque — 100% dos casos, sem exceção, porque o próprio desenho técnico não deixa margem pra atraso. O erro de digitação, que antes era praticamente garantido em algum ponto da reentrada manual de dado, simplesmente deixou de existir, porque deixou de existir a reentrada manual.

Do lado operacional, o despacho ficou 30% mais ágil. Faz sentido quando você para pra pensar: sem precisar conferir estoque físico contra sistema antes de liberar pedido, a equipe corta uma etapa inteira do processo. E o tempo que antes ia pra reconciliação manual de planilha — algo em torno de 40 horas por mês, segundo o próprio time da empresa — voltou pra operação, pra atendimento, pra qualquer coisa que gere valor de verdade em vez de corrigir divergência que nunca devia ter existido.

Por que isso é mais comum do que parece

A gente costuma ouvir de dono de negócio que esse tipo de problema é "coisa de empresa pequena, que ainda não profissionalizou processo". Discordamos. Vemos operação de porte considerável carregando exatamente essa falha, só que camuflada atrás de planilha bonita e relatório mensal. O tamanho da empresa não protege contra sistema desconectado — só atrasa o momento em que o problema fica visível demais pra ignorar.

O que muda com o tempo é o custo de manter o remendo. No começo, uma pessoa checando planilha resolve. Depois, precisa de duas. Depois, vira um cargo inteiro dedicado a "bater" um sistema contra o outro, o que é, sem meias palavras, pagar salário pra alguém fazer o trabalho que uma integração bem desenhada faz sozinha, em segundos, sem erro.

Se tem uma coisa que aprendemos revisando esse tipo de operação repetidamente é que o overselling quase nunca aparece sozinho. Ele vem acompanhado de outros sintomas do mesmo problema raiz — atraso de reposição, divergência de inventário em auditoria, cliente insatisfeito que compra em outro lugar da próxima vez. Resolver só a ponta visível, sem mexer na causa, é como trocar lâmpada queimada sem checar a fiação: vai queimar de novo.

Se esse tipo de cena soa familiar — cliente feliz na hora da compra, time de estoque surpreso vinte minutos depois — talvez valha a pena entender onde exatamente está a desconexão na sua operação antes que ela custe mais um cliente. A gente costuma começar esse tipo de conversa com um diagnóstico gratuito, sem compromisso, só pra mapear onde estão os furos reais entre venda e estoque. Às vezes o problema é bem menor do que parece. Às vezes é maior. De um jeito ou de outro, dá pra saber com clareza antes de decidir o que fazer.