Produtos (REST)

A API de Produtos gerencia todo o ciclo de vida dos produtos da sua loja Venddor. Você pode criar, consultar, atualizar e excluir produtos e gerenciar as entidades relacionadas: variações, opções, imagens e características.

Esta seção é a parte REST da API Venddor 1.0. Ela trabalha nas URLs genéricas de objeto (/api/products e, na API 2.0, /api/2.0/products) e usa as mesmas credenciais HTTP Basic do restante da API: o e-mail do administrador e a chave de API. Nos exemplos, $BASE_URL é o endereço do e-commerce da sua loja, $EMAIL é o e-mail do administrador e $API_KEY é a chave de API.

Como funciona

Um produto é um único objeto JSON. Abaixo está a estrutura básica, exatamente como a referência a mostra. O texto depois de // é a explicação da própria referência para o código e não faz parte do JSON que você envia.

{
  "product_id": "423",
  "product_code": "LAPTOP-PRO-15",
  "product": "Professional Laptop 15\"",
  "company_id": "1",
  "product_type": "P",  // P - physical, D - digital, S - service
  "status": "A",        // A - active, D - disabled, H - hidden
  "list_price": "1499.99",
  "price": "1299.99",
  "category_ids": ["42", "56"],
  "main_category": "42",
  "tax_ids": ["3"],
  "tracking": "B",      // B - track with options, O - track without options
  "amount": "100",
  "weight": "2.1",
  "length": "14.2",
  "width": "9.8",
  "height": "0.8",
  "shipping_freight": "0",
  "is_edp": "N",        // Y - downloadable product, N - not downloadable
  "edp_shipping": "N",   // Y - requires shipping, N - no shipping
  "unlimited_download": "N",
  "free_shipping": "N",
  "zero_price_action": "R",  // R - require selection, P - allow add to cart
  "product_features": {
    // Features array
  },
  "main_pair": {
    // Main image details
  },
  "image_pairs": {
    // Additional images
  },
  "short_description": "Powerful laptop for professional use",
  "full_description": "Detailed product description...",
  "meta_keywords": "laptop, professional, business",
  "meta_description": "High-performance laptop for business professionals",
  "search_words": "notebook computer laptop business",
  "page_title": "Professional Laptop 15\" - High Performance",
  "options": [
    // Product options array
  ],
  "product_options": [
    // Available options IDs
  ],
  "variation_features": [
    // Variation features
  ]
}

Uma integração típica segue a ordem que a referência recomenda para produtos com variações e opções:

1. Crie o produto base
   Envie POST /api/2.0/products com os campos do produto.
2. Adicione opções e variações
   Use POST /api/2.0/products/{product_id}/options para cada opção. Veja Opções do produto.
3. Adicione imagens e características
   Use POST /api/2.0/products/{product_id}/images e POST /api/2.0/products/{product_id}/features. Veja Características do produto.

Códigos usados na estrutura

Esses são os significados escritos nos comentários da estrutura acima. A página Campos do produto descreve os mesmos campos com redação própria; use essa página ao criar ou atualizar um produto.

Conceitos principais

Textos e identificadores

Identificadores e preços voltam como texto ("product_id": "423", "price": "1299.99"). Os identificadores de categoria e de imposto são listas de textos ("category_ids": ["42", "56"]).

Objetos aninhados

product_features, main_pair e image_pairs são objetos aninhados, e options, product_options e variation_features são listas. Veja Objetos aninhados e Campos do produto.

Palavras de busca

Operações principais de produto

Endpoints relacionados

Imagens do produto

Características e opções do produto

As características e as opções de um produto têm seções próprias:

• GET e POST /api/2.0/products/{product_id}/features estão em Características do produto.
• GET e POST /api/2.0/products/{product_id}/options estão em Opções do produto.

Endpoints

Erros comuns e boas práticas

• Não conte com campos que não estão na referência: qualquer campo que não conste na página Campos do produto é ignorado.
• Use um sistema lógico e consistente para os códigos de produto.
• Informe sempre títulos, descrições e palavras-chave pensados para SEO.
• Garanta que cada produto esteja categorizado corretamente.
• Envie imagens com dimensões e compressão adequadas.
• Use as características do produto para detalhar as especificações.
• Controle o estoque com a configuração de tracking adequada.

Próximos passos