Skip to content

Promoções Aplicáveis no Carrinho Interno

Visão Geral

O módulo de Promoções permite que o operador administrativo aplique benefícios e incentivos financeiros diretamente ao carrinho do cliente.

Esta funcionalidade garante paridade total com o checkout público, permitindo que negociações assistidas se beneficiem de campanhas de marketing, saldos de fidelidade e cupons de desconto.

Todas as operações desta família são concentradas sob o prefixo /carts/{cartId}/promotionals e atuam de forma síncrona, atualizando imediatamente o discountMap do carrinho.

---

Tipos de Benefícios

O sistema suporta três pilares promocionais principais: 1. Cupons de Desconto (coupon): Aplicação de códigos promocionais de campanhas específicas. 2. Carteira do Cliente (wallet): Uso de saldos de créditos, trocas ou estornos acumulados no perfil do comprador. 3. Programa de Pontos (point-system): Resgate de pontuação de fidelidade para abatimento no valor total da compra.

---

Regras de Acumulatividade

A aplicação de promoções segue as regras de concorrência definidas no motor de promoções da plataforma.

Algumas promoções podem ser mutuamente exclusivas (ex: um cupom que não permite uso conjunto com pontos).

O sistema validará estas condições em tempo real, retornando mensagens informativas caso um benefício bloqueie outro.

Entidades Envolvidas

  • Discount Map: Estrutura de dados que detalha a origem de cada desconto aplicado ao carrinho, facilitando a transparência para o operador e para o cliente final.
  • Coupon Hash: O identificador alfanumérico do cupom gerado pelo marketing.
  • Saldos Disponíveis: Valores em carteira ou pontos que são consultados diretamente no perfil do cliente vinculado antes da aplicação.

Notas e Considerações

Pré-requisito de Identificação

Para o uso de Carteira e Pontos, o carrinho deve obrigatoriamente possuir um cliente vinculado.

Tentativas de aplicar estes benefícios em carrinhos anônimos resultarão em erro, pois o sistema não terá contexto para debitar os saldos.

---

Invalidação em Mudanças de Carrinho

Promoções vinculadas a itens específicos (ex: "10% de desconto no produto X") serão automaticamente removidas ou recalculadas caso o item em questão seja excluído ou tenha sua quantidade alterada.

O operador deve estar atento aos totais do carrinho após realizar modificações na lista de produtos.

Aplicar Cupom no Carrinho (Admin)

PUT /carts/{cartId}/promotionals/coupon

Insere um código promocional (hash) no carrinho administrativo para abatimento de valores conforme as regras da campanha.

Descrição

Este endpoint permite a inserção de cupons de desconto no carrinho administrativo.

Ele funciona como um validador em tempo real: ao receber o hash (código do cupom), o sistema verifica a vigência da campanha, o limite de usos, as condições de valor mínimo e a compatibilidade com os itens já presentes no carrinho.

Se o cupom for válido, o desconto será aplicado imediatamente e detalhado no objeto discountMap.coupon da resposta.

Esta ação é fundamental para que o operador administrativo replique benefícios prometidos em campanhas de marketing ou ofereça descontos de contingência autorizados.

---

Comportamento de Substituição

A aplicação de cupom via PUT é idempotente no sentido de substituição:

se o carrinho já possuir um cupom aplicado, o novo hash substituirá o anterior (respeitando as regras de acumulatividade do motor de promoções).

Caso o operador deseje apenas remover o benefício sem inserir um novo, deve utilizar o método DELETE.

---

Impacto no Recálculo

