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

Contas, jobs e categorias

Lista e consulta as contas de marketplace do seller, acompanha a fila de jobs de cada conta e consulta categorias e atributos exigidos pelo canal.

Uma conta de marketplace é a ligação da loja com um canal (por exemplo "Mercado Livre produção"): guarda as credenciais cifradas, o modo de operação e a fila de sincronização. O seller só lê as contas que o administrador associou a ele. As rotas abaixo são de leitura; criar, autorizar e desligar contas é com o administrador.

Listar as contas

GET/api/v1/vendor/markethub/accountsSeller

Lista as contas de marketplace do seller

Parâmetros de consulta

marketplacestring
Filtra por canal (por exemplo mercadolivre, shopee, tiktokshop, amazon). Quando informado e conhecido, a resposta traz também meta (dados do canal) e webhook_url_base.
200Contas do seller
json
{
  "accounts": [
    {
      "id": "e4648fc4-dd0d-45cd-9eaf-4fad48de4a78",
      "marketplace": "mercadolivre",
      "name": "Mercado Livre (produção)",
      "external_account_id": "123456789",
      "status": "A",
      "status_label": "active",
      "sandbox": false,
      "credentials_expires_at": "2026-10-12T20:00:00Z",
      "webhook_token": "3fedea5b97fc8b3c...",
      "settings": {},
      "last_ping_at": "2026-10-11T22:00:00Z",
      "created_at": "2026-09-09T05:37:45Z",
      "updated_at": "2026-10-11T22:00:00Z",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "orders_today": 4,
      "listings_error_count": 0,
      "last_synced_at": "2026-10-11T22:05:00Z"
    }
  ]
}

Campos da resposta

accountsarray
Contas do seller. Lista vazia ([]) quando o administrador não associou nenhuma.
accounts[].iduuid
Id da conta.
accounts[].marketplacestring
Canal da conta.
accounts[].namestring
Nome dado pela loja.
accounts[].external_account_idstring
Id da conta no canal, descoberto na autorização. Vazio antes dela.
accounts[].statusstring
PARDE
Situação em letra.
accounts[].status_labelstring
pending_authactivereauth_requireddisablederror
Situação por extenso.
accounts[].sandboxboolean
Se a conta aponta para o ambiente de testes do canal.
accounts[].credentials_expires_atstring
Quando a autorização vence, se o canal informa.
accounts[].webhook_tokenstring
Trecho secreto da URL de webhook da conta. Trate como senha: não registre em log.
accounts[].sales_channel_idstring
Canal de venda interno ligado à conta, quando há.
accounts[].settingsobject
Configurações da conta. Pode ser {}.
accounts[].last_ping_atstring
Último teste de conexão.
accounts[].last_errorstring
Último erro de comunicação, quando há.
accounts[].vendor_iduuid
Seller dono da conta; é o seu.
accounts[].orders_todayinteger
Pedidos do canal recebidos hoje.
accounts[].listings_error_countinteger
Anúncios da conta em situação de erro.
accounts[].last_synced_atstring
Última sincronização concluída.
metaobject
Só com marketplace: dados do canal (nome, capacidades, formato de autenticação).
webhook_url_basestring
Só com marketplace: modelo da URL pública de webhook.

Consultar uma conta

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

Consulta uma conta de marketplace do seller

Devolve a conta com os campos descritos acima. Conta de outro seller, sem dono ou inexistente responde 404.

Parâmetros de caminho

iduuidobrigatório
Id da conta.

Fila de jobs de uma conta

GET/api/v1/vendor/markethub/accounts/{id}/jobsSeller

Lista os jobs de sincronização de uma conta

Mostra o que a plataforma enfileirou para o canal e como foi: publicações, atualizações, buscas de pedidos, etiquetas. É o lugar para entender por que um anúncio ou pedido não andou.

Parâmetros de caminho

iduuidobrigatório
Id da conta.

Parâmetros de consulta

statusstring
PRSFD
Só jobs nesta situação (letra; minúscula é aceita).
kindstring
publishupdatepricestockpauseresumedeleteorder_fetchorder_pulllabelshipsplitunsplitinvoicereturn_pullsettleqa_pulllisting_reconciletracking_pullmissed_feeds
Só jobs deste tipo.
limitintegerpadrão: 100
Máximo de jobs, de 1 a 500. Fora disso volta a 100.
200Jobs da conta
json
{
  "jobs": [
    {
      "id": 4812,
      "account_id": "e4648fc4-dd0d-45cd-9eaf-4fad48de4a78",
      "kind": "publish",
      "ref_id": "a7c1d0e2-3b4f-4c5a-8d6e-9f0a1b2c3d4e",
      "status": "F",
      "attempts": 2,
      "run_after": "2026-10-11T22:30:00Z",
      "last_error": "rate limited by the channel",
      "created_at": "2026-10-11T22:00:00Z"
    }
  ]
}

Campos da resposta

