Skip to content

📮 Documentação de Consulta de CEP

📋 Visão Geral

A Consulta de CEP é o recurso responsável por retornar os dados de endereço associados a um código postal, seja ele nacional (Brasil) ou internacional.

O endpoint é público — não exige Bearer token — e aceita tanto CEPs no formato com hífen (37757-000) quanto sem hífen (37757000). A normalização é feita automaticamente pelo sistema antes de qualquer consulta.

Os dados retornados incluem logradouro, bairro, cidade, estado, coordenadas geográficas e informações do país, compondo um contrato completo de endereçamento.

🔄 Fluxo Interno

A consulta segue uma cadeia de três etapas, executadas em ordem:

1. Verificação no cache interno

O sistema consulta a tabela interna de CEPs antes de acionar qualquer provedor externo.

Se o registro for encontrado e estiver dentro do prazo de 30 dias (TTL do cache), o resultado é retornado diretamente, sem chamadas externas.

Se o registro existir, mas o prazo de 30 dias tiver sido ultrapassado, o sistema aciona o provedor externo para atualizar os dados e renova o cache automaticamente.

2. Consulta via ViaCEP (Brasil)

Quando o código de país informado é BRA e o registro não está em cache (ou está desatualizado), o sistema consulta a API ViaCEP para obter os dados do CEP.

Em caso de falha no servidor do ViaCEP, o sistema utiliza os dados do cache expirado, se disponíveis, evitando interrupção de serviço.

3. Consulta via ZipCodeBase (Internacional)

Para todos os outros países, o sistema utiliza a API ZipCodeBase para localizar o código postal internacionalmente.

A chave de integração é gerenciada internamente via variável de ambiente e não é exposta ao consumidor da API.

🗃️ Entidades Envolvidas

Resultado da Consulta (ConsultZipCodeDMC)

Representa o contrato de resposta retornado ao consumidor após a resolução do CEP. Contém:

  • zipCode — código postal consultado, sempre sem hífen.
  • publicPlace — logradouro (rua, avenida, alameda etc.).
  • complement — complemento do endereço; pode ser null quando não disponível.
  • district — bairro.
  • city — cidade.
  • stateCode — código do estado no formato {sigla do país}-{sigla do estado} (por exemplo, BR-SP).
  • latitude — latitude de referência do CEP.
  • longitude — longitude de referência do CEP.
  • countryName — nome completo do país (por exemplo, BRAZIL).
  • countryCodeAlpha2 — sigla de dois caracteres do país (por exemplo, BR).
  • countryCodeAlpha3 — sigla de três caracteres do país (por exemplo, BRA).
  • ddi — código DDI do país.
  • currency — código da moeda do país.

    • 📌 Notas e Considerações

  • Hífens são removidos automaticamente: o valor 37757-000 é normalizado para 37757000 antes da consulta. O consumidor pode enviar o CEP em qualquer formato.
  • TTL de cache de 30 dias: registros com mais de 30 dias são considerados desatualizados e provocam uma nova consulta ao provedor externo, atualizando a entrada na base interna.
  • CEPs desativados: se um CEP que existia na base interna não for mais encontrado nos provedores externos, ele é marcado como desativado. Consultas subsequentes a esse CEP retornarão o erro UAPPI_INTEGRATION_SHIPPING_ZIPCODE_DISABLED.
  • Rota pública: o endpoint utiliza o middleware PublicAuth e não requer autenticação por Bearer token.
  • Coordenadas no Brasil: para CEPs nacionais consultados via ViaCEP, os campos latitude e longitude são retornados com valor 0 por limitação do provedor.

🔍 Consulta de CEP

GET /shipping/zipcode/consult/{countryCode}/{zipCode}

Retorna os dados de endereço associados a um código postal nacional ou internacional

📄 Descrição

Endpoint utilizado para consultar os dados de endereço de um código postal, informando o código do país e o CEP desejado.

O sistema verifica o cache interno antes de acionar qualquer provedor externo. Para o Brasil (BRA), utiliza a API ViaCEP; para os demais países, utiliza a API ZipCodeBase.

Esta é uma rota pública — não requer Bearer token. Hífens no CEP são removidos automaticamente pelo sistema.

📋 Parâmetros

