Skip to content

🚚 Documentação de Credenciais de Frete

📋 Visão Geral

As Credenciais de Frete representam as configurações de acesso que a loja utiliza para se comunicar com os gateways de frete integrados à plataforma.

Cada credencial está vinculada a uma integração de frete (shipping) e armazena os dados necessários para autenticação e operação junto ao parceiro logístico.

Uma credencial é composta por três estruturas principais: os dados de identificação da credencial em si, o mapeamento com políticas comerciais e armazéns (tradePoliciesStorageMap), e os itens de configuração (configurationItems) — que variam de acordo com o gateway de frete.

🔄 Entidades Envolvidas

Credencial de frete (ShippingStoreCredential)

Representa a instância da credencial cadastrada na loja.

Armazena o nome da credencial e a referência ao gateway de frete ao qual pertence.

O gateway (shipping) contém informações institucionais do parceiro: código identificador, nome, descrição, logotipo, URL do site e se utiliza autenticação OAuth.

Mapeamento de políticas comerciais (tradePoliciesStorageMap)

Define quais armazéns (productStorageIds) estão vinculados à credencial por política comercial (tradePolicyId).

Esse mapeamento determina de onde os produtos serão expedidos ao calcular o frete para cada canal de venda.

O campo active controla se o vínculo está ativo. Quando false, a credencial não é utilizada para cotar frete naquela política comercial, mesmo que o mapeamento exista.

O campo shippingTableQuantity indica quantas tabelas de frete estão vinculadas ao mapeamento — útil para auditar configurações e entender a complexidade logística por política comercial.

Itens de configuração (configurationItems)

Cada gateway de frete exige um conjunto de campos específicos para autenticação e operação.

Esses campos são representados pelos itens de configuração da credencial.

Cada item possui um credentialCode (identificador do campo no gateway), um type (tipo do dado esperado) e o value (valor configurado na loja).

O campo enum lista as opções disponíveis quando o tipo é de seleção. Os campos de configuração variam por gateway — consulte os campos retornados pela API para cada integração.

📌 Notas e Considerações

  • O escopo SHIPPING_CREDENTIAL_READ é exigido em todas as operações de leitura (listagem e detalhe). Operações de escrita — criação, atualização, setup e remoção — requerem o escopo SHIPPING_CREDENTIAL_WRITE.
  • O campo credentials enviado na criação e atualização é um array livre de configurações — seu conteúdo varia conforme o gateway de frete. Consulte os configurationItems retornados no detalhe para conhecer os campos aceitos.
  • O mapeamento de políticas comerciais (setup) é gerenciado separadamente da credencial em si. Criar ou atualizar uma credencial não altera os vínculos com políticas comerciais já existentes.
  • Alterações nas credenciais e no setup invalidam o cache de cotação de frete (PRODUCT_QUOTE) automaticamente, garantindo que os preços recalculados reflitam a nova configuração.
  • A remoção de um mapeamento específico (DELETE /setup/{tradePolicyId}) exclui apenas o vínculo de uma política comercial com a credencial, sem afetar as demais. Já a remoção da credencial inteira (DELETE /{shippingCredentialId}) elimina a credencial e todos os seus mapeamentos.

📋 Listagem de Credenciais de Frete

GET /shipping/credential

Retorna todas as credenciais de frete cadastradas na loja

📄 Descrição

Endpoint utilizado para listar todas as credenciais de frete da loja, com suporte a filtros por condição e ordenação.

Requer o escopo SHIPPING_CREDENTIAL_READ.

Itens de configuração

O campo configurationItems retorna sempre vazio ([]) na listagem.

Para visualizar os itens de configuração de uma credencial, utilize o endpoint de detalhe.

Retorno

A resposta é um array direto de credenciais — não há paginação neste endpoint.

Cada item inclui os dados da credencial, o gateway de frete vinculado (shipping) e o mapeamento de políticas comerciais (tradePoliciesStorageMap).

📋 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔍 Campos de Condição Disponíveis

