Serviço REST Protheus: como criar APIs seguras no TOTVS Protheus e integrar sistemas externos

Criar um serviço REST no TOTVS Protheus é uma das formas mais eficientes de integrar o ERP com sistemas externos, automatizar processos e permitir que diferentes plataformas troquem informações de maneira estruturada.

Em empresas que utilizam Protheus, APIs REST podem conectar o ERP a e-commerce, marketplaces, bancos, WMS, TMS, CRM, BI, aplicativos internos, portais de clientes, sistemas fiscais e soluções legadas. Com isso, pedidos, clientes, fornecedores, produtos, notas fiscais, títulos financeiros, saldos de estoque e relatórios podem circular com mais velocidade e menor dependência de processos manuais.

No entanto, criar uma API REST no Protheus não deve ser tratado apenas como uma tarefa de desenvolvimento ADVPL. É necessário planejar o endpoint, configurar corretamente o AppServer, definir métodos HTTP, validar autenticação, proteger dados sensíveis, tratar erros, testar cenários reais e documentar a integração para garantir segurança, estabilidade e manutenção.

Neste guia, você verá como criar um serviço REST no Protheus, quais configurações validar antes de publicar a API, como consumir APIs externas com FWRest, quais cuidados tomar com segurança e como a Global GCS pode apoiar projetos de integração com TOTVS Protheus.

como criar um serviço REST no Protheus?

Para criar um serviço REST no Protheus, a empresa precisa configurar o ambiente REST no AppServer, desenvolver uma classe usando WSRESTFUL em ADVPL, declarar os métodos HTTP necessários, como GET, POST, PUT e DELETE, compilar o fonte, reiniciar o AppServer, testar o endpoint com ferramentas como Postman ou cURL e validar segurança, autenticação, permissões, logs e tratamento de erros.

Além disso, é importante testar o serviço em ambiente de homologação antes de disponibilizar em produção, principalmente quando a API envolve dados de clientes, fornecedores, produtos, pedidos, estoque, financeiro ou informações fiscais.

O que é REST e por que usar no Protheus?

REST, ou Representational State Transfer, é um estilo de arquitetura usado para criar APIs que permitem a comunicação entre sistemas por meio de requisições HTTP.

Na prática, uma API REST permite que um sistema envie ou consulte informações usando métodos como:

Método HTTP	Uso comum
GET	Consultar informações
POST	Criar registros
PUT	Atualizar registros
DELETE	Excluir ou remover registros
PATCH	Atualizar parcialmente um recurso, quando suportado pela arquitetura

No contexto do TOTVS Protheus, um serviço REST pode expor rotinas do ERP para outros sistemas ou permitir que o Protheus consuma dados de APIs externas.

Exemplos de uso:

• consultar cadastro de clientes;
• integrar pedidos de venda de um e-commerce;
• enviar dados de estoque para marketplace;
• receber informações de transportadoras;
• integrar cobranças bancárias;
• alimentar dashboards de BI;
• consultar status de notas fiscais;
• conectar sistemas legados ao ERP;
• automatizar rotinas entre Protheus e aplicações externas.

O grande benefício é reduzir retrabalho, eliminar digitação duplicada e melhorar a integração entre áreas e sistemas.

Quando criar um serviço REST no Protheus?

Criar um serviço REST no Protheus faz sentido quando a empresa precisa trocar informações com outros sistemas de forma estruturada, segura e recorrente.

Alguns cenários comuns:

Cenário	Exemplo prático
Integração com e-commerce	Receber pedidos no Protheus e devolver nota fiscal e status de faturamento
Integração com marketplace	Sincronizar produtos, preços, estoque e pedidos
Integração com banco	Consultar pagamentos, gerar cobranças ou processar retornos
Integração com BI	Enviar dados financeiros, comerciais e operacionais para dashboards
Integração com WMS ou TMS	Atualizar estoque, expedição, separação e entrega
Integração com CRM	Sincronizar clientes, oportunidades, pedidos e histórico comercial
Integração fiscal	Apoiar documentos eletrônicos, notas, obrigações e validações
Portal de clientes	Permitir consulta de pedidos, notas, boletos ou status de entrega

