Transporte e Cotizações no Admin

Visão Geral

O gerenciamento logístico no carrinho administrativo permite que o operador simule custos e prazos de entrega em tempo real para o cliente.

Este processo é essencial para a transparência da venda assistida, permitindo que a melhor opção de frete seja negociada e selecionada antes da conversão do carrinho em pedido.

O ecossistema de frete no admin opera em dois tempos: 1. Simulação (POST /quote): O sistema consulta as tabelas de frete e transportadoras integradas para o destino informado, retornando uma lista de opções candidatas. 2. Efetivação (PUT /shipping): O operador seleciona uma das opções retornadas, consolidando o valor de entrega no total do carrinho.

---

Particionamento Logístico (orders[])

Um diferencial crítico da plataforma Uappi v3 é o tratamento de pedidos multi-origem.

Caso o carrinho contenha produtos armazenados em diferentes centros de distribuição, o sistema particionará a resposta em múltiplos objetos dentro do array orders[].

Nesses casos, a cotação e a seleção do frete devem ser feitas de forma independente para cada "ordem" simulada, garantindo a precisão dos prazos e custos por armazém.

---

Pontos de Retirada (Pickup Points)

Além da entrega convencional, a API suporta modalidades de "Clique e Retire".

Quando uma transportadora permite esta modalidade, o sistema retorna os shippingPickupPointId disponíveis, que devem ser informados no momento da seleção final para garantir o correto direcionamento da mercadoria.

Entidades Envolvidas

Shipping Options: Lista dinâmica de transportadoras que atendem ao CEP de destino, contendo valor do frete (shippingValue) e tempo de trânsito em dias úteis ou corridos.
Shipping Table: Identificador da regra de frete no backend que rege o cálculo (tabela de preços, contrato com Correios, transportadoras privadas, etc.).
Target Zip Code: O CEP de destino, que serve como chave primária para a consulta nas tabelas de faixas de CEP.

Notas e Considerações

Resiliência de Cotação

O processo de cotação frequentemente depende de web services externos (transportadoras e hubs logísticos).

O erro UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED sinaliza que o sistema não conseguiu obter resposta desses serviços.

Nestes cenários, o operador pode tentar uma nova cotação ou verificar se os dados de peso e dimensões dos produtos no catálogo estão preenchidos corretamente.

---

Invalidação Automática

Qualquer alteração na composição de itens do carrinho (adição, remoção ou mudança de quantidade) invalida automaticamente as seleções de frete anteriores.

Isso ocorre porque o peso cubado e o valor total do carrinho são variáveis críticas para o cálculo de frete e concessão de benefícios como "Frete Grátis".

Cotação de Frete do Carrinho (Admin)

POST /carts/{cartId}/quote

Consulta as transportadoras e opções de entrega disponíveis para o destino informado, considerando o peso e dimensões dos itens no carrinho.

Descrição

Este endpoint realiza a simulação logística para o carrinho administrativo.

Ao informar um CEP de destino, o sistema aciona o motor de fretes da Uappi, que consulta tabelas internas e integradores externos para retornar todas as modalidades de entrega compatíveis com a carga atual.

A resposta desta chamada popula o array shippingOptions dentro de cada ordem simulada (orders[]).

É importante notar que a cotação é uma operação de consulta: ela não altera a escolha final de frete do carrinho, apenas apresenta as possibilidades para que o operador possa negociar prazos e valores com o cliente.

---

Validação de Endereço

Embora o carrinho possa ter um endereço formal já vinculado, este endpoint permite realizar cotações rápidas apenas com o targetZipCode.

Isso é útil para simulações preliminares antes de o operador realizar o vínculo definitivo do cliente ou do endereço ao carrinho.

---

Escopo de Acesso

A cotação é considerada uma operação de escrita de contexto, exigindo a permissão CART_WRITE.