jobsarray
Jobs do mais novo para o mais antigo.
jobs[].idinteger
Id do job (inteiro).
jobs[].account_iduuid
Conta.
jobs[].kindstring
Tipo do job.
jobs[].ref_idstring
O que o job trata: id do anúncio, por exemplo. Pode faltar.
jobs[].statusstring
PRSFD
P pendente, R em execução, S sucesso, F falhou e será tentado de novo, D desistiu (esgotou as tentativas).
jobs[].attemptsinteger
Tentativas feitas.
jobs[].run_afterstring
Quando será tentado a próxima vez.
jobs[].last_errorstring
Último erro, quando houve.
jobs[].payloadobject
Dados do job, quando há.
jobs[].created_atstring
Quando entrou na fila.

Categorias do canal

GET/api/v1/vendor/markethub/accounts/{id}/categoriesSeller

Lista as categorias do canal sob uma categoria-pai

Devolve os filhos de uma categoria do canal (a raiz se parent vier vazio), da cópia guardada na plataforma ou, se estiver vencida, buscada no canal. Percorra a árvore descendo de pai em filho até chegar a uma folha (leaf: true): só categorias folha servem para anunciar.

Parâmetros de caminho

iduuidobrigatório
Id da conta.

Parâmetros de consulta

parentstring
Id da categoria-pai no canal (external_id). Vazio traz a raiz.
pageintegerpadrão: 1
Página. Só vale com per_page.
per_pageinteger
Quando maior que 0 pagina o resultado (máximo 200) e a resposta traz next_page. Sem ele, vem tudo.
200Categorias
json
{
  "categories": [
    { "external_id": "MLB1051", "parent_ext_id": null, "name": "Celulares e Telefones", "path": "Celulares e Telefones", "leaf": false }
  ],
  "next_page": 0
}

Campos da resposta

categoriesarray
Categorias filhas.
categories[].external_idstring
Id da categoria no canal. É o category_ext_id do anúncio.
categories[].parent_ext_idstring
Id da categoria-pai. null na raiz.
categories[].namestring
Nome.
categories[].pathstring
Caminho completo, quando o canal informa.
categories[].leafboolean
true quando não tem filhos.
next_pageinteger
Só com per_page: próxima página, ou 0 se esta é a última.

Atributos de uma categoria

GET/api/v1/vendor/markethub/accounts/{id}/categories/{extID}/attributesSeller

Lista os atributos exigidos por uma categoria do canal

Diz o que o canal pede para anunciar nessa categoria: marca, cor, voltagem etc., com as opções permitidas quando o campo é uma lista. Use para montar o campo attributes do anúncio.

Parâmetros de caminho

iduuidobrigatório
Id da conta.
extIDstringobrigatório
Id da categoria no canal (external_id).
200Atributos da categoria
json
{
  "attributes": [
    {
      "external_id": "BRAND",
      "name": "Marca",
      "required": true,
      "type": "string"
    },
    {
      "external_id": "COLOR",
      "name": "Cor",
      "required": false,
      "type": "list",
      "values": [{ "id": "52049", "name": "Preto" }]
    }
  ]
}

Campos da resposta

attributesarray
Atributos da categoria.
attributes[].external_idstring
Id do atributo no canal.
attributes[].namestring
Nome exibível.
attributes[].requiredboolean
Se o canal exige o atributo.
attributes[].typestring
Tipo do valor, como o canal informa. Pode faltar.
attributes[].valuesarray
Opções permitidas (id e name), quando o atributo é uma lista.

Exemplo de requisição

bash
# contas
curl "$BASE_URL/api/v1/vendor/markethub/accounts" -H "Authorization: Bearer $TOKEN"

# categorias da raiz, 50 por vez
curl "$BASE_URL/api/v1/vendor/markethub/accounts/$ACCOUNT_ID/categories?per_page=50" \
  -H "Authorization: Bearer $TOKEN"

# atributos de uma categoria folha
curl "$BASE_URL/api/v1/vendor/markethub/accounts/$ACCOUNT_ID/categories/MLB1055/attributes" \
  -H "Authorization: Bearer $TOKEN"

Erros

StatusQuandoCorpo de exemplo
401Sem token.{"error":"authentication required"}
403Módulo desligado.{"error":"module_disabled","module":"marketplace-hub"}
403O usuário não tem seller.{"error":"no vendor account associated with this user"}
404Conta de outro seller, sem dono ou inexistente.{"error":"account not found","detail":"markethub: account not found"}
500id da conta que não é UUID.{"error":"account not found","detail":"o valor \"abc\" não é um uuid válido. ..."}
4xx/5xxO canal recusou ou falhou ao buscar categorias ou atributos; o status é o do canal (502 se não informado).{"error":"failed to load categories","code":"...","detail":"..."}
Lista vazia não é erro

Se o administrador ainda não associou nenhuma conta ao seu seller, accounts vem [] com 200. Isso não significa que a loja não tem contas: só que nenhuma é sua.

Verificado em parte

A loja de testes não tem contas associadas ao seller de teste, então as respostas de conta, jobs, categorias e atributos são exemplos montados a partir do código. As chamadas de lista e de erro foram feitas ao vivo.

Veja também

  • Anúncios
  • Pedidos do canal
  • Visão geral
Anterior
Hub de marketplaces do seller
Próxima
Anúncios do seller
Nesta página
  • Listar as contas
  • Consultar uma conta
  • Fila de jobs de uma conta
  • Categorias do canal
  • Atributos de uma categoria
  • Exemplo de requisição
  • Erros
  • Veja também