Documentação de Upsell

Visão Geral

O módulo de Upsell é uma ferramenta estratégica projetada para elevar o ticket médio das vendas, permitindo a oferta de produtos complementares ou superiores durante a jornada de compra do cliente. 🚀

Através desta funcionalidade, o lojista pode configurar itens específicos para serem exibidos em pontos cruciais do fluxo de navegação, como na página de produto ou no carrinho de compras, incentivando a adição de mais valor ao pedido final. 🛒

Cada oferta de upsell é construída sobre a base de um produto já existente no catálogo, mas ganha uma camada adicional de personalização para o contexto da oferta.

É possível definir títulos e descrições exclusivas para o momento do upsell, além de associar regras de preço automáticas que garantem condições comerciais diferenciadas apenas quando o item é adquirido através desta modalidade. ✨

O gerenciamento do módulo abrange desde a criação das ofertas até a definição refinada de onde e como elas devem aparecer. 🛠️

O sistema permite o controle de visibilidade por políticas comerciais e a ordenação prioritária das ofertas em cada localização, garantindo que as promoções mais relevantes tenham maior destaque. 📶

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

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

Entidades Envolvidas

Produto: Representa a entidade base que será ofertada. Cada registro de upsell está intrinsecamente ligado a um único ID de produto. 📦
Regra de Preço: Entidade opcional que define o comportamento financeiro da oferta. Para ser utilizada em um upsell, a regra deve ser obrigatoriamente do tipo automática. 💰
Localização (Location): Define os pontos de contato no layout da loja onde o upsell pode ser renderizado, como CART_PAGE ou PRODUCT_PAGE. 📍
Política Comercial: Determina o escopo de validade da oferta, permitindo segmentar o upsell para diferentes canais de venda ou grupos de clientes. 🏢

Notas e Considerações

Uma regra de negócio fundamental é a unicidade do produto no contexto de upsell: o sistema impede que um mesmo produto seja cadastrado em múltiplas ofertas de upsell simultaneamente. ⚠️

O cadastro de um novo upsell para um produto que já possui uma oferta ativa resultará em erro.

Além disso, a integridade das ofertas depende da validade dos produtos e das regras de preço associadas. 🛠️

Se uma regra de preço for vinculada, ela passará por uma validação para garantir que seu tipo de aplicação seja automático, caso contrário, a operação será rejeitada.

Essas travas garantem que a experiência do cliente final seja consistente e alinhada com as configurações comerciais da loja. ✅

Detalhe de Upsell

GET /products/upsells/{upsellId}

Retorna os dados detalhados de um upsell específico.

Descrição

Este endpoint permite a recuperação detalhada de todas as informações configuradas para uma oferta de upsell específica. 🚀

É utilizado principalmente no ambiente administrativo quando o lojista deseja visualizar ou editar as configurações de uma oferta já existente, como os títulos de exibição, a descrição promocional, as regras de preço atreladas e as políticas comerciais onde o item está disponível.

O acesso a este endpoint requer obrigatoriamente a permissão de segurança UPSELL_READ. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
upsellId	integer	Sim	ID único da oferta de upsell

Campos Disponíveis (fields)

Campo	Descrição
priceRule	Retorna os detalhes da regra de preço vinculada ao upsell
segmentation	Retorna as regras de segmentação configuradas para a oferta
locations	Retorna a lista de locais onde o upsell está configurado para aparecer
product	Retorna informações básicas do produto vinculado (DMC de produto simples)

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/upsells/10 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "product",
7      "locations",
8      "priceRule"
9    ]
10  }'
curl --request GET \
  --url {{MAIN_URL}}/products/upsells/10 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "fields": [
      "product",
      "locations",
      "priceRule"
    ]
  }'

✅ Resposta de Sucesso

