Integração Protheus via API REST: Guia Seguro

Aprenda a planejar uma integração Protheus via API REST com contratos, autenticação, idempotência, filas, testes, observabilidade e reconciliação.

O que é uma integração Protheus via API REST?

Uma integração Protheus via API REST permite que portais, aplicativos, e-commerces, plataformas de logística e outros sistemas consultem ou enviem informações ao ERP por endpoints HTTP. Em vez de repetir cadastros manualmente ou trocar planilhas, os sistemas comunicam eventos e dados por um contrato explícito, normalmente usando JSON.

O projeto, porém, não termina quando uma requisição retorna sucesso. Uma integração empresarial precisa preservar regras de negócio, identificar empresa e filial, autenticar cada consumidor, evitar duplicidades, registrar falhas, reconciliar resultados e continuar operável quando um dos lados estiver indisponível.

A TOTVS documenta que o REST 2.0 do Protheus suporta APIs tradicionais em ADVPL e APIs em TLPP com anotações. Versões, componentes e recursos variam conforme a release e a LIB; por isso, a documentação correspondente ao ambiente instalado deve prevalecer sobre exemplos antigos encontrados na internet.

Quando usar API para integrar o Protheus

Uma API costuma ser adequada quando a interação precisa ocorrer sob demanda, com validação e resposta claras. Exemplos incluem:

consultar disponibilidade e preço para um canal de vendas;
enviar pedidos aprovados ao ERP;
informar status de faturamento ou expedição;
receber cadastros de uma aplicação autorizada;
disponibilizar dados controlados para um portal;
acionar uma regra de negócio do Protheus sem acesso direto ao banco.

Nem todo fluxo deve ser síncrono. Importações volumosas, fechamentos, processamento em lote e operações que atravessam vários sistemas podem funcionar melhor com filas, jobs ou arquivos controlados. A decisão depende de volume, latência tolerada, consistência, capacidade de reprocessamento e criticidade.

O guia sobre integração de sistemas via API apresenta os fundamentos gerais. Aqui, o foco é aplicar esses princípios ao Protheus e às particularidades de um ERP transacional.

Defina o processo antes do endpoint

Começar pelo recurso técnico costuma produzir uma API que transfere campos, mas não resolve o processo. Antes de programar, descreva o fluxo de ponta a ponta:

qual evento inicia a integração;
qual sistema é responsável por cada dado;
quais validações devem ocorrer;
quando o registro é considerado aceito;
qual identificador relaciona as duas plataformas;
o que acontece se houver rejeição, demora ou indisponibilidade;
como uma pessoa corrige e reprocessa o caso;
como os sistemas confirmam que terminaram com o mesmo resultado.

Em um pedido de venda, por exemplo, receber JSON não equivale a concluir o processo. Cliente, condição de pagamento, produto, estoque, preço, impostos e permissões podem afetar a inclusão. A resposta precisa distinguir falha técnica de rejeição por regra de negócio e retornar um identificador rastreável.

API padrão ou API customizada no Protheus?

Primeiro verifique se existe API oficial para o módulo e a operação desejados. A disponibilidade e os requisitos não são uniformes: a referência de APIs de Manutenção e Gestão de Frotas, por exemplo, documenta endpoints, autenticação e cabeçalhos próprios daquele contexto. Outros módulos podem adotar contratos diferentes ou não expor a operação necessária.

Use uma API padrão quando ela atender à regra, à versão e ao modelo de dados da empresa. Isso reduz código próprio, mas ainda exige testes de contrato, segurança e operação.

Uma API customizada pode ser justificável quando o processo reúne validações específicas, precisa orquestrar mais de uma rotina ou deve oferecer um contrato estável diferente das estruturas internas. Nesse caso:

prefira mecanismos suportados pela release;
encapsule a regra de negócio em vez de expor tabelas;
versione código e contrato;
documente entradas, saídas e efeitos colaterais;
teste a compatibilidade em atualizações;
defina um responsável pela manutenção.

Se o Protheus precisar consumir uma API externa, a TOTVS disponibiliza a classe cliente FWRest. Ela não elimina a necessidade de tratar timeout, códigos HTTP, autenticação, limites e resposta inválida.

Desenhe um contrato que sobreviva a mudanças

O contrato deve ser compreensível sem acesso ao código-fonte. Para cada endpoint, documente:

finalidade e proprietário;
método, caminho e versão;
campos obrigatórios, formatos, limites e enumerações;
empresa, filial e contexto operacional aplicáveis;
autenticação e autorização exigidas;
exemplos válidos e inválidos;
códigos HTTP e estrutura dos erros;
chave de idempotência ou identificador externo;
paginação, filtros e ordenação em consultas;
limites de uso e timeout;
política de compatibilidade e descontinuação.

Algumas APIs do Protheus usam cabeçalhos como tenantId para identificar empresa e filial. Não generalize esse formato para todo endpoint: confirme a documentação da API e da release adotadas. Uma interpretação errada desse contexto pode direcionar uma operação à entidade incorreta.

Evite fazer o consumidor depender de nomes de tabela, campos internos ou mensagens livres. Um contrato de negócio — pedidoExterno, cliente, itens e condicaoPagamento, por exemplo — tende a ser mais controlável do que replicar diretamente a estrutura física do ERP.

Segurança da integração Protheus via API REST

Uma API do ERP alcança dados e processos sensíveis. A proteção deve combinar rede, identidade, aplicação e operação.

Autenticação não é autorização

Autenticar confirma a identidade do consumidor; autorizar limita o que ele pode fazer. Crie identidades próprias para integrações, conceda somente os acessos necessários e evite compartilhar usuários humanos.

A TOTVS informa que, a partir do release 12.1.2410, a autenticação de REST e SOAP fica ligada por padrão. Ambientes anteriores e APIs específicas precisam ser avaliados conforme suas versões. Não trate essa mudança como garantia de que permissões, rede e credenciais já estejam corretas.

Proteja credenciais e transporte

Use HTTPS válido, armazene segredos em mecanismo apropriado, restrinja leitura, registre rotações e nunca coloque credenciais do ERP em navegador ou aplicativo móvel. Quando compatível com o ambiente, considere o modelo de token de acesso das APIs REST do Protheus, verificando pré-requisitos e comportamento na documentação atual.

Reduza a superfície exposta

Não publique o AppServer diretamente na internet apenas para facilitar a primeira conexão. Avalie gateway, proxy reverso, allowlist quando aplicável, segmentação, limites de requisição e monitoração. Separe o serviço REST das cargas interativas quando a arquitetura e a orientação oficial do produto recomendarem isso.

O OWASP API Security Top 10 de 2023 destaca riscos como autorização quebrada, autenticação inadequada, consumo irrestrito de recursos e inventário deficiente. Use-o como roteiro de ameaças, não como checklist que por si só comprova segurança.

Como evitar pedidos e títulos duplicados

Falhas de rede criam ambiguidade: o cliente pode não receber a resposta mesmo depois de o Protheus concluir a operação. Se ele repetir o POST sem controle, o ERP pode registrar o mesmo negócio novamente.

Implemente idempotência no nível do processo:

o sistema de origem gera uma chave única e estável;
o Protheus ou a camada de integração registra essa chave com o resultado;
uma repetição retorna o resultado conhecido, sem refazer a operação;
tentativas concorrentes são serializadas ou rejeitadas de forma previsível;
a chave participa da conciliação entre os sistemas.

Não suponha que todo método HTTP seja idempotente. A RFC 9110 define a semântica dos métodos, mas a operação de negócio e sua implementação continuam determinantes. Um PUT mal projetado também pode produzir efeitos repetidos.

Quando usar processamento síncrono ou assíncrono

Fluxo síncrono

É adequado quando o consumidor precisa de resposta imediata, o processamento é curto e a indisponibilidade pode ser comunicada ao usuário. Consultas e validações simples são exemplos frequentes.

Defina timeout realista. Uma conexão aberta por muito tempo ocupa recursos nos dois lados e aumenta a chance de repetição incerta.

Fluxo assíncrono

É preferível quando há picos, processamento demorado, dependências instáveis ou necessidade de reprocessamento. O produtor registra a mensagem, recebe confirmação de aceite e consulta o resultado depois ou recebe uma notificação.

Filas não resolvem consistência automaticamente. Defina ordenação quando necessária, tentativas com espera progressiva, limite de repetição, fila de erros e ferramenta para reprocessar. Registre a correlação entre mensagem, requisição, documento do Protheus e retorno.

Não use gravação direta no banco como atalho

Alterar tabelas do ERP diretamente pode ignorar validações, transações, sequências, gatilhos lógicos e relacionamentos mantidos pela aplicação. O resultado pode parecer correto em uma tabela e permanecer incoerente para o processo.

