Documentação de Faixa de CEP do Armazém

Visão Geral

O módulo de Faixa de CEP do Armazém permite que a loja controle, para um intervalo específico de CEPs, quais armazéns podem participar da cotação de frete e em qual ordem de prioridade eles devem ser considerados.

Essa configuração é opcional e atua como uma sobreposição ao fluxo padrão de cotação. Quando não existe nenhuma faixa cadastrada para o CEP de destino, a cotação segue o comportamento normal da plataforma, considerando todos os armazéns com estoque disponível e priorizando pela menor distância até o destino.

A comunicação com as funcionalidades deste módulo é controlada por escopos de permissão. A leitura de dados exige o escopo PRODUCT_STORAGE_READ, enquanto operações de escrita exigem o escopo PRODUCT_STORAGE_WRITE.

Regras de Negócio

• Sem faixa cadastrada para o CEP, o fluxo normal de cotação é mantido. Todos os armazéns com estoque disponível são considerados, priorizados pela menor distância até o destino.
• Uma faixa cadastrada sem nenhum armazém indica ausência de entrega para a região. Ao cadastrar uma faixa com storageIds vazio, a loja está informando que não há cobertura de frete para os CEPs contidos nela. Nesse caso, nenhuma opção de frete é retornada para o cliente.
• Uma faixa cadastrada com armazéns restringe e prioriza a cotação. Apenas os armazéns informados em storageIds são considerados para os CEPs contidos na faixa, e a cotação segue exatamente a ordem em que eles foram informados — em vez da priorização padrão por distância.
• Quando um CEP está contido em mais de uma faixa, a mais específica prevalece — ou seja, a que possui o menor intervalo entre o CEP inicial e o final. Isso permite manter uma faixa ampla como regra geral e criar faixas mais estreitas para exceções pontuais.
• Um armazém que atenda o pedido por completo tem prioridade sobre a ordem configurada. Mesmo com uma ordem de prioridade definida, se um único armazém entre os informados já for capaz de atender integralmente o pedido, ele é priorizado na frente dos demais. O objetivo é evitar dividir a entrega entre mais de um armazém quando isso não é necessário. A ordem configurada continua valendo para decidir a prioridade entre os armazéns quando a demanda precisar ser combinada entre mais de um.
• O CEP inicial não pode ser maior que o CEP final. Essa validação é aplicada tanto na criação quanto na atualização da faixa.
• A restrição de armazéns não garante disponibilidade de estoque. Se nenhum dos armazéns informados na faixa tiver estoque do produto solicitado, esse item pode não ser cotado, mesmo que outros armazéns da loja, fora da faixa, tenham disponibilidade.
• Alterações em uma faixa têm efeito imediato na próxima cotação realizada.

Entidades Envolvidas

• Faixa de CEP: entidade principal, com CEP inicial (initialZipcode), CEP final (finalZipcode), a lista ordenada de armazéns (storageIds) e o status de ativação (active).
• Armazém: os IDs referenciados em storageIds correspondem a registros do módulo de Armazém.

Notas e Considerações

Faixas inativas (active: false) são ignoradas na busca durante a cotação, com o mesmo efeito de não existirem — o fluxo cai para o comportamento normal ou para outra faixa ativa que também contemple o CEP.

O campo storageIds aceita array vazio deliberadamente — não é um erro de validação, é a forma de configurar "sem cobertura de frete" para uma região.

Os CEPs informados (initialZipcode, finalZipcode e o CEP de destino da cotação) devem seguir o mesmo formato — apenas números, sem hífen. Formatos diferentes podem impedir que a faixa seja corretamente identificada.

Listagem de Ranges de CEP

Descrição

Este endpoint retorna a listagem paginada das faixas de CEP cadastradas, permitindo filtrar por id, initialZipcode, finalZipcode e active, além de ordenar por id, initialZipcode, finalZipcode e createdAt.

Para realizar esta operação, o usuário deve estar autenticado e possuir o escopo de permissão PRODUCT_STORAGE_READ.

Parâmetros

Headers Obrigatórios

Parâmetros de Query

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/products/storage-zipcode-ranges?limit=10&offset=0" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "registers": [
3    {
4      "id": 5,
5      "initialZipcode": "01000000",
6      "finalZipcode": "01999999",
7      "storageIds": [12, 7, 3],
8      "active": true,
9      "createdAt": "2026-08-13 10:00:00",
10      "updatedAt": "2026-08-13 10:00:00"
11    }
12  ],
13  "pagination": {
14    "registers": 1,
15    "pages": 1
16  }
17}

Detalhe de Range de CEP

Descrição

Este endpoint retorna os dados completos de uma faixa de CEP, incluindo o CEP inicial, o CEP final, os armazéns permitidos (storageIds, na ordem de prioridade) e o status de ativação.

Para realizar esta operação, o usuário deve estar autenticado e possuir o escopo de permissão PRODUCT_STORAGE_READ.

Parâmetros

Headers Obrigatórios

Parâmetros de URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/storage-zipcode-ranges/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 5,
3  "initialZipcode": "01000000",
4  "finalZipcode": "01999999",
5  "storageIds": [12, 7, 3],
6  "active": true,
7  "createdAt": "2026-08-13 10:00:00",
8  "updatedAt": "2026-08-13 10:00:00"
9}

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

Cadastro de Range de CEP

Descrição

Este endpoint permite cadastrar faixas de CEP que restringem e ordenam quais armazéns participam da cotação de frete.

Quando o CEP de destino de uma cotação estiver dentro de uma faixa cadastrada, apenas os armazéns informados em storageIds serão considerados, e a cotação seguirá exatamente a ordem em que os IDs foram informados (em vez da ordenação padrão por distância).

Se storageIds for enviado como uma lista vazia, a loja está indicando que não há cotação de frete disponível para os CEPs daquela faixa — qualquer tentativa de cotação para um CEP dentro dela será encerrada.

Quando múltiplas faixas cadastradas puderem corresponder ao mesmo CEP, a faixa de maior precisão (menor diferença entre finalZipcode e initialZipcode) tem prioridade.

Para realizar esta operação, o usuário deve estar autenticado e possuir os escopos de permissão PRODUCT_STORAGE_READ e PRODUCT_STORAGE_WRITE.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/storage-zipcode-ranges \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "initialZipcode": "01000000",
6    "finalZipcode": "01999999",
7    "storageIds": [12, 7, 3],
8    "active": true
9  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "id": 5,
3  "initialZipcode": "01000000",
4  "finalZipcode": "01999999",
5  "storageIds": [12, 7, 3],
6  "active": true,
7  "createdAt": "2026-08-13 10:00:00",
8  "updatedAt": "2026-08-13 10:00:00"
9}

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

Atualização de Range de CEP

Descrição

Este endpoint permite atualizar uma faixa de CEP já existente, substituindo o CEP inicial, o CEP final, a lista de armazéns permitidos (storageIds) e o status de ativação.

Assim como no cadastro, enviar storageIds como uma lista vazia indica que não há cotação de frete disponível para os CEPs da faixa.

Para realizar esta operação, o usuário deve estar autenticado e possuir os escopos de permissão PRODUCT_STORAGE_READ e PRODUCT_STORAGE_WRITE.

Parâmetros

Headers Obrigatórios

Parâmetros de URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/storage-zipcode-ranges/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "initialZipcode": "01000000",
6    "finalZipcode": "01999999",
7    "storageIds": [7, 12],
8    "active": true
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 5,
3  "initialZipcode": "01000000",
4  "finalZipcode": "01999999",
5  "storageIds": [7, 12],
6  "active": true,
7  "createdAt": "2026-08-13 10:00:00",
8  "updatedAt": "2026-08-13 10:05:00"
9}

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

Remoção de Range de CEP

Descrição

Este endpoint remove definitivamente uma faixa de CEP. Após a remoção, os CEPs anteriormente cobertos por ela passam a seguir o fluxo padrão de cotação (todos os armazéns com estoque, ordenados por distância), a menos que estejam cobertos por outra faixa cadastrada.

Para realizar esta operação, o usuário deve estar autenticado e possuir os escopos de permissão PRODUCT_STORAGE_READ e PRODUCT_STORAGE_WRITE.

Parâmetros

Headers Obrigatórios

Parâmetros de URL

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/storage-zipcode-ranges/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true

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