Documentação de Selos

Visão Geral

O módulo de Selos é uma ferramenta visual essencial para destacar características específicas, promoções ou selos de qualidade diretamente nas imagens dos produtos. 🎨

Através desta funcionalidade, o lojista pode criar elementos gráficos que são sobrepostos à imagem do produto, tanto na vitrine quanto na página de detalhes, fornecendo informações imediatas ao cliente de forma atraente e profissional. 🚀

Cada selo é composto por uma imagem (ou cores de fundo e texto) e um conjunto de regras de exibição altamente customizáveis.

É possível definir com precisão a posição (horizontal e vertical) e a proporção que o selo deve ocupar em relação à imagem do produto, garantindo que a identidade visual da loja seja preservada em diferentes dispositivos e layouts. 🛠️

O sistema permite que selos sejam vinculados a produtos de forma individual ou automatizada (através de promoções), e cada vínculo pode ter sua própria configuração de agendamento, permitindo campanhas com data de início e fim programadas. 🕒

O acesso às funcionalidades deste módulo é restrito e controlado por escopos de segurança. 🔒

A visualização de dados requer a permissão SEAL_READ, enquanto qualquer operação de modificação, incluindo criação, edição, remoção ou configuração de exibição, exige a permissão SEAL_WRITE. Estas permissões devem estar vinculadas ao token de autenticação administrativa.

Entidades Envolvidas

• Selo (Seal): A entidade principal que contém a imagem original, nome e cores padrão. 🏷️
• Configuração (Setting): Define o comportamento visual do selo, como coordenadas de posicionamento e escalas de tamanho para diferentes contextos (showcase/detail). 📐
• Vínculo (Link): Representa a associação entre um selo e um produto, podendo herdar a configuração padrão do selo ou possuir uma customizada para aquele produto específico. 🔗
• Agendamento (Scheduling): Entidade opcional que determina o período de validade do selo no produto. 📅

Notas e Considerações

Uma regra de negócio fundamental é que o sistema suporta o posicionamento via coordenadas horizontalPosition e verticalPosition, que aceitam valores estratégicos como top, bottom, left, right e center. 📍

As proporções (proportionInProductDetail e proportionInProductShowcase) são definidas em valores flutuantes, permitindo um ajuste fino do tamanho do selo.

Além disso, o sistema possui um mecanismo de limpeza de cache automático: qualquer alteração em um selo ou em seus vínculos dispara a invalidação do cache de produtos relacionados, garantindo que o cliente final visualize a informação atualizada instantaneamente. ⚡

A integridade dos vínculos é garantida por validações que impedem o uso de selos inexistentes ou a aplicação de configurações inválidas. ✅

Listagem de Selos

Descrição

Este endpoint permite a recuperação de todos os selos configurados no catálogo da loja. 📋

A listagem é uma ferramenta fundamental para a gestão visual da loja, permitindo que o administrador localize selos específicos para edição ou para novos vínculos com produtos. 🛠️

O sistema oferece recursos avançados de filtragem e ordenação, possibilitando buscas por nome, status de ativação (active) e até mesmo por critérios de posicionamento técnico (através do join com as configurações de selo). 🔍

Cada item retornado na listagem inclui os dados básicos do selo e, opcionalmente, o objeto de configuração padrão (setting), que detalha onde e como o selo deve ser renderizado por padrão caso não haja uma regra específica no vínculo com o produto. ✨

A resposta é paginada para garantir a performance do sistema mesmo em catálogos com grande volume de elementos gráficos. 📶

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_READ. 🔒

---

Parâmetros

Headers Obrigatórios

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/seals \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "registers": [
3    {
4      "id": 1,
5      "name": "Selo de Natal",
6      "active": true,
7      "textColor": "#FFFFFF",
8      "sealColor": "#FF0000",
9      "image": "https://static.uappi.com.br/seals/natal.png",
10      "originalImage": "seals/natal_orig.png",
11      "setting": {
12        "id": 10,
13        "horizontalPosition": "right",
14        "verticalPosition": "top",
15        "proportionInProductDetail": 0.15,
16        "proportionInProductShowcase": 0.10,
17        "scheduling": null
18      },
19      "promotionLinkId": 1,
20      "createdAt": "2023-11-20 10:00:00",
21      "updatedAt": "2023-11-20 10:00:00"
22    }
23  ],
24  "pagination": {
25    "limit": 10,
26    "offset": 0,
27    "pages": 1,
28    "registers": 1
29  }
30}

Listagem de Todos os Selos

Descrição

Este endpoint fornece uma lista completa e não paginada de todos os selos disponíveis. 📋

