Skip to content

Carrinho

Visão Geral

O carrinho de compras é um dos principais componentes de um e-commerce.

Ele permite que o cliente adicione e gerencie múltiplos produtos em um único pedido, armazenando temporariamente os itens selecionados.

Além disso, o carrinho pode oferecer recursos como aplicação de cupons de desconto, promoções, cálculo de frete, atualização de quantidades e visualização do valor total da compra.

Autenticação

Os endpoints de carrinho não exigem autenticação na maioria dos casos.

A exceção ocorre em funcionalidades promocionais relacionadas ao sistema de pontos e à carteira do cliente, que exigem vínculo com o usuário para validação.

Token

O carrinho pode ser criado a partir de quase todos os endpoints, retornando um token no header da resposta, que deve ser armazenado e reutilizado nas requisições seguintes.

Esse token representa o carrinho atual e permite a utilização sem autenticação.

Caso ele seja perdido, ao realizar qualquer nova solicitação, um novo carrinho e token serão gerados automaticamente.

Embora o token seja retornado inicialmente via header, nas requisições subsequentes ele será enviado por meio de cookie.

Entidades relacionadas

Promocional Cupom

No contexto do carrinho, o cupom permite a aplicação de descontos por meio de um hash que representa um cupom específico.

Essa aplicação envolve regras e período de validade, sendo uma forma simples para o lojista oferecer descontos à loja ou a clientes específicos.

Em geral, apenas quem gera o cupom conhece seu hash e define para quem ele será distribuído.

Promocional Carteira

A carteira do cliente é uma entidade que armazena valores disponíveis, provenientes de cartões-presente, vouchers ou outras ações promocionais.

Em alguns casos, pode conter valores de estornos de compras que não foram concluídas corretamente.

Esse saldo pode ser utilizado no carrinho como forma de pagamento ou desconto.

Promocional Sistema de Pontos

O sistema de pontos premia o cliente após cada compra, permitindo o acúmulo de pontos que podem ser convertidos em descontos para compras futuras.

No carrinho, esses pontos podem ser aplicados para redução do valor total ou, caso o saldo seja suficiente, para pagamento integral de um produto ou serviço.

Produtos de Upsell

Os produtos de upsell são sugestões exibidas, geralmente, no checkout, oferecendo algum desconto adicional com base nos itens presentes no carrinho.

Cada item pode atender a regras específicas de segmentação, fazendo com que determinados produtos sejam exibidos como oferta.

Compre Junto

Produtos de compre junto são sugestões complementares ao produto principal.

Quando o item sugerido é adicionado ao carrinho, pode ser aplicado um desconto, conforme a configuração definida pelo lojista.

Notas e Considerações

O carrinho é recalculado constantemente e passa repetidamente pelos mesmos processos a cada endpoint acionado.

Por esse motivo, alguns erros podem se repetir em diferentes operações.

Nesta documentação, foram priorizados os erros mais relevantes dentro do contexto específico de cada endpoint.

Aplicação de Cupom no Carrinho

PUT /cart/promotionals/coupon

Possibilita aplicação de cupom no carrinho

Descrição

Endpoint responsável por permitir que o cliente aplique um cupom válido no carrinho, concedendo desconto sobre o valor dos produtos 🎟️.

A aplicação do cupom segue um conjunto de regras de validação, garantindo coerência com as configurações comerciais da loja.

Limite de uso O cupom pode possuir um número máximo de utilizações, definido conforme a configuração realizada.

Período de validade A aplicação depende de um agendamento ativo, com data de início e data de expiração previamente definidas.

Segmentação de produtos Nem todo cupom é aplicável a todos os produtos, podendo existir regras específicas de segmentação que restringem seu uso.

Compatibilidade com promoções Cupons e promoções podem ser mutuamente excludentes, seja por bloqueio do próprio cupom ou por restrição imposta pela promoção ativa.

Dependência do carrinho A aplicação do cupom exige a presença de itens no carrinho, não sendo possível validá-lo em um carrinho vazio.

