Webhooks de integração

A loja conversa com sistemas externos: o ERP (sistema de gestão da empresa, como Omie, Bling ou Totvs), os marketplaces (Mercado Livre, Shopee e similares) e canais de venda de terceiros. Esses sistemas precisam avisar a loja quando algo muda do lado deles (um pedido novo, um estoque alterado, uma nota emitida). Para isso a loja expõe rotas públicas de webhook: o sistema externo faz um POST na rota, a loja confere quem chamou e processa o aviso.

Esta seção documenta as rotas que o sistema externo chama. Quem integra pelo lado da loja normalmente não as usa: o administrador cadastra a conexão no painel, copia a URL do webhook e a cola no ERP ou marketplace.

Como funciona

1. O administrador cria a conexão

   No painel, a conexão com o ERP (ou a conta do marketplace) recebe um token opaco. A URL do webhook é a rota desta seção com esse token no final.

2. O sistema externo é configurado

   A URL é cadastrada no ERP ou marketplace (à mão ou pelo botão de configuração automática do painel). Quando houver login OAuth, a URL de retorno também é cadastrada lá.

3. O aviso chega

   O sistema externo faz POST com o corpo em JSON. A loja confere o token e a assinatura, guarda o aviso e responde 200.

4. O aviso vira trabalho

   Em segundo plano a loja converte o aviso em tarefas de sincronização (puxar produto, preço, estoque, pedido ou nota).

Conceitos-chave

Token na URL e assinatura

O token identifica a conexão e só é conhecido por quem a configurou. A assinatura prova que o corpo veio mesmo do sistema externo; cada conector usa o seu cabeçalho e algoritmo, definidos pelo fornecedor. Trate o token como uma senha: quem o tem consegue enviar avisos à loja.

Resposta rápida

ERPs e marketplaces cancelam a entrega do webhook se a resposta demora. Por isso a loja só guarda o aviso e responde; o processamento pesado é feito depois. Um 200 significa "recebi", não "já apliquei".

Respostas em texto

Estas rotas respondem em texto puro (ok, invalid signature, 404 page not found), não em JSON. Só a rota de canais responde JSON.

Endpoints

Erros comuns

1. Usar a URL errada do Hub de ERPs. A rota real é /api/v1/storefront/erphub/.... O painel pode mostrar a base /api/v1/public/erphub/..., que não existe e responde 404 (veja Hub de ERPs).
2. Reenviar o corpo reformatado. A assinatura é calculada sobre os bytes exatos que o sistema externo enviou. Se um proxy reescreve o JSON, a conferência falha e a resposta é 401.
3. Mandar mais de 2 MB. O Hub de Marketplaces responde 413; o Hub de ERPs lê só os primeiros 2 MB, e um corpo cortado falha na assinatura.
4. Achar que 404 significa "rota inexistente". Com token errado, ERP errado ou conexão apagada a resposta também é 404, de propósito, para não revelar que a conexão existe.
5. Chamar o callback OAuth com curl. Ele espera o state assinado que a loja gerou ao iniciar o login; sem ele a resposta é 400.

Próximos passos