Integração TOTVS Protheus e Zoho CRM:como estruturar o projeto

Integrar Protheus ao Zoho CRM é menos uma questão de tecnologia do que de arqueologia operacional: antes de qualquer conector, alguém precisa escavar o que está debaixo da instalação. Campos adicionados ao longo dos anos, pontos de entrada customizados em rotinas críticas, regras fiscais específicas por UF — tudo isso existe e nenhuma documentação padrão do ERP vai cobrir. O projeto que começa sem esse levantamento descobre o problema durante a homologação, quando o prazo já está comprometido.

A Outsmart projeta integrações entre Protheus e Zoho CRM para operações B2B que precisam conectar comercial e ERP sem interromper a operação e sem depender do conhecimento de uma única pessoa que "sabe como o Protheus funciona aqui". O padrão de ondas, fila e log está no guia completo CRM + ERP e em integrações Zoho. O que muda no Protheus são os detalhes — e é exatamente nos detalhes que os projetos de integração costumam perder semanas.

1. Onda por onda — nunca tudo de uma vez

Onda 1: cliente e produto, as entidades mais estáveis e de maior impacto imediato. Onda 2: tabela de preços e pedido, onde o retorno aparece primeiro. Onda 3: financeiro e nota fiscal. Onda 4: indicadores, histórico e análise. Cada onda entra em produção e é estabilizada antes de a seguinte começar — sem exceção.

Projeto de integração que sobe tudo de uma vez costuma passar semanas em correção simultânea: bug em cliente que bloqueia pedido, que bloqueia faturamento, que bloqueia qualquer análise. Onda por onda mantém cada trecho auditável e o impacto de erro limitado ao que ainda não está em produção. O time comercial segue trabalhando, mesmo com parte da integração ainda em desenvolvimento.

O campo que vai em dois sistemas ao mesmo tempo — e dá errado

Para cada campo mapeado: origem, destino e o que acontece em caso de conflito. É a documentação mais trabalhosa do projeto e a única que evita a discussão de "quem sobrescreveu o quê" seis meses depois. Sem ela, cada campo bidirecional é uma armadilha esperando o momento certo para disparar — e o momento certo é sempre aquele em que o cliente mais importante da carteira está no meio de uma negociação.

A customização que invalidou o mapeamento completo

Cena fictícia, mas corriqueira: o levantamento de entidades levou três semanas. O cronograma estava aprovado, o desenvolvimento havia começado. Na segunda semana de codificação, o time de ERP mencionou que o campo de condição de pagamento no SC5 (tabela de pedidos do Protheus) tinha sido substituído por um campo customizado há dois anos — o campo padrão estava vazio em todos os pedidos reais. O código precisou ser reescrito. O prazo derrapou um mês. A pergunta que teria evitado isso: "quais campos customizados existem nessa tabela?" — feita na primeira semana, não na segunda de desenvolvimento.

2. Como o Protheus expõe dados — e onde há armadilhas

O Protheus expõe dados principalmente via REST através do servidor de aplicação (AppServer), usando a camada de serviços do framework TOTVS. Cada instalação customiza quais serviços estão ativos — e "a API do Protheus existe" não significa "todos os endpoints que você precisa estão habilitados nessa instância específica". A primeira verificação do projeto é confirmar quais serviços estão publicados e quais precisam ser ativados ou criados pelo time de ERP.

Instalações TOTVS mais antigas, ou com módulos legados, frequentemente não têm REST ativado e trabalham com WebServices SOAP — uma interface mais antiga, mais verbosa, mas funcionalmente equivalente para integração. Em casos extremos de instalações muito antigas sem nenhuma camada de serviço confiável, a solução é uma view de banco de dados lida pela integração em modo somente leitura. É a opção de menor risco para o ERP e maior para a integridade dos dados, porque elimina qualquer abstração de negócio — a integração lê tabelas cruas.

O ponto de entrada no SC5 — e o gatilho que ninguém documentou

O pedido de venda no Protheus passa pelo SC5 (cabeçalho) e SC6 (itens). Em instalações com customização de ponto de entrada — pequenos scripts em AdvPL que disparam em momentos específicos do ciclo do pedido — a escrita via API pode ativar validações e regras que o time de ERP nem sabe que existem porque foram adicionadas há anos por um consultor que não está mais na empresa. Mapear todos os pontos de entrada ativos no SC5 antes de escrever o primeiro pedido via integração é o trabalho chato que evita a surpresa de go-live.

