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

Hub de Marketplaces

Recebe os avisos dos marketplaces e fecha o login OAuth das contas.

O Hub de Marketplaces liga a loja a marketplaces como Mercado Livre e Shopee. Cada conta de marketplace (de um seller ou da própria loja) usa um conector. O marketplace avisa a loja de novos pedidos, perguntas e mudanças em anúncios.

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

Receber um aviso

POST/api/v1/storefront/markethub/{marketplace}/webhook/{accountToken}Pública

Recebe um aviso do marketplace

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

marketplacestringobrigatório

Identificador do marketplace (o slug mostrado na conta no painel).

accountTokenstringobrigatório

Token opaco da conta do marketplace, gerado pela loja. Faz parte da URL do webhook.

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/markethub/mercadolivre/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.

Diferente do Hub de ERPs, aqui o aviso é interpretado e gravado antes da resposta. Só então a loja responde 200; se não conseguir gravar, responde 503 e o marketplace tenta de novo.

Um conector sem suporte a webhook ainda recebe o aviso: ele é guardado como ignorado e a resposta é 200.

Erros

Status	Quando	Corpo
200	Aviso gravado (corpo `ok`, texto puro).	`ok`
400	Corpo que o conector não consegue interpretar.	`bad payload`
401	Assinatura inválida.	`invalid signature`
404	Marketplace ou token desconhecido, ou conta apagada.	`404 page not found`
413	Corpo maior que 2 MB.	`payload too large`
503	Não foi possível gravar o aviso. O marketplace deve tentar de novo.	`persist failed`

GET/api/v1/storefront/markethub/oauth/callback/{marketplace}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

marketplacestringobrigatório

Identificador do marketplace (o slug mostrado na conta 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/markethub/oauth/callback/mercadolivre?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/marketplaces/settings/{marketplace}?connected={accountId}) ou, quando o login partiu do painel do seller, /vendor/marketplaces/settings/{marketplace}?connected={accountId}.

Erros

Status	Quando	Corpo
302	Login concluído: redireciona para a tela de configuração do marketplace.	`Location: /admin/marketplaces/settings/mercadolivre?connected=...`
400	`state` ou parâmetros inválidos, ou troca do código recusada.	`oauth error: markethub: invalid input`

Veja também

Hub de Marketplaces

Recebe os avisos dos marketplaces e fecha o login OAuth das contas.

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

Receber um aviso

POST/api/v1/storefront/markethub/{marketplace}/webhook/{accountToken}Pública

Recebe um aviso do marketplace

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

marketplacestringobrigatório

Identificador do marketplace (o slug mostrado na conta no painel).

accountTokenstringobrigatório

Token opaco da conta do marketplace, gerado pela loja. Faz parte da URL do webhook.

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/markethub/mercadolivre/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.

Diferente do Hub de ERPs, aqui o aviso é interpretado e gravado antes da resposta. Só então a loja responde 200; se não conseguir gravar, responde 503 e o marketplace tenta de novo.

Um conector sem suporte a webhook ainda recebe o aviso: ele é guardado como ignorado e a resposta é 200.

Erros

Status	Quando	Corpo
200	Aviso gravado (corpo `ok`, texto puro).	`ok`
400	Corpo que o conector não consegue interpretar.	`bad payload`
401	Assinatura inválida.	`invalid signature`
404	Marketplace ou token desconhecido, ou conta apagada.	`404 page not found`
413	Corpo maior que 2 MB.	`payload too large`
503	Não foi possível gravar o aviso. O marketplace deve tentar de novo.	`persist failed`

GET/api/v1/storefront/markethub/oauth/callback/{marketplace}Pública

Fecha o login OAuth

Parâmetros de caminho

marketplacestringobrigatório

Identificador do marketplace (o slug mostrado na conta 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/markethub/oauth/callback/mercadolivre?code=AUTH_CODE&state=SIGNED_STATE"

Resposta

Erros

Status	Quando	Corpo
302	Login concluído: redireciona para a tela de configuração do marketplace.	`Location: /admin/marketplaces/settings/mercadolivre?connected=...`
400	`state` ou parâmetros inválidos, ou troca do código recusada.	`oauth error: markethub: invalid input`