Itens do carrinho administrativo

Visão Geral

O gerenciamento de itens no carrinho administrativo é o núcleo da operação de venda assistida.

Após a obtenção de um cartId válido, o operador utiliza o prefixo de rota /carts/{cartId}/item para espelhar as negociações em tempo real com o cliente, permitindo a construção granular do pedido.

Diferente do fluxo público baseado em sessões transitórias (cookies), o carrinho administrativo utiliza identificadores persistentes e autenticação corporativa (Bearer token), garantindo que a montagem do pedido possa ser interrompida e retomada com total segurança e rastreabilidade.

Este módulo compartilha regras de negócio críticas com o checkout público, como validações de estoque, políticas de preços e programas de benefícios, assegurando que o operador administrativo visualize exatamente o que o cliente final veria, mas com o poder de intervenção direta em produtos e quantidades.

Entidades Envolvidas

Neste fluxo, as seguintes entidades e conceitos operacionais são fundamentais:

Produto e SKU: A unidade básica de venda. Inclui a validação de estoque projetado (stock), tipo de produto (físico ou digital) e regras de categoria.
Upsell e Venda Cruzada: Ofertas complementares (upsellId) que podem ser vinculadas a itens específicos para elevar o ticket médio.
Compre Junto (Product Pair): Relacionamentos de oferta (productPairOfferId) que exigem a presença de itens específicos no carrinho para validação do desconto ou condição.
Requested Product Map: Um mapa que consolida o "raciocínio" do pedido, permitindo visualizar os itens antes mesmo de serem particionados em remessas (shipments/orders) por armazém.

Notas e Considerações

As operações de alteração de itens são protegidas pelo escopo CART_WRITE. Qualquer tentativa de modificação sem este privilégio resultará em erro de autorização.

---

Cálculos e Particionamento

A cada alteração de item, o domínio de Store executa um ciclo de recálculo total.

Isso inclui a reavaliação de taxas de entrega, quotas por armazém (storage) e aplicação de regras de preço. Em carrinhos com múltiplos itens, o sistema pode particionar a resposta em múltiplos objetos dentro de orders[] caso os produtos provenham de origens logísticas distintas.

---

Sincronização de Estoque

O sistema valida a disponibilidade no momento da adição e atualização. Mensagens de "estoque insuficiente" seguem o padrão global da plataforma, permitindo que o operador informe ao cliente sobre disponibilidades parciais ou prazos diferenciados.

Adição de Itens no Carrinho (Admin)

POST /carts/{cartId}/item

Inclui novos produtos e SKUs em um carrinho administrativo existente para montagem assistida do pedido.

Descrição

Este endpoint permite a inclusão de novas linhas de produto no carrinho administrativo. Ele é fundamental para fluxos de venda assistida onde o operador administrativo insere os itens negociados diretamente no carrinho do cliente.

A requisição aceita uma lista de objetos, permitindo a adição em lote de múltiplos produtos. Para cada item, é validada a existência do produto, o status ativo e a disponibilidade de estoque no armazém correspondente.

---

Regras de Negócio e Validações

Estoque: O sistema verifica se a quantidade solicitada está disponível. Caso o estoque seja insuficiente ou esteja abaixo do mínimo permitido, a operação retornará erro.
Conflitos de Oferta: Os campos upsellId e productPairOfferId são mutuamente exclusivos por item. Tentar enviar ambos na mesma linha de produto resultará em erro de validação.
Tipagem de Produto: Produtos do tipo "Pai" (configuráveis) não podem ser adicionados diretamente; apenas seus SKUs (filhos) são elegíveis para o carrinho.

---

Comportamento Pós-Adição

Após o sucesso da inclusão, o backend realiza um recálculo automático de todos os valores do carrinho (subtotal, frete e descontos).