A inclusão de um cupom dispara um recálculo total do carrinho. Valores de frete e parcelamentos podem ser alterados caso o desconto reduza o valor final abaixo de determinadas faixas de benefícios ou condições de pagamento.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo CART_WRITE.
Content-Typeapplication/jsonTipo de conteúdo da requisição.

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimToken identificador único do carrinho administrativo.

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
hashstringSimCódigo alfanumérico do cupom (ex: VERAO2026).

Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/carts/CART123/promotionals/coupon' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "hash": "MEU-CUPOM"
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
3  "currencyId": "BRL",
4  "countryCode": "BRA",
5  "quoteZipcode": "12123-123",
6  "subtotalValue": 259.9,
7  "shippingValue": 18.4,
8  "discountValue": 15,
9  "additionValue": 0,
10  "totalValue": 263.3,
11  "discountPreview": {
12    "cashDiscount": {
13      "discountPercentage": 5,
14      "discountValue": 13.17,
15      "valueWithDiscount": 250.13
16    },
17    "pointSystem": {
18      "name": "Programa Fidelidade Uappi",
19      "pointValue": 0.01,
20      "originalAmount": 2633,
21      "finalAmount": 2501,
22      "finalValue": 25.01
23    }
24  },
25  "installments": [],
26  "requestedProductMap": [
27    {
28      "productId": 1,
29      "quantity": 2,
30      "code": "PROMO-ADMIN",
31      "upsellId": null,
32      "productPairOfferId": null
33    },
34    {
35      "productId": 25,
36      "quantity": 1,
37      "code": null,
38      "upsellId": 7,
39      "productPairOfferId": 18
40    }
41  ],
42  "discountMap": {
43    "promotion": [],
44    "coupon": {
45      "discountId": 9002,
46      "discountType": "coupon",
47      "discountValue": 5,
48      "discountMainCode": "BEMVINDO5",
49      "discountTitle": "Cupom de boas-vindas"
50    },
51    "customer-wallet": null,
52    "point-system": null
53  },
54  "customer": {
55    "customerId": 345,
56    "nameCorporateName": "Mariana Souza",
57    "tradeName": "",
58    "email": "mariana.souza@cliente.com",
59    "document": "12345678909",
60    "gender": "female",
61    "isCorporate": false,
62    "nationality": "BRA",
63    "birthdate": "1992-08-14",
64    "phone": "+5511998765432"
65  },
66  "addresses": [
67    {
68      "addressId": 31,
69      "type": "delivery",
70      "zipCode": "12123-123",
71      "identification": "Casa",
72      "street": "Rua das Flores",
73      "number": "120",
74      "city": "São José dos Campos",
75      "complement": "Apto 22",
76      "district": "Jardim Primavera",
77      "state": "São Paulo",
78      "stateCode": "SP",
79      "countryCode": "BRA",
80      "recipient": "Mariana Souza",
81      "createdAt": "2026-05-05 10:10:00",
82      "updatedAt": "2026-05-05 10:12:00"
83    }
84  ],
85  "orders": [
86    {
87      "orderId": 1,
88      "quoteId": "quote-01",
89      "distance": 12,
90      "subtotalValue": 259.9,
91      "shippingValue": 18.4,
92      "discountValue": 15,
93      "additionValue": 0,
94      "totalValue": 263.3,
95      "service": false,
96      "storage": {
97        "id": 11,
98        "code": "CD-SP-01",
99        "corporateName": "Centro de Distribuição SP LTDA",
100        "email": "logistica.sp@uappi.com.br",
101        "phone": "+551133334444",
102        "tradeName": "CD São Paulo",
103        "stateCode": "SP",
104        "countryCode": "BRA",
105        "document": "12345678000199",
106        "zipCode": "01000-000",
107        "city": "São Paulo",
108        "address": "Avenida Logística",
109        "district": "Centro",
110        "number": "1000",
111        "complement": "Galpão B",
112        "latitude": "-23.55052",
113        "longitude": "-46.63331",
114        "active": true,
115        "observation": "Janela de coleta até 16h",
116        "tradePolicyExceptions": [
117          5,
118          7
119        ]
120      },
121      "items": [
122        {
123          "itemId": 1,
124          "productCategoryIds": [
125            15,
126            18
127          ],
128          "upsellId": null,
129          "productPairOfferId": null,
130          "productPriceRuleId": 3,
131          "productPriceRuleName": "Preço Atacado",
132          "quantity": 2,
133          "code": "PROMO-ADMIN",
134          "unitValue": 129.95,
135          "unitAdditionValue": 0,
136          "unitDiscountValue": 7.5,
137          "subtotalValue": 259.9,
138          "subtotalAdditionValue": 0,
139          "subtotalDiscountValue": 15,
140          "totalValue": 244.9,
141          "product": {
142            "productId": 1,
143            "brandId": 9,
144            "brandName": "Marca Exemplo",
145            "mainCategoryId": 15,
146            "mainCategoryName": "Tênis",
147            "type": "simple",
148            "sku": "SKU-001",
149            "name": "Tênis Running Pro",
150            "active": true,
151            "url": "tenis-running-pro",
152            "comparisonPrice": 149.9,
153            "stock": 25,
154            "medias": [
155              {
156                "id": 88,
157                "type": "image",
158                "title": "Foto frontal",
159                "alternativeText": "Tênis Running Pro azul",
160                "file": "products/tenis-running-pro-frontal.webp",
161                "originalFile": "products/original/tenis-running-pro-frontal.jpg",
162                "size": 148230,
163                "originalSize": 423991,
164                "width": 1200,
165                "height": 1200,
166                "url": "https://cdn.uappi.com.br/products/tenis-running-pro-frontal.webp"
167              }
168            ],
169            "combination": [
170              301,
171              455
172            ],
173            "currentAttributes": [
174              {
175                "id": 12,
176                "name": "Cor",
177                "value": {
178                  "id": 455,
179                  "label": "Azul",
180                  "image": "attributes/color-blue.webp",
181                  "originalImage": "attributes/original/color-blue.png",
182                  "color": "#0033CC",
183                  "order": 2
184                }
185              },
186              {
187                "id": 13,
188                "name": "Tamanho",
189                "value": {
190                  "id": 301,
191                  "label": "42",
192                  "image": null,
193                  "originalImage": null,
194                  "color": null,
195                  "order": 4
196                }
197              }
198            ],
199            "restriction": {
200              "tradePolicyId": 1,
201              "requiredAge": 0
202            }
203          },
204          "discounts": [
205            {
206              "cartOrderDiscountId": 9001,
207              "cartOrderAdditionId": 0,
208              "value": 10,
209              "detail": {
210                "rule": "PROMO-10-CATEGORIA",
211                "scope": "item"
212              }
213            }
214          ],
215          "additions": [
216            {
217              "cartOrderDiscountId": 0,
218              "cartOrderAdditionId": 7001,
219              "value": 0,
220              "detail": {
221                "reason": "sem acrescimo aplicado"
222              }
223            }
224          ]
225        }
226      ],
227      "additions": [
228        {
229          "additionType": "custom-value-rule",
230          "additionValue": 0,
231          "additionTitle": "Ajuste manual interno"
232        }
233      ],
234      "discounts": [
235        {
236          "discountId": 9002,
237          "discountType": "coupon",
238          "discountValue": 5,
239          "discountMainCode": "BEMVINDO5",
240          "discountTitle": "Cupom de boas-vindas"
241        }
242      ],
243      "shippingOptions": [
244        {
245          "shippingTableId": 55,
246          "shippingPickupPointId": 0,
247          "label": "Entrega padrão",
248          "shippingValue": 18.4,
249          "beginShippingTime": 2,
250          "endShippingTime": 5,
251          "shippingTimeType": "days",
252          "selected": true,
253          "details": {
254            "shippingTableId": 55,
255            "integrationCode": "uappi",
256            "externalShippingCode": "STD-55",
257            "carrierId": 17,
258            "carrierName": "Transportadora XPTO",
259            "label": "Entrega padrão",
260            "value": 18.4,
261            "beginShippingTime": 2,
262            "endShippingTime": 5,
263            "trackingUrl": "https://tracking.transportadora.com/{code}",
264            "row": {
265              "id": 901,
266              "initialZipcode": "12000-000",
267              "finalZipcode": "12999-999",
268              "initialWeight": 0,
269              "finalWeight": 30,
270              "initialPrice": 0,
271              "finalPrice": 99999,
272              "beginShippingTime": 2,
273              "endShippingTime": 5,
274              "shippingValue": 18.4,
275              "variables": {
276                "kg_factor": 1.2,
277                "distance_factor": 0.8
278              }
279            },
280            "pickups": [
281              {
282                "id": 100,
283                "type": "internal",
284                "selected": false,
285                "name": "Loja Centro",
286                "address": "Rua Quinze de Novembro",
287                "number": "45",
288                "district": "Centro",
289                "city": "São José dos Campos",
290                "countryCode": "BRA",
291                "stateCode": "SP",
292                "zipCode": "12210-000",
293                "complement": "Retirar no balcão 2",
294                "latitude": "-23.1895",
295                "longitude": "-45.8841",
296                "openingHours": "Seg-Sex 09:00-18:00"
297              }
298            ],
299            "error": null
300          }
301        }
302      ]
303    }
304  ],
305  "errors": [
306    {
307      "identifier": 1,
308      "entity": "Payment",
309      "type": "warning",
310      "description": "Condição de pagamento indisponível para uma das parcelas.",
311      "error": "UAPPI_STORE_PAYMENT_CONDITION_UNAVAILABLE"
312    }
313  ],
314  "isMerged": false,
315  "createdAt": "2026-05-05 10:00:00",
316  "updatedAt": "2026-05-05 10:43:21"
317}

⚠️ Possíveis erros:

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

Código InternoCódigo HttpDescrição
UAPPI_STORE_APPLY_PROMOTIONAL_NOT_FOUND404O código de cupom informado não existe no sistema.
UAPPI_STORE_APPLY_PROMOTIONAL_BLOCKED400O cupom é válido, mas não pode ser usado em conjunto com as promoções já aplicadas.
UAPPI_STORE_APPLY_PROMOTIONAL_OUT_OF_SCHEDULE400A campanha vinculada ao cupom já expirou ou ainda não começou.
UAPPI_STORE_APPLY_PROMOTIONAL_MAX_USE400O limite global ou por cliente de usos deste cupom foi atingido.
UAPPI_STORE_CART_NOT_FOUND404O carrinho administrativo informado não foi encontrado.

Remover Cupom do Carrinho (Admin)

DELETE /carts/{cartId}/promotionals/coupon

Retira o cupom promocional atualmente aplicado ao carrinho administrativo.

Descrição

Este endpoint remove qualquer cupom de desconto que tenha sido aplicado anteriormente ao carrinho.

Ao realizar esta ação, o sistema anula o abatimento financeiro vinculado ao hash e retorna os totais do carrinho ao seu estado original (ou apenas com descontos automáticos de catálogo).

É a operação recomendada para limpar o estado promocional do carrinho caso o cliente decida trocar de cupom ou se as condições da negociação mudarem e o benefício não for mais aplicável.

---

Sincronização de Totais

A remoção do cupom dispara um novo ciclo de cálculo no domínio de Store. O operador deve observar o objeto totalValue na resposta para confirmar o novo saldo devedor do carrinho após a retirada do incentivo.

---

Autenticação

A remoção exige permissão de escrita (CART_WRITE). O sistema valida se o operador tem autoridade sobre o carrinho antes de processar a limpeza das regras promocionais.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo CART_WRITE.

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimToken identificador único do carrinho administrativo.

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
3  "currencyId": "BRL",
4  "countryCode": "BRA",
5  "quoteZipcode": "12123-123",
6  "subtotalValue": 259.9,
7  "shippingValue": 18.4,
8  "discountValue": 15,
9  "additionValue": 0,
10  "totalValue": 263.3,
11  "discountPreview": {
12    "cashDiscount": {
13      "discountPercentage": 5,
14      "discountValue": 13.17,
15      "valueWithDiscount": 250.13
16    },
17    "pointSystem": {
18      "name": "Programa Fidelidade Uappi",
19      "pointValue": 0.01,
20      "originalAmount": 2633,
21      "finalAmount": 2501,
22      "finalValue": 25.01
23    }
24  },
25  "installments": [],
26  "requestedProductMap": [
27    {
28      "productId": 1,
29      "quantity": 2,
30      "code": "PROMO-ADMIN",
31      "upsellId": null,
32      "productPairOfferId": null
33    },
34    {
35      "productId": 25,
36      "quantity": 1,
37      "code": null,
38      "upsellId": 7,
39      "productPairOfferId": 18
40    }
41  ],
42  "discountMap": {
43    "promotion": [],
44    "coupon": null,
45    "customer-wallet": null,
46    "point-system": null
47  },
48  "customer": {
49    "customerId": 345,
50    "nameCorporateName": "Mariana Souza",
51    "tradeName": "",
52    "email": "mariana.souza@cliente.com",
53    "document": "12345678909",
54    "gender": "female",
55    "isCorporate": false,
56    "nationality": "BRA",
57    "birthdate": "1992-08-14",
58    "phone": "+5511998765432"
59  },
60  "addresses": [
61    {
62      "addressId": 31,
63      "type": "delivery",
64      "zipCode": "12123-123",
65      "identification": "Casa",
66      "street": "Rua das Flores",
67      "number": "120",
68      "city": "São José dos Campos",
69      "complement": "Apto 22",
70      "district": "Jardim Primavera",
71      "state": "São Paulo",
72      "stateCode": "SP",
73      "countryCode": "BRA",
74      "recipient": "Mariana Souza",
75      "createdAt": "2026-05-05 10:10:00",
76      "updatedAt": "2026-05-05 10:12:00"
77    }
78  ],
79  "orders": [
80    {
81      "orderId": 1,
82      "quoteId": "quote-01",
83      "distance": 12,
84      "subtotalValue": 259.9,
85      "shippingValue": 18.4,
86      "discountValue": 15,
87      "additionValue": 0,
88      "totalValue": 263.3,
89      "service": false,
90      "storage": {
91        "id": 11,
92        "code": "CD-SP-01",
93        "corporateName": "Centro de Distribuição SP LTDA",
94        "email": "logistica.sp@uappi.com.br",
95        "phone": "+551133334444",
96        "tradeName": "CD São Paulo",
97        "stateCode": "SP",
98        "countryCode": "BRA",
99        "document": "12345678000199",
100        "zipCode": "01000-000",
101        "city": "São Paulo",
102        "address": "Avenida Logística",
103        "district": "Centro",
104        "number": "1000",
105        "complement": "Galpão B",
106        "latitude": "-23.55052",
107        "longitude": "-46.63331",
108        "active": true,
109        "observation": "Janela de coleta até 16h",
110        "tradePolicyExceptions": [
111          5,
112          7
113        ]
114      },
115      "items": [
116        {
117          "itemId": 1,
118          "productCategoryIds": [
119            15,
120            18
121          ],
122          "upsellId": null,
123          "productPairOfferId": null,
124          "productPriceRuleId": 3,
125          "productPriceRuleName": "Preço Atacado",
126          "quantity": 2,
127          "code": "PROMO-ADMIN",
128          "unitValue": 129.95,
129          "unitAdditionValue": 0,
130          "unitDiscountValue": 7.5,
131          "subtotalValue": 259.9,
132          "subtotalAdditionValue": 0,
133          "subtotalDiscountValue": 15,
134          "totalValue": 244.9,
135          "product": {
136            "productId": 1,
137            "brandId": 9,
138            "brandName": "Marca Exemplo",
139            "mainCategoryId": 15,
140            "mainCategoryName": "Tênis",
141            "type": "simple",
142            "sku": "SKU-001",
143            "name": "Tênis Running Pro",
144            "active": true,
145            "url": "tenis-running-pro",
146            "comparisonPrice": 149.9,
147            "stock": 25,
148            "medias": [
149              {
150                "id": 88,
151                "type": "image",
152                "title": "Foto frontal",
153                "alternativeText": "Tênis Running Pro azul",
154                "file": "products/tenis-running-pro-frontal.webp",
155                "originalFile": "products/original/tenis-running-pro-frontal.jpg",
156                "size": 148230,
157                "originalSize": 423991,
158                "width": 1200,
159                "height": 1200,
160                "url": "https://cdn.uappi.com.br/products/tenis-running-pro-frontal.webp"
161              }
162            ],
163            "combination": [
164              301,
165              455
166            ],
167            "currentAttributes": [
168              {
169                "id": 12,
170                "name": "Cor",
171                "value": {
172                  "id": 455,
173                  "label": "Azul",
174                  "image": "attributes/color-blue.webp",
175                  "originalImage": "attributes/original/color-blue.png",
176                  "color": "#0033CC",
177                  "order": 2
178                }
179              },
180              {
181                "id": 13,
182                "name": "Tamanho",
183                "value": {
184                  "id": 301,
185                  "label": "42",
186                  "image": null,
187                  "originalImage": null,
188                  "color": null,
189                  "order": 4
190                }
191              }
192            ],
193            "restriction": {
194              "tradePolicyId": 1,
195              "requiredAge": 0
196            }
197          },
198          "discounts": [
199            {
200              "cartOrderDiscountId": 9001,
201              "cartOrderAdditionId": 0,
202              "value": 10,
203              "detail": {
204                "rule": "PROMO-10-CATEGORIA",
205                "scope": "item"
206              }
207            }
208          ],
209          "additions": [
210            {
211              "cartOrderDiscountId": 0,
212              "cartOrderAdditionId": 7001,
213              "value": 0,
214              "detail": {
215                "reason": "sem acrescimo aplicado"
216              }
217            }
218          ]
219        }
220      ],
221      "additions": [
222        {
223          "additionType": "custom-value-rule",
224          "additionValue": 0,
225          "additionTitle": "Ajuste manual interno"
226        }
227      ],
228      "discounts": [],
229      "shippingOptions": [
230        {
231          "shippingTableId": 55,
232          "shippingPickupPointId": 0,
233          "label": "Entrega padrão",
234          "shippingValue": 18.4,
235          "beginShippingTime": 2,
236          "endShippingTime": 5,
237          "shippingTimeType": "days",
238          "selected": true,
239          "details": {
240            "shippingTableId": 55,
241            "integrationCode": "uappi",
242            "externalShippingCode": "STD-55",
243            "carrierId": 17,
244            "carrierName": "Transportadora XPTO",
245            "label": "Entrega padrão",
246            "value": 18.4,
247            "beginShippingTime": 2,
248            "endShippingTime": 5,
249            "trackingUrl": "https://tracking.transportadora.com/{code}",
250            "row": {
251              "id": 901,
252              "initialZipcode": "12000-000",
253              "finalZipcode": "12999-999",
254              "initialWeight": 0,
255              "finalWeight": 30,
256              "initialPrice": 0,
257              "finalPrice": 99999,
258              "beginShippingTime": 2,
259              "endShippingTime": 5,
260              "shippingValue": 18.4,
261              "variables": {
262                "kg_factor": 1.2,
263                "distance_factor": 0.8
264              }
265            },
266            "pickups": [
267              {
268                "id": 100,
269                "type": "internal",
270                "selected": false,
271                "name": "Loja Centro",
272                "address": "Rua Quinze de Novembro",
273                "number": "45",
274                "district": "Centro",
275                "city": "São José dos Campos",
276                "countryCode": "BRA",
277                "stateCode": "SP",
278                "zipCode": "12210-000",
279                "complement": "Retirar no balcão 2",
280                "latitude": "-23.1895",
281                "longitude": "-45.8841",
282                "openingHours": "Seg-Sex 09:00-18:00"
283              }
284            ],
285            "error": null
286          }
287        }
288      ]
289    }
290  ],
291  "errors": [
292    {
293      "identifier": 1,
294      "entity": "Payment",
295      "type": "warning",
296      "description": "Condição de pagamento indisponível para uma das parcelas.",
297      "error": "UAPPI_STORE_PAYMENT_CONDITION_UNAVAILABLE"
298    }
299  ],
300  "isMerged": false,
301  "createdAt": "2026-05-05 10:00:00",
302  "updatedAt": "2026-05-05 10:43:21"
303}

⚠️ Possíveis erros:

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

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho administrativo informado não foi encontrado.
UAPPI_STORE_CART_USER_MISMATCH403O operador não tem permissão para remover promoções deste carrinho.
UAPPI_STORE_CART_ORDER_EXISTS403O carrinho já gerou um pedido; o cupom utilizado no fechamento não pode ser removido.

Aplicar Carteira no Carrinho (Admin)

POST /carts/{cartId}/promotionals/customer-wallet

Utiliza o saldo de créditos ou cashback do perfil do cliente para abater o valor total do carrinho administrativo.

Descrição

Este endpoint permite o resgate de saldos acumulados na carteira virtual do cliente (Gift Cards, estornos em conta ou cashback) como forma de pagamento parcial ou total do carrinho administrativo.

Ao ser acionada, a API consulta o saldo disponível no perfil do titular vinculado e aplica o abatimento máximo permitido pelas regras da loja.

O benefício é refletido imediatamente no objeto discountMap.customer-wallet, permitindo que o operador administrativo informe ao cliente o novo saldo devedor.

Esta ação é fundamental para fidelização, permitindo que o atendimento assistido utilize créditos que o cliente já possui em sua conta.

---

Pré-requisito de Vínculo

O uso da carteira é estritamente vinculado à identidade do comprador.

