Carrinho

Visão Geral

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

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

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

Autenticação

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

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

Token

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

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

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

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

Entidades relacionadas

Promocional Cupom

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

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

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

Promocional Carteira

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

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

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

Promocional Sistema de Pontos

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

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

Produtos de Upsell

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

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

Compre Junto

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

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

Notas e Considerações

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

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

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

Detalhe de Carrinho

GET /cart

Detalhes de um carrinho da loja

Descrição

Endpoint responsável por retornar informações detalhadas do carrinho a partir do cartToken, caso não seja informado nenhum token, um novo carrinho será criado e retornado.

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/cart \
3  --cookie {cartToken}
curl --request GET \
  --url {{MAIN_URL}}/cart \
  --cookie {cartToken}

✅ Resposta de Sucesso

1{
2  "id": "abc12345678910",
3  "countryCode": "",
4  "quoteZipcode": "",
5  "subtotalValue": 0,
6  "shippingValue": 0,
7  "discountValue": 0,
8  "additionValue": 0,
9  "totalValue": 0,
10  "discountPreview": {
11    "cashDiscount": {
12      "discountPercentage": -10,
13      "discountValue": 0,
14      "valueWithDiscount": 0
15    },
16    "pointSystem": null
17  },
18  "installments": [
19    {
20      "installment": 1,
21      "installmentValue": 0,
22      "totalValue": 0,
23      "fee": 0,
24      "feeTotalValue": 0
25    }
26  ],
27  "requestedProductMap": [],
28  "discountMap": {
29    "promotion": [],
30    "coupon": null,
31    "customer-wallet": null,
32    "point-system": null
33  },
34  "customer": null,
35  "addresses": [],
36  "orders": [],
37  "errors": [],
38  "createdAt": "2025-11-11 11-58-15",
39  "updatedAt": "2025-11-11 11-58-15"
40}
{
  "id": "abc12345678910",
  "countryCode": "",
  "quoteZipcode": "",
  "subtotalValue": 0,
  "shippingValue": 0,
  "discountValue": 0,
  "additionValue": 0,
  "totalValue": 0,
  "discountPreview": {
    "cashDiscount": {
      "discountPercentage": -10,
      "discountValue": 0,
      "valueWithDiscount": 0
    },
    "pointSystem": null
  },
  "installments": [
    {
      "installment": 1,
      "installmentValue": 0,
      "totalValue": 0,
      "fee": 0,
      "feeTotalValue": 0
    }
  ],
  "requestedProductMap": [],
  "discountMap": {
    "promotion": [],
    "coupon": null,
    "customer-wallet": null,
    "point-system": null
  },
  "customer": null,
  "addresses": [],
  "orders": [],
  "errors": [],
  "createdAt": "2025-11-11 11-58-15",
  "updatedAt": "2025-11-11 11-58-15"
}

⚠️ Possível 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.

⚠️ Erros genéricos de carrinho:

Código Interno	Código Http	Descrição
UAPPI_STORE_CART_NOT_FOUND	404	O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED	401	O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED	409	O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND	404	O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH	500	Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED	502	A tentativa de cotação para o grupo de cotação falhou.

Adição de Item no Carrinho

POST /cart

Adição de item no carrinho

Descrição

Endpoint responsável por adicionar itens ao carrinho, como produtos, upsell e compre-junto.

Não requer autenticação, porém depende do cartToken. Caso o token não seja informado, um novo carrinho será criado e os itens serão adicionados a ele.

Regras e Comportamento

Itens de upsell e compre junto não podem ser informados juntos, o produto só pode ser de um tipo por vez;
Um item de compre junto não pode ser adicionado ao carrinho caso seu par não esteja presente;
Quando a quantidade solicitada exceder o estoque disponível, um ajuste é realizado aplicando a quantidade existente;
Produtos pais não são aceitos, exceto nos casos de upsell e compre junto; deve ser informada a variação, a menos que o produto seja simples;
A expiração do carrinho pode variar de loja para loja, porém, caso nenhuma configuração seja encontrada, o padrão será de 60 dias;
A adição de produtos ao carrinho possui requisitos mínimos, como estar ativo, possuir preço, flag de disponível para venda ativa e estoque (exceto para venda sem estoque ou serviços);
Itens de upsell devem respeitar a quantidade definida na regra configurada;
O carrinho nunca é travado por erros; em caso de falha, a ação não é aplicada e o carrinho é retornado com as mensagens de erro correspondentes.