Antes de desenvolver a API, a empresa deve responder uma pergunta central: qual processo de negócio essa integração precisa resolver?

A resposta ajuda a definir escopo, método HTTP, payload, segurança, responsáveis e critérios de aceite.

REST no Protheus: ponto de atenção antes do desenvolvimento

Antes de começar a escrever código, é necessário confirmar se o ambiente está preparado.

A implantação de um serviço REST no Protheus depende de:

• release compatível;
• AppServer configurado;
• includes atualizados;
• ambiente REST habilitado;
• porta definida;
• segurança configurada;
• usuário com permissão;
• rotina compilada corretamente;
• reinício do AppServer após publicação;
• testes em homologação;
• plano de publicação em produção.

Também é importante validar com a equipe de TI se o endpoint será usado apenas internamente ou se ficará exposto para sistemas externos. Essa decisão muda os cuidados de rede, firewall, autenticação, SSL, controle de IPs, logs e monitoramento.

Configuração básica do ambiente REST no Protheus

O serviço REST precisa estar habilitado no arquivo de configuração do AppServer.

Um exemplo básico de configuração pode seguir esta estrutura:

[HTTP_SERVER]

Enabled=1

Port=8080

Em ambientes produtivos, a configuração deve ser revisada com mais cuidado. A porta, o serviço, a segurança e a exposição externa precisam ser definidos conforme a arquitetura da empresa.

Também é importante avaliar configurações relacionadas a:

• HTTPS/SSL;
• autenticação;
• controle de origem;
• CORS;
• logs;
• timeout;
• performance;
• balanceamento;
• acesso por IP;
• segregação entre homologação e produção.

Para ambientes críticos, evite publicar serviços REST sem autenticação, sem criptografia e sem controle de acesso.

Como criar um serviço REST no Protheus com WSRESTFUL

No Protheus, a criação de um serviço REST pode ser feita com a estrutura WSRESTFUL em ADVPL.

A estrutura básica envolve:

1. incluir as bibliotecas necessárias;
2. declarar a classe REST;
3. declarar os métodos;
4. desenvolver cada método;
5. definir o retorno da requisição;
6. compilar o fonte;
7. reiniciar o AppServer;
8. testar o endpoint.

Exemplo básico:

#Include “TOTVS.ch”

#Include “RESTFUL.ch”

WSRESTFUL HELLOWORLD DESCRIPTION “Meu primeiro serviço REST no Protheus”

    WSMETHOD GET DESCRIPTION “Retorna mensagem de teste”

END WSRESTFUL

WSMETHOD GET WSSERVICE HELLOWORLD

    ::SetResponse(‘[{“status”:”Hello World”}]’)

Return .T.

Esse exemplo cria um endpoint simples de consulta.

Após a compilação, o AppServer deve ser reiniciado para que o serviço seja publicado corretamente.

Como estruturar endpoints REST no Protheus

A criação de uma API deve seguir uma lógica clara de recursos.

Evite nomes genéricos, confusos ou dependentes de lógica interna do ERP.

Exemplos de endpoints mais claros:

/rest/clientes

/rest/clientes/{id}

/rest/produtos

/rest/pedidos

/rest/pedidos/{id}

/rest/estoque/{produto}

/rest/notas-fiscais/{numero}

Uma boa API deve ser previsível para quem consome.

Boas práticas:

• usar nomes de recursos no plural;
• evitar verbos desnecessários na URL;
• usar métodos HTTP corretamente;
• manter padrão de resposta em JSON;
• retornar mensagens de erro claras;
• versionar APIs quando necessário;
• documentar parâmetros obrigatórios;
• validar permissões por operação.

Exemplo:

Operação	Método	Endpoint
Consultar clientes	GET	/rest/clientes
Consultar cliente específico	GET	/rest/clientes/{id}
Criar pedido	POST	/rest/pedidos
Atualizar pedido	PUT	/rest/pedidos/{id}
Excluir ou cancelar recurso	DELETE	/rest/recurso/{id}

Exemplo de retorno JSON

Uma API REST deve retornar dados em formato estruturado, preferencialmente JSON.

Exemplo de resposta de sucesso:

{

  “success”: true,

  “message”: “Consulta realizada com sucesso”,

  “data”: {

    “codigo”: “000001”,

    “nome”: “Cliente Exemplo”,

    “status”: “ativo”

  }

}

Exemplo de resposta com erro:

{

  “success”: false,

  “message”: “Cliente não encontrado”,

  “errorCode”: “CLIENTE_NAO_ENCONTRADO”

}

Manter um padrão de resposta facilita o consumo por outros sistemas e reduz dúvidas durante a integração.

Como tratar erros em serviços REST no Protheus

O tratamento de erros é essencial para tornar a API mais robusta.

Uma API não deve retornar apenas erro genérico. Ela precisa indicar o que aconteceu e, quando possível, orientar a correção.

Exemplos de erros que devem ser tratados:

• recurso não encontrado;
• parâmetro obrigatório ausente;
• JSON inválido;
• usuário sem permissão;
• autenticação ausente;
• dados inconsistentes;
• erro de integração;
• erro interno no processamento;
• timeout;
• duplicidade de registro.

Sugestão de organização:

Situação	Retorno recomendado
Requisição válida	200 ou 201
Parâmetro ausente	400
Usuário não autenticado	401
Usuário sem permissão	403
Registro não encontrado	404
Erro de regra de negócio	422
Erro interno	500

Mesmo que a implementação varie conforme o ambiente, o importante é manter consistência e clareza para quem consome a API.

Segurança em APIs REST no Protheus

Segurança é uma das partes mais importantes de qualquer API.

Uma API REST pode expor dados estratégicos da empresa. Por isso, não deve ser publicada sem autenticação, controle de acesso e criptografia.

Cuidados recomendados:

• exigir autenticação;
• usar HTTPS/SSL;
• restringir IPs autorizados, quando aplicável;
• controlar permissões por rotina ou recurso;
• evitar exposição de dados sensíveis;
• registrar logs de acesso;
• proteger tokens e credenciais;
• evitar senhas em código-fonte;
• limitar endpoints disponíveis;
• validar todos os parâmetros recebidos;
• aplicar regras de autorização por usuário;
• revisar riscos de LGPD.

No Protheus, a configuração de segurança pode envolver o uso de Security=1 no serviço REST e o uso de controle de permissões associado à rotina indicada no serviço.

Também é possível estruturar autenticação com Basic ou OAuth 2.0, conforme arquitetura, ambiente e necessidade da integração.

APIs REST e LGPD: cuidado com dados pessoais

Quando uma API REST trafega dados de clientes, fornecedores, usuários, colaboradores ou contatos, a empresa precisa considerar a LGPD.

Pontos de atenção:

• coletar apenas os dados necessários;
• limitar o retorno da API ao mínimo necessário;
• evitar exposição de CPF, e-mail, telefone ou endereço sem necessidade;
• registrar logs sem gravar dados sensíveis em excesso;
• controlar quem pode consumir a API;
• revisar contratos com terceiros integrados;
• aplicar criptografia em trânsito;
• definir política de retenção de logs;
• manter trilha de auditoria.

Uma API eficiente não deve retornar todos os dados disponíveis. Ela deve retornar apenas o que o processo realmente precisa.

OWASP API Security: riscos que precisam ser considerados

As APIs estão entre os principais pontos de atenção em segurança digital. A OWASP API Security Top 10 destaca riscos como autorização quebrada em nível de objeto, falhas de autenticação, exposição excessiva de dados, consumo de recursos sem controle e configurações incorretas de segurança.

No contexto do Protheus, isso significa que uma API não deve confiar apenas no parâmetro enviado pelo consumidor.

Exemplo de risco:

/rest/clientes/000001

/rest/clientes/000002

Se o consumidor altera o código do cliente na URL e consegue acessar dados sem autorização, existe uma falha de controle de acesso.

Por isso, cada endpoint deve validar:

• quem é o usuário;
• qual empresa ou filial ele pode acessar;
• quais registros ele pode consultar;
• quais operações ele pode executar;
• se o recurso solicitado pertence ao escopo autorizado;
• se os dados retornados são realmente necessários.

Segurança de API não é apenas login. É controle de autorização em cada operação.

