API atual/Referência completa/Selos de produto

Criar e gerenciar selos

Lista, cria, consulta, altera e apaga selos de produto, com textos, aparência, onde aparecem e status.

Estas cinco rotas cuidam do cadastro do selo em si. Escolher em quais produtos ele aparece é assunto de Produtos do selo e de Regras automáticas. O módulo product-stickers precisa estar ligado na loja.

GET/api/v1/admin/stickersAdmin

Lista os selos

Devolve todos os selos, sem paginação, ordenados por position e, empatando, do mais novo para o mais antigo. Cada item traz product_count, o número de produtos ligados.

Parâmetros de consulta

statusstring

AD

Só os selos com este status. Outro valor responde 500 failed to list stickers.

vendor_iduuid

Só os selos deste seller.

marketplace_onlyboolean

Com true, só os selos da própria loja (sem seller). Ignorado se vendor_id vier junto.

POST/api/v1/admin/stickersAdmin

Cria um selo

Responde 201 com o selo. Só name_admin é obrigatório.

Corpo da requisição (JSON)

name_adminstringobrigatório

Nome interno, que só o painel mostra.

name_desktopstring

Texto do selo no computador. Vazio repete name_admin.

name_mobilestring

Texto do selo no celular.

stylestringpadrão: T

TIP

T texto, I imagem, P pictograma (a vitrine o desenha como texto). Minúsculas são aceitas.

appearanceobjectpadrão: {}

Aparência livre: bg_color, text_color, radius, opacity, padding, font_size, position, image_url.

display_onobject

Onde mostrar: product_card, pdp e quickview (booleanos). Omitido, os três ficam ligados.

statusstringpadrão: A

AD

A ativo, D desativado.

positionintegerpadrão: 0

Ordem de exibição entre os selos; menor aparece primeiro.

GET/api/v1/admin/stickers/{id}Admin

Consulta um selo

Devolve o selo, incluindo o modo (assignment_mode), a regra e a data da última avaliação.

Parâmetros de caminho

iduuidobrigatório

Id do selo.

PUT/api/v1/admin/stickers/{id}Admin

Altera um selo

Altera só os campos enviados. Um corpo vazio não muda nada e devolve o selo atual. A resposta traz os campos de cadastro, mas não os da regra; para ver a regra, consulte o selo.

Parâmetros de caminho

iduuidobrigatório

Id do selo.

Corpo da requisição (JSON)

name_adminstring

Novo nome interno. Não pode ficar em branco.

name_desktopstring

Novo texto no computador.

name_mobilestring

Novo texto no celular.

stylestring

TIP

Novo estilo.

appearanceobject

Nova aparência (substitui a anterior inteira).

display_onobject

Novo display_on (substitui o anterior inteiro).

statusstring

AD

Novo status.

positioninteger

Nova ordem.

DELETE/api/v1/admin/stickers/{id}Admin

Apaga um selo

Apaga o selo de forma definitiva, junto com todas as ligações a produtos.

Parâmetros de caminho

iduuidobrigatório

Id do selo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/stickers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name_admin": "Lançamento",
    "name_desktop": "Novo",
    "style": "T",
    "appearance": {"bg_color": "#16a34a", "text_color": "#ffffff", "position": "tl"},
    "display_on": {"product_card": true, "pdp": true, "quickview": false}
  }'

Resposta

201Selo criado

json

{
  "id": "e902d002-71a3-4f85-9383-4e2416d72a64",
  "name_admin": "Lançamento",
  "name_desktop": "Novo",
  "name_mobile": "",
  "style": "T",
  "appearance": { "bg_color": "#16a34a", "position": "tl", "text_color": "#ffffff" },
  "display_on": { "pdp": true, "quickview": false, "product_card": true },
  "status": "A",
  "position": 0,
  "created_at": "2026-10-11T21:09:15.141574Z",
  "updated_at": "2026-10-11T21:09:15.141574Z"
}

200Selo consultado (com regra)

json

{
  "id": "e902d002-71a3-4f85-9383-4e2416d72a64",
  "name_admin": "Lançamento",
  "name_desktop": "Novo",
  "name_mobile": "",
  "style": "T",
  "appearance": { "bg_color": "#16a34a", "position": "tl", "text_color": "#ffffff" },
  "display_on": { "pdp": true, "quickview": true, "product_card": true },
  "status": "A",
  "position": 0,
  "created_at": "2026-10-11T21:09:15.141574Z",
  "updated_at": "2026-10-11T21:09:15.18554Z",
  "assignment_mode": "rule",
  "rule_type": "new_arrival",
  "rule_params": { "days": 7 },
  "last_evaluated_at": "2026-10-11T21:09:15.229012Z"
}

200Selo apagado

json

{ "message": "sticker deleted" }

Campos do selo

iduuid

Id do selo.

name_adminstring

Nome interno.

name_desktopstring

Texto no computador.

name_mobilestring

Texto no celular. Pode ser vazio.

stylestring

TIP

Estilo.

appearanceobject

Aparência.

display_onobject

Onde aparece (product_card, pdp, quickview).

statusstring

AD

Status.

positioninteger

Ordem.

vendor_iduuid

Seller dono. Ausente nos selos da loja.

product_countinteger

Produtos ligados. Só na lista.

assignment_modestring

manualrule

Modo de ligação. Na consulta e na lista.

rule_typestring

Tipo da regra, no modo rule.

rule_paramsobject

Parâmetros da regra. Só na consulta.

starts_atstring

Início da validade da regra, RFC 3339. Ausente sem janela.

ends_atstring

Fim da validade da regra, RFC 3339. Ausente sem janela.

last_evaluated_atstring

Última avaliação da regra. Ausente se nunca foi avaliada.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name_admin` ausente ou em branco	`{"error":"failed to create sticker","detail":"name_admin is required"}`
400	`style` ou `status` fora da lista	`{"error":"failed to create sticker","detail":"invalid style \"X\" (expected T, I, or P)"}`
400	Apagar um selo que não existe	`{"error":"failed to delete sticker","detail":"sticker <id> not found"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado	`{"error":"module_disabled","module":"product-stickers"}`
404	`GET` ou `PUT` de um selo que não existe	`{"error":"sticker not found"}`
500	Id que não é UUID, ou `status` inválido na lista	`{"error":"failed to get sticker","detail":"..."}`

Veja também

Criar e gerenciar selos

Lista, cria, consulta, altera e apaga selos de produto, com textos, aparência, onde aparecem e status.

GET/api/v1/admin/stickersAdmin

Lista os selos

Devolve todos os selos, sem paginação, ordenados por position e, empatando, do mais novo para o mais antigo. Cada item traz product_count, o número de produtos ligados.

Parâmetros de consulta

statusstring

AD

Só os selos com este status. Outro valor responde 500 failed to list stickers.

vendor_iduuid

Só os selos deste seller.

marketplace_onlyboolean

Com true, só os selos da própria loja (sem seller). Ignorado se vendor_id vier junto.

POST/api/v1/admin/stickersAdmin

Cria um selo

Responde 201 com o selo. Só name_admin é obrigatório.

Corpo da requisição (JSON)

name_adminstringobrigatório

Nome interno, que só o painel mostra.

name_desktopstring

Texto do selo no computador. Vazio repete name_admin.

name_mobilestring

Texto do selo no celular.

stylestringpadrão: T

TIP

T texto, I imagem, P pictograma (a vitrine o desenha como texto). Minúsculas são aceitas.

appearanceobjectpadrão: {}

Aparência livre: bg_color, text_color, radius, opacity, padding, font_size, position, image_url.

display_onobject

Onde mostrar: product_card, pdp e quickview (booleanos). Omitido, os três ficam ligados.

statusstringpadrão: A

AD

A ativo, D desativado.

positionintegerpadrão: 0

Ordem de exibição entre os selos; menor aparece primeiro.

GET/api/v1/admin/stickers/{id}Admin

Consulta um selo

Devolve o selo, incluindo o modo (assignment_mode), a regra e a data da última avaliação.

Parâmetros de caminho

iduuidobrigatório

Id do selo.

PUT/api/v1/admin/stickers/{id}Admin

Altera um selo

Altera só os campos enviados. Um corpo vazio não muda nada e devolve o selo atual. A resposta traz os campos de cadastro, mas não os da regra; para ver a regra, consulte o selo.

Parâmetros de caminho

iduuidobrigatório

Id do selo.

Corpo da requisição (JSON)

name_adminstring

Novo nome interno. Não pode ficar em branco.

name_desktopstring

Novo texto no computador.

name_mobilestring

Novo texto no celular.

stylestring

TIP

Novo estilo.

appearanceobject

Nova aparência (substitui a anterior inteira).

display_onobject

Novo display_on (substitui o anterior inteiro).

statusstring

AD

Novo status.

positioninteger

Nova ordem.

DELETE/api/v1/admin/stickers/{id}Admin

Apaga um selo

Apaga o selo de forma definitiva, junto com todas as ligações a produtos.

Parâmetros de caminho

iduuidobrigatório

Id do selo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/stickers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name_admin": "Lançamento",
    "name_desktop": "Novo",
    "style": "T",
    "appearance": {"bg_color": "#16a34a", "text_color": "#ffffff", "position": "tl"},
    "display_on": {"product_card": true, "pdp": true, "quickview": false}
  }'

Resposta

201Selo criado

json

{
  "id": "e902d002-71a3-4f85-9383-4e2416d72a64",
  "name_admin": "Lançamento",
  "name_desktop": "Novo",
  "name_mobile": "",
  "style": "T",
  "appearance": { "bg_color": "#16a34a", "position": "tl", "text_color": "#ffffff" },
  "display_on": { "pdp": true, "quickview": false, "product_card": true },
  "status": "A",
  "position": 0,
  "created_at": "2026-10-11T21:09:15.141574Z",
  "updated_at": "2026-10-11T21:09:15.141574Z"
}

200Selo consultado (com regra)

json

{
  "id": "e902d002-71a3-4f85-9383-4e2416d72a64",
  "name_admin": "Lançamento",
  "name_desktop": "Novo",
  "name_mobile": "",
  "style": "T",
  "appearance": { "bg_color": "#16a34a", "position": "tl", "text_color": "#ffffff" },
  "display_on": { "pdp": true, "quickview": true, "product_card": true },
  "status": "A",
  "position": 0,
  "created_at": "2026-10-11T21:09:15.141574Z",
  "updated_at": "2026-10-11T21:09:15.18554Z",
  "assignment_mode": "rule",
  "rule_type": "new_arrival",
  "rule_params": { "days": 7 },
  "last_evaluated_at": "2026-10-11T21:09:15.229012Z"
}

200Selo apagado

json

{ "message": "sticker deleted" }

Campos do selo

iduuid

Id do selo.

name_adminstring

Nome interno.

name_desktopstring

Texto no computador.

name_mobilestring

Texto no celular. Pode ser vazio.

stylestring

TIP

Estilo.

appearanceobject

Aparência.

display_onobject

Onde aparece (product_card, pdp, quickview).

statusstring

AD

Status.

positioninteger

Ordem.

vendor_iduuid

Seller dono. Ausente nos selos da loja.

product_countinteger

Produtos ligados. Só na lista.

assignment_modestring

manualrule

Modo de ligação. Na consulta e na lista.

rule_typestring

Tipo da regra, no modo rule.

rule_paramsobject

Parâmetros da regra. Só na consulta.

starts_atstring

Início da validade da regra, RFC 3339. Ausente sem janela.

ends_atstring

Fim da validade da regra, RFC 3339. Ausente sem janela.

last_evaluated_atstring

Última avaliação da regra. Ausente se nunca foi avaliada.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name_admin` ausente ou em branco	`{"error":"failed to create sticker","detail":"name_admin is required"}`
400	`style` ou `status` fora da lista	`{"error":"failed to create sticker","detail":"invalid style \"X\" (expected T, I, or P)"}`
400	Apagar um selo que não existe	`{"error":"failed to delete sticker","detail":"sticker <id> not found"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado	`{"error":"module_disabled","module":"product-stickers"}`
404	`GET` ou `PUT` de um selo que não existe	`{"error":"sticker not found"}`
500	Id que não é UUID, ou `status` inválido na lista	`{"error":"failed to get sticker","detail":"..."}`