📢 Documentação de Integração via Webhook – Mercos / Protheus
📌 Visão Geral
Este documento descreve o padrão de integração via Webhook utilizado para comunicação entre o Mercos e sistemas externos integrados ao Protheus, permitindo o envio automático de eventos e dados em tempo real de acordo com as disponibilidades Mercos.
Hoje os Webhooks disponiveveis sao Clientes e Pedidos.
O pacote do integrador ja contempla o as rotinas envolvidas para contrele do processo de integração via Webhook Mercos.
A integração utiliza chamadas HTTP(S) com payload em JSON, seguindo um endpoint REST padronizado.
🌐 URL do Webhook
URL Base de Exemplo
http://meuipexeterno.com:9432/rest/mercosv1/03/02/01/webhook
🧩 Estrutura da URL
| Posição | Valor Exemplo | Descrição |
|---|---|---|
/rest |
— | Prefixo padrão de serviços REST |
mercosv1 |
Endpoint Mercos | Identifica o endpoint de integração Mercos |
03 |
Grupo de Empresa | Código do Grupo de Empresa no Protheus |
02 |
Filial | Código da Filial Protheus onde a conta está cadastrada |
01 |
Código da Conta | Código da Conta do Integrador |
webhook |
Origem | Indica que a chamada é originada de um Webhook |
🔍 Exemplo com identificação semântica
/rest/{endpoint}/{grupoEmpresa}/{filial}/{codigoConta}/webhook
✅ Pré‑Requisitos de Configuração no Protheus
🔧 Configuração Obrigatória – API Pública (Sem Autenticação)
Para que o Webhook do Mercos consiga consumir o endpoint REST no Protheus, é obrigatório que a API esteja configurada como pública, ou seja, sem exigir autenticação (usuário/senha, JWT ou OAuth).
Essa configuração é realizada através da chave Public no arquivo AppServer.ini, conforme orientação oficial da TOTVS.
📌 Ambiente Compatível
- Produto: TOTVS Backoffice – Linha Protheus
- Tecnologia: ADVPL / REST
- Versão mínima: A partir da 12.1.2410 [centraldea....totvs.com]
🛠️ Configuração no AppServer.ini
É necessário declarar explicitamente as rotas REST que poderão ser acessadas sem autenticação através da chave Public.
📄 Exemplo de Configuração
✅ No exemplo acima, todas as rotas iniciadas por
/rest/mercosv1passam a ser públicas, incluindo o endpoint:/rest/mercosv1/03/02/01/webhook
Essa configuração permite que chamadas externas sejam realizadas sem retorno de HTTP 401 (Unauthorized), garantindo o recebimento dos eventos do webhook. [centraldea....totvs.com]
⚠️ Observações Importantes da TOTVS
- A TOTVS recomenda que APIs públicas sejam usadas somente quando estritamente necessário, devido a riscos de segurança. [centraldea....totvs.com]
- A exposição deve ser limitada apenas às rotas indispensáveis, nunca utilizando curingas que liberem todas as APIs REST.
- A validação de contexto (empresa, filial e conta) deve ser feita na lógica da API.
✅ Pré‑Requisitos de Configuração – Mercos (Webhooks)
🔔 Configuração do Webhook no Mercos
Para que o Mercos envie eventos automaticamente ao endpoint REST do Protheus, é necessário configurar o Webhook diretamente no painel do Mercos, conforme sua documentação oficial de Webhooks