Parâmetros de query

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`items`	array	✅	Lista de produtos desejados para adicionar ao carrinho
`items.*.productId`	integer	✅	Identificador do produto que deve ser adicionado
`items.*.quantity`	integer	✅	Quantidade que deve ser adicionado do produto
`items.*.code`	string	❌	Campo opcional que permite especificação de um código ao pedido
`items.*.upsellId`	integer	❌	Campo opcional que determina se o produto é de upsell
`items.*.productPairOfferId`	integer	❌	Campo opcional que determina se o produto é um compre junto

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/cart \
3  --cookie {cartToken}
4  --data '{
5	"items": [
6		{
7			"productId":1,
8			"quantity":1
9		}
10	]
11}
curl --request POST \
  --url {{MAIN_URL}}/cart \
  --cookie {cartToken}
  --data '{
	"items": [
		{
			"productId":1,
			"quantity":1
		}
	]
}

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "abc12345678910",
3  "countryCode": "",
4  "quoteZipcode": "",
5  "subtotalValue": 100,
6  "shippingValue": 0,
7  "discountValue": 0,
8  "additionValue": 0,
9  "totalValue": 100,
10  "discountPreview": {
11    "cashDiscount": {
12      "discountPercentage": -10,
13      "discountValue": 10,
14      "valueWithDiscount": 90
15    },
16    "pointSystem": null
17  },
18  "installments": [
19    {
20      "installment": 1,
21      "installmentValue": 90,
22      "totalValue": 90,
23      "fee": 0,
24      "feeTotalValue": 0
25    }
26  ],
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": null,
40    "point-system": null
41  },
42  "customer": null,
43  "addresses": [],
44  "orders": [
45    {
46      "orderId": 0,
47      "quoteId": "",
48      "distance": 0,
49      "subtotalValue": 100,
50      "shippingValue": 0,
51      "discountValue": 0,
52      "additionValue": 0,
53      "totalValue": 100,
54      "service": false,
55      "storage": null,
56      "items": [
57        {
58          "itemId": 0,
59          "productCategoryId": 0,
60          "upsellId": null,
61          "productPairOfferId": null,
62          "productPriceRuleId": 0,
63          "productPriceRuleName": "Original",
64          "quantity": 9,
65          "code": null,
66          "unitValue": 100,
67          "unitAdditionValue": 0,
68          "unitDiscountValue": 0,
69          "subtotalValue": 100,
70          "subtotalAdditionValue": 0,
71          "subtotalDiscountValue": 0,
72          "totalValue": 100,
73          "product": {
74            "productId": 1,
75            "brandId": 0,
76            "brandName": "",
77            "mainCategoryId": 0,
78            "mainCategoryName": "",
79            "type": "product",
80            "sku": "SKU1234",
81            "name": "",
82            "active": true,
83            "url": "",
84            "comparisonPrice": 220,
85            "stock": 20,
86            "medias": [],
87            "combination": [],
88            "currentAttributes": []
89          },
90          "discounts": [],
91          "additions": []
92        }
93      ],
94      "additions": [],
95      "discounts": [],
96      "shippingOptions": []
97    }
98  ],
99  "errors": [],
100  "isMerged": false,
101  "createdAt": "2026-01-19 12:56:41",
102  "updatedAt": "2026-01-19 13:39:58"
103}
{
  "id": "abc12345678910",
  "countryCode": "",
  "quoteZipcode": "",
  "subtotalValue": 100,
  "shippingValue": 0,
  "discountValue": 0,
  "additionValue": 0,
  "totalValue": 100,
  "discountPreview": {
    "cashDiscount": {
      "discountPercentage": -10,
      "discountValue": 10,
      "valueWithDiscount": 90
    },
    "pointSystem": null
  },
  "installments": [
    {
      "installment": 1,
      "installmentValue": 90,
      "totalValue": 90,
      "fee": 0,
      "feeTotalValue": 0
    }
  ],
  "requestedProductMap": [
    {
      "productId": 1,
      "quantity": 1,
      "code": null,
      "upsellId": null,
      "productPairOfferId": null
    }
  ],
  "discountMap": {
    "promotion": [],
    "coupon": null,
    "customer-wallet": null,
    "point-system": null
  },
  "customer": null,
  "addresses": [],
  "orders": [
    {
      "orderId": 0,
      "quoteId": "",
      "distance": 0,
      "subtotalValue": 100,
      "shippingValue": 0,
      "discountValue": 0,
      "additionValue": 0,
      "totalValue": 100,
      "service": false,
      "storage": null,
      "items": [
        {
          "itemId": 0,
          "productCategoryId": 0,
          "upsellId": null,
          "productPairOfferId": null,
          "productPriceRuleId": 0,
          "productPriceRuleName": "Original",
          "quantity": 9,
          "code": null,
          "unitValue": 100,
          "unitAdditionValue": 0,
          "unitDiscountValue": 0,
          "subtotalValue": 100,
          "subtotalAdditionValue": 0,
          "subtotalDiscountValue": 0,
          "totalValue": 100,
          "product": {
            "productId": 1,
            "brandId": 0,
            "brandName": "",
            "mainCategoryId": 0,
            "mainCategoryName": "",
            "type": "product",
            "sku": "SKU1234",
            "name": "",
            "active": true,
            "url": "",
            "comparisonPrice": 220,
            "stock": 20,
            "medias": [],
            "combination": [],
            "currentAttributes": []
          },
          "discounts": [],
          "additions": []
        }
      ],
      "additions": [],
      "discounts": [],
      "shippingOptions": []
    }
  ],
  "errors": [],
  "isMerged": false,
  "createdAt": "2026-01-19 12:56:41",
  "updatedAt": "2026-01-19 13:39:58"
}

⚠️ Possíveis erros:

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

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

⚠️ Principais erros:

