Consultas rápidas de produto

Acha produtos pelo código de barras e atualiza os preços de vários produtos de uma vez, para leitores de código e para trocar o preço depois do login.

Duas rotas pequenas e muito úteis em apps: uma resolve um código de barras (EAN/GTIN) para produtos, a outra devolve só os preços reais de uma lista de produtos. As duas seguem as mesmas regras de visibilidade da lista de produtos: produto inativo, restrito a grupo ou de vendedor suspenso não aparece, e quem está sem permissão não descobre que ele existe.

Achar produto pelo código de barras

Use quando o comprador escaneia a embalagem com o app. A busca é pela igualdade exata do campo de código de barras do produto, preservando zeros à esquerda (0789... é diferente de 789...). Como vendedores diferentes podem cadastrar o mesmo EAN, a resposta é uma lista: com 1 item, abra o produto direto; com vários, mostre uma lista para o comprador escolher. No máximo 50 candidatos são considerados.

GET/api/v1/storefront/products/by-barcodePública

Achar produtos pelo código de barras

Parâmetros de consulta

codestringobrigatório

Código de barras (EAN/GTIN) exato. Sem code, ou vazio, a resposta é {"products": []} com status 200.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/by-barcode?code=7891000100103"

Resposta

200Produtos encontrados (reduzido)

json

{
  "products": [
    {
      "id": "038235f3-7686-4742-b823-be3f26fa8fb8",
      "name": "Luminária Vintage Roxo 03599 - PROMOÇÃO",
      "slug": "luminaria-vintage-roxo-03599-3599",
      "sku": "SD-003599",
      "barcode": "SD-003599",
      "price": 1990,
      "price_str": "19.90",
      "track_inventory": true,
      "quantity": 224,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "status": "A"
    }
  ]
}

Campos da resposta

productsarray

Produtos com esse código, no formato do cartão de Listar produtos. Lista vazia quando nada casa, o produto está oculto ou o código é vazio. barcode traz o código pesquisado.

Preços reais em lote

Páginas de lista são servidas de cache e, quando a loja esconde preços de visitantes, trazem o preço zerado. Depois do login, chame esta rota uma vez com os ids da página para trocar os preços pelos do cliente, sem refazer a lista. Ela aplica o preço do grupo do cliente, os preços calculados da loja e o desconto de catálogo.

GET/api/v1/storefront/products/pricesPública

Preços reais de vários produtos

Parâmetros de consulta

idsstringobrigatório

Ids de produto (UUID) separados por vírgula. No máximo 200: os demais são ignorados. Sem ids, a resposta é {"prices": {}}.

Cabeçalhos

Authorizationstring

Bearer $TOKEN do cliente. Sem token (visitante), em lojas que escondem preço, cada item volta com price_redacted: true e valores zerados.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/prices?ids=34a3bed9-c40d-4519-801f-5cae027eac2a,62fa0ff0-555c-4b12-bb44-4bfa8df0f97c" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Preços retornados

json

{
  "prices": {
    "34a3bed9-c40d-4519-801f-5cae027eac2a": {
      "price": 3780,
      "list_price": null,
      "catalog_discount": 0,
      "price_redacted": false
    },
    "62fa0ff0-555c-4b12-bb44-4bfa8df0f97c": {
      "price": 14990,
      "list_price": null,
      "catalog_discount": 2998,
      "price_redacted": false
    }
  }
}

Campos da resposta

pricesobject

Mapa id do produto para preço. Ids inexistentes, inativos ou sem permissão são omitidos em silêncio (não geram erro): compare com o que você pediu.

prices.{id}.priceinteger

Preço unitário em centavos para quem fez a requisição. É o valor antes de catalog_discount.

prices.{id}.list_priceinteger|null

Preço "de" em centavos, ou null.

prices.{id}.catalog_discountinteger

Desconto por unidade, em centavos, de promoção de catálogo ativa. O valor cobrado é price - catalog_discount (no exemplo, 14990 - 2998 = 11992, ou R$ 119,92).

