Índice do artigofaltam 5 min de leitura
No Protheus, dizer que "tem API" resolve menos do que parece. Existe o servidor REST estar ligado, existe o modelo estar publicado, e existe o campo estar dentro do modelo. São três perguntas diferentes, com três responsáveis diferentes.
Nos projetos que a X-Apps executa, o TOTVS Protheus é o sistema de gestão que mais aparece do outro lado da mesa quando uma empresa de médio ou grande porte decide construir um aplicativo, um portal do cliente ou um e-commerce próprio. E é onde o cronograma mais derrapa, quase sempre pelo mesmo motivo: a estimativa foi feita como se o acesso ao dado fosse um problema de programação.
Este artigo é para quem vai estimar, contratar ou executar uma integração dessas. Ele descreve de onde o dado pode sair, o que precisa estar ligado do outro lado e quais perguntas precisam ser respondidas antes de qualquer data ser prometida.
Resumo do artigo
- Existem três caminhos para tirar dado do Protheus, e a escolha determina quem depende de quem pelo resto do projeto.
- O servidor REST do Protheus depende de configuração no
appserver.ini. Sem ela, não há endpoint, por mais que a documentação do produto descreva o recurso. - O defeito mais comum não é erro de conexão: é campo que existe no ERP e não faz parte do recurso publicado.
- Protheus e Fluig são produtos separados. Acesso a um não implica acesso ao outro, e isso são duas dependências no cronograma, não uma.
"Ter API" no Protheus são três perguntas, não uma
A frase que trava projetos é "o cliente confirmou que o Protheus tem API". Ela mistura três condições que precisam ser verificadas separadamente, porque cada uma tem um responsável distinto e um prazo distinto.
A primeira é se o serviço REST está ativo naquele ambiente. A segunda é se existe um recurso publicado que corresponda ao dado desejado. A terceira é se os campos que o produto precisa estão dentro desse recurso. É perfeitamente possível ter as duas primeiras e falhar na terceira, e é exatamente esse o caso mais frequente.
Em termos de negócio: cada uma dessas três condições, quando ausente, é resolvida por uma pessoa diferente, e nenhuma delas costuma estar na equipe que constrói o aplicativo. Por isso a estimativa honesta de uma integração com Protheus tem sempre a forma "X semanas de trabalho, depois que A, B e C estiverem liberados".
Os três caminhos para tirar o dado
Modelo publicado. O framework do Protheus permite publicar modelos de dados como recurso REST, e o endereço segue um padrão previsível, na forma <protocolo>://<servidor>:<porta>/fwmodel/<nome do modelo publicado>/<PK>. A publicação é declarada no código, com a instrução PUBLISH MODEL REST NAME <nome> SOURCE <fonte> RESOURCE OBJECT <objeto>. É o caminho mais alinhado ao produto e o que menos quebra em atualização.
REST customizado. A classe FWRest permite escrever rotas sob medida em ADVPL, tanto para publicar quanto para consumir serviços externos. É o caminho quando a regra de negócio é específica demais para o modelo padrão, e o que mais depende de quem domina o ambiente do cliente.
Base de dados direta. Ler as tabelas sem passar pelo framework é o caminho mais rápido de todos e o mais caro no ano seguinte. Você passa a depender do formato interno das tabelas, que não é contrato público, e a relação de suporte com o fornecedor do ERP muda de figura.
O que isso destrava: escolher entre os três não é preferência técnica, é decidir de quem o seu cronograma vai depender pelos próximos anos. O primeiro caminho depende do fornecedor para cada campo novo e é estável. O terceiro não depende de ninguém para começar e quebra sozinho em toda atualização de versão.
O servidor REST precisa estar ligado, e isso é configuração de ambiente
Antes de qualquer endpoint responder, o serviço REST precisa estar habilitado no ambiente. Essa configuração vive no appserver.ini e envolve, entre outras chaves, HTTPJOB para inicializar o serviço, HTTPREST para a configuração de sockets e autenticação, HTTPV11 para habilitar o servidor REST e HTTPURI para controlar a URL base em que os serviços ficam disponíveis.
Isso não é detalhe de implementação para quem estima projeto: é um item que costuma estar sob responsabilidade da infraestrutura do cliente ou do parceiro TOTVS que mantém o ambiente, e não da equipe do aplicativo.
O campo que falta é o problema mais comum
Esse é o defeito que mais aparece nos nossos projetos e o menos previsto nas propostas. O dado está no ERP, a operação vê o dado na tela do Protheus todos os dias, e ele simplesmente não vem na resposta da API.
Num aplicativo de atendimento de uma rede de pneus, a consulta por CPF não retornava clientes que estavam cadastrados no Protheus. No mesmo projeto, veículos com placa no padrão Mercosul não eram localizados. Nenhum dos dois era falha de conexão.
E, quando o produto precisou também de DDD e data de nascimento, quem alterou a API para incluir esses campos foi quem mantinha o ERP, não a equipe do app.
A consequência prática é uma só, e ela vale para qualquer projeto com Protheus: a lista de campos precisa ser conferida contra uma resposta real da API antes de o cronograma ser fechado, não contra a documentação e não contra a tela do sistema. Uma chamada de teste na primeira semana evita uma renegociação de prazo no segundo mês.
- Peça uma chamada real, no ambiente de homologação, para o recurso que o produto vai consumir.
- Compare a resposta com a lista de campos do contrato de dados, campo a campo, e não por amostragem.
- Teste os casos de borda do seu negócio: formato novo de documento, registro antigo, cadastro incompleto, acentuação.
- Registre quem publica campo novo, com nome e canal de acionamento, antes de assinar o cronograma.
Homologação costuma chegar depois do combinado
O acesso ao ambiente de testes é a dependência que mais atrasa integração com ERP, e ela raramente é técnica.
Quando o Protheus está hospedado na nuvem da TOTVS, a liberação de usuário, de permissão e de porta passa por um fluxo de chamado do lado do fornecedor. Em uma operação de logística frigorificada, o time chegou a autenticar no Protheus e continuou bloqueado no Fluig, que pedia um arquivo de licença próprio. São dois produtos, duas liberações, dois prazos.
Vale tratar isso como se trata qualquer insumo de projeto: com data prevista, responsável nomeado e um plano para o caso de o acesso não sair a tempo. Trabalhar contra uma base de exemplo enquanto a liberação não chega costuma ser melhor do que parar a equipe.
Protheus e Fluig resolvem coisas diferentes
Vale a distinção, porque a confusão gera escopo mal dimensionado. O Protheus é onde estão os dados de gestão: cadastro, estoque, financeiro, faturamento. O Fluig é a camada de processos e documentos, onde vivem fluxos de aprovação e formulários.
Um projeto que precisa consultar saldo de cliente fala com o Protheus. Um projeto que precisa disparar e acompanhar uma aprovação interna fala com o Fluig. Um projeto que precisa dos dois tem duas integrações, duas credenciais e duas dependências de liberação, e o orçamento precisa dizer isso explicitamente.
As perguntas para levar à primeira reunião técnica
Esta é a lista que muda a qualidade de uma estimativa. Ela cabe em uma reunião de uma hora com quem mantém o ERP, e responde quase tudo que decide prazo.
- O serviço REST está habilitado em homologação e em produção, com as mesmas configurações?
- Quais recursos já estão publicados hoje, e podemos ver uma resposta real de cada um?
- Quem publica um campo novo, por qual canal, e qual foi o prazo da última vez que isso aconteceu?
- O ambiente é local ou está na nuvem da TOTVS, e quem abre chamado de liberação de acesso?
- Existe alguma customização no ambiente que altere o comportamento padrão dos recursos?
A última pergunta é a que costuma render a resposta mais reveladora. Ambiente Protheus de empresa com anos de operação quase sempre tem customização, e customização é a diferença entre a documentação do produto e o que aquele servidor específico faz.
Precisa integrar o Protheus a um app, portal ou e-commerce?
Solicite um orçamento e comece pela conferência de campos, antes de o cronograma estar comprometido.
Perguntas frequentes
Sim. O framework do Protheus oferece publicação REST de modelos de dados e a classe FWRest para consumo e publicação customizados em ADVPL. O que varia de empresa para empresa é se o serviço está ligado no ambiente e quais modelos foram efetivamente publicados.
Porque o campo precisa fazer parte do recurso publicado. Estar preenchido na tela do ERP não significa estar exposto na API. Incluir um campo novo costuma exigir alteração do lado do Protheus, feita por quem mantém o ERP.
Tecnicamente costuma ser possível e é o caminho mais rápido no curto prazo. O custo aparece na atualização de versão, quando o formato interno muda sem aviso, e na relação de suporte com o fornecedor do ERP.
Muda principalmente a governança de acesso. A liberação de usuário, de permissão e de porta passa a depender de chamado junto à TOTVS, e isso entra no cronograma do projeto como dependência externa com prazo próprio.
Não. São produtos distintos, com autenticação e liberação próprias. É comum uma equipe conseguir autenticar no Protheus e continuar bloqueada no Fluig, o que precisa ser tratado como duas dependências separadas no plano do projeto.
Depende menos da complexidade técnica e mais de duas dependências externas: o tempo de liberação do ambiente de homologação e o tempo de quem mantém o ERP para publicar qualquer campo que falte. Prazo prometido sem essas duas respostas é chute.
Fontes e método
As referências ao framework do Protheus vêm da documentação oficial da TOTVS, consultada em 31 de agosto de 2026: a página do FWRestModel na TOTVS Developer Network, que descreve a publicação de modelos e o padrão de endereço dos recursos, e o material de configuração básica REST da Central de Atendimento TOTVS, que descreve as chaves de appserver.ini.
Os casos citados vêm de integrações executadas pelo time da X-Apps entre 2023 e 2026 e foram despersonalizados, já que a relação entre esses clientes e o sistema não é pública. Preços, limites de chamada e níveis de serviço da TOTVS não foram apurados e por isso não aparecem no texto.
