Фулфілмент

Оновити дані товару

patch

/fulfillment/{countrycode}/goods/{objectId}

Цей endpoint дозволяє змінювати дані існуючого товару. В тілі запиту потрібно передавати лише ті поля, які необхідно оновити (часткове оновлення), наприклад назву, ціну або термін придатності товару.

🔸Усі поля необов’язкові, але для виконання оновлення потрібно передати щонайменше одне поле. У разі успіху API повертає оновлені дані товару.

🔹Опис елементів керування:

SCHEMA

Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Показує готовий приклад JSON із правильно сформованими значеннями для демонстрації того, як має виглядати валідний запит або відповідь.

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the goods are registered.

Example: pl

objectIdstringRequired

Unique identifier of the goods to be updated.

Example: 1b34e39f-5805-4510-94ca-1d88ea14739a

Body

Request body for updating goods. Only the fields that need to be changed should be provided. At least one field must be present.

goodsUnitNamestring · min: 2 · max: 255Optional

Product name.

goodsUnitFullNamestring · min: 2 · max: 255Optional

Full product name.

pricenumber · float · min: 0.01 · max: 1000000Optional

Price per unit of the product.

inventExpireDaysinteger · min: 1 · max: 15000 · nullableOptional

Shelf life in days or null if not applicable.

Responses

201

Request successful. Goods details were updated.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

403

Authorization Error. Access to the resource is forbidden.

application/json

404

Resource Not Found. The requested resource does not exist.

application/json

422

Unprocessable Entity. The request body contains validation errors.

application/json

patch

/fulfillment/{countrycode}/goods/{objectId}

PATCH /v.1.0/fulfillment/{countrycode}/goods/{objectId} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "goodsUnitName": "string",
  "goodsUnitFullName": "string",
  "price": 900,
  "inventExpireDays": 1
}

{
  "goodsUnitName": "string",
  "goodsUnitFullName": "string",
  "price": 900,
  "inventExpireDays": 1
}

Оновити дані штрихкоду

patch

/fulfillment/{countrycode}/barcodes/{objectBarcodeId}

Цей ендпоінт використовується для оновлення параметрів існуючого штрих-коду в системі за його унікальним ідентифікатором.

У тілі запиту слід зазначати лише ті поля, які необхідно оновити.

🔸Усі поля є необов'язковими, проте для виконання оновлення необхідно надати хоча б одне поле. У разі успішного виконання API повертає оновлений об'єкт штрих-коду.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the barcode is registered.

Example: pl

objectBarcodeIdstringRequired

Unique identifier of the barcode to be updated.

Example: 3279cadb-daeb-4c62-a2fa-8fdb105c85a4

Body

Request body for updating barcode details. Only the fields that need to be changed should be provided. At least one field must be present.

measureUnitNamestring · enumOptional

Unit of measurement.

Example: pcsPossible values:

includesinteger · min: 1 · max: 1000000Optional

Number of units in the package.

weightnumber · float · min: 0.01 · max: 1000000Optional

Weight of the barcode package in kilograms.

lengthnumber · float · min: 0.01 · max: 1000000Optional

Package length in centimeters.

heightnumber · float · min: 0.01 · max: 1000000Optional

Package height in centimeters.

widthnumber · float · min: 0.01 · max: 1000000Optional

Package width in centimeters.

Responses

201

Barcode successfully updated.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

403

Authorization Error. Access to the resource is forbidden.

application/json

404

Resource Not Found. The requested resource does not exist.

application/json

422

Unprocessable Entity. The request body contains validation errors.

application/json

patch

/fulfillment/{countrycode}/barcodes/{objectBarcodeId}

PATCH /v.1.0/fulfillment/{countrycode}/barcodes/{objectBarcodeId} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "measureUnitName": "pcs",
  "includes": 1,
  "weight": 2.02,
  "length": 5.05,
  "height": 4.45,
  "width": 30
}

{
  "measureUnitName": "pcs",
  "includes": 1,
  "weight": 2.02,
  "length": 5.05,
  "height": 4.45,
  "width": 30
}

