📦 Documentação de Tabelas de Frete

📋 Visão Geral

As Tabelas de Frete são os registros centrais da logística da loja.

Cada tabela define uma opção de envio disponível no checkout, vinculada a uma integração de frete e, opcionalmente, a uma transportadora específica.

Uma tabela contém as linhas de cálculo — faixas de CEP, peso e preço com seus respectivos valores e prazos — além de um conjunto de configurações que determinam como o sistema aplica e calcula o frete para cada pedido.

Todas as operações exigem autenticação via Bearer token no cabeçalho Authorization.

1GET /api/v3/shipping/table
2Authorization: Bearer SEU_TOKEN_AQUI
GET /api/v3/shipping/table
Authorization: Bearer SEU_TOKEN_AQUI

🔄 Entidades Envolvidas

Tabela de Frete (ShippingTable)

Representa a opção de envio configurada na loja. Cada registro contém:

id — identificador único da tabela.
shippingId — ID da integração de frete (ex.: Correios, Jadlog, Frenet) à qual a tabela pertence.
externalShippingCode — código externo da tabela, proveniente da integração de frete.
name — nome interno de identificação da tabela (máximo 255 caracteres). Usado no painel administrativo.
label — rótulo público exibido no checkout para o comprador (máximo 255 caracteres).
trackingUrl — URL de rastreio do envio. Campo opcional.
active — flag booleana que indica se a tabela está ativa e disponível para cotação.
createdAt e updatedAt — datas de criação e atualização do registro.

Integração (shipping)

Objeto aninhado que representa a integração de frete associada à tabela. Contém id, code, name, description, image, url e oauth.

Transportadora (carrier)

Objeto aninhado opcional (ShippingCarrierDMC) com dados da transportadora vinculada à tabela.

Credencial (credential)

Objeto aninhado opcional (SimpleShippingCredentialDMC) referenciando a credencial de autenticação usada pela integração.

Configurações da Tabela (setting)

Objeto ShippingTableSettings que define as regras de cálculo e aplicação da tabela:

type — tipo de cálculo: value (valor fixo por faixa) ou formula (cálculo por expressão matemática).
cubingFactor — fator de cubagem aplicado ao peso do produto.
consideredWeight — peso a ser considerado no cálculo: cart-weight (peso real do carrinho), cubic-weight (peso cubado) ou max-weight (o maior entre os dois).
useAbove — valor mínimo do carrinho para a tabela ser aplicada.
useBelow — valor máximo do carrinho para a tabela ser aplicada.
additionalTime — dias adicionais ao prazo base da tabela.
additionalPercentage — percentual adicional aplicado ao valor do frete calculado.
formula — expressão de cálculo utilizada quando type é formula.
formulaVariable — lista de variáveis disponíveis na fórmula.
useCargoType — habilita a filtragem por tipo de carga (modal de transporte).
allowProductsWithoutCargoType — quando useCargoType está ativo, permite incluir no cálculo produtos sem tipo de carga definido.
cargoTypes — lista de IDs dos tipos de carga aceitos pela tabela.
useStorage — habilita a filtragem por armazém de origem.
storages — lista de IDs dos armazéns considerados.
useTradePolicy — habilita a filtragem por política comercial (canal de venda).
tradePolicies — mapa de ID de política comercial para boolean indicando se está habilitada.

Pontos de Retirada (pickup)

Array de objetos PickupPointDMC representando os pontos de retirada vinculados à tabela. Cada ponto contém dados de endereço, telefone, coordenadas e horário de funcionamento.

Linhas da Tabela (ShippingTableRow)

Cada linha representa uma faixa de cálculo da tabela. Campos:

id — identificador da linha.
initialZipcode / finalZipcode — faixa de CEP (máximo 100 caracteres cada).
initialWeight / finalWeight — faixa de peso em quilogramas.
initialPrice / finalPrice — faixa de valor do carrinho.
beginShippingTime / endShippingTime — prazo de entrega em dias (de/até).
shippingValue — valor do frete para a faixa.
variables — array de variáveis nomeadas usadas em fórmulas de cálculo.

Listagem simplificada (/all)

O endpoint GET /all retorna um mapa simples de id => nome de todas as tabelas cadastradas na loja, sem paginação. Ideal para popular dropdowns e seletores no painel administrativo.

📌 Notas e Considerações

O escopo SHIPPING_OPTION_READ é exigido em todas as operações de leitura. Operações de escrita — criação, atualização, configuração e remoção — requerem adicionalmente o escopo SHIPPING_OPTION_WRITE.
As operações de criação (POST) retornam status HTTP 201; a atualização de configurações (PUT /settings) também retorna 201. Demais atualizações retornam 200.
As operações de escrita sobre tabelas disparam o middleware CacheCleaner:PRODUCT_QUOTE, que invalida o cache de cotações de frete. Isso garante que novas cotações reflitam imediatamente as alterações na tabela.
A importação de arquivo CSV aceita arquivos de até 16 MB (16000 KB). Os parâmetros replaceAll e replaceRows controlam o comportamento de substituição das linhas existentes.
O download de tabela exportada é realizado em dois passos: primeiro solicita-se a exportação via POST .../file/export, que retorna uma downloadKey; em seguida, acessa-se GET /shipping/table/download/{downloadKey} — este último endpoint não exige autenticação.
O endpoint GET .../file/example retorna um arquivo CSV com o cabeçalho das colunas exigidas pela tabela, útil para preparar arquivos de importação.
O campo storageIds, tradePolicyIds e cargoTypeIds no objeto de resposta da tabela consolidam os IDs dos vínculos ativos nas configurações da tabela.

📋 Listagem de Tabelas de Frete

GET /shipping/table

Retorna a listagem paginada de tabelas de frete cadastradas na loja

📄 Descrição

Endpoint utilizado para listar as tabelas de frete cadastradas na loja, com suporte a paginação, filtros e ordenação.

Cada registro retornado inclui os dados completos da tabela, incluindo informações da integração de frete e da transportadora vinculada.

Requer o escopo SHIPPING_OPTION_READ.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔍 Campos de Condição Disponíveis

