API atual/Referência completa/Webhooks de integração

Hub de ERPs

Recebe os avisos do ERP e fecha o login OAuth dos conectores que o usam.

O Hub de ERPs liga a loja ao sistema de gestão da empresa. Cada conexão (de um seller ou da própria loja) usa um conector específico (Omie, Bling, Totvs e outros). O ERP avisa a loja de mudanças em produtos, preços, clientes, crédito, pedidos, notas e estoque; a loja transforma cada aviso numa tarefa de sincronização.

Há duas rotas: o webhook (um servidor chama) e o retorno do OAuth (o navegador chama).

Receber um aviso

POST/api/v1/storefront/erphub/{erp}/webhook/{connToken}Pública

Recebe um aviso do ERP

Chamada pelo sistema externo, nunca pelo seu app. O corpo é o JSON que o fornecedor define para cada tipo de aviso; a loja não o interpreta aqui, só o guarda e o encaminha ao conector.

Parâmetros de caminho

erpstringobrigatório

Identificador do conector do ERP (o slug mostrado na conexão no painel).

connTokenstringobrigatório

Token opaco da conexão, gerado pela loja. Faz parte da URL do webhook que o painel mostra.

Cabeçalhos

Content-Typestring

Normalmente application/json. Um corpo que não seja JSON válido é guardado como texto bruto.

(assinatura)string

Cabeçalho de assinatura próprio de cada conector (definido pelo fornecedor). A loja o confere sobre o corpo exato antes de aceitar.

Corpo da requisição

(corpo)object

JSON do aviso, no formato do fornecedor. Até 2 MB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/erphub/omie/webhook/9f3c1a7e5b2d4c68a0e1f2b3c4d5e6f7" \
  -H "Content-Type: application/json" \
  -H "X-Signature: $SIGNATURE" \
  -d '{"event":"order.updated","id":"123456"}'

Resposta

200Aviso aceito

json

ok

O corpo da resposta é a palavra ok em texto puro, não JSON.

O aviso é guardado e a resposta 200 sai antes do processamento (que corre em segundo plano). Um corpo cuja assinatura falha é guardado como inválido, gera um evento de alerta e recebe 401.

Os avisos reconhecidos viram tarefas de: produto, preço, cliente, crédito, pedido (status), nota fiscal, estoque e renovação de token. Avisos de outro tipo são guardados e ignorados.

Alguns ERPs (como o Dynamics 365 Business Central) validam a URL ao criar a assinatura enviando ?validationToken=.... Nesse caso a loja responde 200 com o mesmo valor em texto puro, sem conferir assinatura.

Erros

Status	Quando	Corpo
200	Aviso aceito (corpo `ok`, texto puro). Também é o status do desafio `validationToken`, que devolve o valor recebido.	`ok`
400	Falha ao ler o corpo.	`read error`
401	Assinatura inválida.	`invalid signature`
404	ERP ou token desconhecido, ou conexão apagada.	`404 page not found`

GET/api/v1/storefront/erphub/oauth/callback/{erp}Pública

Fecha o login OAuth

É o endereço para o qual o fornecedor devolve o navegador do administrador depois que ele autoriza o acesso. Cadastre esta URL como "URL de redirecionamento" no aplicativo OAuth do fornecedor. A loja troca o code por credenciais, grava-as cifradas e redireciona o navegador de volta ao painel.

Parâmetros de caminho

erpstringobrigatório

Identificador do conector do ERP (o slug mostrado na conexão no painel).

Parâmetros de consulta

statestringobrigatório

Valor assinado que a loja criou ao iniciar o login. Identifica a conexão e vence com o tempo. Devolvido sem alteração pelo fornecedor.

codestringobrigatório

Código de autorização enviado pelo fornecedor.

(outros)string

Qualquer outro parâmetro que o fornecedor acrescente é repassado ao conector.

Exemplo de requisição

bash

curl -i "$BASE_URL/api/v1/storefront/erphub/oauth/callback/omie?code=AUTH_CODE&state=SIGNED_STATE"

Resposta

Em caso de sucesso a resposta não tem corpo útil: é um redirecionamento 302 para O painel do administrador: /admin/erp-hub/connections/{id}?connected=1.

Erros

Status	Quando	Corpo
302	Login concluído: redireciona para o painel da conexão.	`Location: /admin/erp-hub/connections/{id}?connected=1`
400	`state` inválido ou vencido, ERP diferente do `state`, conector sem OAuth ou troca do código recusada.	`oauth error: erphub: bad state format`

Veja também

API atual/Referência completa/Webhooks de integração

Hub de ERPs

Recebe os avisos do ERP e fecha o login OAuth dos conectores que o usam.

Há duas rotas: o webhook (um servidor chama) e o retorno do OAuth (o navegador chama).

Receber um aviso

POST/api/v1/storefront/erphub/{erp}/webhook/{connToken}Pública

Recebe um aviso do ERP

Chamada pelo sistema externo, nunca pelo seu app. O corpo é o JSON que o fornecedor define para cada tipo de aviso; a loja não o interpreta aqui, só o guarda e o encaminha ao conector.

Parâmetros de caminho

erpstringobrigatório

Identificador do conector do ERP (o slug mostrado na conexão no painel).

connTokenstringobrigatório

Token opaco da conexão, gerado pela loja. Faz parte da URL do webhook que o painel mostra.

Cabeçalhos

Content-Typestring

Normalmente application/json. Um corpo que não seja JSON válido é guardado como texto bruto.

(assinatura)string

Cabeçalho de assinatura próprio de cada conector (definido pelo fornecedor). A loja o confere sobre o corpo exato antes de aceitar.

Corpo da requisição

(corpo)object

JSON do aviso, no formato do fornecedor. Até 2 MB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/erphub/omie/webhook/9f3c1a7e5b2d4c68a0e1f2b3c4d5e6f7" \
  -H "Content-Type: application/json" \
  -H "X-Signature: $SIGNATURE" \
  -d '{"event":"order.updated","id":"123456"}'

Resposta

200Aviso aceito

json

ok

O corpo da resposta é a palavra ok em texto puro, não JSON.

O aviso é guardado e a resposta 200 sai antes do processamento (que corre em segundo plano). Um corpo cuja assinatura falha é guardado como inválido, gera um evento de alerta e recebe 401.

Os avisos reconhecidos viram tarefas de: produto, preço, cliente, crédito, pedido (status), nota fiscal, estoque e renovação de token. Avisos de outro tipo são guardados e ignorados.

Erros

Status	Quando	Corpo
200	Aviso aceito (corpo `ok`, texto puro). Também é o status do desafio `validationToken`, que devolve o valor recebido.	`ok`
400	Falha ao ler o corpo.	`read error`
401	Assinatura inválida.	`invalid signature`
404	ERP ou token desconhecido, ou conexão apagada.	`404 page not found`

GET/api/v1/storefront/erphub/oauth/callback/{erp}Pública

Fecha o login OAuth

Parâmetros de caminho

erpstringobrigatório

Identificador do conector do ERP (o slug mostrado na conexão no painel).

Parâmetros de consulta

statestringobrigatório

Valor assinado que a loja criou ao iniciar o login. Identifica a conexão e vence com o tempo. Devolvido sem alteração pelo fornecedor.

codestringobrigatório

Código de autorização enviado pelo fornecedor.

(outros)string

Qualquer outro parâmetro que o fornecedor acrescente é repassado ao conector.

Exemplo de requisição

bash

curl -i "$BASE_URL/api/v1/storefront/erphub/oauth/callback/omie?code=AUTH_CODE&state=SIGNED_STATE"

Resposta

Em caso de sucesso a resposta não tem corpo útil: é um redirecionamento 302 para O painel do administrador: /admin/erp-hub/connections/{id}?connected=1.

Erros

Status	Quando	Corpo
302	Login concluído: redireciona para o painel da conexão.	`Location: /admin/erp-hub/connections/{id}?connected=1`
400	`state` inválido ou vencido, ERP diferente do `state`, conector sem OAuth ou troca do código recusada.	`oauth error: erphub: bad state format`