Status do cupom O cupom precisa estar ativo para que a aplicação seja permitida e o desconto concedido.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
hashstring✅hash do cupom que deve ser aplicado no carrinho (max 100 caracteres)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/cart/promotionals/coupon \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "hash": "abc123456",
6  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "abc12332124623462",
3  "countryCode": "",
4  "quoteZipcode": "",
5  "subtotalValue": 300,
6  "shippingValue": 0,
7  "discountValue": 50,
8  "additionValue": 0,
9  "totalValue": 250,
10  "discountPreview": {
11    "cashDiscount": {
12      "discountPercentage": 0,
13      "discountValue": 0,
14      "valueWithDiscount": 250
15    },
16    "pointSystem": null
17  },
18  "installments": [],
19  "requestedProductMap": [
20    {
21      "productId": 1,
22      "quantity": 1,
23      "code": null,
24      "upsellId": null,
25      "productPairOfferId": null
26    }
27  ],
28  "discountMap": {
29    "promotion": [],
30    "coupon": {
31      "discountId": 1,
32      "discountType": "coupon",
33      "discountValue": 50,
34      "discountMainCode": "#cupom",
35      "discountTitle": "Cupom 50"
36    },
37    "customer-wallet": null,
38    "point-system": null
39  },
40  "customer": null,
41  "addresses": [],
42  "orders": [
43    {
44      "orderId": 0,
45      "quoteId": "",
46      "distance": 0,
47      "subtotalValue": 300,
48      "shippingValue": 0,
49      "discountValue": 50,
50      "additionValue": 0,
51      "totalValue": 250,
52      "service": false,
53      "storage": null,
54      "items": [
55        {
56          "itemId": 0,
57          "productCategoryId": 0,
58          "upsellId": null,
59          "productPairOfferId": null,
60          "productPriceRuleId": 0,
61          "productPriceRuleName": "Original",
62          "quantity": 1,
63          "code": null,
64          "unitValue": 300,
65          "unitAdditionValue": 0,
66          "unitDiscountValue": 50,
67          "subtotalValue": 300,
68          "subtotalAdditionValue": 0,
69          "subtotalDiscountValue": 50,
70          "totalValue": 250,
71          "product": {
72            "productId": 1,
73            "brandId": 0,
74            "brandName": "",
75            "mainCategoryId": 0,
76            "mainCategoryName": "",
77            "type": "product",
78            "sku": "SKU12321",
79            "name": "Produto tecnológico",
80            "active": true,
81            "url": "tech-brand-product-plus.html",
82            "comparisonPrice": 400,
83            "stock": 20,
84            "medias": [],
85            "combination": [],
86            "currentAttributes": []
87          },
88          "discounts": [
89            {
90              "cartOrderDiscountId": 1,
91              "cartOrderAdditionId": 0,
92              "value": 50,
93              "detail": {
94                "entity": {
95                  "entity": "coupon",
96                  "identifier": "#cupom",
97                  "description": "Cupom 50",
98                  "type": "value",
99                  "target": "subtotal-shipping",
100                  "error": null
101                },
102                "target": "subtotal",
103                "value": 50
104              }
105            }
106          ],
107          "additions": []
108        }
109      ],
110      "additions": [],
111      "discounts": [
112        {
113          "discountId": 1,
114          "discountType": "coupon",
115          "discountValue": 50,
116          "discountMainCode": "#cupom",
117          "discountTitle": "Cupom 50"
118        }
119      ],
120      "shippingOptions": []
121    }
122  ],
123  "errors": [],
124  "isMerged": false,
125  "createdAt": "2026-01-28 19:32:58",
126  "updatedAt": "2026-01-28 19:39:46"
127}

⚠️ 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.

⚠️ Principais erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED401O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED409O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND404O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH500Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED502A tentativa de cotação para o grupo de cotação falhou.
UAPPI_STORE_CART_CUSTOMER_IS_REQUIRED401O cliente é requerido.
UAPPI_STORE_CART_EMPTY400O carrinho está vazio e a operação não pode continuar.

⚠️ Erros de promocionais:

Código InternoCódigo HttpDescrição
UAPPI_STORE_APPLY_PROMOTIONAL_NO_ITEMS400A promoção solicitada não pode ser aplicada porque não havia itens elegíveis para o desconto.
UAPPI_STORE_APPLY_PROMOTIONAL_NOT_FOUND404A promoção solicitada não pode ser aplicada, pois não foi encontrada.
UAPPI_STORE_APPLY_PROMOTIONAL_BLOCKED400A promoção solicitada não pode ser aplicada, pois foi bloqueada por outra promoção.
UAPPI_STORE_APPLY_PROMOTIONAL_DISABLED400A promoção solicitada não pode ser aplicada, pois não está ativa.
UAPPI_STORE_APPLY_PROMOTIONAL_OUT_OF_SCHEDULE400A promoção solicitada não pode ser aplicada, pois está fora do período de vigência.
UAPPI_STORE_APPLY_PROMOTIONAL_MAX_USE400A promoção solicitada não pode ser aplicada, pois atingiu o limite máximo de utilização.
UAPPI_STORE_APPLY_PROMOTIONAL_ORDER_QUANTITY400A promoção solicitada não pode ser aplicada, pois o cliente não atende aos requisitos de quantidade do pedido.
UAPPI_STORE_APPLY_PROMOTIONAL_DISCOUNT_UNAVAILABLE400A promoção não pode ser aplicada, pois não há desconto disponível.
UAPPI_STORE_APPLY_PROMOTIONAL_MISSING_TRADE_POLICY400A promoção solicitada não inclui o link para a política comercial.
UAPPI_STORE_APPLY_PROMOTIONAL_REQUIRED_CUSTOMER400A promoção solicitada não pode ser aplicada, pois requer um cliente.

