Conectar sistemas não é mais diferencial — é obrigação. Mas sem governança, a API vira um gargalo.

Introdução: A era das conexões invisíveis

Imagine um cenário comum: o time comercial trabalha em um CRM moderno, o financeiro depende do ERP, o estoque precisa integrar com uma plataforma de e-commerce, e a diretoria quer dashboards em tempo real.

Tudo isso só funciona se os sistemas conversarem entre si — de forma estruturada, segura e escalável. Mas o que acontece na prática?
Na pressa por entregar “integrações rápidas”, nascem gambiarras: queries diretas na base do Protheus, arquivos texto em pastas compartilhadas, robôs que leem telas via OCR.

E o resultado? Um ambiente frágil, difícil de auditar e cada vez mais caro de manter.

Spoiler: o TOTVS Protheus tem infraestrutura para fazer isso direito. Só falta usar.

REST e Web Services no Protheus: O que você precisa saber

O Protheus oferece dois caminhos principais de integração:

• Web Services (SOAP/XML) – mais tradicionais, utilizados em integrações legadas e sistemas legados.
  
  
• REST (JSON) – modernos, mais leves, fáceis de consumir e compatíveis com praticamente qualquer linguagem.
  
  

A TOTVS disponibiliza uma camada chamada TOTVS SmartClient WebService (TSW), além de permitir o desenvolvimento de REST APIs customizadas com MVC (Model-View-Controller) dentro do Protheus.

Exemplo prático: Criar um Pedido de Venda via API REST

• Endpoint: /api/v1/salesorder
  
  
• Autenticação: Token via header
  
  
• Payload: JSON com estrutura validada pelo dicionário de dados
  
  
• Resposta: Código do pedido gerado, status e logs de execução
  
  

Autenticação e Segurança: A porta só abre pra quem tem chave

Permitir chamadas para o seu ERP exige uma camada robusta de segurança:

• Autenticação via token JWT ou OAuth2 — jamais deixe sua API aberta com login e senha hardcoded.
  
  
• Controle por IP — restrinja o acesso a IPs confiáveis.
  
  
• Criptografia (HTTPS) — obrigatório, mesmo em redes privadas.
  
  
• Limites de requisição (Rate Limiting) — evite sobrecarga em rotinas sensíveis.
  
  
• Log de acessos e auditoria — registre cada interação para rastreabilidade.
  
  

Versionamento de API: Evite quebrar o que está funcionando

Toda API deve nascer com versionamento. Por exemplo:

• /api/v1/clientes
  
  
• /api/v2/clientes
  
  

Isso garante que novas mudanças não interrompam integrações que já funcionam em produção. Mudar uma estrutura de payload ou um campo obrigatório sem versionar é receita para o caos.

Tratamento de Erros: A integração não pode cair em silêncio

Erros acontecem. O problema é não saber onde, nem quando.

Por isso, toda chamada à API do Protheus deve:

• Retornar códigos HTTP padronizados (200, 400, 401, 500, etc.)
  
  
• Incluir mensagens descritivas no corpo do erro
  
  
• Escrever logs técnicos (com timestamp, usuário, input e stacktrace)
  
  
• Acionar alertas pro time correto em caso de falha crítica (via e-mail, webhook ou ferramenta de monitoramento)
  
  

Casos reais de uso

Integração com CRM (como Pipedrive ou Hubspot)

• Cadastro de clientes e negócios no CRM espelhados no Protheus via API REST.
  
  
• Atualizações de status sincronizadas automaticamente com a pipeline.
  
  

Integração com plataformas de e-commerce (VTEX, Magento, Tray)

• Consulta de preços e estoque em tempo real direto do Protheus.
  
  
• Importação automática de pedidos e geração de NF-e.
  
  

RPA com plataformas como UiPath ou Power Automate

• Robôs que consomem e alimentam dados via APIs REST, substituindo telas legadas ou processos manuais.
  
  

Mini-Framework de Boas Práticas

Evite criar uma estrutura paralela que ninguém consegue manter. Use o seguinte framework como base de governança:

Conclusão: A API é a nova interface de negócios

Se antes o foco era automatizar processos internos, hoje a estratégia exige comunicação sistêmica contínua. A API não é mais “um extra” — é infraestrutura crítica.

No TOTVS Protheus, é possível construir essa ponte com segurança e escalabilidade. Mas só se você tratar sua API com a seriedade que ela merece: como parte essencial da arquitetura corporativa, e não como um quebra-galho temporário.