Como integrar o Protheus com e-commerce e marketplace (Mercado Livre, Shopify, VTEX)
Por Cesar Ramalho (abre em nova aba), HSB Consultoria · Atualizado em
Para integrar o Protheus com Mercado Livre, Shopify ou VTEX pelo HyperSync, a plataforma ou um middleware de vocês faz um POST autenticado nos endpoints do Protheus, porque não há conector pronto por marca. O pedido entra pela MATA410, por ExecAuto, e estoque, produto, preço e status saem por consulta SQL, cada um num endpoint configurado sem fonte ADVPL. O Protheus não avisa sozinho quando um dado muda: quem chama é a loja ou o middleware.
- Uma rota para todos os endpoints: POST /api/v1/hypersync/execute.
- Autenticação pelo REST do próprio Protheus, com usuários autorizados por endpoint.
- Os campos vão com os nomes do Protheus, como C5_CLIENTE e B2_QATU: não há de-para.
Quem chama quem
Mercado Livre, Shopify e VTEX não são conectores do HyperSync: são exemplos de quem chama. Cada integração é um endpoint no Protheus, e o outro lado faz a chamada.
Loja ou marketplace
Mercado Livre, Shopify, VTEX. É onde o pedido nasce e onde o estoque e o preço precisam aparecer.
Quem faz o POST
A própria plataforma, quando ela consegue chamar uma API com token, ou um middleware de vocês. Ele pega o token no REST do Protheus, monta o corpo com os campos do Protheus e chama o endpoint.
Protheus com HyperSync
Recebe na rota única, confere se o usuário está na lista de autorizados do endpoint, executa a consulta ou a rotina e registra a execução na Auditoria.
O HyperSync não recebe webhook de outro sistema. Se a plataforma avisa por webhook que entrou um pedido, quem recebe esse aviso é o middleware, que então faz o POST no Protheus. Empresa e filial vão no header tenantId, e um usuário fora da lista de autorizados recebe 400 sem permissão.
Os casos típicos
Cada caso é um endpoint; o do cliente são dois, a consulta e a inclusão. Uma consulta pode juntar tabelas, como a SC5 com a SF2 no status do pedido.
Estoque: a loja consulta o saldo da SB2
A loja precisa do saldo por produto. No Protheus ele está na SB2, por armazém.
O endpoint
configuração- 1Direção
- Saída
- 2Tipo
- Query SQL
- 3Execução
- Síncrona
- 4Configuração
- O SELECT na SB2 com os campos que podem sair
- 5Autorização
- O usuário do Protheus que o middleware usa
- 6Sandbox
- Testa e gera o cURL e a collection do Postman
A consulta configurada:
SELECT B2_COD, B2_LOCAL, B2_QATU FROM %table:SB2% WHERE D_E_L_E_T_ = ' '
Qual saldo publicar, de qual armazém e descontando reserva ou não, é decisão de vocês, na consulta.
A chamada
middleware ou lojaPOST /api/v1/hypersync/execute
Authorization: Bearer <token do REST do Protheus>
tenantId: 99,01
{
"id": 43,
"data": {
"fields": ["B2_COD", "B2_LOCAL", "B2_QATU"],
"params": "B2_LOCAL = '01'",
"page": 1,
"pageSize": 100
}
}A resposta traz só os campos pedidos, em minúsculas:
{
"result": [
{ "b2_cod": "PA-00102", "b2_local": "01", "b2_qatu": 148 },
{ "b2_cod": "PA-00215", "b2_local": "01", "b2_qatu": 37 }
]
}O filtro em params vale quando o endpoint permite parâmetros. page e pageSize paginam; sem eles volta tudo o que a consulta trouxer. Produto e preço da SB1 seguem o mesmo formato, em outro endpoint.
Pedido: a loja grava pela MATA410
O pedido aprovado na loja vira pedido de venda no Protheus pela rotina automática padrão, com cabeçalho e itens na mesma chamada.
O endpoint
configuração- 1Direção
- Entrada
- 2Tipo
- ExecAuto
- 3Execução
- Síncrona, ou assíncrona se o volume pedir fila
- 4Configuração
- Rotina MATA410, só inclusão
- 5Autorização
- O usuário do Protheus que o middleware usa
- 6Sandbox
- Testa numa transação desfeita no fim e gera o cURL
- action 3 inclui, 4 altera e 5 exclui. O endpoint define quais operações são permitidas.
- function e action ficam fora de data; cabeçalho em data.cabec e itens em data.itens.
- Datas vão em AAAAMMDD.
- Se a rotina recusar, a resposta traz errorMessage com a mesma mensagem que o Protheus mostraria na tela.
A chamada
middleware ou lojaPOST /api/v1/hypersync/execute
Authorization: Bearer <token do REST do Protheus>
tenantId: 99,01
{
"id": 42,
"function": "MATA410",
"action": 3,
"data": {
"cabec": {
"C5_TIPO": "N",
"C5_CLIENTE": "000231",
"C5_LOJACLI": "01",
"C5_CONDPAG": "001"
},
"itens": [
{ "C6_PRODUTO": "PA-00102", "C6_QTDVEN": 2, "C6_PRCVEN": 899.9, "C6_TES": "501" }
]
}
}Gravou:
{
"successMessage": "Registro incluído via execauto com sucesso!"
}Em dia de pico: assíncrono
Configurado como assíncrono, o mesmo endpoint responde na hora com um protocolo e grava pela fila. O resultado sai na rota de resposta e fica na Auditoria; um ticket que não existe volta 404.
Para não ficar consultando, o Protheus pode chamar um webhook de vocês quando a execução termina, com POST, PUT ou PATCH: sempre, só no sucesso ou só no erro. O corpo é montado com dados da execução, como ticket, status, endpoint, empresa e filial, quem chamou, duração e retorno.
O passo a passo completo da gravação está no guia pedido de venda pela API com a MATA410.
// resposta do POST, na hora
{ "ticket": "3f6c1e9a-7b2d-4c58-9a41-0d2e8f5b6c17" }
// o resultado, depois
GET v1/hypersync/getresponse?ticket=3f6c1e9a-7b2d-4c58-9a41-0d2e8f5b6c17O Protheus não empurra o dado sozinho
O HyperSync não tem gatilho de alteração. Quando o saldo da SB2 ou o preço da SB1 muda, nada sai do Protheus por conta própria. Quem inicia é o outro lado, ou o Schedule do Protheus nas saídas para banco e arquivo.
A loja ou o middleware consulta de tempos em tempos
É o caminho mais simples para estoque, preço e status: uma chamada ao endpoint de consulta na frequência que fizer sentido, com filtro em params para trazer só o necessário. Cada chamada conta como uma requisição do plano.
O Schedule exporta para um banco ou arquivo
Os tipos Banco de Dados e Arquivo rodam pelo Schedule do Protheus e gravam o resultado de uma consulta num SQL Server, PostgreSQL ou Oracle, ou num CSV ou TXT no FTP. O middleware lê de lá.
Disparo no momento em que o dado muda
Continua sendo ADVPL, num ponto de entrada. O webhook do HyperSync é outra coisa: avisa que uma execução assíncrona terminou.
Os três tipos de saída estão no guia como levar dados do Protheus para o BI.
Perguntas frequentes
Existe conector pronto do HyperSync para Mercado Livre, Shopify ou VTEX?+
Preciso de um middleware entre a loja e o Protheus?+
O Protheus avisa a loja quando o estoque muda?+
O pedido de venda entra de forma síncrona ou assíncrona?+
Como evitar que o mesmo pedido entre duas vezes?+
Dá para testar a integração sem gravar pedido de verdade?+
Veja o endpoint de pedido ou de estoque ficar pronto para produção.
A demonstração monta o endpoint numa conversa, no visual do configurador. Nenhum Protheus real é acessado.