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, desativa e consulta o que existe.

Esta seção documenta o cadastro de produtos da API legada, compatível com a Venddor 1.0 (/api/v1.0/products...). Ela segue o contrato da Venddor 1.0, para clientes que já foram escritos para a plataforma antiga: dinheiro em string decimal ("49.90"), status em letra (A, D, H) e campos com os nomes de sempre (product, product_code, amount).

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 e Conteúdo e características.

Como funciona

O ciclo de vida de um produto

O produto criado por um administrador já nasce ativo. O produto criado por um seller pode passar antes por moderação, se a loja tiver a pré-moderação ligada: ele nasce aguardando aprovação e só vira ativo quando alguém aprova.

O campo status é uma letra:

Esta API só entende A, D e H. 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 seller (company_id) e de uma categoria (main_category), ambos UUID. Guarde-os na sua configuração.

2. Criar o produto

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

3. Complementar o cadastro

   Consulte as imagens (Mídia), as características (Conteúdo), as opções e 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.

Conceitos-chave

Autenticação

Um administrador gera uma chave de API para o próprio usuário no painel. Você envia Authorization: Basic base64(e-mail:chave) em toda chamada. Authorization: Bearer <JWT> também funciona. As leituras (GET) aceitam qualquer usuário autenticado; criar, alterar e excluir exigem administrador (senão, 403 Forbidden: admin scope required). A mesma rota responde com e sem /v1.0 (/api/products e /api/v1.0/products), com maiúsculas ou minúsculas e com barra no final.

Para apps de terceiros, sem usuário, veja Produtos por token de app.

Ids: UUID, número curto e código

Cada produto tem um product_id, que é um UUID de 36 caracteres e é a chave da API. Em PUT e DELETE, qualquer outro valor é recusado.

Na forma sem versão (/api/products), pensada para clientes que esperam o id inteiro da Venddor 1.0, todos os ids saem como números decimais dentro de uma string ("77051560"), derivados do UUID, e também são aceitos na entrada (caminho, query e corpo). O UUID continua aceito. Não misture as duas formas no mesmo cliente: escolha uma.

Código do produto

O product_code é o código que a sua empresa usa para o item (o SKU). Ele é único na loja inteira (não só por seller), e reutilizar o código de outro produto devolve erro. O código de um produto excluído pode ser reutilizado. Ele é opcional: sem ele, o produto fica sem código. O filtro product_code da lista contém o texto (sem diferenciar maiúsculas), não exige igualdade.

Dinheiro

Todo valor é string decimal com ponto e duas casas ("49.90"). Na entrada a API aceita "49,90" (vírgula decimal) e "1.234,56" (com vírgula presente, o ponto é milhar). Atenção: sem vírgula, um único ponto é decimal, então "1.000" vale R$ 1,00, não mil. E um texto que não é número ("abc") vale zero em silêncio, sem erro. Os campos de dinheiro do produto são price (preço de venda) e list_price (preço "de", o valor riscado que a loja mostra antes da promoção). O frete fixo (shipping_freight) é o único valor em centavos inteiros.

Preço zero é permitido e negativo é recusado.

Estoque

• amount é a quantidade disponível na unidade de venda do produto. A API só enxerga inteiros: ela arredonda para baixo.
• tracking (Y ou N) indica se o produto controla estoque.
• min_qty, max_qty e qty_step limitam a compra: mínimo, máximo (0 = sem limite) e múltiplo (qty_step: 6 vende de seis em seis).

Alterar amount por PUT grava um movimento no extrato de 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. A criação por esta API não lê o campo, então o produto nasce com o padrão R, que protege contra um produto "de graça" por engano.

Seller

A loja pode ser um marketplace, com vários sellers vendendo na mesma vitrine. Nesta API, company_id é o id do seller dono do produto; o valor "0" quer dizer produto sem seller. Os campos de preço, estoque, código e status são do seller.

Categorias

Todo produto tem uma categoria principal (main_category, obrigatória) e pode ter categorias adicionais. Na leitura elas aparecem como main_category e category_ids (a principal primeiro). Para ler as categorias de um produto, veja Categorias do produto. Uma categoria desativada esconde seus produtos da loja.

Imagens, características e variações

• Imagens ficam na seção Mídia do produto. A resposta do produto já traz main_pair e image_pairs.
• 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 código, preço e estoque próprios) ficam em Variações e opções.

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 código volta a ficar livre assim que o produto vai para a lixeira.

Endpoints

Auth: Admin é um administrador (Basic ou Bearer). App é o token de app.

Cada rota /api/v1.0/... também responde sem a versão, como /api/products....

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

Erros comuns

1. Criar produto sem company_id ou sem main_category. Os dois são obrigatórios. Sem seller a resposta é 400 vendor_required; sem categoria, 400 category_required.
2. Usar o código do produto como {id} na URL. O {id} é o UUID (ou o id decimal, na rota sem versão).
3. Mandar dinheiro no formato errado. Envie string decimal ("49.90"). "abc" vira R$ 0,00 sem erro e "1.000" vira R$ 1,00.
4. Filtrar a lista sem status e achar que só vêm produtos ativos. Sem o filtro a lista traz todos os status (ativo, oculto, desativado e aguardando aprovação). Filtre status=A para a vitrine.
5. Mandar status ao criar. O campo é ignorado na criação. Com a pré-moderação ligada o produto nasce aguardando aprovação (a API o mostra como H).
6. Tratar o DELETE como definitivo. Ele envia o produto para a lixeira por 30 dias. A exclusão permanente é feita no painel.
7. Ler amount como se fosse exato para produtos fracionados. amount é inteiro e arredonda para baixo (2,5 kg aparece como 2).
8. Repetir POST depois de um timeout sem product_code. Sem um código único o servidor não tem como reconhecer o repetido, e o produto é duplicado.

Próximos passos