Código Interno	Código Http	Descrição
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_IS_INACTIVE	403	O solicitado está inativo.
UAPPI_STORE_PRODUCT_PRICE_NOT_FOUND	404	O preço do produto não foi encontrado.
UAPPI_STORE_PRODUCT_NOT_AVAILABLE_FOR_SALE	403	O produto não pode ser vendido pois está incompleto.
UAPPI_STORE_PRODUCT_IS_PARENT	400	O produto é um item pai com filhos e a operação não pode ser continuada.
UAPPI_STORE_UPSELL_NOT_FOUND	404	O upsell solicitado não foi encontrado.
UAPPI_STORE_UPSELL_QUANTITY_EXCEDEED	400	A quantidade de itens de upsell excedeu o limite.
UAPPI_STORE_PRODUCT_PAIR_OFFER_NOT_FOUND	404	O compre junto solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_PAIR_MISSING_IN_CART	400	O compre junto requer que o item complementar também esteja no carrinho.
UAPPI_STORE_STOCK_INSUFFICIENT_AVAILABLE_STOCK	400	A quantidade de estoque solicitada não está disponível.
UAPPI_STORE_STOCK_BELLOW_MINIMUM	400	O estoque do produto solicitado está abaixo do mínimo.

⚠️ Erros genéricos de carrinho:

Código Interno	Código Http	Descrição
UAPPI_STORE_CART_NOT_FOUND	404	O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED	401	O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED	409	O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND	404	O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH	500	Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED	502	A tentativa de cotação para o grupo de cotação falhou.

⚠️ Erros de promocionais:

Código Interno	Código Http	Descrição
UAPPI_STORE_SEGMENTATION_NOT_FOUND	404	A segmentação não foi encontrada.
UAPPI_STORE_APPLY_PROMOTIONAL_SEGMENTATION_FAIL	400	A promoção não pode ser aplicada porque nenhum item foi segmentado.
UAPPI_STORE_APPLY_PROMOTIONAL_NO_ITEMS	400	A promoção solicitada não pode ser aplicada porque não havia itens elegíveis para o desconto.
UAPPI_STORE_APPLY_PROMOTIONAL_NOT_FOUND	404	A promoção solicitada não pode ser aplicada, pois não foi encontrada.
UAPPI_STORE_APPLY_PROMOTIONAL_BLOCKED	400	A promoção solicitada não pode ser aplicada, pois foi bloqueada por outra promoção.
UAPPI_STORE_APPLY_PROMOTIONAL_DISABLED	400	A promoção solicitada não pode ser aplicada, pois não está ativa.
UAPPI_STORE_APPLY_PROMOTIONAL_OUT_OF_SCHEDULE	400	A promoção solicitada não pode ser aplicada, pois está fora do período de vigência.
UAPPI_STORE_APPLY_PROMOTIONAL_MAX_USE	400	A promoção solicitada não pode ser aplicada, pois atingiu o limite máximo de utilização.
UAPPI_STORE_APPLY_PROMOTIONAL_ORDER_QUANTITY	400	A promoção solicitada não pode ser aplicada, pois o cliente não atende aos requisitos de quantidade do pedido.
UAPPI_STORE_APPLY_PROMOTIONAL_DISCOUNT_UNAVAILABLE	400	A promoção não pode ser aplicada, pois não há desconto disponível.
UAPPI_STORE_APPLY_PROMOTIONAL_MISSING_TRADE_POLICY	400	A promoção solicitada não inclui o link para a política comercial.
UAPPI_STORE_APPLY_PROMOTIONAL_REQUIRED_CUSTOMER	400	A promoção solicitada não pode ser aplicada, pois requer um cliente.
UAPPI_STORE_APPLY_PROMOTIONAL_INSUFFICIENT_BALANCE	400	A promoção solicitada não pode ser aplicada porque seu saldo é insuficiente.

Atualização de Item no Carrinho

PUT /cart

Atualização de item no carrinho

Descrição

Endpoint responsável por adicionar e atualizar itens no carrinho, como produtos, upsell e compre-junto.

Não requer autenticação, porém depende do cartToken.

Caso o token não seja informado, um novo carrinho será criado e os itens serão adicionados a ele.

Essa rota se destaca por permitir a atualização dos itens já existentes no carrinho, sendo, na prática, um clone do endpoint de adição, com foco específico em atualização.

Regras e Comportamento

Itens de upsell e compre junto não podem ser informados juntos, onde o produto só pode ser um tipo por vez;
Um compre junto não pode ser adicionado ao carrinho caso seu par não esteja presente;
Quando a quantidade de itens exceder o estoque, um ajuste é realizado aplicando a quantidade disponível;
Produtos pais não são aceitos exceto por upsell e compre junto, deve ser informado a variação a menos que o produto seja simples;
A expiração do carrinho pode variar de loja para loja, mas caso nada seja encontrado o padrão será 60 dias;
A adição de produtos no carrinho possuem requisítos mínimos como estar ativo, conter preço, flag de disponível para venda ativa e possuir estoque (exceto por venda sem estoque ou venda de serviço);
Itens de upsell devem respeitar a quantidade definida na regra do upsell;
O carrinho nunca é travado por erros, este foi desenvolvido para sempre estar funcionando e em casos de erro, a ação não é aplicada e o carrinho é retornado com as mensagens de erro que ocorreram.

Parâmetros de query

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`items`	array	✅	Lista de produtos desejados para adicionar ao carrinho
`items.*.productId`	integer	✅	Identificador do produto que deve ser adicionado
`items.*.quantity`	integer	✅	Quantidade que deve ser adicionado do produto
`items.*.code`	string	❌	Campo opcional que permite especificação de um código ao pedido
`items.*.upsellId`	integer	❌	Campo opcional que determina se o produto é de upsell
`items.*.productPairOfferId`	integer	❌	Campo opcional que determina se o produto é um compre junto

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/cart \
3  --cookie {cartToken}
4  --data '{
5	"items": [
6		{
7			"productId":1,
8			"quantity":1
9		}
10	]
11}
curl --request PUT \
  --url {{MAIN_URL}}/cart \
  --cookie {cartToken}
  --data '{
	"items": [
		{
			"productId":1,
			"quantity":1
		}
	]
}

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "abc12345678910",
3  "countryCode": "",
4  "quoteZipcode": "",
5  "subtotalValue": 100,
6  "shippingValue": 0,
7  "discountValue": 0,
8  "additionValue": 0,
9  "totalValue": 100,
10  "discountPreview": {
11    "cashDiscount": {
12      "discountPercentage": -10,
13      "discountValue": 10,
14      "valueWithDiscount": 90
15    },
16    "pointSystem": null
17  },
18  "installments": [
19    {
20      "installment": 1,
21      "installmentValue": 90,
22      "totalValue": 90,
23      "fee": 0,
24      "feeTotalValue": 0
25    }
26  ],
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": null,
40    "point-system": null
41  },
42  "customer": null,
43  "addresses": [],
44  "orders": [
45    {
46      "orderId": 0,
47      "quoteId": "",
48      "distance": 0,
49      "subtotalValue": 100,
50      "shippingValue": 0,
51      "discountValue": 0,
52      "additionValue": 0,
53      "totalValue": 100,
54      "service": false,
55      "storage": null,
56      "items": [
57        {
58          "itemId": 0,
59          "productCategoryId": 0,
60          "upsellId": null,
61          "productPairOfferId": null,
62          "productPriceRuleId": 0,
63          "productPriceRuleName": "Original",
64          "quantity": 9,
65          "code": null,
66          "unitValue": 100,
67          "unitAdditionValue": 0,
68          "unitDiscountValue": 0,
69          "subtotalValue": 100,
70          "subtotalAdditionValue": 0,
71          "subtotalDiscountValue": 0,
72          "totalValue": 100,
73          "product": {
74            "productId": 1,
75            "brandId": 0,
76            "brandName": "",
77            "mainCategoryId": 0,
78            "mainCategoryName": "",
79            "type": "product",
80            "sku": "SKU1234",
81            "name": "",
82            "active": true,
83            "url": "",
84            "comparisonPrice": 220,
85            "stock": 20,
86            "medias": [],
87            "combination": [],
88            "currentAttributes": []
89          },
90          "discounts": [],
91          "additions": []
92        }
93      ],
94      "additions": [],
95      "discounts": [],
96      "shippingOptions": []
97    }
98  ],
99  "errors": [],
100  "isMerged": false,
101  "createdAt": "2026-01-19 12:56:41",
102  "updatedAt": "2026-01-19 13:39:58"
103}
{
  "id": "abc12345678910",
  "countryCode": "",
  "quoteZipcode": "",
  "subtotalValue": 100,
  "shippingValue": 0,
  "discountValue": 0,
  "additionValue": 0,
  "totalValue": 100,
  "discountPreview": {
    "cashDiscount": {
      "discountPercentage": -10,
      "discountValue": 10,
      "valueWithDiscount": 90
    },
    "pointSystem": null
  },
  "installments": [
    {
      "installment": 1,
      "installmentValue": 90,
      "totalValue": 90,
      "fee": 0,
      "feeTotalValue": 0
    }
  ],
  "requestedProductMap": [
    {
      "productId": 1,
      "quantity": 1,
      "code": null,
      "upsellId": null,
      "productPairOfferId": null
    }
  ],
  "discountMap": {
    "promotion": [],
    "coupon": null,
    "customer-wallet": null,
    "point-system": null
  },
  "customer": null,
  "addresses": [],
  "orders": [
    {
      "orderId": 0,
      "quoteId": "",
      "distance": 0,
      "subtotalValue": 100,
      "shippingValue": 0,
      "discountValue": 0,
      "additionValue": 0,
      "totalValue": 100,
      "service": false,
      "storage": null,
      "items": [
        {
          "itemId": 0,
          "productCategoryId": 0,
          "upsellId": null,
          "productPairOfferId": null,
          "productPriceRuleId": 0,
          "productPriceRuleName": "Original",
          "quantity": 9,
          "code": null,
          "unitValue": 100,
          "unitAdditionValue": 0,
          "unitDiscountValue": 0,
          "subtotalValue": 100,
          "subtotalAdditionValue": 0,
          "subtotalDiscountValue": 0,
          "totalValue": 100,
          "product": {
            "productId": 1,
            "brandId": 0,
            "brandName": "",
            "mainCategoryId": 0,
            "mainCategoryName": "",
            "type": "product",
            "sku": "SKU1234",
            "name": "",
            "active": true,
            "url": "",
            "comparisonPrice": 220,
            "stock": 20,
            "medias": [],
            "combination": [],
            "currentAttributes": []
          },
          "discounts": [],
          "additions": []
        }
      ],
      "additions": [],
      "discounts": [],
      "shippingOptions": []
    }
  ],
  "errors": [],
  "isMerged": false,
  "createdAt": "2026-01-19 12:56:41",
  "updatedAt": "2026-01-19 13:39:58"
}

⚠️ Possíveis erros:

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

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

⚠️ Principais erros:

Código Interno	Código Http	Descrição
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_IS_INACTIVE	403	O solicitado está inativo.
UAPPI_STORE_PRODUCT_PRICE_NOT_FOUND	404	O preço do produto não foi encontrado.
UAPPI_STORE_PRODUCT_NOT_AVAILABLE_FOR_SALE	403	O produto não pode ser vendido pois está incompleto.
UAPPI_STORE_PRODUCT_IS_PARENT	400	O produto é um item pai com filhos e a operação não pode ser continuada.
UAPPI_STORE_UPSELL_NOT_FOUND	404	O upsell solicitado não foi encontrado.
UAPPI_STORE_UPSELL_QUANTITY_EXCEDEED	400	A quantidade de itens de upsell excedeu o limite.
UAPPI_STORE_PRODUCT_PAIR_OFFER_NOT_FOUND	404	O compre junto solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_PAIR_MISSING_IN_CART	400	O compre junto requer que o item complementar também esteja no carrinho.
UAPPI_STORE_STOCK_INSUFFICIENT_AVAILABLE_STOCK	400	A quantidade de estoque solicitada não está disponível.
UAPPI_STORE_STOCK_BELLOW_MINIMUM	400	O estoque do produto solicitado está abaixo do mínimo.

⚠️ Erros genéricos de carrinho:

Código Interno	Código Http	Descrição
UAPPI_STORE_CART_NOT_FOUND	404	O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED	401	O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED	409	O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND	404	O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH	500	Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED	502	A tentativa de cotação para o grupo de cotação falhou.

⚠️ Erros de promocionais:

Código Interno	Código Http	Descrição
UAPPI_STORE_SEGMENTATION_NOT_FOUND	404	A segmentação não foi encontrada.
UAPPI_STORE_APPLY_PROMOTIONAL_SEGMENTATION_FAIL	400	A promoção não pode ser aplicada porque nenhum item foi segmentado.
UAPPI_STORE_APPLY_PROMOTIONAL_NO_ITEMS	400	A promoção solicitada não pode ser aplicada porque não havia itens elegíveis para o desconto.
UAPPI_STORE_APPLY_PROMOTIONAL_NOT_FOUND	404	A promoção solicitada não pode ser aplicada, pois não foi encontrada.
UAPPI_STORE_APPLY_PROMOTIONAL_BLOCKED	400	A promoção solicitada não pode ser aplicada, pois foi bloqueada por outra promoção.
UAPPI_STORE_APPLY_PROMOTIONAL_DISABLED	400	A promoção solicitada não pode ser aplicada, pois não está ativa.
UAPPI_STORE_APPLY_PROMOTIONAL_OUT_OF_SCHEDULE	400	A promoção solicitada não pode ser aplicada, pois está fora do período de vigência.
UAPPI_STORE_APPLY_PROMOTIONAL_MAX_USE	400	A promoção solicitada não pode ser aplicada, pois atingiu o limite máximo de utilização.
UAPPI_STORE_APPLY_PROMOTIONAL_ORDER_QUANTITY	400	A promoção solicitada não pode ser aplicada, pois o cliente não atende aos requisitos de quantidade do pedido.
UAPPI_STORE_APPLY_PROMOTIONAL_DISCOUNT_UNAVAILABLE	400	A promoção não pode ser aplicada, pois não há desconto disponível.
UAPPI_STORE_APPLY_PROMOTIONAL_MISSING_TRADE_POLICY	400	A promoção solicitada não inclui o link para a política comercial.
UAPPI_STORE_APPLY_PROMOTIONAL_REQUIRED_CUSTOMER	400	A promoção solicitada não pode ser aplicada, pois requer um cliente.
UAPPI_STORE_APPLY_PROMOTIONAL_INSUFFICIENT_BALANCE	400	A promoção solicitada não pode ser aplicada porque seu saldo é insuficiente.

Exclusão de itens do carrinho

DELETE /cart

Exclui itens do carrinho

Descrição

Este endpoint é responsável por permitir a remoção de itens do carrinho.

É possível informar um conjunto de produtos para exclusão em massa, sejam eles upsell, compre junto ou simples.

É importante observar que, a cada remoção, o carrinho é validado novamente por completo, garantindo consistência na aplicação de promoções, preços, pontos e demais regras.