CampoTipoDescrição
idintegerID da credencial
shippingIdintegerID do gateway de frete vinculado
namestringNome da credencial

🔃 Campos de Ordenação Disponíveis

CampoDescrição
createdAtData de criação
updatedAtData da última atualizaçã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/credential \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "fields": [],
7    "order": [],
8    "condition": {
9      "type": "AND",
10      "conditions": []
11    }
12  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "id": 1,
6      "name": "Correios - Loja Principal",
7      "webhookUrl": "https://minhaloja.com.br/api/v3/shipping/webhook/1",
8      "shipping": {
9        "id": 3,
10        "code": "correios",
11        "name": "Correios",
12        "description": "Integração com os Correios para entrega de encomendas.",
13        "image": "https://sua-loja-uappi.com.br/images/shipping/correios.png",
14        "url": "https://www.correios.com.br",
15        "oauth": false,
16        "orderManagement": false,
17				"webhook": false,
18        "shippingTableQuantity": 2,
19        "shippingCredencialQuantity": 1
20      },
21      "tradePoliciesStorageMap": [
22        {
23          "tradePolicyId": 1,
24          "productStorageIds": [1, 2],
25          "shippingTableQuantity": 2,
26          "active": true
27        }
28      ],
29      "configurationItems": []
30    }
31  ]
32}

⚠️ 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 InternoHTTPDescrição
UAPPI_AUTH_INVALID401❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED403❌ O usuário não possui a permissão SHIPPING_CREDENTIAL_READ.

🔍 Detalhe de Credencial de Frete

GET /shipping/credential/{shippingCredentialId}

Retorna os dados completos de uma credencial de frete pelo seu ID

📄 Descrição

Endpoint utilizado para obter os dados completos de uma credencial de frete a partir do seu identificador.

Requer o escopo SHIPPING_CREDENTIAL_READ.

Itens de configuração

Diferente da listagem, este endpoint retorna o campo configurationItems populado.

Cada item representa um campo de configuração exigido pelo gateway de frete — como credenciais de acesso, contratos e parâmetros operacionais.

O campo enum de cada item indica as opções disponíveis quando o tipo aceita valores pré-definidos. Quando não há opções, retorna um array vazio.

Gateway de frete

O objeto shipping traz as informações institucionais do parceiro logístico vinculado à credencial.

Os campos shippingTableQuantity e shippingCredencialQuantity indicam, respectivamente, quantas tabelas de frete e credenciais estão associadas ao gateway.

📋 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔗 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
shippingCredentialIdinteger✅ID único da credencial de frete

💡 Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "name": "Correios - Loja Principal",
6    "webhookUrl": "https://minhaloja.com.br/api/v3/shipping/webhook/1",
7    "shipping": {
8      "id": 3,
9      "code": "correios",
10      "name": "Correios",
11      "description": "Integração com os Correios para entrega de encomendas.",
12      "image": "https://sua-loja-uappi.com.br/images/shipping/correios.png",
13      "url": "https://www.correios.com.br",
14      "oauth": false,
15      "orderManagement": false,
16			"webhook": false,
17      "shippingTableQuantity": 2,
18      "shippingCredencialQuantity": 1
19    },
20    "tradePoliciesStorageMap": [
21      {
22        "tradePolicyId": 1,
23        "productStorageIds": [1, 2],
24        "shippingTableQuantity": 2,
25        "active": true
26      }
27    ],
28    "configurationItems": [
29      {
30        "credentialCode": "username",
31        "type": "string",
32        "value": "meu-usuario-correios",
33        "enum": [],
34        "createdAt": "2026-01-10 09:00:00",
35        "updatedAt": "2026-01-10 09:00:00"
36      },
37      {
38        "credentialCode": "password",
39        "type": "password",
40        "value": "••••••••",
41        "enum": [],
42        "createdAt": "2026-01-10 09:00:00",
43        "updatedAt": "2026-01-10 09:00:00"
44      },
45      {
46        "credentialCode": "postingCard",
47        "type": "string",
48        "value": "9912345678",
49        "enum": [],
50        "createdAt": "2026-01-10 09:00:00",
51        "updatedAt": "2026-01-10 09:00:00"
52      }
53    ]
54  }
55}

