Documentação de Compre Junto

Visão Geral

O módulo de Compre Junto (Pair Offer) é uma ferramenta poderosa de cross-selling que permite ao lojista criar ofertas associando dois produtos específicos. 🤝

Diferente do Upsell, onde um produto é oferecido como substituto ou complemento individual, o Compre Junto foca na venda casada, incentivando o cliente a adquirir um par de produtos que se complementam (ex: Tênis + Meia) através de condições comerciais vantajosas. 🚀

Através desta funcionalidade, é possível definir um produto principal e um produto relacionado. Quando ambos são adicionados ao carrinho, o sistema aplica automaticamente a regra de preço configurada para a oferta. 🛒

A flexibilidade do módulo permite que a regra de preço seja aplicada a apenas um dos produtos do par ou a ambos, dependendo da estratégia comercial adotada. ✨

O gerenciamento do módulo abrange a criação, edição e remoção das associações entre produtos, garantindo que as ofertas estejam sempre alinhadas com o estoque e as campanhas vigentes. 🛠️

O acesso às funcionalidades de Compre Junto é controlado por escopos de segurança rigorosos. 🔒

Para visualizar as ofertas existentes, é necessário o escopo PAIR_OFFER_READ. Já para operações que alteram o estado das ofertas (criação, atualização ou remoção), o usuário deve possuir o escopo PAIR_OFFER_WRITE.

Entidades Envolvidas

Produto Principal (productId1): O item que serve de âncora para a oferta. ⚓
Produto Relacionado (productId2): O item que completa o par da oferta de Compre Junto. 🔗
Regra de Preço: Define o benefício financeiro da oferta. Para o Compre Junto, a regra deve ser obrigatoriamente do tipo automática. 💰
Target: Define qual produto do par receberá o desconto da regra de preço. Pode ser o produto 1, o produto 2 ou ambos. 🎯

Notas e Considerações

Uma regra de negócio crítica é que o benefício do Compre Junto só é ativado quando ambos os produtos estão presentes no carrinho. ⚠️

Caso um dos itens seja removido, o sistema recalcula os preços automaticamente para os valores originais, garantindo a integridade da margem de lucro. 🔄

Além disso, a validação de regras de preço exige que estas sejam do tipo automática. O uso de regras manuais ou baseadas em cupons não é suportado diretamente pelo módulo de Compre Junto, pois o objetivo é a aplicação fluida do desconto durante a navegação. ✅

Detalhe de Compre Junto

GET /products/pair-offers/{productId1}/linked/{productId2}

Retorna os dados detalhados de uma associação de Compre Junto.

Descrição

Este endpoint permite a consulta detalhada de um par específico de produtos configurados no módulo de Compre Junto. 🔍

Ao fornecer os IDs de ambos os produtos, o sistema retorna a configuração exata da oferta, incluindo o target (qual produto recebe o benefício), o status de ativação e a regra de preço vinculada. ✨

Este recurso é essencial para validar configurações individuais de ofertas e garantir que os benefícios comerciais aplicados entre dois produtos específicos estejam corretos.

O acesso a este detalhamento exige a permissão PAIR_OFFER_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

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
productId1	integer	Sim	ID do produto principal da oferta
productId2	integer	Sim	ID do produto relacionado da oferta

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/pair-offers/101/linked/202/ \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"
curl --request GET \
  --url {{MAIN_URL}}/products/pair-offers/101/linked/202/ \
  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "product1": {
3    "productId": 1,
4    "brandId": 0,
5    "brandName": "",
6    "mainCategoryId": 0,
7    "mainCategoryName": "",
8    "type": "product",
9    "sku": "ABC321",
10    "name": "Techbrand smartphone",
11    "active": true,
12    "url": "tech-brand-smartphone.html",
13    "comparisonPrice": 299,
14    "stock": 20,
15    "medias": [],
16    "combination": [],
17    "currentAttributes": [],
18    "restriction": null
19  },
20  "product2": {
21    "productId": 2,
22    "brandId": 0,
23    "brandName": "",
24    "mainCategoryId": 0,
25    "mainCategoryName": "",
26    "type": "product",
27    "sku": "ABC123",
28    "name": "Carregador Techbrand",
29    "active": true,
30    "url": "tech-brand-smartphone-carregador.html",
31    "comparisonPrice": 186,
32    "stock": 20,
33    "medias": [],
34    "combination": [],
35    "currentAttributes": [],
36    "restriction": null
37  },
38  "priceRule": {
39    "id": 1,
40    "name": "pair-offer-price-rule",
41    "trigger": "automatic",
42    "ruleTarget": "product",
43    "origin": "pair-offer",
44    "applyInGroup": false,
45    "updateComparisonPrice": "not-update",
46    "basePriceField": "sale-price",
47    "code": null,
48    "beginQuantity": 0,
49    "endQuantity": 0,
50    "value": 2,
51    "valueType": "percentage",
52    "priority": 0,
53    "active": true,
54    "scheduling": null,
55    "tradePolicies": [
56      1,
57      2,
58    ],
59    "productIds": [],
60    "productCategoryIds": [],
61    "productBrandIds": [],
62    "lastUpdateUserName": null,
63    "createdAt": "2023-05-27 22:08:30",
64    "updatedAt": "2025-08-20 12:41:24"
65  },
66  "target": "product-2",
67  "active": false,
68  "createdAt": "2023-05-27 22:08:30",
69  "updatedAt": "2025-10-23 17:15:59"
70}
{
  "product1": {
    "productId": 1,
    "brandId": 0,
    "brandName": "",
    "mainCategoryId": 0,
    "mainCategoryName": "",
    "type": "product",
    "sku": "ABC321",
    "name": "Techbrand smartphone",
    "active": true,
    "url": "tech-brand-smartphone.html",
    "comparisonPrice": 299,
    "stock": 20,
    "medias": [],
    "combination": [],
    "currentAttributes": [],
    "restriction": null
  },
  "product2": {
    "productId": 2,
    "brandId": 0,
    "brandName": "",
    "mainCategoryId": 0,
    "mainCategoryName": "",
    "type": "product",
    "sku": "ABC123",
    "name": "Carregador Techbrand",
    "active": true,
    "url": "tech-brand-smartphone-carregador.html",
    "comparisonPrice": 186,
    "stock": 20,
    "medias": [],
    "combination": [],
    "currentAttributes": [],
    "restriction": null
  },
  "priceRule": {
    "id": 1,
    "name": "pair-offer-price-rule",
    "trigger": "automatic",
    "ruleTarget": "product",
    "origin": "pair-offer",
    "applyInGroup": false,
    "updateComparisonPrice": "not-update",
    "basePriceField": "sale-price",
    "code": null,
    "beginQuantity": 0,
    "endQuantity": 0,
    "value": 2,
    "valueType": "percentage",
    "priority": 0,
    "active": true,
    "scheduling": null,
    "tradePolicies": [
      1,
      2,
    ],
    "productIds": [],
    "productCategoryIds": [],
    "productBrandIds": [],
    "lastUpdateUserName": null,
    "createdAt": "2023-05-27 22:08:30",
    "updatedAt": "2025-08-20 12:41:24"
  },
  "target": "product-2",
  "active": false,
  "createdAt": "2023-05-27 22:08:30",
  "updatedAt": "2025-10-23 17:15:59"
}

⚠️ Possíveis erros:

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

Listagem de Compre Junto

GET /products/pair-offers

Retorna a listagem de ofertas de Compre Junto com suporte a filtros e paginação.

Descrição

Este endpoint permite a recuperação de todas as ofertas de cross-selling do tipo "Compre Junto" configuradas na plataforma. 📋

A resposta é estruturada agrupando os pares de ofertas em torno de um produto principal, facilitando a visualização de todas as combinações disponíveis para um determinado item do catálogo. 📦

O endpoint suporta filtros avançados, permitindo buscar ofertas por IDs de produtos, SKUs ou nomes, facilitando o gerenciamento de grandes volumes de associações comerciais. 🔍

Além disso, é possível expandir a resposta para incluir detalhes completos das regras de preço associadas a cada par, permitindo validar rapidamente as condições comerciais ativas.

O acesso a este recurso requer que o usuário possua a permissão PAIR_OFFER_READ vinculada ao seu token de autenticaçã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

Campos Disponíveis (fields)

Campo	Descrição
productPriceRule	Retorna os detalhes da regra de preço vinculada a cada par de oferta

Campos de Condição Disponíveis

Campo	Tipo	Descrição
productId1	integer	ID do produto principal da oferta
productId2	integer	ID do produto relacionado da oferta
sku	string	SKU de um dos produtos do par (busca em ambos)
name	string	Nome de um dos produtos do par (busca em ambos)
productPriceRuleId	integer	ID da regra de preço associada
active	boolean	Status de ativação da oferta
createdAt	string	Data de criação da oferta
updatedAt	string	Data de atualização da oferta

Campos de Ordenação Disponíveis

