Hub de marketplaces do seller

Como o seller (lojista) acompanha suas contas em marketplaces, publica anúncios do catálogo da loja nesses canais e recebe os pedidos de volta.

Um marketplace é um site de terceiros que vende por conta de lojistas, como o Mercado Livre, a Shopee, a Amazon ou o TikTok Shop. O Hub de marketplaces (MarketHub) liga o catálogo e o estoque da loja a esses canais: o seller escolhe produtos, a plataforma monta e envia o anúncio (listing) ao canal, mantém preço e estoque em dia e traz de volta os pedidos do canal como pedidos da loja. Esta seção é a visão do seller: só enxerga as contas e os dados que são dele.

Pontos principais

Só funciona com o módulo marketplace-hub ligado. Sem ele, as rotas respondem 403 module_disabled.
Quem cria a conta de marketplace e faz a autorização com o canal (OAuth, chaves) é o administrador da loja. O seller enxerga as contas que o administrador associou a ele: uma conta sem seller dono não aparece para nenhum seller.
O escopo vem do token, nunca de parâmetro. Conta, anúncio ou pedido de outro seller responde 404, como se não existisse.
Dinheiro em centavos; datas em RFC 3339 (UTC), exceto os filtros from e until de pedidos, que usam AAAA-MM-DD.
Tudo o que fala com o canal é assíncrono: publicar, atualizar e buscar pedidos entram numa fila de jobs. A resposta 200 diz que o pedido foi aceito, não que o canal já respondeu.
Algumas rotas existem apenas para uma loja específica e respondem 404 nas demais; elas não fazem parte deste contrato e não estão documentadas aqui.

Como funciona

Administrador cria a conta→Seller cria o anúncio (rascunho)→Prévia e publicação→Fila de jobs→Pedidos chegam

Veja suas contas
Liste as contas e confira status_label. Uma conta pending_auth ou reauth_required não consegue falar com o canal e pede ação do administrador.
Crie o anúncio
Crie o rascunho escolhendo a conta e o produto, e preencha categoria e atributos do canal (consulte categorias e atributos).
Confira antes de publicar
Chame a prévia: ela devolve o conteúdo que seria enviado e os problemas a corrigir, sem enviar nada.
Publique
Publique. Se há problemas bloqueantes, volta 422 listing_issues e nada entra na fila. Se está tudo certo, o anúncio vai para Q (na fila) e o canal responde depois.
Receba os pedidos
Os pedidos do canal viram pedidos da loja sozinhos; use a lista para acompanhar nota fiscal, etiqueta e envio.

Situação do anúncio

O status do anúncio é uma letra.

Letra	Nome	Significado
`D`	rascunho	Criado, ainda não publicado.
`Q`	na fila	Publicação ou atualização enviada à fila.
`A`	ativo	No ar no canal.
`P`	pausado	Pausado.
`E`	erro	A última tentativa falhou ou tem problemas; veja `last_issues`.
`C`	encerrado	Fechado.
`R`	em revisão	O canal está revisando.

Situação da conta

`status`	`status_label`	Significado
`P`	`pending_auth`	Criada, aguardando autorização.
`A`	`active`	Operando.
`R`	`reauth_required`	A autorização venceu ou foi revogada.
`D`	`disabled`	Desligada.
`E`	`error`	Com erro.

Conceitos importantes

Modo de teste e execução seca

Uma conta pode estar em sandbox (ambiente de testes do canal) ou em execução seca (dry_run): nesses modos a plataforma monta e guarda o que enviaria, mas não chama o canal. Publicar numa conta assim devolve dry_run: true. Também só nesses modos é permitido forçar a busca manual de pedidos.

Jobs

Cada ação com o canal vira um job (publish, update, order_pull, order_fetch, label...) com situação P pendente, R em execução, S sucesso, F falhou (nova tentativa agendada) ou D esgotou as tentativas. A rota de jobs da conta mostra a fila.

Dados que o canal exige

Cada canal tem a própria árvore de categorias e uma lista de atributos obrigatórios por categoria (marca, cor, tamanho). O anúncio só é aceito quando os atributos obrigatórios estão preenchidos.

Endpoints

Método	Caminho	Para quê	Auth
GET	`/api/v1/vendor/markethub/accounts`	Lista as contas do seller.	seller
GET	`/api/v1/vendor/markethub/accounts/{id}`	Consulta uma conta.	seller
GET	`/api/v1/vendor/markethub/accounts/{id}/jobs`	Fila de sincronização da conta.	seller
GET	`/api/v1/vendor/markethub/accounts/{id}/categories`	Categorias do canal.	seller
GET	`/api/v1/vendor/markethub/accounts/{id}/categories/{extID}/attributes`	Atributos exigidos por uma categoria.	seller
GET	`/api/v1/vendor/markethub/listings`	Lista os anúncios.	seller
POST	`/api/v1/vendor/markethub/listings`	Cria um anúncio em rascunho.	seller
GET	`/api/v1/vendor/markethub/listings/{id}`	Detalhe de um anúncio.	seller
PATCH	`/api/v1/vendor/markethub/listings/{id}`	Altera o rascunho.	seller
POST	`/api/v1/vendor/markethub/listings/{id}/preview`	Prévia do que seria enviado.	seller
POST	`/api/v1/vendor/markethub/listings/{id}/publish`	Publica o anúncio.	seller
PUT	`/api/v1/vendor/markethub/listings/{id}/logistics`	Define o canal de logística do anúncio.	seller
PUT	`/api/v1/vendor/markethub/brand-mappings`	Liga uma marca local a uma marca do canal.	seller
GET	`/api/v1/vendor/markethub/products/{productID}/commercial`	Marca e logística guardadas nos anúncios de um produto.	seller
GET	`/api/v1/vendor/markethub/orders`	Lista os pedidos vindos dos canais.	seller
GET	`/api/v1/vendor/markethub/orders/detail`	Detalhe de um pedido, pacotes e jobs.	seller
POST	`/api/v1/vendor/markethub/orders/pull`	Pede a busca de pedidos de um período.	seller
POST	`/api/v1/vendor/markethub/orders/retry`	Pede nova busca de pedidos específicos.	seller
GET	`/api/v1/vendor/markethub/orders/{orderID}/label`	Baixa a etiqueta de envio.	seller

Erros comuns

Procurar a conta do administrador e achar a lista vazia. Uma conta sem seller dono não aparece para sellers. Peça ao administrador que associe a conta ao seu seller.
Publicar sem preencher os atributos obrigatórios. Volta 422 listing_issues; leia a lista issues e corrija o rascunho com PATCH.
Achar que 200 na publicação é "no ar". O anúncio só vai para a fila; acompanhe o status e os jobs.
Usar orders/pull numa conta de produção. Só contas em sandbox ou em execução seca aceitam busca manual; as demais voltam 400.
Mandar data com hora em from e until. Use AAAA-MM-DD.
Passar um id que não é UUID. Várias rotas respondem 500 em vez de 400.

Próximos passos

Contas, jobs e categorias

Veja suas contas e o catálogo do canal.

Anúncios

Listar, criar e editar rascunhos.

Prévia e publicação

Conferir e publicar no canal.

Pedidos do canal

Acompanhar pedidos e etiquetas.