API legada/Referência completa/API 4.0 (app móvel)

Produtos

Lista, busca e filtra produtos, lista promoções e produtos de uma categoria e lê a ficha de um produto, no formato do app móvel.

Estas quatro rotas alimentam as telas de lista, busca, promoção e detalhe do app. Todas são anônimas (a ekey é opcional) e só devolvem produtos ativos que a vitrine mostra. Com a ekey, o preço e a visibilidade seguem o grupo do cliente logado.

Todas as listas devolvem o mesmo cartão de produto (veja os campos abaixo) dentro de products, mais params com a paginação. A ficha de um produto devolve o cartão direto.

GET/api/4.0/sra_productsPública

Listar e buscar produtos

Os resultados vêm na ordem do catálogo, a menos que você peça sort_by.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

items_per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Acima de 100 vira 100. (per_page e limit são sinônimos.)

searchstring

Texto de busca. q é um sinônimo.

category_idstring

Só produtos desta categoria (id decimal ou UUID). Categoria desconhecida devolve lista vazia.

subcatsstring

Yyestrue1

Inclui os produtos das subcategorias. (include_subcategories=true faz o mesmo.)

company_idstring

Só produtos deste seller. vendor_id é um sinônimo; seller desconhecido devolve lista vazia.

sort_bystring

productpriceamountpopularityratingtimestamp

Campo de ordenação. Também são aceitos name, list_price, quantity, rating_avg, created_at, position e code.

sort_dirstring

ascdesc

Direção. sort_order é um sinônimo. Outro valor usa a direção padrão do campo.

on_saleboolean

truefalse

Só produtos em promoção.

in_stockboolean

true

Só produtos com estoque.

exclude_variationsbooleanpadrão: true

truefalse

Por padrão as variações (tamanho, cor) ficam de fora e só o produto principal aparece. false, 0, n ou no incluem as variações como produtos.

variation_group_idstring

Só os produtos deste grupo de variações. Já inclui as variações.

features[ID]string

Filtro por característica: features[12]=34,35 traz produtos com a variante 34 ou 35 da característica 12. Pode repetir para várias características.

features_hashstring

Os mesmos filtros de característica em formato compacto, como o app 1.0 os enviava.

GET/api/4.0/sra_products/{id}Pública

Ficha de um produto

Devolve o cartão do produto, incluindo variation_features_variants quando o produto tem variações. Produto inexistente ou que não está ativo responde 404.

Parâmetros de caminho

idstringobrigatório

Id do produto (decimal ou UUID).

GET/api/4.0/sra_products_discountedPública

Produtos em promoção

Igual a GET /api/4.0/sra_products com on_sale ligado. Aceita todos os mesmos parâmetros.

GET/api/4.0/categories/{id}/sra_productsPública

Produtos de uma categoria

Igual a GET /api/4.0/sra_products com a categoria vinda do caminho. Aceita os mesmos parâmetros e mais um.

Parâmetros de caminho

idstringobrigatório

Id da categoria (decimal ou UUID). Categoria desconhecida responde 404.

Parâmetros de consulta

get_filtersboolean

true1yyes

Inclui em filters as características e variantes disponíveis na categoria, para montar a tela de filtros.

Exemplo de requisição

bash

curl "$BASE_URL/api/4.0/sra_products?search=caneca&sort_by=price&sort_dir=asc&items_per_page=20"

Com a ekey do cliente (preços do grupo dele):

bash

curl "$BASE_URL/api/4.0/categories/878363454/sra_products?get_filters=true&items_per_page=20" \
  -H "Authorization: Basic $(printf '%s' "$CUSTOMER_TOKEN" | base64 -w0):"

Resposta

200Lista de produtos

json

{
  "products": [
    {
      "product_id": "1585658495",
      "product": "Caneca Esmaltada 350ml",
      "product_code": "CAN-350",
      "price": 52.9,
      "price_formatted": { "price": "52.90" },
      "list_price": 52.9,
      "list_price_formatted": { "price": "52.90" },
      "min_qty": 0,
      "qty_step": 1,
      "amount": 5,
      "in_stock": 1,
      "company_id": "347963034",
      "company_name": "Loja Exemplo",
      "category_ids": ["878363454", "2126275725"],
      "discounts": { "A": 0, "P": 0 },
      "free_shipping": "N",
      "full_description": "Caneca de aço esmaltado, 350 ml.",
      "product_options": {},
      "product_features": {},
      "variation_features": {},
      "variation_feature_ids": {},
      "variation_features_variants": {},
      "main_pair": {
        "icon": {
          "image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400",
          "http_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400",
          "https_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400"
        },
        "detailed": {
          "image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png",
          "http_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png",
          "https_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png"
        },
        "icons": {
          "500x500": {
            "image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400",
            "http_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400",
            "https_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400"
          }
        }
      }
    }
  ],
  "params": { "page": 1, "items_per_page": 20, "total_items": 4981 }
}

