🚚 Documentação de Fretes

📋 Visão Geral

Os Fretes representam as integrações de envio disponíveis e instaladas na plataforma — como Correios, Melhor Envio e Frenet.

Cada integração expõe um conjunto de campos de configuração que devem ser preenchidos com as credenciais e parâmetros operacionais exigidos pelo serviço de envio correspondente.

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

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

🔄 Entidades Envolvidas

Integração de Frete (Shipping)

Representa um serviço de envio disponível na loja. Cada registro contém:

id — identificador único da integração.
code — código interno da integração (ex.: "correios-api").
name — nome de exibição da integração (ex.: "Correios API").
description — descrição resumida do serviço de envio.
image — URL do ícone ou logotipo da integração.
url — site oficial do serviço de envio.
oauth — indica se a integração utiliza fluxo OAuth para autenticação.
shippingTableQuantity — quantidade de tabelas de frete configuradas para a integração.
shippingCredencialQuantity — quantidade de campos de credencial disponíveis para configuração.
orderManagement - determina se a integração possui recursos de cadastro/consulta e cancelamento de remessas;
webhook - determina se a integração possui porcessamento de webhook.

Campo de Configuração (ShippingCredential)

Representa um campo de configuração exposto por uma integração específica. Cada campo contém:

code — identificador do campo (ex.: "cartao-postagem").
title — rótulo legível do campo (ex.: "Número do Cartão de Postagem").
type — tipo do campo: string, numeric, bool ou map.
default — valor padrão do campo.
enum — lista de valores aceitos, quando aplicável.
mapKey — rótulo da chave, utilizado apenas quando type é map.
mapValue — rótulo do valor, utilizado apenas quando type é map.

📮 Consulta de CEP

O módulo de Fretes também expõe um endpoint público para consulta de código postal.

Dado um código de país (Alpha-3) e um CEP, o sistema retorna logradouro, bairro, cidade, estado, coordenadas e informações do país.

Não é necessário Bearer token — qualquer consumidor pode chamar esta rota diretamente.

1GET /api/v3/shipping/zipcode/consult/{countryCode}/{zipCode}
GET /api/v3/shipping/zipcode/consult/{countryCode}/{zipCode}

📌 Notas e Considerações

O escopo SHIPPING_READ é exigido em todas as operações de leitura deste módulo.
A listagem de fretes (GET /shipping/) suporta paginação via limit e offset. Filtros por condition (campos: name, description, code, active) e campos extras via fields (shippingTableQuantity, shippingCredencialQuantity) também estão disponíveis.
O endpoint de credenciais (GET /shipping/{shippingId}/credentials) retorna o esquema de campos da integração — não os valores salvos. Os valores preenchidos são gerenciados pelo módulo de Credenciais (/shipping/credential).
Campos do tipo map representam pares chave-valor configuráveis, retornados e salvos como um objeto {chave: valor}. Os rótulos mapKey e mapValue indicam o significado semântico de cada coluna.

📋 Listagem de Fretes

GET /shipping/

Retorna a listagem paginada de integrações de frete disponíveis na loja

📄 Descrição

Endpoint utilizado para listar as integrações de frete instaladas na loja, com suporte a paginação, filtros e campos extras.

Cada registro retornado inclui informações identificadoras da integração, como nome, código, imagem e URL.

As contagens de tabelas de frete (shippingTableQuantity) e credenciais configuradas (shippingCredencialQuantity) só são incluídas na resposta quando explicitamente solicitadas via fields.

Requer o escopo SHIPPING_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 Disponíveis (fields)

Envie o array fields no corpo da requisição para incluir dados adicionais na resposta.

Campo	Descrição
`shippingTableQuantity`	Quantidade de tabelas de frete configuradas para a integração
`shippingCredencialQuantity`	Quantidade de credenciais configuradas para a integração

🔍 Campos de Condição Disponíveis

Utilize o objeto condition no corpo da requisição para filtrar os resultados.

Campo	Tipo	Descrição
`name`	string	Nome da integração de frete
`description`	string	Descrição da integração
`code`	string	Código interno da integração
`active`	boolean	Indica se a integração está ativa

💡 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/ \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "limit": 10,
7    "offset": 0,
8    "fields": [
9      "shippingTableQuantity",
10      "shippingCredencialQuantity"
11    ]
12  }'
curl --request GET \
  --url {{MAIN_URL}}/shipping/ \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "limit": 10,
    "offset": 0,
    "fields": [
      "shippingTableQuantity",
      "shippingCredencialQuantity"
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 3,
7        "code": "transportadora-exemplo",
8        "name": "Transportadora Exemplo",
9        "description": "App para cálculo de frete e rastreio de encomendas da Transportadora Exemplo",
10        "image": "https://exemplo.com/resources/app/transportadora-exemplo/icone.png",
11        "url": "https://www.transportadora-exemplo.com.br",
12        "oauth": false,
13        "shippingTableQuantity": 2,
14        "shippingCredencialQuantity": 3
15      },
16      {
17        "id": 5,
18        "code": "envio-rapido",
19        "name": "Envio Rápido",
20        "description": "Integração para envios expressos com rastreamento em tempo real",
21        "image": "https://exemplo.com/resources/app/envio-rapido/icone.png",
22        "url": "https://www.enviorapido.com.br",
23        "oauth": true,
24        "orderManagement": false,
25				"webhook": false,
26        "shippingTableQuantity": 1,
27        "shippingCredencialQuantity": 4
28      }
29    ],
30    "pagination": {
31      "limit": 10,
32      "offset": 0,
33      "pages": 1,
34      "registers": 2
35    }
36  }
37}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 3,
        "code": "transportadora-exemplo",
        "name": "Transportadora Exemplo",
        "description": "App para cálculo de frete e rastreio de encomendas da Transportadora Exemplo",
        "image": "https://exemplo.com/resources/app/transportadora-exemplo/icone.png",
        "url": "https://www.transportadora-exemplo.com.br",
        "oauth": false,
        "shippingTableQuantity": 2,
        "shippingCredencialQuantity": 3
      },
      {
        "id": 5,
        "code": "envio-rapido",
        "name": "Envio Rápido",
        "description": "Integração para envios expressos com rastreamento em tempo real",
        "image": "https://exemplo.com/resources/app/envio-rapido/icone.png",
        "url": "https://www.enviorapido.com.br",
        "oauth": true,
        "orderManagement": false,
				"webhook": false,
        "shippingTableQuantity": 1,
        "shippingCredencialQuantity": 4
      }
    ],
    "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_USER	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_FORBBIDEN_ACCESS	403	❌ O usuário não possui a permissão `SHIPPING_READ`.

🔑 Credenciais de Frete

GET /shipping/{shippingId}/credentials

Retorna os campos de configuração disponíveis para uma integração de frete específica

📄 Descrição

Endpoint utilizado para recuperar o esquema de campos de configuração de uma integração de frete específica.

O retorno representa a estrutura de credenciais exigida pela integração — não os valores atualmente salvos. Cada campo descreve seu tipo, valor padrão e, quando aplicável, os rótulos dos mapeamentos.

Os campos do tipo map representam pares chave-valor configuráveis pelo operador da loja, retornados e salvos como um objeto {chave: valor}. Os rótulos das duas colunas vêm de mapKey e mapValue.

Formato dos campos de lista e mapeamento

Tipo	`default`	`enum`	Valor enviado na credencial
`array`	Array com os valores selecionados por padrão. Ex.: `[3, 4]`.	Objeto `{valor: rótulo}` com as opções de seleção. Ex.: `{"3": "Faturado"}`.	Array com os valores escolhidos. Ex.: `[3, 4]`. Um array vazio é permitido.
`map`	Objeto `{chave: valor}` com o mapeamento padrão. Ex.: `{"04014": "SEDEX (sem contrato)"}`.	Objeto `{valor: rótulo}` com as opções do valor, quando houver.	Objeto `{chave: valor}` com o mapeamento.