prices.{id}.price_redactedboolean

true quando o preço foi escondido porque o chamador é visitante.

Erros

Status	Quando	Exemplo de corpo
401	A loja exige login para navegar e a requisição é anônima	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
403	Chave de API sem o escopo `storefront:read`	`{"error":"missing_scope","required":"storefront:read"}`
500	Falha ao consultar o código de barras (só `by-barcode`)	`{"error":"failed to resolve barcode","detail":"..."}`

Um code ou ids ausente não é erro: devolve a coleção vazia com 200.

Veja também

API atual/Referência completa/Catálogo

Consultas rápidas de produto

Acha produtos pelo código de barras e atualiza os preços de vários produtos de uma vez, para leitores de código e para trocar o preço depois do login.

Achar produto pelo código de barras

GET/api/v1/storefront/products/by-barcodePública

Achar produtos pelo código de barras

Parâmetros de consulta

codestringobrigatório

Código de barras (EAN/GTIN) exato. Sem code, ou vazio, a resposta é {"products": []} com status 200.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/by-barcode?code=7891000100103"

Resposta

200Produtos encontrados (reduzido)

json

{
  "products": [
    {
      "id": "038235f3-7686-4742-b823-be3f26fa8fb8",
      "name": "Luminária Vintage Roxo 03599 - PROMOÇÃO",
      "slug": "luminaria-vintage-roxo-03599-3599",
      "sku": "SD-003599",
      "barcode": "SD-003599",
      "price": 1990,
      "price_str": "19.90",
      "track_inventory": true,
      "quantity": 224,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "status": "A"
    }
  ]
}

Campos da resposta

productsarray

Produtos com esse código, no formato do cartão de Listar produtos. Lista vazia quando nada casa, o produto está oculto ou o código é vazio. barcode traz o código pesquisado.

Preços reais em lote

GET/api/v1/storefront/products/pricesPública

Preços reais de vários produtos

Parâmetros de consulta

idsstringobrigatório

Ids de produto (UUID) separados por vírgula. No máximo 200: os demais são ignorados. Sem ids, a resposta é {"prices": {}}.

Cabeçalhos

Authorizationstring

Bearer $TOKEN do cliente. Sem token (visitante), em lojas que escondem preço, cada item volta com price_redacted: true e valores zerados.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/prices?ids=34a3bed9-c40d-4519-801f-5cae027eac2a,62fa0ff0-555c-4b12-bb44-4bfa8df0f97c" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Preços retornados

json

{
  "prices": {
    "34a3bed9-c40d-4519-801f-5cae027eac2a": {
      "price": 3780,
      "list_price": null,
      "catalog_discount": 0,
      "price_redacted": false
    },
    "62fa0ff0-555c-4b12-bb44-4bfa8df0f97c": {
      "price": 14990,
      "list_price": null,
      "catalog_discount": 2998,
      "price_redacted": false
    }
  }
}

Campos da resposta

pricesobject

Mapa id do produto para preço. Ids inexistentes, inativos ou sem permissão são omitidos em silêncio (não geram erro): compare com o que você pediu.

prices.{id}.priceinteger

Preço unitário em centavos para quem fez a requisição. É o valor antes de catalog_discount.

prices.{id}.list_priceinteger|null

Preço "de" em centavos, ou null.

prices.{id}.catalog_discountinteger

Desconto por unidade, em centavos, de promoção de catálogo ativa. O valor cobrado é price - catalog_discount (no exemplo, 14990 - 2998 = 11992, ou R$ 119,92).

prices.{id}.price_redactedboolean

true quando o preço foi escondido porque o chamador é visitante.

Erros

Status	Quando	Exemplo de corpo
401	A loja exige login para navegar e a requisição é anônima	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
403	Chave de API sem o escopo `storefront:read`	`{"error":"missing_scope","required":"storefront:read"}`
500	Falha ao consultar o código de barras (só `by-barcode`)	`{"error":"failed to resolve barcode","detail":"..."}`

Um code ou ids ausente não é erro: devolve a coleção vazia com 200.