1{
2  "id": 10,
3  "productId": 500,
4  "productPriceRuleId": 5,
5  "priceRule": {
6    "id": 5,
7    "name": "Desconto de Natal",
8    "trigger": "automatic",
9    "ruleTarget": "product",
10    "origin": "api",
11    "applyInGroup": false,
12    "updateComparisonPrice": "yes",
13    "basePriceField": "salePrice",
14    "code": "NATAL2026",
15    "beginQuantity": 1,
16    "endQuantity": 10,
17    "value": 15.50,
18    "valueType": "percentage",
19    "priority": 1,
20    "active": true,
21    "scheduling": {
22      "id": 10,
23      "startDate": "2026-12-01 00:00:00",
24      "endDate": "2026-12-25 23:59:59"
25    },
26    "tradePolicies": [
27      1,
28      2
29    ],
30    "productIds": [
31      500
32    ],
33    "productCategoryIds": [
34      15
35    ],
36    "productBrandIds": [
37      3
38    ],
39    "lastUpdateUserName": "admin_user",
40    "createdAt": "2023-11-01 09:00:00",
41    "updatedAt": "2023-11-01 10:00:00"
42  },
43  "segmentation": {
44    "id": 1,
45    "operator": "AND",
46    "sellerId": 12,
47    "userForAllSellers": true,
48    "rules": [
49      {
50        "id": 1,
51        "ruleType": "category-id",
52        "ruleOperator": "in",
53        "ruleValue": [
54          1,
55          2,
56          2
57        ],
58        "entityMap": {
59          "1": "category1"  
60        },
61        "createdAt": "2024-08-21 00:00:00",
62        "updatedAt": "2025-09-01 13:11:44"
63      }
64    ]
65  },
66  "simpleProduct": {
67    "productId": 500,
68    "brandId": 3,
69    "brandName": "Marca Exemplo",
70    "mainCategoryId": 15,
71    "mainCategoryName": "Categoria Principal",
72    "type": "simple",
73    "sku": "PROD-500",
74    "name": "Produto Exemplo Upsell",
75    "active": true,
76    "url": "produto-exemplo-upsell",
77    "comparisonPrice": 150.00,
78    "stock": 100,
79    "medias": [
80      {
81        "id": 20,
82        "type": "image",
83        "title": "Imagem Frontal",
84        "alternativeText": "Visão frontal do produto",
85        "file": "imagem.jpg",
86        "originalFile": "imagem_original.jpg",
87        "size": 1024,
88        "originalSize": 2048,
89        "width": 800,
90        "height": 800,
91        "url": "https://cdn.uappi.com.br/imagem.jpg"
92      }
93    ],
94    "combination": [1,2,3],
95    "currentAttributes": [
96      {
97        "id": 5,
98        "name": "Cor",
99        "value": {
100          "id": 10,
101          "label": "Azul",
102          "image": "cor_azul.png",
103          "originalImage": "cor_azul_original.png",
104          "color": "#0000FF",
105          "order": 1
106        }
107      }
108    ],
109    "restriction": {
110      "tradePolicyId": 1,
111      "requiredAge": 18
112    }
113  },
114  "title": "Upsell Campanha Natal",
115  "displayTitle": "Aproveite esta oferta especial!",
116  "displayDescription": "Adicione este item por um preço reduzido.",
117  "displayButtonText": "Adicionar ao Carrinho",
118  "quantity": 1,
119  "active": true,
120  "locations": {
121    "CART_PAGE": 1
122  },
123  "tradePolicies": [
124    1,
125    2
126  ],
127  "createdAt": "2023-11-01 10:00:00",
128  "updatedAt": "2023-11-01 10:00:00"
129}
{
  "id": 10,
  "productId": 500,
  "productPriceRuleId": 5,
  "priceRule": {
    "id": 5,
    "name": "Desconto de Natal",
    "trigger": "automatic",
    "ruleTarget": "product",
    "origin": "api",
    "applyInGroup": false,
    "updateComparisonPrice": "yes",
    "basePriceField": "salePrice",
    "code": "NATAL2026",
    "beginQuantity": 1,
    "endQuantity": 10,
    "value": 15.50,
    "valueType": "percentage",
    "priority": 1,
    "active": true,
    "scheduling": {
      "id": 10,
      "startDate": "2026-12-01 00:00:00",
      "endDate": "2026-12-25 23:59:59"
    },
    "tradePolicies": [
      1,
      2
    ],
    "productIds": [
      500
    ],
    "productCategoryIds": [
      15
    ],
    "productBrandIds": [
      3
    ],
    "lastUpdateUserName": "admin_user",
    "createdAt": "2023-11-01 09:00:00",
    "updatedAt": "2023-11-01 10:00:00"
  },
  "segmentation": {
    "id": 1,
    "operator": "AND",
    "sellerId": 12,
    "userForAllSellers": true,
    "rules": [
      {
        "id": 1,
        "ruleType": "category-id",
        "ruleOperator": "in",
        "ruleValue": [
          1,
          2,
          2
        ],
        "entityMap": {
          "1": "category1"  
        },
        "createdAt": "2024-08-21 00:00:00",
        "updatedAt": "2025-09-01 13:11:44"
      }
    ]
  },
  "simpleProduct": {
    "productId": 500,
    "brandId": 3,
    "brandName": "Marca Exemplo",
    "mainCategoryId": 15,
    "mainCategoryName": "Categoria Principal",
    "type": "simple",
    "sku": "PROD-500",
    "name": "Produto Exemplo Upsell",
    "active": true,
    "url": "produto-exemplo-upsell",
    "comparisonPrice": 150.00,
    "stock": 100,
    "medias": [
      {
        "id": 20,
        "type": "image",
        "title": "Imagem Frontal",
        "alternativeText": "Visão frontal do produto",
        "file": "imagem.jpg",
        "originalFile": "imagem_original.jpg",
        "size": 1024,
        "originalSize": 2048,
        "width": 800,
        "height": 800,
        "url": "https://cdn.uappi.com.br/imagem.jpg"
      }
    ],
    "combination": [1,2,3],
    "currentAttributes": [
      {
        "id": 5,
        "name": "Cor",
        "value": {
          "id": 10,
          "label": "Azul",
          "image": "cor_azul.png",
          "originalImage": "cor_azul_original.png",
          "color": "#0000FF",
          "order": 1
        }
      }
    ],
    "restriction": {
      "tradePolicyId": 1,
      "requiredAge": 18
    }
  },
  "title": "Upsell Campanha Natal",
  "displayTitle": "Aproveite esta oferta especial!",
  "displayDescription": "Adicione este item por um preço reduzido.",
  "displayButtonText": "Adicionar ao Carrinho",
  "quantity": 1,
  "active": true,
  "locations": {
    "CART_PAGE": 1
  },
  "tradePolicies": [
    1,
    2
  ],
  "createdAt": "2023-11-01 10:00:00",
  "updatedAt": "2023-11-01 10:00:00"
}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_UPSELL_NOT_FOUND	404	O upsell solicitado não foi encontrado.

Listagem de Upsells

GET /products/upsells

Retorna a listagem de upsells com suporte a filtros e paginação.

Descrição

Este endpoint é destinado à recuperação de todas as ofertas de upsell configuradas no catálogo de produtos. 📋

O upsell é uma ferramenta fundamental para estratégias de aumento de ticket médio, permitindo que o lojista ofereça itens complementares ou de valor superior em momentos estratégicos da jornada de compra, como na visualização do produto ou no fechamento do carrinho.

A listagem suporta o padrão de busca avançada da plataforma, permitindo filtrar por status de ativação, IDs de produtos vinculados, localizações específicas de exibição e até mesmo por SKUs. 🔍

Além disso, é possível utilizar o recurso de campos customizados para expandir a resposta e trazer detalhes completos sobre as regras de preço associadas, segmentações de público e informações resumidas do produto principal.

O acesso a este recurso é restrito ao ambiente administrativo e requer obrigatoriamente que o usuário possua o escopo de permissão UPSELL_READ. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {token}	Token de autenticação

Campos Disponíveis (fields)

Campo	Descrição
priceRule	Retorna os detalhes da regra de preço vinculada ao upsell
segmentation	Retorna as regras de segmentação configuradas para a oferta
locations	Retorna a lista de locais onde o upsell está configurado para aparecer
product	Retorna informações básicas do produto vinculado (DMC de produto simples)

Campos de Condição Disponíveis

Campo	Tipo	Descrição
id	integer	ID do upsell
title	string	Título interno do upsell
displayTitle	string	Título de exibição para o cliente
productPriceRuleId	integer	ID da regra de preço associada
productId	integer	ID do produto vinculado
active	boolean	Status de ativação da oferta
locationId	string	Identificador do local de exibição
productName	string	Nome do produto para busca parcial
productSku	string	SKU do produto para busca exata

Campos de Ordenação Disponíveis

Campo	Descrição
id	ID da entidade
title	Título interno do upsell
order	Ordem de exibição configurada

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/upsells \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "product",
7      "locations"
8    ],
9    "conditions": {
10      "type": "AND",
11      "conditions": [
12        {
13          "field": "active",
14          "value": 1
15        }
16      ]
17    },
18    "limit": 10,
19    "offset": 0
20  }'
curl --request GET \
  --url {{MAIN_URL}}/products/upsells \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "fields": [
      "product",
      "locations"
    ],
    "conditions": {
      "type": "AND",
      "conditions": [
        {
          "field": "active",
          "value": 1
        }
      ]
    },
    "limit": 10,
    "offset": 0
  }'

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 10,
5      "productId": 500,
6      "productPriceRuleId": 5,
7      "priceRule": null,
8      "segmentation": null,
9      "simpleProduct": null,
10      "title": "Upsell Campanha Natal",
11      "displayTitle": "Aproveite esta oferta especial!",
12      "displayDescription": "Adicione este item por um preço reduzido.",
13      "displayButtonText": "Adicionar ao Carrinho",
14      "quantity": 1,
15      "active": true,
16      "locations": [],
17      "tradePolicies": [
18        1,
19        2
20      ],
21      "createdAt": "2023-11-01 10:00:00",
22      "updatedAt": "2023-11-01 10:00:00"
23    }
24  ],
25  "pagination": {
26    "limit": 10,
27    "offset": 0,
28    "pages": 1,
29    "registers": 1
30  }
31}
{
  "registers": [
    {
      "id": 10,
      "productId": 500,
      "productPriceRuleId": 5,
      "priceRule": null,
      "segmentation": null,
      "simpleProduct": null,
      "title": "Upsell Campanha Natal",
      "displayTitle": "Aproveite esta oferta especial!",
      "displayDescription": "Adicione este item por um preço reduzido.",
      "displayButtonText": "Adicionar ao Carrinho",
      "quantity": 1,
      "active": true,
      "locations": [],
      "tradePolicies": [
        1,
        2
      ],
      "createdAt": "2023-11-01 10:00:00",
      "updatedAt": "2023-11-01 10:00:00"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "pages": 1,
    "registers": 1
  }
}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_UPSELL_NOT_FOUND	404	O upsell solicitado não foi encontrado.

Listagem Simplificada de Upsells

GET /products/upsells/all

Retorna um mapa de IDs de produtos e seus respectivos títulos de upsell.

Descrição

Este endpoint fornece uma visão consolidada e leve de todas as ofertas de upsell cadastradas na plataforma. 🚀

Diferente da listagem principal, este recurso foca na entrega de um mapeamento direto entre o identificador do produto (productId) e o título interno configurado para o upsell. 📋

É ideal para componentes de interface que necessitam apenas de uma lista rápida para seleção ou verificação de existência. ✨

O retorno deste endpoint é estruturado como um objeto JSON onde as chaves são os IDs dos produtos e os valores são os títulos das ofertas.

Esta estrutura permite um acesso O(1) no lado do cliente para verificar se um determinado produto já possui um upsell vinculado, sem a necessidade de iterar sobre uma lista completa de registros. ⚡

Por ser uma operação de leitura otimizada, ela não suporta parâmetros de filtro ou expansão de campos.

O acesso a este recurso requer a permissão de segurança UPSELL_READ. 🔒

A requisição deve ser autenticada via token administrativo e enviada através do método GET.

Como este endpoint retorna todos os registros de uma vez de forma simplificada, ele é recomendado para contextos onde a performance de carregamento inicial é uma prioridade. 📈

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "1": "Upsell Campanha Natal",
3  "2": "Upsell Especial Black Friday",
4  "3": "Upsell Campanha de Verão"
5}
{
  "1": "Upsell Campanha Natal",
  "2": "Upsell Especial Black Friday",
  "3": "Upsell Campanha de Verão"
}

Cadastro de Upsell

POST /products/upsells

Cria um novo registro de upsell vinculado a um produto.

Descrição

Este endpoint permite a criação de uma nova oferta de upsell no catálogo da loja. 🚀

O processo de cadastro consiste em vincular um produto existente a uma estrutura de oferta promocional, onde o lojista define como o item será apresentado ao cliente final (título e descrição de exibição) e quais as condições comerciais aplicadas. 🛒

É uma ferramenta poderosa para campanhas de marketing e estratégias de cross-selling. ✨

Durante o cadastro, é possível associar uma regra de preço ao upsell. 💰

Uma validação crítica do sistema exige que, caso uma regra seja informada, ela deve ser obrigatoriamente do tipo automática, garantindo que o desconto seja aplicado sem a necessidade de cupons. 🛠️

Além disso, o sistema impõe uma regra de unicidade: cada produto do catálogo só pode possuir uma única oferta de upsell ativa por vez. Tentar cadastrar um produto que já possua um upsell resultará em erro. ⚠️

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

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
productId	integer	✅	ID do produto base que será ofertado como upsell
productPriceRuleId	integer	❌	ID da regra de preço automática (opcional)
title	string	✅	Título interno para controle do lojista (máx 255)
displayTitle	string	✅	Título promocional exibido para o cliente na loja
displayDescription	string	✅	Descrição detalhada da oferta para o cliente
displayButtonText	string	✅	Texto personalizado do botão de compra
quantity	integer	✅	Quantidade padrão de itens para esta oferta
active	boolean	✅	Define se a oferta já inicia como ativa ou inativa
tradePolicies	array	❌	Lista de IDs de políticas comerciais onde a oferta é válida
tradePolicies.*	array	✅	ID de uma política comercial onde a oferta é válida (exemplo: "1": true)

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/upsells \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "productId": 123,
6    "productPriceRuleId": 123,
7    "title": "Upsell Campanha Natal",
8    "displayTitle": "Aproveite esta oferta especial!",
9    "displayDescription": "Adicione este item por um preço reduzido.",
10    "displayButtonText": "Adicionar ao Carrinho",
11    "quantity": 1,
12    "active": true,
13    "tradePolicies": {
14      "1": true, 
15      "2": false
16    }
17  }'
curl --request POST \
  --url {{MAIN_URL}}/products/upsells \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "productId": 123,
    "productPriceRuleId": 123,
    "title": "Upsell Campanha Natal",
    "displayTitle": "Aproveite esta oferta especial!",
    "displayDescription": "Adicione este item por um preço reduzido.",
    "displayButtonText": "Adicionar ao Carrinho",
    "quantity": 1,
    "active": true,
    "tradePolicies": {
      "1": true, 
      "2": false
    }
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "id": 10,
3  "productId": 500,
4  "productPriceRuleId": 5,
5  "priceRule": null,
6  "segmentation": null,
7  "simpleProduct": null,
8  "title": "Upsell Campanha Natal",
9  "displayTitle": "Aproveite esta oferta especial!",
10  "displayDescription": "Adicione este item por um preço reduzido.",
11  "displayButtonText": "Adicionar ao Carrinho",
12  "quantity": 1,
13  "active": true,
14  "locations": [],
15  "tradePolicies": [
16    1,
17    2
18  ],
19  "createdAt": "2023-11-01 10:00:00",
20  "updatedAt": "2023-11-01 10:00:00"
21}
{
  "id": 10,
  "productId": 500,
  "productPriceRuleId": 5,
  "priceRule": null,
  "segmentation": null,
  "simpleProduct": null,
  "title": "Upsell Campanha Natal",
  "displayTitle": "Aproveite esta oferta especial!",
  "displayDescription": "Adicione este item por um preço reduzido.",
  "displayButtonText": "Adicionar ao Carrinho",
  "quantity": 1,
  "active": true,
  "locations": [],
  "tradePolicies": [
    1,
    2
  ],
  "createdAt": "2023-11-01 10:00:00",
  "updatedAt": "2023-11-01 10:00:00"
}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_UPSELL_PRODUCT_DUPLICATED	400	O produto solicitado já está sendo usado em outro upsell.
UAPPI_STORE_PRICE_RULE_MUST_BE_AUTOMATIC	400	A regra de preço solicitada deve ser configurada como automática.
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_PRICE_RULE_NOT_FOUND	404	A regra de preço solicitada não foi encontrada.

Atualização de Upsell

PUT /products/upsells/{upsellId}

Atualiza os dados de um registro de upsell existente.

Descrição

Este endpoint permite a modificação completa dos dados de uma oferta de upsell previamente cadastrada no sistema. 📝

