Webservices REST no TOTVS Protheus: guia de integração

Toda integração séria com o TOTVS Protheus passa por uma decisão de arquitetura: entrar pelo banco de dados ou pela porta da frente — os webservices REST. A resposta curta de quem já sustentou as duas abordagens em produção: leitura pode ir ao banco com credencial restrita; escrita passa pela API, sempre. Gravar direto na tabela pulando as regras de negócio do ERP é dívida técnica com juros compostos.

O que o Protheus oferece de REST

• APIs padrão do ERP para entidades comuns (clientes, produtos, pedidos), disponíveis conforme a versão e o licenciamento do ambiente;
• Serviços customizados em ADVPL: você expõe suas próprias rotinas como endpoints REST — o caminho mais usado em integração sob medida;
• Autenticação e controle de acesso integrados à segurança do ERP.

O serviço customizado é onde mora a flexibilidade: uma função ADVPL que valida, executa a regra de negócio (ExecAuto, modelo MVC) e responde JSON. É assim que pedido de marketplace entra no ERP sem quebrar nada.

Boas práticas que evitam sofrimento

1. Contrato claro: documente cada endpoint (payload, respostas, erros) — a IA ajuda a gerar essa documentação a partir do código;
2. Idempotência: o mesmo pedido enviado duas vezes não pode virar duas vendas — use chaves externas;
3. Erros que explicam: "422: cliente bloqueado por crédito" vale ouro; "400: erro" custa horas de suporte;
4. Credencial por integração: cada sistema consumidor com seu usuário, escopo mínimo e logs separados;
5. Versionamento: mudou o contrato, versione o endpoint — integração alheia não pode quebrar em silêncio.

REST como fundação para IA no ERP

Aqui está o ponto que pouca gente conecta: os mesmos webservices que servem integrações tradicionais são a porta pela qual agentes de IA operam o ERP com segurança. O chat com o ERP consulta por leitura; um agente que dispara a régua de cobrança ou registra uma ocorrência escreve via API — passando pelas mesmas validações que um usuário passaria. A qualidade das suas APIs define o teto do que a IA pode fazer no seu ambiente.

Por isso, quando fazemos diagnóstico de prontidão para IA, uma das primeiras perguntas é: o que já está exposto como serviço? Ambientes com camada REST organizada saem na frente; nos demais, construir os primeiros endpoints certos faz parte do projeto — e as automações via n8n se beneficiam imediatamente.

Por onde começar

Se a sua integração hoje é planilha, arquivo ou gravação direta no banco, comece expondo os dois ou três serviços mais usados. Como estimativa, uma camada REST inicial bem feita leva poucas semanas e destrava anos de integrações mais seguras. A Totusia projeta e constrói essa camada em ambientes TOTVS Protheus — conheça as soluções de integração ERP × IA.

Perguntas rápidas

REST ou fila de mensagens para integrar o ERP?

Os dois convivem: REST para consulta e comando síncrono (consultar saldo, incluir pedido), fila para volume e resiliência (milhares de eventos, sistemas que podem ficar fora do ar). A escolha errada mais comum é usar só REST síncrono para tudo e descobrir o limite em dia de pico.

Como testar sem arriscar a produção?

Ambiente de homologação com dados mascarados, coleção de testes automatizada por endpoint e janela de validação com dados reais controlados. Endpoint que nunca foi testado sob erro (payload inválido, duplicidade) não está pronto.