API atual/Referência completa/Regras de vitrine

Consultar regras de vitrine

Lista as regras de vitrine com filtros e detalha uma regra.

A lista devolve as regras não excluídas, na ordem em que são aplicadas (priority crescente e, em empate, a mais nova primeiro). Regras arquivadas e vencidas aparecem; use expired e status para separá-las.

Listar regras

GET/api/v1/admin/merch-rulesAdmin

Lista as regras de vitrine

Parâmetros de consulta

contextstring

searchcategoryglobal

Filtra por onde a regra atua.

statusstring

draftactivearchived

Filtra por status.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Fora disso volta a 50.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/admin/merch-rules?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Regras

json

{
  "rules": [
    {
      "id": "aa3cf134-6d3f-4f16-b4f0-09c3df9601fc",
      "name": "Camisas de time primeiro",
      "context": "category",
      "search_term": null,
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "include_children": true,
      "pins": ["22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"],
      "boosts": [
        { "field": "on_sale", "value": true, "weight": 30 },
        { "field": "created_days_lte", "value": 30, "weight": 20 }
      ],
      "bury_out_of_stock": true,
      "status": "active",
      "priority": 100,
      "starts_at": "2026-11-20T03:00:00Z",
      "ends_at": "2026-12-01T02:59:59Z",
      "created_at": "2026-10-11T15:02:11.512Z",
      "updated_at": "2026-10-11T15:02:11.512Z",
      "expired": false
    }
  ],
  "total": 1
}

Campos da resposta

rulesarray

Regras da página. Sem resultados vem [].

iduuid

Identificador da regra.

namestring

Nome interno.

contextstring

searchcategoryglobal

Onde a regra atua: search (num termo de busca), category (numa listagem de categoria) ou global (em tudo).

search_termstring | null

Termo de busca alvo, só em search.

category_iduuid | null

Categoria alvo, só em category.

include_childrenboolean

Em category, vale também para as subcategorias.

pinsarray of uuid

Produtos fixados no topo, na ordem dada.

boostsarray

Impulsos por característica do produto (veja a home da seção).

fieldstring

Característica avaliada.

valueany

Valor de comparação (depende do field).

weightinteger

Peso de -100 a 100. Positivo sobe o produto, negativo o desce.

bury_out_of_stockboolean

Manda os produtos sem estoque para o fim da lista.

statusstring

draftactivearchived

draft, active ou archived. Só active atua na vitrine.

priorityinteger

Ordem de aplicação; menor primeiro. 0 enviado vira 100.

starts_atstring (RFC 3339) | null

Início da janela de atuação.

ends_atstring (RFC 3339) | null

Fim da janela de atuação.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

expiredboolean

true quando ends_at já passou. Só vem na lista.

totalinteger

Total de regras que casam com o filtro (não só as da página).

Erros: listar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Falta o privilégio `manage_catalog` (vale também para leitura).	`{"error":"insufficient privileges","required":"manage_catalog"}`
500	Falha ao consultar.	`{"error":"failed to list rules","detail":"..."}`

Detalhar uma regra

GET/api/v1/admin/merch-rules/{id}Admin

Detalha uma regra de vitrine

Parâmetros de caminho

iduuidobrigatório

Id da regra.

Exemplo de requisição: detalhar

bash

curl "$BASE_URL/api/v1/admin/merch-rules/aa3cf134-6d3f-4f16-b4f0-09c3df9601fc" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Regra

json

{
  "id": "aa3cf134-6d3f-4f16-b4f0-09c3df9601fc",
  "name": "Camisas de time primeiro",
  "context": "category",
  "search_term": null,
  "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
  "include_children": true,
  "pins": ["22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"],
  "boosts": [
    { "field": "on_sale", "value": true, "weight": 30 },
    { "field": "created_days_lte", "value": 30, "weight": 20 }
  ],
  "bury_out_of_stock": true,
  "status": "active",
  "priority": 100,
  "starts_at": "2026-11-20T03:00:00Z",
  "ends_at": "2026-12-01T02:59:59Z",
  "created_at": "2026-10-11T15:02:11.512Z",
  "updated_at": "2026-10-11T15:02:11.512Z"
}

Campos da resposta

iduuid

Identificador da regra.

namestring

Nome interno.

contextstring

searchcategoryglobal

Onde a regra atua: search (num termo de busca), category (numa listagem de categoria) ou global (em tudo).

search_termstring | null

Termo de busca alvo, só em search.

category_iduuid | null

Categoria alvo, só em category.

include_childrenboolean

Em category, vale também para as subcategorias.

pinsarray of uuid

Produtos fixados no topo, na ordem dada.

boostsarray

Impulsos por característica do produto (veja a home da seção).

fieldstring

Característica avaliada.

valueany

Valor de comparação (depende do field).

weightinteger

Peso de -100 a 100. Positivo sobe o produto, negativo o desce.

bury_out_of_stockboolean

Manda os produtos sem estoque para o fim da lista.

statusstring

draftactivearchived

draft, active ou archived. Só active atua na vitrine.

priorityinteger

Ordem de aplicação; menor primeiro. 0 enviado vira 100.

starts_atstring (RFC 3339) | null

Início da janela de atuação.

ends_atstring (RFC 3339) | null

Fim da janela de atuação.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

Erros: detalhar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Falta o privilégio `manage_catalog` (vale também para leitura).	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Não existe regra com esse id (qualquer falha na leitura, inclusive id que não é UUID, também vira `404`).	`{"error":"rule not found"}`

Veja também

Consultar regras de vitrine

Lista as regras de vitrine com filtros e detalha uma regra.

Listar regras

GET/api/v1/admin/merch-rulesAdmin

Lista as regras de vitrine

Parâmetros de consulta

contextstring

searchcategoryglobal

Filtra por onde a regra atua.

statusstring

draftactivearchived

Filtra por status.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Fora disso volta a 50.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/admin/merch-rules?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Regras

json

{
  "rules": [
    {
      "id": "aa3cf134-6d3f-4f16-b4f0-09c3df9601fc",
      "name": "Camisas de time primeiro",
      "context": "category",
      "search_term": null,
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "include_children": true,
      "pins": ["22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"],
      "boosts": [
        { "field": "on_sale", "value": true, "weight": 30 },
        { "field": "created_days_lte", "value": 30, "weight": 20 }
      ],
      "bury_out_of_stock": true,
      "status": "active",
      "priority": 100,
      "starts_at": "2026-11-20T03:00:00Z",
      "ends_at": "2026-12-01T02:59:59Z",
      "created_at": "2026-10-11T15:02:11.512Z",
      "updated_at": "2026-10-11T15:02:11.512Z",
      "expired": false
    }
  ],
  "total": 1
}

Campos da resposta

rulesarray

Regras da página. Sem resultados vem [].

iduuid

Identificador da regra.

namestring

Nome interno.

contextstring

searchcategoryglobal

Onde a regra atua: search (num termo de busca), category (numa listagem de categoria) ou global (em tudo).

search_termstring | null

Termo de busca alvo, só em search.

category_iduuid | null

Categoria alvo, só em category.

include_childrenboolean

Em category, vale também para as subcategorias.

pinsarray of uuid

Produtos fixados no topo, na ordem dada.

boostsarray

Impulsos por característica do produto (veja a home da seção).

fieldstring

Característica avaliada.

valueany

Valor de comparação (depende do field).

weightinteger

Peso de -100 a 100. Positivo sobe o produto, negativo o desce.

bury_out_of_stockboolean

Manda os produtos sem estoque para o fim da lista.

statusstring

draftactivearchived

draft, active ou archived. Só active atua na vitrine.

priorityinteger

Ordem de aplicação; menor primeiro. 0 enviado vira 100.

starts_atstring (RFC 3339) | null

Início da janela de atuação.

ends_atstring (RFC 3339) | null

Fim da janela de atuação.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

expiredboolean

true quando ends_at já passou. Só vem na lista.

totalinteger

Total de regras que casam com o filtro (não só as da página).

Erros: listar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Falta o privilégio `manage_catalog` (vale também para leitura).	`{"error":"insufficient privileges","required":"manage_catalog"}`
500	Falha ao consultar.	`{"error":"failed to list rules","detail":"..."}`

Detalhar uma regra

GET/api/v1/admin/merch-rules/{id}Admin

Detalha uma regra de vitrine

Parâmetros de caminho

iduuidobrigatório

Id da regra.

Exemplo de requisição: detalhar

bash

curl "$BASE_URL/api/v1/admin/merch-rules/aa3cf134-6d3f-4f16-b4f0-09c3df9601fc" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Regra

json

{
  "id": "aa3cf134-6d3f-4f16-b4f0-09c3df9601fc",
  "name": "Camisas de time primeiro",
  "context": "category",
  "search_term": null,
  "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
  "include_children": true,
  "pins": ["22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"],
  "boosts": [
    { "field": "on_sale", "value": true, "weight": 30 },
    { "field": "created_days_lte", "value": 30, "weight": 20 }
  ],
  "bury_out_of_stock": true,
  "status": "active",
  "priority": 100,
  "starts_at": "2026-11-20T03:00:00Z",
  "ends_at": "2026-12-01T02:59:59Z",
  "created_at": "2026-10-11T15:02:11.512Z",
  "updated_at": "2026-10-11T15:02:11.512Z"
}

Campos da resposta

iduuid

Identificador da regra.

namestring

Nome interno.

contextstring

searchcategoryglobal

Onde a regra atua: search (num termo de busca), category (numa listagem de categoria) ou global (em tudo).

search_termstring | null

Termo de busca alvo, só em search.

category_iduuid | null

Categoria alvo, só em category.

include_childrenboolean

Em category, vale também para as subcategorias.

pinsarray of uuid

Produtos fixados no topo, na ordem dada.

boostsarray

Impulsos por característica do produto (veja a home da seção).

fieldstring

Característica avaliada.

valueany

Valor de comparação (depende do field).

weightinteger

Peso de -100 a 100. Positivo sobe o produto, negativo o desce.

bury_out_of_stockboolean

Manda os produtos sem estoque para o fim da lista.

statusstring

draftactivearchived

draft, active ou archived. Só active atua na vitrine.

priorityinteger

Ordem de aplicação; menor primeiro. 0 enviado vira 100.

starts_atstring (RFC 3339) | null

Início da janela de atuação.

ends_atstring (RFC 3339) | null

Fim da janela de atuação.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

Erros: detalhar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	Falta o privilégio `manage_catalog` (vale também para leitura).	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Não existe regra com esse id (qualquer falha na leitura, inclusive id que não é UUID, também vira `404`).	`{"error":"rule not found"}`