VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Hub de marketplaces do seller

Prévia e publicação

Confere o que seria enviado ao marketplace, publica o anúncio, define logística e marca por anúncio e consulta o que foi guardado para um produto.

Antes de publicar, você pode pedir ao Hub uma prévia: ele monta exatamente o que enviaria ao canal e aponta os problemas (atributo obrigatório faltando, categoria que não é folha, imagem ausente), sem escrever nada. Quando a prévia vem limpa, a publicação coloca o anúncio na fila de envio. O canal pode ainda recusar depois; o resultado final aparece em status, last_issues e nos jobs.

Prévia do anúncio

POST/api/v1/vendor/markethub/listings/{id}/previewSeller

Mostra o que seria enviado e os problemas encontrados

Não escreve no canal, não enfileira nada e não muda a situação do anúncio. Sem corpo. Use para validar um rascunho a cada alteração.

Parâmetros de caminho

iduuidobrigatório
Id do anúncio.
200Prévia
json
{
  "fiscal_version": "",
  "external_id": "",
  "issues": [
    { "code": "missing_required_attribute", "message": "Preencha a cor.", "attr_id": "COLOR" },
    { "code": "short_title", "message": "Título curto.", "warning": true }
  ],
  "payload": { "title": "Smartphone Plus Roxo 128 GB", "category_id": "MLB1055" }
}

Campos da resposta

issuesarray
Problemas encontrados. [] quando não há nenhum.
issues[].codestring
Código do problema.
issues[].messagestring
Mensagem para o usuário.
issues[].attr_idstring
Atributo envolvido, quando o problema é de um atributo.
issues[].warningboolean
true é só um aviso: não impede a publicação. Sem ele (ou false), o problema é bloqueante.
payloadobject
O conteúdo que seria enviado ao canal, sem segredos, no formato do canal. null quando o canal não tem prévia.
external_idstring
Id do anúncio no canal, quando já foi publicado.
fiscal_versionstring
Versão das regras fiscais usadas para montar os dados (pode vir vazia). Útil para suporte.

Publicar

POST/api/v1/vendor/markethub/listings/{id}/publishSeller

Coloca o anúncio na fila de publicação

Confere o plano do seller e a prévia. Se há problema bloqueante, nada é enfileirado, os problemas ficam gravados em last_issues e a resposta é 422. Se está tudo certo, o anúncio vai para Q (na fila) e um job publish é criado, ou update quando o anúncio já tem external_id. O envio e a resposta do canal acontecem depois.

Em conta desligada ou em execução seca (dry_run), a plataforma monta e guarda a prévia mas não chama o canal: a resposta traz dry_run: true.

Parâmetros de caminho

iduuidobrigatório
Id do anúncio.
200Aceito para publicação
json
{ "ok": true, "dry_run": false, "fiscal_version": "" }
422Problemas bloqueantes
json
{
  "error": "listing_issues",
  "issues": [
    { "code": "missing_required_attribute", "message": "Preencha a cor.", "attr_id": "COLOR" }
  ]
}

Campos da resposta

okboolean
Sempre true quando aceito.
dry_runboolean
true quando a conta não chama o canal: nada foi enviado.
fiscal_versionstring
Versão das regras fiscais usada.

Logística do anúncio

PUT/api/v1/vendor/markethub/listings/{id}/logisticsSeller

Define o canal de logística de um anúncio

Grava qual canal de logística do marketplace (por exemplo, envio pelo próprio canal ou por conta do seller) este anúncio usa, em vez do padrão da conta. A gravação vale para os próximos envios.

Parâmetros de caminho

iduuidobrigatório
Id do anúncio.

Corpo da requisição

channel_idstring
Id do canal de logística, como o marketplace o define. Vazio apaga a escolha.
200Logística gravada
json
{ "ok": true }

Mapear uma marca

PUT/api/v1/vendor/markethub/brand-mappingsSeller

Liga uma marca local à marca do canal

Alguns canais exigem a marca como um id próprio deles. Esta rota ensina a conta que a marca "Plus" da loja é a marca 12345 do canal, para uma categoria. Gravar de novo a mesma marca na mesma conta e categoria substitui o mapeamento anterior.

Corpo da requisição

account_iduuidobrigatório
Conta do seller.
category_ext_idstring
Categoria do canal em que o mapeamento vale.
local_brandstringobrigatório
Nome da marca na loja.
external_brand_idstringobrigatório
Id da marca no canal.
external_namestring
Nome da marca no canal, para exibição.
200Mapeamento gravado
json
{ "ok": true }

