Skip to content

Documentação de frete e ERP

Visão Geral

O mapeamento de frete tem a função de relacionar as modalidades de entrega da loja com as tabelas ou métodos configurados no ERP 🚚

Esse processo garante que valores, transportadoras e condições logísticas sejam corretamente identificados no momento da integração do pedido.

Assim como no pagamento, o mapeamento realiza a correspondência entre identificadores, permitindo que o ERP reconheça exatamente qual regra de frete foi aplicada na venda.

Isso assegura coerência entre a operação logística da plataforma e os controles internos do sistema de gestão, reduzindo falhas no faturamento e na expedição.

Listagem das opções de tabela de frete disponíveis

GET /erps/maps/{erpStoreCredentialId}/shipping-tables/options

Lista as opções de tabela de frete disponíveis

Descrição

Endpoint responsável por listar todas as opções de tabela de frete disponíveis no ERP.

Consulta direta ao ERP: Realiza a busca precisa das tabelas de frete vinculadas diretamente no sistema de gestão.

Dependência de credencial: A requisição depende das credenciais do ERP, sendo necessário informar o id da credencial na URL para autenticação e retorno correto dos dados 🔐

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
erpStoreCredentialIdintegerSimID único da credencial para acesso ao ERP

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/erps/maps/{erpStoreCredentialId}/shipping-tables/options \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": {
4		"externalId": {
5			"code": "externalId",
6			"title": "Forma de envio",
7			"type": "enum",
8			"default": "",
9			"enum": {
10        "987654321": "Correio Lunar",
11        "987654322": "TransRápido Log",
12        "987654323": "Retirada na Base",
13        "987654324": "NuvemPost",
14        "987654325": "Venda Corporativa",
15        "987654326": "EntregaXpress TN",
16        "987654327": "NuvemPost",
17        "987654328": "NuvemPost",
18        "987654329": "FreteMax - Correio Lunar",
19        "987654330": "envio personalizado",
20        "987654331": "Correio Lunar - Econômico",
21        "987654332-987654333": "AeroFlash Cargo via Hub Envio Fácil - Expresso",
22        "987654334-987654335": "AeroFlash Cargo via Hub Envio Fácil - e-commerce",
23        "987654336-987654337": "RodoSul Log via Hub Envio Fácil - Rodoviário",
24        "987654338-987654339": "Correio Lunar via Hub Envio Fácil - Econômico"
25			},
26			"mapKey": "",
27			"mapValue": ""
28		}
29	}
30}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código InternoCódigo HttpDescrição
UAPPI_INTEGRATION_ERP_CREDENTIAL_NOT_FOUND404A credencial de ERP solicitada não foi encontrada.
UAPPI_EXTERNAL_ERROR_NOT_MAPPED403A aplicação encontrou um erro de "não mapeado" no microsserviço external.uappi.

Listagem de mapeamento das tabelas de frete

GET /erps/maps/shipping-tables

Retorna lista de tabelas de frete mapeadas

Descrição

Endpoint responsável por retornar uma lista de tabelas de frete mapeadas no ERP.

Tabelas de frete: Representam as configurações cadastradas no sistema de gestão e utilizadas para cálculo e aplicação de frete nos pedidos.

Consulta centralizada: Permite que o sistema identifique quais tabelas estão devidamente integradas e disponíveis no ERP.

Com isso, garante-se maior consistência nas regras de frete e alinhamento entre as plataformas 🔄

Este é endpoint amplo e lista mapeamento de tabelas com qualquer ERP associado.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Campos de Condição Disponíveis

CampoTipoDescrição
erpStoreCredentialIdintegerIdentificador da credencial do ERP associado
shippingTableIdintegerIdentificador da tabela de frete
createdAtstringData de cadastro do mapeamento

Campos de Ordenação Disponíveis

CampoDescrição
createdAtData de cadastro do mapeamento

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "erpStoreCredentialId": 1,
7        "externalId": "ponto_de_entrega_1",
8        "createdAt": "2026-02-19 17:33:40",
9        "shippingTableId": 1,
10        "shippingPickupPointId": 1
11      },
12      {
13        "erpStoreCredentialId": 1,
14        "externalId": "ponto_de_entrega_2",
15        "createdAt": "2026-02-19 17:33:40",
16        "shippingTableId": 2,
17        "shippingPickupPointId": 2
18      },
19      {
20        "erpStoreCredentialId": 1,
21        "externalId": "ponto_de_entrega_3",
22        "createdAt": "2026-02-19 18:02:00",
23        "shippingTableId": 3,
24        "shippingPickupPointId": 3
25      }
26    ],
27    "pagination": {
28      "limit": 10,
29      "offset": 0,
30      "pages": 1,
31      "registers": 10
32    }
33  }
34}

Atualização do mapeamento de tabelas de fretes

PUT /erps/maps/{erpStoreCredentialId}/shipping-tables

Atualiza mapeamento de tabelas de fretes com ERP

Descrição

Endpoint responsável por atualizar o mapeamento de tabelas de frete com o ERP 🔄

Permite corrigir mapeamentos incorretos de forma rápida, evitando inconsistências entre os sistemas.

Também possibilita cadastrar um novo mapeamento em cenários de falha, garantindo a continuidade da operação e a integridade das integrações.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
erpStoreCredentialIdintegerSimIdentificador da credencial de acesso no ERP

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
mapsarray✅lista de credenciais de ERP
maps.*.shippingTableIdinteger✅Identificador da tabela de fretes
maps.*.shippingPickupPointIdinteger❌Identificador do ponto de retirada
maps.*.externalIdstring✅Identificador da tabela de frete no ERP
maps.*.actionstring✅Determina se a ação é de adição ou remoção do mapeamento (add/remove)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/erps/maps/{erpStoreCredentialId}/shipping-tables \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "maps": [
6      {
7        "shippingTableId": 1,
8        "shippingPickupPointId": 1,
9        "externalId": "987654321-987654321",
10        "action": "add"
11      }
12    ]
13  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": [
4		{
5			"externalId": "987654321-987654321",
6			"erpStoreCredentialId": 1,
7			"action": "add",
8			"shippingTableId": 1,
9			"shippingPickupPointId": null
10		}
11	]
12}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código InternoCódigo HttpDescrição
UAPPI_INTEGRATION_SHIPPING_TABLE_NOT_FOUND404As tabelas de frete solicitadas (1,2,3) não foi encontradas
UAPPI_INTEGRATION_ERP_CREDENTIAL_NOT_FOUND404A credencial de ERP solicitada não foi encontrada.

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

Institucional

;