API atual/Referência completa/Produtos mestre

Gerenciar produtos mestre

Lista, cria, consulta, altera e exclui produtos mestre, o cadastro-modelo ao qual os produtos dos sellers se ligam.

Estas cinco rotas são o CRUD do cadastro-modelo. Leia primeiro os conceitos: o mestre manda no conteúdo, e cada alteração se propaga às ofertas ligadas. Leitura exige view_catalog ou manage_catalog; escrita, manage_master_products ou manage_catalog. O módulo master-products e a configuração de produtos mestre precisam estar ligados.

GET/api/v1/admin/master-productsAdmin

Lista os produtos mestre

Do mais novo para o mais antigo. Mestres excluídos (D) não aparecem. O item da lista não traz imagens nem descrições traduzidas; para isso consulte o mestre.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página. Acima de 100 é limitado a 100.

searchstring

Texto procurado no nome, no SKU e na marca (contém, sem diferenciar maiúsculas).

brandstring

Marca (contém).

category_iduuid

Categoria principal.

statusstring

AH

Status do mestre.

POST/api/v1/admin/master-productsAdmin

Cria um produto mestre

Responde 201 com o mestre completo. É obrigatório informar name, category_id e barcode.

Corpo da requisição (JSON)

namestringobrigatório

Nome do produto.

category_iduuidobrigatório

Categoria principal. O mestre define a navegação das ofertas ligadas.

barcodestringobrigatório

Código de barras (EAN/GTIN). Único em toda a loja.

skustring

SKU do mestre. Único entre mestres e produtos de seller; gravado em minúsculas.

brandstring

Marca.

descriptionstring

Descrição, em HTML.

short_descriptionstring

Resumo.

base_priceinteger

Preço sugerido ao consumidor, em centavos.

main_image_urlstring

Imagem principal. É um campo próprio; o envio de images não o preenche.

featuresobject

Características livres, pares nome e valor ({"Cor":"Azul"}).

specificationsobject

Ficha técnica livre, pares nome e valor.

statusstringpadrão: A

AH

Status inicial.

quantityinteger

Estoque próprio do mestre.

min_quantityinteger

Quantidade mínima por pedido. 0 sem limite.

max_quantityinteger

Quantidade máxima por pedido. 0 sem limite.

quantity_stepinteger

Múltiplo permitido na compra. 0 sem regra.

additional_category_idsarray

Categorias extras, além da principal.

editable_fields_overridearray

Campos que o seller pode editar nas ofertas deste mestre. Vazio usa o padrão da loja.

imagesarray

Galeria.

image_urlstringobrigatório

Endereço da imagem.

alt_textstring

Texto alternativo.

positioninteger

Ordem.

is_primaryboolean

Se é a imagem principal da galeria.

descriptionsarray

Traduções.

lang_codestringobrigatório

Idioma (en, es...).

namestring

Nome no idioma.

descriptionstring

Descrição no idioma.

short_descriptionstring

Resumo no idioma.

GET/api/v1/admin/master-products/{id}Admin

Consulta um produto mestre

Devolve o mestre com imagens, traduções, category_name e offer_count.

Parâmetros de caminho

iduuidobrigatório

Id do mestre.

PUT/api/v1/admin/master-products/{id}Admin

Altera um produto mestre

Altera só os campos enviados. Quando images é enviado, a galeria é substituída por inteira; o mesmo vale para additional_category_ids. Ao terminar, a plataforma propaga nome, descrições, categoria, marca, código de barras, galeria, características e especificações às ofertas ligadas. Preço, estoque, SKU e status das ofertas não mudam.

Parâmetros de caminho

iduuidobrigatório

Id do mestre.

Aceita os mesmos campos da criação, todos opcionais. Uma alteração parcial, como {"status":"H"}, não apaga os outros campos.

DELETE/api/v1/admin/master-products/{id}Admin

Exclui um produto mestre

Exclusão lógica: o status vira D e o mestre some das listas e da consulta. Só é permitida quando nenhum produto de seller está ligado a ele. Repetir a chamada em um mestre já excluído responde 200 de novo.

Parâmetros de caminho

iduuidobrigatório

Id do mestre.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/master-products" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Cafeteira Elétrica 15 Xícaras",
    "brand": "Acme",
    "base_price": 12990,
    "sku": "CAF-15X",
    "barcode": "7899999000011",
    "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
    "features": {"Voltagem": "220v"},
    "images": [{"image_url": "/uploads/exemplo/cafeteira.png", "is_primary": true}]
  }'

Resposta

201Mestre criado

json

{
  "id": "e179b2b4-74a3-42ec-9b8d-326482188a65",
  "sku": "caf-15x",
  "name": "Cafeteira Elétrica 15 Xícaras",
  "description": "",
  "short_description": "",
  "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
  "category_name": "Cafeteiras",
  "brand": "Acme",
  "base_price": 12990,
  "main_image_url": "",
  "features": { "Voltagem": "220v" },
  "specifications": {},
  "status": "A",
  "offer_count": 0,
  "barcode": "7899999000011",
  "quantity": 0,
  "min_quantity": 0,
  "max_quantity": 0,
  "quantity_step": 0,
  "images": [
    {
      "id": "8af9466c-0f4e-418c-921b-d5d8e311bc09",
      "master_product_id": "e179b2b4-74a3-42ec-9b8d-326482188a65",
      "image_url": "/uploads/exemplo/cafeteira.png",
      "alt_text": "",
      "position": 0,
      "is_primary": true
    }
  ],
  "created_at": "2026-10-11T21:10:18.714345Z",
  "updated_at": "2026-10-11T21:10:18.714345Z"
}

200Lista

json