Оновити план приймання

patch

/fulfillment/{countrycode}/inbound-plans/{documentId}

Цей endpoint використовується для оновлення параметрів існуючого плану приймання за його унікальним ідентифікатором.

План приймання має перебувати у статусі 1 (New). У тілі запиту потрібно передавати лише ті поля, які необхідно змінити.

🔸Усі поля необов’язкові, але для виконання оновлення потрібно передати щонайменше одне поле. У разі успіху API повертає оновлений об’єкт плану приймання.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the inbound plan is registered.

Example: pl

documentIdstringRequired

Unique identifier of the inbound plan.

Example: 392d0fdd-0f79-4d6c-8c05-cd3bc76432bd

Body

Request body for updating an inbound plan. Only the fields that need to be changed should be provided. At least one field must be present.

destWarehousestringOptional

Destination warehouse code.

deliveryTypeinteger · enumOptional

Delivery type(1 — Supplier delivery, 3 — Nova Post return, 7 — Nova Post delivery).

Possible values:

additionalInfostring · min: 2 · max: 255Optional

Additional information or comments.

Responses

201

The inbound plan was successfully updated.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

403

Authorization Error. Access to the resource is forbidden.

application/json

404

Resource Not Found. The requested resource does not exist.

application/json

422

Unprocessable Entity. The data in the request body is invalid.

application/json

patch

/fulfillment/{countrycode}/inbound-plans/{documentId}

PATCH /v.1.0/fulfillment/{countrycode}/inbound-plans/{documentId} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 233

{
  "destWarehouse": "TEST",
  "deliveryType": 3,
  "additionalInfo": "Change quantity and warehouse",
  "details": [
    {
      "objectId": "7599d0e2-813b-4889-aca4-c9056abd0d27",
      "quantity": 7
    },
    {
      "objectId": "cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe",
      "quantity": 15
    }
  ]
}

{
  "status": "1",
  "destWarehouse": "TEST",
  "deliveryType": 3,
  "additionalInfo": "Change quantity and warehouse",
  "details": [
    {
      "objectId": "7599d0e2-813b-4889-aca4-c9056abd0d27",
      "quantity": 7
    },
    {
      "objectId": "cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe",
      "quantity": 15
    }
  ]
}

Оновити дані клієнтського замовлення

patch

/fulfillment/{countrycode}/orders/{documentId}

Цей endpoint використовується для оновлення параметрів існуючого клієнтського замовлення, яке наразі перебуває у статусі 13 (Incomplete).

Запит дозволяє змінювати загальні параметри замовлення, список товарів, а також, якщо доставка здійснюється через Nova Post, встановлювати або оновлювати номер накладної.

🔸Усі поля необов’язкові, але для виконання оновлення потрібно передати щонайменше одне поле.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the order is registered.

Example: pl

documentIdstring · uuidRequired

Unique identifier of the client order.

Example: 7fe65529-5cd1-4333-93a8-c072aae70edc

Body

Request body for updating a client order. Only the fields that need to be changed should be provided. At least one field must be present.

destWarehousestringOptional

Code of the warehouse for dispatch.

deliveryTypeinteger · enumOptional

Delivery type (2 = Nova Post, 5 = Pickup).

Possible values:

waybilNumberstring · nullableOptional

Waybill number. Required if deliveryType = 2.

additionalInfostring · min: 2 · max: 255Optional

Additional info or comment.

Responses

201

The client order was successfully updated. The response contains the updated order object.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

403

Authorization Error. Access to the resource is forbidden.

application/json

404

Resource Not Found. The requested resource does not exist.

application/json

422

Unprocessable Entity. The request body contains invalid data.

application/json

patch

/fulfillment/{countrycode}/orders/{documentId}

PATCH /v.1.0/fulfillment/{countrycode}/orders/{documentId} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 177

{
  "destWarehouse": "Boyarka",
  "deliveryType": 5,
  "additionalInfo": "Update Info",
  "details": [
    {
      "objectId": "04adcd98-edd5-4428-9106-e6f43544d683",
      "quantity": 48,
      "price": 15.5,
      "sum": 34.5
    }
  ]
}

