Criar produto

Cadastra um produto novo com seller, categoria, preço e estoque, e devolve o id para as chamadas seguintes.

Use esta operação para colocar um item no catálogo: um ERP que publica um produto novo, um sistema de catálogo que sincroniza a base, um cadastro por planilha. A criação grava o produto, gera o slug da URL a partir do nome, registra o estoque inicial e aciona a indexação para a busca da loja. Para criar milhares de produtos de uma vez, crie-os em um laço, um POST por produto, respeitando o limite de requisições.

Dois campos são obrigatórios além do nome: o seller (quem vende o item) e a categoria. Sem seller o produto não pode ser comprado (o carrinho o recusa), e sem categoria ele some da navegação da loja; por isso a criação rejeita os dois. Imagens, características, variações e faixas de preço são enviadas depois, pelas rotas de cada assunto (veja Produtos).

POST/api/v1.0/productsAdmin

Criar um produto

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>. A rota também responde em /api/products; nessa forma company_id, main_category e category_ids podem ir como ids decimais. Os nomes dos campos são os da Venddor 1.0 (product, product_code, amount...). Chaves que a rota não conhece são ignoradas sem erro.

Corpo da requisição

productstringobrigatório

Nome do produto, até 255 caracteres. HTML e caracteres de controle são removidos.

company_idstringobrigatório

Id do seller (UUID; na rota /api/products, o id decimal). vendor_id é aceito como sinônimo. "0" ou vazio conta como ausente e a criação é recusada.

main_categorystring

Id da categoria principal (UUID; ou decimal em /api/products). É obrigatório informar main_category ou category_ids.

category_idsarray

Lista de ids de categoria. Sem main_category, o primeiro vira a principal e os demais, adicionais. Com main_category, os diferentes dela viram adicionais.

pricestring

Preço de venda, em string decimal ("49.90"; também aceita "49,90"). Um número JSON é lido em reais (49.9 = R$ 49,90, 49 = R$ 49,00). Texto que não é número vira R$ 0,00 sem erro. Padrão: zero.

list_pricestring

Preço "de" (riscado), mesmo formato de price. Se maior que zero, não pode ser menor que price.

product_codestring

Código do produto (SKU). Único na loja.

full_descriptionstring

Descrição completa, em HTML (scripts e atributos perigosos são removidos).

short_descriptionstring

Descrição curta.

seo_namestring

Slug da URL. Sem ele, o slug sai do nome; em caso de repetição a plataforma acrescenta -2, -3...

amountstring

Estoque inicial, inteiro (string "12" ou número 12). Uma string que não é inteira ("7.5") é ignorada e o estoque fica zero.

weightstring

Peso em kg ("0.350" ou número). Não pode ser negativo.

free_shippingstringpadrão: N

YN

Y para frete grátis.

min_qtyinteger

Quantidade mínima por compra. 0 = sem mínimo.

max_qtyinteger

Quantidade máxima por compra. 0 = sem máximo. Não pode ser menor que min_qty quando os dois são positivos.

qty_stepintegerpadrão: 1

Múltiplo de compra.

meta_keywordsstring

Palavras-chave SEO.

search_wordsstring

Termos extras para a busca da loja.

promo_textstring

Texto promocional mostrado acima do botão de compra.

A criação não lê status, page_title, meta_description, zero_price_action nem as dimensões (length, width, height, que só aparecem na leitura).

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/products" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Caneca Esmaltada 350 ml",
    "product_code": "CAN-350-AZ",
    "price": "49.90",
    "list_price": "59.90",
    "amount": 12,
    "weight": "0.350",
    "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "main_category": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
    "full_description": "<p>Caneca esmaltada azul.</p>"
  }'

Resposta

201Produto criado

json

{ "product_id": "dfe61315-f681-400d-836b-d507c76645be" }

Campos da resposta

product_idstring

Id do novo produto. UUID em /api/v1.0; decimal em string em /api/products.

Erros

Status	Quando	Corpo
400	JSON inválido, ou número em formato inválido	`{"message":"Invalid JSON: invalid character 'b' looking for beginning of object key string","status":400}`
400	Sem nome	`{"message":"product (name) is required","status":400}`
400	Sem seller	`{"message":"vendor_required: um vendedor precisa ser escolhido...","status":400}`
400	Sem categoria	`{"message":"category_required: a category must be selected...","status":400}`
400	Regra de negócio violada: `list_price` menor que `price`, nome com mais de 255 caracteres, peso, dimensão ou quantidade negativos, `max_quantity` menor que `min_quantity`, código do produto ou de barras repetido, código de barras exigido pela loja, dados de frete incompletos em produto físico ativo, `company_id` ou `main_category` inexistentes	`{"message":"<código>: <texto>","status":400}`. O texto vem do serviço de catálogo e pode estar em português ou inglês
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Usuário sem permissão de escrita	`{"message":"Forbidden: admin scope required","status":403}`
429	Limite de requisições (por exemplo, login repetido)	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`

Os erros do serviço de catálogo saem como 400 com message (no formato codigo: texto), inclusive o código de produto repetido. Mensagens que o servidor devolve em português ficam como são devolvidas.

Veja também