{
  "products": [
    {
      "id": "6b5806fe-4370-4f12-bc95-a7dbba04918b",
      "sku": "sd-001426",
      "name": "Cafeteira Moderno Branco 01426",
      "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
      "brand": "",
      "base_price": 80990,
      "features": { "Modelo": "220v" },
      "specifications": {},
      "status": "A",
      "offer_count": 1,
      "images": [],
      "created_at": "2026-07-23T14:30:14.156287Z",
      "updated_at": "2026-09-15T13:34:19.235744Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos do mestre

iduuid

Id do mestre.

skustring

SKU, em minúsculas. Ausente quando não definido.

namestring

Nome.

descriptionstring

Descrição em HTML.

short_descriptionstring

Resumo.

category_iduuid

Categoria principal.

category_namestring

Nome da categoria. Só na consulta de um mestre.

brandstring

Marca.

base_priceinteger

Preço sugerido, em centavos.

main_image_urlstring

Imagem principal.

featuresobject

Características livres.

specificationsobject

Ficha técnica livre.

statusstring

AHD

Status.

offer_countinteger

Ofertas ativas ligadas ao mestre, contadas na hora.

barcodestring

Código de barras.

quantityinteger

Estoque próprio.

min_quantityinteger

Mínimo por pedido.

max_quantityinteger

Máximo por pedido.

quantity_stepinteger

Múltiplo de compra.

additional_category_idsarray

Categorias extras. Só na consulta.

editable_fields_overridearray

Campos liberados ao seller. Ausente quando vale o padrão da loja.

imagesarray

Galeria (id, master_product_id, image_url, alt_text, position, is_primary). Na lista pode vir vazia.

descriptionsarray

Traduções. Só na consulta.

first_approved_atstring

Quando a primeira oferta ligada foi aprovada. Ausente enquanto nenhuma foi.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Sem `name`	`{"error":"name is required"}`
400	Sem `barcode`	`{"error":"barcode is required for master products","detail":"barcode_required: ..."}`
400	Imagem sem `image_url`	`{"error":"every image needs an image_url","detail":"image_url_required: ..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado, ou falta o privilégio	`{"error":"module_disabled","module":"master-products"}`
404	Recurso desligado na loja	`{"error":"feature not enabled","detail":"enable master_products via admin settings"}`
404	Mestre não existe (ou foi excluído)	`{"error":"master product not found"}`
409	SKU ou código de barras já em uso	`{"error":"código de barras 7899999000011 já está em uso pelo produto \"Cafeteira X\". Use outro código ou vincule este mestre ao produto existente.","detail":"..."}`
409	Excluir um mestre com ofertas	`{"error":"cannot delete: 1 vendor products are linked to this master product","detail":"unlink all vendor products first"}`
500	Sem `category_id`	`{"error":"failed to create master product","detail":"category_required: a category must be selected ..."}`
500	Id que não é UUID	`{"error":"failed to update master product","detail":"..."}`

A mensagem de 409 por código repetido vem em português do servidor.

Veja também

Gerenciar produtos mestre

Lista, cria, consulta, altera e exclui produtos mestre, o cadastro-modelo ao qual os produtos dos sellers se ligam.

GET/api/v1/admin/master-productsAdmin

Lista os produtos mestre

Do mais novo para o mais antigo. Mestres excluídos (D) não aparecem. O item da lista não traz imagens nem descrições traduzidas; para isso consulte o mestre.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página. Acima de 100 é limitado a 100.

searchstring

Texto procurado no nome, no SKU e na marca (contém, sem diferenciar maiúsculas).

brandstring

Marca (contém).

category_iduuid

Categoria principal.

statusstring

AH

Status do mestre.

POST/api/v1/admin/master-productsAdmin

Cria um produto mestre

Responde 201 com o mestre completo. É obrigatório informar name, category_id e barcode.

Corpo da requisição (JSON)

namestringobrigatório

Nome do produto.

category_iduuidobrigatório

Categoria principal. O mestre define a navegação das ofertas ligadas.

barcodestringobrigatório

Código de barras (EAN/GTIN). Único em toda a loja.

skustring

SKU do mestre. Único entre mestres e produtos de seller; gravado em minúsculas.

brandstring

Marca.

descriptionstring

Descrição, em HTML.

short_descriptionstring

Resumo.

base_priceinteger

Preço sugerido ao consumidor, em centavos.

main_image_urlstring

Imagem principal. É um campo próprio; o envio de images não o preenche.

featuresobject

Características livres, pares nome e valor ({"Cor":"Azul"}).

specificationsobject

Ficha técnica livre, pares nome e valor.

statusstringpadrão: A

AH

Status inicial.

quantityinteger

Estoque próprio do mestre.

min_quantityinteger

Quantidade mínima por pedido. 0 sem limite.

max_quantityinteger

Quantidade máxima por pedido. 0 sem limite.

quantity_stepinteger

Múltiplo permitido na compra. 0 sem regra.

additional_category_idsarray

Categorias extras, além da principal.

editable_fields_overridearray

Campos que o seller pode editar nas ofertas deste mestre. Vazio usa o padrão da loja.

imagesarray

Galeria.

image_urlstringobrigatório

Endereço da imagem.

alt_textstring

Texto alternativo.

positioninteger

Ordem.

is_primaryboolean

Se é a imagem principal da galeria.

descriptionsarray

Traduções.

lang_codestringobrigatório

Idioma (en, es...).

namestring

Nome no idioma.

descriptionstring

Descrição no idioma.

short_descriptionstring

Resumo no idioma.

GET/api/v1/admin/master-products/{id}Admin

Consulta um produto mestre

Devolve o mestre com imagens, traduções, category_name e offer_count.

Parâmetros de caminho

iduuidobrigatório

Id do mestre.

PUT/api/v1/admin/master-products/{id}Admin

Altera um produto mestre

Parâmetros de caminho

iduuidobrigatório

Id do mestre.

Aceita os mesmos campos da criação, todos opcionais. Uma alteração parcial, como {"status":"H"}, não apaga os outros campos.

DELETE/api/v1/admin/master-products/{id}Admin

Exclui um produto mestre

Parâmetros de caminho

iduuidobrigatório

Id do mestre.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/master-products" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Cafeteira Elétrica 15 Xícaras",
    "brand": "Acme",
    "base_price": 12990,
    "sku": "CAF-15X",
    "barcode": "7899999000011",
    "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
    "features": {"Voltagem": "220v"},
    "images": [{"image_url": "/uploads/exemplo/cafeteira.png", "is_primary": true}]
  }'

Resposta

201Mestre criado

json

{
  "id": "e179b2b4-74a3-42ec-9b8d-326482188a65",
  "sku": "caf-15x",
  "name": "Cafeteira Elétrica 15 Xícaras",
  "description": "",
  "short_description": "",
  "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
  "category_name": "Cafeteiras",
  "brand": "Acme",
  "base_price": 12990,
  "main_image_url": "",
  "features": { "Voltagem": "220v" },
  "specifications": {},
  "status": "A",
  "offer_count": 0,
  "barcode": "7899999000011",
  "quantity": 0,
  "min_quantity": 0,
  "max_quantity": 0,
  "quantity_step": 0,
  "images": [
    {
      "id": "8af9466c-0f4e-418c-921b-d5d8e311bc09",
      "master_product_id": "e179b2b4-74a3-42ec-9b8d-326482188a65",
      "image_url": "/uploads/exemplo/cafeteira.png",
      "alt_text": "",
      "position": 0,
      "is_primary": true
    }
  ],
  "created_at": "2026-10-11T21:10:18.714345Z",
  "updated_at": "2026-10-11T21:10:18.714345Z"
}

200Lista

json

{
  "products": [
    {
      "id": "6b5806fe-4370-4f12-bc95-a7dbba04918b",
      "sku": "sd-001426",
      "name": "Cafeteira Moderno Branco 01426",
      "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c",
      "brand": "",
      "base_price": 80990,
      "features": { "Modelo": "220v" },
      "specifications": {},
      "status": "A",
      "offer_count": 1,
      "images": [],
      "created_at": "2026-07-23T14:30:14.156287Z",
      "updated_at": "2026-09-15T13:34:19.235744Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos do mestre

iduuid

Id do mestre.

skustring

SKU, em minúsculas. Ausente quando não definido.

namestring

Nome.

descriptionstring

Descrição em HTML.

short_descriptionstring

Resumo.

category_iduuid

Categoria principal.

category_namestring

Nome da categoria. Só na consulta de um mestre.

brandstring

Marca.

base_priceinteger

Preço sugerido, em centavos.

main_image_urlstring

Imagem principal.

featuresobject

Características livres.

specificationsobject

Ficha técnica livre.

statusstring

AHD

Status.

offer_countinteger

Ofertas ativas ligadas ao mestre, contadas na hora.

barcodestring

Código de barras.

quantityinteger

Estoque próprio.

min_quantityinteger

Mínimo por pedido.

max_quantityinteger

Máximo por pedido.

quantity_stepinteger

Múltiplo de compra.

additional_category_idsarray

Categorias extras. Só na consulta.

editable_fields_overridearray

Campos liberados ao seller. Ausente quando vale o padrão da loja.

imagesarray

Galeria (id, master_product_id, image_url, alt_text, position, is_primary). Na lista pode vir vazia.

descriptionsarray

Traduções. Só na consulta.

first_approved_atstring

Quando a primeira oferta ligada foi aprovada. Ausente enquanto nenhuma foi.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Sem `name`	`{"error":"name is required"}`
400	Sem `barcode`	`{"error":"barcode is required for master products","detail":"barcode_required: ..."}`
400	Imagem sem `image_url`	`{"error":"every image needs an image_url","detail":"image_url_required: ..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado, ou falta o privilégio	`{"error":"module_disabled","module":"master-products"}`
404	Recurso desligado na loja	`{"error":"feature not enabled","detail":"enable master_products via admin settings"}`
404	Mestre não existe (ou foi excluído)	`{"error":"master product not found"}`
409	SKU ou código de barras já em uso	`{"error":"código de barras 7899999000011 já está em uso pelo produto \"Cafeteira X\". Use outro código ou vincule este mestre ao produto existente.","detail":"..."}`
409	Excluir um mestre com ofertas	`{"error":"cannot delete: 1 vendor products are linked to this master product","detail":"unlink all vendor products first"}`
500	Sem `category_id`	`{"error":"failed to create master product","detail":"category_required: a category must be selected ..."}`
500	Id que não é UUID	`{"error":"failed to update master product","detail":"..."}`

A mensagem de 409 por código repetido vem em português do servidor.