Parâmetros de query

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`items`	array	✅	uma lista de itens que devem ser removidos do carrinho
`productId`	integer	✅	id do produto que deve ser removido
`upsellId`	integer	❌	id do upsell caso o produto a ser removido seja um item de upsell

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/cart \
3  --cookie {cartToken}
4  --data '{
5    "items":[
6      {
7        "productId":1
8      }
9    ]
10  }'
curl --request DELETE \
  --url {{MAIN_URL}}/cart \
  --cookie {cartToken}
  --data '{
    "items":[
      {
        "productId":1
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2		"id": "abc123321654456",
3		"countryCode": "",
4		"quoteZipcode": "",
5		"subtotalValue": 0,
6		"shippingValue": 0,
7		"discountValue": 0,
8		"additionValue": 0,
9		"totalValue": 0,
10		"discountPreview": {
11			"cashDiscount": {
12				"discountPercentage": -10,
13				"discountValue": 0,
14				"valueWithDiscount": 0
15			},
16			"pointSystem": null
17		},
18		"installments": [
19			{
20				"installment": 1,
21				"installmentValue": 0,
22				"totalValue": 0,
23				"fee": 0,
24				"feeTotalValue": 0
25			}
26		],
27		"requestedProductMap": [],
28		"discountMap": {
29			"promotion": [],
30			"coupon": null,
31			"customer-wallet": null,
32			"point-system": null
33		},
34		"customer": null,
35		"addresses": [],
36		"orders": [],
37		"errors": [],
38		"isMerged": false,
39		"createdAt": "2026-01-19 12:56:41",
40		"updatedAt": "2026-01-19 13:47:07"
41	}
{
		"id": "abc123321654456",
		"countryCode": "",
		"quoteZipcode": "",
		"subtotalValue": 0,
		"shippingValue": 0,
		"discountValue": 0,
		"additionValue": 0,
		"totalValue": 0,
		"discountPreview": {
			"cashDiscount": {
				"discountPercentage": -10,
				"discountValue": 0,
				"valueWithDiscount": 0
			},
			"pointSystem": null
		},
		"installments": [
			{
				"installment": 1,
				"installmentValue": 0,
				"totalValue": 0,
				"fee": 0,
				"feeTotalValue": 0
			}
		],
		"requestedProductMap": [],
		"discountMap": {
			"promotion": [],
			"coupon": null,
			"customer-wallet": null,
			"point-system": null
		},
		"customer": null,
		"addresses": [],
		"orders": [],
		"errors": [],
		"isMerged": false,
		"createdAt": "2026-01-19 12:56:41",
		"updatedAt": "2026-01-19 13:47:07"
	}

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

⚠️ Erros genéricos de carrinho:

Código Interno	Código Http	Descrição
UAPPI_STORE_CART_NOT_FOUND	404	O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED	401	O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED	409	O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND	404	O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH	500	Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED	502	A tentativa de cotação para o grupo de cotação falhou.

⚠️ Erros de promocionais:

Código Interno	Código Http	Descrição
UAPPI_STORE_SEGMENTATION_NOT_FOUND	404	A segmentação não foi encontrada.
UAPPI_STORE_APPLY_PROMOTIONAL_SEGMENTATION_FAIL	400	A promoção não pode ser aplicada porque nenhum item foi segmentado.
UAPPI_STORE_APPLY_PROMOTIONAL_NO_ITEMS	400	A promoção solicitada não pode ser aplicada porque não havia itens elegíveis para o desconto.
UAPPI_STORE_APPLY_PROMOTIONAL_NOT_FOUND	404	A promoção solicitada não pode ser aplicada, pois não foi encontrada.
UAPPI_STORE_APPLY_PROMOTIONAL_BLOCKED	400	A promoção solicitada não pode ser aplicada, pois foi bloqueada por outra promoção.
UAPPI_STORE_APPLY_PROMOTIONAL_DISABLED	400	A promoção solicitada não pode ser aplicada, pois não está ativa.
UAPPI_STORE_APPLY_PROMOTIONAL_OUT_OF_SCHEDULE	400	A promoção solicitada não pode ser aplicada, pois está fora do período de vigência.
UAPPI_STORE_APPLY_PROMOTIONAL_MAX_USE	400	A promoção solicitada não pode ser aplicada, pois atingiu o limite máximo de utilização.
UAPPI_STORE_APPLY_PROMOTIONAL_ORDER_QUANTITY	400	A promoção solicitada não pode ser aplicada, pois o cliente não atende aos requisitos de quantidade do pedido.
UAPPI_STORE_APPLY_PROMOTIONAL_DISCOUNT_UNAVAILABLE	400	A promoção não pode ser aplicada, pois não há desconto disponível.
UAPPI_STORE_APPLY_PROMOTIONAL_MISSING_TRADE_POLICY	400	A promoção solicitada não inclui o link para a política comercial.
UAPPI_STORE_APPLY_PROMOTIONAL_REQUIRED_CUSTOMER	400	A promoção solicitada não pode ser aplicada, pois requer um cliente.
UAPPI_STORE_APPLY_PROMOTIONAL_INSUFFICIENT_BALANCE	400	A promoção solicitada não pode ser aplicada porque seu saldo é insuficiente.

Recuperação de Carrinho

PUT /cart/recovery/{code}

Recuperação de carrinho por código

Descrição

Endpoint responsável por permitir que o cliente recupere seu carrinho após uma tentativa de compra abandonada anteriormente.

A Uappi trabalha com o envio de notificações, fazendo com que o cliente receba um e-mail lembrando a tentativa de compra.

Nesse e-mail, é disponibilizado um código que permite a recuperação do carrinho.

Ao acessar o link recebido, o código já é enviado como parâmetro na URL, direcionando o cliente para a loja com o carrinho recuperado.

Parâmetros de query

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
code	string	Sim	Código que possibilita recuperação do carrinho

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/cart/recovery/{code} \
3  --cookie "cartToken" \
curl --request PUT \
  --url {{MAIN_URL}}/cart/recovery/{code} \
  --cookie "cartToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"data": {
3		"id": "abc1234567890",
4		"countryCode": "BRA",
5		"quoteZipcode": "12345678",
6		"subtotalValue": 40,
7		"shippingValue": 10,
8		"discountValue": 0,
9		"additionValue": 0,
10		"totalValue": 50,
11		"discountPreview": {
12			"cashDiscount": {
13				"discountPercentage": -10,
14				"discountValue": 5,
15				"valueWithDiscount": 45
16			},
17			"pointSystem": null
18		},
19		"installments": [
20			{
21				"installment": 1,
22				"installmentValue": 50,
23				"totalValue": 50,
24				"fee": 0,
25				"feeTotalValue": 0
26			},
27			{
28				"installment": 2,
29				"installmentValue": 25,
30				"totalValue": 50,
31				"fee": 0,
32				"feeTotalValue": 0
33			},
34			{
35				"installment": 3,
36				"installmentValue": 16.60,
37				"totalValue": 50,
38				"fee": 0,
39				"feeTotalValue": 0
40			}
41		],
42		"requestedProductMap": [
43			{
44				"productId": 1,
45				"quantity": 1,
46				"code": null,
47				"upsellId": null,
48				"productPairOfferId": null
49			}
50		],
51		"discountMap": {
52			"promotion": [],
53			"coupon": null,
54			"customer-wallet": null,
55			"point-system": null
56		},
57		"customer": {
58			"customerId": 1,
59			"nameCorporateName": "Eric",
60			"tradeName": "",
61			"email": "customer@email.com",
62			"document": "",
63			"gender": "undefined",
64			"isCorporate": false,
65			"nationality": "BRA",
66			"birthdate": "2001-01-16",
67			"phone": "+5511123451234"
68		},
69		"addresses": [],
70		"orders": [
71			{
72				"orderId": 0,
73				"quoteId": "abc1234567",
74				"distance": 5949,
75				"subtotalValue": 40,
76				"shippingValue": 10,
77				"discountValue": 0,
78				"additionValue": 0,
79				"totalValue": 45,
80				"service": false,
81				"storage": {
82					"id": 1,
83					"code": "code123",
84					"corporateName": "Storage Ltda.",
85					"email": "storage@email.com.br",
86					"phone": "+5511123451234",
87					"tradeName": "Armazém Principal",
88					"stateCode": "BR-SP",
89					"countryCode": "BRA",
90					"document": "12345567896743",
91					"zipCode": "12312312",
92					"city": "Birigui",
93					"address": "Rua das flores",
94					"district": "Jardim bonito",
95					"number": "10",
96					"complement": "",
97					"latitude": "",
98					"longitude": "",
99					"active": true,
100					"observation": null,
101					"tradePolicyExceptions": []
102				},
103				"items": [
104					{
105						"itemId": 0,
106						"productCategoryId": 1,
107						"upsellId": null,
108						"productPairOfferId": null,
109						"productPriceRuleId": 0,
110						"productPriceRuleName": "Original",
111						"quantity": 1,
112						"code": null,
113						"unitValue": 40,
114						"unitAdditionValue": 0,
115						"unitDiscountValue": 0,
116						"subtotalValue": 40,
117						"subtotalAdditionValue": 0,
118						"subtotalDiscountValue": 0,
119						"totalValue": 45,
120						"product": {
121							"productId": 1,
122							"brandId": 1,
123							"brandName": "TechBrand",
124							"mainCategoryId": 1,
125							"mainCategoryName": "Tecnologia",
126							"type": "product",
127							"sku": "ABC123SKU",
128							"name": "Fone de ouvido com fio",
129							"active": true,
130							"url": "/fone-com-fio-techbrand.html",
131							"comparisonPrice": 60,
132							"stock": 25,
133							"medias": [],
134							"combination": [],
135							"currentAttributes": []
136						},
137						"discounts": [],
138						"additions": []
139					}
140				],
141				"additions": [],
142				"discounts": [],
143				"shippingOptions": []
144			}
145		],
146		"errors": [],
147		"isMerged": false,
148		"createdAt": "2026-01-21 08:39:09",
149		"updatedAt": "2026-01-21 13:17:05",
150		"tradePolicyId": 1,
151		"salesChannelId": 1,
152		"userId": 0,
153		"username": "",
154		"userEmail": "",
155		"expirationDate": "2026-02-20"
156	}
157}
{
	"data": {
		"id": "abc1234567890",
		"countryCode": "BRA",
		"quoteZipcode": "12345678",
		"subtotalValue": 40,
		"shippingValue": 10,
		"discountValue": 0,
		"additionValue": 0,
		"totalValue": 50,
		"discountPreview": {
			"cashDiscount": {
				"discountPercentage": -10,
				"discountValue": 5,
				"valueWithDiscount": 45
			},
			"pointSystem": null
		},
		"installments": [
			{
				"installment": 1,
				"installmentValue": 50,
				"totalValue": 50,
				"fee": 0,
				"feeTotalValue": 0
			},
			{
				"installment": 2,
				"installmentValue": 25,
				"totalValue": 50,
				"fee": 0,
				"feeTotalValue": 0
			},
			{
				"installment": 3,
				"installmentValue": 16.60,
				"totalValue": 50,
				"fee": 0,
				"feeTotalValue": 0
			}
		],
		"requestedProductMap": [
			{
				"productId": 1,
				"quantity": 1,
				"code": null,
				"upsellId": null,
				"productPairOfferId": null
			}
		],
		"discountMap": {
			"promotion": [],
			"coupon": null,
			"customer-wallet": null,
			"point-system": null
		},
		"customer": {
			"customerId": 1,
			"nameCorporateName": "Eric",
			"tradeName": "",
			"email": "customer@email.com",
			"document": "",
			"gender": "undefined",
			"isCorporate": false,
			"nationality": "BRA",
			"birthdate": "2001-01-16",
			"phone": "+5511123451234"
		},
		"addresses": [],
		"orders": [
			{
				"orderId": 0,
				"quoteId": "abc1234567",
				"distance": 5949,
				"subtotalValue": 40,
				"shippingValue": 10,
				"discountValue": 0,
				"additionValue": 0,
				"totalValue": 45,
				"service": false,
				"storage": {
					"id": 1,
					"code": "code123",
					"corporateName": "Storage Ltda.",
					"email": "storage@email.com.br",
					"phone": "+5511123451234",
					"tradeName": "Armazém Principal",
					"stateCode": "BR-SP",
					"countryCode": "BRA",
					"document": "12345567896743",
					"zipCode": "12312312",
					"city": "Birigui",
					"address": "Rua das flores",
					"district": "Jardim bonito",
					"number": "10",
					"complement": "",
					"latitude": "",
					"longitude": "",
					"active": true,
					"observation": null,
					"tradePolicyExceptions": []
				},
				"items": [
					{
						"itemId": 0,
						"productCategoryId": 1,
						"upsellId": null,
						"productPairOfferId": null,
						"productPriceRuleId": 0,
						"productPriceRuleName": "Original",
						"quantity": 1,
						"code": null,
						"unitValue": 40,
						"unitAdditionValue": 0,
						"unitDiscountValue": 0,
						"subtotalValue": 40,
						"subtotalAdditionValue": 0,
						"subtotalDiscountValue": 0,
						"totalValue": 45,
						"product": {
							"productId": 1,
							"brandId": 1,
							"brandName": "TechBrand",
							"mainCategoryId": 1,
							"mainCategoryName": "Tecnologia",
							"type": "product",
							"sku": "ABC123SKU",
							"name": "Fone de ouvido com fio",
							"active": true,
							"url": "/fone-com-fio-techbrand.html",
							"comparisonPrice": 60,
							"stock": 25,
							"medias": [],
							"combination": [],
							"currentAttributes": []
						},
						"discounts": [],
						"additions": []
					}
				],
				"additions": [],
				"discounts": [],
				"shippingOptions": []
			}
		],
		"errors": [],
		"isMerged": false,
		"createdAt": "2026-01-21 08:39:09",
		"updatedAt": "2026-01-21 13:17:05",
		"tradePolicyId": 1,
		"salesChannelId": 1,
		"userId": 0,
		"username": "",
		"userEmail": "",
		"expirationDate": "2026-02-20"
	}
}