Campo	Descrição
createdAt	Ordenar pela data de criação
updatedAt	Ordenar pela data de atualização

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/pair-offers \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "productPriceRule"
7    ],
8    "conditions": {
9      "type": "AND",
10      "conditions": []
11    },
12    "limit": 10,
13    "offset": 0
14  }'
curl --request GET \
  --url {{MAIN_URL}}/products/pair-offers \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "fields": [
      "productPriceRule"
    ],
    "conditions": {
      "type": "AND",
      "conditions": []
    },
    "limit": 10,
    "offset": 0
  }'

✅ Resposta de Sucesso

1{
2  "registers": [
3{
4				"mainProduct": {
5					"productId": 1,
6					"brandId": 0,
7					"brandName": "",
8					"mainCategoryId": 0,
9					"mainCategoryName": "",
10					"type": "product",
11					"sku": "ABC123",
12					"name": "Techbrand smartphone",
13					"active": true,
14					"url": "/techbrand-smartphone.html",
15					"comparisonPrice": 3500,
16					"stock": 22,
17					"medias": [],
18					"combination": [],
19					"currentAttributes": [],
20					"restriction": null
21				},
22				"pairOffer": [
23					{
24						"relatedProduct": {
25							"productId": 2,
26							"brandId": 0,
27							"brandName": "",
28							"mainCategoryId": 0,
29							"mainCategoryName": "",
30							"type": "product",
31							"sku": "ABC123",
32							"name": "Techbrand smartphone carregador USB C",
33							"active": true,
34							"url": "/tech-brand-smartphone-carregador.html",
35							"comparisonPrice": 459,
36							"stock": 20,
37							"medias": [],
38							"combination": [],
39							"currentAttributes": [],
40							"restriction": null
41						},
42						"productPriceRuleId": 1,
43						"target": "product-2",
44						"active": true,
45						"priceRule": {
46							"id": 1,
47							"name": "pair-offer-price-rule",
48							"trigger": "automatic",
49							"ruleTarget": "product",
50							"origin": "pair-offer",
51							"applyInGroup": false,
52							"updateComparisonPrice": "original-sale-price",
53							"basePriceField": "sale-price",
54							"code": null,
55							"beginQuantity": 0,
56							"endQuantity": 0,
57							"value": 100,
58							"valueType": "percentage",
59							"priority": 0,
60							"active": true,
61							"scheduling": null,
62							"tradePolicies": [],
63							"productIds": [],
64							"productCategoryIds": [],
65							"productBrandIds": [],
66							"lastUpdateUserName": null,
67							"createdAt": "2023-10-04 19:11:08",
68							"updatedAt": "2025-09-03 14:14:04"
69						},
70						"createdAt": "2023-10-04 19:11:08",
71						"updatedAt": ""
72					}
73				]
74			},
75  ],
76  "pagination": {
77    "limit": 10,
78    "offset": 0,
79    "pages": 1,
80    "registers": 1
81  }
82}
{
  "registers": [
{
				"mainProduct": {
					"productId": 1,
					"brandId": 0,
					"brandName": "",
					"mainCategoryId": 0,
					"mainCategoryName": "",
					"type": "product",
					"sku": "ABC123",
					"name": "Techbrand smartphone",
					"active": true,
					"url": "/techbrand-smartphone.html",
					"comparisonPrice": 3500,
					"stock": 22,
					"medias": [],
					"combination": [],
					"currentAttributes": [],
					"restriction": null
				},
				"pairOffer": [
					{
						"relatedProduct": {
							"productId": 2,
							"brandId": 0,
							"brandName": "",
							"mainCategoryId": 0,
							"mainCategoryName": "",
							"type": "product",
							"sku": "ABC123",
							"name": "Techbrand smartphone carregador USB C",
							"active": true,
							"url": "/tech-brand-smartphone-carregador.html",
							"comparisonPrice": 459,
							"stock": 20,
							"medias": [],
							"combination": [],
							"currentAttributes": [],
							"restriction": null
						},
						"productPriceRuleId": 1,
						"target": "product-2",
						"active": true,
						"priceRule": {
							"id": 1,
							"name": "pair-offer-price-rule",
							"trigger": "automatic",
							"ruleTarget": "product",
							"origin": "pair-offer",
							"applyInGroup": false,
							"updateComparisonPrice": "original-sale-price",
							"basePriceField": "sale-price",
							"code": null,
							"beginQuantity": 0,
							"endQuantity": 0,
							"value": 100,
							"valueType": "percentage",
							"priority": 0,
							"active": true,
							"scheduling": null,
							"tradePolicies": [],
							"productIds": [],
							"productCategoryIds": [],
							"productBrandIds": [],
							"lastUpdateUserName": null,
							"createdAt": "2023-10-04 19:11:08",
							"updatedAt": "2025-09-03 14:14:04"
						},
						"createdAt": "2023-10-04 19:11:08",
						"updatedAt": ""
					}
				]
			},
  ],
  "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.

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

Cadastro de Compre Junto

PUT /products/pair-offers

Cria ou atualiza uma associação de Compre Junto entre dois produtos.

Descrição

Este endpoint é utilizado para o gerenciamento de ofertas casadas, permitindo vincular dois produtos em uma estratégia de Compre Junto. 🛠️

A operação é do tipo save (update or create): se a associação entre os dois produtos já existir, ela será atualizada com os novos parâmetros; caso contrário, uma nova oferta será criada. 🔄

Durante o processo, o sistema realiza validações rigorosas para garantir a integridade da oferta:

Ambos os produtos devem existir e estar aptos para venda.
Se uma regra de preço for informada, ela deve ser obrigatoriamente do tipo automática. 💰

O campo target é fundamental, pois define a aplicação do benefício: se o desconto será aplicado no produto principal, no relacionado ou em ambos quando estiverem juntos no carrinho. 🎯

A execução desta operação exige o escopo de segurança PAIR_OFFER_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 de Corpo (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
productId1	integer	Sim	ID do produto principal da oferta
productId2	integer	Sim	ID do produto relacionado da oferta
target	string	Sim	Alvo do benefício. Valores aceitos: `PRODUCT_1`, `PRODUCT_2`, `BOTH`
productPriceRuleId	integer	Não	ID da regra de preço automática vinculada
active	boolean	Não	Status de ativação da oferta (Default: true)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/pair-offers \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "productId1": 101,
6    "productId2": 202,
7    "target": "PRODUCT_2",
8    "productPriceRuleId": 5,
9    "active": true
10  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/pair-offers \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "productId1": 101,
    "productId2": 202,
    "target": "PRODUCT_2",
    "productPriceRuleId": 5,
    "active": true
  }'

✅ Resposta de Sucesso

1{
2  "productId1": 101,
3  "productId2": 202,
4  "target": "PRODUCT_2",
5  "productPriceRuleId": 5,
6  "active": true,
7  "createdAt": "2024-01-01 10:00:00",
8  "updatedAt": "2024-01-01 10:05:00"
9}
{
  "productId1": 101,
  "productId2": 202,
  "target": "PRODUCT_2",
  "productPriceRuleId": 5,
  "active": true,
  "createdAt": "2024-01-01 10:00:00",
  "updatedAt": "2024-01-01 10:05:00"
}

⚠️ Possíveis erros:

Código Interno	Código Http	Descrição
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.
UAPPI_STORE_PRICE_RULE_NOT_FOUND	404	A regra de preço solicitada não foi encontrada.
UAPPI_STORE_PRICE_RULE_MUST_BE_AUTOMATIC	400	A regra de preço solicitada deve ser configurada como automática.

Remoção de Compre Junto

DELETE /products/pair-offers

Remove definitivamente a associação de Compre Junto entre dois produtos.

Descrição

Este endpoint permite a exclusão definitiva de uma oferta de Compre Junto do catálogo da loja. 🗑️

Ao remover a oferta, os produtos envolvidos deixam de ter o benefício comercial vinculado quando comprados em conjunto, e o sistema para de aplicar a regra de preço que estava associada ao par. 🔄

Esta operação é irreversível e deve ser utilizada quando uma estratégia de cross-selling de par de produtos chega ao fim ou precisa ser completamente reformulada.

Para executar a remoção, o usuário deve possuir a permissão PAIR_OFFER_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 de Corpo (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
productId1	integer	Sim	ID do produto principal da oferta
productId2	integer	Sim	ID do produto relacionado da oferta

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/pair-offers \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "productId1": 101,
6    "productId2": 202
7  }'
curl --request DELETE \
  --url {{MAIN_URL}}/products/pair-offers \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "productId1": 101,
    "productId2": 202
  }'

✅ Resposta de Sucesso

1true
true

⚠️ Possíveis erros:

Código Interno	Código Http	Descrição
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto 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 Compre Junto

Visão Geral

Entidades Envolvidas

Notas e Considerações

Detalhe de Compre Junto

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Listagem de Compre Junto

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:

Cadastro de Compre Junto

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo (JSON)

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros: