Como integrar TOTVS com CRM: passo a passo prático
Empresa que cresce sem integrar ERP e CRM vive a mesma dor: vendedor cadastra cliente no CRM, alguém redigita no TOTVS, faturamento sai com dado errado, financeiro cobra cliente que não existe no CRM. Reuniões viram briga de planilha.
Este artigo é o guia que eu daria para um gestor que vai começar essa integração. Foco em TOTVS Protheus porque é o mais comum, mas o método se aplica a RM, SAP Business One e Sankhya com adaptações pontuais.
Os 4 fluxos que você precisa decidir antes de começar
Antes de qualquer código, decida quais fluxos vão ser integrados. Não tente integrar tudo de uma vez — projeto vira eterno.
Os quatro mais comuns:
- Cliente / Conta: sincronização do cadastro. Quando alguém é criado no CRM, vira no ERP (ou vice-versa).
- Pedido / Oportunidade: quando oportunidade vira "fechada-ganha" no CRM, pedido nasce no ERP.
- Faturamento / Nota Fiscal: quando ERP emite NF, status volta para o CRM.
- Histórico financeiro: título em aberto, pagamento, inadimplência — visíveis no CRM ao vendedor.
Você não precisa dos quatro. Comece por um. Os dois primeiros entregam 80% do valor.
Sentido do fluxo: quem é a fonte da verdade?
Esta é a decisão arquitetural mais importante. Para cada entidade, defina qual sistema é mestre:
- Cliente quase sempre nasce no CRM (lead → conta), então CRM é mestre até o cliente ter um pedido fechado. A partir daí, o ERP assume.
- Produto sempre nasce no ERP. O CRM apenas consome.
- Pedido nasce no CRM (oportunidade fechada) e é criado no ERP. Status volta para o CRM.
- Financeiro nasce no ERP. CRM apenas consome para visualização.
Definir mestre evita o pior bug de integração: dois sistemas tentando atualizar o mesmo dado ao mesmo tempo, gerando inconsistência.
A API REST oficial do TOTVS
TOTVS Protheus oferece desde 2018 uma API REST oficial (Rest 2.0), com endpoints para a maioria dos módulos:
/api/framework/v1/users/api/erp/v1/customers/api/erp/v1/products/api/erp/v1/orders
Para usar, é necessário habilitar o módulo REST no Protheus (via SmartClient ou via TOTVS Connect) e gerar token de acesso. Cada empresa tem seu próprio endpoint.
Limitações conhecidas da API: alguns campos customizados (User Defined Fields) não vêm na resposta padrão. Para esses casos, é necessário criar endpoint customizado em ADVPL. Reserve essa complexidade para o final do projeto.
E se a API não cobrir tudo?
Para módulos sem API exposta, há três alternativas:
1. Customização ADVPL. Você (ou um parceiro TOTVS) escreve endpoint customizado. Mais robusto, mais caro. Use para casos de alto volume.
2. Banco de dados direto (perigoso). Conectar direto no Oracle/SQL Server do Protheus. Só leitura. Escrita direta no banco quebra integridade. Use só para relatórios e BI.
3. RPA de interface. Robô opera o Protheus SmartClient como humano. Use para casos onde nem API nem banco resolvem. Tem custo de manutenção.
Os 6 passos do projeto
1. Mapeamento de chaves
Defina como os IDs vão se corresponder. Exemplo:
- Cliente no CRM tem ID Salesforce:
0010X00abc... - Mesmo cliente no Protheus tem código
SA1.A1_COD:000123 - Como sabemos que são o mesmo? Por CNPJ (no caso de PJ) ou CPF (PF).
Você precisa armazenar essa relação em algum lugar — geralmente em um campo customizado no CRM (Codigo_ERP__c) ou em uma tabela de mapeamento externa.
2. Arquitetura do middleware
Recomendo middleware dedicado entre os dois sistemas — não conexão ponto a ponto. Por quê? Porque assim:
- Você troca de CRM sem refazer toda a integração
- Logs ficam centralizados
- Reprocessamento é simples
- Auditoria é completa
Stack típica: Node.js ou Python rodando em AWS Lambda / Cloud Run / VPS, com fila (SQS, RabbitMQ) e logs (Datadog, CloudWatch).
3. Idempotência
Toda mensagem entre sistemas precisa ser idempotente — se for processada 2 vezes por engano, o resultado é o mesmo. Implementação prática: armazenar external_id em cada entidade e fazer upsert, nunca insert puro.
4. Tratamento de erro com fila de reprocessamento
Quando o ERP estiver fora do ar (manutenção, deploy, etc.), o middleware não pode perder dados. Padrão: toda mensagem que falha vai para uma fila de retry exponencial (1min, 5min, 30min, 2h). Se falhar após N tentativas, alerta para humano.
5. Painel de monitoramento
Você precisa de painel que mostre:
- Quantas mensagens passaram nas últimas 24h
- Quantas falharam
- Tempo médio de sincronização (CRM → ERP, ERP → CRM)
- Lista de erros pendentes
Sem isso, a integração vira caixa preta — quando alguém reclamar, ninguém saberá o que aconteceu.
6. Estratégia de go-live
Nunca vá direto para produção 100%. Padrão sensato:
- Semana 1: integração rodando em paralelo (espelhamento), sem afetar usuários
- Semana 2: liberar para 1 vendedor ou 1 filial piloto
- Semana 3: ampliar para 25% da operação
- Semana 4: rollout total
Esse processo dá tempo de pegar bugs em cenário real sem virar problema para todo mundo.
Cronograma realista
Integração TOTVS ↔ CRM com 2 fluxos (cliente + pedido):
- Levantamento e arquitetura: 1–2 semanas
- Desenvolvimento: 4–6 semanas
- Testes paralelos: 2 semanas
- Go-live faseado: 2 semanas
Total: 9 a 12 semanas. Quem promete entregar em 4 semanas está mentindo ou cortando algum dos passos acima — geralmente o tratamento de erro.
Quando contratar e quando fazer interno
Faça interno se: sua TI tem experiência prévia com integrações TOTVS, você tem 3+ meses de prazo, e o time pode dedicar pelo menos 1 dev sênior em tempo integral.
Contrate parceiro especializado se: é a primeira integração TOTVS da empresa, o time atual está sobrecarregado, ou você precisa entregar em menos de 3 meses.
Para os clientes que atendemos, a integração TOTVS com CRM e outros sistemas tipicamente custa entre R$ 35 mil e R$ 90 mil, com prazo de 8 a 14 semanas. Inclui middleware, monitoramento e 6 meses de garantia.
Conclusão
Integração TOTVS-CRM não é projeto de tecnologia. É projeto de processo. O que mata integração é não decidir antes quem é mestre, quais fluxos integrar, e como lidar com erro. O que faz dar certo é começar pequeno, monitorar tudo e fazer rollout faseado.
A pergunta final: você tem time, tempo e tolerância para errar duas vezes antes de acertar? Se sim, faça interno. Se não, contrate alguém que já errou as duas vezes antes.