Skip to content

Carrinhos administrativos e venda interna

Visão Geral

O módulo de Venda Interna é a ferramenta essencial para cenários de venda assistida, onde atendentes, representantes ou operadores de backoffice montam pedidos em nome do cliente.

Diferente do checkout público, este ecossistema na API privada oferece controle total sobre o ciclo de vida da venda antes de sua conversão definitiva em pedido.

Operando sob o prefixo de rota /carts, este módulo permite a criação de rascunhos persistentes, a retomada de atendimentos interrompidos e a duplicação de estruturas de pedidos complexas.

A segurança é garantida por autenticação de usuário corporativo (UserAuth), com permissões granulares de leitura (CART_READ) e escrita (CART_WRITE).

---

Cenário Operacional Típico

Um fluxo padrão de venda interna segue os seguintes passos: 1. Criação: O operador inicia um carrinho vinculado a um Canal de Venda específico. 2. Seleção: Produtos são adicionados, atualizados ou removidos conforme a negociação. 3. Identificação: O cliente e seus endereços são vinculados para cálculo de frete. 4. Fechamento: Definição da forma de pagamento interna e conversão em pedido real.

---

Diferenciação Técnica: API Pública vs. Privada

Enquanto a API pública depende de sessões de navegador e cookies para manter o estado do carrinho, a API privada utiliza o cartId como chave primária persistente.

Isso permite que um carrinho administrativo seja acessado de diferentes dispositivos ou por diferentes operadores (respeitando as travas de USER_MISMATCH), garantindo que o progresso da venda nunca seja perdido por expiração de sessão de front-end.

Entidades Envolvidas

As seguintes entidades compõem a estrutura lógica deste módulo:

  • Canal de Venda (salesChannelId): Define a política comercial, o catálogo visível e a tabela de preços aplicada ao carrinho desde o momento da criação.
  • Operador Administrativo (userId): Identifica o responsável pela montagem do carrinho, permitindo auditoria e segmentação de comissões ou metas.
  • Configurações de Venda Interna (internalSaleSettings): Armazena preferências específicas do operador, como a forma de pagamento selecionada para aquela negociação assistida.
  • Regras de Valor Customizado (customValueRule): Permite a aplicação de ajustes manuais de preço ou descontos específicos negociados ponto a ponto pelo operador.

Notas e Considerações

Governança e Segurança

O sistema impede a alteração de carrinhos que já resultaram em pedidos gerados (order_exists: true). Isso preserva a integridade dos dados históricos e evita que mudanças em um rascunho afetem pedidos já em processamento logístico ou financeiro.

---

Extensibilidade com fields

A maioria dos endpoints de leitura (GET) deste módulo suporta o parâmetro fields[]. Esta é uma ferramenta poderosa para evitar múltiplas requisições (over-fetching ou under-fetching).

Através dela, o operador pode decidir se deseja apenas os totais do carrinho ou se precisa carregar, na mesma chamada, a lista de itens, os endereços do cliente e as cotações de frete disponíveis.

---

Escaneabilidade da Documentação

Para facilitar a implementação, as páginas subsequentes detalham cada endpoint individualmente.

Recomenda-se a leitura atenta das seções de Erros Possíveis, que mapeiam as falhas de negócio mais comuns retornadas pelo domínio de Store, como indisponibilidade de estoque ou expiração de políticas comerciais.

Listagem de Carrinhos (Admin)

GET /carts

Recupera uma lista paginada de carrinhos administrativos com suporte a filtros avançados e carregamento de entidades relacionadas.

Descrição

Este endpoint fornece uma visão consolidada de todos os carrinhos gerados no ambiente administrativo e de venda assistida.

Ele é a base para a construção de dashboards de vendas em aberto, permitindo que operadores localizem negociações por cliente, data, valor ou responsável.

A listagem utiliza o motor de busca avançada da Uappi, suportando paginação flexível e filtros complexos.

Através do parâmetro fields, é possível expandir a resposta para incluir detalhes que não vêm por padrão, como os itens do carrinho, dados completos do cliente ou regras de preços aplicadas.

---

Capacidades de Filtro

  • Contexto de Venda: Filtre por userId para isolar carrinhos de um operador específico ou por salesChannelId para segmentar por canal de origem.
  • Geolocalização e Entrega: Localize carrinhos por zipCode (CEP) ou stateCode (UF), útil para análises logísticas de vendas pendentes.
  • Valores Operacionais: Permite filtrar faixas de totalValue ou subtotalValue, facilitando a identificação de negociações de alto ticket.

---

Escaneabilidade e Performance

Para otimizar a performance, recomenda-se solicitar apenas os fields estritamente necessários para a visualização atual.

Listagens massivas que carregam items e orders simultaneamente podem ter um tempo de resposta superior devido ao volume de processamento no domínio de Store.

Parâmetros

Headers Obrigatórios

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

Parâmetros

Campos de fields Disponíveis

CampoDescrição
addressesEndereços de entrega e faturamento vinculados.
customerDados básicos do cliente (nome, e-mail, documento).
ordersDetalhes do particionamento lógico do carrinho em pedidos.
itemsLista detalhada de produtos, SKUs e quantidades.
recoveryInformações de recuperação de carrinho (se houver).
customValueRuleRegras de preço ou valor customizado aplicadas manualmente.

Campos de Condição Disponíveis

CampoTipoDescrição
idstringID/Token único do carrinho.
userIdintegerID do operador administrativo responsável.
customerIdintegerID do cliente vinculado.
customerEmailstringBusca parcial ou exata pelo e-mail do cliente.
statusstringStatus operacional do carrinho.
totalValuenumericFiltro por valor total bruto.
createdAtdateFiltro por data de criação (suporta between).

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/carts?limit=10&offset=0&fields[]=customer&fields[]=items' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ Possíveis erros:

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

Código InternoCódigo HttpDescrição
UAPPI_AUTH_INVALID401Token expirado ou inexistente.
UAPPI_SCOPE_FORBIDDEN403O usuário não possui a permissão CART_READ.
UAPPI_LISTING_INVALID_FIELD400Um dos campos solicitados no fields é inválido ou restrito.

Criação de Carrinho (Admin)

POST /carts/sales-channel/{salesChannelId}

Inicia um novo processo de venda assistida criando um carrinho vinculado a um canal de venda e política comercial.

Descrição

Este endpoint é o ponto de partida de qualquer fluxo de venda interna na Uappi.

Ele inicializa um novo contêiner de carrinho, vinculando-o permanentemente a um Canal de Venda (salesChannelId).

Esta vinculação é crítica, pois define quais produtos estarão disponíveis para o operador e quais tabelas de preços e promoções serão aplicadas durante a montagem do pedido.

A criação do carrinho administrativo gera um identificador único persistente (token).

Diferente da API pública, onde o carrinho é gerenciado por cookies, aqui o operador deve capturar este identificador retornado na resposta para utilizá-lo como prefixo em todas as chamadas subsequentes de adição de itens, vínculo de cliente e fechamento.

---

Personalização da Validade

O operador pode, opcionalmente, definir uma data de expiração (expirationDate) para o carrinho.

Isso é útil para propostas comerciais temporárias ou orçamentos com validade limitada. Caso não seja enviada, o sistema aplicará o tempo de vida padrão configurado para carrinhos administrativos na loja.

---

Autenticação e Escopo

A criação exige um token de usuário administrativo válido com a permissão CART_WRITE.

O operador que criar o carrinho será registrado como seu "dono" inicial, vinculando o rascunho de venda ao seu perfil de usuário para fins de auditoria e listagem posterior.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
salesChannelIdintegerSimID do canal de venda que regerá as políticas do carrinho.

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
expirationDatestringNãoData limite de validade do carrinho (Formato: AAAA-MM-DD).

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/sales-channel/1' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "expirationDate": "2026-12-31"
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta contém apenas a string do identificador único do carrinho criado.

1"abc12345678910-TOKEN-EXEMPLO"

⚠️ Possíveis erros:

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

Código InternoCódigo HttpDescrição
UAPPI_AUTH_INVALID401Token administrativo ausente ou inválido.
UAPPI_SCOPE_FORBIDDEN403O usuário não possui permissão para criar carrinhos (CART_WRITE).
UAPPI_STORE_SALES_CHANNEL_NOT_FOUND404O salesChannelId informado não existe ou não está ativo.
UAPPI_STORE_CART_EXPIRATION_DATE_INVALID400A data de expiração enviada possui formato inválido ou é anterior à data atual.

Detalhe de Carrinho (Admin)

GET /carts/{cartId}

Recupera o estado completo e detalhado de um carrinho administrativo específico, incluindo entidades vinculadas e configurações de venda.

Descrição

Este endpoint retorna o estado consolidado de um carrinho administrativo.

Ele funciona como o "recibo mestre" da negociação, agregando informações de múltiplas camadas do sistema (Store, Catálogo, Logística e Pagamentos) em uma única resposta estruturada.

Diferente da listagem, o detalhe é otimizado para a exibição em telas de edição ou fechamento de pedido.

Ele apresenta desde os totais brutos até detalhes minuciosos como o mapa de produtos solicitados, endereços vinculados e o particionamento logístico (orders[]) resultante da cotação atual.

---

Uso de fields para Expansão

Por padrão, a resposta é enxuta para garantir performance. O parâmetro fields[] é essencial para carregar dados profundos:

  • items: Carrega o objeto completo dos produtos dentro de cada ordem, incluindo SKUs, imagens e nomes.
  • customer & addresses: Expande o vínculo com o CRM para mostrar dados cadastrais e de entrega.
  • internalSaleSettings: Mostra as escolhas de pagamento já feitas pelo operador.

---

Sincronia com o Domínio de Store

Cada chamada ao detalhe garante que o operador está visualizando o estado mais recente do cálculo de frete e regras de preço.

Se houverem erros persistentes (ex: CEP inválido, item sem estoque), eles serão listados no array errors[] da raiz do objeto, permitindo que a interface administrativa alerte o usuário sobre impedimentos ao fechamento.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

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