Tempo real versus lote: a decisão que muda o custo do projeto

Cadastro de cliente e pedido de venda pedem sincronização rápida — o vendedor não pode esperar um lote noturno para saber se o cliente existe ou se o pedido foi confirmado. Tabela de preços, histórico de faturamento e relatório de carteira funcionam perfeitamente em lote diário, com custo de infraestrutura muito menor e risco quase zero de sobrecarga no ERP. A maioria dos projetos começa tentando colocar tudo em tempo real e descobre na prática que o custo não se justifica para 80% das entidades.

3. A janela de manutenção que não pode virar pedido perdido

Integrações ponto a ponto funcionam até a primeira indisponibilidade do ERP. Com camada intermediária de fila persistente — uma estrutura que armazena cada mensagem com seu estado, número de tentativas e conteúdo original — uma janela de manutenção do Protheus deixa de significar pedido perdido ou dado inconsistente. A mensagem aguarda, é reprocessada em ordem e chega com rastreabilidade para qualquer investigação posterior.

Fila persistente não é complexidade desnecessária. É o que diferencia uma integração que o time comercial confia de uma que gera um grupo de WhatsApp para "confirmar se o pedido chegou no ERP". Em operações com mais de cinquenta pedidos por dia, a ausência de fila transforma qualquer janela de instabilidade em trabalho manual de reconciliação.

4. O trecho que paga o projeto antes de tudo

Eliminar a redigitação entre proposta aprovada e pedido no ERP reduz erro de digitação, encurta o ciclo de faturamento e libera horas de retaguarda para trabalho que não é transferência de dado de uma tela para outra. Em operações B2B com Protheus, esse trecho — proposta aprovada no CRM virando pedido no SC5 automaticamente — é onde o retorno aparece primeiro e onde o argumento para o restante do projeto se sustenta.

O fluxo completo: proposta aprovada no Zoho CRM com alçada de desconto registrada dispara a criação do pedido no Protheus via integração. O ERP valida crédito, aplica a política fiscal correta por UF e retorna o número do pedido para o CRM. O vendedor vê a confirmação sem sair do CRM. O back-office não recebe planilha. A nota sai no ciclo normal do ERP, sem que nenhum humano tenha replicado um único campo.

5. O caso que sempre derruba a integração em produção

O caminho feliz sempre passa no teste. O que derruba a integração em produção é o cliente de grupo econômico com chave de filial, o item com substituição tributária que o mapeamento não cobriu, o pedido parcial com entrega futura e a devolução que dispara rotina diferente da entrada. Roteiro de homologação que não inclui as exceções reais da operação é uma garantia de surpresa na primeira semana em produção.

A massa de teste precisa ser extraída da operação real: os pedidos mais comuns dos últimos noventa dias, os clientes com hierarquia de grupo econômico, os itens com regra fiscal específica e os casos de erro que o time de back-office conhece de cor. Testar apenas com exemplos simples valida a integração para um universo que não representa o cotidiano.

A virada assistida que evita a surpresa

A virada em produção deve ter um período de operação paralela: os mesmos pedidos transitando pela integração e pelo processo manual durante uma ou duas semanas, com comparação de resultado. Qualquer discrepância — pedido que chegou no ERP com campo diferente do que estava no CRM — é identificada antes de o processo manual ser desligado. Virada única, sem paralelo, é a forma mais cara de descobrir uma regra de negócio que o levantamento não capturou.

Limites honestos

Integração não conserta processo. Se o cadastro do ERP tem duplicidade e o CRM é preenchido de forma irregular, a sincronização propaga o problema — mais rápido do que antes. A limpeza de base é pré-requisito, não etapa opcional, e costuma consumir mais tempo do que a integração em si. Ver também cadastro duplicado CRM/ERP e como estruturamos esse tipo de projeto.

A disponibilidade do time de ERP é o risco de cronograma mais comum e menos documentado nos contratos de projeto. Consultores de Protheus experientes têm agenda cheia e nem sempre podem dedicar horas ao levantamento de customizações dentro da janela planejada. Reduzir a superfície de contato — menos entidades por onda, homologação em janelas previamente acordadas — é a forma mais prática de proteger o prazo sem depender de disponibilidade que não existe.

Perguntas frequentes

Continue por aqui