Dados comerciais de um produto

GET/api/v1/vendor/markethub/products/{productID}/commercialSeller

Marca e logística guardadas nos anúncios de um produto

Para um produto da loja, lista os anúncios dele nas suas contas com a marca e a logística guardadas, o SKU e o último preço e estoque enviados. Anúncios em contas de outros sellers não aparecem. Produto sem anúncios devolve lista vazia.

Parâmetros de caminho

productIDuuidobrigatório
Id do produto da loja.
200Dados comerciais
json
{
  "listings": [
    {
      "listing_id": "a7c1d0e2-3b4f-4c5a-8d6e-9f0a1b2c3d4e",
      "account_id": "e4648fc4-dd0d-45cd-9eaf-4fad48de4a78",
      "account_name": "Mercado Livre (produção)",
      "marketplace": "mercadolivre",
      "external_id": "MLB123456789",
      "brand_ext_id": "12345",
      "logistics": { "channel_id": "fulfillment" },
      "status": "A",
      "seller_sku": "SMART-ROXO-128",
      "sent_price_cents": 129900,
      "sent_stock": 12
    }
  ]
}

Campos da resposta

listingsarray
Anúncios do produto nas contas do seller.
listings[].listing_iduuid
Anúncio.
listings[].account_iduuid
Conta.
listings[].account_namestring
Nome da conta.
listings[].marketplacestring
Canal.
listings[].external_idstring
Id no canal. Ausente até publicar.
listings[].brand_ext_idstring
Id da marca no canal usada neste anúncio.
listings[].logisticsobject
Escolha de logística (channel_id). Ausente quando não definida.
listings[].statusstring
Situação do anúncio, em letra.
listings[].seller_skustring
SKU enviado.
listings[].sent_price_centsinteger
Último preço enviado, em centavos.
listings[].sent_stockinteger
Último estoque enviado.

Exemplo de requisição

bash
LISTING=a7c1d0e2-3b4f-4c5a-8d6e-9f0a1b2c3d4e

# 1. prévia
curl -X POST "$BASE_URL/api/v1/vendor/markethub/listings/$LISTING/preview" \
  -H "Authorization: Bearer $TOKEN"

# 2. publicar (só se a prévia não tem problema bloqueante)
curl -X POST "$BASE_URL/api/v1/vendor/markethub/listings/$LISTING/publish" \
  -H "Authorization: Bearer $TOKEN"

Erros

StatusQuandoCorpo de exemplo
400Corpo não é JSON (logística, marca).{"error":"invalid body","detail":"..."}
400local_brand ou external_brand_id vazio.{"error":"failed to save brand mapping","detail":"markethub: invalid input"}
401Sem token.{"error":"authentication required"}
403Módulo desligado.{"error":"module_disabled","module":"marketplace-hub"}
403O plano do seller não inclui este canal.{"error":"failed to publish listing","detail":"plan_feature_required"}
404Anúncio ou conta de outro seller, ou inexistente.{"error":"listing not found","detail":"markethub: listing not found"}
422Problemas bloqueantes na publicação ou na prévia.{"error":"listing_issues","issues":[...]}
4xx/5xxO canal recusou a prévia; o status é o do canal.{"error":"failed to preview listing","code":"...","detail":"..."}
500account_id ou id que não é UUID válido.{"error":"failed to save brand mapping","detail":"o valor \"\" não é um uuid válido. ..."}
Publicar com sucesso não é estar no ar

200 significa que o anúncio entrou na fila. Ele passa por Q, depois A (ativo) ou E (erro). Se o canal recusar, last_issues traz o motivo e o anúncio volta para ajuste.

Avisos não bloqueiam

Na prévia, ignore os itens com warning: true ao decidir se pode publicar. Eles ajudam a melhorar o anúncio, mas o canal aceita sem eles.

Verificado em parte

A loja de testes não tem anúncios nem contas do seller, então os exemplos de prévia e publicação são montados a partir do código. Os códigos de erro de validação foram chamados ao vivo.

Veja também

  • Anúncios do seller
  • Contas, jobs e categorias
  • Visão geral
Anterior
Anúncios do seller
Próxima
Pedidos do canal
Nesta página
  • Prévia do anúncio
  • Publicar
  • Logística do anúncio
  • Mapear uma marca
  • Dados comerciais de um produto
  • Exemplo de requisição
  • Erros
  • Veja também