Parâmetros de Query

ParâmetroTipoObrigatórioDescrição
fields[]arrayNãoEntidades relacionadas para inclusão (ex: customer, orders, items).

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/carts/CART123?fields[]=customer&fields[]=items' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
3  "currencyId": "BRL",
4  "countryCode": "BRA",
5  "quoteZipcode": "12123-123",
6  "subtotalValue": 259.9,
7  "shippingValue": 18.4,
8  "discountValue": 15,
9  "additionValue": 0,
10  "totalValue": 263.3,
11  "discountPreview": {
12    "cashDiscount": {
13      "discountPercentage": 5,
14      "discountValue": 13.17,
15      "valueWithDiscount": 250.13
16    },
17    "pointSystem": {
18      "name": "Programa Fidelidade Uappi",
19      "pointValue": 0.01,
20      "originalAmount": 2633,
21      "finalAmount": 2501,
22      "finalValue": 25.01
23    }
24  },
25  "installments": [
26    {
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}

⚠️ Possíveis erros:

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

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho solicitado não existe ou o token é inválido.
UAPPI_SCOPE_FORBIDDEN403Falta a permissão CART_READ no token de acesso.
UAPPI_STORE_CART_USER_MISMATCH403O carrinho pertence a outro operador e o acesso foi negado.

Duplicar Carrinho (Admin)

POST /carts/{cartId}/duplicate

Cria uma cópia idêntica de um carrinho administrativo existente, gerando um novo identificador para prosseguir com uma nova negociação.

Descrição

O endpoint de duplicação é uma ferramenta estratégica para acelerar a montagem de pedidos complexos ou recorrentes.

Ele permite que o operador capture todo o trabalho de seleção de produtos, SKUs e quantidades de um carrinho existente e o replique instantaneamente em um novo identificador de carrinho.

Esta funcionalidade é ideal para cenários onde o cliente deseja repetir um pedido anterior com pequenos ajustes ou quando o operador precisa abrir uma negociação paralela (ex: testar diferentes condições de frete ou pagamento) sem perder o rascunho original.

---

Estado Espelhado

Ao duplicar, o sistema copia:

  • Todos os itens e SKUs (requestedProductMap).
  • Vinculação com o Canal de Venda original.
  • Configurações de quantidades e códigos customizados.

A resposta contém exclusivamente o novo identificador (token) do carrinho gerado, que deve ser utilizado nas chamadas subsequentes.

---

Autenticação e Regras

A operação exige permissão de escrita (CART_WRITE). O sistema valida se o operador tem acesso ao carrinho de origem antes de permitir a cópia.

Importante notar que a duplicação gera um novo rascunho independente; alterações no carrinho novo não afetarão o carrinho de origem e vice-versa.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimToken do carrinho de origem que será espelhado.

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/CART_ORIGINAL_ID/duplicate' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta retorna a string do novo identificador gerado.

1"NOVO-CART-ID-DUPLICADO"

⚠️ Possíveis erros:

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

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho de origem não foi encontrado ou já foi expirado.
UAPPI_STORE_CART_USER_MISMATCH403O operador atual não tem permissão para acessar o carrinho de origem.
UAPPI_STORE_CART_ORDER_EXISTS403O carrinho de origem já possui um pedido finalizado e, por regras de integridade, sua estrutura não pode mais ser duplicada.

Remoção de Carrinho (Admin)

DELETE /carts/{cartId}

Remove permanentemente um carrinho administrativo (rascunho de venda) do sistema.

Descrição

Este endpoint permite a exclusão definitiva de um carrinho administrativo. Sua aplicação principal é a limpeza de rascunhos de vendas canceladas, testes de operadores ou atendimentos que não progrediram para a fase de fechamento.

A remoção desvincula todas as reservas temporárias de produtos e apaga o rastro operacional do rascunho no domínio de Store.

Por ser uma ação irreversível, recomenda-se que o front-end administrativo solicite uma confirmação do operador antes de disparar esta chamada.

---

Restrições de Exclusão

Para garantir a integridade fiscal e histórica da plataforma, o sistema aplica uma trava de segurança:

Carrinhos que já foram convertidos em pedidos reais (com transação financeira ou reserva logística definitiva) não podem ser removidos.

Nesses casos, a operação retornará um erro de permissão ou conflito de estado.

---

Autenticação e Auditoria

A exclusão exige o escopo de escrita CART_WRITE. O sistema valida se o operador autenticado possui os privilégios necessários para manipular o carrinho específico, evitando a exclusão acidental de atendimentos de outros membros da equipe.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimToken identificador único do carrinho a ser removido.

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta retorna um booleano indicando o sucesso da operação.

1true

⚠️ Possíveis erros:

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

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho informado não existe ou já foi removido anteriormente.
UAPPI_STORE_CART_USER_MISMATCH403O operador não tem permissão para remover este carrinho (vínculo com outro usuário).
UAPPI_STORE_CART_ORDER_EXISTS403O carrinho já possui um pedido vinculado e não pode ser excluído por razões de integridade.

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

Institucional

;