API atual/Referência completa/Produtos do seller

Criar produto

Cadastra um produto novo no catálogo do seller, que fica pendente de aprovação se a loja usa premoderação.

Crie o produto com os dados essenciais e complemente depois: imagens em Imagens, características em Características, variações na seção de variações. O produto nasce com o seu vendor_id; um vendor_id no corpo é descartado.

POST/api/v1/vendor/productsSeller

Criar um produto

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

namestringobrigatório

Nome do produto, até 255 caracteres. Tags HTML são removidas.

category_idstring (uuid)obrigatório

Categoria principal. Obrigatória: produto sem categoria some da navegação.

priceintegerobrigatório

Preço em centavos. Não pode ser negativo; zero é aceito.

additional_category_idsarray of string

Outras categorias onde o produto também aparece.

slugstring

Trecho da URL. Se vazio, nasce do nome. Se já existir, a plataforma acrescenta -2, -3...

descriptionstring

Descrição em HTML. O HTML é sanitizado.

short_descriptionstring

Resumo curto.

skustring

SKU. Único na loja: repetido volta 409.

barcodestring

EAN/GTIN. Único na loja; obrigatório se a loja exigir.

list_priceinteger

Preço "De" em centavos. Se informado e maior que zero, não pode ser menor que price.

cost_priceinteger

Custo em centavos.

quantitynumber

Estoque inicial.

statusstringpadrão: A

ADH

Status pretendido: A, D ou H (ou active, disabled, hidden). Vazio = A. R e X são recusados.

weightnumber

Peso em kg. Não pode ser negativo.

widthnumber

Largura em cm.

heightnumber

Altura em cm.

lengthnumber

Comprimento em cm.

free_shippingboolean

Frete grátis no produto.

shipping_freightinteger

Frete extra do produto em centavos.

requires_shippingbooleanpadrão: true

false para produto digital.

ncm_codestring

NCM de 8 dígitos.

meta_keywordsstring

Palavras-chave de SEO.

min_quantitynumber

Quantidade mínima por pedido.

max_quantitynumber

Quantidade máxima por pedido. Se também houver mínimo, não pode ser menor que ele.

quantity_stepnumber

Passo de quantidade.

sale_unitstring

Unidade de venda (un, kg...).

sale_unit_labelstring

Rótulo da unidade mostrado ao cliente.

allow_fractionalboolean

Permite quantidade fracionada.

usergroup_idsarray of string

Restringe a visibilidade a estes grupos de clientes. Vazio = todos veem.

zero_price_actionstringpadrão: R

PRA

Preço zero: P, R ou A.

out_of_stock_actionstringpadrão: S

NBS

Sem estoque: N, B ou S.

low_stock_alertinteger

Limite de alerta de estoque baixo.

search_wordsstring

Palavras extras para a busca.

promo_textstring

Texto promocional perto do botão de compra.

avail_sincestring

Data (RFC 3339) a partir da qual o produto aparece. Serve para pré-venda.

vendor_internal_skustring

Seu código interno, que não aparece para o cliente.

whatsapp_hiddenboolean

Esconde só do catálogo do WhatsApp.

descriptionsobject

Conteúdo por idioma, chaves como pt-BR e en, cada uma com name, description, short_description.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Camiseta Básica Algodão Preta",
  "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
  "sku": "CAM-001",
  "price": 4990,
  "list_price": 5990,
  "quantity": 25,
  "status": "A",
  "description": "<p>Camiseta 100% algodão.</p>",
  "weight": 0.25,
  "width": 30,
  "height": 2,
  "length": 40
}'

Resposta

201Produto criado

json

{
  "id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "display_id": 10664,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
  "name": "Camiseta Básica Algodão Preta",
  "slug": "camiseta-basica-algodao-preta",
  "sku": "CAM-001",
  "barcode": "7891234567895",
  "description": "<p>Camiseta 100% algodão.</p>",
  "short_description": "Camiseta 100% algodão",
  "price": 4990,
  "list_price": 5990,
  "track_inventory": true,
  "quantity": 25,
  "low_stock_alert": 5,
  "min_quantity": 0,
  "max_quantity": 0,
  "quantity_step": 1,
  "sale_unit": "un",
  "zero_price_action": "P",
  "popularity": 0,
  "out_of_stock_action": "N",
  "weight": 0.25,
  "width": 30,
  "height": 2,
  "length": 40,
  "status": "A",
  "intended_status": "A",
  "approval_status": "approved",
  "view_count": 0,
  "sales_count": 0,
  "rating_avg": 0,
  "rating_count": 0,
  "free_shipping": false,
  "shipping_freight": 0,
  "requires_shipping": true,
  "vendor_name": "Loja Seller Teste",
  "vendor_slug": "loja-seller-teste",
  "created_at": "2026-10-11T20:56:24.231132Z",
  "updated_at": "2026-10-11T21:05:40.573283Z"
}

Campos da resposta

(corpo)object

O produto criado, com os mesmos campos de Consultar produto. Confira status e intended_status.

Erros

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
400	Falta nome, categoria ou preço é negativo.	`{"error":"validation_failed","fields":{"category_id":"category_required"}}`
400	Status inválido (inclusive `R` e `X`).	`{"error":"invalid product status","detail":"..."}`
400	Regra de negócio: `list_price_below_price`, `name_required`, `name_too_long`, `physical_shipping_data_required`, peso/medida/quantidade negativos, `zero_price_action` ou `out_of_stock_action` inválidos.	`{"error":"list_price_below_price","detail":"list_price (4000) must be >= price (4990)"}`
400	A loja exige EAN e ele não foi enviado.	`{"error":"barcode_required: product barcode (EAN/GTIN) is required on this store"}`
403	A loja só deixa o seller vender produtos do catálogo mestre.	`{"error":"vendor_normal_product_blocked","detail":"..."}`
409	SKU, nome/slug ou EAN já usados na loja.	`{"error":"a product with this SKU already exists"}`

Veja também