VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Catálogo mestre e visibilidade

Clonar mestres

Cria produtos do seller a partir de produtos mestre, um a um ou em lote por lista de ids ou por filtro.

Clonar um mestre

Cria um produto do seu seller a partir do mestre, copiando nome, descrição, fotos, características e EAN. Você informa só o que é seu. O produto nasce ligado ao mestre e passa pela moderação da loja como um produto novo do seller.

POST/api/v1/vendor/master-catalog/{id}/cloneSeller

Clonar um mestre

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

iduuidobrigatório
Id do mestre.

Corpo da requisição

priceinteger
Preço do seu produto, em centavos. Omitido, usa o base_price do mestre.
quantityinteger
Estoque inicial. Omitido, 0.
skustring
Seu SKU para o produto.
statusstring
Situação do produto. Omitido, active.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/master-catalog/$MASTER_ID/clone" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "price": 79900,
  "quantity": 20,
  "sku": "CAF-001"
}'

Resposta

201Produto criado
json
{
  "id": "0c5a7e14-3b2d-4c19-8f66-7a1d2e3f4b50",
  "vendor_id": "7c1f0b52-3a64-4d1e-9a40-5f0c2b6a91d3",
  "name": "Cafeteira Moderno Branco 01426",
  "slug": "cafeteira-moderno-branco-01426",
  "sku": "CAF-001",
  "price": 79900,
  "quantity": 20,
  "status": "A",
  "master_product_id": "6b5806fe-4370-4f12-bc95-a7dbba04918b"
}

Campos da resposta

iduuid
Id do novo produto.
vendor_iduuid
Seu seller (sempre forçado pelo token).
namestring
Nome copiado do mestre.
slugstring
Endereço curto gerado.
skustring
Seu SKU.
priceinteger
Preço em centavos.
quantitynumber
Estoque.
statusstring
Letra da situação: A ativo, H oculto, D desativado. Se a moderação da loja exigir aprovação, o produto nasce em espera.
master_product_iduuid
Mestre de origem.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"no vendor account associated with this user"}
403O usuário da equipe do seller não tem nenhum dos privilégios exigidos: vendor_catalog, vendor_view_catalog, vendor_manage_products, vendor_manage_master, vendor_manage_mix, vendor_manage_quotes, vendor_manage_features, vendor_import_products.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}
404O recurso de produtos mestre está desligado nesta loja.{"error":"feature not enabled","detail":"enable master_products via admin settings"}
400Corpo que não é JSON.{"error":"invalid request body","detail":"..."}
404Mestre inexistente.{"error":"master product not found"}
500Você já clonou este mestre; o módulo de produtos mestre está desligado; ou a loja exige código de barras e o mestre não tem. O motivo vai em detail.{"error":"failed to clone master product","detail":"clone master product: ..."}
Repetição vira erro 500

Clonar de novo o mesmo mestre responde 500 (o detail diz que você já tem um produto ligado). Antes de clonar, confira em GET /master-catalog se o offer_count já inclui você, ou use o bulk-clone, que só conta o repetido em skipped.

Moderação

Preço, SKU e estoque são informados por você, então o clone segue a regra de moderação do seller (pré-aprovação, se a loja a exigir), mesmo vindo de um mestre já aprovado.

Clonar em lote

Clona vários mestres de uma vez, com os padrões (preço do mestre, estoque 0). Quem já foi clonado, ou não está disponível, é contado em skipped, sem derrubar o lote. Há três jeitos de chamar: lista de ids (resposta imediata), filter com simulação, ou lista de ids com simulate/confirm_token.

POST/api/v1/vendor/master-catalog/bulk-cloneSeller

Clonar vários mestres

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

filterobject
Recorte resolvido no servidor. Chaves: ids (lista de ids de mestre), exclude_ids, name_contains, brand, category_id, status (active, pending, hidden), price_min e price_max (centavos), created_after e created_before (AAAA-MM-DD), all (true para a tabela inteira). Uma chave desconhecida é recusada com a lista das aceitas. Mestres que o seller já clonou ficam de fora.
master_product_idsarray
Modo simples: lista de ids de mestre. Cada um é clonado com os padrões (preço do mestre, estoque 0).
simulateboolean
true só conta e devolve amostra e confirm_token; não clona nada.
confirm_tokenstring
Token da simulação com o mesmo corpo. Obrigatório para executar por filtro. Vale 70 minutos e só serve para o mesmo seller, usuário e corpo.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/master-catalog/bulk-clone" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "master_product_ids": [
    "6b5806fe-4370-4f12-bc95-a7dbba04918b",
    "0d2f9a4b-7c61-4e3a-9b85-2a6c1d0e8f33"
  ]
}'

Resposta

200Lista de ids: resultado
json
{
  "created": 1,
  "skipped": 1,
  "partial_failure": true,
  "message": "1 de 2 produtos não foram clonados (já existiam, ou o mestre não está disponível para este seller)"
}
200Simulação por filtro
json
{
  "simulate": true,
  "action": "clone",
  "description": "Clonar produtos do catálogo mestre para a loja do seller",
  "total": 87,
  "sample": [
    {
      "id": "6b5806fe-4370-4f12-bc95-a7dbba04918b",
      "name": "Cafeteira Moderno Branco 01426",
      "before": "no catálogo mestre",
      "after": "na sua loja"
    }
  ],
  "confirm_token": "eyJ...",
  "expires_at": "2026-10-11T23:10:00Z",
  "async": true,
  "by": "filter"
}
202Execução por filtro (tarefa em andamento)
json
{
  "action": "clone",
  "by": "filter",
  "total_requested": 87,
  "status": "queued",
  "async": true,
  "job": {
    "id": "4636fe0a-063a-4b19-8f62-11512ebcc416",
    "route": "POST /vendor/master-catalog/bulk-clone",
    "action": "clone",
    "status": "queued",
    "total": 87,
    "processed": 0,
    "affected": 0,
    "failed": 0,
    "percent": 0,
    "created_at": "2026-10-11T22:05:00Z"
  }
}

Campos da resposta

createdinteger
Lista de ids: produtos criados.
skippedinteger
Ids já clonados ou indisponíveis.
partial_failureboolean
true quando skipped > 0.
messagestring
Resumo em português, quando há skipped.
simulateboolean
Simulação: sempre true.
totalinteger
Simulação: quantos mestres o filtro alcança.
samplearray
Simulação: até 10 exemplos (id, name, before, after).
confirm_tokenstring
Simulação: token para a execução.
expires_atstring
Simulação: RFC 3339. Validade do token.
asyncboolean
true quando a execução vira tarefa (50 registros ou mais).
jobobject
Execução assíncrona (202): a tarefa; acompanhe em Tarefas em lote.
total_requestedinteger
Execução por filtro: registros alcançados.
affectedinteger
Execução síncrona por filtro: clonados.
failedarray
Execução síncrona por filtro: falhas por registro (id, error).

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"no vendor account associated with this user"}
403O usuário da equipe do seller não tem nenhum dos privilégios exigidos: vendor_catalog, vendor_view_catalog, vendor_manage_products, vendor_manage_master, vendor_manage_mix, vendor_manage_quotes, vendor_manage_features, vendor_import_products.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}
404O recurso de produtos mestre está desligado nesta loja.{"error":"feature not enabled","detail":"enable master_products via admin settings"}
400Lista de ids vazia, corpo inválido ou filtro inválido (chave desconhecida, sem recorte).{"error":"master_product_ids is required"} / {"error":"invalid_filter","detail":"..."}
409confirm_token de outro pedido, expirado, ou o recorte cresceu desde a simulação.{"error":"confirm_token_invalid","detail":"..."}
428Execução por filtro sem confirm_token.{"error":"simulate_required","detail":"lote por filtro exige simulação: ..."}
500Falha geral do lote.{"error":"failed to bulk-clone master products"}
Fluxo recomendado para muitos itens
  1. Chame com filter e simulate: true. 2) Mostre total e sample ao usuário. 3) Repita o mesmo corpo trocando simulate por confirm_token. 4) Se vier 202, acompanhe o job.id em Tarefas em lote.
Padrões fixos

O lote não aceita preço nem estoque por item: tudo nasce com o preço do mestre e estoque 0. Para valores próprios, clone um a um ou ajuste depois.

Anterior
Catálogo mestre
Próxima
Modo catálogo
Nesta página
  • Clonar um mestre
  • Exemplo de requisição
  • Resposta
  • Erros
  • Clonar em lote
  • Exemplo de requisição
  • Resposta
  • Erros