> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vinmake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Warehouse & Inventory

> Logistics, stock lots, outbound allocation, and delivery

# Warehouse & Inventory

This domain tracks every physical unit from the moment it enters the building to the moment it ships. **Logistics** handles inbound receipts and shipments; **Stock** holds the truth — lots at locations with a full ledger; **Warehouse Outbound** allocates and dispatches finished goods; and **Delivery Notes** document what left the dock. Every posting reflects into the [Finindex](/finindex/accounting/overview) GL.

## Flow

```mermaid theme={null}
flowchart LR
  IS[Inbound Shipment] --> GR[Goods Receipt]
  GR --> Lot[Stock Lots @ Locations]
  Lot --> Issue[Issue to Production]
  Lot --> FG[Finished Goods]
  FG --> OB[Outbound Order]
  OB --> Alloc[Allocate]
  Alloc --> DN[Delivery Note]
  DN --> Ship[Dispatch / Ship]
  GR -.inventory GL.-> Fin[Finindex]
  Ship -.COGS / AR.-> Fin
```

## Inbound to outbound

```mermaid theme={null}
sequenceDiagram
  participant Sup as Supplier
  participant Log as Logistics
  participant Stock as Stock
  participant WH as Warehouse Outbound
  participant Cust as Customer
  Sup->>Log: POST /logistics/inbound-receipts
  Log->>Log: POST /logistics/inbound-receipts/{id}/post
  Log->>Stock: stock lot created @ location
  Stock-->>Fin: inventory GL posting (Finindex)
  WH->>WH: POST /warehouse-outbound/orders
  WH->>Stock: POST /warehouse-outbound/orders/{id}/allocate
  Stock-->>WH: lots reserved
  WH->>Cust: POST /warehouse-outbound/orders/{id}/dispatch
  WH->>WH: POST /delivery-notes
  WH-->>Fin: COGS + AR posting (Finindex)
```

## Logistics

Inbound receipts bring goods in; shipments and deliveries move them out. Locations are the warehouse map.

```bash theme={null}
GET  /api/v1/logistics/locations
POST /api/v1/logistics/inbound-receipts
POST /api/v1/logistics/inbound-receipts/{receipt_id}/post
GET  /api/v1/logistics/shipments
POST /api/v1/logistics/shipments/{shipment_id}/packing-lists
```

### Post an inbound receipt

Posting is what turns a draft receipt into real stock — it creates lots and writes the inventory GL entry.

```bash theme={null}
POST /api/v1/logistics/inbound-receipts/{receipt_id}/post
Authorization: Bearer <access_token>
```

**Response (200):**

```json theme={null}
{
  "receipt_id": "uuid",
  "status": "posted",
  "lots_created": [
    { "lot_id": "uuid", "material_id": "uuid", "quantity": 500, "location_id": "uuid" }
  ]
}
```

<Warning>
  A receipt is editable only while in `draft`. Once posted it is immutable — correct mistakes with a stock movement or stock-take adjustment, not by editing the receipt.
</Warning>

## Stock

Stock is the inventory system of record: **lots** (a quantity of a material/SKU with provenance) live at **locations**, and every change appends to the **ledger**.

```bash theme={null}
GET  /api/v1/stock/balances
GET  /api/v1/stock/lots
POST /api/v1/stock/movements
GET  /api/v1/stock/ledger
POST /api/v1/stock/stock-take
```

<ParamField body="lot_id" type="string" required>
  The source lot for a movement.
</ParamField>

<ParamField body="to_location_id" type="string" required>
  Destination location (omit for an issue/consumption).
</ParamField>

<ParamField body="quantity" type="number" required>
  Quantity to move; must not exceed the lot's available balance.
</ParamField>

```bash theme={null}
POST /api/v1/stock/movements
Authorization: Bearer <access_token>

{
  "lot_id": "uuid",
  "to_location_id": "uuid",
  "quantity": 120,
  "reason": "transfer_to_cutting"
}
```

**Response (201):**

```json theme={null}
{
  "movement_id": "uuid",
  "lot_id": "uuid",
  "quantity": 120,
  "ledger_entry_id": "uuid"
}
```

<Tip>
  Use `POST /api/v1/stock/issue-suggestions` to let the system pick which lots to consume (FIFO / by expiry) before issuing fabric to a cut job. Reservations (`/stock/reservations`) hold stock for a planned outbound so it cannot be double-allocated.
</Tip>

## Warehouse Outbound

Outbound orders pull finished goods, **allocate** them against available lots, then **dispatch**.

```bash theme={null}
GET  /api/v1/warehouse-outbound/orders
POST /api/v1/warehouse-outbound/orders
POST /api/v1/warehouse-outbound/orders/{order_id}/allocate
POST /api/v1/warehouse-outbound/orders/{order_id}/dispatch
```

### Allocate an outbound order

```bash theme={null}
POST /api/v1/warehouse-outbound/orders/{order_id}/allocate
Authorization: Bearer <access_token>
```

**Response (200):**

```json theme={null}
{
  "order_id": "uuid",
  "status": "allocated",
  "allocations": [
    { "lot_id": "uuid", "quantity": 600, "location_id": "uuid" }
  ]
}
```

<Info>
  Allocate reserves specific lots; dispatch commits the movement, decrements stock, and triggers the COGS / accounts-receivable posting in [Finindex](/finindex/accounting/overview).
</Info>

## Delivery Notes

A delivery note is the document of record for goods leaving the dock, usually generated from a dispatched outbound order.

```bash theme={null}
GET  /api/v1/delivery-notes
POST /api/v1/delivery-notes
GET  /api/v1/delivery-notes/{note_id}
```

## Inventory Reconciliation

A read-only report comparing on-hand stock against the ledger to surface drift before a stock-take.

```bash theme={null}
GET /api/v1/inventory/reconciliation
Authorization: Bearer <access_token>
```

<Note>
  Discrepancies flagged here are corrected with `POST /api/v1/stock/stock-take`, which posts the adjusting movement and its gain/loss entry to the GL.
</Note>

See the **API Reference** tab for the full endpoint list across the Logistics, Stock, Warehouse Outbound, Delivery Notes, and Inventory Reconciliation tags.