Remoção de Cupom do Carrinho

DELETE /cart/promotionals/coupon

Remove o cupom aplicado em um carrinho

Descrição

Endpoint responsável por permitir que o cliente remova o cupom aplicado ao carrinho sempre que desejar 🧾.

Essa ação restaura os valores originais do carrinho, garantindo flexibilidade para que o cliente possa alterar ou reconsiderar a utilização de descontos antes da finalização do pedido.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/cart/promotionals/coupon \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "abc12332124623462",
3  "countryCode": "",
4  "quoteZipcode": "",
5  "subtotalValue": 300,
6  "shippingValue": 0,
7  "discountValue": 0,
8  "additionValue": 0,
9  "totalValue": 300,
10  "discountPreview": {
11    "cashDiscount": {
12      "discountPercentage": 0,
13      "discountValue": 0,
14      "valueWithDiscount": 300
15    },
16    "pointSystem": null
17  },
18  "installments": [],
19  "requestedProductMap": [
20    {
21      "productId": 1,
22      "quantity": 1,
23      "code": null,
24      "upsellId": null,
25      "productPairOfferId": null
26    }
27  ],
28  "discountMap": {
29    "promotion": [],
30    "coupon": null,
31    "customer-wallet": null,
32    "point-system": null
33  },
34  "customer": null,
35  "addresses": [],
36  "orders": [
37    {
38      "orderId": 0,
39      "quoteId": "",
40      "distance": 0,
41      "subtotalValue": 300,
42      "shippingValue": 0,
43      "discountValue": 0,
44      "additionValue": 0,
45      "totalValue": 300,
46      "service": false,
47      "storage": null,
48      "items": [
49        {
50          "itemId": 0,
51          "productCategoryId": 0,
52          "upsellId": null,
53          "productPairOfferId": null,
54          "productPriceRuleId": 0,
55          "productPriceRuleName": "Original",
56          "quantity": 1,
57          "code": null,
58          "unitValue": 300,
59          "unitAdditionValue": 0,
60          "unitDiscountValue": 0,
61          "subtotalValue": 300,
62          "subtotalAdditionValue": 0,
63          "subtotalDiscountValue": 0,
64          "totalValue": 300,
65          "product": {
66            "productId": 1,
67            "brandId": 0,
68            "brandName": "",
69            "mainCategoryId": 0,
70            "mainCategoryName": "",
71            "type": "product",
72            "sku": "SKU12321",
73            "name": "Produto tecnológico",
74            "active": true,
75            "url": "tech-brand-product-plus.html",
76            "comparisonPrice": 400,
77            "stock": 20,
78            "medias": [],
79            "combination": [],
80            "currentAttributes": []
81          },
82          "discounts": [],
83          "additions": []
84        }
85      ],
86      "additions": [],
87      "discounts": [],
88      "shippingOptions": []
89    }
90  ],
91  "errors": [],
92  "isMerged": false,
93  "createdAt": "2026-01-28 19:32:58",
94  "updatedAt": "2026-01-28 19:39:46"
95}

⚠️ 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 InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED401O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED409O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND404O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH500Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED502A tentativa de cotação para o grupo de cotação falhou.
UAPPI_STORE_CART_CUSTOMER_IS_REQUIRED401O cliente é requerido.
UAPPI_STORE_CART_EMPTY400O carrinho está vazio e a operação não pode continuar.

Aplicar saldo da carteira no carrinho

POST /cart/promotionals/customer-wallet

Permite o cliente aplicar o saldo da carteira no carrinho

Descrição

Endpoint responsável por permitir que o cliente aplique o saldo disponível na carteira ao carrinho, utilizando-o para realizar o pagamento da compra 💼.

A aplicação do saldo ocorre apenas quando o cliente está autenticado, possui saldo disponível na conta e há itens presentes no carrinho, garantindo a validade da operação dentro do fluxo de compra.

Como regra de segurança e validação, a autenticação do cliente é identificada pelo token do próprio carrinho, não sendo necessário um mecanismo adicional de login nesse fluxo.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/cart/promotionals/customer-wallet \
3  --cookie "cartToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"id": "abc12345678907865432",
5		"countryCode": "",
6		"quoteZipcode": "",
7		"subtotalValue": 300,
8		"shippingValue": 0,
9		"discountValue": 300,
10		"additionValue": 0,
11		"totalValue": 0,
12		"discountPreview": {
13			"cashDiscount": {
14				"discountPercentage": 0,
15				"discountValue": 0,
16				"valueWithDiscount": 0
17			},
18			"pointSystem": {
19				"name": "System Point",
20				"pointValue": 0.01,
21				"originalAmount": 3.79,
22				"finalAmount": 3.79,
23				"finalValue": 0.0300
24			}
25		},
26		"installments": [],
27		"requestedProductMap": [
28			{
29				"productId": 1,
30				"quantity": 1,
31				"code": null,
32				"upsellId": null,
33				"productPairOfferId": null
34			}
35		],
36		"discountMap": {
37			"promotion": [],
38			"coupon": null,
39			"customer-wallet": {
40				"discountId": 1,
41				"discountType": "customer-wallet",
42				"discountValue": 300,
43				"discountMainCode": "customer-wallet",
44				"discountTitle": "Customer Wallet"
45			},
46			"point-system": null
47		},
48		"customer": {
49			"customerId": 1,
50			"nameCorporateName": "Eric",
51			"tradeName": "",
52			"email": "customer.test@uappi.com.br",
53			"document": "",
54			"gender": "male",
55			"isCorporate": false,
56			"nationality": "BRA",
57			"birthdate": "2000-01-01",
58			"phone": "+12345678912"
59		},
60		"addresses": [
61			{
62				"addressId": 1,
63				"type": "both",
64				"zipCode": "12345678",
65				"identification": "casa",
66				"street": "Rua das flores",
67				"number": "1000",
68				"city": "Birigui",
69				"complement": "Casa",
70				"district": "Bairro floral",
71				"state": "São Paulo",
72				"stateCode": "BR-SP",
73				"countryCode": "BRA",
74				"recipient": "Eric"
75			}
76		],
77		"orders": [
78			{
79				"orderId": 0,
80				"quoteId": "",
81				"distance": 0,
82				"subtotalValue": 300,
83				"shippingValue": 0,
84				"discountValue": 300,
85				"additionValue": 0,
86				"totalValue": 0,
87				"service": false,
88				"storage": null,
89				"items": [
90					{
91						"itemId": 0,
92						"productCategoryId": 0,
93						"upsellId": null,
94						"productPairOfferId": null,
95						"productPriceRuleId": 0,
96						"productPriceRuleName": "Original",
97						"quantity": 1,
98						"code": null,
99						"unitValue": 300,
100						"unitAdditionValue": 0,
101						"unitDiscountValue": 300,
102						"subtotalValue": 300,
103						"subtotalAdditionValue": 0,
104						"subtotalDiscountValue": 300,
105						"totalValue": 0,
106						"product": {
107							"productId": 1,
108							"brandId": 0,
109							"brandName": "",
110							"mainCategoryId": 0,
111							"mainCategoryName": "",
112							"type": "product",
113							"sku": "SKU123321",
114							"name": "Produto tecnológico",
115							"active": true,
116							"url": "tech-brand-product.html",
117							"comparisonPrice": 499,
118							"stock": 20,
119							"medias": [],
120							"combination": [],
121							"currentAttributes": []
122						},
123						"discounts": [
124							{
125								"cartOrderDiscountId": 1,
126								"cartOrderAdditionId": 0,
127								"value": 300,
128								"detail": {
129									"entity": {
130										"entity": "customer-wallet",
131										"identifier": "customer-wallet",
132										"description": "Customer Wallet",
133										"type": "value",
134										"target": "subtotal-shipping",
135										"error": null
136									},
137									"target": "subtotal",
138									"value": 300
139								}
140							}
141						],
142						"additions": []
143					}
144				],
145				"additions": [],
146				"discounts": [
147					{
148						"discountId": 1,
149						"discountType": "customer-wallet",
150						"discountValue": 300,
151						"discountMainCode": "customer-wallet",
152						"discountTitle": "Customer Wallet"
153					}
154				],
155				"shippingOptions": []
156			}
157		],
158		"errors": [],
159		"isMerged": false,
160		"createdAt": "2026-01-29 20:14:59",
161		"updatedAt": "2026-01-30 11:30:53"
162	}
163}