{
  "status": "13",
  "destWarehouse": "MAIN",
  "additionalInfo": "Update Info",
  "deliveryType": 5,
  "waybilNumber": null,
  "details": [
    {
      "objectId": "1b34e39f-5805-4510-94ca-1d88ea14739a",
      "quantity": 2,
      "price": 10.5,
      "sum": 30.5
    },
    {
      "objectId": "04adcd98-edd5-4428-9106-e6f43544d683",
      "quantity": 48,
      "price": 15.5,
      "sum": 34.5
    }
  ]
}

Перевірити статус плану приймання

get

/fulfillment/{countrycode}/inbound-plans/status

Цей endpoint використовується для отримання статусів одного або кількох планів приймання.

Підтримує фільтрацію через query-параметри, зокрема за ID документа, зовнішніми номерами, кодами складів і діапазоном дат.

🔹Якщо параметри фільтрації не передані, у відповіді повертаються останні плани приймання.

🔸Цей GET запит не повертає помилку, якщо використано некоректні, неіснуючі або частково невалідні значення фільтрів. У таких випадках система:

Ігнорує невалідні або порожні значення фільтрів без повернення помилки.
Повертає порожній масив documents, якщо жоден план приймання не відповідає умовам запиту.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where inbound plans are registered.

Example: pl

Query parameters

pageintegerOptional

Page number (each page returns up to 25 records).

Example: 1

documentIds[]string · uuid[]Optional

List of inbound plan IDs.

externalNumbers[]string[]Optional

List of inbound plan external numbers.

warehouseIds[]string[]Optional

List of warehouse codes.

startDatestring · date-timeOptional

Start date of search (ISO 8601).

Example: 2025-05-05T00:00:00Z

endDatestring · date-timeOptional

End date of search (ISO 8601).

Example: 2025-05-10T00:00:00Z

Responses

201

Data retrieved successfully.

application/json

get

/fulfillment/{countrycode}/inbound-plans/status

GET /v.1.0/fulfillment/{countrycode}/inbound-plans/status HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

201

Data retrieved successfully.

{
  "documents": [
    {
      "documentId": "28c16a4e-ad76-4c21-83bf-a7d8de8a4879",
      "externalNumber": "PL-249400",
      "status": 1,
      "destWarehouse": "MAIN",
      "items": [
        {
          "objectId": "2f1d92e7-0e92-46eb-bd9c-888ec3a9789c",
          "expectedQuantity": 25,
          "receivedQuantity": null,
          "expiryDate": null,
          "measureUnitName": null,
          "condition": null,
          "sku": "9948610846581684151031"
        }
      ]
    },
    {
      "documentId": "745a5e03-93b5-4332-9f5f-64ba0329102d",
      "externalNumber": "PL-169084",
      "status": 10,
      "destWarehouse": "2",
      "items": []
    }
  ],
  "page": 1,
  "pages": 9
}

Створити план приймання

post

/fulfillment/{countrycode}/inbound-plans

Цей endpoint дозволяє створити новий план приймання для отримання товарів на вказаний склад. План може містити одну або кілька товарних позицій.

У разі успіху API повертає створений план приймання з його унікальним ідентифікатором і початковим статусом.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the inbound plan is created.

Example: pl

Body

Request body for creating an inbound plan. All required fields must be provided.

externalNumberstring · min: 2 · max: 72Required

Document number in the client's system.

guidstring · min: 2 · max: 72Optional

Unique document ID in the client's system.

destWarehousestring · min: 2 · max: 255Required

Destination warehouse code.

deliveryTypeinteger · enumRequired

Delivery type (1 — Supplier, 3 — Return, 7 — Nova Post).

Possible values:

additionalInfostring · min: 2 · max: 255Optional

Additional information or comment.

Responses

201

Request successful. Inbound plan was created.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

422

Unprocessable Entity. Validation errors.

application/json

post

/fulfillment/{countrycode}/inbound-plans

POST /v.1.0/fulfillment/{countrycode}/inbound-plans HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 335

{
  "externalNumber": "PL-116252",
  "guid": "123e4567-e89b-12d3-a456-426614174000",
  "destWarehouse": "TEST",
  "deliveryType": 3,
  "additionalInfo": "Поставка згідно замовлення #154",
  "details": [
    {
      "objectId": "776cfd22-1a20-4def-82dd-b14d2e6fba1f",
      "quantity": 10
    },
    {
      "objectId": "08adb9c8-4819-4480-87aa-54538563269e",
      "quantity": 25
    }
  ]
}

{
  "documentId": "e52937bd-bdbc-499c-bbf8-2cbfeab51ee5",
  "status": "1",
  "externalNumber": "PL-437763",
  "guid": "123e4567-e89b-12d3-a456-426614174000",
  "destWarehouse": "Boyarka",
  "deliveryType": 3,
  "additionalInfo": "Поставка згідно замовлення #154",
  "details": [
    {
      "objectId": "776cfd22-1a20-4def-82dd-b14d2e6fba1f",
      "quantity": 10
    },
    {
      "objectId": "08adb9c8-4819-4480-87aa-54538563269e",
      "quantity": 25
    }
  ]
}

Скасувати план приймання

patch

/fulfillment/{countrycode}/inbound-plans/{documentId}/cancel

Цей endpoint скасовує існуючий план приймання, який наразі перебуває у статусі 1 (New).

Після скасування план приймання переходить у статус 10 (Canceled) і виключається з подальшої обробки.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the inbound plan is registered.

Example: pl

documentIdstring · uuidRequired

Unique identifier of the inbound plan.

Example: e52937bd-bdbc-499c-bbf8-2cbfeab51ee5

Responses

200

The inbound plan was successfully canceled.

application/json

documentIdstringRequired

Unique identifier of the inbound plan.

statusinteger · enumRequired

Current status of the inbound plan.

Possible values:

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

403

Authorization Error. Access to the resource is forbidden.

application/json

404

Resource Not Found. The requested resource does not exist.

application/json

422

Unprocessable Entity. Validation errors.

application/json

patch

/fulfillment/{countrycode}/inbound-plans/{documentId}/cancel

PATCH /v.1.0/fulfillment/{countrycode}/inbound-plans/{documentId}/cancel HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "documentId": "e52937bd-bdbc-499c-bbf8-2cbfeab51ee5",
  "status": 10
}

Створити товар

post

/fulfillment/{countrycode}/goods/multiple

Цей endpoint використовується для створення запису товару, який може бути доданий до плану приймання або до замовлення.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code for which the goods are being created.

Example: pl

Body

Responses

201

Request successful. Goods were created.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

422

Unprocessable Entity. The request body contains validation errors.

application/json

post

/fulfillment/{countrycode}/goods/multiple

POST /v.1.0/fulfillment/{countrycode}/goods/multiple HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 255

{
  "goods": [
    {
      "sku": "9948610846581684151024",
      "goodsUnitName": "string",
      "goodsUnitFullName": "string",
      "price": 1000,
      "inventExpireDays": 1
    },
    {
      "sku": "9948610846581684151045",
      "goodsUnitName": "string",
      "goodsUnitFullName": "string",
      "price": 200,
      "inventExpireDays": null
    }
  ]
}

{
  "goods": [
    {
      "objectId": "69dfb650-92f9-4d27-a03c-a39e0a099374",
      "sku": "9948610846581684151024",
      "goodsUnitName": "string",
      "goodsUnitFullName": "string",
      "price": 1000,
      "inventExpireDays": 1
    },
    {
      "objectId": "b1fc6f3d-edaa-49e5-aa39-88890c367387",
      "sku": "9948610846581684151045",
      "goodsUnitName": "string",
      "goodsUnitFullName": "string",
      "price": 200,
      "inventExpireDays": null
    }
  ]
}

Створити штрихкод

post

/fulfillment/{countrycode}/goods/{objectId}/barcodes/multiple

Цей endpoint використовується для створення одного або кількох штрихкодів, пов’язаних із конкретним товаром. Дані штрихкодів передаються масивом, що дозволяє створити кілька штрихкодів в одному запиті.

У разі успіху API повертає всі створені штрихкоди з їхніми унікальними ідентифікаторами та параметрами, вказаними в запиті.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the goods are registered.

Example: pl

objectIdstringRequired

Unique identifier of the goods for which barcodes are created.

Example: 7c5438ad-0ee6-11f0-9f10-42010adefd36

Body

Responses

201

Barcode(s) successfully created.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

422

Unprocessable Entity. Validation errors in the request body.

application/json

post

/fulfillment/{countrycode}/goods/{objectId}/barcodes/multiple

POST /v.1.0/fulfillment/{countrycode}/goods/{objectId}/barcodes/multiple HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "barcodes": [
    {
      "barCode": "string",
      "measureUnitName": "pcs",
      "includes": 1,
      "weight": 0.01,
      "length": 0.01,
      "height": 0.01,
      "width": 0.01
    }
  ]
}

{
  "barcodes": [
    {
      "objectBarcodeId": "3279cadb-daeb-4c62-a2fa-8fdb105c85a4",
      "barCode": "string",
      "measureUnitName": "pcs",
      "includes": 1,
      "weight": 0.01,
      "length": 0.01,
      "height": 0.01,
      "width": 0.01
    }
  ]
}

Додати товари до плану приймання

post

/fulfillment/{countrycode}/inbound-plans/{documentId}/details

Цей endpoint дозволяє додавати одну або кілька товарних позицій до вже створеного плану приймання, який перебуває у статусі 1 (New).

Операція розширює список товарів у наявному плані приймання без створення нового документа.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the inbound plan is registered.

Example: pl

documentIdstringRequired

Unique identifier of the inbound plan.

Example: e52937bd-bdbc-499c-bbf8-2cbfeab51ee5

Body

Request body for adding goods to an existing inbound plan. The details array must contain at least one product item.

Responses

201

The inbound plan was successfully updated.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

422

Unprocessable Entity. The request body contains invalid data.

application/json

post

/fulfillment/{countrycode}/inbound-plans/{documentId}/details

POST /v.1.0/fulfillment/{countrycode}/inbound-plans/{documentId}/details HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 144

{
  "details": [
    {
      "objectId": "7599d0e2-813b-4889-aca4-c9056abd0d27",
      "quantity": 5
    },
    {
      "objectId": "cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe",
      "quantity": 10
    }
  ]
}

{
  "details": [
    {
      "objectId": "7599d0e2-813b-4889-aca4-c9056abd0d27",
      "quantity": 5
    },
    {
      "objectId": "cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe",
      "quantity": 10
    }
  ]
}

Видалити товари з плану приймання

post

/fulfillment/{countrycode}/inbound-plans/{documentId}/details/multiple-delete

Цей endpoint дозволяє видаляти один або кілька товарів з існуючого плану приймання, який перебуває у статусі 1 (New).

Операція видаляє зазначені товарні позиції з плану приймання без видалення самого плану.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the inbound plan is registered.

Example: pl

documentIdstring · uuidRequired

Unique identifier of the inbound plan.

Example: e52937bd-bdbc-499c-bbf8-2cbfeab51ee5

Body

Request body for deleting goods from an inbound plan. The details array must contain at least one product item.

Responses

201

The inbound plan was successfully updated.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

422

Unprocessable Entity. The request body contains invalid data.

application/json

post

/fulfillment/{countrycode}/inbound-plans/{documentId}/details/multiple-delete

POST /v.1.0/fulfillment/{countrycode}/inbound-plans/{documentId}/details/multiple-delete HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "details": [
    {
      "objectId": "7599d0e2-813b-4889-aca4-c9056abd0d27"
    },
    {
      "objectId": "cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe"
    }
  ]
}

{
  "details": [
    {
      "objectId": "7599d0e2-813b-4889-aca4-c9056abd0d27"
    },
    {
      "objectId": "cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe"
    }
  ]
}

Створити замовлення

post

/fulfillment/{countrycode}/orders

Цей endpoint використовується для створення нового клієнтського замовлення на відправлення товарів зі складу.

Підтримуються два сценарії доставки:

Доставка Nova Post — необхідно вказати номер міжнародної експрес-накладної, який клієнт генерує заздалегідь.
Самовивіз клієнтом — замовлення створюється без зазначення номера міжнародної експрес-накладної.

Якщо запит сформований коректно та всі вимоги виконані, замовлення створюється з одним із таких статусів:

1 (New) — коли всі товари є в наявності на складі
13 (Incomplete) — коли частина товарів недоступна повністю або частково

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the order is created.

Example: pl

Body

Request body for creating a customer order. All required fields must be provided.

externalNumberstring · min: 2 · max: 72Required

Customer's internal order number.

destWarehousestring · min: 2 · max: 255Required

Warehouse code.

deliveryTypeinteger · enumRequired

Delivery type(2 — Nova Post, 5 — Customer pickup).

Possible values:

waybilNumberstringOptional

International express waybill number.

additionalInfostring · min: 2 · max: 255Optional

Additional information or comment.

Responses

201

Request successful. Returns the full order object with documentId and initial status.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

422

Unprocessable Entity. The data in the request body is invalid.

application/json

post

/fulfillment/{countrycode}/orders

POST /v.1.0/fulfillment/{countrycode}/orders HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 256

{
  "externalNumber": "ORDER-26062037-16",
  "destWarehouse": "Boyarka",
  "deliveryType": 5,
  "additionalInfo": "Замовлення зі складу в Боярці",
  "details": [
    {
      "objectId": "1b34e39f-5805-4510-94ca-1d88ea14739a",
      "quantity": 2,
      "price": 10.5,
      "sum": 30.5
    }
  ]
}

{
  "documentId": "4f22ed76-8f4f-422f-bf24-f13d165e6bf2",
  "status": "13",
  "externalNumber": "ORDER-26062037-16",
  "destWarehouse": "MAIN",
  "additionalInfo": "Замовлення зі складу в Боярці",
  "deliveryType": 5,
  "waybilNumber": null,
  "details": [
    {
      "objectId": "1b34e39f-5805-4510-94ca-1d88ea14739a",
      "quantity": 2,
      "price": 10.5,
      "sum": 30.5
    }
  ]
}

Отримати деталі замовлення

get

/fulfillment/{countrycode}/orders/{documentId}/details

Цей endpoint використовується для отримання детальної інформації про конкретне клієнтське замовлення за його documentId.

У відповіді повертається повна деталізація замовлених товарів, зокрема планова й фактична кількість, стан товару та серійні номери (за наявності).

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the order is registered.

Example: pl

documentIdstring · uuidRequired

Unique identifier of the client order.

Example: 22be2de9-47ae-4438-9cec-d55a0d4bd387

Responses

201

Data successfully retrieved. The response returns the full breakdown of the order.

application/json

404

Resource Not Found. The requested resource does not exist.

application/json

get

/fulfillment/{countrycode}/orders/{documentId}/details

GET /v.1.0/fulfillment/{countrycode}/orders/{documentId}/details HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "documentId": "22be2de9-47ae-4438-9cec-d55a0d4bd387",
  "externalNumber": "27062025-07",
  "items": [
    {
      "objectId": "08c6c4c9-3258-11f0-befc-42010ade0e9e",
      "sku": "Regression4_1",
      "measureUnitName": "шт.",
      "plannedQuantity": 1,
      "actualQuantity": 1,
      "condition": 0,
      "series": []
    }
  ]
}

Додати товари до клієнтського замовлення

post

/fulfillment/{countrycode}/orders/{documentId}/details

Цей endpoint використовується для додавання нових товарів до існуючого клієнтського замовлення, яке наразі перебуває у статусі 13 (Incomplete).

Якщо додані товари доступні в достатній кількості, статус замовлення автоматично змінюється на 1 (New).

Це дозволяє редагувати існуюче замовлення та відновити його обробку без створення нового документа.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the order is registered.

Example: pl

documentIdstring · uuidRequired

Unique identifier of the client order.

Example: e2d29580-457f-4562-88bf-b5e28aea9f88

Body

Request body for adding goods to an existing client order. At least one product item must be provided.

Responses

201

Order details updated.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

422

Unprocessable Entity. The data in the request body is invalid.

application/json

post

/fulfillment/{countrycode}/orders/{documentId}/details

POST /v.1.0/fulfillment/{countrycode}/orders/{documentId}/details HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 98

{
  "details": [
    {
      "objectId": "ab0b584d-c269-41b3-a8d2-b718b96edf3b",
      "quantity": 5,
      "price": 10,
      "sum": 50
    }
  ]
}

{
  "documentId": "e2d29580-457f-4562-88bf-b5e28aea9f88",
  "status": 13
}

Перевірити статус замовлення

get

/fulfillment/{countrycode}/orders/status

Цей endpoint використовується для отримання інформації про статуси одного або кількох клієнтських замовлень з можливістю додаткової фільтрації.

🔹Якщо параметри фільтрації не передані, у відповіді повертаються останні клієнтські замовлення.

🔸Цей GET запит не повертає помилку, якщо використано некоректні, неіснуючі або частково невалідні значення фільтрів. У таких випадках невалідні або порожні фільтри ігноруються, а якщо жодне замовлення не відповідає критеріям, повертається порожній масив.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the orders are registered.

Example: pl

Query parameters

pageintegerOptional

Page number (each page includes up to 25 objects).

Example: 1

documentIdsstring · uuid[]Optional

List of order identifiers.

externalNumbersstring[]Optional

List of client order numbers.

warehouseIdsstring[]Optional

List of warehouse codes.

startDatestring · date-timeOptional

Start date in ISO 8601 format.

Example: 2025-05-05T00:00:00Z

endDatestring · date-timeOptional

End date in ISO 8601 format.

Example: 2025-05-05T23:59:59Z

Responses

201

Request successful. Returns an array of client orders that match the filtering criteria.

application/json

get

/fulfillment/{countrycode}/orders/status

GET /v.1.0/fulfillment/{countrycode}/orders/status HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

201

Request successful. Returns an array of client orders that match the filtering criteria.

{
  "documents": [
    {
      "documentId": "ab73a718-24fe-11f0-af17-42010ade0e84",
      "externalNumber": "CO-01-01",
      "status": 1,
      "statusTime": "2025-08-01T09:49:38+00:00",
      "waybilNumber": "",
      "destWarehouse": "MAIN"
    }
  ],
  "page": 1,
  "pages": 1
}

Скасувати клієнтське замовлення

patch

/fulfillment/{countrycode}/orders/{documentId}/cancel

Цей endpoint використовується для скасування раніше створеного клієнтського замовлення, яке наразі перебуває у статусі 13 (Incomplete).

Після скасування замовлення переходить у статус 10 (Canceled) і виключається з подальшої обробки.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the client order is registered.

Example: pl

documentIdstring · uuidRequired

Unique identifier of the client order.

Example: 7fe65529-5cd1-4333-93a8-c072aae70edc

Responses

201

The client order was successfully canceled. Returns the documentId and new status ("10") of the canceled order.

application/json

400

Syntax Error. The request has incorrect format or syntax.

application/json

403

Authorization Error. Access to the resource is forbidden.

application/json

404

Resource Not Found. The requested resource does not exist.

application/json

422

Unprocessable Entity. The request body contains invalid data.

application/json

patch

/fulfillment/{countrycode}/orders/{documentId}/cancel

PATCH /v.1.0/fulfillment/{countrycode}/orders/{documentId}/cancel HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "documentId": "7fe65529-5cd1-4333-93a8-c072aae70edc",
  "status": 10
}

Видалити товари з клієнтського замовлення

post

/fulfillment/{countrycode}/orders/{documentId}/details/multiple-delete

Цей endpoint використовується для видалення одного або кількох товарів із клієнтського замовлення, яке наразі перебуває у статусі 13 (Incomplete).

Якщо з такого замовлення видаляється товар із недостатнім залишком на складі, статус замовлення автоматично змінюється на 1 (New). Це дозволяє оновити замовлення та передати його в обробку без створення нового документа.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the order is registered.

Example: pl

documentIdstring · uuidRequired

Unique identifier of the client order.

Example: 7921dccd-9004-472e-a410-c9573a5edadd

Body

Request body for deleting goods from a client order. At least one item must be provided.

Responses

201

The client order was successfully updated. Returns the updated order status.

application/json

400

Bad Request. The request has an incorrect format or invalid syntax.

application/json

403

Authorization Error. Access to the resource is forbidden.

application/json

404

Resource Not Found. The requested resource does not exist.

application/json

422

Unprocessable Entity. The data in the request body is invalid.

application/json

post

/fulfillment/{countrycode}/orders/{documentId}/details/multiple-delete

POST /v.1.0/fulfillment/{countrycode}/orders/{documentId}/details/multiple-delete HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "details": [
    {
      "objectId": "1b34e39f-5805-4510-94ca-1d88ea14739a"
    }
  ]
}

{
  "documentId": "7921dccd-9004-472e-a410-c9573a5edadd",
  "status": 13
}

Перевірити залишки товарів на складі

get

/fulfillment/{countrycode}/stock-remains

Цей endpoint використовується для отримання інформації про поточні залишки товарів на fulfillment-складах.

Дає можливість перевірити, скільки одиниць кожного товару:

знаходиться на складі,
зарезервовано в активних замовленнях,
доступно для нових замовлень.

Можна застосовувати фільтри за товаром, складом, станом або датою. Якщо фільтри не передані, повертаються всі залишки товарів клієнта на всіх складах.

Некоректні або невідомі значення фільтрів ігноруються та не викликають помилок.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Path parameters

countrycodestringRequired

Country code where the fulfillment warehouses are located.

Example: pl

Query parameters

pageintegerOptional

Page number (each page returns up to 25 records).

Example: 1

objectIds[]string · uuid[]Optional

List of goods IDs (UUID) to filter by.

objectArts[]string[]Optional

List of product article numbers (SKUs) to filter by.

objectTitle[]string[]Optional

List of product names to filter by.

warehouseIds[]string[]Optional

Warehouse codes to filter by. If empty, all warehouses are included.

remainDatestring · date-timeOptional

Date up to which to consider all receipts. Stock is calculated as of this date/time. Format: YYYY-MM-DD or full ISO 8601 timestamp.

Example: 2025-05-05T00:00:00Z

conditionstring · enumOptional

Filter by stock condition:

0 — good (saleable),
1 — damaged (unsaleable). If omitted, all conditions are included.

Possible values:

Responses

201

Data retrieved successfully. Returns current stock remains per goods and warehouse.

application/json

403

Authorization Error. Access to the resource is forbidden.

application/json

404

Resource Not Found. The requested resource does not exist.

application/json

get

/fulfillment/{countrycode}/stock-remains

GET /v.1.0/fulfillment/{countrycode}/stock-remains HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "goodsStock": [
    {
      "objectId": "04adcd98-edd5-4428-9106-e6f43544d683",
      "sku": "RestRegression-02",
      "measureUnitName": "шт",
      "quantity": 150,
      "availableQuantity": 149,
      "reservedQuantity": 1,
      "destWarehouse": "War-FF",
      "expiryDate": "2025-12-31"
    },
    {
      "objectId": "04adcd98-edd5-4428-9106-e6f43544d683",
      "sku": "RestRegression-02",
      "measureUnitName": "шт",
      "quantity": 150,
      "availableQuantity": 149,
      "reservedQuantity": 1,
      "destWarehouse": "000063146",
      "expiryDate": "2025-12-31"
    }
  ],
  "page": 1,
  "pages": 1
}

ПопередняWebhooks НаступнаОплата послуг доставки

Останнє оновлення 11 днів тому