Documentação de Armazém

Visão Geral

O módulo de Armazém é o pilar central para a gestão logística descentralizada da plataforma.

Ele representa os locais físicos reais de onde o estoque dos produtos é movimentado durante o fluxo de pedidos e cotações.

Cada armazém configurado atua como um ponto independente de saída de mercadoria.

Isso permite que o lojista gerencie complexas malhas de distribuição, envolvendo centros logísticos, filiais próprias ou depósitos de parceiros (cross-docking).

A inteligência operacional do módulo reside na capacidade de determinar a disponibilidade de estoque baseada na localização, integrando-se diretamente com os motores de cálculo de frete para otimizar prazos e custos de entrega ao consumidor final.

A comunicação com as funcionalidades deste módulo é rigorosamente 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.

Entidades Envolvidas

• Armazém (StorageDMC): Entidade principal que consolida todos os dados cadastrais, informações de contato, endereço físico completo e as coordenadas geográficas necessárias para o funcionamento logístico.
• Exceção de Política Comercial: Recurso que permite restringir a atuação de um armazém para determinados canais de venda.

Um armazém listado como exceção em uma política comercial será ignorado em todas as cotações originadas por ela.

• Geolocalização: Representada por latitude e longitude, estas coordenadas são essenciais para o funcionamento de algoritmos de roteirização e cálculo de frete baseados em distância (raio de entrega).

Notas e Considerações

Um ponto crítico para a integridade do sistema é o cache de cotação (PRODUCT_QUOTE).

Qualquer alteração estrutural em um armazém dispara a limpeza deste cache para garantir que os cálculos de frete reflitam as novas configurações logísticas.

Embora o sistema aceite latitude e longitude como valores numéricos nas requisições de entrada, o retorno entrega como strings.

Essa abordagem visa preservar a precisão decimal absoluta em diferentes plataformas clientes.

Por fim, é importante destacar que o campo active é a chave mestra da disponibilidade: armazéns inativos são sumariamente removidos de qualquer processo de cotação de frete ou reserva de estoque, sem exceções.

Listagem de Armazéns

Descrição

Este endpoint fornece uma visão completa de todos os armazéns cadastrados.

Ele permite que gestores e sistemas externos localizem e auditem a rede de estoque disponível para a loja.

A listagem facilita o entendimento da logística da plataforma, permitindo identificar quais locais estão ativos para receber pedidos e quais possuem restrições para canais de venda específicos através de políticas comerciais.

A consulta a esses dados é fundamental para garantir que a estratégia de vendas esteja alinhada com a capacidade real de entrega de cada centro de distribuição ou loja física.

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

Campos de Seleção Disponíveis (fields)

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/storages \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [],
6    "conditions": {
7      "type": "AND",
8      "conditions": []
9    },
10    "order": [],
11    "limit": 10,
12    "offset": 0
13  }'

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 1,
5      "code": "ARM-001",
6      "corporateName": "Armazém Central Ltda",
7      "email": "armazem@exemplo.com.br",
8      "phone": "(11) 99999-0001",
9      "tradeName": "Armazém Central",
10      "stateCode": "SP",
11      "countryCode": "BRA",
12      "document": "12.345.678/0001-99",
13      "zipCode": "01310-100",
14      "city": "São Paulo",
15      "address": "Av. Paulista",
16      "district": "Bela Vista",
17      "number": "1000",
18      "complement": null,
19      "latitude": "-23.5614",
20      "longitude": "-46.6565",
21      "active": true,
22      "observation": null,
23      "tradePolicyExceptions": [1, 2, 3]
24    }
25  ],
26  "pagination": {
27    "limit": 10,
28    "offset": 0,
29    "pages": 1,
30    "registers": 1
31  }
32}

Listagem Completa de Armazéns

Descrição

Este endpoint fornece um mapa simplificado e não paginado de todos os armazéns ativos cadastrados na plataforma.

Diferente da listagem principal, este recurso não aceita parâmetros de filtro, condição ou paginação — ele retorna sempre o conjunto completo de armazéns ativos.

É otimizado para uso em interfaces administrativas que precisam exibir todos os armazéns disponíveis em componentes de seleção (dropdowns, comboboxes ou modais de vínculo).

O retorno é um objeto JSON onde cada chave corresponde ao ID do armazém (como string) e o valor corresponde à razão social (corporateName) do armazém.

O acesso a este endpoint requer que o usuário autenticado possua o escopo de permissão PRODUCT_STORAGE_READ.

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/storages/all \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

Retorna um objeto onde as chaves são os IDs dos armazéns (como string) e os valores são as razões sociais correspondentes.

1{
2  "1": "Armazém Central Ltda",
3  "2": "Filial São Paulo Ltda",
4  "3": "Depósito Norte Ltda"
5}

Busca de Armazém

Descrição

Este endpoint realiza a recuperação detalhada de todas as informações vinculadas a um armazém específico.

Ele é essencial para consultas pontuais onde se deseja validar dados cadastrais, coordenadas geográficas ou o status operacional de um ponto de estoque.

A resposta deste endpoint é completa, garantindo que o integrador tenha acesso não apenas aos dados de endereço, mas também à lista de exceções de política comercial vinculadas ao armazém consultado.

Diferente da listagem geral, onde alguns campos podem ser omitidos para ganho de performance, a busca por ID entrega a entidade em seu estado máximo de detalhamento, sendo a fonte de verdade para a configuração individual do estoque.

O acesso a este endpoint é restrito e exige que o usuário autenticado possua o escopo de permissão PRODUCT_STORAGE_READ, garantindo que dados sensíveis de localização e logística sejam acessados apenas por perfis autorizados.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "code": "ARM-001",
4  "corporateName": "Armazém Central Ltda",
5  "email": "armazem@exemplo.com.br",
6  "phone": "(11) 99999-0001",
7  "tradeName": "Armazém Central",
8  "stateCode": "SP",
9  "countryCode": "BRA",
10  "document": "12.345.678/0001-99",
11  "zipCode": "01310-100",
12  "city": "São Paulo",
13  "address": "Av. Paulista",
14  "district": "Bela Vista",
15  "number": "1000",
16  "complement": null,
17  "latitude": "-23.5614",
18  "longitude": "-46.6565",
19  "active": true,
20  "observation": null,
21  "tradePolicyExceptions": [2, 5]
22}

⚠️ 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 Armazém

Descrição

Este endpoint permite cadastrar novos locais físicos de estoque, como centros de distribuição ou lojas.

Ele é essencial para organizar como os produtos serão distribuídos e entregues ao cliente final.

Ao criar um armazém, ele fica disponível para receber saldo de estoque e participar de cálculos de frete.

O sistema valida o código enviado para garantir que não existam registros duplicados no catálogo.

Informar o endereço com precisão é fundamental. O sistema utiliza a latitude e longitude para calcular a distância e o prazo de entrega, afetando diretamente o que o cliente vê no checkout da loja.

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/storages \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "code": "ARM-001",
6    "corporateName": "Armazém Central Ltda",
7    "tradeName": "Armazém Central",
8    "email": "armazem@exemplo.com.br",
9    "phone": "(11) 99999-0001",
10    "document": "12.345.678/0001-99",
11    "countryCode": "BRA",
12    "stateCode": "SP",
13    "city": "São Paulo",
14    "district": "Bela Vista",
15    "address": "Av. Paulista",
16    "number": "1000",
17    "zipCode": "01310-100",
18    "complement": null,
19    "latitude": -23.5614,
20    "longitude": -46.6565,
21    "active": true,
22    "observation": ""
23  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "id": 123,
3  "code": "ARM-001",
4  "corporateName": "Armazém Central Ltda",
5  "email": "armazem@exemplo.com.br",
6  "phone": "(11) 99999-0001",
7  "tradeName": "Armazém Central",
8  "stateCode": "SP",
9  "countryCode": "BRA",
10  "document": "12.345.678/0001-99",
11  "zipCode": "01310-100",
12  "city": "São Paulo",
13  "address": "Av. Paulista",
14  "district": "Bela Vista",
15  "number": "1000",
16  "complement": null,
17  "latitude": -23.5614,
18  "longitude": -46.6565,
19  "active": true,
20  "observation": null,
21  "tradePolicyExceptions": [1, 2, 3]
22}

⚠️ 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 Armazém

Descrição

Este endpoint permite atualizar os dados de um armazém já cadastrado.

Ele deve ser usado sempre que houver mudanças no endereço, nos dados de contato ou na disponibilidade operacional de um depósito.

Alterar o status de ativação ou a localização geográfica tem impacto imediato.

O motor de frete passa a considerar as novas informações para recalcular custos e prazos de entrega para os produtos vinculados.

O sistema valida o código do armazém para evitar que a alteração gere conflitos de identificação.

Além disso, o campo de observação deve ser enviado em todas as atualizações para confirmar ou limpar as notas existentes.

Manter esses dados atualizados é vital para que a logística da loja funcione sem erros, garantindo que o estoque seja debitado do local correto e que o frete seja calculado com precisão.

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 da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/storages/1 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "code": "ARM-001",
6    "corporateName": "Armazém Central Ltda",
7    "tradeName": "Armazém Central Atualizado",
8    "email": "armazem@exemplo.com.br",
9    "phone": "(11) 99999-0001",
10    "document": "12.345.678/0001-99",
11    "countryCode": "BRA",
12    "stateCode": "SP",
13    "city": "São Paulo",
14    "district": "Bela Vista",
15    "address": "Av. Paulista",
16    "number": "1000",
17    "zipCode": "01310-100",
18    "complement": "Bloco B",
19    "latitude": -23.5614,
20    "longitude": -46.6565,
21    "active": true,
22    "observation": "Depósito principal - Horário de funcionamento 08h às 18h"
23  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 123,
3  "code": "ARM-001",
4  "corporateName": "Armazém Central Ltda",
5  "email": "armazem@exemplo.com.br",
6  "phone": "(11) 99999-0001",
7  "tradeName": "Armazém Central Atualizado",
8  "stateCode": "SP",
9  "countryCode": "BRA",
10  "document": "12.345.678/0001-99",
11  "zipCode": "01310-100",
12  "city": "São Paulo",
13  "address": "Av. Paulista",
14  "district": "Bela Vista",
15  "number": "1000",
16  "complement": "Bloco B",
17  "latitude": -23.5614,
18  "longitude": -46.6565,
19  "active": true,
20  "observation": "Depósito principal - Horário de funcionamento 08h às 18h",
21  "tradePolicyExceptions": [1, 2, 3]
22}

⚠️ 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 Armazém

Descrição

Este endpoint permite a remoção irreversível de um armazém da plataforma.

Esta operação é crítica, pois apaga definitivamente todas as configurações cadastrais, de endereço e as exceções de política comercial associadas ao local.

Antes de realizar a exclusão, é fundamental garantir que o armazém não possua dependências ativas que possam causar inconsistências no processamento de pedidos ou no histórico de movimentações de estoque da loja.

A remoção de um armazém impacta diretamente o motor de cotação e disponibilidade, uma vez que o ponto de estoque deixará de existir para qualquer cálculo futuro de frete ou reserva de produtos no catálogo.

Por se tratar de uma operação destrutiva, o acesso é altamente controlado.

O usuário deve estar autenticado e possuir obrigatoriamente os escopos de permissão PRODUCT_STORAGE_READ e PRODUCT_STORAGE_WRITE.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/storages/1 \
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.

Atualização de Exceções de Política Comercial de Armazém

Descrição

Este endpoint permite gerenciar em lote as exceções de política comercial associadas aos armazéns da plataforma.

Cada item do array exceptions representa uma operação independente de adição (add) ou remoção (remove) de uma exceção entre um armazém e uma política comercial.

Quando um armazém possui uma exceção para determinada política comercial, ele é excluído da cotação para aquela política.

O processamento é item a item e independente: um erro em um item não interrompe o processamento dos demais.

O endpoint sempre retorna 200 OK, mesmo que alguns itens tenham falhado.

O resultado de cada item pode ser verificado pelo campo error na resposta: null indica sucesso, enquanto uma string com a mensagem de erro indica falha naquele item específico.

Qualquer alteração bem-sucedida nas exceções de política comercial dispara automaticamente a limpeza do cache de cotação (PRODUCT_QUOTE) dos armazéns afetados.

Para realizar esta operação, o usuário autenticado deve 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 PUT \
2  --url {{MAIN_URL}}/products/storages/trade-policy-exceptions \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "exceptions": [
6      {
7        "productStorageId": 1,
8        "tradePolicyId": 2,
9        "action": "add"
10      },
11      {
12        "productStorageId": 1,
13        "tradePolicyId": 99,
14        "action": "add"
15      }
16    ]
17  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1[
2  {
3    "productStorageId": 1,
4    "tradePolicyId": 2,
5    "action": "add",
6    "error": null
7  },
8  {
9    "productStorageId": 1,
10    "tradePolicyId": 99,
11    "action": "add",
12    "error": "O armazém solicitado não foi encontrado."
13  }
14]

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

Os erros abaixo são propagados no campo error de cada item da resposta — não causam falha global do endpoint.