🔗 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
countryCodestringSimCódigo do país no formato Alpha-3 (por exemplo, BRA, USA, ARG)
zipCodestringSimCódigo postal a ser consultado, com ou sem hífen (por exemplo, 01310100 ou 01310-100)

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/zipcode/consult/BRA/01310100 \
3  --header "Accept: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"zipCode": "01310100",
5		"publicPlace": "Avenida Paulista",
6		"complement": "de 612 a 1510 - lado par",
7		"district": "Bela Vista",
8		"city": "São Paulo",
9		"stateCode": "BR-SP",
10		"latitude": "0",
11		"longitude": "0",
12		"countryName": "Brasil",
13		"countryCodeAlpha2": "BR",
14		"countryCodeAlpha3": "BRA",
15		"ddi": "+55",
16		"currency": "BRL"
17	}
18}

⚠️ 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_INTEGRATION_SHIPPING_COUNTRY_NOT_FOUND404❌ O código de país informado não foi encontrado na plataforma.
UAPPI_INTEGRATION_SHIPPING_ZIPCODE_NOT_FOUND404❌ O CEP informado não foi localizado em nenhum provedor externo.
UAPPI_INTEGRATION_SHIPPING_ZIPCODE_DISABLED422❌ O CEP existe na base interna, mas foi desativado por não ser mais encontrado nos provedores externos.
UAPPI_INTEGRATION_SHIPPING_ZIPCODE_SEARCH_FAIL500❌ Falha na comunicação com o provedor externo ao tentar localizar o CEP.

Cotação de Frete

GET /publics/products/quote

Calcula opções e valores de frete para uma lista de produtos com destino específico

Descrição

Endpoint responsável por realizar a cotação de frete 🚚📦.

Funciona da seguinte forma:

  • Recebe uma lista de itens e o destino da entrega
  • Calcula os custos e prazos de envio para os produtos informados
  • Retorna as opções de frete disponíveis, permitindo ao cliente escolher a mais adequada

Parâmetros de Query

Headers Obrigatórios

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

Parâmetros de Corpo

ParâmetroTipoObrigatórioDescrição
tradePolicyIdintegerNãoID da política comercial
targetZipCodestringSimCEP de destino da entrega
targetCountryCodestringSimCódigo do país de destino (3 caracteres)
itemsarraySimArray de itens para cotação
items[].productIdintegerSimID do produto
items[].quantityintegerSimQuantidade do produto

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/publics/products/quote \
3  --data '{
4    "tradePolicyId":1,
5    "targetZipCode": "01001000",
6    "targetCountryCode": "BRA",
7    "items": [
8      "productId": 1,
9      "quantity": 3
10    ]
11  }'

✅ Resposta de Sucesso

1{
2  "quoteGroups": [
3    {
4      "quoteId": "group-1-storage-1",
5      "error": null,
6      "tradePolicyId": 1,
7      "productStorageId": 1,
8      "distance": 15.5,
9      "originZipCode": "04567890",
10      "targetZipCode": "01310100",
11      "totalPrice": 2399.80,
12      "quantityItems": 2,
13      "totalCubicVolume": 8000,
14      "totalWeight": 1.2,
15      "service": false,
16      "cargoTypeCombination": [1, 2],
17      "additionalTimeGroup": 2,
18      "storage": {
19        "id": 1,
20        "name": "Armazém Central SP",
21        "zipCode": "04567-890"
22      },
23      "items": [
24        {
25          "productId": 1234,
26          "upsellId": null,
27          "productPairOfferId": null,
28          "name": "Smartphone TechBrand"
29          "sku":"ABC123",
30          "service": false,
31          "saleWithoutStock": false,
32          "quantity": 2,
33          "productPriceRuleId": 0,
34          "productPriceRuleName": "Original",
35          "value": 1299.90,
36          "code": null,
37          "product": {
38            "id": 1234,
39            "brandId": 1234,
40            "brandName": "TopPhone,
41            "mainCategoryId": 1,
42            "mainCategoryName": "smartphone",
43            "type": "product",
44            "name": "Smartphone XYZ Pro 128GB",
45            "sku": "SMPH001",
46            "url": "/smartphone-xyz-pro-128gb",
47            "comparisonPrice":2199.99,
48            "stock":20,
49            "medias":[
50              {
51                "id": 123,
52                "type": "image",
53                "title": "",
54                "alternativeText": null,
55                "file": "\/upload\/media\/produto-media.webp",
56                "originalFile": "\/upload\/media\/produto-media.png",
57                "size": null,
58                "originalSize": null,
59                "width": null,
60                "height": null,
61                "url": null
62              }
63            ],
64            "combination":[1, 2, 3],
65            "currentAttributes":[
66              {
67                "id":123,
68                "name":"cor",
69                "value":{
70                  "id":123,
71                  "label":"azul-escuro",
72                  "image":null,
73                  "originalImage":null,
74                  "color":"#00008B",
75                  "order":1
76                }
77              }
78            ],
79            "active": true
80          },
81					"productStorages": [
82            {
83              "productStorageId": 1234, 
84              "stock": 20,
85              "zipCode": "04567890",
86              "latitude": "-12983571225721985",
87              "longitude": "-12904872198572198",
88            }
89          ],
90          "volume": {
91            "height": 15.7,
92            "width": 7.8,
93            "length": 0.8,
94            "weight": 0.195
95          },
96          "category": {
97            "id": 123,
98            "name": "tecnologia/smartphones"
99          }
100          "cargoTypeId": 1,
101          "additionalTime": 1,
102          "cubicVolumeItem": 0.0196,
103          "totalCubicVolume": 0.0196,
104          "error": null
105        }
106      ],
107      "shippingOptions": [
108        {
109          "shippingTableId": 8,
110          "integrationCode": "",
111          "externalShippingCode": "",
112          "carrierId": 0,
113          "carrierName": "",
114          "label": "Retirar na loja",
115          "value": 0,
116          "beginShippingTime": 1,
117          "endShippingTime": 1,
118          "trackingUrl": null,
119          "row": {
120            "id": 1,
121            "initialZipcode": "10000000",
122            "finalZipcode": "99999999",
123            "initialWeight": 0,
124            "finalWeight": 10,
125            "initialPrice": 0,
126            "finalPrice": 100000,
127            "beginShippingTime": 1,
128            "endShippingTime": 1,
129            "shippingValue": 0,
130            "variables": []
131          },
132          "pickups": [
133            {
134              "id": 1,
135              "type": "inner",
136              "selected": false,
137              "name": "Retirada na loja TechBrand",
138              "address": "TechBrand street",
139              "number": "1234",
140              "district": "TechBrand",
141              "city": "São Paulo",
142              "countryCode": "BRA",
143              "stateCode": "BR-SP",
144              "zipCode": "12345-123",
145              "complement": "",
146              "latitude": "-22109580918509215",
147              "longitude": "-1023598021985029185",
148              "openingHours": "9 horas am"
149            }
150          ],
151          "error": null
152        }
153      ],
154      "additionalTimeGroup":0,
155      "storage": {
156        "id": 1234,
157        "code": "1",
158        "corporateName": "TechBrand",
159        "email": "suporte@techbrand.com.br",
160        "phone": "+55123451234",
161        "tradeName": "Armazém Principal",
162        "stateCode": "BR-SP",
163        "countryCode": "BRA",
164        "document": "12345678910",
165        "zipCode": "12345678",
166        "city": "Birigui",
167        "address": "Rua das flores 123",
168        "district": "Jardim das flores 1234",
169        "number": "1234",
170        "complement": "Ao lado da praça",
171        "latitude": "-12034598159523",
172        "longitude": "-12351298578213",
173        "active": true,
174        "observation": null,
175        "tradePolicyExceptions": [1, 2, 3]
176      }
177    }
178  ],
179  "errorItems": []
180}

⚠️ 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.

⚠️ Principais erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_PRODUCT_NOT_FOUND404O produto solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_IS_INACTIVE403O solicitado está inativo.
UAPPI_STORE_PRODUCT_PRICE_NOT_FOUND404O preço do produto não foi encontrado.
UAPPI_STORE_PRODUCT_NOT_AVAILABLE_FOR_SALE403O produto não pode ser vendido pois está incompleto.
UAPPI_STORE_PRODUCT_IS_PARENT400O produto é um item pai com filhos e a operação não pode ser continuada.
UAPPI_STORE_UPSELL_NOT_FOUND404O upsell solicitado não foi encontrado.
UAPPI_STORE_UPSELL_QUANTITY_EXCEDEED400A quantidade de itens de upsell excedeu o limite.
UAPPI_STORE_PRODUCT_PAIR_OFFER_NOT_FOUND404O compre junto solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_PAIR_MISSING_IN_CART400O compre junto requer que o item complementar também esteja no carrinho.
UAPPI_STORE_STOCK_INSUFFICIENT_AVAILABLE_STOCK400A quantidade de estoque solicitada não está disponível.
UAPPI_STORE_STOCK_BELLOW_MINIMUM400O estoque do produto solicitado está abaixo do mínimo.
UAPPI_INTEGRATION_SHIPPING_ZIPCODE_NOT_FOUND404O código postal solicitado não foi encontrado.
UAPPI_STORE_ZIPCODE_RANGE_NO_COVERAGE409Não há entrega disponível para o CEP informado.

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

Institucional

;