Purchase order

INFO

Every response arrives in the shared envelope — code, message, messages, status_code, time — with the payload in data. The tables below describe what is inside data.

GET /purchase-order/get-by-id/{id}

Get a purchase order by its _id (detailed view).

Path parameters

Parameter	Type	Required	Description
id	string	Yes

Request body

No request body.

Response

Field	Type	Description
_id	string
number	string
code	string
organization_id	string
supplier_id	string
supplier	object
supplier._id	string
supplier.name	string
responsible_id	string
responsible	object
responsible._id	string
responsible.full_name	string
warehouse_id	string
currency_id	string
date	string (date-time)
delivery_date	string (date-time)
state	string	One of: new, in_progress, done, canceled, draft
is_fully_purchased	boolean
total	number
note	string
items	object[]
items[]._id	string
items[].product_id	string
items[].amount	number
items[].cost	number
items[].purchased_amount	number
created_at	string (date-time)
updated_at	string (date-time)

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "_id": "string",
    "number": "string",
    "code": "string",
    "organization_id": "string",
    "supplier_id": "string",
    "supplier": {
      "_id": "string",
      "name": "string"
    },
    "responsible_id": "string",
    "responsible": {
      "_id": "string",
      "full_name": "string"
    },
    "warehouse_id": "string",
    "currency_id": "string",
    "date": "2025-05-01T12:00:00Z",
    "delivery_date": "2025-05-01T12:00:00Z",
    "state": "new",
    "is_fully_purchased": false,
    "total": 0,
    "note": "string",
    "items": [
      {
        "_id": "string",
        "product_id": "string",
        "amount": 0,
        "cost": 0,
        "purchased_amount": 0
      }
    ],
    "created_at": "2025-05-01T12:00:00Z",
    "updated_at": "2025-05-01T12:00:00Z"
  },
  "time": "2025-05-01T12:00:00Z"
}

POST /purchase-order/get-paging

Paginated list of purchase orders with optional filters.

Request body

Field	Type	Required	Description
page	number	Yes	Default: 1
limit	number	Yes	Default: 20
states	string[]	No
organization_id	string	No
supplier_id	string	No
responsible_id	string	No
currency_id	string	No
is_fully_purchased	boolean	No

{
  "page": 1,
  "limit": 20,
  "states": [
    "new"
  ],
  "organization_id": "string",
  "supplier_id": "string",
  "responsible_id": "string",
  "currency_id": "string",
  "is_fully_purchased": false
}

Response

Field	Type	Description
list	object[]
list[]._id	string
list[].number	string
list[].code	string
list[].organization_id	string
list[].supplier_id	string
list[].supplier	object
list[].supplier._id	string
list[].supplier.name	string
list[].responsible_id	string
list[].responsible	object
list[].responsible._id	string
list[].responsible.full_name	string
list[].warehouse_id	string
list[].currency_id	string
list[].date	string (date-time)
list[].delivery_date	string (date-time)
list[].state	string	One of: new, in_progress, done, canceled, draft
list[].is_fully_purchased	boolean
list[].total	number
list[].note	string
list[].items	object[]
list[].items[]._id	string
list[].items[].product_id	string
list[].items[].amount	number
list[].items[].cost	number
list[].items[].purchased_amount	number
list[].created_at	string (date-time)
list[].updated_at	string (date-time)
total	number

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "list": [
      {
        "_id": "string",
        "number": "string",
        "code": "string",
        "organization_id": "string",
        "supplier_id": "string",
        "supplier": {
          "_id": null,
          "name": null
        },
        "responsible_id": "string",
        "responsible": {
          "_id": null,
          "full_name": null
        },
        "warehouse_id": "string",
        "currency_id": "string",
        "date": "2025-05-01T12:00:00Z",
        "delivery_date": "2025-05-01T12:00:00Z",
        "state": "new",
        "is_fully_purchased": false,
        "total": 0,
        "note": "string",
        "items": [],
        "created_at": "2025-05-01T12:00:00Z",
        "updated_at": "2025-05-01T12:00:00Z"
      }
    ],
    "total": 0
  },
  "time": "2025-05-01T12:00:00Z"
}

POST /purchase-order/create

Open a purchase order — the request stage that precedes a purchase. Ordered quantities are validated against product stock/measure rules before anything is written. state must be "new"; any other value is rejected. Returns the created order in its detailed form.

Request body

Field	Type	Required	Description
organization_id	string	Yes	Organization placing the order (required). Must exist.
ordered_at	string (date-time)	Yes	When the order was placed (required, ISO 8601).
purchase_date	string (date-time)	No	Expected purchase/delivery date.
responsible_id	string	Yes	Responsible user ObjectId (required).
supplier_id	string	Yes	Supplier ObjectId (required).
supplier_assistant_id	string	No	Supplier-side contact person ObjectId.
currency_id	string	Yes	Currency the costs are quoted in (required).
price_id	string	No	Price list the costs were quoted from.
state	string	Yes	Initial state (required). Only "new" is accepted on create — anything else is rejected.. One of: new, accepted, in_progress, done, canceled, draft
state_id	string	No	Board column ObjectId. When omitted the default column for the state is resolved.
code	string	No	Caller-supplied external code.
note	string	No	Free-text note.
requests	object[]	Yes	Order lines grouped by source purchase request (required, at least one group).
requests[].request_id	string	No	Source purchase-request ObjectId. Omit for an order raised without a request.
requests[].products	object[]	Yes	Lines in this group (required, at least one).
requests[].products[].product_id	string	Yes	Product ObjectId (required).
requests[].products[].amount	number	Yes	Ordered quantity (required, > 0). Validated against the product measure.
requests[].products[].box_count	number	No	Whole boxes ordered. Defaults to 0.
requests[].products[].cost	number	No	Unit cost in the order currency.
requests[].products[].total_cost	number	No	Line total. Derived when omitted.
requests[].products[].request_item_id	string	No	Source purchase-request line this order line fulfils.
requests[].products[].used_measure	object	No	Alternative unit of measure: { _id, ratio, amount }.
attachments	object[]	No	Attached files: { name, path, size, note }.

{
  "organization_id": "64b7f4d9e2b3b6a0b7c5d80a",
  "ordered_at": "2025-05-01T12:00:00Z",
  "purchase_date": "2025-05-01T12:00:00Z",
  "responsible_id": "string",
  "supplier_id": "string",
  "supplier_assistant_id": "string",
  "currency_id": "string",
  "price_id": "string",
  "state": "new",
  "state_id": "string",
  "code": "string",
  "note": "string",
  "requests": [
    {
      "request_id": "string",
      "products": []
    }
  ],
  "attachments": [
    {}
  ]
}

Response

Same response shape as GET /purchase-order/get-by-id/{id}.

PUT /purchase-order/set-state

Move a purchase order along its lifecycle. Allowed transitions: new → in_progress | accepted | canceled; in_progress → done | in_progress; accepted → done. Returns the updated order in its detailed form.

Request body

Field	Type	Required	Description
_id	string	Yes	Purchase order ObjectId (required).
state	string	Yes	Target state (required). Allowed transitions: new → in_progress | accepted | canceled; in_progress → done | in_progress; accepted → done. An unsupported transition is rejected.. One of: new, accepted, in_progress, done, canceled, draft
state_id	string	No	Board column ObjectId to move the order into.

{
  "_id": "64b7f4d9e2b3b6a0b7c5d80a",
  "state": "new",
  "state_id": "string"
}

Response

Same response shape as GET /purchase-order/get-by-id/{id}.

---

This page is generated from the OpenAPI spec.