Produtos
Criação, atualização, consulta, vínculo, imagens e exclusão de produtos — com suporte a paginação determinística, seleção explícita de store_id, controle de limit e metadados opcionais de paginação.
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.
limit.limit é omitido ou inválido.total, last_page, has_next sob include_pagination=1.Criar produto configurável.
{
"attribute_set_id": 4,
"type_id": "configurable",
"visibility": 4,
"store_id": 1,
"sku": "novo_configuravel",
"name": "novo configuravel",
"description": "Descrição do produto configurável",
"short_description": "Curta descrição",
"price": 99.90,
"status": 1,
"tax_class_id": 2,
"categories": [54, 59, 128],
"website_id": [1],
"additional_attributes": {
"single_data": [
{"key": "color", "value": "AZUL"},
{"key": "ncm", "value": "5543"}
]
},
"configurable_attributes": [335]
}Criar produto simples.
{
"type_id": "simple",
"attribute_set_id": 4,
"sku": "produto_teste",
"store_id": 1,
"name": "Produto teste",
"price": "2000",
"special_price": "150",
"weight": "0.5",
"status": 1,
"visibility": 4,
"categories": [54, 59, 128],
"website_id": [1],
"stock_data": {"qty": "99", "is_in_stock": 1}
}Atualizar produto.
{
"type": "sku",
"id": "novo_produto",
"name": "Novo nome do produto"
}invalid_fields, invalid_attributes e invalid_attribute_values.Consultar produto (individual) ou listar com paginação determinística.
?page=1&type=sku&id=novo_produtoVincular simples a configurável.
{
"type": "sku",
"configurable_id": "novo_produto",
"simples": "novo_configuravel"
}Excluir produto.
{
"type": "sku",
"id": "novo_produto"
}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=16) 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.
1 habilita). Quando ativa, inclui na resposta os campos total, last_page e has_next.include_pagination=1).limit corrente.Exemplo
GET /api2/products?page=1&include_pagination=17) 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.
| Regra | Valor | Comportamento |
|---|---|---|
| Padrão | 20 | Aplicado quando limit é omitido. |
| Máximo | 200 | Teto rígido para proteger a rota em cenários de alta carga. |
| Inválido | — | Valores inválidos são normalizados para 20. |
Exemplos
GET /api2/products?page=1&limit=50
GET /api2/products?page=1&limit=200Formas de uso suportadas
Referência rápida das combinações testadas e homologadas para o GET /api2/products.
GET /api2/products
GET /api2/products?page=2
GET /api2/products?page=1&limit=100
GET /api2/products?id=24404
GET /api2/products?id=ABC-123&type=sku
GET /api2/products?page=1&store_id=1
GET /api2/products?page=1&limit=100&include_pagination=1
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
pageexplicitamente em rotinas de paginação. - Usar
store_idsempre que a integração precisar de resultado determinístico em ambiente multi-store. - Preferir
limit=50oulimit=100para sincronizações usuais. - Usar
limit=200apenas quando houver necessidade real de reduzir o número de chamadas. - Usar
include_pagination=1para controlar avanço de paginação com mais segurança (loop baseado emhas_next).
Evitar
- Enviar parâmetros como array em campos escalares — por exemplo
id[]oulimit[]. - 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.
Dica de sincronização
Para sincronizações periódicas, combine store_id + limit=100 + include_pagination=1. Você obtém determinismo, throughput equilibrado e um critério de parada confiável (has_next=false).
Imagens de produto
Upload de imagem em base64.
{
"type": "sku",
"product_id": "novo_produto",
"position": 1,
"label": "Imagem",
"file_name": "minha_imagem.png",
"file_mime_type": "image/png",
"file_content": "iVBORw0KGgoAAAANS...",
"types": ["image"]
}Atualizar metadados da imagem.
{
"type": "sku",
"product_id": "produtoteste",
"image_id": "70449",
"position": 999,
"label": "Imagem atualizada",
"types": ["image"]
}Excluir imagem do produto.
{
"type": "sku",
"product_id": "produtoteste",
"image_id": "70449"
}