Orders

CREATE order

---

This method allows creating a new order, setting order properties, and adding order items. Production items are automatically generated based on the order items' quantity.

Method

POST /api.hesh.app/api/v1/public/orders

Returns

The method returns the created order details, including the order items and their associated production items.

Permissions Required

No specific permissions are mentioned, but the API should be accessed with valid credentials if required.

Request

• Headers:

  • x-tenant-id (string, UUID v4) - Tenant ID Example: 40dd0c53-2fa7-4193-82ae-14d4e62c20fb

• Body (application/json):

{
  "external_order_id": "string",
  "external_order_number": "string",
  "marketplace_order_number": "string",
  "external_note": "string",
  "marketplace_note": "string",
  "deadline_at": "2024-05-17T11:21:47.898Z",
  "external_created_at": "2024-05-14T11:21:47.898Z",
  "to_stock": false,
  "client": {
    "name": "string",
    "external_client_id": "string",
    "phone": "string",
    "email": "string",
    "company": "string"
  },
  "primary_client": {
    "name": "string",
    "external_client_id": "string",
    "phone": "string",
    "email": "string",
    "company": "string"
  },
  "line_items": [
    {
      "line_item_id": "string",
      "deadline_at": "2024-05-17T11:21:47.898Z",
      "barcode": "string",
      "sku": "string",
      "name": "string",
      "quantity": 3,
      "line_item_note": "string"
    }
  ]
}

• Request body parameters

  • Order

    • external_order_id (string, required): A unique identifier for each order. Example: b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e

    • external_order_number (string, required): A unique string used in the UI and controlled by the user. Example: ON-12345

    • marketplace_order_number (string, optional): A unique string used in the UI and controlled by the user. Example: MON-986-456

    • marketplace_note (string, optional): Additional comments or info for the order. Example: needs extra packing

    • deadline_at (date, optional): The date when the order should be produced (ISO 8601 format). Example: 2024-05-17T11:21:47.898Z

    • external_created_at (date, optional): The date when the order was created in an external system (ISO 8601 format). Example: 2024-05-14T11:21:47.898Z

    • to_stock (boolean, optional): Indicates if this is an internal company order (e.g., to replenish warehouse stocks). Example: false

    Client:

    • name (string, required): Full name of the customer. Example: Client 123

    • external_client_id (string, optional): A unique ID for the customer. Example: 1345-2345

    • phone (string, optional): The customer's phone number. Example: 00074567309

    • email (string, optional): The customer's email address. Example: [e-mail]

    • company (string, optional): The customer's company name. Example: Company 123

    Primary Client:

    • name (string, required): Full name of the primary customer. Example: Client 1234

    • external_client_id (string, optional): A unique ID for the primary customer. Example: 1345-2345-987

    • phone (string, optional): The primary customer's phone number. Example: 00074567399

    • email (string, optional): The primary customer's email address. Example: [e-mail]

    • company (string, optional): The primary customer's company name. Example: Company 1234

    Line Items:

    • line_item_id (string, optional): A unique identifier for the order item. If this number is not available, the system will create it automatically. Example: 557657-8654-89i76

    • deadline_at (date, optional): The date when the line item should be produced (ISO 8601 format). Example: 2024-05-17T11:21:47.898Z

    • barcode (string, required): The unique identifier of the product variant. Example: 13465678767

    • sku (string, optional): The SKU key for the product variant. Example: product-84620

    • name (string, required): The name of the ordered product variant. Example: Super product

    • quantity (number, required): The number of ordered items of the product variant. Example: 3

    • line_item_note (string, optional): Additional comments or info for the line item. Example: Should be smooth

Path Parameters

This method does not use path parameters.

Response

• 200 OK: Successfully created the order

Response body (application/json):

 {
  "id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
  "external_order_number": "external-order-number",
  "order_key": "O-EX-1",
  "external_order_id": "external-order-id",
  "marketplace_order_number": "marketplace_order_number",
  "marketplace_note": "extra packaging",
  "line_items": [
    {
      "id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
      "line_item_id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
      "barcode": "453454334234",
      "sku": "product-84620",
      "name": "Super product",
      "quantity": 10,
      "line_item_note": "extra packaging",
      "productions": [
        {
          "production_key": "new-production-key",
          "created_at": "2025-01-22T16:48:25.616Z"
        }
      ]
    }
  ]
}

Error Codes:

• 400 Bad Request — Invalid input data or missing required fields.

• 500 Internal Server Error — Server-side error occurred.

Notes

• If the "line_item_id" is not provided in the request, HESH generates it and includes it in the response.

• If the "line_item_id" is provided, HESH uses it and includes the same ID in the response.

How to check transfered data in HESH

1. Register in Hesh:

   1. Go to your success manager and provide registration email

   2. Recieve invitation on the email

   3. Create a password and log in

2. Open "Production" page

   1. If you don't have "Production" page in the sidebar or don't have access contact your success manager

3. Choose "Source" filter

4. Filter productions by External type

5. Sorting productions by date, deadline and so on

UPDATE order

---

This method allows to update order properties and separate order lines with new values. Any property not provided will be left unchanged.

Method

PUT /api.hesh.app/api/v1/public/orders/{id}

Returns

The method returns success message about updated order details or error code based on the operation's outcome.

Permissions Required

No specific permissions are mentioned, but the API should be accessed with valid credentials if required.

Request

• Headers:

  • x-tenant-id (string, UUID v4) - Tenant ID Example: 40dd0c53-2fa7-4193-82ae-14d4e62c20fb

• Body (application/json):

{
  "external_order_number": "external_order_number",
  "marketplace_order_number": "marketplace_order_number",
  "comment": "extra packaging",
  "deadline_at": "2025-01-22T16:48:25.617Z",
  "external_created_at": "2025-01-22T16:48:25.618Z",
  "to_stock": true,
  "client": {
    "name": "client name",
    "external_client_id": "937-99-92",
    "phone": "937-99-92",
    "email": "[e-mail]",
    "company": "client company"
  },
  "primary_client": {
    "name": "client name",
    "external_client_id": "937-99-92",
    "phone": "937-99-92",
    "email": "[e-mail]",
    "company": "client company"
  },
  "line_items": [
    {
      "line_item_id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
      "barcode": "453454334234",
      "deadline_at": "2025-01-22T16:48:25.616Z",
      "quantity": 10,
      "comment": "extra packaging"
    }
  ]

Request body parameters

• Order

  • external_order_number (string, required): A unique string used in the UI and controlled by the user. Example: ON-12345

  • marketplace_order_number (string, optional): A unique string used in the UI and controlled by the user. Example: MON-986-456

  • marketplace_note (string, optional): Additional comments or info for the order. Example: needs extra packing

  • deadline_at (date, optional): The date when the order should be produced (ISO 8601 format). Example: 2024-05-17T11:21:47.898Z

  • external_created_at (date, optional): The date when the order was created in an external system (ISO 8601 format). Example: 2024-05-14T11:21:47.898Z

  • to_stock (boolean, optional): Indicates if this is an internal company order (e.g., to replenish warehouse stocks). Example: false

  Client:

  • name (string, required): Full name of the customer. Example: Client 123

  • external_client_id (string, optional): A unique ID for the customer. Example: 1345-2345

  • phone (string, optional): The customer's phone number. Example: 00074567309

  • email (string, optional): The customer's email address. Example: [e-mail]

  • company (string, optional): The customer's company name. Example: Company 123

  Primary Client:

  • name (string, required): Full name of the primary customer. Example: Client 1234

  • external_client_id (string, optional): A unique ID for the primary customer. Example: 1345-2345-987

  • phone (string, optional): The primary customer's phone number. Example: 00074567399

  • email (string, optional): The primary customer's email address. Example: [e-mail]

  • company (string, optional): The primary customer's company name. Example: Company 1234

  Line Items:

  • line_item_id (string, optional): A unique identifier for the order item. If this number is not available, the system will create it automatically. Example: 557657-8654-89i76

  • deadline_at (date, optional): The date when the line item should be produced (ISO 8601 format). Example: 2024-05-17T11:21:47.898Z

  • barcode (string, required): The unique identifier of the product variant. Example: 13465678767

  • sku (string, optional): The SKU key for the product variant. Example: product-84620

  • name (string, required): The name of the ordered product variant. Example: Super product

  • quantity (number, required): The number of ordered items of the product variant. Example: 3

  • line_item_note (string, optional): Additional comments or info for the line item. Example: Should be smooth

Path Parameters

• external_id (string, required): The unique identifier of the order used to link ordered items to the order. Example: b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e

Responses

• 200 OK: Successfully updated the order and/or line items

{
  "id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
  "external_order_number": "external-order-number",
  "order_key": "O-EX-1",
  "external_order_id": "external-order-id",
  "marketplace_order_number": "marketplace_order_number",
  "marketplace_note": "extra packaging",
  "line_items": [
    {
      "id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
      "line_item_id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
      "barcode": "453454334234",
      "sku": "product-84620",
      "name": "Super product",
      "quantity": 10,
      "line_item_note": "extra packaging",
      "productions": [
        {
          "production_key": "new-production-key",
          "created_at": "2025-01-22T16:48:25.616Z"
        }
      ]
    }
  ]
}

Error Codes:

• 400 Bad Request — The request is malformed or contains invalid data

• 404 Not Found — The order with the specified external_id does not exist

• 500 Internal Server Error — An unexpected error occurred while processing the request

Scenarios for processing the received data

📝 Amount updated

• the quantity is increased (past quantity>new quantity)

The system counts by how many units the quantity of the product has increased and adds a separate production item to the order for each unit of the difference

• the number is decreased (past quantity<new quantity)

The system counts by how many units the quantity of the product has decreased and selects difference number with non-started productions among all in the specified order and cancels them

If decreased difference more than number of non-started productions then system find not finished productions with low production priority and then the smallest progress bar and stops them.

📝 Quantity is zero

If you enter zero in the ‘Quantity’ value in the body of the query, the system will cancel all production of this line item with the specified characteristic. This way, a certain number of created productions with the specified parameters are deleted within one order.

📝 Line item is missed in request body

Productions are not in finished states - the system cancels all productions from this order with specified barcodes. Updates the deadline for the whole order according to the most short term deadline of the item in it.

📝 Deadline updated

System checks deadlines for each production item with the same barcode in specified order and rewrites them, saving the history and marks that changes were made by external system Updates deadline for the whole order according to the most short term deadline of the item in it.

GET order

---

This method retrieves a list of all external orders along with their details, such as order numbers, priority, client information, and timestamps.

Method

GET /api.hesh.app/api/v1/public/orders

Returns

A list of external orders in JSON format.

Permissions Required

No specific permissions are mentioned, but the API should be accessed with valid credentials if required.

Request

Header Parameters:

• x-tenant-id (string, required): The unique identifier of the tenant (UUID v4). Example: 40dd0c53-2fa7-4193-82ae-14d4e62c20fb

Path Parameters

This method does not use path parameters.

Responses

• 200 OK: A successful response returns an array of external orders.

[
  {
    "id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
    "external_order_number": "external-order-number",
    "marketplace_order_number": "marketplace_order_number",
    "external_order_id": "external-order-id",
    "order_key": "order-key-123",
    "comment": "fragile",
    "to_stock": false,
    "is_deleted": false,
    "priority": "Medium",
    "client_id": "string",
    "counterparty_id": "string",
    "created_at": "2025-01-23T17:01:31.692Z"
  }
]

Error Codes:

• 400 Bad Request - The request is malformed or contains invalid data

• 404 Not Found - No orders were found for the provided x-tenant-id

• 500 Internal Server Error - An unexpected error occurred while processing the request

CANCEL order

---

This method allows to cancel all productions in specified order.

Method

POST /api.hesh.app/api/v1/public/orders/{id}

Returns

A success status if the order is canceled or an error if the cancelation fails.

Permissions Required

No specific permissions are mentioned, but the API should be accessed with valid credentials if required.

Request

• Headers:

  • x-tenant-id (string, UUID v4) - Tenant ID Example: 40dd0c53-2fa7-4193-82ae-14d4e62c20fb

Path Parameters

• external_id (string, required): The unique identifier of the order used to link ordered items to the order. Example: b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e

Response

• 200 OK: Successfully created the order

Response body (application/json):

{
  "id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
  "external_order_number": "external-order-number",
  "marketplace_order_number": "marketplace_order_number",
  "external_order_id": "external-order-id",
  "order_key": "order-key-123",
  "comment": "fragile",
  "to_stock": false,
  "is_deleted": false,
  "priority": "Medium",
  "client_id": "string",
  "counterparty_id": "string",
  "created_at": "2025-01-23T17:30:13.303Z"
}

Error Codes:

• 400 Bad Request — Invalid input data or missing required fields

• 404 Not Found —The specified order or item was not found

• 500 Internal Server Error — Server-side error occurred

Notes

Productions, additional productions and tasks are not in finished states (not “Done”, “Cancelled”, “From Stock”):

• the system cancels all productions, tasks and additional components from this order with specified barcodes

• updates the deadline for the whole order according to the most short term deadline of the item in it

DELETE order

---

This method allows to delete a single order by its id.

Method

DELETE /api.hesh.app/api/v1/public/orders/{id}

Returns

A success status if the order is deleted or an error if the deletion fails.

Permissions Required

No specific permissions are mentioned, but the API should be accessed with valid credentials if required.

Request

• Headers:

  • x-tenant-id (string, UUID v4) - Tenant ID Example: 40dd0c53-2fa7-4193-82ae-14d4e62c20fb

Path Parameters

• external_id (string, required): The unique identifier of the order used to link ordered items to the order. Example: b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e

Response

• 200 OK: Successfully created the order

Response body (application/json):

{
  "id": "b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e",
  "external_order_number": "external-order-number",
  "marketplace_order_number": "marketplace_order_number",
  "external_order_id": "external-order-id",
  "order_key": "order-key-123",
  "comment": "fragile",
  "to_stock": false,
  "is_deleted": false,
  "priority": "Medium",
  "client_id": "string",
  "counterparty_id": "string",
  "created_at": "2025-01-23T17:18:24.820Z"
}

Error Codes:

• 400 Bad Request — Invalid input data or missing required fields

• 404 Not Found —The specified order or item was not found

• 500 Internal Server Error — Server-side error occurred

Notes

Productions, additional productions and tasks are not in finished states (not “Done”, “Cancelled”, “From Stock”):

• the system cancels all productions, tasks, additional tasks and additional components from this order with specified barcodes

• Payment for task that are in “In progress” status should be calculated

• Add flag “is deleted” to order info in all canceled productions.

• Updates the deadline for the whole order according to the most short term deadline of the item in it.

• Removes order details assosiated with this order from the list in “New production” and “Change order for production” pop-ups.

Productions, additional productions and tasks that are in finished states (not “Done”, “Cancelled”, “From Stock”) remain in the same status.