Produtos

Visão geral

O endpoint /api2/products é uma rota integracional/administrativa. Ele não se limita a produtos ativos de vitrine — ele expõe o catálogo para sincronização com ERPs, PIMs, marketplaces e rotinas internas. A rota suporta tanto listagem paginada quanto busca individual por id ou sku.

Consulta individual de produto Atualizado

O GET /api2/products continua atendendo à listagem quando usado sem identificação individual. Para trazer um único produto, informe id e type. Nessa forma de uso a resposta passa a incluir referências legíveis (conjunto de atributos, categorias, websites, status e visibilidade), além de um resumo de preço e um resumo de estoque.

Parâmetros

Exemplo de resposta — produto simples

{
  "success": true,
  "product": {
    "product_id": "2074",
    "sku": "3291",
    "name": "Cápsulas de Café União Ristretto 10 unidades",
    "set": "4",
    "product_set": {
      "id": "4",
      "name": "Default"
    },
    "type": "simple",
    "categories": ["122", "124"],
    "product_categories": [
      {"id": "122", "name": "Cápsulas Compatíveis"},
      {"id": "124", "name": "Cafés"}
    ],
    "websites": ["1"],
    "product_websites": [
      {"id": "1", "code": "cafe", "name": "Website Principal"}
    ],
    "status": "1",
    "product_status": {
      "value": "1",
      "code": "enabled",
      "label": "Habilitado"
    },
    "visibility": "4",
    "product_visibility": {
      "value": "4",
      "code": "catalog_search",
      "label": "Catálogo, Busca"
    },
    "created_at": "2025-12-01T12:02:21-03:00",
    "updated_at": "2025-12-01 19:57:58",
    "pricing": {
      "price": "28.9000",
      "special_price": "25.9000",
      "final_price": "25.9000",
      "currency": "BRL"
    },
    "inventory": {
      "inventory_manage_stock": true,
      "inventory_qty": "38.0000",
      "inventory_stock_availability": "in_stock",
      "inventory_stock_availability_label": "Em Estoque",
      "inventory_is_salable": true
    }
  }
}

Retrocompatibilidade

Os campos históricos continuam presentes e com a mesma semântica: set, categories, websites, status e visibility. Os objetos product_set, product_categories, product_websites, product_status, product_visibility, pricing e inventory são aditivos.

• Integrações existentes podem continuar utilizando apenas os campos históricos, sem nenhuma alteração.
• Novas integrações devem preferir os objetos enriquecidos quando precisarem de nome, código ou label sem consultar o painel manualmente.

Referências enriquecidas

Resumo de preço

O bloco pricing entrega uma visão rápida do preço do produto no contexto consultado.

{
  "price": "28.9000",
  "special_price": "25.9000",
  "final_price": "25.9000",
  "currency": "BRL"
}

Resumo de estoque

O bloco inventory entrega uma visão rápida da disponibilidade.

{
  "inventory_manage_stock": true,
  "inventory_qty": "38.0000",
  "inventory_stock_availability": "in_stock",
  "inventory_stock_availability_label": "Em Estoque",
  "inventory_is_salable": true
}

Respostas HTTP

Novidades do GET /api2/products

Três evoluções principais foram incorporadas ao endpoint de listagem, tornando-o mais previsível em ambientes multi-store e mais eficiente para sincronizações em lote.

5) Suporte a store_id opcional Novo

Agora é possível informar store_id para tornar o resultado explícito e determinístico em cenários multi-store. Sem esse parâmetro, a seleção de store segue a regra default do ambiente; com ele, a integração assume o controle.

Exemplo

GET /api2/products?page=1&store_id=1

6) Metadados opcionais de paginação Novo

Foi adicionado suporte opcional a campos de paginação no corpo da resposta. Eles só são retornados quando for enviado include_pagination=1, evitando overhead em sincronizações que não precisam desses metadados.

Exemplo

GET /api2/products?page=1&include_pagination=1

7) Suporte a limit opcional Novo

O endpoint aceita limit para definir a quantidade de produtos por página. Valores inválidos (não numéricos, arrays, negativos, zero ou acima do máximo) são normalizados para o padrão, garantindo que nenhuma requisição quebre por entrada inesperada.

Exemplos

GET /api2/products?page=1&limit=50
GET /api2/products?page=1&limit=200

Formas de uso suportadas

Referência rápida das combinações testadas e homologadas para o GET /api2/products.

Recomendações para integração

Boas práticas consolidadas após a evolução do endpoint. Seguir essas diretrizes reduz retrabalho, evita paginação infinita e garante determinismo em ambientes multi-store.

Recomendado

• Enviar sempre page explicitamente em rotinas de paginação.
• Usar store_id sempre que a integração precisar de resultado determinístico em ambiente multi-store.
• Preferir limit=50 ou limit=100 para sincronizações usuais.
• Usar limit=200 apenas quando houver necessidade real de reduzir o número de chamadas.
• Usar include_pagination=1 para controlar avanço de paginação com mais segurança (loop baseado em has_next).

Evitar

• Enviar parâmetros como array em campos escalares — por exemplo id[] ou limit[].
• Considerar que o endpoint retorna apenas produtos ativos de vitrine. Esta rota é integracional/administrativa.
• Depender de ordenação implícita entre páginas em cenários multi-store sem store_id.

Imagens de produto

Para consultar, reconciliar, incluir, atualizar ou excluir imagens de produtos, consulte Catálogo › Imagens.