⚠️ Possíveis erros:

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

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

⚠️ Principais erros:

Código Interno	Código Http	Descrição
UAPPI_STORE_CART_RECOVERY_CODE_INVALID	404	O código de recuperação é inválido ou expirou.

⚠️ Erros genéricos de carrinho:

Código Interno	Código Http	Descrição
UAPPI_STORE_CART_NOT_FOUND	404	O carrinho atual não foi encontrado.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED	401	O cliente está inativo.
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED	409	O carrinho já possui um cliente definido.
UAPPI_STORE_CUSTOMER_NOT_FOUND	404	O cliente solicitado não foi encontrado.
UAPPI_STORE_CART_INVALID_ERROR_TO_PUSH	500	Falha ao aplicar erro no carrinho.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED	502	A tentativa de cotação para o grupo de cotação falhou.

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

Carrinho

Visão Geral

Autenticação

Token

Entidades relacionadas

Promocional Cupom

Promocional Carteira

Promocional Sistema de Pontos

Produtos de Upsell

Compre Junto

Notas e Considerações

Detalhe de Carrinho

Descrição

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possível erros:

⚠️ Erros genéricos de carrinho:

Adição de Item no Carrinho

Descrição

Regras e Comportamento

Parâmetros de query

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

⚠️ Principais erros:

⚠️ Erros genéricos de carrinho:

⚠️ Erros de promocionais:

Atualização de Item no Carrinho