Multi-estoque

Visão geral

Quando a funcionalidade de multi-estoque está ativa na loja, a Yep distribui o estoque de cada produto por múltiplos armazéns (loja física, depósito principal, centros de distribuição etc.). Esta página cobre as quatro interfaces da API REST relacionadas: Warehouses (cadastro de armazéns), Stockitems (estoque por warehouse, com agregação automática), Products (com stock_data.warehouses) e o impacto em Orders (warehouses por item do pedido).

Regras gerais

Convenções comuns aos endpoints de multi-estoque. Base URL nos exemplos: /api2. Endpoints protegidos exigem Authorization: Bearer {{token}} e Content-Type: application/json nos verbos POST/PATCH.

• Os endpoints fazem parte da funcionalidade de multi-estoque e herdam a autenticação OAuth, a paginação determinística e o padrão de resposta da API REST Yep.
• Listagens aceitam page, limit, include_pagination e filtros por query string ou JSON body.
• O campo warehouses aceita dois formatos: mapa {code: qty} (atalho compacto) ou lista [{code, qty}] (mais explícita; útil quando a integração trabalha com arrays).
• Quando warehouses é enviado, o estoque total agregado do produto é recalculado automaticamente pelo model do módulo. Não é necessário enviar qty separadamente.

Warehouses

Cadastro dos armazéns da loja. Por padrão, lista apenas armazéns ativos; use include_inactive=true para auditoria ou para integrações que precisam ver todos.

GET /api2/warehouses?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

GET /api2/warehouses?code=deposito_padrao
Authorization: Bearer {{token}}

{
  "success": true,
  "warehouse": {
    "warehouse_id": 1,
    "code": "deposito_padrao",
    "name": "Depósito Padrão",
    "status": 1
  }
}

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total": 4,
  "last_page": 1,
  "has_next": false,
  "warehouses": [
    {"warehouse_id": 1, "code": "deposito_padrao", "name": "Depósito Padrão", "status": 1},
    {"warehouse_id": 2, "code": "loja_sp",         "name": "Loja São Paulo",  "status": 1},
    {"warehouse_id": 3, "code": "loja_rj",         "name": "Loja Rio",        "status": 1},
    {"warehouse_id": 4, "code": "cd_norte",        "name": "CD Norte",        "status": 0}
  ]
}

Stockitems

Consulta e atualização do estoque por warehouse. A resposta inclui sempre o campo warehouses com a distribuição por armazém e o qty total agregado.

GET /api2/stockitems?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

GET /api2/stockitems?id=456
Authorization: Bearer {{token}}

GET /api2/stockitems?product_id=123
Authorization: Bearer {{token}}

GET /api2/stockitems?sku=PRODUTO-001
Authorization: Bearer {{token}}

{
  "sku": ["PRODUTO-001", "PRODUTO-002"],
  "include_pagination": true
}

{
  "success": true,
  "stockitem": {
    "item_id": 456,
    "stock_item_id": 456,
    "stock_id": 1,
    "product_id": 123,
    "sku": "PRODUTO-001",
    "name": "Produto 001",
    "qty": 15,
    "is_in_stock": 1,
    "manage_stock": 1,
    "use_config_manage_stock": 1,
    "backorders": 0,
    "min_qty": 0,
    "min_sale_qty": 1,
    "warehouses": {
      "deposito_padrao": 10,
      "loja_sp": 5
    }
  }
}

PATCH /api2/stockitems
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "id": 456,
  "warehouses": {
    "deposito_padrao": 10,
    "loja_sp": 5
  }
}

PATCH /api2/stockitems
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "sku": "PRODUTO-001",
  "warehouses": {
    "deposito_padrao": 10,
    "loja_sp": 5
  }
}

PATCH /api2/stockitems
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "product_id": 123,
  "stock_data": {
    "is_in_stock": 1,
    "manage_stock": 1,
    "warehouses": {
      "deposito_padrao": 10
    }
  }
}

PATCH /api2/stockitems
Authorization: Bearer {{token}}
Content-Type: application/json

[
  {
    "sku": "PRODUTO-001",
    "warehouses": {
      "deposito_padrao": 10
    }
  },
  {
    "sku": "PRODUTO-002",
    "warehouses": [
      {"code": "deposito_padrao", "qty": 3},
      {"code": "loja_sp", "qty": 2}
    ]
  }
]

Warehouses dentro de Produtos

Quando a funcionalidade de multi-estoque está ativa, os endpoints de Produtos passam a incluir stock_data.warehouses nas respostas, mantendo compatibilidade com a semântica de stock_data já consumida por integrações de catálogo.

GET /api2/products?type=sku&id=PRODUTO-001
Authorization: Bearer {{token}}

GET /api2/products?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

{
  "success": true,
  "product": {
    "product_id": 123,
    "sku": "PRODUTO-001",
    "name": "Produto 001",
    "stock_data": {
      "qty": 15,
      "is_in_stock": 1,
      "warehouses": {
        "deposito_padrao": 10,
        "loja_sp": 5
      }
    }
  }
}

Warehouses dentro dos itens do pedido

Quando a funcionalidade de multi-estoque está ativa, os endpoints de Pedidos incluem o campo warehouses dentro de cada item da resposta — indicando de quais armazéns cada quantidade foi reservada/separada.

GET /api2/order?id=100
Authorization: Bearer {{token}}

{
  "success": true,
  "order": {
    "order_id": 100,
    "increment_id": "100000100",
    "items": [
      {
        "item_id": 10,
        "sku": "PRODUTO-001",
        "qty_ordered": 2,
        "warehouses": {
          "deposito_padrao": 2
        }
      }
    ]
  }
}

Formas de uso suportadas

Combinações testadas e homologadas para a API de multi-estoque.

Recomendações para integração

Recomendado

• Cachear a listagem de /api2/warehouses — o cadastro muda raramente, e cada chamada de stock pode reaproveitar a lista.
• Usar o formato em lista ([{code, qty}]) quando a integração serializa dados a partir de banco relacional; usar o mapa ({code: qty}) quando os dados já vêm em forma de dicionário.
• Em sincronizações de alta volumetria, preferir o PATCH em lote — minimiza overhead de autenticação e logging.
• Ler warehouses dos itens do pedido para alimentar OMS/WMS com a informação de qual armazém atende cada linha.

Evitar

• Enviar qty total junto com warehouses — o total será sobrescrito pelo recálculo do módulo.
• Usar códigos de warehouse com caracteres não-ASCII em ambientes que serializam URL — prefira slugs (deposito_padrao em vez de depósito padrão).
• Atualizar warehouses em loop (1 PATCH por SKU) quando o lote já resolve — gera contenção no estoque agregado.

Erros comuns