Campos da resposta

products[].product_idstring

Id decimal do produto.

products[].productstring

Nome do produto.

products[].product_codestring

SKU. Vazio quando não há.

products[].pricenumber

Preço de venda atual em reais, já com desconto de catálogo e preço do grupo do cliente.

products[].price_formatted.pricestring

O mesmo preço com duas casas, como texto.

products[].list_pricenumber

Preço de tabela em reais (o "de"). Igual a price quando não há desconto.

products[].min_qtynumber

Quantidade mínima por compra. 0 é sem mínimo.

products[].qty_stepnumber

Múltiplo da quantidade (de quanto em quanto se pode comprar). Padrão 1.

products[].amountnumber

Estoque disponível, em unidades inteiras.

products[].in_stockinteger

01

1 quando há estoque ou a loja não controla estoque do produto.

products[].company_idstring

Id do seller. "0" é a própria loja.

products[].company_namestring

Nome do seller.

products[].category_idsarray

Ids das categorias, a principal primeiro.

products[].discountsobject

Sempre {"A":0,"P":0}. Mantido por compatibilidade: o desconto já está em price.

products[].free_shippingstring

YN

Se o produto tem frete grátis.

products[].full_descriptionstring

Descrição completa (HTML).

products[].product_optionsobject

Sempre {}.

products[].product_featuresobject

Características do produto, por id. Cada uma tem feature_id, variant_id, variant, value e description.

products[].variation_featuresobject

As mesmas características, usadas pelo app para escolher a variação.

products[].variation_features_variantsobject

Para cada característica, as variantes disponíveis e o produto de cada uma. Só na ficha do produto e quando ele tem variações.

products[].variation_group_idstring

Id do grupo de variações, quando o produto faz parte de um.

products[].main_pairobject

Imagem principal em icon (miniatura de 400 px), detailed (original) e icons.500x500. Ausente quando o produto não tem imagem.

paramsobject

page, items_per_page e total_items (todos os produtos que atendem aos filtros).

filtersarray

Só com get_filters. Cada item: filter_id, filter (nome), filter_style (checkbox, color ou slider) e variants (mapa de variant_id para {variant_id, variant, color}).

Erros

Status	Quando	Corpo
401	`Authorization` presente mas não é uma ekey válida	`{"error":"unauthorized"}`
404	Produto inexistente ou inativo (ficha)	`{"error":"product not found"}`
404	Categoria inexistente (`/categories/{id}/sra_products`)	`{"error":"category not found"}`
500	Falha ao listar	`{"error":"failed to list products","detail":"..."}`

Veja também

Produtos

Lista, busca e filtra produtos, lista promoções e produtos de uma categoria e lê a ficha de um produto, no formato do app móvel.

Todas as listas devolvem o mesmo cartão de produto (veja os campos abaixo) dentro de products, mais params com a paginação. A ficha de um produto devolve o cartão direto.

GET/api/4.0/sra_productsPública

Listar e buscar produtos

Os resultados vêm na ordem do catálogo, a menos que você peça sort_by.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

items_per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Acima de 100 vira 100. (per_page e limit são sinônimos.)

searchstring

Texto de busca. q é um sinônimo.

category_idstring

Só produtos desta categoria (id decimal ou UUID). Categoria desconhecida devolve lista vazia.

subcatsstring

Yyestrue1

Inclui os produtos das subcategorias. (include_subcategories=true faz o mesmo.)

company_idstring

Só produtos deste seller. vendor_id é um sinônimo; seller desconhecido devolve lista vazia.

sort_bystring

productpriceamountpopularityratingtimestamp

Campo de ordenação. Também são aceitos name, list_price, quantity, rating_avg, created_at, position e code.

sort_dirstring

ascdesc

Direção. sort_order é um sinônimo. Outro valor usa a direção padrão do campo.

on_saleboolean

truefalse

Só produtos em promoção.

in_stockboolean

true

Só produtos com estoque.

exclude_variationsbooleanpadrão: true

truefalse

Por padrão as variações (tamanho, cor) ficam de fora e só o produto principal aparece. false, 0, n ou no incluem as variações como produtos.

variation_group_idstring

Só os produtos deste grupo de variações. Já inclui as variações.

features[ID]string

Filtro por característica: features[12]=34,35 traz produtos com a variante 34 ou 35 da característica 12. Pode repetir para várias características.

features_hashstring

Os mesmos filtros de característica em formato compacto, como o app 1.0 os enviava.

GET/api/4.0/sra_products/{id}Pública

Ficha de um produto

Devolve o cartão do produto, incluindo variation_features_variants quando o produto tem variações. Produto inexistente ou que não está ativo responde 404.

Parâmetros de caminho

idstringobrigatório

Id do produto (decimal ou UUID).

GET/api/4.0/sra_products_discountedPública

Produtos em promoção

Igual a GET /api/4.0/sra_products com on_sale ligado. Aceita todos os mesmos parâmetros.

GET/api/4.0/categories/{id}/sra_productsPública

Produtos de uma categoria

Igual a GET /api/4.0/sra_products com a categoria vinda do caminho. Aceita os mesmos parâmetros e mais um.

Parâmetros de caminho

idstringobrigatório

Id da categoria (decimal ou UUID). Categoria desconhecida responde 404.

Parâmetros de consulta

get_filtersboolean

true1yyes

Inclui em filters as características e variantes disponíveis na categoria, para montar a tela de filtros.

Exemplo de requisição

bash

curl "$BASE_URL/api/4.0/sra_products?search=caneca&sort_by=price&sort_dir=asc&items_per_page=20"

Com a ekey do cliente (preços do grupo dele):

bash

curl "$BASE_URL/api/4.0/categories/878363454/sra_products?get_filters=true&items_per_page=20" \
  -H "Authorization: Basic $(printf '%s' "$CUSTOMER_TOKEN" | base64 -w0):"

Resposta

200Lista de produtos

json

{
  "products": [
    {
      "product_id": "1585658495",
      "product": "Caneca Esmaltada 350ml",
      "product_code": "CAN-350",
      "price": 52.9,
      "price_formatted": { "price": "52.90" },
      "list_price": 52.9,
      "list_price_formatted": { "price": "52.90" },
      "min_qty": 0,
      "qty_step": 1,
      "amount": 5,
      "in_stock": 1,
      "company_id": "347963034",
      "company_name": "Loja Exemplo",
      "category_ids": ["878363454", "2126275725"],
      "discounts": { "A": 0, "P": 0 },
      "free_shipping": "N",
      "full_description": "Caneca de aço esmaltado, 350 ml.",
      "product_options": {},
      "product_features": {},
      "variation_features": {},
      "variation_feature_ids": {},
      "variation_features_variants": {},
      "main_pair": {
        "icon": {
          "image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400",
          "http_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400",
          "https_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400"
        },
        "detailed": {
          "image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png",
          "http_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png",
          "https_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png"
        },
        "icons": {
          "500x500": {
            "image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400",
            "http_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400",
            "https_image_path": "https://minhaloja.io.venddor.com.br/uploads/p/caneca.png?w=400"
          }
        }
      }
    }
  ],
  "params": { "page": 1, "items_per_page": 20, "total_items": 4981 }
}

Campos da resposta

products[].product_idstring

Id decimal do produto.

products[].productstring

Nome do produto.

products[].product_codestring

SKU. Vazio quando não há.

products[].pricenumber

Preço de venda atual em reais, já com desconto de catálogo e preço do grupo do cliente.

products[].price_formatted.pricestring

O mesmo preço com duas casas, como texto.

products[].list_pricenumber

Preço de tabela em reais (o "de"). Igual a price quando não há desconto.

products[].min_qtynumber

Quantidade mínima por compra. 0 é sem mínimo.

products[].qty_stepnumber

Múltiplo da quantidade (de quanto em quanto se pode comprar). Padrão 1.

products[].amountnumber

Estoque disponível, em unidades inteiras.

products[].in_stockinteger

01

1 quando há estoque ou a loja não controla estoque do produto.

products[].company_idstring

Id do seller. "0" é a própria loja.

products[].company_namestring

Nome do seller.

products[].category_idsarray

Ids das categorias, a principal primeiro.

products[].discountsobject

Sempre {"A":0,"P":0}. Mantido por compatibilidade: o desconto já está em price.

products[].free_shippingstring

YN

Se o produto tem frete grátis.

products[].full_descriptionstring

Descrição completa (HTML).

products[].product_optionsobject

Sempre {}.

products[].product_featuresobject

Características do produto, por id. Cada uma tem feature_id, variant_id, variant, value e description.

products[].variation_featuresobject

As mesmas características, usadas pelo app para escolher a variação.

products[].variation_features_variantsobject

Para cada característica, as variantes disponíveis e o produto de cada uma. Só na ficha do produto e quando ele tem variações.

products[].variation_group_idstring

Id do grupo de variações, quando o produto faz parte de um.

products[].main_pairobject

Imagem principal em icon (miniatura de 400 px), detailed (original) e icons.500x500. Ausente quando o produto não tem imagem.

paramsobject

page, items_per_page e total_items (todos os produtos que atendem aos filtros).

filtersarray

Só com get_filters. Cada item: filter_id, filter (nome), filter_style (checkbox, color ou slider) e variants (mapa de variant_id para {variant_id, variant, color}).

Erros

Status	Quando	Corpo
401	`Authorization` presente mas não é uma ekey válida	`{"error":"unauthorized"}`
404	Produto inexistente ou inativo (ficha)	`{"error":"product not found"}`
404	Categoria inexistente (`/categories/{id}/sra_products`)	`{"error":"category not found"}`
500	Falha ao listar	`{"error":"failed to list products","detail":"..."}`