API legada/Referência completa/Catálogo do app do vendedor

Produto: escrita

Cria e altera um produto do seller com nome, preço em reais, estoque, descrição e SKU.

Duas operações para o app do seller cadastrar e editar produtos: criar (POST /vendor_product, singular) e alterar (PUT /vendor_product/{id}). Preços entram como número em reais e são convertidos para centavos pelo servidor. A exclusão não está aqui: ela é um POST em /vendor_products, descrito em Produtos.

Criar um produto

POST/api/v1.0/vendor_productSeller

Criar um produto do seller

Cria o produto em nome do seller autenticado. Dependendo da regra de moderação da loja, o produto pode nascer aguardando aprovação (R) e só aparecer na vitrine depois de aprovado: confira o status com uma leitura.

Corpo da requisição

productstringobrigatório

Nome do produto.

pricenumber

Preço de venda em reais (49.9). Precisa ser número JSON: texto como "49.90" é ignorado e o preço fica zerado. Zero ou omitido: sem preço.

list_pricenumber

Preço "de" em reais, com a mesma regra de price.

descriptionstring

Descrição completa.

short_descriptionstring

Descrição curta.

amountnumber

Saldo inicial em estoque. Zero ou omitido: sem saldo.

skustring

Código do produto (SKU).

POST/api/vendor_productSeller

Alias de POST /api/v1.0/vendor_product

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/vendor_product. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

POST/api/v1.0/vn_product_apiSeller

Alias de POST /api/v1.0/vendor_product

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/vendor_product.

POST/api/vn_product_apiSeller

Alias de POST /api/v1.0/vendor_product

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/vendor_product. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Alterar um produto

PUT/api/v1.0/vendor_product/{id}Seller

Alterar um produto do seller

Altera só os campos enviados; o resto fica como estava. Diferente da criação, aqui zero é um valor: price: 0 zera o preço e amount: 0 zera o estoque. O produto precisa ser do seller autenticado.

Parâmetros de caminho

iduuidobrigatório

Id do produto. Na URL sem v1.0, o inteiro numérico não é aceito.

Corpo da requisição

productstring

Novo nome.

pricenumber

Novo preço em reais (número).

list_pricenumber

Novo preço "de" em reais.

descriptionstring

Nova descrição.

statusstring

ADH

Novo status: A ativo, D desativado, H oculto. As palavras active, disabled e hidden também são aceitas; outro valor é recusado com Update failed: ....

amountnumber

Novo saldo em estoque.

PUT/api/vendor_product/{id}Seller

Alias de PUT /api/v1.0/vendor_product/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/vendor_product/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

PUT/api/v1.0/vn_product_api/{id}Seller

Alias de PUT /api/v1.0/vendor_product/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/vendor_product/{id}.

PUT/api/vn_product_api/{id}Seller

Alias de PUT /api/v1.0/vendor_product/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/vendor_product/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Exemplo de requisição

bash

# Criar
curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/vendor_product" \
  -H "Content-Type: application/json" \
  -d '{"product":"Camiseta Básica Azul","price":49.9,"list_price":69.9,"description":"Camiseta de algodão.","short_description":"Camiseta azul","amount":20,"sku":"CAM-AZ-001"}'

# Alterar
curl -u "$EMAIL:$API_KEY" -X PUT "$BASE_URL/api/v1.0/vendor_product/$PRODUCT_ID" \
  -H "Content-Type: application/json" \
  -d '{"price":44.9,"amount":15}'

Resposta

200Produto criado

json

{
  "status": 200,
  "data": {
    "success": true,
    "message": "Product created successfully",
    "product_id": "3a2e6c1d-8f4b-4e55-9d0a-7b1c2e3f4a5b"
  }
}

200Produto alterado

json

{ "status": 200, "data": { "success": true, "message": "Product updated successfully" } }

Campos da resposta

data.successboolean

true se a operação deu certo.

data.messagestring

Product created successfully, Product updated successfully ou o motivo da falha.

data.product_iduuid

Id do produto criado. Só na criação. Na URL sem v1.0, um inteiro derivado do UUID.

Erros

Status	Quando	Corpo
200	Corpo inválido	`{"status": 200, "data": {"success": false, "message": "Invalid request body"}}`
200	Criação sem nome	`{"status": 200, "data": {"success": false, "message": "product name is required"}}`
200	Criação recusada por regra do catálogo	`{"status": 200, "data": {"success": false, "message": "Failed to create product: <motivo>"}}`
200	Alteração recusada por regra do catálogo	`{"status": 200, "data": {"success": false, "message": "Update failed: <motivo>"}}`
200	Alteração de produto inexistente	`{"status": 200, "data": {"success": false, "message": "Product not found"}}`
200	Alteração de produto de outro seller	`{"status": 200, "data": {"success": false, "message": "Access denied"}}`
200	Conta que não é de seller ativo	`{"status": 200, "data": {"success": false, "message": "User is not a vendor", "action": "logout"}}`
401	Sem credencial ou credencial inválida	`{"message": "Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.", "status": 401}`
403	Usuário cliente (não seller nem administrador)	`{"message": "Forbidden: vendor scope required", "status": 403}`

Veja também

API legada/Referência completa/Catálogo do app do vendedor

Produto: escrita

Cria e altera um produto do seller com nome, preço em reais, estoque, descrição e SKU.

Criar um produto

POST/api/v1.0/vendor_productSeller

Criar um produto do seller

Corpo da requisição

productstringobrigatório

Nome do produto.

pricenumber

Preço de venda em reais (49.9). Precisa ser número JSON: texto como "49.90" é ignorado e o preço fica zerado. Zero ou omitido: sem preço.

list_pricenumber

Preço "de" em reais, com a mesma regra de price.

descriptionstring

Descrição completa.

short_descriptionstring

Descrição curta.

amountnumber

Saldo inicial em estoque. Zero ou omitido: sem saldo.

skustring

Código do produto (SKU).

POST/api/vendor_productSeller

Alias de POST /api/v1.0/vendor_product

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/vendor_product. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

POST/api/v1.0/vn_product_apiSeller

Alias de POST /api/v1.0/vendor_product

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/vendor_product.

POST/api/vn_product_apiSeller

Alias de POST /api/v1.0/vendor_product

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/vendor_product. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Alterar um produto

PUT/api/v1.0/vendor_product/{id}Seller

Alterar um produto do seller

Parâmetros de caminho

iduuidobrigatório

Id do produto. Na URL sem v1.0, o inteiro numérico não é aceito.

Corpo da requisição

productstring

Novo nome.

pricenumber

Novo preço em reais (número).

list_pricenumber

Novo preço "de" em reais.

descriptionstring

Nova descrição.

statusstring

ADH

Novo status: A ativo, D desativado, H oculto. As palavras active, disabled e hidden também são aceitas; outro valor é recusado com Update failed: ....

amountnumber

Novo saldo em estoque.

PUT/api/vendor_product/{id}Seller

Alias de PUT /api/v1.0/vendor_product/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/vendor_product/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

PUT/api/v1.0/vn_product_api/{id}Seller

Alias de PUT /api/v1.0/vendor_product/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/vendor_product/{id}.

PUT/api/vn_product_api/{id}Seller

Alias de PUT /api/v1.0/vendor_product/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/vendor_product/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Exemplo de requisição

bash

# Criar
curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/vendor_product" \
  -H "Content-Type: application/json" \
  -d '{"product":"Camiseta Básica Azul","price":49.9,"list_price":69.9,"description":"Camiseta de algodão.","short_description":"Camiseta azul","amount":20,"sku":"CAM-AZ-001"}'

# Alterar
curl -u "$EMAIL:$API_KEY" -X PUT "$BASE_URL/api/v1.0/vendor_product/$PRODUCT_ID" \
  -H "Content-Type: application/json" \
  -d '{"price":44.9,"amount":15}'

Resposta

200Produto criado

json

{
  "status": 200,
  "data": {
    "success": true,
    "message": "Product created successfully",
    "product_id": "3a2e6c1d-8f4b-4e55-9d0a-7b1c2e3f4a5b"
  }
}

200Produto alterado

json

{ "status": 200, "data": { "success": true, "message": "Product updated successfully" } }

Campos da resposta

data.successboolean

true se a operação deu certo.

data.messagestring

Product created successfully, Product updated successfully ou o motivo da falha.

data.product_iduuid

Id do produto criado. Só na criação. Na URL sem v1.0, um inteiro derivado do UUID.

Erros

Status	Quando	Corpo
200	Corpo inválido	`{"status": 200, "data": {"success": false, "message": "Invalid request body"}}`
200	Criação sem nome	`{"status": 200, "data": {"success": false, "message": "product name is required"}}`
200	Criação recusada por regra do catálogo	`{"status": 200, "data": {"success": false, "message": "Failed to create product: <motivo>"}}`
200	Alteração recusada por regra do catálogo	`{"status": 200, "data": {"success": false, "message": "Update failed: <motivo>"}}`
200	Alteração de produto inexistente	`{"status": 200, "data": {"success": false, "message": "Product not found"}}`
200	Alteração de produto de outro seller	`{"status": 200, "data": {"success": false, "message": "Access denied"}}`
200	Conta que não é de seller ativo	`{"status": 200, "data": {"success": false, "message": "User is not a vendor", "action": "logout"}}`
401	Sem credencial ou credencial inválida	`{"message": "Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.", "status": 401}`
403	Usuário cliente (não seller nem administrador)	`{"message": "Forbidden: vendor scope required", "status": 403}`