Para escrita, prefira APIs e rotinas compatíveis com a regra de negócio, validadas para a release. Consultas diretas também exigem cuidado: estruturas podem mudar, campos podem ter semântica interna e leituras pesadas podem afetar a produção. Quando o objetivo for analytics, avalie réplica, extração incremental ou camada de dados própria.

Uma consultoria Protheus pode mapear a rotina padrão, as customizações existentes e o mecanismo de integração adequado antes que o projeto crie dependência difícil de manter.

Observabilidade e reconciliação

Uma integração precisa responder: o que entrou, o que saiu, o que falhou e qual foi o resultado final. Registre, sem expor dados sensíveis:

identificador de correlação;
sistema de origem e destino;
endpoint, versão e operação;
empresa e filial quando necessárias;
horário, duração e código de retorno;
número da tentativa;
identificador externo e documento gerado;
categoria do erro;
estado do reprocessamento.

Crie métricas de volume, sucesso, rejeição funcional, erro técnico, latência, backlog e idade da mensagem mais antiga. Alertas devem indicar impacto e responsável, não apenas produzir ruído.

Reconciliação é a verificação periódica de que os dois lados concordam. Compare chaves, quantidade, valores e estados; trate divergências por fluxo auditável. Logs ajudam a investigar, mas não substituem essa confirmação. O guia de observabilidade de sistemas aprofunda métricas, traces e alertas orientados ao serviço.

Testes antes de integrar com a produção

Use um ambiente de homologação representativo, com acessos separados e dados protegidos. Cubra:

contrato e validação de cada campo;
autenticação, autorização e troca de credenciais;
empresa e filial corretas;
regras fiscais, comerciais e de estoque aplicáveis;
duplicidade, concorrência e reenvio;
timeout e resposta perdida;
indisponibilidade de cada dependência;
payload grande, incompleto ou malformado;
caracteres, datas, decimais e fuso horário;
carga e limite de recursos;
atualização da release e regressão;
reconciliação e reprocessamento.

Não use apenas o status HTTP como aceite. Confira o documento criado, os efeitos contábeis ou fiscais pertinentes, os vínculos e a resposta consumida pelo outro sistema. Áreas responsáveis pelo processo devem aprovar cenários críticos.

Plano de implementação em oito etapas

Mapeie o processo: evento, responsáveis, fonte de verdade e resultado esperado.
Inventarie o ambiente: release, LIB, módulos, APIs existentes, customizações e integrações.
Escolha o padrão: API oficial, extensão controlada ou fluxo assíncrono conforme o caso.
Defina o contrato: versão, dados, erros, idempotência e compatibilidade.
Projete a segurança: identidade, autorização, segredos, rede e auditoria.
Construa e teste: automatize contrato, regressão, falhas e carga em homologação.
Implante gradualmente: limite consumidores, monitore e mantenha possibilidade de retorno.
Opere e reconcilie: acompanhe métricas, divergências, mudanças e versões.

A criação de software sob medida pode incluir a camada de integração, filas, portal e observabilidade, enquanto governança e compliance ajuda a definir acessos, riscos e evidências.

Checklist da integração Protheus via API REST

Processo e fonte de verdade estão definidos?
A API padrão foi avaliada para a release instalada?
Contrato possui versão e política de compatibilidade?
Empresa e filial são tratadas explicitamente?
Consumidor usa identidade própria e menor privilégio?
Credenciais ficam fora do código e do cliente público?
Transporte e exposição de rede estão protegidos?
Operações de escrita possuem chave de idempotência?
Retentativas têm limite e espera progressiva?
Fluxos longos usam processamento assíncrono quando necessário?
Erros técnicos e rejeições funcionais são diferentes?
Logs usam correlação sem vazar dados sensíveis?
Há métricas, alertas, reconciliação e reprocessamento?
Homologação cobre concorrência, falhas e carga?
Atualizações do Protheus entram nos testes regressivos?
Responsáveis por suporte e evolução estão definidos?

Conclusão

Uma integração Protheus via API REST confiável combina conhecimento do processo, mecanismos suportados pelo ERP e engenharia de integração. O endpoint é apenas a porta: contrato, autenticação, idempotência, processamento assíncrono, observabilidade e reconciliação determinam se a automação continuará segura quando surgirem falhas e mudanças.

Se sua empresa precisa integrar o Protheus a e-commerce, aplicativo, portal ou sistema interno, fale com a Mattos Tech Solutions para avaliar o fluxo, o ambiente e a arquitetura apropriada.