Campo	Tipo	Descrição
name	string	Nome interno da tabela
active	boolean	Status de ativação da tabela

🔃 Campos de Ordenação Disponíveis

Campo	Descrição
id	ID da tabela
name	Nome da tabela
createdAt	Data de criação

💡 Exemplo de Requisição

> Nota: esta API aceita corpo JSON em requisições GET, seguindo a convenção da plataforma. Utilize o header Content-Type: application/json e envie os parâmetros no corpo da requisição.

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/table \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "fields": [
7        "shippingIntegration",
8        "shippingPickupPoint",
9        "settingTable",
10        "shippingCarrier",
11        "storages",
12        "cargoTypes"
13    ],
14    "limit": 10,
15    "offset": 0
16  }'
curl --request GET \
  --url {{MAIN_URL}}/shipping/table \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "fields": [
        "shippingIntegration",
        "shippingPickupPoint",
        "settingTable",
        "shippingCarrier",
        "storages",
        "cargoTypes"
    ],
    "limit": 10,
    "offset": 0
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "shippingId": 3,
8        "externalShippingCode": "PAC",
9        "name": "PAC Nacional",
10        "label": "Entrega Econômica",
11        "trackingUrl": "https://rastreamento.correios.com.br",
12        "active": true,
13        "createdAt": "2025-02-10 08:00:00",
14        "updatedAt": "2025-04-20 10:30:00",
15        "carrier": {
16          "id": 2,
17          "code": "correios",
18          "name": "Correios",
19          "corporateName": "Empresa Brasileira de Correios e Telégrafos",
20          "email": "atendimento@correios.com.br",
21          "phone": "(61) 3003-0100",
22          "document": "34.028.316/0001-03",
23          "addresses": [],
24          "shippingTableIds": [1],
25          "createdAt": "2025-01-15 10:00:00",
26          "updatedAt": "2025-03-20 08:30:00"
27        },
28        "shipping": {
29          "id": 3,
30          "code": "correios",
31          "name": "Correios",
32          "description": "Integração com os Correios",
33          "image": "https://cdn.uappi.com.br/correios.png",
34          "url": "https://www.correios.com.br",
35          "oauth": false
36        },
37        "credential": {
38          "id": 1,
39          "name": "Credencial Correios Produção"
40        },
41        "setting": {
42          "cubingFactor": 300,
43          "consideredWeight": "max-weight",
44          "useCargoType": false,
45          "allowProductsWithoutCargoType": false,
46          "type": "value",
47          "useAbove": 0,
48          "useBelow": 0,
49          "additionalTime": 2,
50          "additionalPercentage": 0,
51          "formula": null,
52          "formulaVariable": null,
53          "createdAt": "2025-02-10 08:00:00",
54          "updatedAt": "2025-04-20 10:30:00"
55        },
56        "pickup": [
57          {
58            "id": 1,
59            "name": "Loja Centro",
60            "phone": "(11) 3000-1234",
61            "address": "Rua das Flores",
62            "number": "200",
63            "district": "Centro",
64            "city": "São Paulo",
65            "countryCode": "BR",
66            "stateCode": "SP",
67            "zipCode": "01310-100",
68            "complement": "Loja A",
69            "latitude": "-23.561684",
70            "longitude": "-46.655981",
71            "openingHours": "Seg-Sex 09h-18h",
72            "active": true,
73            "linkedShippingTables": [1]
74          }
75        ],
76        "storageIds": [1],
77        "tradePolicyIds": [1],
78        "cargoTypeIds": [2]
79      },
80      {
81        "id": 2,
82        "shippingId": 3,
83        "externalShippingCode": "SEDEX",
84        "name": "SEDEX Expresso",
85        "label": "Entrega Expressa",
86        "trackingUrl": "https://rastreamento.correios.com.br",
87        "active": true,
88        "createdAt": "2025-02-11 09:15:00",
89        "updatedAt": "2025-04-21 11:00:00",
90        "carrier": null,
91        "shipping": {
92          "id": 3,
93          "code": "correios",
94          "name": "Correios",
95          "description": "Integração com os Correios",
96          "image": "https://cdn.uappi.com.br/correios.png",
97          "url": "https://www.correios.com.br",
98          "oauth": false
99        },
100        "credential": null,
101        "setting": {
102          "cubingFactor": 0,
103          "consideredWeight": "cart-weight",
104          "useCargoType": false,
105          "allowProductsWithoutCargoType": false,
106          "type": "value",
107          "useAbove": 0,
108          "useBelow": 0,
109          "additionalTime": 0,
110          "additionalPercentage": 0,
111          "formula": null,
112          "formulaVariable": null,
113          "createdAt": "2025-02-11 09:15:00",
114          "updatedAt": "2025-04-21 11:00:00"
115        },
116        "pickup": [],
117        "storageIds": [],
118        "tradePolicyIds": null,
119        "cargoTypeIds": []
120      }
121    ],
122    "pagination": {
123      "limit": 10,
124      "offset": 0,
125      "pages": 1,
126      "registers": 2
127    }
128  }
129}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 1,
        "shippingId": 3,
        "externalShippingCode": "PAC",
        "name": "PAC Nacional",
        "label": "Entrega Econômica",
        "trackingUrl": "https://rastreamento.correios.com.br",
        "active": true,
        "createdAt": "2025-02-10 08:00:00",
        "updatedAt": "2025-04-20 10:30:00",
        "carrier": {
          "id": 2,
          "code": "correios",
          "name": "Correios",
          "corporateName": "Empresa Brasileira de Correios e Telégrafos",
          "email": "atendimento@correios.com.br",
          "phone": "(61) 3003-0100",
          "document": "34.028.316/0001-03",
          "addresses": [],
          "shippingTableIds": [1],
          "createdAt": "2025-01-15 10:00:00",
          "updatedAt": "2025-03-20 08:30:00"
        },
        "shipping": {
          "id": 3,
          "code": "correios",
          "name": "Correios",
          "description": "Integração com os Correios",
          "image": "https://cdn.uappi.com.br/correios.png",
          "url": "https://www.correios.com.br",
          "oauth": false
        },
        "credential": {
          "id": 1,
          "name": "Credencial Correios Produção"
        },
        "setting": {
          "cubingFactor": 300,
          "consideredWeight": "max-weight",
          "useCargoType": false,
          "allowProductsWithoutCargoType": false,
          "type": "value",
          "useAbove": 0,
          "useBelow": 0,
          "additionalTime": 2,
          "additionalPercentage": 0,
          "formula": null,
          "formulaVariable": null,
          "createdAt": "2025-02-10 08:00:00",
          "updatedAt": "2025-04-20 10:30:00"
        },
        "pickup": [
          {
            "id": 1,
            "name": "Loja Centro",
            "phone": "(11) 3000-1234",
            "address": "Rua das Flores",
            "number": "200",
            "district": "Centro",
            "city": "São Paulo",
            "countryCode": "BR",
            "stateCode": "SP",
            "zipCode": "01310-100",
            "complement": "Loja A",
            "latitude": "-23.561684",
            "longitude": "-46.655981",
            "openingHours": "Seg-Sex 09h-18h",
            "active": true,
            "linkedShippingTables": [1]
          }
        ],
        "storageIds": [1],
        "tradePolicyIds": [1],
        "cargoTypeIds": [2]
      },
      {
        "id": 2,
        "shippingId": 3,
        "externalShippingCode": "SEDEX",
        "name": "SEDEX Expresso",
        "label": "Entrega Expressa",
        "trackingUrl": "https://rastreamento.correios.com.br",
        "active": true,
        "createdAt": "2025-02-11 09:15:00",
        "updatedAt": "2025-04-21 11:00:00",
        "carrier": null,
        "shipping": {
          "id": 3,
          "code": "correios",
          "name": "Correios",
          "description": "Integração com os Correios",
          "image": "https://cdn.uappi.com.br/correios.png",
          "url": "https://www.correios.com.br",
          "oauth": false
        },
        "credential": null,
        "setting": {
          "cubingFactor": 0,
          "consideredWeight": "cart-weight",
          "useCargoType": false,
          "allowProductsWithoutCargoType": false,
          "type": "value",
          "useAbove": 0,
          "useBelow": 0,
          "additionalTime": 0,
          "additionalPercentage": 0,
          "formula": null,
          "formulaVariable": null,
          "createdAt": "2025-02-11 09:15:00",
          "updatedAt": "2025-04-21 11:00:00"
        },
        "pickup": [],
        "storageIds": [],
        "tradePolicyIds": null,
        "cargoTypeIds": []
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 2
    }
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_OPTION_READ`.

📄 Listagem Simplificada de Tabelas de Frete

GET /shipping/table/all

Retorna o mapa simplificado de todas as tabelas de frete cadastradas na loja, sem paginação

📄 Descrição

Endpoint utilizado para obter um mapa simples de id => nome de todas as tabelas de frete disponíveis na loja, sem paginação.

Ideal para popular dropdowns e seletores no painel administrativo com custo mínimo de resposta.

Requer o escopo SHIPPING_OPTION_READ.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/table/all \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"
curl --request GET \
  --url {{MAIN_URL}}/shipping/table/all \
  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "1": "PAC Nacional",
5    "2": "SEDEX Expresso",
6    "3": "Transportadora Rodoviária Sul"
7  }
8}
{
  "status": true,
  "data": {
    "1": "PAC Nacional",
    "2": "SEDEX Expresso",
    "3": "Transportadora Rodoviária Sul"
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_OPTION_READ`.

🔍 Detalhe de Tabela de Frete

GET /shipping/table/{shippingTableId}

Retorna os dados completos de uma tabela de frete específica, incluindo configurações, pontos de retirada e vínculos

📄 Descrição

Endpoint utilizado para obter os dados completos de uma tabela de frete, incluindo sua integração, transportadora, credencial, configurações de cálculo, pontos de retirada vinculados e IDs de armazéns, políticas comerciais e tipos de carga.

Requer o escopo SHIPPING_OPTION_READ.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/table/1 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"
curl --request GET \
  --url {{MAIN_URL}}/shipping/table/1 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "shippingId": 3,
6    "externalShippingCode": "PAC",
7    "name": "PAC Nacional",
8    "label": "Entrega Econômica",
9    "trackingUrl": "https://rastreamento.correios.com.br",
10    "active": true,
11    "createdAt": "2025-02-10 08:00:00",
12    "updatedAt": "2025-04-20 10:30:00",
13    "carrier": {
14      "id": 2,
15      "name": "Correios Transportes"
16    },
17    "shipping": {
18      "id": 3,
19      "code": "correios",
20      "name": "Correios",
21      "description": "Integração com os Correios",
22      "image": "https://cdn.uappi.com.br/correios.png",
23      "url": "https://www.correios.com.br",
24      "oauth": false
25    },
26    "credential": {
27      "id": 5,
28      "name": "Credencial Principal Correios"
29    },
30    "setting": {
31      "type": "value",
32      "cubingFactor": 300,
33      "consideredWeight": "max-weight",
34      "useAbove": 0,
35      "useBelow": 9999.99,
36      "additionalTime": 1,
37      "additionalPercentage": 0,
38      "formula": null,
39      "formulaVariable": null,
40      "useCargoType": true,
41      "allowProductsWithoutCargoType": false,
42      "cargoTypes": [1, 2],
43      "useStorage": true,
44      "storages": [10, 11],
45      "useTradePolicy": false,
46      "tradePolicies": {},
47      "createdAt": "2025-02-10 08:00:00",
48      "updatedAt": "2025-04-20 10:30:00"
49    },
50    "pickup": [
51      {
52        "id": 7,
53        "name": "Loja Centro SP",
54        "phone": "(11) 3000-0000",
55        "address": "Av. Paulista",
56        "number": "1000",
57        "district": "Bela Vista",
58        "city": "São Paulo",
59        "countryCode": "BR",
60        "stateCode": "SP",
61        "zipCode": "01310-100",
62        "complement": "Loja 5",
63        "latitude": "-23.5613",
64        "longitude": "-46.6558",
65        "openingHours": "Seg-Sex 09h-18h",
66        "active": true,
67        "linkedShippingTables": [1]
68      }
69    ],
70    "storageIds": [10, 11],
71    "tradePolicyIds": [],
72    "cargoTypeIds": [1, 2]
73  }
74}
{
  "status": true,
  "data": {
    "id": 1,
    "shippingId": 3,
    "externalShippingCode": "PAC",
    "name": "PAC Nacional",
    "label": "Entrega Econômica",
    "trackingUrl": "https://rastreamento.correios.com.br",
    "active": true,
    "createdAt": "2025-02-10 08:00:00",
    "updatedAt": "2025-04-20 10:30:00",
    "carrier": {
      "id": 2,
      "name": "Correios Transportes"
    },
    "shipping": {
      "id": 3,
      "code": "correios",
      "name": "Correios",
      "description": "Integração com os Correios",
      "image": "https://cdn.uappi.com.br/correios.png",
      "url": "https://www.correios.com.br",
      "oauth": false
    },
    "credential": {
      "id": 5,
      "name": "Credencial Principal Correios"
    },
    "setting": {
      "type": "value",
      "cubingFactor": 300,
      "consideredWeight": "max-weight",
      "useAbove": 0,
      "useBelow": 9999.99,
      "additionalTime": 1,
      "additionalPercentage": 0,
      "formula": null,
      "formulaVariable": null,
      "useCargoType": true,
      "allowProductsWithoutCargoType": false,
      "cargoTypes": [1, 2],
      "useStorage": true,
      "storages": [10, 11],
      "useTradePolicy": false,
      "tradePolicies": {},
      "createdAt": "2025-02-10 08:00:00",
      "updatedAt": "2025-04-20 10:30:00"
    },
    "pickup": [
      {
        "id": 7,
        "name": "Loja Centro SP",
        "phone": "(11) 3000-0000",
        "address": "Av. Paulista",
        "number": "1000",
        "district": "Bela Vista",
        "city": "São Paulo",
        "countryCode": "BR",
        "stateCode": "SP",
        "zipCode": "01310-100",
        "complement": "Loja 5",
        "latitude": "-23.5613",
        "longitude": "-46.6558",
        "openingHours": "Seg-Sex 09h-18h",
        "active": true,
        "linkedShippingTables": [1]
      }
    ],
    "storageIds": [10, 11],
    "tradePolicyIds": [],
    "cargoTypeIds": [1, 2]
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_OPTION_READ`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.

➕ Criar Tabela de Frete

POST /shipping/table

Permite criar uma nova tabela de frete na loja

📄 Descrição

Endpoint responsável por criar uma nova tabela de frete na loja. Após a criação, o cache de cotações de frete (PRODUCT_QUOTE) é invalidado automaticamente pelo middleware CacheCleaner.

Requer os escopos SHIPPING_OPTION_READ e SHIPPING_OPTION_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo da requisição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação do usuário

📝 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
name	string	✅ Sim	Nome interno da tabela (máximo 255 caracteres)
label	string	✅ Sim	Rótulo público exibido no checkout (máximo 255 caracteres)
active	boolean	✅ Sim	Define se a tabela está ativa para cotação
shippingCarrierId	integer	❌ Não	ID da transportadora a vincular à tabela
trackingUrl	string	❌ Não	URL para rastreamento do envio

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/shipping/table \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "PAC Nacional",
7    "label": "Entrega Econômica",
8    "active": true,
9    "shippingCarrierId": 2,
10    "trackingUrl": "https://rastreamento.exemplo.com.br"
11  }'
curl --request POST \
  --url {{MAIN_URL}}/shipping/table \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "PAC Nacional",
    "label": "Entrega Econômica",
    "active": true,
    "shippingCarrierId": 2,
    "trackingUrl": "https://rastreamento.exemplo.com.br"
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "shippingId": 3,
6    "externalShippingCode": "",
7    "name": "PAC Nacional",
8    "label": "Entrega Econômica",
9    "trackingUrl": "https://rastreamento.exemplo.com.br",
10    "active": true,
11    "createdAt": "2026-05-18 14:00:00",
12    "updatedAt": "2026-05-18 14:00:00",
13    "carrier": {
14      "id": 2,
15      "name": "Transportadora Exemplo"
16    },
17    "shipping": {
18      "id": 3,
19      "code": "correios",
20      "name": "Correios",
21      "description": "Integração com os Correios",
22      "image": "https://cdn.uappi.com.br/correios.png",
23      "url": "https://www.correios.com.br",
24      "oauth": false
25    },
26    "credential": null,
27    "setting": null,
28    "pickup": null,
29    "storageIds": null,
30    "tradePolicyIds": null,
31    "cargoTypeIds": null
32  }
33}
{
  "status": true,
  "data": {
    "id": 5,
    "shippingId": 3,
    "externalShippingCode": "",
    "name": "PAC Nacional",
    "label": "Entrega Econômica",
    "trackingUrl": "https://rastreamento.exemplo.com.br",
    "active": true,
    "createdAt": "2026-05-18 14:00:00",
    "updatedAt": "2026-05-18 14:00:00",
    "carrier": {
      "id": 2,
      "name": "Transportadora Exemplo"
    },
    "shipping": {
      "id": 3,
      "code": "correios",
      "name": "Correios",
      "description": "Integração com os Correios",
      "image": "https://cdn.uappi.com.br/correios.png",
      "url": "https://www.correios.com.br",
      "oauth": false
    },
    "credential": null,
    "setting": null,
    "pickup": null,
    "storageIds": null,
    "tradePolicyIds": null,
    "cargoTypeIds": null
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui o escopo `SHIPPING_OPTION_WRITE`.
UAPPI_VALIDATION_ERROR	422	❌ Campos obrigatórios ausentes ou com formato inválido (`name`, `label`, `active`).

✏️ Atualizar Tabela de Frete

PUT /shipping/table/{shippingTableId}

Atualiza os dados cadastrais de uma tabela de frete existente

📄 Descrição

Endpoint responsável por atualizar os dados cadastrais de uma tabela de frete identificada por shippingTableId. Após a atualização, o cache de cotações de frete (PRODUCT_QUOTE) é invalidado automaticamente pelo middleware CacheCleaner.

Requer os escopos SHIPPING_OPTION_READ e SHIPPING_OPTION_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo da requisição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação do usuário

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete a ser atualizada

📝 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
name	string	✅ Sim	Nome interno da tabela (máximo 255 caracteres)
label	string	✅ Sim	Rótulo público exibido no checkout (máximo 255 caracteres)
active	boolean	✅ Sim	Define se a tabela está ativa para cotação
shippingCarrierId	integer	❌ Não	ID da transportadora a vincular à tabela
trackingUrl	string	❌ Não	URL para rastreamento do envio

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/shipping/table/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "PAC Nacional Atualizado",
7    "label": "Entrega Econômica",
8    "active": true,
9    "shippingCarrierId": 2,
10    "trackingUrl": "https://rastreamento.exemplo.com.br"
11  }'
curl --request PUT \
  --url {{MAIN_URL}}/shipping/table/5 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "PAC Nacional Atualizado",
    "label": "Entrega Econômica",
    "active": true,
    "shippingCarrierId": 2,
    "trackingUrl": "https://rastreamento.exemplo.com.br"
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "shippingId": 3,
6    "externalShippingCode": "PAC",
7    "name": "PAC Nacional Atualizado",
8    "label": "Entrega Econômica",
9    "trackingUrl": "https://rastreamento.exemplo.com.br",
10    "active": true,
11    "createdAt": "2026-05-18 14:00:00",
12    "updatedAt": "2026-05-18 15:30:00",
13    "carrier": {
14      "id": 2,
15      "name": "Transportadora Exemplo"
16    },
17    "shipping": {
18      "id": 3,
19      "code": "correios",
20      "name": "Correios",
21      "description": "Integração com os Correios",
22      "image": "https://cdn.uappi.com.br/correios.png",
23      "url": "https://www.correios.com.br",
24      "oauth": false
25    },
26    "credential": null,
27    "setting": null,
28    "pickup": null,
29    "storageIds": null,
30    "tradePolicyIds": null,
31    "cargoTypeIds": null
32  }
33}
{
  "status": true,
  "data": {
    "id": 5,
    "shippingId": 3,
    "externalShippingCode": "PAC",
    "name": "PAC Nacional Atualizado",
    "label": "Entrega Econômica",
    "trackingUrl": "https://rastreamento.exemplo.com.br",
    "active": true,
    "createdAt": "2026-05-18 14:00:00",
    "updatedAt": "2026-05-18 15:30:00",
    "carrier": {
      "id": 2,
      "name": "Transportadora Exemplo"
    },
    "shipping": {
      "id": 3,
      "code": "correios",
      "name": "Correios",
      "description": "Integração com os Correios",
      "image": "https://cdn.uappi.com.br/correios.png",
      "url": "https://www.correios.com.br",
      "oauth": false
    },
    "credential": null,
    "setting": null,
    "pickup": null,
    "storageIds": null,
    "tradePolicyIds": null,
    "cargoTypeIds": null
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui o escopo `SHIPPING_OPTION_WRITE`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.
UAPPI_VALIDATION_ERROR	422	❌ Campos obrigatórios ausentes ou com formato inválido (`name`, `label`, `active`).

🗑️ Remover Tabela de Frete

DELETE /shipping/table/{shippingTableId}

Remove permanentemente uma tabela de frete existente na loja

📄 Descrição

Endpoint responsável por remover permanentemente uma tabela de frete, identificada pelo shippingTableId na URL.

A remoção é permanente e não pode ser desfeita. Quando bem-sucedida, o campo data da resposta retorna true. Após a remoção, o cache de cotações de frete (PRODUCT_QUOTE) é invalidado automaticamente pelo middleware CacheCleaner.

Requer os escopos SHIPPING_OPTION_READ e SHIPPING_OPTION_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação do usuário

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete a ser removida

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/shipping/table/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"
curl --request DELETE \
  --url {{MAIN_URL}}/shipping/table/5 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}
{
  "status": true,
  "data": true
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui o escopo `SHIPPING_OPTION_WRITE`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.

⚙️ Atualizar Configurações da Tabela de Frete

PUT /shipping/table/{shippingTableId}/settings

Define ou atualiza as configurações de cálculo e aplicação de uma tabela de frete

📄 Descrição

Endpoint responsável por definir ou atualizar as configurações de cálculo de uma tabela de frete. As configurações determinam como o sistema aplica e calcula o frete para cada pedido: tipo de cálculo, peso considerado, faixa de aplicação, vínculos com armazéns, tipos de carga e políticas comerciais.

Após a atualização, o cache de cotações de frete (PRODUCT_QUOTE) é invalidado automaticamente pelo middleware CacheCleaner.

Requer os escopos SHIPPING_OPTION_READ e SHIPPING_OPTION_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo da requisição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação do usuário

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete

📝 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
type	string	✅ Sim	Tipo de cálculo: `value` (faixa de valor) ou `formula` (expressão matemática)
consideredWeight	string	✅ Sim	Peso usado no cálculo: `cart-weight`, `cubic-weight` ou `max-weight`
useAbove	numeric	✅ Sim	Valor mínimo do carrinho para aplicar a tabela
useBelow	numeric	✅ Sim	Valor máximo do carrinho para aplicar a tabela
additionalTime	integer	✅ Sim	Dias adicionais ao prazo base
additionalPercentage	numeric	✅ Sim	Percentual adicional sobre o valor calculado
useCargoType	boolean	✅ Sim	Habilita filtragem por tipo de carga
useStorage	boolean	✅ Sim	Habilita filtragem por armazém
useTradePolicy	boolean	✅ Sim	Habilita filtragem por política comercial
cubingFactor	numeric	❌ Não	Fator de cubagem para o peso
formula	string	⚠️ Condicional	Obrigatório quando `type` é `formula`
allowProductsWithoutCargoType	boolean	⚠️ Condicional	Obrigatório quando `useCargoType` é `true`
cargoTypes	array de integers	⚠️ Condicional	Obrigatório quando `useCargoType` é `true`. IDs dos tipos de carga aceitos
storages	array de integers	⚠️ Condicional	Obrigatório quando `useStorage` é `true`. IDs dos armazéns considerados
tradePolicies	objeto	⚠️ Condicional	Obrigatório quando `useTradePolicy` é `true`. Mapa `{id: boolean}` de políticas

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/shipping/table/5/settings \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "type": "value",
7    "cubingFactor": 300,
8    "consideredWeight": "max-weight",
9    "useAbove": 0,
10    "useBelow": 9999.99,
11    "additionalTime": 1,
12    "additionalPercentage": 0,
13    "useCargoType": true,
14    "allowProductsWithoutCargoType": false,
15    "cargoTypes": [1, 2],
16    "useStorage": true,
17    "storages": [10, 11],
18    "useTradePolicy": false,
19    "tradePolicies": {}
20  }'
curl --request PUT \
  --url {{MAIN_URL}}/shipping/table/5/settings \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "value",
    "cubingFactor": 300,
    "consideredWeight": "max-weight",
    "useAbove": 0,
    "useBelow": 9999.99,
    "additionalTime": 1,
    "additionalPercentage": 0,
    "useCargoType": true,
    "allowProductsWithoutCargoType": false,
    "cargoTypes": [1, 2],
    "useStorage": true,
    "storages": [10, 11],
    "useTradePolicy": false,
    "tradePolicies": {}
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "type": "value",
5    "cubingFactor": 300,
6    "consideredWeight": "max-weight",
7    "useAbove": 0,
8    "useBelow": 9999.99,
9    "additionalTime": 1,
10    "additionalPercentage": 0,
11    "formula": null,
12    "formulaVariable": null,
13    "useCargoType": true,
14    "allowProductsWithoutCargoType": false,
15    "cargoTypes": [1, 2],
16    "useStorage": true,
17    "storages": [10, 11],
18    "useTradePolicy": false,
19    "tradePolicies": {},
20    "createdAt": "2025-02-10 08:00:00",
21    "updatedAt": "2026-05-18 15:45:00"
22  }
23}
{
  "status": true,
  "data": {
    "type": "value",
    "cubingFactor": 300,
    "consideredWeight": "max-weight",
    "useAbove": 0,
    "useBelow": 9999.99,
    "additionalTime": 1,
    "additionalPercentage": 0,
    "formula": null,
    "formulaVariable": null,
    "useCargoType": true,
    "allowProductsWithoutCargoType": false,
    "cargoTypes": [1, 2],
    "useStorage": true,
    "storages": [10, 11],
    "useTradePolicy": false,
    "tradePolicies": {},
    "createdAt": "2025-02-10 08:00:00",
    "updatedAt": "2026-05-18 15:45:00"
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui o escopo `SHIPPING_OPTION_WRITE`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.
UAPPI_VALIDATION_ERROR	422	❌ Campos obrigatórios ausentes, valores inválidos ou condicionais não satisfeitos (ex.: `type` inválido, `formula` ausente quando `type=formula`).

📋 Listagem de Linhas da Tabela de Frete

GET /shipping/table/{shippingTableId}/file

Retorna a listagem paginada das linhas de cálculo de uma tabela de frete

📄 Descrição

Endpoint utilizado para listar as linhas de cálculo de uma tabela de frete com suporte a paginação. Cada linha representa uma faixa de CEP, peso e preço com seu respectivo valor de frete e prazo de entrega.

Requer o escopo SHIPPING_OPTION_READ.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete

💡 Exemplo de Requisição

> Nota: esta API aceita corpo JSON em requisições GET, seguindo a convenção da plataforma. Utilize o header Content-Type: application/json e envie os parâmetros no corpo da requisição.

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/table/5/file \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "limit": 10,
7    "offset": 0
8  }'
curl --request GET \
  --url {{MAIN_URL}}/shipping/table/5/file \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "limit": 10,
    "offset": 0
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 101,
7        "initialZipcode": "01000-000",
8        "finalZipcode": "09999-999",
9        "initialWeight": 0,
10        "finalWeight": 5,
11        "initialPrice": 0,
12        "finalPrice": 500,
13        "beginShippingTime": 3,
14        "endShippingTime": 5,
15        "shippingValue": 18.90,
16        "variables": []
17      },
18      {
19        "id": 102,
20        "initialZipcode": "01000-000",
21        "finalZipcode": "09999-999",
22        "initialWeight": 5.01,
23        "finalWeight": 15,
24        "initialPrice": 0,
25        "finalPrice": 500,
26        "beginShippingTime": 3,
27        "endShippingTime": 5,
28        "shippingValue": 32.50,
29        "variables": []
30      }
31    ],
32    "pagination": {
33      "limit": 10,
34      "offset": 0,
35      "pages": 1,
36      "registers": 2
37    }
38  }
39}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 101,
        "initialZipcode": "01000-000",
        "finalZipcode": "09999-999",
        "initialWeight": 0,
        "finalWeight": 5,
        "initialPrice": 0,
        "finalPrice": 500,
        "beginShippingTime": 3,
        "endShippingTime": 5,
        "shippingValue": 18.90,
        "variables": []
      },
      {
        "id": 102,
        "initialZipcode": "01000-000",
        "finalZipcode": "09999-999",
        "initialWeight": 5.01,
        "finalWeight": 15,
        "initialPrice": 0,
        "finalPrice": 500,
        "beginShippingTime": 3,
        "endShippingTime": 5,
        "shippingValue": 32.50,
        "variables": []
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 2
    }
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_OPTION_READ`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.

📥 Download de Arquivo de Exemplo da Tabela de Frete

GET /shipping/table/{shippingTableId}/file/example

Retorna um arquivo CSV com o cabeçalho das colunas exigidas pela tabela de frete

📄 Descrição

Endpoint que gera e retorna um arquivo CSV de exemplo contendo apenas o cabeçalho com as colunas exigidas pela tabela de frete. Útil para preparar arquivos de importação com o formato correto esperado pela API.

A resposta é um download direto do arquivo com o nome shipping-table-example.csv.

Requer o escopo SHIPPING_OPTION_READ.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/table/5/file/example \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --output shipping-table-example.csv
curl --request GET \
  --url {{MAIN_URL}}/shipping/table/5/file/example \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --output shipping-table-example.csv

✅ Resposta de Sucesso

HTTP Status: 200 OK

Headers de resposta:

Header	Valor
`Content-Type`	application/octet-stream
`Content-Disposition`	attachment; filename="shipping-table-example.csv"

Conteúdo do arquivo (exemplo):

1initialZipcode,finalZipcode,initialWeight,finalWeight,initialPrice,finalPrice,beginShippingTime,endShippingTime,shippingValue
initialZipcode,finalZipcode,initialWeight,finalWeight,initialPrice,finalPrice,beginShippingTime,endShippingTime,shippingValue

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_OPTION_READ`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.

📤 Exportar Tabela de Frete

POST /shipping/table/{shippingTableId}/file/export

Solicita a exportação da tabela de frete e retorna uma chave para download do arquivo gerado

📄 Descrição

Endpoint responsável por solicitar a exportação de uma tabela de frete. A resposta retorna uma downloadKey que deve ser utilizada para fazer o download do arquivo exportado via GET /shipping/table/download/{downloadKey}.

O download via downloadKey não exige autenticação.

Requer os escopos SHIPPING_OPTION_READ e SHIPPING_OPTION_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete a ser exportada

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/shipping/table/5/file/export \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"
curl --request POST \
  --url {{MAIN_URL}}/shipping/table/5/file/export \
  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "downloadKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.abc123xyz"
5  }
6}
{
  "status": true,
  "data": {
    "downloadKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.abc123xyz"
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui o escopo `SHIPPING_OPTION_WRITE`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.

📥 Importar Arquivo de Tabela de Frete

POST /shipping/table/{shippingTableId}/file/import

Importa um arquivo CSV com as linhas de cálculo para uma tabela de frete

📄 Descrição

Endpoint responsável por importar um arquivo CSV contendo as linhas de cálculo de uma tabela de frete. Os parâmetros replaceAll e replaceRows controlam como as linhas existentes serão tratadas durante a importação.

O arquivo deve estar no formato CSV (text/csv) e ter no máximo 16 MB (16.000 KB). Use o endpoint GET .../file/example para obter o modelo de arquivo com as colunas corretas.

Após a importação, o cache de cotações de frete (PRODUCT_QUOTE) é invalidado automaticamente pelo middleware CacheCleaner.

Requer os escopos SHIPPING_OPTION_READ e SHIPPING_OPTION_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	multipart/form-data	Tipo de conteúdo para envio de arquivo
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação do usuário

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete

📝 Parâmetros do Corpo (multipart/form-data)

Parâmetro	Tipo	Obrigatório	Descrição
file	file (text/csv)	✅ Sim	Arquivo CSV com as linhas da tabela (máximo 16 MB)
replaceAll	boolean	✅ Sim	Quando `true`, substitui todas as linhas existentes pelas do arquivo
replaceRows	boolean	✅ Sim	Quando `true`, substitui as linhas existentes que tiverem correspondência no arquivo

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/shipping/table/5/file/import \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --form "file=@/caminho/para/tabela-frete.csv" \
5  --form "replaceAll=false" \
6  --form "replaceRows=true"
curl --request POST \
  --url {{MAIN_URL}}/shipping/table/5/file/import \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --form "file=@/caminho/para/tabela-frete.csv" \
  --form "replaceAll=false" \
  --form "replaceRows=true"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}
{
  "status": true,
  "data": true
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui o escopo `SHIPPING_OPTION_WRITE`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.
UAPPI_VALIDATION_ERROR	422	❌ O arquivo é obrigatório, deve ser CSV e ter no máximo 16 MB. Os campos `replaceAll` e `replaceRows` são obrigatórios e devem ser booleanos.

💾 Salvar Linhas da Tabela de Frete

PUT /shipping/table/{shippingTableId}/file

Salva ou atualiza individualmente as linhas de cálculo de uma tabela de frete

📄 Descrição

Endpoint responsável por salvar ou atualizar individualmente as linhas de cálculo de uma tabela de frete. Aceita um array de até 100 linhas por requisição.

Linhas com id existente são atualizadas; linhas sem id (ou com id igual a 0) são criadas. Após a operação, o cache de cotações de frete (PRODUCT_QUOTE) é invalidado automaticamente pelo middleware CacheCleaner.

Requer os escopos SHIPPING_OPTION_READ e SHIPPING_OPTION_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo da requisição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação do usuário

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete

📝 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
rows	array	✅ Sim	Lista de linhas a salvar (máximo 100)
rows[].initialZipcode	string	✅ Sim	CEP inicial da faixa (máximo 100 caracteres)
rows[].finalZipcode	string	✅ Sim	CEP final da faixa (máximo 100 caracteres)
rows[].initialWeight	numeric	✅ Sim	Peso inicial da faixa em kg
rows[].finalWeight	numeric	✅ Sim	Peso final da faixa em kg
rows[].initialPrice	numeric	✅ Sim	Valor mínimo do carrinho para a faixa
rows[].finalPrice	numeric	✅ Sim	Valor máximo do carrinho para a faixa
rows[].beginShippingTime	integer	✅ Sim	Prazo inicial de entrega em dias
rows[].endShippingTime	integer	✅ Sim	Prazo final de entrega em dias
rows[].shippingValue	numeric	✅ Sim	Valor do frete para a faixa
rows[].variables	array	❌ Não	Variáveis para fórmulas (máximo 20 por linha)
rows[].variables[].name	string	⚠️ Condicional	Nome da variável (obrigatório se `variables` enviado)
rows[].variables[].value	numeric	⚠️ Condicional	Valor da variável (obrigatório se `variables` enviado)

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/shipping/table/5/file \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "rows": [
7      {
8        "initialZipcode": "01000-000",
9        "finalZipcode": "09999-999",
10        "initialWeight": 0,
11        "finalWeight": 5,
12        "initialPrice": 0,
13        "finalPrice": 500,
14        "beginShippingTime": 3,
15        "endShippingTime": 5,
16        "shippingValue": 18.90,
17        "variables": []
18      },
19      {
20        "initialZipcode": "10000-000",
21        "finalZipcode": "19999-999",
22        "initialWeight": 0,
23        "finalWeight": 5,
24        "initialPrice": 0,
25        "finalPrice": 500,
26        "beginShippingTime": 5,
27        "endShippingTime": 8,
28        "shippingValue": 24.50,
29        "variables": []
30      }
31    ]
32  }'
curl --request PUT \
  --url {{MAIN_URL}}/shipping/table/5/file \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "rows": [
      {
        "initialZipcode": "01000-000",
        "finalZipcode": "09999-999",
        "initialWeight": 0,
        "finalWeight": 5,
        "initialPrice": 0,
        "finalPrice": 500,
        "beginShippingTime": 3,
        "endShippingTime": 5,
        "shippingValue": 18.90,
        "variables": []
      },
      {
        "initialZipcode": "10000-000",
        "finalZipcode": "19999-999",
        "initialWeight": 0,
        "finalWeight": 5,
        "initialPrice": 0,
        "finalPrice": 500,
        "beginShippingTime": 5,
        "endShippingTime": 8,
        "shippingValue": 24.50,
        "variables": []
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "id": 101,
6      "initialZipcode": "01000-000",
7      "finalZipcode": "09999-999",
8      "initialWeight": 0,
9      "finalWeight": 5,
10      "initialPrice": 0,
11      "finalPrice": 500,
12      "beginShippingTime": 3,
13      "endShippingTime": 5,
14      "shippingValue": 18.90,
15      "variables": []
16    },
17    {
18      "id": 102,
19      "initialZipcode": "10000-000",
20      "finalZipcode": "19999-999",
21      "initialWeight": 0,
22      "finalWeight": 5,
23      "initialPrice": 0,
24      "finalPrice": 500,
25      "beginShippingTime": 5,
26      "endShippingTime": 8,
27      "shippingValue": 24.50,
28      "variables": []
29    }
30  ]
31}
{
  "status": true,
  "data": [
    {
      "id": 101,
      "initialZipcode": "01000-000",
      "finalZipcode": "09999-999",
      "initialWeight": 0,
      "finalWeight": 5,
      "initialPrice": 0,
      "finalPrice": 500,
      "beginShippingTime": 3,
      "endShippingTime": 5,
      "shippingValue": 18.90,
      "variables": []
    },
    {
      "id": 102,
      "initialZipcode": "10000-000",
      "finalZipcode": "19999-999",
      "initialWeight": 0,
      "finalWeight": 5,
      "initialPrice": 0,
      "finalPrice": 500,
      "beginShippingTime": 5,
      "endShippingTime": 8,
      "shippingValue": 24.50,
      "variables": []
    }
  ]
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui o escopo `SHIPPING_OPTION_WRITE`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.
UAPPI_VALIDATION_ERROR	422	❌ Campos obrigatórios ausentes, tipos inválidos ou array `rows` excede o limite de 100 itens.

🗑️ Remover Linhas da Tabela de Frete

DELETE /shipping/table/{shippingTableId}/file

Remove permanentemente linhas de cálculo específicas de uma tabela de frete

📄 Descrição

Endpoint responsável por remover permanentemente linhas de cálculo de uma tabela de frete a partir de seus IDs. Aceita um array de até 100 IDs por requisição.

A remoção é permanente e não pode ser desfeita. Após a operação, o cache de cotações de frete (PRODUCT_QUOTE) é invalidado automaticamente pelo middleware CacheCleaner.

Requer os escopos SHIPPING_OPTION_READ e SHIPPING_OPTION_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo da requisição
`Authorization`	Bearer SEU_TOKEN_AQUI	Token de autenticação do usuário

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅ Sim	ID da tabela de frete

📝 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
ids	array de integers	✅ Sim	IDs das linhas a serem removidas (máximo 100)

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/shipping/table/5/file \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "ids": [101, 102, 103]
7  }'
curl --request DELETE \
  --url {{MAIN_URL}}/shipping/table/5/file \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "ids": [101, 102, 103]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}
{
  "status": true,
  "data": true
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui o escopo `SHIPPING_OPTION_WRITE`.
UAPPI_NOT_FOUND	404	❌ A tabela de frete informada não foi encontrada.
UAPPI_VALIDATION_ERROR	422	❌ O campo `ids` é obrigatório, deve ser um array de inteiros e não pode exceder 100 itens.

📥 Download de Tabela de Frete Exportada

GET /shipping/table/download/{downloadKey}

Realiza o download do arquivo de tabela de frete previamente exportado, a partir de uma chave temporária

📄 Descrição

Endpoint utilizado para fazer o download do arquivo de uma tabela de frete exportada. A downloadKey é obtida previamente ao chamar POST /shipping/table/{shippingTableId}/file/export.

Este endpoint não exige autenticação. A chave de download é temporária e deve ser utilizada logo após a exportação.

📋 Parâmetros

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
downloadKey	string	✅ Sim	Chave temporária de download obtida via exportação

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/table/download/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.abc123xyz \
3  --output tabela-frete-exportada.csv
curl --request GET \
  --url {{MAIN_URL}}/shipping/table/download/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.abc123xyz \
  --output tabela-frete-exportada.csv

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta é o conteúdo binário do arquivo exportado (CSV), com os cabeçalhos adequados para download.

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_NOT_FOUND	404	❌ A chave de download não foi encontrada ou já expirou.

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

📦 Documentação de Tabelas de Frete

📋 Visão Geral

🔄 Entidades Envolvidas

📌 Notas e Considerações

📋 Listagem de Tabelas de Frete

📄 Descrição

📋 Parâmetros

🏷️ Headers Obrigatórios

🔍 Campos de Condição Disponíveis

🔃 Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

📄 Listagem Simplificada de Tabelas de Frete

📄 Descrição

📋 Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

🔍 Detalhe de Tabela de Frete

📄 Descrição

📋 Parâmetros

🏷️ Headers Obrigatórios

🔑 Parâmetros da URL

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

➕ Criar Tabela de Frete

📄 Descrição