Produtos do seller

Este é o catálogo do seller (lojista): o vendedor que opera dentro do marketplace da loja com produtos, pedidos e financeiro próprios. As rotas de /api/v1/vendor/products deixam o seller criar, alterar, publicar e organizar os seus produtos, e é por elas que o painel do seller e as integrações de catálogo trabalham. O seller nunca vê nem altera produto de outro seller ou da própria loja.

Como funciona

O ciclo de vida de um produto do seller depende de a loja ligar a premoderação. Com ela ligada, tudo que o seller publica passa por revisão:

Você só escolhe A, D ou H. R e X pertencem ao fluxo de moderação: ao criar, o status que você pede vira o intended_status (o destino depois da aprovação) e o produto nasce R. Sem premoderação ele nasce direto no status pedido, e A se você não disser nada.

Conceitos importantes

Dinheiro

Todo valor monetário do produto (price, list_price, cost_price, shipping_freight) é um inteiro em centavos. Na entrada, o decodificador também aceita decimais (49.9 vira 4990) e textos como "R$ 49,90". Um inteiro puro sempre vale centavos. Mande sempre inteiros para evitar surpresa.

Quem pode chamar

Além de ser seller, o usuário precisa de um privilégio de catálogo (por exemplo vendor_catalog ou vendor_manage_products). O privilégio de leitura vendor_view_catalog também abre as rotas de escrita desta seção, então não o conceda a quem não deve alterar produtos. Seller em análise de cadastro recebe 403 com vendor_pending_review.

Produto do catálogo mestre

O catálogo mestre é uma lista de produtos curada pela loja (nome, descrição, imagem, características). Um produto do seller ligado a um mestre herda esses dados, e só preço, estoque, SKU interno e medidas de envio continuam livres. Ver Catálogo mestre.

Variações, opções e preços por quantidade

Variações (produtos filhos), opções de compra, escalas de preço e produtos obrigatórios têm a própria seção: Variações e opções.

Endpoints

Erros comuns

1. Mandar 50 esperando R$ 50,00. Inteiro é centavos: use 5000.
2. Esquecer a categoria. category_id é obrigatório na criação; sem ele a resposta é 400 validation_failed.
3. Esperar o produto ativo logo após criar. Com premoderação ele fica R. Leia status e intended_status na resposta.
4. Ativar produto físico sem peso e medidas em loja que exige dados de frete: volta physical_shipping_data_required. Salve como D até completar.
5. Editar campo travado de produto do catálogo mestre. Volta 409 com locked_fields.
6. Usar o token de administrador. Estas rotas são só de seller; o administrador usa /api/v1/admin/products.
7. Reenviar price zerado achando que é erro. Preço zero é aceito; o que acontece na compra depende de zero_price_action.

Próximos passos