Isso ocorre porque os resultados da cotação são persistidos temporariamente no estado do carrinho para permitir a seleção subsequente sem a necessidade de uma nova chamada aos integradores.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	`Bearer {token}`	Token do usuário autenticado na API privada com escopo `CART_WRITE`.
`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	Token identificador único do carrinho administrativo.

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`targetCountryCode`	string	Sim	Código ISO do país com 3 caracteres (ex: `BRA`).
`targetZipCode`	string	Sim	CEP ou código postal para o cálculo do frete.

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/CART123/quote' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "targetCountryCode": "BRA",
7    "targetZipCode": "01310100"
8  }'
curl --request POST \
  --url '{{MAIN_URL}}/carts/CART123/quote' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "targetCountryCode": "BRA",
    "targetZipCode": "01310100"
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
5    "currencyId": "BRL",
6    "countryCode": "BRA",
7    "quoteZipcode": "01310100",
8    "subtotalValue": 259.9,
9    "shippingValue": 0,
10    "discountValue": 0,
11    "additionValue": 0,
12    "totalValue": 259.9,
13    "discountPreview": {
14      "cashDiscount": null,
15      "pointSystem": null
16    },
17    "installments": [],
18    "requestedProductMap": [
19      {
20        "productId": 1,
21        "quantity": 2,
22        "code": "PROMO-ADMIN",
23        "upsellId": null,
24        "productPairOfferId": null
25      }
26    ],
27    "discountMap": {
28      "promotion": [],
29      "coupon": null,
30      "customer-wallet": null,
31      "point-system": null
32    },
33    "customer": null,
34    "addresses": [],
35    "orders": [
36      {
37        "orderId": 1,
38        "quoteId": "quote-01",
39        "distance": 12.5,
40        "subtotalValue": 259.9,
41        "shippingValue": 0,
42        "discountValue": 0,
43        "additionValue": 0,
44        "totalValue": 259.9,
45        "service": false,
46        "storage": null,
47        "items": [],
48        "additions": [],
49        "discounts": [],
50        "shippingOptions": [
51          {
52            "shippingTableId": 55,
53            "shippingPickupPointId": 0,
54            "label": "Entrega Expressa",
55            "shippingValue": 25.50,
56            "beginShippingTime": 1,
57            "endShippingTime": 2,
58            "shippingTimeType": "days",
59            "selected": false,
60            "details": null
61          }
62        ]
63      }
64    ],
65    "errors": [],
66    "isMerged": false,
67    "createdAt": "2026-05-05 10:00:00",
68    "updatedAt": "2026-05-05 10:45:00"
69  }
70}
{
  "status": true,
  "data": {
    "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
    "currencyId": "BRL",
    "countryCode": "BRA",
    "quoteZipcode": "01310100",
    "subtotalValue": 259.9,
    "shippingValue": 0,
    "discountValue": 0,
    "additionValue": 0,
    "totalValue": 259.9,
    "discountPreview": {
      "cashDiscount": null,
      "pointSystem": null
    },
    "installments": [],
    "requestedProductMap": [
      {
        "productId": 1,
        "quantity": 2,
        "code": "PROMO-ADMIN",
        "upsellId": null,
        "productPairOfferId": null
      }
    ],
    "discountMap": {
      "promotion": [],
      "coupon": null,
      "customer-wallet": null,
      "point-system": null
    },
    "customer": null,
    "addresses": [],
    "orders": [
      {
        "orderId": 1,
        "quoteId": "quote-01",
        "distance": 12.5,
        "subtotalValue": 259.9,
        "shippingValue": 0,
        "discountValue": 0,
        "additionValue": 0,
        "totalValue": 259.9,
        "service": false,
        "storage": null,
        "items": [],
        "additions": [],
        "discounts": [],
        "shippingOptions": [
          {
            "shippingTableId": 55,
            "shippingPickupPointId": 0,
            "label": "Entrega Expressa",
            "shippingValue": 25.50,
            "beginShippingTime": 1,
            "endShippingTime": 2,
            "shippingTimeType": "days",
            "selected": false,
            "details": null
          }
        ]
      }
    ],
    "errors": [],
    "isMerged": false,
    "createdAt": "2026-05-05 10:00:00",
    "updatedAt": "2026-05-05 10:45:00"
  }
}

⚠️ 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 administrativo informado não foi encontrado.
UAPPI_STORE_CART_QUOTE_ATTEMPT_FAILED	502	Falha na comunicação com o motor de fretes ou transportadoras externas.
UAPPI_STORE_CART_EMPTY	400	Não é possível cotar frete para um carrinho sem itens.
UAPPI_STORE_CART_USER_MISMATCH	403	O operador não tem permissão para realizar cotações neste carrinho.
UAPPI_STORE_CART_ORDER_EXISTS	403	O carrinho já foi convertido em pedido e sua logística não pode mais ser alterada.
UAPPI_STORE_ZIPCODE_RANGE_NO_COVERAGE	409	Não há entrega disponível para o CEP informado.

Seleção de Frete no Carrinho (Admin)

PUT /carts/{cartId}/shipping

Define a transportadora e a modalidade de entrega escolhidas para os pedidos do carrinho administrativo.

Descrição

Após a realização da cotação, o operador deve utilizar este endpoint para efetivar a escolha do frete.

Esta ação fixa os valores e prazos de entrega no carrinho, sendo um passo obrigatório para que o sistema consiga calcular o valor total final (Grand Total) e habilitar as opções de pagamento.

A seleção deve ser feita por cartOrderId, permitindo que o operador escolha diferentes transportadoras para diferentes origens logísticas (armazéns) dentro do mesmo carrinho.

Se uma transportadora do tipo "Retirada" for selecionada, o identificador do ponto de coleta (shippingPickupPointId) também deve ser enviado.

---

Consistência Logística

A API valida se a shippingTableId enviada estava de fato presente nos resultados da última cotação realizada para aquele carrinho.

Tentar forçar um ID de tabela de frete que não foi retornado pela cotação resultará em erro, garantindo que apenas opções logísticas válidas e disponíveis sejam aplicadas.

---

Persistência da Escolha

Uma vez selecionado, o frete permanece fixo até que ocorra uma mudança na composição de itens do carrinho ou uma nova cotação seja solicitada.

A resposta desta chamada retorna o objeto do carrinho com o status selected: true na opção escolhida, permitindo que a interface administrativa destaque a transportadora selecionada.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	`Bearer {token}`	Token do usuário autenticado na API privada com escopo `CART_WRITE`.
`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	Token identificador único do carrinho administrativo.

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
orders	array	Sim	Lista de objetos contendo as definições de frete por ordem.
orders[].cartOrderId	integer	Sim	ID da ordem/particionamento dentro do carrinho.
orders[].shippingTableId	integer	Sim	ID da tabela de frete/transportadora selecionada.
orders[].shippingPickupPointId	integer	Não	ID do ponto de retirada (obrigatório para modalidades de retirada).

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
5    "currencyId": "BRL",
6    "countryCode": "BRA",
7    "quoteZipcode": "01310100",
8    "subtotalValue": 259.9,
9    "shippingValue": 25.5,
10    "discountValue": 0,
11    "additionValue": 0,
12    "totalValue": 285.4,
13    "discountPreview": {
14      "cashDiscount": null,
15      "pointSystem": null
16    },
17    "installments": [],
18    "requestedProductMap": [
19      {
20        "productId": 1,
21        "quantity": 2,
22        "code": "PROMO-ADMIN",
23        "upsellId": null,
24        "productPairOfferId": null
25      }
26    ],
27    "discountMap": {
28      "promotion": [],
29      "coupon": null,
30      "customer-wallet": null,
31      "point-system": null
32    },
33    "customer": null,
34    "addresses": [],
35    "orders": [
36      {
37        "orderId": 1,
38        "quoteId": "quote-01",
39        "distance": 12.5,
40        "subtotalValue": 259.9,
41        "shippingValue": 25.5,
42        "discountValue": 0,
43        "additionValue": 0,
44        "totalValue": 285.4,
45        "service": false,
46        "storage": null,
47        "items": [],
48        "additions": [],
49        "discounts": [],
50        "shippingOptions": [
51          {
52            "shippingTableId": 55,
53            "shippingPickupPointId": 0,
54            "label": "Entrega Expressa",
55            "shippingValue": 25.50,
56            "beginShippingTime": 1,
57            "endShippingTime": 2,
58            "shippingTimeType": "days",
59            "selected": true,
60            "details": null
61          }
62        ]
63      }
64    ],
65    "errors": [],
66    "isMerged": false,
67    "createdAt": "2026-05-05 10:00:00",
68    "updatedAt": "2026-05-05 10:50:00"
69  }
70}
{
  "status": true,
  "data": {
    "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
    "currencyId": "BRL",
    "countryCode": "BRA",
    "quoteZipcode": "01310100",
    "subtotalValue": 259.9,
    "shippingValue": 25.5,
    "discountValue": 0,
    "additionValue": 0,
    "totalValue": 285.4,
    "discountPreview": {
      "cashDiscount": null,
      "pointSystem": null
    },
    "installments": [],
    "requestedProductMap": [
      {
        "productId": 1,
        "quantity": 2,
        "code": "PROMO-ADMIN",
        "upsellId": null,
        "productPairOfferId": null
      }
    ],
    "discountMap": {
      "promotion": [],
      "coupon": null,
      "customer-wallet": null,
      "point-system": null
    },
    "customer": null,
    "addresses": [],
    "orders": [
      {
        "orderId": 1,
        "quoteId": "quote-01",
        "distance": 12.5,
        "subtotalValue": 259.9,
        "shippingValue": 25.5,
        "discountValue": 0,
        "additionValue": 0,
        "totalValue": 285.4,
        "service": false,
        "storage": null,
        "items": [],
        "additions": [],
        "discounts": [],
        "shippingOptions": [
          {
            "shippingTableId": 55,
            "shippingPickupPointId": 0,
            "label": "Entrega Expressa",
            "shippingValue": 25.50,
            "beginShippingTime": 1,
            "endShippingTime": 2,
            "shippingTimeType": "days",
            "selected": true,
            "details": null
          }
        ]
      }
    ],
    "errors": [],
    "isMerged": false,
    "createdAt": "2026-05-05 10:00:00",
    "updatedAt": "2026-05-05 10:50:00"
  }
}

⚠️ 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 administrativo informado não foi encontrado.
UAPPI_STORE_CART_INVALID_ORDER_ID	400	O `cartOrderId` informado não existe ou não pertence a este carrinho.
UAPPI_STORE_CART_INVALID_SHIPPING_OPTION	400	A `shippingTableId` informada não é válida para esta ordem ou não estava na última cotação.
UAPPI_STORE_CART_PICKUP_POINT_ID_IS_REQUIRED	400	A transportadora exige um ponto de retirada, mas o ID não foi enviado.
UAPPI_STORE_CART_ORDER_EXISTS	403	O carrinho já possui pedido finalizado e não permite alteração de frete.

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

Transporte e Cotizações no Admin

Visão Geral

Entidades Envolvidas

Notas e Considerações

Resiliência de Cotação

Invalidação Automática

Cotação de Frete 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

⚠️ Possíveis erros:

Seleção de Frete 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:

Nesta página

Institucional