⚠️ 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 InternoHTTPDescrição
UAPPI_AUTH_INVALID401❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED403❌ O usuário não possui a permissão SHIPPING_CREDENTIAL_READ.
UAPPI_AUTH_NOT_FOUND404❌ Nenhuma credencial encontrada com o ID informado.

➕ Criar Credencial de Frete

POST /shipping/credential

Cria uma nova credencial de frete vinculada a um gateway

📄 Descrição

Endpoint utilizado para cadastrar uma nova credencial de frete na loja, vinculando-a a um gateway de frete já disponível na plataforma.

Requer o escopo SHIPPING_CREDENTIAL_WRITE.

Campo credentials

O campo credentials deve conter todos os campos exigidos pelo gateway selecionado — nenhum pode ser omitido.

Cada chave representa um credentialCode do gateway, e o valor deve respeitar o tipo esperado (string, numeric, bool, enum).

Para campos do tipo enum, o valor enviado deve ser exatamente uma das opções disponíveis. As opções de cada campo podem ser consultadas no enum dos configurationItems retornados pelo endpoint de detalhe de uma credencial já cadastrada para o mesmo shippingId.

Para campos do tipo array, envie um array com os valores escolhidos entre as opções do enum (por exemplo, [3, 4]; um array vazio é permitido). Para campos do tipo map, envie um objeto {chave: valor} com o mapeamento (por exemplo, {"IN_TRANSIT": 4}), em que a chave é única e o valor pode se repetir. Os formatos de cada campo estão em GET /shipping/{shippingId}/credentials.

Para conhecer todos os campos exigidos por um gateway, consulte os configurationItems de uma credencial existente do mesmo shippingId.

Cache

Ao criar uma credencial, o cache de cotação de frete (PRODUCT_QUOTE) é invalidado automaticamente, garantindo que novas cotações reflitam a configuração recém-criada.

Resposta

Em caso de sucesso, a API retorna HTTP 201 com o objeto completo da credencial criada, no mesmo formato do endpoint de detalhe.

📋 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

📋 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
shippingIdinteger✅ID do gateway de frete ao qual a credencial será vinculada
namestring✅Nome da credencial (máximo 100 caracteres)
credentialsobject✅Campos de configuração do gateway — todos os credentialCode exigidos devem estar presentes

💡 Exemplo de Requisição

> Nota: os campos dentro de credentials variam por gateway. O exemplo abaixo utiliza a Intelipost (shippingId: 7). Consulte os configurationItems do detalhe de uma credencial existente para conhecer os campos do gateway desejado.

1curl --request POST \
2  --url {{MAIN_URL}}/shipping/credential \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "shippingId": 7,
7    "name": "Intelipost - Loja Principal",
8    "credentials": {
9      "api-key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
10      "pickup": false,
11      "tempo-adicional-frete": 1,
12      "valor-adicional-frete": 3,
13      "tipo-cotacao": "Caixa dinâmica com todos os itens"
14    }
15  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "name": "Intelipost - Loja Principal",
6    "webhookUrl": "https://minhaloja.com.br/api/v3/shipping/webhook/5",
7    "shipping": {
8      "id": 7,
9      "code": "intelipost-api",
10      "name": "Intelipost",
11      "description": "A tecnologia completa para a entrega perfeita",
12      "image": "https://wapi.webart.com.br/resources/app/intelipost-api/icone.png",
13      "url": "https://www.intelipost.com.br/",
14      "oauth": false,
15      "orderManagement": true,
16      "webhook": true,
17      "shippingTableQuantity": 0,
18      "shippingCredencialQuantity": 1
19    },
20    "tradePoliciesStorageMap": [],
21    "configurationItems": [
22      {
23        "credentialCode": "api-key",
24        "type": "string",
25        "value": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
26        "enum": "",
27        "createdAt": "2026-05-12 08:30:00",
28        "updatedAt": "2026-05-12 08:30:00"
29      },
30      {
31        "credentialCode": "pickup",
32        "type": "bool",
33        "value": "false",
34        "enum": "",
35        "createdAt": "2026-05-12 08:30:00",
36        "updatedAt": "2026-05-12 08:30:00"
37      },
38      {
39        "credentialCode": "tempo-adicional-frete",
40        "type": "numeric",
41        "value": "1",
42        "enum": "",
43        "createdAt": "2026-05-12 08:30:00",
44        "updatedAt": "2026-05-12 08:30:00"
45      },
46      {
47        "credentialCode": "valor-adicional-frete",
48        "type": "numeric",
49        "value": "3",
50        "enum": "",
51        "createdAt": "2026-05-12 08:30:00",
52        "updatedAt": "2026-05-12 08:30:00"
53      },
54      {
55        "credentialCode": "tipo-cotacao",
56        "type": "enum",
57        "value": "Caixa dinâmica com todos os itens",
58        "enum": "Caixa dinâmica com todos os itens, Caixas registradas, Caixa dinâmica com item único, Caixa dinâmica por sku, Nenhum",
59        "createdAt": "2026-05-12 08:30:00",
60        "updatedAt": "2026-05-12 08:30:00"
61      }
62    ]
63  }
64}

⚠️ 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 InternoHTTPDescrição
UAPPI_AUTH_INVALID401❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED403❌ O usuário não possui a permissão SHIPPING_CREDENTIAL_WRITE.
UAPPI_INTEGRATION_SHIPPING_NOT_FOUND400❌ O shippingId informado não corresponde a nenhum gateway ativo.
UAPPI_INTEGRATION_SHIPPING_CREDENTIAL_IS_REQUIRED400❌ Um ou mais campos obrigatórios do gateway estão ausentes em credentials.
UAPPI_INTEGRATION_SHIPPING_CREDENTIAL_TYPE_IS_INVALID400❌ O valor de um campo em credentials não corresponde ao tipo esperado pelo gateway.
UAPPI_VALIDATION_ERROR422❌ Um ou mais campos obrigatórios do corpo estão ausentes ou inválidos.

✏️ Atualizar Credencial de Frete

PUT /shipping/credential/{shippingCredentialId}

Atualiza o nome e os dados de configuração de uma credencial de frete existente

📄 Descrição

Endpoint utilizado para atualizar uma credencial de frete já cadastrada na loja.

Requer o escopo SHIPPING_CREDENTIAL_WRITE.

Gateway imutável

O gateway de frete vinculado (shippingId) não pode ser alterado após a criação da credencial.

Para trocar o gateway, é necessário remover a credencial atual e criar uma nova.

Campo credentials

Assim como na criação, todos os campos exigidos pelo gateway devem estar presentes em credentials — mesmo que o valor não tenha mudado.

O tipo de cada campo também é validado. Campos do tipo enum devem conter exatamente um dos valores disponíveis.

Campos do tipo array recebem um array com os valores escolhidos (por exemplo, [3, 4]; um array vazio é permitido) e campos do tipo map recebem um objeto {chave: valor} (por exemplo, {"IN_TRANSIT": 4}), em que a chave é única e o valor pode se repetir. Os formatos de cada campo estão em GET /shipping/{shippingId}/credentials.

Cache

Ao atualizar uma credencial, o cache de cotação de frete (PRODUCT_QUOTE) é invalidado automaticamente.

📋 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔗 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
shippingCredentialIdinteger✅ID único da credencial a ser atualizada

📋 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
namestring✅Nome da credencial (máximo 100 caracteres)
credentialsobject✅Campos de configuração do gateway — todos os credentialCode exigidos devem estar presentes

💡 Exemplo de Requisição

> Nota: os campos dentro de credentials variam por gateway. O exemplo abaixo utiliza a Intelipost (shippingId: 7). Consulte os configurationItems do detalhe da credencial para conhecer os campos exigidos.

1curl --request PUT \
2  --url {{MAIN_URL}}/shipping/credential/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Intelipost - Loja Principal (atualizado)",
7    "credentials": {
8      "api-key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
9      "pickup": false,
10      "tempo-adicional-frete": 2,
11      "valor-adicional-frete": 5,
12      "tipo-cotacao": "Caixas registradas"
13    }
14  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "name": "Intelipost - Loja Principal (atualizado)",
6    "webhookUrl": "https://minhaloja.com.br/api/v3/shipping/webhook/5",
7    "shipping": {
8      "id": 7,
9      "code": "intelipost-api",
10      "name": "Intelipost",
11      "description": "A tecnologia completa para a entrega perfeita",
12      "image": "https://wapi.webart.com.br/resources/app/intelipost-api/icone.png",
13      "url": "https://www.intelipost.com.br/",
14      "oauth": false,
15      "orderManagement": true,
16			"webhook": true,
17      "shippingTableQuantity": 0,
18      "shippingCredencialQuantity": 1
19    },
20    "tradePoliciesStorageMap": [],
21    "configurationItems": [
22      {
23        "credentialCode": "api-key",
24        "type": "string",
25        "value": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
26        "enum": "",
27        "createdAt": "2026-05-12 08:30:00",
28        "updatedAt": "2026-05-12 10:15:00"
29      },
30      {
31        "credentialCode": "pickup",
32        "type": "bool",
33        "value": "false",
34        "enum": "",
35        "createdAt": "2026-05-12 08:30:00",
36        "updatedAt": "2026-05-12 10:15:00"
37      },
38      {
39        "credentialCode": "tempo-adicional-frete",
40        "type": "numeric",
41        "value": "2",
42        "enum": "",
43        "createdAt": "2026-05-12 08:30:00",
44        "updatedAt": "2026-05-12 10:15:00"
45      },
46      {
47        "credentialCode": "valor-adicional-frete",
48        "type": "numeric",
49        "value": "5",
50        "enum": "",
51        "createdAt": "2026-05-12 08:30:00",
52        "updatedAt": "2026-05-12 10:15:00"
53      },
54      {
55        "credentialCode": "tipo-cotacao",
56        "type": "enum",
57        "value": "Caixas registradas",
58        "enum": "Caixa dinâmica com todos os itens, Caixas registradas, Caixa dinâmica com item único, Caixa dinâmica por sku, Nenhum",
59        "createdAt": "2026-05-12 08:30:00",
60        "updatedAt": "2026-05-12 10:15:00"
61      }
62    ]
63  }
64}

⚠️ 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 InternoHTTPDescrição
UAPPI_AUTH_INVALID401❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED403❌ O usuário não possui a permissão SHIPPING_CREDENTIAL_WRITE.
UAPPI_AUTH_NOT_FOUND404❌ Nenhuma credencial encontrada com o ID informado.
UAPPI_INTEGRATION_SHIPPING_CREDENTIAL_IS_REQUIRED400❌ Um ou mais campos obrigatórios do gateway estão ausentes em credentials.
UAPPI_INTEGRATION_SHIPPING_CREDENTIAL_TYPE_IS_INVALID400❌ O valor de um campo em credentials não corresponde ao tipo esperado pelo gateway.
UAPPI_VALIDATION_ERROR422❌ Um ou mais campos obrigatórios do corpo estão ausentes ou inválidos.

⚙️ Configurar Mapeamento de Credencial de Frete

PUT /shipping/credential/{shippingCredentialId}/setup

Define ou atualiza o mapeamento entre uma credencial de frete e as políticas comerciais com seus armazéns de expedição

📄 Descrição

Endpoint responsável por configurar o mapeamento de uma credencial de frete com uma ou mais políticas comerciais e seus respectivos armazéns de expedição.

Requer o escopo SHIPPING_CREDENTIAL_WRITE.

O que é o mapeamento?

O mapeamento define de onde os produtos serão expedidos ao calcular frete para um determinado canal de venda.

Cada entrada em tradePolicyStorageMap associa uma política comercial (tradePolicyId) a um conjunto de armazéns (productStorageIds) — indicando que pedidos daquela política usarão essa credencial e esses armazéns para cotação.

Operação em lote e substituição

O array tradePolicyStorageMap pode conter múltiplos mapeamentos em uma única requisição.

Cada item é processado individualmente: se o vínculo entre a credencial e a política comercial já existir, ele será atualizado; caso contrário, será criado.

Mapeamentos de outras políticas comerciais não informadas na requisição não são alterados ou removidos.

Campo active

O campo active controla se o mapeamento está habilitado para cotação.

Quando false, a credencial não será utilizada para cotar frete naquela política comercial, mesmo que o mapeamento exista. O campo productStorageIds é obrigatório apenas quando active é true.

Cache

Ao realizar o setup, o cache de cotação de frete (PRODUCT_QUOTE) é invalidado automaticamente, garantindo que novas cotações reflitam os armazéns e políticas recém-configurados.

📋 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔗 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
shippingCredentialIdinteger✅ID único da credencial de frete a ser configurada

📋 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
tradePolicyStorageMaparray✅Lista de mapeamentos de políticas comerciais com armazéns
tradePolicyStorageMap.*.tradePolicyIdinteger✅ID da política comercial a ser vinculada
tradePolicyStorageMap.*.productStorageIdsarray de integers✅ quando active: trueIDs dos armazéns de expedição para a política
tradePolicyStorageMap.*.activeboolean✅Define se o mapeamento está ativo para cotação de frete

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/shipping/credential/5/setup \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "tradePolicyStorageMap": [
7      {
8        "tradePolicyId": 1,
9        "productStorageIds": [1, 2],
10        "active": true
11      },
12      {
13        "tradePolicyId": 2,
14        "productStorageIds": [],
15        "active": false
16      }
17    ]
18  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "name": "Intelipost - Loja Principal",
6    "webhookUrl": "https://minhaloja.com.br/api/v3/shipping/webhook/5",
7    "shipping": {
8      "id": 7,
9      "code": "intelipost-api",
10      "name": "Intelipost",
11      "description": "A tecnologia completa para a entrega perfeita",
12      "image": "https://wapi.webart.com.br/resources/app/intelipost-api/icone.png",
13      "url": "https://www.intelipost.com.br/",
14      "oauth": false,
15      "orderManagement": true,
16			"webhook": true,
17      "shippingTableQuantity": 0,
18      "shippingCredencialQuantity": 1
19    },
20    "tradePoliciesStorageMap": [
21      {
22        "tradePolicyId": 1,
23        "productStorageIds": [1, 2],
24        "shippingTableQuantity": 0,
25        "active": true
26      },
27      {
28        "tradePolicyId": 2,
29        "productStorageIds": [],
30        "shippingTableQuantity": 0,
31        "active": false
32      }
33    ],
34    "configurationItems": [
35      {
36        "credentialCode": "api-key",
37        "type": "string",
38        "value": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
39        "enum": "",
40        "createdAt": "2026-05-12 08:30:00",
41        "updatedAt": "2026-05-12 08:30:00"
42      },
43      {
44        "credentialCode": "pickup",
45        "type": "bool",
46        "value": "false",
47        "enum": "",
48        "createdAt": "2026-05-12 08:30:00",
49        "updatedAt": "2026-05-12 08:30:00"
50      },
51      {
52        "credentialCode": "tempo-adicional-frete",
53        "type": "numeric",
54        "value": "1",
55        "enum": "",
56        "createdAt": "2026-05-12 08:30:00",
57        "updatedAt": "2026-05-12 08:30:00"
58      },
59      {
60        "credentialCode": "valor-adicional-frete",
61        "type": "numeric",
62        "value": "3",
63        "enum": "",
64        "createdAt": "2026-05-12 08:30:00",
65        "updatedAt": "2026-05-12 08:30:00"
66      },
67      {
68        "credentialCode": "tipo-cotacao",
69        "type": "enum",
70        "value": "Caixa dinâmica com todos os itens",
71        "enum": "Caixa dinâmica com todos os itens, Caixas registradas, Caixa dinâmica com item único, Caixa dinâmica por sku, Nenhum",
72        "createdAt": "2026-05-12 08:30:00",
73        "updatedAt": "2026-05-12 08:30:00"
74      }
75    ]
76  }
77}

⚠️ 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 InternoHTTPDescrição
UAPPI_AUTH_INVALID401❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED403❌ O usuário não possui a permissão SHIPPING_CREDENTIAL_WRITE.
UAPPI_AUTH_NOT_FOUND404❌ Nenhuma credencial encontrada com o ID informado.
UAPPI_VALIDATION_ERROR422❌ Um ou mais campos obrigatórios do corpo estão ausentes ou inválidos — como tradePolicyId faltando ou productStorageIds ausente quando active: true.

🗑️ Remover Mapeamento de Política Comercial

DELETE /shipping/credential/{shippingCredentialId}/setup/{tradePolicyId}

Remove o vínculo entre uma credencial de frete e uma política comercial específica

📄 Descrição

Endpoint responsável por remover o mapeamento entre uma credencial de frete e uma política comercial específica.

Requer o escopo SHIPPING_CREDENTIAL_WRITE.

Remoção cirúrgica

Esta operação remove apenas o vínculo da política comercial informada com a credencial.

Os demais mapeamentos da credencial com outras políticas comerciais não são afetados.

Para remover todos os mapeamentos junto com a credencial, utilize o endpoint de exclusão da credencial (DELETE /shipping/credential/{shippingCredentialId}).

Resposta

Em caso de sucesso, a API retorna true indicando que o mapeamento foi removido.

Cache

Ao remover um mapeamento, o cache de cotação de frete (PRODUCT_QUOTE) é invalidado automaticamente, garantindo que novas cotações não utilizem mais o armazém removido para aquela política comercial.

📋 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔗 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
shippingCredentialIdinteger✅ID único da credencial de frete
tradePolicyIdinteger✅ID da política comercial cujo mapeamento será removido

💡 Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ 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 InternoHTTPDescrição
UAPPI_AUTH_INVALID401❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED403❌ O usuário não possui a permissão SHIPPING_CREDENTIAL_WRITE.
UAPPI_AUTH_NOT_FOUND404❌ Nenhuma credencial ou mapeamento encontrado com os IDs informados.

🗑️ Remover Credencial de Frete

DELETE /shipping/credential/{shippingCredentialId}

Remove permanentemente uma credencial de frete e todos os seus mapeamentos com políticas comerciais

📄 Descrição

Endpoint responsável por remover permanentemente uma credencial de frete da loja.

Requer o escopo SHIPPING_CREDENTIAL_WRITE.

Remoção em cascata

Ao remover uma credencial, todos os seus mapeamentos com políticas comerciais (tradePoliciesStorageMap) são excluídos automaticamente.

Para remover apenas o vínculo com uma política comercial específica sem excluir a credencial, utilize o endpoint DELETE /shipping/credential/{shippingCredentialId}/setup/{tradePolicyId}.

Resposta

A API retorna data: true quando a credencial foi removida com sucesso.

Caso o ID informado não corresponda a nenhuma credencial da loja, a resposta será data: false — sem lançar erro.

Cache

Ao remover a credencial, o cache de cotação de frete (PRODUCT_QUOTE) é invalidado automaticamente, garantindo que novas cotações não utilizem mais a configuração removida.

📋 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔗 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
shippingCredentialIdinteger✅ID único da credencial de frete a ser removida

💡 Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

ℹ️ Credencial não encontrada

Quando o ID informado não corresponde a nenhuma credencial da loja, a API retorna data: false — sem lançar erro HTTP.

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

⚠️ 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 InternoHTTPDescrição
UAPPI_AUTH_INVALID401❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED403❌ O usuário não possui a permissão SHIPPING_CREDENTIAL_WRITE.

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

Institucional

;