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

Anúncios do seller

Lista, cria, consulta e edita os anúncios (rascunhos) do seller nos marketplaces; a prévia e a publicação ficam na página seguinte.

Um anúncio (listing) é um produto da loja oferecido em um canal, com título, descrição, categoria do canal, atributos e preço próprios daquele canal. Ele nasce como rascunho (D), você completa os dados e depois publica. Cada anúncio pertence a uma conta e a um produto (ou kit) da loja; enquanto não está publicado, nada é enviado ao canal.

Depois de publicado, o estoque e (salvo preço fixo) o preço do anúncio acompanham o produto da loja: a plataforma envia as mudanças ao canal sozinha. Para cada variação do produto o anúncio guarda um SKU (skus), que carrega o preço e o estoque enviados.

Listar anúncios

GET/api/v1/vendor/markethub/listingsSeller

Lista os anúncios das contas do seller

Devolve os anúncios das contas do seller, do mais recentemente alterado para o mais antigo, com uma prévia do preço e um resumo dos problemas.

Parâmetros de consulta

accountuuid
Só anúncios desta conta. Uma conta que não é sua devolve lista vazia.
statusstring
DQAPECR
Só anúncios nesta situação (letra; minúscula é aceita).
qstring
Busca por trecho do título do anúncio ou do nome do produto.
productuuid
Só anúncios deste produto.
issuesstring
1
1 traz só os anúncios em erro (E).
pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora disso volta a 50.
200Anúncios
json
{
  "listings": [
    {
      "id": "a7c1d0e2-3b4f-4c5a-8d6e-9f0a1b2c3d4e",
      "account_id": "e4648fc4-dd0d-45cd-9eaf-4fad48de4a78",
      "marketplace": "mercadolivre",
      "account_name": "Mercado Livre (produção)",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "bundle_id": null,
      "product_name": "Smartphone Plus Roxo",
      "product_image": "/uploads/products/smartphone-roxo.jpg",
      "external_id": null,
      "external_url": null,
      "status": "E",
      "title": "Smartphone Plus Roxo 128 GB",
      "description": "Smartphone com tela de 6,5 polegadas.",
      "category_ext_id": "MLB1055",
      "listing_type_ext_id": "gold_special",
      "price_override_cents": null,
      "attributes": [{ "id": "BRAND", "name": "Marca", "value": "Plus" }],
      "last_issues": [{ "code": "missing_required_attribute", "message": "Preencha a cor.", "attr_id": "COLOR" }],
      "last_synced_at": null,
      "published_at": null,
      "created_at": "2026-10-11T20:00:00Z",
      "updated_at": "2026-10-11T20:30:00Z",
      "price_resolution": { "base_cents": 129900, "rule_label": "Preço da loja", "final_cents": 129900 }
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50,
  "issue_groups": [
    { "code": "missing_required_attribute", "count": 1, "message": "Preencha a cor.", "listing_ids": ["a7c1d0e2-3b4f-4c5a-8d6e-9f0a1b2c3d4e"] }
  ]
}

Campos da resposta

listingsarray
Anúncios da página. [] quando não há nenhum (na lista do seller; a do administrador pode trazer null).
totalinteger
Total que casa com os filtros.
pageinteger
Página devolvida.
per_pageinteger
Tamanho aplicado.
issue_groupsarray
Problemas agrupados por código, sobre a página devolvida. Ausente quando não há.
issue_groups[].codestring
Código do problema.
issue_groups[].countinteger
Quantos anúncios têm esse problema.
issue_groups[].messagestring
Mensagem do problema.
issue_groups[].listing_idsarray
Anúncios afetados.
listings[].iduuid
Id do anúncio.
listings[].account_iduuid
Conta do anúncio.
listings[].marketplacestring
Canal.
listings[].account_namestring
Nome da conta.
listings[].product_iduuid
Produto da loja. Nulo em anúncio de kit.
listings[].bundle_iduuid
Kit da loja. Nulo em anúncio de produto.
listings[].product_namestring
Nome do produto.
listings[].product_imagestring
Imagem principal do produto.
listings[].external_idstring
Id do anúncio no canal. Nulo até publicar.
listings[].external_urlstring
Endereço do anúncio no canal. Nulo até publicar.
listings[].statusstring
DQAPECR
Situação: D rascunho, Q na fila, A ativo, P pausado, E erro, C encerrado, R em revisão.
listings[].titlestring
Título no canal. Nulo usa o nome do produto.
listings[].descriptionstring
Descrição no canal.
listings[].category_ext_idstring
Categoria do canal (veja as categorias).
listings[].listing_type_ext_idstring
Tipo de anúncio do canal (por exemplo, clássico ou premium), quando o canal tem.
listings[].price_override_centsinteger
Preço fixo do anúncio, em centavos. Nulo usa o preço da loja.
listings[].attributesarray
Valores dos atributos da categoria (id, name, value, e value_id e unit quando há).
listings[].last_issuesarray
Problemas da última tentativa de publicação (code, message, attr_id, warning).
listings[].last_synced_atstring
Última sincronização com o canal.
listings[].published_atstring
Quando foi publicado.
listings[].created_atstring
Criação.
listings[].updated_atstring
Última alteração.
listings[].price_resolutionobject
Prévia do preço que seria enviado: base_cents (preço da loja), rule_label (regra do canal aplicada, se houver), final_cents e override_cents (quando há preço fixo).

Criar um anúncio

POST/api/v1/vendor/markethub/listingsSeller

Cria um anúncio em rascunho

Cria o rascunho (status: D) e já gera os SKUs a partir do produto: um por variação, ou um só para produto simples. Nada é enviado ao canal. Informe exatamente um entre product_id e bundle_id. A resposta é o detalhe do anúncio (com skus e jobs).

Corpo da requisição

account_iduuidobrigatório
Conta onde o anúncio vai. Precisa ser do seller.
product_iduuid
Produto da loja. Obrigatório se não houver bundle_id.
bundle_iduuid
Kit da loja. Obrigatório se não houver product_id.
titlestring
Título no canal. Vazio usa o nome do produto.
descriptionstring
Descrição no canal.
category_ext_idstring
Categoria folha do canal.
listing_type_ext_idstring
Tipo de anúncio do canal.
price_override_centsinteger
Preço fixo em centavos. Omitido usa o preço da loja.
attributesarray
Valores dos atributos: lista de { "id", "name", "value", "value_id", "unit" }. Um JSON inválido é descartado e vira [].

Exemplo de requisição: criar

bash
curl -X POST "$BASE_URL/api/v1/vendor/markethub/listings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "e4648fc4-dd0d-45cd-9eaf-4fad48de4a78",
    "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
    "category_ext_id": "MLB1055",
    "attributes": [{ "id": "BRAND", "value": "Plus" }]
  }'

Consultar um anúncio

GET/api/v1/vendor/markethub/listings/{id}Seller

Detalhe de um anúncio, com SKUs e jobs recentes

Devolve o anúncio com os mesmos campos da lista e mais duas listas: skus (um por variação) e jobs (os jobs recentes só deste anúncio). Anúncio de outra conta responde 404.

Parâmetros de caminho

iduuidobrigatório
Id do anúncio.
200Detalhe do anúncio
json
{
  "id": "a7c1d0e2-3b4f-4c5a-8d6e-9f0a1b2c3d4e",
  "account_id": "e4648fc4-dd0d-45cd-9eaf-4fad48de4a78",
  "marketplace": "mercadolivre",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "status": "D",
  "title": "Smartphone Plus Roxo 128 GB",
  "category_ext_id": "MLB1055",
  "attributes": [{ "id": "BRAND", "value": "Plus" }],
  "last_issues": null,
  "price_resolution": { "base_cents": 129900, "final_cents": 129900 },
  "skus": [
    {
      "id": "5b8e1c0a-0d3f-4a7b-9c21-6e4f8a1b2c3d",
      "listing_id": "a7c1d0e2-3b4f-4c5a-8d6e-9f0a1b2c3d4e",
      "local_key": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "seller_sku": "SMART-ROXO-128",
      "external_sku_id": null,
      "price_cents": null,
      "stock": null
    }
  ],
  "jobs": []
}

Campos da resposta

skusarray
SKUs do anúncio, um por variação (ou um para produto simples ou kit).
skus[].local_keystring
Chave do item na loja (id do produto, ou produto:variação).
skus[].seller_skustring
Código SKU enviado ao canal.
skus[].external_sku_idstring
Id do SKU no canal, depois de publicado.
skus[].price_centsinteger
Último preço enviado, em centavos. Nulo antes do primeiro envio.
skus[].stockinteger
Último estoque enviado. Nulo antes do primeiro envio.
skus[].b2bobject
Preço para empresas (price_cents e faixas por quantidade), nos canais que têm.
jobsarray
Jobs recentes deste anúncio, no mesmo formato da fila da conta.

Os demais campos são os da lista.

Alterar um rascunho

PATCH/api/v1/vendor/markethub/listings/{id}Seller

Altera parcialmente um anúncio

Altera só os campos presentes no corpo; o que não vier fica como está. Enviar null limpa um campo de texto ou o preço fixo. Trocar category_ext_id descarta os atributos que não existem na nova categoria. A alteração não reenvia nada ao canal: para isso, publique de novo. A resposta é o detalhe do anúncio.

Parâmetros de caminho

iduuidobrigatório
Id do anúncio.

Corpo da requisição

titlestring
Título. null ou vazio volta ao nome do produto.
descriptionstring
Descrição.
category_ext_idstring
Categoria do canal.
listing_type_ext_idstring
Tipo de anúncio do canal.
price_override_centsinteger
Preço fixo em centavos; null volta ao preço da loja.
attributesarray
Lista completa de valores de atributo. Substitui a anterior.
bash
curl -X PATCH "$BASE_URL/api/v1/vendor/markethub/listings/a7c1d0e2-3b4f-4c5a-8d6e-9f0a1b2c3d4e" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price_override_cents": 119900, "attributes": [{"id": "BRAND", "value": "Plus"}, {"id": "COLOR", "value": "Roxo"}]}'

Erros

StatusQuandoCorpo de exemplo
400Corpo não é JSON.{"error":"invalid body","detail":"..."}
400Criação sem account_id, ou sem ou com os dois product_id e bundle_id.{"error":"failed to create listing","detail":"markethub: invalid input: exactly one of product_id or bundle_id is required"}
400Campo de texto que não é texto, price_override_cents que não é inteiro, attributes que não é lista (alteração).{"error":"failed to update listing","detail":"markethub: invalid input: attributes must be an array"}
401Sem token.{"error":"authentication required"}
403Módulo desligado.{"error":"module_disabled","module":"marketplace-hub"}
403Usuário sem seller.{"error":"no vendor account associated with this user"}
404Conta (na criação) ou anúncio de outro seller, ou inexistente.{"error":"listing not found","detail":"markethub: listing not found"}
500Qualquer id que não é UUID válido.{"error":"failed to create listing","detail":"..."}
Atributos: mande a lista inteira

attributes no PATCH substitui tudo. Para mudar um valor, leia o anúncio, altere o item e reenvie a lista completa, ou os outros atributos somem.

Preço do canal diferente do da loja

Use price_override_cents quando o canal precisa de preço próprio (por causa da comissão dele, por exemplo). Sem ele, vale o preço da loja com as regras de preço do canal. A prévia em price_resolution mostra o resultado.

Verificado em parte

A loja de testes não tem anúncios, então as respostas de anúncio são exemplos montados a partir do código. Os erros de validação foram chamados ao vivo.

Veja também

  • Prévia e publicação
  • Contas, jobs e categorias
  • Visão geral
Anterior
Contas, jobs e categorias
Próxima
Prévia e publicação
Nesta página
  • Listar anúncios
  • Criar um anúncio
  • Exemplo de requisição: criar
  • Consultar um anúncio
  • Alterar um rascunho
  • Erros
  • Veja também