Como consumir APIs externas no Protheus com FWRest

Além de expor serviços REST, o Protheus também pode consumir APIs externas.

Para isso, uma abordagem comum é utilizar a classe FWRest.

Esse recurso permite realizar chamadas HTTP para APIs de terceiros, enviar headers, informar parâmetros, enviar JSON no corpo da requisição e processar o retorno.

Exemplo simplificado de consumo de API externa:

#Include “TOTVS.ch”

User Function ConsApi()

    Local cURI      := “https://api.exemplo.com.br”

    Local cResource := “/v1/clientes”

    Local oRest     := FWRest():New(cURI)

    Local aHeader   := {}

    AAdd(aHeader, “Content-Type: application/json; charset=UTF-8”)

    AAdd(aHeader, “Accept: application/json”)

    oRest:SetPath(cResource)

    If oRest:Get(aHeader)

        ConOut(oRest:GetResult())

    Else

        ConOut(oRest:GetLastError())

    EndIf

Return

Para chamadas POST, é necessário configurar o body da requisição e enviar o JSON conforme a documentação da API externa.

Exemplo de POST com FWRest

#Include “TOTVS.ch”

User Function PostApi()

    Local cURI      := “https://api.exemplo.com.br”

    Local cResource := “/v1/pedidos”

    Local oRest     := FWRest():New(cURI)

    Local aHeader   := {}

    Local cJson      := “”

    AAdd(aHeader, “Content-Type: application/json; charset=UTF-8”)

    AAdd(aHeader, “Accept: application/json”)

    cJson := ‘{“pedido”:”12345″,”cliente”:”000001″,”valor”:1500.00}’

    oRest:SetPath(cResource)

    oRest:SetPostParams(cJson)

    If oRest:Post(aHeader)

        ConOut(oRest:GetResult())

    Else

        ConOut(oRest:GetLastError())

    EndIf

Return

Esse exemplo é apenas uma base. Em produção, a integração precisa tratar autenticação, tokens, erros, logs, timeout, reprocessamento e validação de retorno.

O que validar ao integrar o Protheus com APIs externas

Antes de consumir uma API externa pelo Protheus, levante as seguintes informações:

Item	O que verificar
URL base	Endereço da API
Recurso	Endpoint que será consumido
Método HTTP	GET, POST, PUT, DELETE
Autenticação	Token, OAuth 2.0, Basic, API key ou outro modelo
Headers	Content-Type, Accept, Authorization e outros
Payload	Estrutura JSON enviada
Retorno	Estrutura JSON recebida
Códigos de erro	Como a API retorna falhas
Timeout	Tempo limite de resposta
Rate limit	Limite de chamadas
Logs	O que será registrado
Reprocessamento	Como tratar falhas temporárias
Responsável externo	Quem acionar em caso de erro

A integração não deve depender apenas de uma chamada bem-sucedida em teste. Ela precisa prever falhas reais de operação.

Integração Protheus com e-commerce, BI, bancos e sistemas externos

Serviços REST podem apoiar diferentes frentes de integração no Protheus.

Integração com e-commerce

Pode envolver:

• importação de pedidos;
• consulta de estoque;
• atualização de preços;
• envio de status;
• retorno de nota fiscal;
• integração com transportadora;
• baixa de pedidos faturados.

Integração com bancos

Pode envolver:

• geração de cobranças;
• consulta de pagamentos;
• conciliação;
• retorno bancário;
• baixa de títulos;
• status de boletos;
• arquivos ou APIs bancárias.

Integração com BI

Pode envolver:

• dados de faturamento;
• contas a pagar;
• contas a receber;
• estoque;
• compras;
• margem;
• clientes;
• fornecedores;
• indicadores gerenciais.

Integração com WMS e TMS

Pode envolver:

• separação;
• expedição;
• estoque;
• movimentações;
• transportadoras;
• status de entrega;
• devoluções.

Integração com sistemas fiscais

Pode envolver:

• documentos eletrônicos;
• validações fiscais;
• apuração;
• obrigações acessórias;
• conferência de notas;
• integração com TSS ou ferramentas externas.

Como testar um serviço REST no Protheus

Depois de criar o serviço, é necessário testar antes de liberar para produção.

Ferramentas como Postman, Insomnia ou cURL podem ser usadas para enviar requisições e validar respostas.

Exemplo de teste com cURL:

curl -X GET “http://localhost:8080/rest/helloworld” \

     -H “Accept: application/json”

Teste sempre:

• endpoint correto;
• método HTTP correto;
• autenticação;
• headers;
• parâmetros obrigatórios;
• body da requisição;
• resposta de sucesso;
• resposta de erro;
• permissões;
• cenários de exceção;
• logs;
• performance;
• timeout.

Também é importante testar com dados reais ou próximos da realidade, especialmente em integrações com pedidos, clientes, estoque, financeiro e fiscal.

Checklist de homologação de API REST no Protheus

Antes de publicar a API em produção, valide:

Pergunta	Status
O objetivo da API está documentado?	A definir
O endpoint segue padrão claro de nomenclatura?	A definir
O método HTTP está correto para a operação?	A definir
O payload JSON foi documentado?	A definir
A resposta da API segue padrão definido?	A definir
Os erros foram tratados com mensagens claras?	A definir
Existe autenticação obrigatória?	A definir
Existe autorização por usuário, rotina ou escopo?	A definir
O serviço usa HTTPS em produção?	A definir
Há controle de IPs ou origens autorizadas?	A definir
Logs foram configurados sem expor dados sensíveis?	A definir
A API foi testada em homologação?	A definir
Integrações externas foram testadas?	A definir
Há plano de rollback ou contingência?	A definir
Existe responsável técnico e funcional pela API?	A definir
A documentação foi entregue aos consumidores da API?	A definir

Documentação da API: por que ela é indispensável?

Toda API precisa de documentação clara.

A documentação deve permitir que outro desenvolvedor entenda como consumir o serviço sem depender de conversas informais.

Documente:

• objetivo da API;
• URL base;
• endpoints;
• métodos HTTP;
• parâmetros;
• headers;
• autenticação;
• exemplo de request;
• exemplo de response;
• erros possíveis;
• regras de negócio;
• limites de uso;
• contatos de suporte;
• versão da API;
• histórico de mudanças.

Quando possível, organize a documentação em formato compatível com OpenAPI ou Swagger. Isso facilita manutenção, testes, versionamento e integração com times externos.

Versionamento de APIs no Protheus

À medida que uma API evolui, mudanças podem impactar sistemas consumidores.

Por isso, é importante versionar endpoints.

Exemplo:

/rest/v1/clientes

/rest/v2/clientes

O versionamento ajuda a evitar que uma mudança quebre integrações existentes.

Boas práticas:

• evitar alterações incompatíveis sem aviso;
• documentar mudanças;
• manter versões antigas por período de transição;
• comunicar consumidores da API;
• criar política de descontinuação;
• registrar responsáveis por cada integração.

Esse cuidado é especialmente importante em APIs consumidas por e-commerce, bancos, BI, marketplaces ou sistemas de operação crítica.

Monitoramento e logs da API

Depois que a API entra em produção, a empresa precisa monitorar seu comportamento.

Acompanhe:

• volume de requisições;
• tempo médio de resposta;
• erros por endpoint;
• falhas de autenticação;
• consumo por sistema integrado;
• indisponibilidade;
• timeouts;
• lentidão;
• reprocessamentos;
• mensagens de erro;
• logs de auditoria.

Logs são importantes para rastreabilidade, mas devem ser configurados com cuidado para não expor dados sensíveis, tokens, senhas ou informações pessoais desnecessárias.

Erros comuns ao criar serviço REST no Protheus

Alguns erros podem comprometer a integração:

• publicar endpoint sem autenticação;
• testar apenas cenário de sucesso;
• não validar permissões por usuário;
• retornar dados sensíveis em excesso;
• não tratar erros corretamente;
• não documentar payloads;
• expor API em HTTP sem SSL;
• não controlar IPs autorizados;
• criar endpoints com nomes confusos;
• não versionar APIs críticas;
• não testar customizações após atualização;
• não monitorar logs;
• deixar credenciais fixas no código;
• não definir responsável pela API;
• publicar direto em produção sem homologação.

Evitar esses erros reduz riscos técnicos, operacionais e de segurança.

Como a Global GCS apoia integrações REST no Protheus

A Global GCS apoia empresas em projetos de implantação, suporte, customização, atualização e integração do TOTVS Protheus.

Em projetos com APIs REST, o apoio pode envolver:

• diagnóstico da necessidade de integração;
• definição da arquitetura;
• configuração do ambiente REST;
• desenvolvimento ADVPL;
• criação de endpoints;
• consumo de APIs externas com FWRest;
• testes em homologação;
• validação de segurança;
• documentação técnica;
• integração com e-commerce, BI, bancos, CRM, WMS, TMS e sistemas fiscais;
• suporte ao go-live;
• monitoramento e sustentação.

O objetivo é garantir que a integração não seja apenas funcional, mas também segura, documentada, escalável e aderente aos processos da empresa.

Perguntas frequentes sobre serviço REST Protheus

O que é um serviço REST no Protheus?

É uma API criada no TOTVS Protheus para permitir comunicação entre o ERP e outros sistemas por meio de requisições HTTP, usando métodos como GET, POST, PUT e DELETE.

Para que serve uma API REST no Protheus?

Ela serve para integrar o Protheus com sistemas externos, como e-commerce, bancos, BI, CRM, WMS, TMS, marketplaces, sistemas fiscais e aplicações internas.

Qual classe é usada para criar serviço REST no Protheus?

A estrutura WSRESTFUL é usada para criar e declarar serviços REST no Protheus em ADVPL.

Qual classe pode ser usada para consumir APIs externas no Protheus?

A classe FWRest pode ser usada para consumir APIs externas a partir do Protheus, enviando requisições HTTP e processando respostas.

Preciso reiniciar o AppServer após publicar um serviço REST?

Sim, após compilar o fonte, geralmente é necessário reiniciar o AppServer para que o serviço seja publicado corretamente na lista de APIs.

Posso publicar uma API REST Protheus sem autenticação?

Não é recomendado. APIs devem exigir autenticação e autorização, principalmente quando trafegam dados operacionais, fiscais, financeiros ou pessoais.

O Protheus permite usar HTTPS em APIs REST?

Sim, é possível estruturar o serviço REST com HTTPS/SSL conforme a configuração do ambiente e boas práticas de segurança.

Como testar uma API REST no Protheus?

É possível testar com ferramentas como Postman, Insomnia ou cURL, validando método HTTP, endpoint, headers, autenticação, payload, retorno, erros e logs.

APIs REST no Protheus precisam de documentação?

Sim. A documentação é essencial para manutenção, testes, integração com terceiros, versionamento e suporte.

Quando contratar apoio especializado para API REST Protheus?

Quando a integração envolve operação crítica, dados sensíveis, segurança, autenticação, fiscal, financeiro, e-commerce, bancos, BI, WMS, TMS ou sistemas legados, o apoio especializado reduz riscos e melhora a estabilidade do projeto.

Criar um serviço REST no TOTVS Protheus é uma estratégia importante para integrar o ERP com sistemas externos, automatizar processos e melhorar a troca de dados entre áreas e plataformas.

No entanto, uma API REST no Protheus precisa ser planejada com cuidado. Não basta criar um endpoint e testar uma chamada simples. É necessário configurar o AppServer, desenvolver com WSRESTFUL, validar métodos HTTP, tratar JSON, controlar autenticação, aplicar segurança, testar em homologação, documentar o serviço e monitorar o uso em produção.

Também é importante lembrar que integrações fazem parte da operação da empresa. Uma falha em API pode afetar pedidos, estoque, notas fiscais, financeiro, BI, logística e atendimento ao cliente.

Por isso, a criação de APIs REST no Protheus deve combinar desenvolvimento técnico, visão de negócio, segurança e governança.

 Precisa criar, revisar ou integrar APIs REST no Protheus? Conte com a Global GCS para estruturar serviços REST seguros, documentados e conectados aos processos da sua empresa, com apoio técnico para desenvolvimento, homologação, integração e sustentação. Entre em contato.