VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa

Armazéns

Gerencie armazéns e centros de distribuição, as áreas de entrega que cada um atende e os grupos de usuários que podem receber estoque dele.

A API de armazéns permite gerenciar vários locais de armazenamento e centros de distribuição da loja. Você pode criar, consultar, atualizar e excluir armazéns, e também gerenciar as áreas de entrega e os grupos de usuários que valem para cada um na alocação de estoque.

Use-a quando o estoque estiver em mais de um lugar e você precisar dizer aonde cada lugar entrega e quais segmentos de clientes ele atende. As rotas ficam em $BASE_URL/api/2.0/warehouses, exigem uma conta de administrador e usam credenciais HTTP Basic ($EMAIL:$API_KEY). O estoque de cada armazém está na página Estoque.

Pontos principais
  • Um armazém tem status (A ativo, D desativado) e pode ser o armazém padrão (is_default Y ou N).
  • As áreas de entrega definem as regiões geográficas em que o armazém pode entregar produtos.
  • Os grupos de usuários determinam quais segmentos de clientes têm acesso ao estoque de um armazém.
  • O tipo de alocação de um grupo de usuários é P (prioridade) ou E (exclusivo).
  • Mantenha um armazém padrão como alternativa.

Como funciona

  1. Crie o armazém
    Envie a identificação, o endereço, a prioridade e o indicador de padrão, junto com as áreas de entrega e os grupos de usuários, se você já os tiver.
  2. Descreva aonde ele entrega
    Acrescente áreas de entrega por estado, cidade e faixa de CEP, cada uma com um prazo de entrega em horas.
  3. Escolha quem ele atende
    Associe grupos de usuários ao armazém, com prioridade e tipo de alocação.
  4. Carregue o estoque
    Defina a quantidade de cada produto no armazém, veja Estoque.

Conceitos principais

Estrutura do armazém

Esta é a estrutura completa de um objeto de armazém:

json
{
  "warehouse_id": "12",
  "name": "Centro de Distribuição SP",
  "code": "CD-SP-001",
  "status": "A",          // A - active, D - disabled
  "description": "Centro principal de distribuição em São Paulo",
  "address": "Rua das Indústrias, 1000",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "zipcode": "01234-567",
  "phone": "+55 11 9999-8888",
  "email": "cdsp@venddor.com.br",
  "latitude": "-23.5505",
  "longitude": "-46.6333",
  "priority": 1,           // Higher number = higher priority
  "is_default": "Y",      // Y - default warehouse, N - not default
  "shipping_delay": 2,    // Days to add to shipping time
  "min_items_in_box": 1,
  "max_items_in_box": 50,
  "company_id": "1",
  "delivery_areas": [
    {
      "area_id": "1",
      "area_name": "Grande São Paulo",
      "states": ["SP"],
      "cities": [
        "São Paulo",
        "Guarulhos",
        "Osasco",
        "Santo André"
      ],
      "zipcodes": [
        {
          "zipcode_from": "01000-000",
          "zipcode_to": "05999-999"
        },
        {
          "zipcode_from": "08000-000",
          "zipcode_to": "08999-999"
        }
      ],
      "delivery_time": 24,  // Hours for delivery
      "status": "A"
    },
    {
      "area_id": "2",
      "area_name": "Interior SP",
      "states": ["SP"],
      "cities": [
        "Campinas",
        "Ribeirão Preto",
        "Sorocaba"
      ],
      "delivery_time": 48,
      "status": "A"
    }
  ],
  "user_groups": [
    {
      "usergroup_id": "3",
      "usergroup_name": "Clientes Premium",
      "priority": 1,       // Priority for this group
      "allocation_type": "P", // P - priority, E - exclusive
      "status": "A"
    },
    {
      "usergroup_id": "1",
      "usergroup_name": "Clientes Gerais",
      "priority": 2,
      "allocation_type": "P",
      "status": "A"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-06-20T14:22:15Z"
}

Campos do armazém

warehouse_idstring
Identificador do armazém.
namestring
Nome do armazém.
codestring
Código que identifica o armazém. Use códigos consistentes e com significado.
statusstring
AD
A para ativo, D para desativado.
descriptionstring
Descrição do armazém.
addressstring
Endereço (logradouro).
citystring
Cidade.
statestring
Estado.
countrystring
Código do país.
zipcodestring
CEP.
phonestring
Telefone.
emailstring
E-mail de contato.
latitudestring
Latitude, para acompanhar a localização com precisão.
longitudestring
Longitude, para acompanhar a localização com precisão.
priorityinteger
Prioridade do armazém. Número maior significa prioridade maior.
is_defaultstring
YN
Y para o armazém padrão, N para os demais.
shipping_delayinteger
Dias somados ao prazo de envio.
min_items_in_boxinteger
Quantidade mínima de itens em uma caixa.
max_items_in_boxinteger
Quantidade máxima de itens em uma caixa.
company_idstring
Identificador da empresa.
delivery_areasarray
Áreas de entrega do armazém, veja abaixo.
user_groupsarray
Grupos de usuários associados ao armazém, veja abaixo.
created_atstring
Quando o armazém foi criado.
updated_atstring
Quando o armazém foi atualizado pela última vez.

Áreas de entrega

As áreas de entrega definem as regiões geográficas em que o armazém pode entregar produtos.

Campos da área de entrega

area_idstring
Identificador da área de entrega.
area_namestring
Nome da área.
statesarray
Estados cobertos pela área.
citiesarray
Cidades cobertas pela área.
zipcodesarray
Faixas de CEP, cada uma com zipcode_from e zipcode_to.
delivery_timeinteger
Horas para a entrega.
statusstring
AD
Status da área (o exemplo usa A).

Grupos de usuários

Os grupos de usuários determinam quais segmentos de clientes têm acesso ao estoque de determinados armazéns, o que permite estratégias avançadas de alocação de estoque.

Campos do grupo de usuários

usergroup_idstring
Identificador do grupo de usuários.
usergroup_namestring
Nome do grupo de usuários.
priorityinteger
Prioridade deste grupo.
allocation_typestring
PE
P para prioridade, E para exclusivo.
statusstring
AD
Status da associação (o exemplo usa A).

Endpoints

MétodoCaminhoFinalidadeAutenticação
GET/api/2.0/warehousesRecupera a lista de todos os armazéns, com suporte a filtros e paginação, veja abaixoAdmin
GET/api/2.0/warehouses/{warehouse_id}Recupera as informações detalhadas de um armazém, incluindo áreas de entrega e grupos de usuários, veja abaixoAdmin
POST/api/2.0/warehousesCria um novo armazém no sistema, veja abaixoAdmin
PUT/api/2.0/warehouses/{warehouse_id}Atualiza as informações, as áreas de entrega e os grupos de usuários de um armazém, veja abaixoAdmin
DELETE/api/2.0/warehouses/{warehouse_id}Exclui um armazém do sistema, veja abaixoAdmin
GET/api/2.0/warehouses/{warehouse_id}/delivery_areasRecupera todas as áreas de entrega de um armazém, veja abaixoAdmin
POST/api/2.0/warehouses/{warehouse_id}/delivery_areasAdiciona uma nova área de entrega a um armazém, veja abaixoAdmin
PUT/api/2.0/warehouses/{warehouse_id}/delivery_areas/{area_id}Atualiza a configuração de uma área de entrega, veja abaixoAdmin
DELETE/api/2.0/warehouses/{warehouse_id}/delivery_areas/{area_id}Remove uma área de entrega de um armazém, veja abaixoAdmin
GET/api/2.0/warehouses/{warehouse_id}/user_groupsRecupera todos os grupos de usuários associados a um armazém, veja abaixoAdmin
POST/api/2.0/warehouses/{warehouse_id}/user_groupsAssocia um grupo de usuários a um armazém para alocação de estoque, veja abaixoAdmin
PUT/api/2.0/warehouses/{warehouse_id}/user_groups/{usergroup_id}Atualiza as configurações de alocação de um grupo de usuários em um armazém, veja abaixoAdmin
DELETE/api/2.0/warehouses/{warehouse_id}/user_groups/{usergroup_id}Remove a associação de um grupo de usuários com um armazém, veja abaixoAdmin
GET/api/2.0/warehouses/{warehouse_id}/stockRecupera os níveis de estoque de todos os produtos de um armazém, veja EstoqueAdmin
GET/api/2.0/warehouses/{warehouse_id}/stock/{product_id}Recupera as informações de estoque de um produto em um armazém, veja EstoqueAdmin
PUT/api/2.0/warehouses/{warehouse_id}/stock/{product_id}Atualiza os níveis de estoque de um produto em um armazém, veja EstoqueAdmin

Armazéns

Listar armazéns

GET/api/2.0/warehousesAdmin

Recupera a lista de todos os armazéns, com suporte a filtros e paginação

bash
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses"

Consultar um armazém

GET/api/2.0/warehouses/{warehouse_id}Admin

Recupera as informações detalhadas de um armazém, incluindo áreas de entrega e grupos de usuários

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
bash
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12"

Criar um armazém

POST/api/2.0/warehousesAdmin

Cria um novo armazém no sistema

Corpo da requisição

namestring
Nome do armazém.
codestring
Código que identifica o armazém.
statusstring
AD
A para ativo, D para desativado.
descriptionstring
Descrição do armazém.
addressstring
Endereço (logradouro).
citystring
Cidade.
statestring
Estado.
countrystring
Código do país.
zipcodestring
CEP.
phonestring
Telefone.
emailstring
E-mail de contato.
latitudestring
Latitude.
longitudestring
Longitude.
priorityinteger
Prioridade do armazém.
is_defaultstring
YN
Indica se é o armazém padrão.
shipping_delayinteger
Dias somados ao prazo de envio.
delivery_areasarray
Áreas de entrega a criar junto com o armazém.
user_groupsarray
Grupos de usuários a associar ao armazém.

Exemplo de requisição para criar um novo armazém:

bash
curl -X POST "$BASE_URL/api/2.0/warehouses" \
  -H "Content-Type: application/json" \
  -u "$EMAIL:$API_KEY" \
  -d '{
    "name": "Centro de Distribuição RJ",
    "code": "CD-RJ-001",
    "status": "A",
    "description": "Centro de distribuição no Rio de Janeiro",
    "address": "Av. Brasil, 2000",
    "city": "Rio de Janeiro",
    "state": "RJ",
    "country": "BR",
    "zipcode": "20000-000",
    "phone": "+55 21 8888-7777",
    "email": "cdrj@venddor.com.br",
    "latitude": "-22.9068",
    "longitude": "-43.1729",
    "priority": 2,
    "is_default": "N",
    "shipping_delay": 3,
    "delivery_areas": [
      {
        "area_name": "Grande Rio",
        "states": ["RJ"],
        "cities": ["Rio de Janeiro", "Niterói", "Nova Iguaçu"],
        "delivery_time": 24,
        "status": "A"
      }
    ],
    "user_groups": [
      {
        "usergroup_id": "1",
        "priority": 1,
        "allocation_type": "P",
        "status": "A"
      }
    ]
  }'

Atualizar um armazém

PUT/api/2.0/warehouses/{warehouse_id}Admin

Atualiza as informações, as áreas de entrega e os grupos de usuários de um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém a atualizar.

O corpo leva os campos da estrutura do armazém que você quer alterar. A página original não traz um exemplo de corpo para esta rota; o exemplo abaixo usa valores da estrutura apresentada acima.

bash
curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+55 11 9999-8888",
  "priority": 1
}'

Excluir um armazém

DELETE/api/2.0/warehouses/{warehouse_id}Admin

Exclui um armazém do sistema

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém a excluir.
bash
curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12"

Gerenciamento de áreas de entrega

Listar áreas de entrega

GET/api/2.0/warehouses/{warehouse_id}/delivery_areasAdmin

Recupera todas as áreas de entrega de um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
bash
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/delivery_areas"

Adicionar uma área de entrega

POST/api/2.0/warehouses/{warehouse_id}/delivery_areasAdmin

Adiciona uma nova área de entrega a um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.

Corpo da requisição

area_namestring
Nome da área.
statesarray
Estados cobertos pela área.
citiesarray
Cidades cobertas pela área.
zipcodesarray
Faixas de CEP, com zipcode_from e zipcode_to.
delivery_timeinteger
Horas para a entrega.
statusstring
AD
Status da área.

O corpo abaixo é a área de entrega do exemplo de criação acima, enviada sozinha.

bash
curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/delivery_areas" \
  -H "Content-Type: application/json" \
  -d '{
  "area_name": "Grande Rio",
  "states": ["RJ"],
  "cities": ["Rio de Janeiro", "Niterói", "Nova Iguaçu"],
  "delivery_time": 24,
  "status": "A"
}'

Atualizar uma área de entrega

PUT/api/2.0/warehouses/{warehouse_id}/delivery_areas/{area_id}Admin

Atualiza a configuração de uma área de entrega

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
area_idintegerobrigatório
Identificador da área de entrega.

Envie os campos da área de entrega que você quer alterar.

bash
curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/delivery_areas/1" \
  -H "Content-Type: application/json" \
  -d '{"delivery_time": 48}'

Remover uma área de entrega

DELETE/api/2.0/warehouses/{warehouse_id}/delivery_areas/{area_id}Admin

Remove uma área de entrega de um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
area_idintegerobrigatório
Identificador da área de entrega a remover.
bash
curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/delivery_areas/1"

Gerenciamento de grupos de usuários

Listar grupos de usuários

GET/api/2.0/warehouses/{warehouse_id}/user_groupsAdmin

Recupera todos os grupos de usuários associados a um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
bash
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/user_groups"

Associar um grupo de usuários

POST/api/2.0/warehouses/{warehouse_id}/user_groupsAdmin

Associa um grupo de usuários a um armazém para alocação de estoque

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.

Corpo da requisição

usergroup_idstring
Identificador do grupo de usuários.
priorityinteger
Prioridade deste grupo.
allocation_typestring
PE
P para prioridade, E para exclusivo.
statusstring
AD
Status da associação.

O corpo abaixo é o grupo de usuários do exemplo de criação acima, enviado sozinho.

bash
curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/user_groups" \
  -H "Content-Type: application/json" \
  -d '{
  "usergroup_id": "1",
  "priority": 1,
  "allocation_type": "P",
  "status": "A"
}'

Atualizar a associação de um grupo de usuários

PUT/api/2.0/warehouses/{warehouse_id}/user_groups/{usergroup_id}Admin

Atualiza as configurações de alocação de um grupo de usuários em um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
usergroup_idintegerobrigatório
Identificador do grupo de usuários.
bash
curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/user_groups/1" \
  -H "Content-Type: application/json" \
  -d '{"priority": 2, "allocation_type": "E"}'

Remover a associação de um grupo de usuários

DELETE/api/2.0/warehouses/{warehouse_id}/user_groups/{usergroup_id}Admin

Remove a associação de um grupo de usuários com um armazém

Parâmetros de caminho

warehouse_idintegerobrigatório
Identificador do armazém.
usergroup_idintegerobrigatório
Identificador do grupo de usuários a remover.
bash
curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/warehouses/12/user_groups/1"
Nota

As áreas de entrega definem as regiões geográficas em que o armazém pode entregar produtos. Os grupos de usuários determinam quais segmentos de clientes têm acesso ao estoque de determinados armazéns, o que permite estratégias avançadas de alocação de estoque.

Melhores práticas

  • Códigos únicos: use códigos consistentes e com significado para identificar os armazéns.
  • Lógica geográfica: configure as áreas de entrega com base em zonas de envio realistas.
  • Prioridades: defina prioridades adequadas para armazéns e grupos de usuários.
  • Armazém padrão: mantenha sempre um armazém padrão como alternativa.
  • Atualizações regulares: mantenha as áreas de entrega e os dados de contato atualizados.
  • Coordenadas: use latitude e longitude para acompanhar a localização com precisão.
Dica

Ao configurar vários armazéns, pense bem no tipo de alocação. Use "P" (prioridade) para uma alocação flexível, em que armazéns de menor prioridade servem de reserva, e "E" (exclusivo) quando certos grupos de usuários só devem receber estoque de armazéns específicos.

Próximos passos

Estoque
Consulte e atualize o estoque de um produto em um armazém.
Métodos de envio
As opções de entrega da loja.
Anterior
Paginação de métodos de envio
Próxima
Estoque do armazém
Nesta página
  • Como funciona
  • Conceitos principais
  • Estrutura do armazém
  • Áreas de entrega
  • Grupos de usuários
  • Endpoints
  • Armazéns
  • Listar armazéns
  • Consultar um armazém
  • Criar um armazém
  • Atualizar um armazém
  • Excluir um armazém
  • Gerenciamento de áreas de entrega
  • Listar áreas de entrega
  • Adicionar uma área de entrega
  • Atualizar uma área de entrega
  • Remover uma área de entrega
  • Gerenciamento de grupos de usuários
  • Listar grupos de usuários
  • Associar um grupo de usuários
  • Atualizar a associação de um grupo de usuários
  • Remover a associação de um grupo de usuários
  • Melhores práticas
  • Próximos passos