O lojista pode utilizar este recurso para ajustar a estratégia de vendas, alterando os textos promocionais que aparecem para o cliente (título e descrição), trocando a regra de preço aplicada ou modificando as políticas comerciais onde a oferta deve ser válida.

É uma operação essencial para a manutenção e otimização das campanhas de marketing da loja. ✨

Assim como no cadastro, a atualização passa por validações rigorosas de integridade. 🛠️

Se uma nova regra de preço for associada à oferta, o sistema validará se ela é do tipo automática e se o ID informado é válido.

Além disso, a regra de unicidade de produto continua sendo aplicada: não é permitido alterar o produto vinculado para um que já possua outro cadastro de upsell ativo.

Todas as alterações são refletidas em tempo real nos canais de venda configurados. 🚀

Para executar esta ação, é necessário que o usuário esteja autenticado administrativamente e possua o escopo de permissão UPSELL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
upsellId	integer	Sim	ID único da oferta de upsell a ser atualizada

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
productId	integer	✅	ID do produto base (deve ser o mesmo ou um produto sem outro upsell)
productPriceRuleId	integer	❌	ID da regra de preço automática (opcional)
title	string	✅	Título interno para controle do lojista (máx 255)
displayTitle	string	✅	Título promocional exibido para o cliente na loja
displayDescription	string	✅	Descrição detalhada da oferta para o cliente
displayButtonText	string	✅	Texto personalizado do botão de compra
quantity	integer	✅	Quantidade padrão de itens para esta oferta
active	boolean	✅	Status de ativação da oferta
tradePolicies	array	❌	Lista de IDs de políticas comerciais atualizada

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/upsells/10 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "productId": 500,
6    "productPriceRuleId": 6,
7    "title": "Upsell Campanha Natal - Atualizado",
8    "displayTitle": "Oferta Imperdível de Natal!",
9    "displayDescription": "Garanta este item complementar com desconto exclusivo.",
10    "displayButtonText": "Aproveitar Agora",
11    "quantity": 2,
12    "active": true,
13    "tradePolicies": [1]
14  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/upsells/10 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "productId": 500,
    "productPriceRuleId": 6,
    "title": "Upsell Campanha Natal - Atualizado",
    "displayTitle": "Oferta Imperdível de Natal!",
    "displayDescription": "Garanta este item complementar com desconto exclusivo.",
    "displayButtonText": "Aproveitar Agora",
    "quantity": 2,
    "active": true,
    "tradePolicies": [1]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 10,
3  "productId": 500,
4  "productPriceRuleId": 5,
5  "priceRule": null,
6  "segmentation": null,
7  "simpleProduct": null,
8  "title": "Upsell Campanha Natal",
9  "displayTitle": "Aproveite esta oferta especial!",
10  "displayDescription": "Adicione este item por um preço reduzido.",
11  "displayButtonText": "Adicionar ao Carrinho",
12  "quantity": 1,
13  "active": true,
14  "locations": [],
15  "tradePolicies": [
16    1,
17    2
18  ],
19  "createdAt": "2023-11-01 10:00:00",
20  "updatedAt": "2023-11-01 10:00:00"
21}
{
  "id": 10,
  "productId": 500,
  "productPriceRuleId": 5,
  "priceRule": null,
  "segmentation": null,
  "simpleProduct": null,
  "title": "Upsell Campanha Natal",
  "displayTitle": "Aproveite esta oferta especial!",
  "displayDescription": "Adicione este item por um preço reduzido.",
  "displayButtonText": "Adicionar ao Carrinho",
  "quantity": 1,
  "active": true,
  "locations": [],
  "tradePolicies": [
    1,
    2
  ],
  "createdAt": "2023-11-01 10:00:00",
  "updatedAt": "2023-11-01 10:00:00"
}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_UPSELL_NOT_FOUND	404	O upsell solicitado não foi encontrado.
UAPPI_STORE_UPSELL_PRODUCT_DUPLICATED	400	O produto solicitado já está sendo usado em outro upsell.
UAPPI_STORE_PRICE_RULE_MUST_BE_AUTOMATIC	400	A regra de preço solicitada deve ser configurada como automática.
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_PRICE_RULE_NOT_FOUND	404	A regra de preço solicitada não foi encontrada.

Ordenação de Upsells

PUT /products/upsells/order

Atualiza a prioridade de exibição dos upsells por localização.

Descrição

Este endpoint permite que o lojista gerencie a prioridade de apresentação das ofertas de upsell ao cliente final. 📶

Como o sistema suporta a exibição de upsells em múltiplos locais (ex: página de produto, carrinho, checkout), este recurso possibilita definir uma ordenação específica para cada uma dessas localizações, garantindo que as ofertas mais estratégicas ou de melhor conversão apareçam em destaque. 🚀

A operação é processada em lote, permitindo enviar um conjunto de IDs de upsells com suas respectivas localizações e posições de ordem em uma única requisição. 📦

O sistema valida cada item enviado, garantindo que os identificadores de upsell existam e que as localizações informadas sejam válidas dentro dos padrões da plataforma (UPPER_SNAKE_CASE). 🔍

Após o processamento, as novas posições são salvas e passam a ser respeitadas imediatamente nas listagens públicas da loja.

O acesso a esta funcionalidade requer obrigatoriamente a permissão de segurança UPSELL_WRITE. 🔒

Por se tratar de uma alteração estrutural no comportamento de exibição do catálogo, ela deve ser realizada exclusivamente através do ambiente administrativo autenticado.

O sucesso da operação retorna os dados atualizados das ordenações processadas, permitindo a confirmação imediata da alteração. ✅

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
upsells	array	✅	Lista de objetos contendo os dados de ordenação
upsells.*.productUpsellId	integer	✅	ID único do registro de upsell
upsells.*.locationId	string	✅	Identificador da localização (ex: PRODUCT_PAGE, CART_PAGE)
upsells.*.order	integer	✅	Posição numérica da ordem (quanto menor, maior a prioridade)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/upsells/order \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "upsells": [
6      {
7        "productUpsellId": 10,
8        "locationId": "CART_PAGE",
9        "order": 1
10      },
11      {
12        "productUpsellId": 11,
13        "locationId": "CART_PAGE",
14        "order": 2
15      }
16    ]
17  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/upsells/order \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "upsells": [
      {
        "productUpsellId": 10,
        "locationId": "CART_PAGE",
        "order": 1
      },
      {
        "productUpsellId": 11,
        "locationId": "CART_PAGE",
        "order": 2
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1[
2  {
3    "productUpsellId": 10,
4    "locationId": "CART_PAGE",
5    "order": 1,
6    "errorCode": "",
7    "errorMessage": ""
8  },
9  {
10    "productUpsellId": 11,
11    "locationId": "CART_PAGE",
12    "order": 2,
13    "errorCode": "",
14    "errorMessage": ""
15  }
16]
[
  {
    "productUpsellId": 10,
    "locationId": "CART_PAGE",
    "order": 1,
    "errorCode": "",
    "errorMessage": ""
  },
  {
    "productUpsellId": 11,
    "locationId": "CART_PAGE",
    "order": 2,
    "errorCode": "",
    "errorMessage": ""
  }
]

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_UPSELL_NOT_FOUND	404	O upsell solicitado não foi encontrado.

Remoção de Upsell

DELETE /products/upsells/{upsellId}

Exclui um registro de upsell do sistema.

Descrição

Este endpoint permite a exclusão definitiva de uma oferta de upsell do sistema. 🗑️

Ao executar esta operação, o vínculo entre o produto e a estrutura promocional de upsell é rompido, e o item deixará de ser exibido como uma sugestão complementar em todas as localizações configuradas (como página de produto e carrinho).

Esta ação é irreversível e deve ser utilizada quando uma campanha de cross-selling é encerrada ou quando o produto não deve mais ser ofertado sob condições especiais de upsell. ⚠️

Para realizar a remoção, o usuário deve estar autenticado administrativamente e possuir o escopo de permissão UPSELL_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {token}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
upsellId	integer	Sim	ID único da oferta de upsell a ser removida

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true
true

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_UPSELL_NOT_FOUND	404	O upsell solicitado não foi encontrado.

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Documentação de Upsell

Visão Geral

Entidades Envolvidas

Notas e Considerações

Detalhe de Upsell

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Campos Disponíveis (fields)

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Listagem de Upsells

Descrição

Parâmetros

Headers Obrigatórios

Campos Disponíveis (fields)

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Listagem Simplificada de Upsells

Descrição

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

✅ Resposta de Sucesso

Cadastro de Upsell