Diferente da listagem principal, este recurso é otimizado para o uso em interfaces administrativas onde é necessário exibir todos os selos em componentes de seleção (dropdowns ou modais de vínculo), facilitando a escolha rápida pelo administrador. ✨

Todos os selos são retornados, ativos e inativos. O retorno é um objeto em que a chave é o ID do selo e o valor é o texto de exibição: a descrição do selo ou, quando ela estiver vazia, o nome. Cores e demais dados do selo não são retornados. 🚀

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_READ. 🔒

---

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/seals/all \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

Retorna um objeto no formato ID do selo => texto. Exemplo: o selo 4 tem a descrição "Entrega sem custo"; o selo 7 não tem descrição, então aparece o nome "Promo". Sem selos cadastrados, o retorno é [].

1{
2  "4": "Entrega sem custo",
3  "7": "Promo"
4}

Detalhe de Selo

Descrição

Este endpoint permite a consulta detalhada de um único selo do catálogo. 🔍

É essencial para visualizar todas as propriedades de um selo, desde seus dados básicos de identificação e cores até sua configuração visual completa (setting), que define como ele é renderizado nas vitrines e páginas de produto da loja. 🎨

O retorno fornece uma visão 360º da entidade, incluindo as URLs das imagens (original e processada) e o histórico de criação e atualização. ✨

Se o selo possuir uma configuração padrão associada, o objeto setting será retornado detalhando as posições horizontal/vertical e as proporções de escala. 📐

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_READ. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/seals/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 5,
3  "name": "Oferta de Verão",
4  "active": true,
5  "textColor": "#000000",
6  "sealColor": "#FFD100",
7  "image": "https://loja.com.br/seals/verao.png",
8  "originalImage": "seals/verao_orig.png",
9  "setting": {
10    "id": 12,
11    "horizontalPosition": "left",
12    "verticalPosition": "top",
13    "proportionInProductDetail": 0.2,
14    "proportionInProductShowcase": 0.15,
15    "scheduling": {
16      "id": 1,
17      "startDate": "2023-11-20 00:00:00",
18      "endDate": "2023-11-20 22:00:00"
19    }
20  },
21  "promotionLinkId": 1,
22  "createdAt": "2023-11-20 11:00:00",
23  "updatedAt": "2023-11-21 09:30:00"
24}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Cadastro de Selo

Descrição

Este endpoint permite a criação de um novo selo no catálogo da loja. 🚀

O processo de cadastro envolve a definição do nome do selo, seu status inicial e as características visuais básicas, como cores de texto e fundo. 🎨

Um diferencial importante deste endpoint é a possibilidade de enviar, já no ato da criação, o objeto de configuração padrão (setting). 📐

Neste objeto, o lojista define como o selo deve se comportar visualmente por padrão: sua posição (ex: top, right) e o tamanho proporcional que deve ocupar nas imagens de detalhe e vitrine. Caso não seja enviado, o sistema aplicará valores padrão internos. 🛠️

É uma ferramenta poderosa para manter a consistência visual das promoções em toda a loja. ✨

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/seals \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Oferta Relâmpago",
6    "active": true,
7    "textColor": "#FFFFFF",
8    "sealColor": "#E63946",
9    "setting": {
10      "horizontalPosition": "left",
11      "verticalPosition": "top",
12      "proportionInProductDetail": 0.20,
13      "proportionInProductShowcase": 0.15
14    }
15  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "id": 5,
3  "name": "Oferta Relâmpago",
4  "active": true,
5  "textColor": "#FFFFFF",
6  "sealColor": "#E63946",
7  "image": null,
8  "originalImage": null,
9  "setting": {
10    "id": 12,
11    "horizontalPosition": "left",
12    "verticalPosition": "top",
13    "proportionInProductDetail": 0.2,
14    "proportionInProductShowcase": 0.15,
15    "scheduling": null
16  },
17  "promotionLinkId": null,
18  "createdAt": "2023-11-20 11:00:00",
19  "updatedAt": "2023-11-20 11:00:00"
20}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Atualização de Selo

Descrição

Este endpoint permite a modificação dos atributos básicos de um selo já cadastrado no sistema. 🛠️

É a ferramenta ideal para ajustes finos em campanhas ativas, permitindo alterar o nome do selo, seu status de ativação ou atualizar sua identidade visual através das cores de texto e fundo. 🎨

Diferente do cadastro, a atualização deste endpoint foca apenas nos dados da entidade principal do selo. Caso seja necessário alterar as configurações de exibição (posicionamento e proporções), deve-se utilizar o endpoint específico de Configuração de Selo. A única exceção é o selo que ainda não tem configuração de exibição (selos antigos): nesse caso, o campo setting enviado aqui cria a configuração. ✨

Qualquer alteração realizada em um selo que possua vínculos ativos com produtos disparará automaticamente a limpeza de cache desses produtos, garantindo que a nova identidade visual seja refletida imediatamente na loja. ⚡

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/seals/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Oferta de Verão",
6    "active": true,
7    "textColor": "#000000",
8    "sealColor": "#FFD100"
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 5,
3  "name": "Oferta de Verão",
4  "active": true,
5  "textColor": "#000000",
6  "sealColor": "#FFD100",
7  "image": "https://static.uappi.com.br/seals/verao.png",
8  "originalImage": "seals/verao_orig.png",
9  "setting": {
10    "id": 12,
11    "horizontalPosition": "left",
12    "verticalPosition": "top",
13    "proportionInProductDetail": 0.2,
14    "proportionInProductShowcase": 0.15,
15    "scheduling": null
16  },
17  "promotionLinkId": null,
18  "createdAt": "2023-11-20 11:00:00",
19  "updatedAt": "2023-11-21 09:30:00"
20}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Atualização de Imagem do Selo

Descrição

Este endpoint permite o upload de novos arquivos gráficos para compor a identidade visual de um selo. 🖼️

O processo de envio utiliza o padrão multipart/form-data, garantindo a compatibilidade com envios de arquivos binários. 🛠️

Ao receber a imagem, o sistema realiza um processamento automático inteligente: ele armazena o arquivo original (para referência e futuras edições) e gera simultaneamente uma versão otimizada no formato WebP, garantindo a melhor performance de carregamento e qualidade visual nas vitrines da loja. 🚀

Se o selo já possuía uma imagem vinculada, os arquivos antigos são removidos automaticamente do servidor para evitar o consumo desnecessário de espaço em disco. 🗑️

A atualização da imagem também dispara a invalidação de cache dos produtos que utilizam este selo, assegurando que o novo visual seja propagado instantaneamente para o consumidor final. ⚡

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo (Form Data)

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/seals/5/image \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: multipart/form-data" \
5  --form "image=@/caminho/para/o/selo.png"

✅ Resposta de Sucesso

HTTP Status: 200 OK

Retorna o objeto do selo atualizado com as novas URLs de imagem.

1{
2  "id": 5,
3  "name": "Oferta de Verão",
4  "active": true,
5  "textColor": "#000000",
6  "sealColor": "#FFD100",
7  "image": "https://static.uappi.com.br/seals/verao_v2.webp",
8  "originalImage": "seals/verao_v2_orig.png",
9  "setting": {
10    "id": 12,
11    "horizontalPosition": "left",
12    "verticalPosition": "top",
13    "proportionInProductDetail": 0.2,
14    "proportionInProductShowcase": 0.15,
15    "scheduling": null
16  },
17	"promotionLinkId": null,
18  "createdAt": "2023-11-20 11:00:00",
19  "updatedAt": "2023-11-22 14:20:00"
20}

⚠️ Possíveis erros:

Remoção da Imagem do Selo

Descrição

Este endpoint permite a limpeza dos arquivos de imagem de um selo sem a necessidade de excluir o selo em si. 🖼️

Ao ser executado, o sistema remove fisicamente os arquivos (original e a versão otimizada em WebP) do servidor de armazenamento e limpa as referências nos campos image e originalImage do banco de dados. 🛠️

Esta operação é útil quando se deseja transformar um selo baseado em imagem em um selo baseado apenas em cores sólidas (configuradas via textColor e sealColor), ou antes de realizar o upload de uma nova imagem. 🎨

Assim como na remoção do selo, esta ação dispara a limpeza de cache dos produtos vinculados para garantir que a alteração visual seja imediata na loja. ⚡

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/seals/5/image \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true

⚠️ Possíveis erros:

Vínculo de Selo com Produto

Descrição

Este endpoint permite a gestão granular da exibição de selos nos produtos do catálogo. 🔗

A operação é extremamente flexível, permitindo que múltiplos vínculos sejam processados em uma única requisição.

Você pode associar um selo a um produto usando a configuração padrão do selo ou, se preferir, informar uma configuração específica (productSealSettingId) para aquele vínculo, permitindo que o mesmo selo apareça em posições diferentes dependendo do produto. 📐

O sistema utiliza o campo action para determinar o comportamento da operação:

• save: Cria um novo vínculo ou atualiza um existente (mantendo a data de atualização).
• remove: Exclui o vínculo entre o selo e o produto.

Uma regra de negócio crítica é a validação do tipo de produto: o sistema impede que selos sejam vinculados diretamente a variações. Os vínculos devem ser feitos sempre no produto pai, garantindo a integridade da exibição na loja. ⚠️

Além disso, qualquer alteração realizada através deste endpoint dispara automaticamente a limpeza de cache dos produtos afetados, garantindo que as mudanças visuais sejam refletidas imediatamente para os clientes. ⚡

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

A requisição aceita um array de objetos, onde cada objeto representa um vínculo a ser processado.

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/seals/link \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '[
5    {
6      "productId": 101,
7      "productSealId": 5,
8      "action": "save"
9    },
10    {
11      "productId": 102,
12      "productSealId": 5,
13      "productSealSettingId": 20,
14      "action": "save"
15    },
16    {
17      "productId": 103,
18      "productSealId": 2,
19      "action": "remove"
20    }
21  ]'

✅ Resposta de Sucesso

HTTP Status: 200 OK

O retorno confirma o processamento de cada item enviado.

1[
2  {
3    "productId": 101,
4    "productSealId": 5,
5    "productSealSettingId": 12,
6    "action": "save",
7    "error": null
8  },
9  {
10    "productId": 102,
11    "productSealId": 5,
12    "productSealSettingId": 20,
13    "action": "save",
14    "error": null
15  },
16  {
17    "productId": 103,
18    "productSealId": 2,
19    "productSealSettingId": 8,
20    "action": "remove",
21    "error": null
22  }
23]

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer no processamento individual de cada item (retornados no campo error).

Remoção de Selo

Descrição

Este endpoint permite a exclusão definitiva de um selo do catálogo da loja. 🗑️

Ao executar esta operação, o sistema realiza uma limpeza completa para garantir a integridade do banco de dados e do armazenamento de arquivos.

Isso inclui a remoção física das imagens do servidor e a exclusão automática de qualquer agendamento ou configuração de exibição vinculada exclusivamente a este selo. 🛠️

É importante notar que a remoção de um selo que está sendo exibido em produtos afetará imediatamente a visualização desses itens na loja. ⚠️

O sistema dispara a limpeza de cache dos produtos que possuíam o selo vinculado, garantindo que os clientes parem de visualizá-lo instantaneamente após a confirmação da deleção. ⚡

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/seals/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true

⚠️ Possíveis erros:

Cadastro de Configuração de Selo

Descrição

Este endpoint permite a definição técnica de como um selo deve ser exibido nas interfaces da loja. 📐

Diferente do cadastro do selo (entidade principal), este recurso foca exclusivamente nas métricas de exibição. Aqui são definidos os eixos de posicionamento (horizontal e vertical) e as escalas de tamanho que o selo deve ocupar em relação ao produto. 🛠️

Estas configurações podem ser criadas de forma independente e posteriormente vinculadas a selos ou a vínculos específicos entre selos e produtos, permitindo uma reutilização eficiente de padrões visuais em todo o catálogo. ✨

O sistema valida as coordenadas informadas para garantir que o selo seja renderizado dentro dos limites esperados do layout. 🚀

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/seals/setting \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "horizontalPosition": "right",
6    "verticalPosition": "bottom",
7    "proportionInProductDetail": 0.12,
8    "proportionInProductShowcase": 0.08
9  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "id": 25,
3  "horizontalPosition": "right",
4  "verticalPosition": "bottom",
5  "proportionInProductDetail": 0.12,
6  "proportionInProductShowcase": 0.08,
7  "scheduling": null
8}

⚠️ Possíveis erros:

Atualização de Configuração de Selo

Descrição

Este endpoint permite o ajuste fino das regras de exibição de selos já cadastradas. 🛠️

Através dele, o administrador pode corrigir o posicionamento ou alterar as proporções de escala de uma configuração específica.

Como as configurações podem estar vinculadas a múltiplos selos ou produtos, uma única atualização aqui pode propagar mudanças visuais em diversos pontos da loja simultaneamente. 📐

É uma ferramenta poderosa para manutenção de campanhas, permitindo ajustes de layout sem a necessidade de re-vincular os selos aos produtos. ✨

Qualquer alteração realizada em uma configuração ativa dispara a limpeza de cache dos produtos que a utilizam, garantindo que o novo posicionamento seja aplicado instantaneamente na vitrine e nos detalhes do produto. ⚡

Para realizar esta operação, o usuário deve estar autenticado em ambiente administrativo e possuir o escopo de permissão SEAL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/seals/setting/25 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "horizontalPosition": "center",
6    "verticalPosition": "top",
7    "proportionInProductDetail": 0.18,
8    "proportionInProductShowcase": 0.12
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 25,
3  "horizontalPosition": "center",
4  "verticalPosition": "top",
5  "proportionInProductDetail": 0.18,
6  "proportionInProductShowcase": 0.12,
7  "scheduling": null
8}

⚠️ Possíveis erros: