Organizational transfer

Stock transfers between organizations

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.

POST /organizational-transfer/create

Create a new organizational transfer (cross-organization stock movement) in DRAFT or NEW state.

Request body

Field	Type	Required	Description
code	string	No	Optional custom transfer code / reference number
source_organization_id	string	Yes	Sending organization ObjectId
destination_organization_id	string	Yes	Receiving organization ObjectId
state	string	Yes	Initial state — draft (held) or new (ready to process). One of: draft, new
invoice_created	boolean	No	Whether a supplier invoice was created for this transfer. Default: false
with_price	boolean	No	Whether product prices are included in the transfer. Default: false
date	string (date-time)	Yes	Transfer document date (ISO 8601)
shipping_date	string (date-time)	Yes	Expected shipment date (ISO 8601)
sender_warehouse_id	string	Yes	Source warehouse ObjectId
sender_employee_id	string	Yes	Employee responsible for sending ObjectId
reason_id	string	Yes	Transfer reason ObjectId
price_id	string	No	Price-list ObjectId (optional)
note	string	No	Optional free-text note (max 500 characters)
currency	object	No	Currency snapshot at transfer time (optional)
currency._id	string	No	Currency ObjectId
currency.name	string	Yes
currency.value	number	Yes	Exchange rate value
currency.symbol	string	No
requests	object[]	Yes	One or more transfer request lines (each may reference a transfer-request document)
requests[].request_id	string	No	Linked transfer-request ObjectId (optional)
requests[].products	object[]	Yes	Products included in this request line
requests[].products[].product_id	string	Yes	Product ObjectId
requests[].products[].amount	number	Yes	Quantity to transfer (must be positive)
requests[].products[].price	number	No	Unit price (optional; required when with_price=true)
requests[].products[].box_count	number	No	Number of boxes (integer ≥ 0). Default: 0
requests[].products[].box_item	number	No	Items per box
requests[].products[].marks	string[]	No	Mark/serial codes for marked goods. Default: []
requests[].products[].expiration_date	string (date-time)	No	Expiration date (ISO 8601) for perishable goods
requests[].products[].extra_costs	object[]	No	Per-product additional costs. Default: []
additional_costs	object[]	No	Transfer-level additional costs. Default: []
additional_costs[].extra_cost_id	string	No
additional_costs[].amount	number	No
attachments	object[]	No	Attached files (documents, scans). Default: []
attachments[].name	string	No
attachments[].url	string	No

{
  "code": "string",
  "source_organization_id": "string",
  "destination_organization_id": "string",
  "state": "draft",
  "invoice_created": false,
  "with_price": false,
  "date": "2025-05-01T12:00:00Z",
  "shipping_date": "2025-05-01T12:00:00Z",
  "sender_warehouse_id": "string",
  "sender_employee_id": "string",
  "reason_id": "string",
  "price_id": "string",
  "note": "string",
  "currency": {
    "_id": "string",
    "name": "string",
    "value": 0,
    "symbol": "string"
  },
  "requests": [
    {
      "request_id": "string",
      "products": []
    }
  ],
  "additional_costs": [
    {
      "extra_cost_id": "string",
      "amount": 0
    }
  ],
  "attachments": [
    {
      "name": "string",
      "url": "string"
    }
  ]
}

Response

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": "string",
  "time": "2025-05-01T12:00:00Z"
}

GET /organizational-transfer/get-by-id/{id}

Fetch a single organizational transfer by ObjectId (aggregated detail view with products and requests).

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Organizational transfer ObjectId

Request body

No request body.

Response

Field	Type	Description
_id	string	Transfer ObjectId
number	string	Auto-generated transfer document number
code	string	Custom reference code
state	string	One of: draft, new, accepted, in_progress, done, canceled
type	string	Transfer type (o2o for organizational transfers)
source_organization_id	string
destination_organization_id	string
sender_warehouse_id	string
receiver_warehouse_id	string	Set after receive; null until received
sender_employee_id	string
reason_id	string
price_id	string
date	string (date-time)
shipping_date	string (date-time)
invoice_created	boolean
with_price	boolean
note	string
total_amount	number	Total quantity across all products
total_cost	number
total_price	number
total_extra_cost	number
requests	object[]	Transfer request lines with their product details
requests[].request_id	string
requests[].products	object[]
requests[].products[].product_id	string
requests[].products[].amount	number
requests[].products[].price	number
requests[].products[].box_count	number
requests[].products[].marks	string[]
requests[].products[].expiration_date	string (date-time)
requests[].products[].sender_stock_before	number	Sender warehouse stock before outflow
requests[].products[].sender_stock_after	number	Derived: sender_stock_before − amount
requests[].products[].receiver_stock_before	number	Receiver warehouse stock before inflow (set after receive)
requests[].products[].receiver_stock_after	number	Derived: receiver_stock_before + amount (set after receive)
additional_costs	object[]
attachments	object[]
created_at	string (date-time)
updated_at	string (date-time)

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "_id": "string",
    "number": "string",
    "code": "string",
    "state": "draft",
    "type": "string",
    "source_organization_id": "string",
    "destination_organization_id": "string",
    "sender_warehouse_id": "string",
    "receiver_warehouse_id": "string",
    "sender_employee_id": "string",
    "reason_id": "string",
    "price_id": "string",
    "date": "2025-05-01T12:00:00Z",
    "shipping_date": "2025-05-01T12:00:00Z",
    "invoice_created": false,
    "with_price": false,
    "note": "string",
    "total_amount": 0,
    "total_cost": 0,
    "total_price": 0,
    "total_extra_cost": 0,
    "requests": [
      {
        "request_id": "string",
        "products": []
      }
    ],
    "additional_costs": [
      {}
    ],
    "attachments": [
      {}
    ],
    "created_at": "2025-05-01T12:00:00Z",
    "updated_at": "2025-05-01T12:00:00Z"
  },
  "time": "2025-05-01T12:00:00Z"
}

POST /organizational-transfer/get-paging

Paginated list of organizational transfers, filterable by organization, warehouse, state, and reason.

Request body

Field	Type	Required	Description
page	number	Yes	Default: 1
limit	number	Yes	Default: 20
source_organization_id	string	No	Filter by sending organization ObjectId
destination_organization_id	string	No	Filter by receiving organization ObjectId
sender_warehouse_id	string	No	Filter by sender warehouse ObjectId
receiver_warehouse_id	string	No	Filter by receiver warehouse ObjectId
states	string[]	No	Filter by one or more transfer states
reason_id	string	No	Filter by transfer reason ObjectId

{
  "page": 1,
  "limit": 20,
  "source_organization_id": "string",
  "destination_organization_id": "string",
  "sender_warehouse_id": "string",
  "receiver_warehouse_id": "string",
  "states": [
    "draft"
  ],
  "reason_id": "string"
}

Response

Field	Type	Description
total	number
list	any[]

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "total": 0,
    "list": []
  },
  "time": "2025-05-01T12:00:00Z"
}

PUT /organizational-transfer/update/{id}

Update an existing organizational transfer. Only allowed in DRAFT or NEW state.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Organizational transfer ObjectId

Request body

Field	Type	Required	Description
code	string	No	Optional custom transfer code / reference number
source_organization_id	string	Yes	Sending organization ObjectId
destination_organization_id	string	Yes	Receiving organization ObjectId
state	string	Yes	Initial state — draft (held) or new (ready to process). One of: draft, new
invoice_created	boolean	No	Whether a supplier invoice was created for this transfer. Default: false
with_price	boolean	No	Whether product prices are included in the transfer. Default: false
date	string (date-time)	Yes	Transfer document date (ISO 8601)
shipping_date	string (date-time)	Yes	Expected shipment date (ISO 8601)
sender_warehouse_id	string	Yes	Source warehouse ObjectId
sender_employee_id	string	Yes	Employee responsible for sending ObjectId
reason_id	string	Yes	Transfer reason ObjectId
price_id	string	No	Price-list ObjectId (optional)
note	string	No	Optional free-text note (max 500 characters)
currency	object	No	Currency snapshot at transfer time (optional)
currency._id	string	No	Currency ObjectId
currency.name	string	Yes
currency.value	number	Yes	Exchange rate value
currency.symbol	string	No
requests	object[]	Yes	One or more transfer request lines (each may reference a transfer-request document)
requests[].request_id	string	No	Linked transfer-request ObjectId (optional)
requests[].products	object[]	Yes	Products included in this request line
requests[].products[].product_id	string	Yes	Product ObjectId
requests[].products[].amount	number	Yes	Quantity to transfer (must be positive)
requests[].products[].price	number	No	Unit price (optional; required when with_price=true)
requests[].products[].box_count	number	No	Number of boxes (integer ≥ 0). Default: 0
requests[].products[].box_item	number	No	Items per box
requests[].products[].marks	string[]	No	Mark/serial codes for marked goods. Default: []
requests[].products[].expiration_date	string (date-time)	No	Expiration date (ISO 8601) for perishable goods
requests[].products[].extra_costs	object[]	No	Per-product additional costs. Default: []
additional_costs	object[]	No	Transfer-level additional costs. Default: []
additional_costs[].extra_cost_id	string	No
additional_costs[].amount	number	No
attachments	object[]	No	Attached files (documents, scans). Default: []
attachments[].name	string	No
attachments[].url	string	No

{
  "code": "string",
  "source_organization_id": "string",
  "destination_organization_id": "string",
  "state": "draft",
  "invoice_created": false,
  "with_price": false,
  "date": "2025-05-01T12:00:00Z",
  "shipping_date": "2025-05-01T12:00:00Z",
  "sender_warehouse_id": "string",
  "sender_employee_id": "string",
  "reason_id": "string",
  "price_id": "string",
  "note": "string",
  "currency": {
    "_id": "string",
    "name": "string",
    "value": 0,
    "symbol": "string"
  },
  "requests": [
    {
      "request_id": "string",
      "products": []
    }
  ],
  "additional_costs": [
    {
      "extra_cost_id": "string",
      "amount": 0
    }
  ],
  "attachments": [
    {
      "name": "string",
      "url": "string"
    }
  ]
}

Response

Same response shape as POST /organizational-transfer/create.

PUT /organizational-transfer/set-status/{id}

Transition the transfer through the state machine. Valid transitions: NEW→DRAFT|CANCELED|ACCEPTED; DRAFT→NEW; ACCEPTED→IN_PROGRESS|CANCELED; IN_PROGRESS→CANCELED; DONE→CANCELED. Use receive for the ACCEPTED/IN_PROGRESS→DONE transition.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Organizational transfer ObjectId

Request body

Field	Type	Required	Description
state	string	Yes	Target state. Valid transitions: NEW→DRAFT|CANCELED|ACCEPTED; DRAFT→NEW; ACCEPTED→IN_PROGRESS|CANCELED; IN_PROGRESS→CANCELED; DONE→CANCELED. Use the receive endpoint to transition to DONE.. One of: draft, new, accepted, in_progress, canceled

{
  "state": "draft"
}

Response

Same response shape as POST /organizational-transfer/create.

PUT /organizational-transfer/receive/{id}

Receive an accepted organizational transfer: transitions ACCEPTED or IN_PROGRESS → DONE and applies stock movement into the receiver warehouse.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Organizational transfer ObjectId

Request body

Field	Type	Required	Description
receiver_warehouse_id	string	Yes	Destination warehouse ObjectId where stock will be received

{
  "receiver_warehouse_id": "string"
}

Response

Same response shape as POST /organizational-transfer/create.

---

This page is generated from the OpenAPI spec.