Produtos

Um produto é o que a loja vende. Ele tem um nome, um preço, uma quantidade em estoque, uma categoria, imagens e um seller (lojista), que é a empresa dona da oferta e quem recebe o pedido. Todo ERP, PDV, marketplace e planilha de catálogo que conversa com a Venddor passa por esta seção: é aqui que você cria o produto, muda o preço, ajusta o estoque, desativa e consulta o que existe.

Esta seção documenta a API de administração do cadastro de produtos (/api/v1/admin/products...): dinheiro em centavos inteiros (4990), ids UUID, datas RFC 3339 e operações como clonar, histórico de alterações, lote, importação e variações.

Os recursos que moram "dentro" do produto têm seções próprias, para nenhuma página ficar longa demais: Mídia do produto, Variações e opções, Preço e estoque, Conteúdo e características e Lote, importação e exportação.

Como funciona

O ciclo de vida de um produto

O produto criado por um administrador já nasce no status que você pediu. O produto criado por um seller pode passar antes por moderação, se a loja tiver a pré-moderação ligada: ele nasce em R e só vira A quando alguém aprova.

O campo status é uma letra:

Além de status, a API devolve intended_status (a letra A, D ou H para a qual o produto volta quando for aprovado) e approval_status (pending, approved ou rejected), campo derivado do status. Em quase todas as rotas você pode mandar o nome longo no lugar da letra: active (A), disabled (D), hidden (H), pending (R) e rejected (X). A criação só aceita A, D e H; R e X pertencem ao fluxo de moderação.

Ter status: "A" é necessário, mas não suficiente para aparecer na loja. A vitrine também esconde produtos cujo seller está inativo, cuja categoria está desativada, com avail_since no futuro (data de lançamento) e, conforme a configuração da loja, sem estoque.

O fluxo típico de uma integração (ERP, catálogo)

1. Descobrir os ids de seller e categoria

   Antes de criar produtos, leia os sellers da loja e a árvore de categorias. Cada produto precisa de um vendor_id e de um category_id (UUID). Guarde-os na sua configuração.

2. Criar o produto

   Criar produto devolve o id. Grave esse id ao lado do seu código interno: ele é a chave de todas as chamadas seguintes. Mande sempre o sku: ele é único na loja, e uma repetição (por exemplo, depois de um timeout) volta como 409 em vez de duplicar o produto.

3. Complementar o cadastro

   Envie as imagens (Mídia), as características (Conteúdo), as faixas de preço e o estoque (Preço e estoque) e, se for o caso, as variações (Variações e opções).

4. Manter preço e estoque em dia

   Alterar produto muda só os campos que você enviar. Para muitos produtos de uma vez, use o lote em vez de um laço de PUTs.

5. Acompanhar mudanças

   Histórico de alterações mostra quem mudou preço, nome, status e outros campos, e quando.

Conceitos-chave

Autenticação

Faça login (POST /api/v1/auth/login com {"email","password"}) e use access_token como Bearer. O login tem limite de requisições (429): guarde o token e reaproveite-o até expirar. A leitura exige o privilégio view_catalog ou manage_catalog; a escrita exige manage_catalog.

Ids: UUID, número curto e SKU

Cada produto tem três identificadores, e só um deles serve de {id} na URL:

• id (UUID, 36 caracteres): a chave da API. Em PUT e DELETE, qualquer outro valor é recusado. A consulta também aceita o slug.
• display_id (inteiro, como 10499): o número curto que o painel mostra. É só para leitura humana; a API não o aceita como {id}.
• sku (texto): o código do produto. Veja a seção seguinte.

SKU e código do produto

O sku é o código que a sua empresa usa para o item. Ele é único na loja inteira (não só por seller), e reutilizar o SKU de outro produto devolve 409. O SKU de um produto excluído pode ser reutilizado. O sku é opcional: sem ele, o produto fica sem código.

O filtro sku da lista contém o texto (sem diferenciar maiúsculas), não exige igualdade.

Outros códigos que o produto pode ter: barcode (EAN/GTIN, com regras de unicidade e obrigatoriedade configuráveis por loja), vendor_internal_sku (código interno do seller) e ncm_code (8 dígitos, fiscal, usado na NF-e).

Dinheiro

Todo valor de dinheiro é inteiro em centavos: 4990 é R$ 49,90. Os campos de dinheiro do produto são price (preço de venda), list_price (preço "de", o valor riscado que a loja mostra antes da promoção) e cost_price (custo), e shipping_freight (frete fixo). Cada produto também traz price_str e list_price_str em decimal, só para leitura.

O servidor tolera clientes que erram a unidade: um número com casas decimais (49.90) é lido como reais e vira 4990, e uma string como "R$ 49,90" também é aceita. Mesmo assim, envie sempre o inteiro em centavos: 49 sem casas decimais é R$ 0,49.

Estas regras valem para todos os campos: preço zero é permitido (veja zero_price_action) e negativo é recusado; o list_price, quando maior que zero, não pode ser menor que o price (list_price_below_price).

Estoque

• quantity é a quantidade disponível na unidade de venda do produto.
• track_inventory liga o controle de estoque.
• sale_unit é a unidade de venda: un (padrão), kg, cx, l, par ou um texto livre (com sale_unit_label para o rótulo). Com allow_fractional: true o cliente pode comprar meia unidade (0,5 kg).
• min_quantity, max_quantity e quantity_step limitam a compra: mínimo, máximo (0 = sem limite) e múltiplo (quantity_step: 6 vende de seis em seis).
• low_stock_alert é o limite de "estoque baixo" usado pelos alertas e pelo filtro low_stock.
• out_of_stock_action diz o que a loja faz com o produto zerado: N esconde o botão de compra, B aceita encomenda (back-order), S mostra o formulário "avise-me quando chegar" (padrão na criação pela API).

Alterar quantity por PUT grava um movimento no extrato de estoque (com o motivo de stock_adjust_reason). Para ajustes de estoque dedicados, veja Preço e estoque.

O preço zero e zero_price_action

O que acontece quando um produto custa R$ 0,00 é decisão do campo zero_price_action, cobrada quando o cliente tenta colocar o item no carrinho: P vende normalmente por zero, R bloqueia a compra online e A exige que o cliente peça um orçamento. O padrão na criação pela API é R, que protege contra um produto "de graça" por engano.

Seller, catálogo mestre e ofertas

A loja pode ser um marketplace, com vários sellers vendendo na mesma vitrine. Dois conceitos importam aqui:

• Produto de seller (oferta). É o produto comum, com vendor_id do seller. O preço, o estoque, o SKU e o status são do seller.
• Produto mestre. Um cadastro único de um item (nome, descrição, imagens, características, EAN) compartilhado por várias ofertas. Cada oferta aponta para o mestre em master_product_id. Os campos que o mestre controla (por exemplo nome, descrição e categoria, conforme a configuração da loja) são ignorados quando você os envia num PUT de uma oferta ligada. A API de catálogo mestre fica na referência completa; aqui você usa Ligar a um mestre para ligar e desligar uma oferta.

A lista de produtos de administração (/api/v1/admin/products) mostra ofertas de sellers e produtos sem seller, e deixa de fora os cadastros mestres.

Categorias

Todo produto tem uma categoria principal (category_id, obrigatória) e pode ter categorias adicionais (additional_category_ids). Para trocar as categorias de um produto já criado, veja Categorias do produto. Uma categoria desativada esconde seus produtos da loja.

Imagens, características e variações

• Imagens e vídeos ficam na seção Mídia do produto. A resposta do produto já traz a lista images.
• Características (marca, cor, material, voltagem...) descrevem o produto e alimentam os filtros da loja. Ficam em Conteúdo e características.
• Opções (um campo que o cliente escolhe na compra, como "gravação") e variações (cada tamanho/cor é um produto filho com SKU, preço e estoque próprios) ficam em Variações e opções. Um produto-pai de variações tem is_variation: false e filhos com is_variation: true; a lista de administração traz pais e filhos.

Idiomas

Nome e descrições existem por idioma. O objeto descriptions (chave = código do idioma, como pt-BR ou en) traz, por idioma, name, description, short_description, promo_text, highlight_text, seo_title, seo_description e meta_keywords. No PUT, só as chaves de idioma que você enviar são regravadas. Sem descriptions, os campos planos (name, description) valem para o idioma padrão.

Exclusão suave e lixeira

DELETE não apaga: marca o produto como excluído e o envia para a lixeira, de onde um administrador pode restaurá-lo por 30 dias. Depois disso a limpeza automática o remove de vez. Os vínculos (categorias, características, imagens) são preservados para a restauração ser completa. O SKU volta a ficar livre assim que o produto vai para a lixeira.

Recursos opcionais da loja

Algumas rotas dependem de um recurso que a loja precisa ter ligado (por exemplo, o catálogo mestre e o cálculo de embalagem dos Correios). Quando está desligado, a rota responde 403 ou 404 com a mensagem do recurso. As páginas dizem quais rotas são assim.

Endpoints

Auth: Admin é um administrador (Bearer).

As rotas aninhadas do produto estão nas outras seções:

Erros comuns

1. Criar produto sem vendor_id ou sem category_id. Os dois são obrigatórios. Sem seller a resposta é 400 vendor_required; sem categoria, 400 category_required.
2. Usar o SKU ou o display_id como {id} na URL. O {id} é o UUID. Em PUT a resposta é 400 invalid product id, e a mensagem explica de onde sai o UUID.
3. Mandar dinheiro na unidade errada. Envie centavos inteiros (4990), nunca 49.90: 49 sem casas decimais é R$ 0,49.
4. Tratar o DELETE como definitivo. Ele envia o produto para a lixeira por 30 dias. A exclusão permanente é feita no painel.
5. Editar o nome ou a descrição de uma oferta ligada a um mestre e achar que salvou. Os campos que o mestre controla são ignorados em silêncio. Edite o mestre.
6. Repetir POST depois de um timeout sem sku. Sem um código único o servidor não tem como reconhecer o repetido, e o produto é duplicado.

Próximos passos