Em mapeamentos no formato de objeto, a chave identifica o item do gateway e é única, enquanto o valor pode se repetir entre chaves.

Configurações de status de remessa

Integrações com gestão de remessas retornam configurações para definir quando a remessa é criada ou cancelada e como a situação do gateway atualiza o pedido:

`code`	Tipo	Descrição
`create-order-status`	`array`	IDs dos status do pedido em que a remessa pode ser criada na integração. Vazio significa que a remessa não é criada.
`cancel-order-status`	`array`	IDs dos status do pedido em que a remessa pode ser cancelada na integração. Vazio significa que a remessa não é cancelada.
`order-status-map`	`map`	Mapeamento de status: a chave é o código do status no gateway e o valor é o ID do status do pedido na plataforma (incluindo status personalizados da loja). Situações do gateway sem mapeamento não alteram o pedido.

Os códigos de status do gateway disponíveis para o mapeamento podem ser consultados em GET /shipping/{shippingId}/order-status.

A integração precisar estar ativa no sistema para que este endpoint retorne resultado. Caso não esteja ativa ou não exista, o sistema retorna um erro 404.

Requer o escopo SHIPPING_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
`shippingId`	integer	Sim	ID único da integração de frete

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/3/credentials \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"
curl --request GET \
  --url {{MAIN_URL}}/shipping/3/credentials \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "code": "codigo-contrato",
6      "title": "Código do Contrato",
7      "type": "string",
8      "default": "0",
9      "enum": "",
10      "mapKey": "",
11      "mapValue": ""
12    },
13    {
14      "code": "servicos-disponiveis",
15      "title": "Serviços disponíveis (verifique seu contrato)",
16      "type": "map",
17      "default": {
18        "04014": "SEDEX (sem contrato)",
19        "04510": "PAC (sem contrato)"
20      },
21      "enum": "",
22      "mapKey": "Código do serviço",
23      "mapValue": "Nome exibido para o cliente"
24    },
25    {
26      "code": "ativo",
27      "title": "Integração ativa",
28      "type": "bool",
29      "default": "true",
30      "enum": "",
31      "mapKey": "",
32      "mapValue": ""
33    },
34    {
35      "code": "create-order-status",
36      "title": "Status permitidos para cadastrar a remessa na integração (vazio = não cadastra)",
37      "type": "array",
38      "default": [3, 4],
39      "enum": {
40        "2": "Pago",
41        "3": "Faturado",
42        "4": "Enviado"
43      },
44      "mapKey": "",
45      "mapValue": ""
46    },
47    {
48      "code": "order-status-map",
49      "title": "Mapeamento de status de remessa (status não mapeados não alteram o pedido)",
50      "type": "map",
51      "default": {
52        "SHIPPED": 4,
53        "IN_TRANSIT": 4,
54        "DELIVERED": 5
55      },
56      "enum": "",
57      "mapKey": "Status da integração",
58      "mapValue": "Status da plataforma"
59    }
60  ]
61}
{
  "status": true,
  "data": [
    {
      "code": "codigo-contrato",
      "title": "Código do Contrato",
      "type": "string",
      "default": "0",
      "enum": "",
      "mapKey": "",
      "mapValue": ""
    },
    {
      "code": "servicos-disponiveis",
      "title": "Serviços disponíveis (verifique seu contrato)",
      "type": "map",
      "default": {
        "04014": "SEDEX (sem contrato)",
        "04510": "PAC (sem contrato)"
      },
      "enum": "",
      "mapKey": "Código do serviço",
      "mapValue": "Nome exibido para o cliente"
    },
    {
      "code": "ativo",
      "title": "Integração ativa",
      "type": "bool",
      "default": "true",
      "enum": "",
      "mapKey": "",
      "mapValue": ""
    },
    {
      "code": "create-order-status",
      "title": "Status permitidos para cadastrar a remessa na integração (vazio = não cadastra)",
      "type": "array",
      "default": [3, 4],
      "enum": {
        "2": "Pago",
        "3": "Faturado",
        "4": "Enviado"
      },
      "mapKey": "",
      "mapValue": ""
    },
    {
      "code": "order-status-map",
      "title": "Mapeamento de status de remessa (status não mapeados não alteram o pedido)",
      "type": "map",
      "default": {
        "SHIPPED": 4,
        "IN_TRANSIT": 4,
        "DELIVERED": 5
      },
      "enum": "",
      "mapKey": "Status da integração",
      "mapValue": "Status da plataforma"
    }
  ]
}

⚠️ 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_USER	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_FORBBIDEN_ACCESS	403	❌ O usuário não possui a permissão `SHIPPING_READ`.
UAPPI_INTEGRATION_SHIPPING_NOT_FOUND	404	❌ A integração de frete informada não foi encontrada ou está inativa.
UAPPI_INTEGRATION_SHIPPING_BAD_GATEWAY_RESPONSE	502	❌ O serviço integrador não respondeu corretamente ao retornar as configurações.

🚚 Status de Remessa do Frete

GET /shipping/{shippingId}/order-status

Retorna os status de remessa disponíveis em uma integração de frete para o mapeamento com os status do pedido

📄 Descrição

Endpoint utilizado para listar os status de remessa que o gateway de frete pode informar e que estão disponíveis para o mapeamento com os status do pedido. São os status relacionados às etapas de envio e entrega da remessa.

O retorno é um objeto, em que cada chave é o código do status no gateway e cada valor é o título do status.

Integrações de frete que não possuem status de remessa retornam um objeto vazio ({}).

A integração precisa estar ativa no sistema para que este endpoint retorne resultado. Caso não esteja ativa ou não exista, o sistema retorna um erro 404.

Requer o escopo SHIPPING_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
`shippingId`	integer	Sim	ID único da integração de frete

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/3/order-status \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"
curl --request GET \
  --url {{MAIN_URL}}/shipping/3/order-status \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "COLLECTED": "Coletado",
5    "SHIPPED": "Despachado",
6    "IN_TRANSIT": "Em trânsito",
7    "TO_BE_DELIVERED": "Saiu para entrega",
8    "DELIVERY_FAILED": "Falha na entrega",
9    "DELIVERED": "Entregue"
10  }
11}
{
  "status": true,
  "data": {
    "COLLECTED": "Coletado",
    "SHIPPED": "Despachado",
    "IN_TRANSIT": "Em trânsito",
    "TO_BE_DELIVERED": "Saiu para entrega",
    "DELIVERY_FAILED": "Falha na entrega",
    "DELIVERED": "Entregue"
  }
}

⚠️ 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_INTEGRATION_SHIPPING_NOT_FOUND	404	A integração de frete informada não foi encontrada ou está inativa.
UAPPI_INTEGRATION_SHIPPING_BAD_GATEWAY_RESPONSE	502	O serviço integrador não respondeu corretamente ao retornar os status de remessa.

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 Fretes

📋 Visão Geral

🔄 Entidades Envolvidas

📮 Consulta de CEP

📌 Notas e Considerações

📋 Listagem de Fretes

📄 Descrição

📋 Parâmetros

🏷️ Headers Obrigatórios

📦 Campos Disponíveis (fields)

🔍 Campos de Condição Disponíveis

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

🔑 Credenciais de Frete

📄 Descrição

Formato dos campos de lista e mapeamento

Configurações de status de remessa

📋 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

🚚 Status de Remessa do Frete

📄 Descrição

📋 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição