> ## 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.

# Procurement

> Demand-driven sourcing — material requests, purchase orders, GRN, and landed costs

# Procurement

Procurement turns BOM-driven demand into purchased and received stock. A **material request** captures what an order needs, those requests are batched into **purchase orders** sent to suppliers, deliveries are booked with **goods receipt notes (GRN)**, and **landed costs** allocate freight and duty onto received stock. Receipts feed **MES** stock and the matching bills post to **Finindex** AP.

## The flow

```mermaid theme={null}
flowchart LR
    Demand[Sales Order / BOM demand] --> MR[Material Request]
    MR --> Approve{Approved?}
    Approve -->|reject| MR
    Approve -->|approve| CreatePO[create-purchase-orders]
    CreatePO --> PO[Purchase Order]
    PO --> Supplier((Supplier))
    Supplier --> GRN[Goods Receipt · GRN]
    GRN --> Stock[(Stock · MES)]
    GRN --> Landed[Landed Costs]
    PO --> Bill[Bill · Finindex AP]
```

```mermaid theme={null}
sequenceDiagram
    actor Staff
    participant API
    participant MaterialRequest
    participant PurchaseOrder
    participant Supplier
    participant GRN
    participant Finindex

    Staff->>API: POST /material-requests
    API->>MaterialRequest: create (from BOM demand)
    Staff->>API: POST /material-requests/{id}/submit
    Staff->>API: POST /material-requests/{id}/approve
    Staff->>API: POST /material-requests/create-purchase-orders
    API->>PurchaseOrder: create POs grouped by supplier
    PurchaseOrder->>Supplier: issue PO
    Supplier-->>GRN: deliver goods
    Staff->>API: POST /grn
    API->>GRN: receive + increment stock
    Staff->>API: POST /purchase-orders/{id}/create-bill
    API->>Finindex: post AP bill
```

## Material Requests

A material request (MR) lists the materials and quantities an order needs, netting demand against available stock. MRs run through a submit → approve workflow, then convert into purchase orders.

```bash theme={null}
GET /api/v1/material-requests
POST /api/v1/material-requests
GET /api/v1/material-requests/{mr_id}
PATCH /api/v1/material-requests/{mr_id}
Authorization: Bearer <access_token>
```

### Create a material request

<ParamField body="order_id" type="string" required>
  The sales order driving this demand.
</ParamField>

<ParamField body="lines" type="array" required>
  Materials and required quantities.
</ParamField>

```bash theme={null}
POST /api/v1/material-requests
Authorization: Bearer <access_token>

{
  "order_id": "uuid",
  "lines": [
    { "material_id": "uuid", "quantity": 850, "uom": "m" }
  ]
}
```

**Response (201):**

```json theme={null}
{
  "id": "uuid",
  "ref": "MR-2026-0118",
  "status": "draft"
}
```

### Approval workflow

```bash theme={null}
POST /api/v1/material-requests/{mr_id}/submit
POST /api/v1/material-requests/{mr_id}/approve
POST /api/v1/material-requests/{mr_id}/reject
POST /api/v1/material-requests/bulk-approve
GET  /api/v1/material-requests/{mr_id}/approval-history
```

Check stock before requesting with `GET /api/v1/material-requests/stock/{material_id}`.

### Create purchase orders from requests

The key handoff: batch one or more approved material requests into purchase orders, grouped by supplier.

<ParamField body="material_request_ids" type="array" required>
  The approved material requests to convert.
</ParamField>

```bash theme={null}
POST /api/v1/material-requests/create-purchase-orders
Authorization: Bearer <access_token>

{
  "material_request_ids": ["uuid", "uuid"]
}
```

**Response (201):**

```json theme={null}
{
  "purchase_orders": [
    { "id": "uuid", "ref": "PO-2026-0091", "supplier_id": "uuid" }
  ]
}
```

Trace the resulting POs with `GET /api/v1/material-requests/{mr_id}/linked-purchase-orders`.

## Purchase Orders

A purchase order is the committed order to a supplier. POs can also originate the other direction — generating a material request from an existing PO.

```bash theme={null}
GET /api/v1/purchase-orders
POST /api/v1/purchase-orders
GET /api/v1/purchase-orders/{po_id}
PATCH /api/v1/purchase-orders/{po_id}
Authorization: Bearer <access_token>
```

### Create a material request from a PO

```bash theme={null}
POST /api/v1/purchase-orders/{po_id}/create-material-request
Authorization: Bearer <access_token>
```

### Create a bill (Finindex AP)

Posts an accounts-payable bill against the PO into **Finindex**.

```bash theme={null}
POST /api/v1/purchase-orders/{po_id}/create-bill
Authorization: Bearer <access_token>
```

Inspect the full document chain with `GET /api/v1/purchase-orders/{po_id}/flow`.

<Info>
  The PO flow endpoint stitches together the linked material request, GRNs, and bill so you can audit a single PO end to end.
</Info>

## Subcontract

Subcontract orders send materials out to an external maker and receive finished goods back. Subcontract invoices post to Finindex.

```bash theme={null}
GET  /api/v1/subcontract-orders
POST /api/v1/subcontract-orders
POST /api/v1/subcontract-orders/{order_id}/issue-material
POST /api/v1/subcontract-orders/{order_id}/receive-goods
POST /api/v1/subcontract-invoices
POST /api/v1/subcontract-invoices/{invoice_id}/post
Authorization: Bearer <access_token>
```

## Goods Receipt Notes (GRN)

A GRN books a supplier delivery against its PO and increments stock. Received quantities feed **MES** inventory.

```bash theme={null}
GET /api/v1/grn
POST /api/v1/grn
GET /api/v1/grn/{grn_id}
PATCH /api/v1/grn/{grn_id}
Authorization: Bearer <access_token>
```

<ParamField body="purchase_order_id" type="string" required>
  The PO being received against.
</ParamField>

<ParamField body="lines" type="array" required>
  Received materials with quantities.
</ParamField>

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

{
  "purchase_order_id": "uuid",
  "lines": [
    { "material_id": "uuid", "received_quantity": 850, "uom": "m" }
  ]
}
```

## Landed Costs

Landed costs allocate freight, duty, and handling onto received stock so material valuation reflects true delivered cost.

```bash theme={null}
POST /api/v1/landed-costs/apply
Authorization: Bearer <access_token>
```

<Warning>
  Apply landed costs after the GRN is booked — the allocation distributes additional cost across already-received quantities. Applying before receipt has nothing to allocate against.
</Warning>

See the **API Reference** tab for the full endpoint list.

## Connects to

<CardGroup cols={2}>
  <Card title="MES Production" icon="industry" href="/cutmake/mes">
    Received stock is consumed by production.
  </Card>

  <Card title="Finindex AP" icon="money-bill-wave" href="/finindex">
    Bills and subcontract invoices post here.
  </Card>
</CardGroup>