VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Regras de vitrine

Criar, alterar e excluir regra de vitrine

Cria, substitui e exclui uma regra de vitrine.

Comece pelo rascunho: crie com status draft, confira com a pré-visualização e só então envie um PUT com status active. Toda gravação limpa o cache da vitrine, e a regra passa a atuar em segundos se estiver ativa e dentro da janela. A resposta é sempre a regra completa, como ficou gravada.

Criar uma regra

POST/api/v1/admin/merch-rulesAdmin

Cria uma regra de vitrine

Corpo da requisição

namestringobrigatório
Nome interno da regra.
contextstringobrigatório
searchcategoryglobal
Onde a regra atua.
search_termstring
Termo de busca alvo (search). Obrigatório para ativar.
category_iduuid
Categoria alvo (category). Obrigatória para ativar. Precisa existir.
include_childrenbooleanpadrão: false
Vale também para subcategorias. Omitido, vira false.
pinsarray of uuidpadrão: []
Produtos a fixar no topo, em ordem.
boostsarraypadrão: []
Impulsos. Cada item tem field, value e weight (-100 a 100).
bury_out_of_stockbooleanpadrão: false
Rebaixa produtos sem estoque.
statusstringpadrão: draft
draftactivearchived
draft, active ou archived.
priorityintegerpadrão: 100
Ordem de aplicação; menor primeiro. 0 ou omitido vira 100.
starts_atstring (RFC 3339)
Início da janela. Omitido = sem início.
ends_atstring (RFC 3339)
Fim da janela. Omitido = sem fim.

Exemplo de requisição: criar

bash
curl -X POST "$BASE_URL/api/v1/admin/merch-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Camisas de time primeiro",
    "context": "category",
    "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",
    "starts_at": "2026-11-20T00:00:00-03:00",
    "ends_at": "2026-11-30T23:59:59-03:00"
  }'

Resposta: criar

201Regra criada
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: criar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403Falta o privilégio manage_catalog (vale também para leitura).{"error":"insufficient privileges","required":"manage_catalog"}
400Corpo que não é JSON.{"error":"invalid body","detail":"..."}
422A regra é inválida: context fora da lista, name vazio, peso de boost fora de -100 a 100, ou (para ativar) falta category_id/search_term. O motivo vem em detail.{"error":"invalid rule","detail":"invalid rule: search_term is required to activate a search rule"}
422Já existem 200 regras ativas na loja.{"error":"too many active rules","detail":"max 200 active rules per tenant"}
422Outra regra ativa já usa o mesmo termo de busca (comparação sem acento e sem diferenciar maiúsculas).{"error":"duplicate search term","detail":"another active rule already targets this term"}
500status fora de draft|active|archived, ou category_id que não existe (barrados pelo banco).{"error":"failed","detail":"..."}

Substituir uma regra

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

Substitui todos os campos de uma regra

Parâmetros de caminho

iduuidobrigatório
Id da regra.

Corpo da requisição

namestringobrigatório
Nome interno da regra.
contextstringobrigatório
searchcategoryglobal
Onde a regra atua.
search_termstring
Termo de busca alvo (search). Obrigatório para ativar.
category_iduuid
Categoria alvo (category). Obrigatória para ativar. Precisa existir.
include_childrenbooleanpadrão: false
Vale também para subcategorias. Omitido, vira false.
pinsarray of uuidpadrão: []
Produtos a fixar no topo, em ordem.
boostsarraypadrão: []
Impulsos. Cada item tem field, value e weight (-100 a 100).
bury_out_of_stockbooleanpadrão: false
Rebaixa produtos sem estoque.
statusstringpadrão: draft
draftactivearchived
draft, active ou archived.
priorityintegerpadrão: 100
Ordem de aplicação; menor primeiro. 0 ou omitido vira 100.
starts_atstring (RFC 3339)
Início da janela. Omitido = sem início.
ends_atstring (RFC 3339)
Fim da janela. Omitido = sem fim.

Exemplo de requisição: substituir

bash
curl -X PUT "$BASE_URL/api/v1/admin/merch-rules/aa3cf134-6d3f-4f16-b4f0-09c3df9601fc" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Camisas de time primeiro",
    "context": "category",
    "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",
    "starts_at": "2026-11-20T00:00:00-03:00",
    "ends_at": "2026-11-30T23:59:59-03:00"
  }'

Resposta: substituir

200Regra gravada
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: substituir

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403Falta o privilégio manage_catalog (vale também para leitura).{"error":"insufficient privileges","required":"manage_catalog"}
400Corpo que não é JSON.{"error":"invalid body","detail":"..."}
422A regra é inválida: context fora da lista, name vazio, peso de boost fora de -100 a 100, ou (para ativar) falta category_id/search_term. O motivo vem em detail.{"error":"invalid rule","detail":"invalid rule: search_term is required to activate a search rule"}
422Já existem 200 regras ativas na loja.{"error":"too many active rules","detail":"max 200 active rules per tenant"}
422Outra regra ativa já usa o mesmo termo de busca (comparação sem acento e sem diferenciar maiúsculas).{"error":"duplicate search term","detail":"another active rule already targets this term"}
500O id não existe ou não é UUID, ou o banco recusou um valor.{"error":"failed","detail":"..."}

Excluir uma regra

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

Exclui (de forma lógica) uma regra de vitrine

Parâmetros de caminho

iduuidobrigatório
Id da regra.

Exemplo de requisição: excluir

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

Resposta: excluir

200Regra excluída
json
{
  "status": "deleted"
}

Erros: excluir

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403Falta o privilégio manage_catalog (vale também para leitura).{"error":"insufficient privileges","required":"manage_catalog"}
500O id não é um UUID válido.{"error":"failed to delete","detail":"..."}
`PUT` não é parcial

Para só ativar uma regra, leia-a, troque status para active e reenvie todos os campos. Reenviar só {"status":"active"} apaga nome, contexto e alvo (e é recusado).

Campanha com data

Use starts_at e ends_at com o fuso (-03:00) para a regra ligar e desligar sozinha, sem precisar de uma segunda chamada na virada.

Veja também

  • Regras de vitrine: visão geral
  • Consultar regras
  • Pré-visualizar
Anterior
Consultar regras de vitrine
Próxima
Pré-visualizar regra
Nesta página
  • Criar uma regra
  • Exemplo de requisição: criar
  • Resposta: criar
  • Erros: criar
  • Substituir uma regra
  • Exemplo de requisição: substituir
  • Resposta: substituir
  • Erros: substituir
  • Excluir uma regra
  • Exemplo de requisição: excluir
  • Resposta: excluir
  • Erros: excluir
  • Veja também