Warehouses

Overview

The Warehouses API allows you to manage multiple storage facilities and distribution centers in your Venddor store. You can create, retrieve, update, and delete warehouses, as well as manage their delivery areas and applicable user groups for inventory allocation.

Base URL: https://www.venddor.com.br/api/2.0/warehouses

Core Warehouse Operations

GET /api/2.0/warehouses

Retrieves a list of all warehouses with support for filtering and pagination.

GET /api/2.0/warehouses/{warehouse_id}

Retrieves detailed information about a specific warehouse including delivery areas and user groups.

POST /api/2.0/warehouses

Creates a new warehouse in the system.

PUT /api/2.0/warehouses/{warehouse_id}

Updates an existing warehouse's information, delivery areas, and user groups.

DELETE /api/2.0/warehouses/{warehouse_id}

Deletes a warehouse from the system.

Warehouse Structure

Below is the complete structure of a warehouse object:

{
  "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"
}

Creating a Warehouse

Example request to create a new warehouse:

curl -X POST "https://www.venddor.com.br/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"
      }
    ]
  }'

Delivery Areas Management

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

Retrieves all delivery areas for a specific warehouse.

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

Adds a new delivery area to a warehouse.

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

Updates a specific delivery area configuration.

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

Removes a delivery area from a warehouse.

User Groups Management

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

Retrieves all user groups associated with a specific warehouse.

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

Associates a user group with a warehouse for inventory allocation.

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

Updates user group allocation settings for a warehouse.

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

Removes a user group association from a warehouse.

Note: Delivery areas define geographic regions where the warehouse can deliver products. User groups determine which customer segments have access to inventory from specific warehouses, enabling advanced inventory allocation strategies.

Best Practices

Unique Codes - Use consistent, meaningful codes for warehouse identification
Geographic Logic - Configure delivery areas based on realistic shipping zones
Priority Settings - Set appropriate priorities for warehouses and user groups
Default Warehouse - Always maintain one default warehouse as fallback
Regular Updates - Keep delivery areas and contact information updated
Coordination Management - Use latitude/longitude for precise location tracking

Tip: When setting up multiple warehouses, consider the allocation type carefully. Use "P" (priority) for flexible allocation where lower priority warehouses can serve as backup, and "E" (exclusive) when certain user groups should only receive inventory from specific warehouses.