⚠️ 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.

⚠️ Principais erros

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED401O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED409O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND404O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH500Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED502A tentativa de cotação para o grupo de cotação falhou.
UAPPI_STORE_CART_CUSTOMER_IS_REQUIRED401O cliente é requerido.
UAPPI_STORE_CART_EMPTY400O carrinho está vazio e a operação não pode continuar.

⚠️ Erros de promocionais:

Código InternoCódigo HttpDescrição
UAPPI_STORE_APPLY_PROMOTIONAL_NO_ITEMS400A promoção solicitada não pode ser aplicada porque não havia itens elegíveis para o desconto.
UAPPI_STORE_APPLY_PROMOTIONAL_NOT_FOUND404A promoção solicitada não pode ser aplicada, pois não foi encontrada.
UAPPI_STORE_APPLY_PROMOTIONAL_BLOCKED400A promoção solicitada não pode ser aplicada, pois foi bloqueada por outra promoção.
UAPPI_STORE_APPLY_PROMOTIONAL_DISABLED400A promoção solicitada não pode ser aplicada, pois não está ativa.
UAPPI_STORE_APPLY_PROMOTIONAL_OUT_OF_SCHEDULE400A promoção solicitada não pode ser aplicada, pois está fora do período de vigência.
UAPPI_STORE_APPLY_PROMOTIONAL_MAX_USE400A promoção solicitada não pode ser aplicada, pois atingiu o limite máximo de utilização.
UAPPI_STORE_APPLY_PROMOTIONAL_ORDER_QUANTITY400A promoção solicitada não pode ser aplicada, pois o cliente não atende aos requisitos de quantidade do pedido.
UAPPI_STORE_APPLY_PROMOTIONAL_DISCOUNT_UNAVAILABLE400A promoção não pode ser aplicada, pois não há desconto disponível.
UAPPI_STORE_APPLY_PROMOTIONAL_MISSING_TRADE_POLICY400A promoção solicitada não inclui o link para a política comercial.
UAPPI_STORE_APPLY_PROMOTIONAL_REQUIRED_CUSTOMER400A promoção solicitada não pode ser aplicada, pois requer um cliente.

Remove saldo da carteira no carrinho

DELETE /cart/promotionals/customer-wallet

Permite o cliente remova o saldo da carteira aplicado em um carrinho

Descrição

Endpoint responsável por permitir que o cliente remova do carrinho o saldo da carteira aplicado anteriormente, realizando o estorno do valor para a própria carteira 💼.

A remoção é permitida apenas quando o cliente está autenticado e existe saldo aplicado no carrinho atual, assegurando a consistência financeira da operação antes da finalização do pedido.