Por isso, esta chamada exige que o carrinho já possua um cliente vinculado (customerId).

Caso o vínculo não exista, o sistema retornará um erro de pré-condição, uma vez que não haverá origem de saldo para o débito.

---

Cálculo e Prioridade

O valor debitado da carteira segue a lógica de "uso total disponível" até o limite do valor do carrinho.

Se o saldo em carteira for superior ao total da compra, o carrinho será zerado e o saldo remanescente permanecerá na conta do cliente para usos futuros.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo CART_WRITE.

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimToken identificador único do carrinho administrativo.

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/CART123/promotionals/customer-wallet' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ 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.

Código InternoCódigo HttpDescrição
UAPPI_STORE_APPLY_PROMOTIONAL_INSUFFICIENT_BALANCE400O cliente não possui saldo em carteira ou o saldo é insuficiente para as regras mínimas da loja.
UAPPI_STORE_CART_CUSTOMER_IS_REQUIRED401Você deve vincular um cliente ao carrinho antes de tentar usar o saldo de carteira.
UAPPI_STORE_APPLY_PROMOTIONAL_NO_ITEMS400Não existem itens no carrinho elegíveis para o uso de créditos de carteira.
UAPPI_STORE_CART_NOT_FOUND404O carrinho administrativo informado não foi encontrado.

Remover Carteira do Carrinho (Admin)

DELETE /carts/{cartId}/promotionals/customer-wallet

Retira o saldo de carteira aplicado como abatimento no carrinho administrativo.

Descrição

Este endpoint anula o uso de créditos da carteira virtual que foram aplicados anteriormente ao carrinho.

Ao realizar a remoção, o sistema "estorna" o saldo virtual para o perfil do cliente e atualiza os totais do carrinho para refletir o valor bruto original (recalculando frete e outros benefícios se necessário).

É o procedimento correto quando o cliente decide que não quer mais utilizar seus créditos nesta compra específica ou quando o operador precisa ajustar o carrinho para um método de pagamento incompatível com o uso de saldos de fidelidade.

---

Autenticação e Segurança

A operação exige o escopo de escrita CART_WRITE. O sistema garante que a remoção do saldo seja feita de forma atômica, assegurando que o cliente não perca seus créditos e que o carrinho permaneça consistente para o fechamento por outros meios.

---

Impacto no Fechamento

Após a remoção bem-sucedida, o objeto discountMap.customer-wallet retornará como null. O operador administrativo deve revalidar o valor total final com o cliente antes de prosseguir para a geração do pedido.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo CART_WRITE.

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimToken identificador único do carrinho administrativo.

Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/carts/CART123/promotionals/customer-wallet' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ 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.

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho administrativo informado não foi encontrado.
UAPPI_STORE_CART_USER_MISMATCH403O operador não possui permissão para gerenciar este carrinho.
UAPPI_STORE_CART_ORDER_EXISTS403O carrinho já gerou um pedido e seu snapshot financeiro não pode mais ser alterado.

Aplicar Pontos no Carrinho (Admin)

POST /carts/{cartId}/promotionals/point-system

Endpoint responsável por aplicar saldo de pontos no carrinho administrativo

Descrição

Este endpoint permite resgatar pontos acumulados de um programa de fidelidade e convertê-los em desconto no carrinho, quando essa funcionalidade estiver habilitada na loja.

Na prática, ele utiliza o saldo disponível do cliente para aplicar um abatimento no valor total, respeitando as regras de conversão definidas — como proporção de pontos, limites e elegibilidade 🎯

Para que a operação seja válida, é necessário que o carrinho esteja vinculado a um cliente com saldo suficiente e elegível no programa de fidelidade.

Após uma chamada bem-sucedida, o sistema atualiza os valores do carrinho, refletindo o desconto aplicado e considerando esse benefício nas etapas seguintes do checkout.

Esse recurso exige a permissão CART_WRITE.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada.

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimIdentificador do carrinho

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/CART123/promotionals/point-system' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "CART123",
3  "countryCode": "BRA",
4  "quoteZipcode": "01310100",
5  "subtotalValue": 100,
6  "shippingValue": 15,
7  "discountValue": 20,
8  "additionValue": 0,
9  "discountPreview": {
10    "cashDiscount": null,
11    "pointSystem": {
12      "name": "Pontos Uappi",
13      "pointValue": 0.01,
14      "originalAmount": 1000,
15      "finalAmount": 800,
16      "finalValue": 8
17    }
18  },
19  "installments": [],
20  "requestedProductMap": [],
21  "discountMap": {
22    "promotion": [],
23    "coupon": null,
24    "customer-wallet": null,
25    "point-system": {
26      "discountId": 31,
27      "discountType": "point-system",
28      "discountValue": 20,
29      "discountMainCode": "point-system",
30      "discountTitle": "Sistema de pontos"
31    }
32  },
33  "totalValue": 95,
34  "customer": null,
35  "addresses": [],
36  "orders": [],
37  "errors": []
38}

⚠️ 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 informado não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED401O cliente vinculado ao carrinho está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_REQUIRED401A ação exige cliente vinculado ao carrinho.
UAPPI_STORE_CART_EMPTY400O carrinho está vazio e não permite aplicar pontos.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH500Falha ao registrar erro interno no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED502A tentativa de cotação para o carrinho falhou.
UAPPI_STORE_APPLY_PROMOTIONAL_NO_ITEMS400Não há itens elegíveis para aplicação do promocional.
UAPPI_STORE_APPLY_PROMOTIONAL_NOT_FOUND404O promocional de pontos não foi encontrado.

Remover Pontos do Carrinho (Admin)

DELETE /carts/{cartId}/promotionals/point-system

Endpoint responsável por remover saldo de pontos do carrinho administrativo

Descrição

Este endpoint permite remover os pontos de fidelidade aplicados ao carrinho, desfazendo a conversão em desconto sem alterar os itens selecionados.

Na prática, ele elimina o abatimento gerado pelo uso de pontos, fazendo com que o total do carrinho volte a considerar apenas os valores monetários e demais promoções ativas 💰

Essa operação não impacta produtos, quantidades ou regras promocionais já aplicadas — apenas retira o benefício vinculado ao programa de fidelidade.

Após uma chamada bem-sucedida, o sistema recalcula o total do carrinho, refletindo a remoção do desconto por pontos.

Esse recurso exige a permissão CART_WRITE.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada.

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimIdentificador do carrinho

Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/carts/CART123/promotionals/point-system' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "CART123",
3  "countryCode": "BRA",
4  "quoteZipcode": "01310100",
5  "subtotalValue": 100,
6  "shippingValue": 15,
7  "discountValue": 0,
8  "additionValue": 0,
9  "discountPreview": {
10    "cashDiscount": null,
11    "pointSystem": null
12  },
13  "installments": [],
14  "requestedProductMap": [],
15  "discountMap": {
16    "promotion": [],
17    "coupon": null,
18    "customer-wallet": null,
19    "point-system": null
20  },
21  "totalValue": 115,
22  "customer": null,
23  "addresses": [],
24  "orders": [],
25  "errors": []
26}

⚠️ 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 informado não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED401O cliente vinculado ao carrinho está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_REQUIRED401A ação exige cliente vinculado ao carrinho.
UAPPI_STORE_CART_EMPTY400O carrinho está vazio e não permite ação promocional.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH500Falha ao registrar erro interno no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED502A tentativa de cotação para o carrinho falhou.

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

Institucional

;