API REST no Protheus: configuração, autenticação e erros
Configurar REST no Protheus exige quatro frentes: habilitar o serviço no AppServer, definir a URI e o ambiente atendido, ativar autenticação e publicar ou consumir os endpoints com o padrão correto. Quando uma dessas camadas está incoerente, o erro pode aparecer como 401, 403, 404, timeout, falha de tenant ou indisponibilidade do serviço.
O primeiro diagnóstico deve separar problema de infraestrutura de problema de código. Antes de alterar ADVPL, confirme se o serviço REST subiu, se a URL base está correta, se a requisição leva os headers exigidos e se empresa/filial estão sendo resolvidas conforme a configuração do ambiente. Só depois avance para payload, regra de negócio e tratamento do método.
Para decisões mais amplas de arquitetura e integração do ERP, consulte também a página de TOTVS Protheus.
Como configurar REST no Protheus?
A configuração REST do Protheus é feita no AppServer e precisa definir serviço HTTP, porta, URI e ambiente atendido. Nos exemplos oficiais aparecem as seções HTTPV11, HTTPREST e uma URI vinculada. No REST ADVPL tradicional, a inicialização também depende do job HTTP_START, normalmente acionado por ONSTART. Porta, PrepareIn, Instances, CORS, autenticação e forma de inicialização variam conforme a arquitetura e não devem ser copiadas de outro ambiente sem validação.
- Habilite o HTTP REST na seção HTTPV11 e vincule o socket do serviço.
- Defina porta, URI e segurança na seção HTTPREST.
- Defina a URL base e a preparação do ambiente na seção da URI.
- Ajuste a quantidade de instâncias/working threads conforme o volume e a capacidade do servidor.
- Valide autenticação, certificado e regras de rede antes de expor o endpoint.
- Reinicie o AppServer e confirme no log que o serviço REST foi iniciado.
Exemplo de estrutura, apenas como referência:
| [HTTPV11]Enable=1Sockets=HTTPREST [HTTPREST]Port=8084URIs=HTTPURISECURITY=1 [HTTPURI]URL=/restPrepareIn=ALLInstances=2,2CORSEnable=1AllowOrigin=* No REST ADVPL tradicional, a TOTVS também documenta a inicialização por job:[ONSTART]Jobs=HTTPJOBRefreshRate=30 [HTTPJOB]MAIN=HTTP_STARTENVIRONMENT=environment Esse bloco não deve ser aplicado automaticamente a qualquer ambiente. Antes, confirme se o servidor está executando REST ADVPL tradicional ou REST 2.0 e adapte o nome do ambiente às configurações reais do AppServer. |
Atenção: os valores acima não são uma receita de produção. PrepareIn pode ser específico por grupo/filial, o uso de ALL depende do cenário, Instances afeta o consumo de recursos e AllowOrigin deve ser restringido quando a integração não precisa aceitar qualquer origem.
Como saber se o ambiente usa REST ADVPL ou REST 2.0?
A TOTVS documenta o REST 2.0 como uma evolução do REST ADVPL e mantém compatibilidade com APIs em WSRESTFUL. A diferença importa porque autenticação, preparação de ambiente e recursos disponíveis mudam.
A documentação da TOTVS indica que o REST ADVPL tradicional é iniciado por HTTP_START; em ambientes atuais também é possível desenvolver endpoints REST em TLPP por annotations, conforme o release utilizado.
- REST ADVPL: modelo tradicional, habilitado no appserver.ini e iniciado pelo job HTTP_START.
- REST 2.0: arquitetura atualizada, com suporte a APIs ADVPL em WSRESTFUL e APIs TLPP por annotations.
- tlppCore REST agnóstico: não deve ser confundido com o REST 2.0 ligado ao ambiente Protheus.
Para o diagnóstico, não presuma a arquitetura pelo código do endpoint. A TOTVS recomenda observar a mensagem exibida no console durante a inicialização. Quando isso não for possível, uma requisição simples também ajuda: no REST ADVPL tradicional é enviado o cabeçalho FWRESTBUILD; a ausência desse header indica o serviço REST atualizado. O endpoint /healthcheck pode ser usado como teste simples quando estiver disponível no ambiente. Depois, confirme a documentação correspondente ao release em uso.
Como funciona a autenticação da API REST no Protheus?
SECURITY=1 explicita a exigência de autenticação. A TOTVS informa que, desde a LIB Label 20201019, quando a chave SECURITY não é informada o comportamento padrão também é exigir autenticação; SECURITY=0 é que desabilita essa exigência.
No ambiente Protheus, a autenticação usa usuários cadastrados no ERP e pode ocorrer por Basic Auth ou por Bearer token/JWT. O método efetivo depende do endpoint, do modelo REST e da configuração do ambiente.
No Basic Auth, o header segue o padrão:
| Authorization: Basic <credenciais_em_base64>A credencial em Base64 não substitui criptografia. Em produção, a autenticação deve trafegar em HTTPS/TLS, com certificado válido, credenciais fora do código-fonte e permissões limitadas ao que a integração realmente precisa.Muitas APIs do Protheus exigem contexto de empresa e filial por tenantId, mas isso não é universal. A própria TOTVS documenta serviços classificados como NOTENANT, como a API /users, que autentica o usuário sem validar empresa e filial. Portanto, não generalize a exigência de tenantId: confirme a documentação do endpoint específico. Um 401 ou 403 também não deve ser tratado automaticamente como falha de tenant. |
Como criar um endpoint REST com WSRESTFUL?
Em ADVPL, uma API pode ser declarada com WSRESTFUL e métodos GET, POST, PUT e DELETE. A classe define o recurso e os caminhos; cada WSMETHOD implementa a operação. A própria documentação da TOTVS recomenda reiniciar o Application Server quando uma nova classe REST é compilada depois que o HTTP_START já foi iniciado.
Exemplo mínimo:
| #INCLUDE “TOTVS.CH”#INCLUDE “RESTFUL.CH” WSRESTFUL sample DESCRIPTION “Exemplo de serviço REST” WSMETHOD GET all DESCRIPTION “Retorna status” PATH “/sample”END WSRESTFUL WSMETHOD GET all WSSERVICE sample ::SetContentType(“application/json”) ::SetResponse(‘{“status”:”ok”}’)Return .T. |
O exemplo mostra a estrutura, não uma API pronta para produção. Na implementação real, valide parâmetros, autorização, empresa/filial, regras de negócio, serialização do JSON e retorno de erros com código HTTP coerente.
Se o endpoint fizer parte de uma implantação ou mudança maior do ambiente, alinhe o desenho com o escopo de implantação do Protheus para evitar que a integração seja tratada como uma customização isolada.
Como consumir APIs externas no Protheus com FWRest?
A classe FWRest é o cliente REST padrão do Framework Protheus para consumo de APIs externas. Ela permite definir host e path, enviar headers, executar GET, POST, PUT e DELETE e consultar o resultado ou o último erro. Para POST, a documentação prevê SetPostParams para informar o corpo da requisição antes do envio.
O FWRest suporta PATCH?
Não nativamente. Em documentação oficial atualizada em abril de 2026, a TOTVS orienta usar HTTPQuote ou HTTPSQuote quando o método HTTP precisa ser informado explicitamente, incluindo PATCH. HTTPGet/HTTPSGet e HTTPPost/HTTPSPost também existem para cenários específicos de GET e POST. A escolha deve considerar o verbo exigido, HTTPS e a política de certificados do ambiente.
Exemplo simplificado de GET:
| Local oRest := FWRest():New(“https://api.exemplo.com”)Local aHeader := {“Accept: application/json”} oRest:SetPath(“/v1/clientes”) If oRest:Get(aHeader) ConOut(oRest:GetResult())Else ConOut(oRest:GetLastError())EndIf |
Exemplo simplificado de POST:
| Local oRest := FWRest():New(“https://api.exemplo.com”)Local aHeader := {“Content-Type: application/json”, “Accept: application/json”}Local cJson := ‘{“codigo”:”000001″}’ oRest:SetPath(“/v1/clientes”)oRest:SetPostParams(cJson) If oRest:Post(aHeader) ConOut(oRest:GetResult())Else ConOut(oRest:GetLastError())EndIf |
Antes de integrar, documente URL base, método, autenticação, headers, payload, retorno, timeout, política de reprocessamento e responsável pela API externa. Uma chamada que funciona no teste manual ainda pode falhar em produção por expiração de token, indisponibilidade, rate limit, timeout ou mudança de contrato.
Como diagnosticar erros REST no Protheus?
O diagnóstico deve seguir a camada em que a falha acontece. Comece pelo AppServer e pela URL base; depois valide autenticação e tenant; só então verifique método, path, headers, JSON e regra de negócio. Essa ordem evita alterar código quando o problema real é serviço não iniciado, porta incorreta, usuário sem acesso ou contexto de empresa/filial.
| Tipo | Sintoma / Código HTTP | Causa provável | O que validar primeiro |
| Conectividade | Sem conexão / Timeout | Porta incorreta, firewall, serviço REST indisponível, problema de certificado ou tempo limite excedido | Log do AppServer, porta configurada, URL base, conectividade de rede e TLS |
| Autenticação | 401 Unauthorized | Header de autenticação ausente ou inválido, ou credencial rejeitada | SECURITY, header Authorization, usuário e método Basic/Bearer |
| Autorização | 403 Forbidden | Usuário autenticado, mas sem permissão suficiente para executar a operação | Permissões do usuário, empresa/filial e escopo do endpoint |
| Rota / publicação | 404 Not Found | URI ou PATH incorreto, ou serviço ainda não publicado | URL base, nome do serviço, PATH e necessidade de reinício do AppServer |
| Método HTTP | 405 Method Not Allowed | Verbo HTTP diferente daquele declarado no WSMETHOD | Conferir se o endpoint aceita GET, POST, PUT ou DELETE |
| Requisição | 400 Bad Request / Payload inválido | Parâmetro obrigatório ausente, JSON inválido ou query string incorreta | Content-Type, campos obrigatórios, tipos de dados e corpo enviado |
| Regra de negócio | 422 Unprocessable Entity | Requisição tecnicamente válida, mas rejeitada pela lógica do processo | Validações funcionais e mensagem devolvida pelo serviço |
| Aplicação | 500 Internal Server Error | Exceção no método, acesso a dados ou falha em customização | Log, stack do erro, ponto exato do método e dados recebidos |
Sequência prática de diagnóstico:
- Confirme que o AppServer REST iniciou sem erro e está ouvindo na porta prevista.
- Teste a URL base e, quando disponível no ambiente, um endpoint simples de saúde/consulta de serviços.
- Valide SECURITY e o modelo de autenticação configurado.
- Confira usuário, senha/token e tenantId ou contexto de empresa/filial.
- Compare o método HTTP e o PATH com a declaração da API.
- Confira headers, Content-Type, parâmetros e JSON enviado.
- Leia o log do AppServer e a mensagem devolvida pelo endpoint antes de alterar o fonte.
- Reproduza em homologação com o mesmo payload e registre request, response e horário do teste.
- Se o problema envolver disponibilidade, logs ou sustentação contínua do ambiente, use também o material de suporte Protheus como referência operacional.
Quais cuidados de segurança aplicar em APIs REST do Protheus?
Uma API REST do Protheus pode acessar dados financeiros, fiscais, comerciais e pessoais, portanto o padrão seguro é autenticar, criptografar e limitar acesso. SECURITY=0 deixa a integração sem exigência de autenticação e não deve ser adotado em produção sem uma justificativa arquitetural formal e controles compensatórios.
- Use HTTPS/TLS em produção e mantenha certificados válidos e atualizados.
- Não grave usuário, senha, token ou chave diretamente no fonte.
- Conceda ao usuário de integração apenas as permissões necessárias.
- Restrinja CORS/origens quando o cenário não exigir acesso amplo.
- Evite retornar campos que o consumidor não precisa.
- Registre logs técnicos sem expor credenciais ou dados sensíveis.
- Separe homologação e produção e teste falhas, não apenas respostas 200.
- Documente quem consome o endpoint, para qual processo e com qual versão do contrato.
Antes de publicar mudanças em produção, verifique se o ambiente está no release esperado e consulte o histórico de atualizações do Protheus.
Checklist para homologar uma API REST no Protheus
A homologação deve comprovar infraestrutura, segurança, contrato da API e comportamento funcional. O endpoint só deve ir para produção quando os cenários de sucesso e de falha estiverem documentados, com evidência de autenticação, permissões, payloads, retornos e logs.
Serviço REST inicia sem erro no AppServer.
URL base, porta e PATH estão documentados.
Métodos HTTP correspondem ao que foi declarado.
SECURITY e autenticação foram validados.
Empresa/filial ou tenant foram testados no cenário correto.
Headers e Content-Type estão documentados.
Payload de entrada e resposta de saída têm exemplos reais.
401, 403, 404 e erro funcional foram testados.
Timeout e indisponibilidade externa têm tratamento definido.
Logs permitem localizar a requisição sem expor segredo.
Versão do endpoint e impacto em consumidores estão registrados.
Há responsável técnico e funcional pela integração.
Perguntas frequentes sobre REST no Protheus
É preciso reiniciar o AppServer depois de publicar uma nova classe REST?
Quando uma nova classe REST é compilada depois que o HTTP_START já foi iniciado, a documentação da TOTVS orienta reiniciar o Application Server para que o serviço seja publicado.
SECURITY=1 é suficiente para proteger a API?
Não. SECURITY=1 habilita autenticação, mas produção também exige transporte seguro por HTTPS/TLS, usuário com permissão adequada, proteção de credenciais, controle de origem/rede e validação de autorização em cada operação.
Basic Auth e Bearer podem ser usados no Protheus?
A documentação do REST 2.0 descreve autenticação Basic ou Bearer baseada nos usuários do Protheus. O método disponível depende da arquitetura, do endpoint e do release, por isso deve ser confirmado no ambiente antes da implementação.
Sempre é obrigatório enviar tenantId?
Não em todos os casos. Em APIs ligadas ao ambiente Protheus, empresa e filial fazem parte do contexto. Porém, métodos declarados com NOTENANT podem autenticar o usuário sem validar tenant. Confirme a regra do endpoint específico.
Como diferenciar erro de FWRest de erro da API externa?
Use GetLastError para identificar falha na chamada e GetResult para ler o conteúdo retornado quando a requisição for atendida. Registre também status, URL, horário, headers não sensíveis e payload de teste para separar conexão, autenticação e regra de negócio.
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.