Como regra de segurança e validação, a autenticação do cliente é identificada pelo token do próprio carrinho, não sendo necessário um mecanismo adicional de login nesse fluxo.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/cart/promotionals/customer-wallet \
3  --cookie "cartToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "abc1234235708967543",
3  "countryCode": "",
4  "quoteZipcode": "",
5  "subtotalValue": 300,
6  "shippingValue": 0,
7  "discountValue": 0,
8  "additionValue": 0,
9  "totalValue": 300,
10  "discountPreview": {
11    "cashDiscount": {
12      "discountPercentage": 0,
13      "discountValue": 0,
14      "valueWithDiscount": 300
15    },
16    "pointSystem": {
17      "name": "System Point",
18      "pointValue": 0.01,
19      "originalAmount": 3.79,
20      "finalAmount": 3.79,
21      "finalValue": 0.0300
22    }
23  },
24  "installments": [],
25  "requestedProductMap": [
26    {
27      "productId": 1,
28      "quantity": 1,
29      "code": null,
30      "upsellId": null,
31      "productPairOfferId": null
32    }
33  ],
34  "discountMap": {
35    "promotion": [],
36    "coupon": null,
37    "customer-wallet": null,
38    "point-system": null
39  },
40  "customer": {
41    "customerId": 1,
42    "nameCorporateName": "Eric",
43    "tradeName": "",
44    "email": "customer.test@uappi.com.br",
45    "document": "",
46    "gender": "male",
47    "isCorporate": false,
48    "nationality": "BRA",
49    "birthdate": "2000-01-01",
50    "phone": "+12345678912"
51  },
52  "addresses": [
53    {
54      "addressId": 1,
55      "type": "both",
56      "zipCode": "12345678",
57      "identification": "casa",
58      "street": "Rua das flores",
59      "number": "1000",
60      "city": "Birigui",
61      "complement": "Casa",
62      "district": "Bairro floral",
63      "state": "São Paulo",
64      "stateCode": "BR-SP",
65      "countryCode": "BRA",
66      "recipient": "Eric"
67    }
68  ],
69  "orders": [
70    {
71      "orderId": 0,
72      "quoteId": "",
73      "distance": 0,
74      "subtotalValue": 300,
75      "shippingValue": 0,
76      "discountValue": 0,
77      "additionValue": 0,
78      "totalValue": 300,
79      "service": false,
80      "storage": null,
81      "items": [
82        {
83          "itemId": 0,
84          "productCategoryId": 0,
85          "upsellId": null,
86          "productPairOfferId": null,
87          "productPriceRuleId": 0,
88          "productPriceRuleName": "Original",
89          "quantity": 1,
90          "code": null,
91          "unitValue": 300,
92          "unitAdditionValue": 0,
93          "unitDiscountValue": 0,
94          "subtotalValue": 300,
95          "subtotalAdditionValue": 0,
96          "subtotalDiscountValue": 0,
97          "totalValue": 300,
98          "product": {
99            "productId": 1,
100            "brandId": 0,
101            "brandName": "",
102            "mainCategoryId": 0,
103            "mainCategoryName": "",
104            "type": "product",
105            "sku": "SKU123321",
106            "name": "Produto Tecnológico",
107            "active": true,
108            "url": "tech-brand-product.html",
109            "comparisonPrice": 499,
110            "stock": 20,
111            "medias": [],
112            "combination": [],
113            "currentAttributes": []
114          },
115          "discounts": [],
116          "additions": []
117        }
118      ],
119      "additions": [],
120      "discounts": [],
121      "shippingOptions": []
122    }
123  ],
124  "errors": [],
125  "isMerged": false,
126  "createdAt": "2026-01-29 20:14:59",
127  "updatedAt": "2026-01-30 11:30:31"
128}

⚠️ 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 InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED401O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED409O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND404O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH500Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED502A tentativa de cotação para o grupo de cotação falhou.
UAPPI_STORE_CART_CUSTOMER_IS_REQUIRED401O cliente é requerido.
UAPPI_STORE_CART_EMPTY400O carrinho está vazio e a operação não pode continuar.

Aplicar saldo do sistema de pontos no carrinho

POST /cart/promotionals/point-system

Permite o cliente aplicar o saldo do sistema de pontos no carrinho

Descrição

Endpoint responsável por permitir que o cliente aplique o saldo disponível do sistema de pontos no carrinho, utilizando-o como forma de pagamento da compra 🎯.

A aplicação dos pontos ocorre apenas quando o cliente está autenticado no contexto do carrinho, possui saldo disponível e há itens adicionados ao carrinho.

Como regra de segurança e validação, a autenticação do cliente é identificada pelo token do próprio carrinho, não sendo necessário um mecanismo adicional de login nesse fluxo.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/cart/promotionals/point-system \
3  --cookie "cartToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "abc12344634723474584562",
3  "countryCode": "",
4  "quoteZipcode": "",
5  "subtotalValue": 300,
6  "shippingValue": 0,
7  "discountValue": 300,
8  "additionValue": 0,
9  "totalValue": 0,
10  "discountPreview": {
11    "cashDiscount": {
12      "discountPercentage": 0,
13      "discountValue": 0,
14      "valueWithDiscount": 0
15    },
16    "pointSystem": null
17  },
18  "installments": [],
19  "requestedProductMap": [
20    {
21      "productId": 1,
22      "quantity": 1,
23      "code": null,
24      "upsellId": null,
25      "productPairOfferId": null
26    }
27  ],
28  "discountMap": {
29    "promotion": [],
30    "coupon": null,
31    "customer-wallet": null,
32    "point-system": {
33      "discountId": 1,
34      "discountType": "point-system",
35      "discountValue": 50,
36      "discountMainCode": "point-system",
37      "discountTitle": "Point System - System Point"
38    }
39  },
40  "customer": {
41    "customerId": 1,
42    "nameCorporateName": "Eric",
43    "tradeName": "",
44    "email": "customer.test@uappi.com.br",
45    "document": "",
46    "gender": "male",
47    "isCorporate": false,
48    "nationality": "BRA",
49    "birthdate": "2000-01-01",
50    "phone": "+12345678912"
51  },
52  "addresses": [],
53  "orders": [
54    {
55      "orderId": 0,
56      "quoteId": "",
57      "distance": 0,
58      "subtotalValue": 300,
59      "shippingValue": 0,
60      "discountValue": 300,
61      "additionValue": 0,
62      "totalValue": 0,
63      "service": false,
64      "storage": null,
65      "items": [
66        {
67          "itemId": 0,
68          "productCategoryId": 0,
69          "upsellId": null,
70          "productPairOfferId": null,
71          "productPriceRuleId": 0,
72          "productPriceRuleName": "Original",
73          "quantity": 1,
74          "code": null,
75          "unitValue": 300,
76          "unitAdditionValue": 0,
77          "unitDiscountValue": 300,
78          "subtotalValue": 300,
79          "subtotalAdditionValue": 0,
80          "subtotalDiscountValue": 300,
81          "totalValue": 0,
82          "product": {
83            "productId": 1,
84            "brandId": 0,
85            "brandName": "",
86            "mainCategoryId": 0,
87            "mainCategoryName": "",
88            "type": "product",
89            "sku": "SKU123321",
90            "name": "Produto Tecnológico",
91            "active": true,
92            "url": "tech-brand-product.html",
93            "comparisonPrice": 499,
94            "stock": 20,
95            "medias": [],
96            "combination": [],
97            "currentAttributes": []
98          },
99          "discounts": [
100            {
101              "cartOrderDiscountId": 1,
102              "cartOrderAdditionId": 0,
103              "value": 50,
104              "detail": {
105                "entity": {
106                  "entity": "point-system",
107                  "identifier": "point-system",
108                  "description": "Point System - System Point",
109                  "type": "value",
110                  "target": "subtotal-shipping",
111                  "error": null
112                },
113                "target": "subtotal",
114                "value": 50
115              }
116            }
117          ],
118          "additions": []
119        }
120      ],
121      "additions": [],
122      "discounts": [
123        {
124          "discountId": 1,
125          "discountType": "point-system",
126          "discountValue": 50,
127          "discountMainCode": "point-system",
128          "discountTitle": "Point System - System Point"
129        }
130      ],
131      "shippingOptions": []
132    }
133  ],
134  "errors": [],
135  "isMerged": false,
136  "createdAt": "2026-01-29 20:14:59",
137  "updatedAt": "2026-01-30 11:30:53"
138}

⚠️ 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.

⚠️ Principais erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED401O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED409O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND404O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH500Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED502A tentativa de cotação para o grupo de cotação falhou.
UAPPI_STORE_CART_CUSTOMER_IS_REQUIRED401O cliente é requerido.
UAPPI_STORE_CART_EMPTY400O carrinho está vazio e a operação não pode continuar.

⚠️ Erros de promocionais:

Código InternoCódigo HttpDescrição
UAPPI_STORE_APPLY_PROMOTIONAL_NO_ITEMS400A promoção solicitada não pode ser aplicada porque não havia itens elegíveis para o desconto.
UAPPI_STORE_APPLY_PROMOTIONAL_NOT_FOUND404A promoção solicitada não pode ser aplicada, pois não foi encontrada.
UAPPI_STORE_APPLY_PROMOTIONAL_BLOCKED400A promoção solicitada não pode ser aplicada, pois foi bloqueada por outra promoção.
UAPPI_STORE_APPLY_PROMOTIONAL_DISABLED400A promoção solicitada não pode ser aplicada, pois não está ativa.
UAPPI_STORE_APPLY_PROMOTIONAL_OUT_OF_SCHEDULE400A promoção solicitada não pode ser aplicada, pois está fora do período de vigência.
UAPPI_STORE_APPLY_PROMOTIONAL_MAX_USE400A promoção solicitada não pode ser aplicada, pois atingiu o limite máximo de utilização.
UAPPI_STORE_APPLY_PROMOTIONAL_ORDER_QUANTITY400A promoção solicitada não pode ser aplicada, pois o cliente não atende aos requisitos de quantidade do pedido.
UAPPI_STORE_APPLY_PROMOTIONAL_DISCOUNT_UNAVAILABLE400A promoção não pode ser aplicada, pois não há desconto disponível.
UAPPI_STORE_APPLY_PROMOTIONAL_MISSING_TRADE_POLICY400A promoção solicitada não inclui o link para a política comercial.
UAPPI_STORE_APPLY_PROMOTIONAL_REQUIRED_CUSTOMER400A promoção solicitada não pode ser aplicada, pois requer um cliente.

Remove saldo da carteira no carrinho