A resposta retornada contém o objeto completo do carrinho (CartDMC), permitindo que a interface administrativa se atualize imediatamente com os novos totais e possíveis particionamentos de remessa.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	`Bearer {token}`	Token do usuário autenticado na API privada.
`Content-Type`	`application/json`	Tipo de conteúdo da requisição.

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
cartId	string	Sim	Identificador único (UUID ou slug) do carrinho administrativo.

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
items	array	Sim	Lista de objetos contendo os itens a serem adicionados.
items.*.productId	integer	Sim	ID único do produto/SKU no catálogo.
items.*.quantity	integer	Sim	Quantidade desejada do item (deve ser maior que zero).
items.*.code	string	Não	Código de referência customizado para o item (máx. 32 caracteres).
items.*.upsellId	integer	Não	ID de uma oferta de Upsell vinculada ao item.
items.*.productPairOfferId	integer	Não	ID de uma oferta de Compre Junto (Product Pair).

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/CART123/item' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "items": [
7      {
8        "productId": 1,
9        "quantity": 2
10      }
11    ]
12  }'
curl --request POST \
  --url '{{MAIN_URL}}/carts/CART123/item' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "productId": 1,
        "quantity": 2
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

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

⚠️ Possíveis erros:

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

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

Código Interno	Código Http	Descrição
UAPPI_STORE_CART_NOT_FOUND	404	O carrinho informado não foi encontrado.
UAPPI_STORE_CART_USER_MISMATCH	403	O carrinho pertence a outro usuário de venda interna.
UAPPI_STORE_CART_ORDER_EXISTS	403	O carrinho já possui um pedido finalizado e não pode ser alterado.
UAPPI_STORE_PRODUCT_NOT_FOUND	404	Um ou mais IDs de produto na lista não foram encontrados.
UAPPI_STORE_PRODUCT_IS_INACTIVE	403	O produto informado está inativo no catálogo.
UAPPI_STORE_PRODUCT_IS_PARENT	400	O ID informado pertence a um produto pai (deve-se usar o ID do SKU/filho).
UAPPI_STORE_STOCK_INSUFFICIENT_AVAILABLE_STOCK	400	A quantidade solicitada excede o estoque disponível.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED	502	Falha ao tentar recalcular o frete após a inserção do item.

Atualização de Itens no Carrinho (Admin)

PUT /carts/{cartId}/item

Ajusta quantidades e configurações de itens já existentes em um carrinho administrativo.

Descrição

Este endpoint permite o ajuste de quantidades e parâmetros de ofertas para itens que já foram previamente adicionados ao carrinho administrativo.

Ele é utilizado principalmente para refletir mudanças na negociação, como o aumento ou diminuição do volume de um SKU específico.

Diferente do endpoint de adição (POST), o PUT sincroniza o estado do item com os novos valores enviados.

Se o produto não existir no carrinho, o comportamento padrão do serviço de Store é ignorar a atualização ou retornar um erro de consistência, dependendo do estado global da venda.

---

Regras de Negócio e Validações

Persistência de Quantidade: A quantidade enviada substitui o valor anterior (não é incremental). Enviar quantity: 0 pode resultar na remoção do item ou em erro, dependendo da configuração da loja; recomenda-se usar o método DELETE para remoções explícitas.
Validação de Estoque: Assim como na adição, qualquer aumento de quantidade dispara uma nova checagem de estoque e disponibilidade.
Vínculos de Oferta: É possível atualizar ou vincular um upsellId ou productPairOfferId a um item existente, desde que as regras de exclusividade mútua sejam respeitadas.

---

Impacto nos Cálculos

Toda atualização bem-sucedida força a invalidação de cotações de frete anteriores e recalcula todos os impostos e descontos aplicáveis ao carrinho.

Se o carrinho possuir endereços vinculados, o sistema tentará re-cotar as opções de entrega automaticamente.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	`Bearer {token}`	Token do usuário autenticado na API privada.
`Content-Type`	`application/json`	Tipo de conteúdo da requisição.

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
cartId	string	Sim	Identificador único do carrinho administrativo.

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
items	array	Sim	Lista de itens para atualização.
items.*.productId	integer	Sim	ID único do produto/SKU a ser atualizado.
items.*.quantity	integer	Sim	Nova quantidade total para o item.
items.*.code	string	Não	Código de referência customizado (máx. 32 caracteres).
items.*.upsellId	integer	Não	ID de oferta de Upsell vinculada.
items.*.productPairOfferId	integer	Não	ID de oferta de Compre Junto vinculada.

Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/carts/CART123/item' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "items": [
7      {
8        "productId": 1,
9        "quantity": 5
10      }
11    ]
12  }'
curl --request PUT \
  --url '{{MAIN_URL}}/carts/CART123/item' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "productId": 1,
        "quantity": 5
      }
    ]
  }'

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

⚠️ 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_CART_NOT_FOUND	404	O carrinho informado não foi encontrado.
UAPPI_STORE_CART_ORDER_EXISTS	403	O carrinho já possui um pedido e não pode ser editado.
UAPPI_STORE_STOCK_INSUFFICIENT_AVAILABLE_STOCK	400	A nova quantidade solicitada não está disponível em estoque.
UAPPI_STORE_PRODUCT_NOT_AVAILABLE_FOR_SALE	403	O produto não está mais disponível para venda.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED	502	Erro ao recalcular frete após a mudança de quantidades.

Remoção de Itens do Carrinho (Admin)

DELETE /carts/{cartId}/item

Remove um ou mais produtos de um carrinho administrativo específico.

Descrição

Este endpoint é responsável por retirar produtos e SKUs de um carrinho administrativo ativo. Ele deve ser utilizado quando um item inserido anteriormente não faz mais parte da negociação ou quando o operador deseja limpar a seleção de produtos antes de prosseguir com o fechamento.

A operação remove completamente a referência do item no mapa de produtos solicitados (requestedProductMap) e dispara a reorganização das ordens de pedido (orders[]) dentro do carrinho.

---

Regras de Negócio e Validações

Inexistência de Item: Tentar remover um produto que não está presente no carrinho não resulta em erro crítico (operação idempotente do ponto de vista do estado final), mas o backend valida a integridade do cartId antes de qualquer ação.
Remoção de Upsells: Se um item possuir um Upsell vinculado, ele pode ser removido especificando o upsellId. Caso contrário, a remoção pelo productId retira o item principal e suas dependências diretas de oferta.
Bloqueio de Edição: Assim como as outras operações de escrita, se o carrinho já tiver sido convertido em um pedido real (order_exists), a remoção de itens será bloqueada.

---

Consequências Operacionais

A remoção de um item pode alterar drasticamente o subtotal e, consequentemente, as regras de frete gratuito ou descontos progressivos por volume.

O sistema sempre invalidará as cotações de frete existentes para garantir que o fechamento do pedido reflita apenas a carga logística dos itens remanescentes.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	`Bearer {token}`	Token do usuário autenticado na API privada.
`Content-Type`	`application/json`	Tipo de conteúdo da requisição.

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
cartId	string	Sim	Identificador único do carrinho administrativo.

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
items	array	Sim	Lista de objetos contendo os itens para exclusão.
items.*.productId	integer	Sim	ID único do produto/SKU a ser removido.
items.*.upsellId	integer	Não	ID específico de um Upsell a ser removido (aceita null).

Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/carts/CART123/item' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "items": [
7      {
8        "productId": 1
9      }
10    ]
11  }'
curl --request DELETE \
  --url '{{MAIN_URL}}/carts/CART123/item' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "productId": 1
      }
    ]
  }'

✅ 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": null,
12  "installments": [],
13  "requestedProductMap": [],
14  "discountMap": [],
15  "customer": null,
16  "addresses": [],
17  "orders": [],
18  "errors": [],
19  "isMerged": false,
20  "createdAt": "2026-05-05 10:00:00",
21  "updatedAt": "2026-05-05 10:43:21"
22}
{
  "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
  "currencyId": "BRL",
  "countryCode": "BRA",
  "quoteZipcode": "12123-123",
  "subtotalValue": 259.9,
  "shippingValue": 18.4,
  "discountValue": 15,
  "additionValue": 0,
  "totalValue": 263.3,
  "discountPreview": null,
  "installments": [],
  "requestedProductMap": [],
  "discountMap": [],
  "customer": null,
  "addresses": [],
  "orders": [],
  "errors": [],
  "isMerged": false,
  "createdAt": "2026-05-05 10:00:00",
  "updatedAt": "2026-05-05 10:43:21"
}

⚠️ 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_CART_NOT_FOUND	404	O carrinho informado não foi encontrado.
UAPPI_STORE_CART_ORDER_EXISTS	403	O carrinho já possui um pedido e seus itens não podem mais ser removidos.
UAPPI_STORE_CART_USER_MISMATCH	403	O operador não tem permissão para manipular este carrinho específico.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH	500	Erro interno ao tentar persistir a mudança de estado do carrinho.

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

Itens do carrinho administrativo

Visão Geral

Entidades Envolvidas

Notas e Considerações

Adição de Itens no Carrinho (Admin)

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Atualização de Itens no Carrinho (Admin)

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Remoção de Itens do Carrinho (Admin)

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso