Coleções inteligentes

Transforma uma categoria em coleção inteligente, que se preenche sozinha com os produtos que atendem a regras como preço, estoque, tag e característica.

Uma coleção inteligente é uma categoria que não depende de você ligar os produtos um a um. Você define regras ("produtos com preço a partir de R$ 100, em estoque, lançados nos últimos 30 dias") e a plataforma preenche a categoria com os produtos que atendem. Para a vitrine, ela é uma categoria comum: tem a mesma página, o mesmo menu e o mesmo filtro.

O fluxo normal tem três passos:

Simular
Chame smart-preview com as regras para ver quantos produtos entrariam e uma amostra de 24. Nada é gravado.
Ligar
Chame smart-rules com category_type: "smart" na categoria que vai receber os produtos (crie-a antes em Criar categoria). A plataforma já começa a preencher a categoria.
Recalcular, se precisar
Chame materialize para refazer a lista na hora. A lista também é recalculada automaticamente cerca de um minuto depois de produtos serem alterados.

Os produtos de uma coleção inteligente não mudam a categoria principal do produto: eles só passam a aparecer também nela. Voltar a categoria para manual remove apenas os produtos que as regras colocaram; os que você ligou à mão continuam. Todas as rotas exigem o privilégio manage_catalog.

POST/api/v1/admin/categories/smart-previewAdmin

Preview a smart collection

Simula as regras sem gravar nada e devolve o total e uma amostra.

Corpo da requisição

smart_rulesobjectobrigatório

O conjunto de regras. É o mesmo objeto enviado em smart-rules.

matchstringpadrão: all

allany

all: o produto precisa atender a todas as condições. any: basta atender a uma.

conditionsarrayobrigatório

Lista de condições, de 1 a 10.

fieldstringobrigatório

price_centsin_stockcreated_days_ltemargin_pct_gtevendor_idtag_slugfeature_variantpred_stockout_risk_gte

Campo avaliado. Qualquer outro valor é recusado (422). Veja a tabela abaixo.

opstring

Operador. Só tem efeito em price_cents (eq, gte, lte, between). Nos outros campos é ignorado.

valueanyobrigatório

Valor da condição. O tipo depende do campo.

feature_iduuid

Obrigatório quando field é feature_variant: a característica cujo valor será comparado.

Campos de condição

`field`	`value`	Atende quando
`price_cents`	inteiro em centavos; com `op: "between"`, uma lista `[mínimo, máximo]`	O preço do produto é igual (`eq`, padrão), maior ou igual (`gte`), menor ou igual (`lte`) ou está entre os dois valores.
`in_stock`	`true` ou `false`	`true`: quantidade maior que zero. `false`: quantidade zero ou negativa.
`created_days_lte`	inteiro (dias)	O produto foi criado nos últimos N dias.
`margin_pct_gte`	inteiro (percentual)	A margem sobre o preço de venda, `(preço - custo) * 100 / preço`, é pelo menos N. Só considera produtos com custo cadastrado.
`vendor_id`	lista de UUIDs de sellers	O produto é de um dos sellers.
`tag_slug`	lista de slugs de tags	O produto tem pelo menos uma das tags.
`feature_variant`	lista de ids de valores de característica (com `feature_id` na condição)	O produto tem um dos valores daquela característica.
`pred_stockout_risk_gte`	número	O produto tem previsão de risco de ruptura de estoque igual ou maior que o valor.

PUT/api/v1/admin/categories/{id}/smart-rulesAdmin

Liga ou desliga uma coleção inteligente

Liga a coleção inteligente (com as regras) ou volta a categoria para o modo manual. Ao ligar, a plataforma já inicia o primeiro preenchimento, em segundo plano.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Corpo da requisição

category_typestringobrigatório

smartmanual

smart liga a coleção inteligente e exige smart_rules. Qualquer outro valor volta a categoria para o modo manual, apaga as regras e remove os produtos que elas tinham colocado.

smart_rulesobject

Obrigatório com smart: o mesmo objeto de smart-preview (match e conditions).

POST/api/v1/admin/categories/{id}/materializeAdmin

Recalcula os produtos de uma coleção inteligente

Refaz, na hora, a lista de produtos de uma coleção inteligente. Responde imediatamente com 202: o cálculo roda em segundo plano. Se já houver um cálculo da mesma categoria em andamento, a chamada não faz nada. Em categoria manual também não faz nada (e também responde 202).

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/categories/b53fa6b9-a1a5-4862-9fac-cdc5585017c7/smart-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_type": "smart",
    "smart_rules": {
      "match": "all",
      "conditions": [
        { "field": "in_stock", "value": true },
        { "field": "created_days_lte", "value": 30 }
      ]
    }
  }'

Resposta

200Prévia

json

{
  "total": 2967,
  "products": [
    {
      "id": "1d22de37-ab3b-422d-82ef-275b8257691d",
      "name": "Mouse Óptico Branco 04387",
      "price": 10990,
      "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/1d22de37-ab3b-422d-82ef-275b8257691d/ai_36271beae1e24418b43fb74ad3b2441b.png",
      "quantity": 3
    }
  ]
}

200Regras gravadas

json

{ "category_type": "smart", "status": "ok" }

202Recálculo enfileirado

json

{ "status": "queued" }

Campos da resposta

totalinteger

Quantos produtos atendem às regras (smart-preview).

productsarray

Até 24 produtos de amostra.

products[].iduuid

Id do produto.

products[].namestring

Nome do produto.

products[].priceinteger

Preço em centavos (10990 = R$ 109,90).

products[].image_urlstring

Imagem principal. Pode ser nula.

products[].quantityinteger

Estoque, arredondado para baixo.

category_typestring

smartmanual

Eco do tipo que você enviou (smart-rules).

statusstring

ok em smart-rules; queued em materialize.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
422	Campo de condição desconhecido, `smart` sem condições, mais de 10 condições ou mais de 50 coleções	`{"error":"invalid rules","detail":"unsupported condition field \"bogus\""}` em `smart-preview`; `{"error":"failed","detail":"smart collection requires at least one condition"}` em `smart-rules`

Veja também

Coleções inteligentes

Transforma uma categoria em coleção inteligente, que se preenche sozinha com os produtos que atendem a regras como preço, estoque, tag e característica.

O fluxo normal tem três passos:

Simular
Chame smart-preview com as regras para ver quantos produtos entrariam e uma amostra de 24. Nada é gravado.
Ligar
Chame smart-rules com category_type: "smart" na categoria que vai receber os produtos (crie-a antes em Criar categoria). A plataforma já começa a preencher a categoria.
Recalcular, se precisar
Chame materialize para refazer a lista na hora. A lista também é recalculada automaticamente cerca de um minuto depois de produtos serem alterados.

POST/api/v1/admin/categories/smart-previewAdmin

Preview a smart collection

Simula as regras sem gravar nada e devolve o total e uma amostra.

Corpo da requisição

smart_rulesobjectobrigatório

O conjunto de regras. É o mesmo objeto enviado em smart-rules.

matchstringpadrão: all

allany

all: o produto precisa atender a todas as condições. any: basta atender a uma.

conditionsarrayobrigatório

Lista de condições, de 1 a 10.

fieldstringobrigatório

price_centsin_stockcreated_days_ltemargin_pct_gtevendor_idtag_slugfeature_variantpred_stockout_risk_gte

Campo avaliado. Qualquer outro valor é recusado (422). Veja a tabela abaixo.

opstring

Operador. Só tem efeito em price_cents (eq, gte, lte, between). Nos outros campos é ignorado.

valueanyobrigatório

Valor da condição. O tipo depende do campo.

feature_iduuid

Obrigatório quando field é feature_variant: a característica cujo valor será comparado.

Campos de condição

`field`	`value`	Atende quando
`price_cents`	inteiro em centavos; com `op: "between"`, uma lista `[mínimo, máximo]`	O preço do produto é igual (`eq`, padrão), maior ou igual (`gte`), menor ou igual (`lte`) ou está entre os dois valores.
`in_stock`	`true` ou `false`	`true`: quantidade maior que zero. `false`: quantidade zero ou negativa.
`created_days_lte`	inteiro (dias)	O produto foi criado nos últimos N dias.
`margin_pct_gte`	inteiro (percentual)	A margem sobre o preço de venda, `(preço - custo) * 100 / preço`, é pelo menos N. Só considera produtos com custo cadastrado.
`vendor_id`	lista de UUIDs de sellers	O produto é de um dos sellers.
`tag_slug`	lista de slugs de tags	O produto tem pelo menos uma das tags.
`feature_variant`	lista de ids de valores de característica (com `feature_id` na condição)	O produto tem um dos valores daquela característica.
`pred_stockout_risk_gte`	número	O produto tem previsão de risco de ruptura de estoque igual ou maior que o valor.

PUT/api/v1/admin/categories/{id}/smart-rulesAdmin

Liga ou desliga uma coleção inteligente

Liga a coleção inteligente (com as regras) ou volta a categoria para o modo manual. Ao ligar, a plataforma já inicia o primeiro preenchimento, em segundo plano.

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Corpo da requisição

category_typestringobrigatório

smartmanual

smart liga a coleção inteligente e exige smart_rules. Qualquer outro valor volta a categoria para o modo manual, apaga as regras e remove os produtos que elas tinham colocado.

smart_rulesobject

Obrigatório com smart: o mesmo objeto de smart-preview (match e conditions).

POST/api/v1/admin/categories/{id}/materializeAdmin

Recalcula os produtos de uma coleção inteligente

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/categories/b53fa6b9-a1a5-4862-9fac-cdc5585017c7/smart-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_type": "smart",
    "smart_rules": {
      "match": "all",
      "conditions": [
        { "field": "in_stock", "value": true },
        { "field": "created_days_lte", "value": 30 }
      ]
    }
  }'

Resposta

200Prévia

json

{
  "total": 2967,
  "products": [
    {
      "id": "1d22de37-ab3b-422d-82ef-275b8257691d",
      "name": "Mouse Óptico Branco 04387",
      "price": 10990,
      "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/1d22de37-ab3b-422d-82ef-275b8257691d/ai_36271beae1e24418b43fb74ad3b2441b.png",
      "quantity": 3
    }
  ]
}

200Regras gravadas

json

{ "category_type": "smart", "status": "ok" }

202Recálculo enfileirado

json

{ "status": "queued" }

Campos da resposta

totalinteger

Quantos produtos atendem às regras (smart-preview).

productsarray

Até 24 produtos de amostra.

products[].iduuid

Id do produto.

products[].namestring

Nome do produto.

products[].priceinteger

Preço em centavos (10990 = R$ 109,90).

products[].image_urlstring

Imagem principal. Pode ser nula.

products[].quantityinteger

Estoque, arredondado para baixo.

category_typestring

smartmanual

Eco do tipo que você enviou (smart-rules).

statusstring

ok em smart-rules; queued em materialize.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
422	Campo de condição desconhecido, `smart` sem condições, mais de 10 condições ou mais de 50 coleções	`{"error":"invalid rules","detail":"unsupported condition field \"bogus\""}` em `smart-preview`; `{"error":"failed","detail":"smart collection requires at least one condition"}` em `smart-rules`