DELETE /cart/promotionals/point-system

Permite o cliente remova o saldo do sistema de pontos aplicado em um carrinho

Descrição

Endpoint responsável por permitir que o cliente remova do carrinho o saldo do sistema de pontos aplicado anteriormente, realizando o estorno dos pontos utilizados 🔄.

A remoção só é permitida quando o cliente está autenticado no contexto do carrinho e existe saldo de pontos aplicado no carrinho atual.

Como observado nesse fluxo, a autenticação do cliente é identificada pelo token do próprio carrinho, garantindo a validação da operação sem a necessidade de autenticação adicional.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/cart/promotionals/point-system \
3  --cookie "cartToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2		"id": "abc1234235708967543",
3		"countryCode": "",
4		"quoteZipcode": "",
5		"subtotalValue": 300,
6		"shippingValue": 0,
7		"discountValue": 0,
8		"additionValue": 0,
9		"totalValue": 300,
10		"discountPreview": {
11			"cashDiscount": {
12				"discountPercentage": 0,
13				"discountValue": 0,
14				"valueWithDiscount": 300
15			},
16			"pointSystem": {
17				"name": "System Point",
18				"pointValue": 0.01,
19				"originalAmount": 3.79,
20				"finalAmount": 3.79,
21				"finalValue": 0.0300
22			}
23		},
24		"installments": [],
25		"requestedProductMap": [
26			{
27				"productId": 1,
28				"quantity": 1,
29				"code": null,
30				"upsellId": null,
31				"productPairOfferId": null
32			}
33		],
34		"discountMap": {
35			"promotion": [],
36			"coupon": null,
37			"customer-wallet": null,
38			"point-system": null
39		},
40		"customer": {
41			"customerId": 1,
42			"nameCorporateName": "Eric",
43			"tradeName": "",
44			"email": "customer.test@uappi.com.br",
45			"document": "",
46			"gender": "male",
47			"isCorporate": false,
48			"nationality": "BRA",
49			"birthdate": "2000-01-01",
50			"phone": "+12345678912"
51		},
52		"addresses": [
53			{
54				"addressId": 1,
55				"type": "both",
56				"zipCode": "12345678",
57				"identification": "casa",
58				"street": "Rua das flores",
59				"number": "1000",
60				"city": "Birigui",
61				"complement": "Casa",
62				"district": "Bairro floral",
63				"state": "São Paulo",
64				"stateCode": "BR-SP",
65				"countryCode": "BRA",
66				"recipient": "Eric"
67			}
68		],
69		"orders": [
70			{
71				"orderId": 0,
72				"quoteId": "",
73				"distance": 0,
74				"subtotalValue": 300,
75				"shippingValue": 0,
76				"discountValue": 0,
77				"additionValue": 0,
78				"totalValue": 300,
79				"service": false,
80				"storage": null,
81				"items": [
82					{
83						"itemId": 0,
84						"productCategoryId": 0,
85						"upsellId": null,
86						"productPairOfferId": null,
87						"productPriceRuleId": 0,
88						"productPriceRuleName": "Original",
89						"quantity": 1,
90						"code": null,
91						"unitValue": 300,
92						"unitAdditionValue": 0,
93						"unitDiscountValue": 0,
94						"subtotalValue": 300,
95						"subtotalAdditionValue": 0,
96						"subtotalDiscountValue": 0,
97						"totalValue": 300,
98						"product": {
99							"productId": 1,
100							"brandId": 0,
101							"brandName": "",
102							"mainCategoryId": 0,
103							"mainCategoryName": "",
104							"type": "product",
105							"sku": "SKU123321",
106							"name": "Produto Tecnológico",
107							"active": true,
108							"url": "tech-brand-product.html",
109							"comparisonPrice": 499,
110							"stock": 20,
111							"medias": [],
112							"combination": [],
113							"currentAttributes": []
114						},
115						"discounts": [],
116						"additions": []
117					}
118				],
119				"additions": [],
120				"discounts": [],
121				"shippingOptions": []
122			}
123		],
124		"errors": [],
125		"isMerged": false,
126		"createdAt": "2026-01-29 20:14:59",
127		"updatedAt": "2026-01-30 11:30:31"
128}

⚠️ 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 InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED401O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED409O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND404O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH500Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED502A tentativa de cotação para o grupo de cotação falhou.
UAPPI_STORE_CART_CUSTOMER_IS_REQUIRED401O cliente é requerido.
UAPPI_STORE_CART_EMPTY400O carrinho está vazio e a operação não pode continuar.

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;