Фулфілмент

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

post

/fulfillment/{countrycode}/v1/goods/multiple

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

Authorizations

AuthorizationstringRequired

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

Bodyobject[]

skustring · min: 2 · max: 72Required

Унікальний артикул товару в інформаційній системі клієнта.

Не чутливий до регістру.

goodsUnitNamestring · min: 2 · max: 255Required

Коротка назва товару.

goodsUnitFullNamestring · min: 2 · max: 255 · nullableOptional

Повна назва товару.

pricenumber · float · min: 0.01 · max: 100000000Required

Ціна за одиницю товару.

inventExpireDaysinteger · min: 1 · max: 15000 · nullableOptional

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

Responses

207

Multi-Status. Товари оброблено.

application/json

errorsobjectRequired

Помилки валідації для товарів, які не вдалося створити.

post/fulfillment/{countrycode}/v1/goods/multiple

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

[
  {
    "sku": "SKU-COFFEE-001",
    "goodsUnitName": "Coffee 250g",
    "goodsUnitFullName": "Coffee Beans Arabica Premium 250g",
    "price": 150.75,
    "inventExpireDays": 365
  },
  {
    "sku": "SKU-COFFEE-002",
    "goodsUnitName": "Coffee 500g",
    "goodsUnitFullName": null,
    "price": 750,
    "inventExpireDays": null
  }
]

207

Multi-Status. Товари оброблено.

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "sku": "SKU-COFFEE-001",
      "goodsUnitName": "Coffee 250g",
      "goodsUnitFullName": "Coffee Beans Arabica Premium 250g",
      "price": 150.75,
      "inventExpireDays": 365,
      "createdAt": "2026-05-09T14:32:00+00:00",
      "updatedAt": "2026-05-09T14:32:00+00:00"
    }
  ],
  "errors": {}
}

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

patch

/fulfillment/{countrycode}/v1/goods/{id}

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор товару, дані якого потрібно оновити.

Example: 550e8400-e29b-41d4-a716-446655440000

Body

Тіло запиту для оновлення даних товару. Необхідно передавати лише поля, значення яких потрібно змінити. Має бути вказане щонайменше одне поле.

goodsUnitNamestring · min: 2 · max: 255Optional

Коротка назва товару.

goodsUnitFullNamestring · min: 2 · max: 255Optional

Повна назва товару.

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

Ціна за одиницю товару.

inventExpireDaysinteger · min: 1 · max: 15000 · nullableOptional

Термін придатності у днях. Передайте null, щоб скасувати облік термінів придатності.

Responses

200

Запит успішно виконано. Дані товару оновлено.

application/json

patch/fulfillment/{countrycode}/v1/goods/{id}

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

{
  "goodsUnitName": "Coffee 250g Premium",
  "price": 180
}

200

Запит успішно виконано. Дані товару оновлено.

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "sku": "SKU-COFFEE-001",
    "goodsUnitName": "Coffee 250g Premium",
    "goodsUnitFullName": "Coffee Beans Arabica Premium 250g",
    "price": 180,
    "inventExpireDays": 365,
    "createdAt": "2026-04-01T10:30:00+00:00",
    "updatedAt": "2026-07-31T12:00:00+00:00"
  }
}

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

post

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

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

objectIdstring · uuidRequired

Унікальний ідентифікатор товару, для якого створюються штрихкоди.

Example: 550e8400-e29b-41d4-a716-446655440000

Bodyobject[]

barCodestring · min: 2 · max: 72Required

Значення штрихкоду.

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

Вага в кілограмах.

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

Довжина в сантиметрах.

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

Висота в сантиметрах.

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

Ширина в сантиметрах.

Responses

207

Multi-Status. Штрихкоди оброблено.

application/json

errorsobjectRequired

Помилки валідації для штрихкодів, які не вдалося створити.

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

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

[
  {
    "barCode": "1234567890123",
    "weight": 10.5,
    "length": 40,
    "height": 30,
    "width": 20
  }
]

207

Multi-Status. Штрихкоди оброблено.

{
  "data": [
    {
      "id": "59571a13-8051-4d21-b3ba-71663074548c",
      "barcode": "1234567890123",
      "measureUnitName": "шт",
      "includes": 1,
      "weight": 10.5,
      "length": 40,
      "height": 30,
      "width": 20,
      "createdAt": "2026-08-01T10:00:00+00:00",
      "updatedAt": "2026-08-01T10:00:00+00:00"
    }
  ],
  "errors": {}
}

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

patch

/fulfillment/{countrycode}/v1/barcodes/{id}

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

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор штрихкоду, який необхідно оновити.

Example: cadeb5e7-a6b2-45d0-af36-60eae53454df

Body

Тіло запиту для оновлення даних штрихкоду. Необхідно передавати лише поля, значення яких потрібно змінити. Має бути вказане щонайменше одне поле.

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

Вага в кілограмах.

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

Довжина в сантиметрах.

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

Висота в сантиметрах.

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

Ширина в сантиметрах.

Responses

200

Штрихкод успішно оновлено.

application/json

patch/fulfillment/{countrycode}/v1/barcodes/{id}

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

{
  "weight": 2.5,
  "length": 30,
  "height": 20,
  "width": 15
}

200

Штрихкод успішно оновлено.

{
  "data": {
    "id": "cadeb5e7-a6b2-45d0-af36-60eae53454df",
    "barcode": "4820024220506",
    "measureUnitName": "шт",
    "includes": 1,
    "weight": 2.5,
    "length": 30,
    "height": 20,
    "width": 15,
    "createdAt": "2026-04-01T10:30:00+00:00",
    "updatedAt": "2026-05-08T14:00:00+00:00"
  }
}

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

post

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

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

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

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

Authorizations

AuthorizationstringRequired

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

Body

Тіло запиту для створення плану приймання. Необхідно передати всі обов’язкові поля.

externalNumberstring · min: 2 · max: 72Required

Унікальний номер документа в інформаційній системі клієнта.

guidstring · min: 2 · max: 72Optional

Унікальний GUID документа в інформаційній системі клієнта.

destWarehousestring · min: 2 · max: 255Required

Код складу призначення.

deliveryTypeinteger · enumRequired

Тип доставки (1 — Supplier delivery, 3 — Nova Post return, 7 — Nova Post delivery).

Possible values:

additionalInfostring · max: 255Optional

Коментар.

Responses

201

Запит успішно виконано. План приймання створено.

application/json

post/fulfillment/{countrycode}/v1/inbound-plans

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

{
  "externalNumber": "INB-2026-001",
  "guid": "8f14e45f-e1ff-4a90-b8a2-657d1c10a790",
  "destWarehouse": "Boyarka",
  "deliveryType": 1,
  "additionalInfo": "Прийом поповнення",
  "details": [
    {
      "objectId": "3279cadb-daeb-4c62-a2fa-8fdb105c85a4",
      "quantity": 100
    }
  ]
}

201

Запит успішно виконано. План приймання створено.

{
  "data": {
    "id": "00f9c83e-4b2a-4d1f-9c9e-1f2c3d4e5f60",
    "externalNumber": "INB-2026-001",
    "guid": "8f14e45f-e1ff-4a90-b8a2-657d1c10a790",
    "destWarehouse": "Boyarka",
    "deliveryType": 1,
    "additionalInfo": "Прийом поповнення",
    "createdAt": "2026-08-01T10:00:00+00:00",
    "updatedAt": "2026-08-01T10:00:00+00:00",
    "details": [
      {
        "id": "3279cadb-daeb-4c62-a2fa-8fdb105c85a4",
        "objectId": "0519dba3-e1df-4379-a3b9-b544a4f22376",
        "quantity": 100
      }
    ]
  }
}

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

post

/fulfillment/{countrycode}/v1/inbound-plans/{id}/details

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор плану приймання.

Example: d1e2f3a4-0000-0000-0000-000000000001

Bodyobject[]

objectIdstring · uuidRequired

UUID товару в WMS (Warehouse Management System).

quantityinteger · min: 1 · max: 1000000Required

Кількість одиниць товару.

Responses

201

Запит успішно виконано. Товарні позиції додано до плану приймання.

application/json

idstring · uuidRequired

Унікальний ідентифікатор позиції плану приймання.

objectIdstring · uuidRequired

UUID товару в WMS (Warehouse Management System).

quantityintegerRequired

Кількість одиниць товару.

post/fulfillment/{countrycode}/v1/inbound-plans/{id}/details

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

[
  {
    "objectId": "ITEM001",
    "quantity": 10
  },
  {
    "objectId": "ITEM002",
    "quantity": 5
  }
]

201

Запит успішно виконано. Товарні позиції додано до плану приймання.

[
  {
    "id": "0519dba3-e1df-4379-a3b9-b544a4f22376",
    "objectId": "ITEM001",
    "quantity": 10
  },
  {
    "id": "0620dba3-e1df-4379-a3b9-b544a4f33487",
    "objectId": "ITEM002",
    "quantity": 5
  }
]

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

patch

/fulfillment/{countrycode}/v1/inbound-plans/{id}

Цей ресурс призначений для оновлення параметрів плану приймання, що перебуває у статусі 1 (Новий).

Метод дозволяє оновлювати склад призначення, тип доставки, коментар, а також кількість для існуючих товарних позицій.

🔸Додавання або видалення товарних позицій через цей метод не підтримується.

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор плану приймання.

Example: d1e2f3a4-0000-0000-0000-000000000001

Body

Тіло запиту для оновлення плану приймання. Необхідно передавати лише поля, значення яких потрібно змінити. Має бути вказане щонайменше одне поле.

destWarehousestring · min: 2 · max: 255Optional

Код складу призначення.

deliveryTypeinteger · enumOptional

Тип доставки (1 — Supplier delivery, 3 — Nova Post return, 7 — Nova Post delivery).

Possible values:

additionalInfostring · max: 255Optional

Коментар.

Responses

200

Запит успішно виконано. План приймання оновлено.

application/json

patch/fulfillment/{countrycode}/v1/inbound-plans/{id}

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

{
  "destWarehouse": "Boyarka",
  "deliveryType": 1,
  "additionalInfo": "Оновлений коментар",
  "details": [
    {
      "objectId": "ITEM001",
      "quantity": 10
    },
    {
      "objectId": "ITEM002",
      "quantity": 7
    }
  ]
}

200

Запит успішно виконано. План приймання оновлено.

{
  "data": {
    "id": "d1e2f3a4-0000-0000-0000-000000000001",
    "externalNumber": "INV-2026-00042",
    "guid": "e5f6-7890-abcd",
    "destWarehouse": "Boyarka",
    "deliveryType": 1,
    "additionalInfo": "Оновлений коментар",
    "createdAt": "2026-05-18T10:00:00+00:00",
    "updatedAt": "2026-05-18T12:30:00+00:00",
    "details": [
      {
        "id": "det-1",
        "objectId": "ITEM001",
        "quantity": 10
      },
      {
        "id": "det-2",
        "objectId": "ITEM002",
        "quantity": 7
      }
    ]
  }
}

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

post

/fulfillment/{countrycode}/v1/inbound-plans/{id}/details/multiple-delete

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор плану приймання.

Example: d1e2f3a4-0000-0000-0000-000000000001

Bodyobject[]

objectIdstring · uuidRequired

UUID товару в WMS (Warehouse Management System).

Responses

200

Запит успішно виконано. Товарні позиції видалено з плану приймання.

application/json

idstring · uuidRequired

Унікальний ідентифікатор позиції плану приймання.

objectIdstring · uuidRequired

UUID товару в WMS (Warehouse Management System).

quantityintegerRequired

Кількість одиниць товару.

post/fulfillment/{countrycode}/v1/inbound-plans/{id}/details/multiple-delete

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

[
  {
    "objectId": "ITEM-02"
  },
  {
    "objectId": "ITEM-03"
  }
]

200

Запит успішно виконано. Товарні позиції видалено з плану приймання.

[
  {
    "id": "6119dba3-e1df-4379-a3b9-b544a4f22673",
    "objectId": "ITEM-01",
    "quantity": 10
  },
  {
    "id": "7120dba3-e1df-4379-a3b9-b544a4f33784",
    "objectId": "ITEM-04",
    "quantity": 10
  }
]

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

patch

/fulfillment/{countrycode}/v1/inbound-plans/{id}/cancel

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

У разі успіху план приймання переходить у статус 10 (Canceled), а API повертає оновлений об'єкт плану приймання.

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор плану приймання.

Example: 00f9c83e-4b2a-4d1f-9c9e-1f2c3d4e5f60

Responses

200

Запит успішно виконано. План приймання скасовано.

application/json

patch/fulfillment/{countrycode}/v1/inbound-plans/{id}/cancel

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

200

Запит успішно виконано. План приймання скасовано.

{
  "data": {
    "id": "00f9c83e-4b2a-4d1f-9c9e-1f2c3d4e5f60",
    "externalNumber": "12345",
    "guid": "8f14e45f-e1ff-4a90-b8a2-657d1c10a790",
    "destWarehouse": "Boyarka",
    "deliveryType": 1,
    "additionalInfo": "Прийом товарів для поповнення запасів",
    "createdAt": "2026-05-09T14:32:00+00:00",
    "updatedAt": "2026-05-09T14:32:00+00:00",
    "details": [
      {
        "id": "3279cadb-daeb-4c62-a2fa-8fdb105c85a4",
        "objectId": "0519dba3-e1df-4379-a3b9-b544a4f22376",
        "quantity": 1
      }
    ]
  }
}

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

post

/fulfillment/{countrycode}/v1/orders/multiple

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

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

• Відвантаження Nova Post — необхідно вказати номер міжнародної експрес-накладної.
• Самовивіз — замовлення створюється без номера міжнародної експрес-накладної.

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

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

Authorizations

AuthorizationstringRequired

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

Bodyobject[]

externalNumberstring · min: 2 · max: 72Required

Внутрішній номер замовлення клієнта.

destWarehousestring · min: 2 · max: 255Required

Код складу відвантаження.

deliveryTypeinteger · enumRequired

Тип доставки (1 — Nova Post, 2 — Самовивіз).

Possible values:

waybillNumberstringOptional

Номер міжнародної експрес-накладної. Обов'язковий для deliveryType = 1.

additionalInfostring · max: 255Optional

Додаткова інформація або коментар.

Responses

207

Запит виконано. Для кожного замовлення повертається результат створення.

application/json

errorsobjectRequired

Помилки створення окремих замовлень.

post/fulfillment/{countrycode}/v1/orders/multiple

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

[
  {
    "externalNumber": "ORD-20260801-001",
    "destWarehouse": "WMS-UK-01",
    "deliveryType": 1,
    "waybillNumber": "20450012345678",
    "additionalInfo": "Терміново",
    "details": [
      {
        "objectId": "0519dba3-e1df-4379-a3b9-b544a4f22376",
        "quantity": 1,
        "price": 150.75,
        "sum": 150.75
      }
    ]
  }
]

207

Запит виконано. Для кожного замовлення повертається результат створення.

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "externalNumber": "ORD-20260801-001",
      "destWarehouse": "WMS-UK-01",
      "deliveryType": 1,
      "waybillNumber": "20450012345678",
      "additionalInfo": "Терміново",
      "createdAt": "2026-08-01T10:00:00+00:00",
      "updatedAt": "2026-08-01T10:00:00+00:00",
      "details": [
        {
          "id": "a1b2c3d4-0000-0000-0000-000000000001",
          "objectId": "0519dba3-e1df-4379-a3b9-b544a4f22376",
          "quantity": 1,
          "price": 150.75,
          "sum": 150.75
        }
      ]
    }
  ],
  "errors": {}
}

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

post

/fulfillment/{countrycode}/v1/orders/{id}/details

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор замовлення.

Example: 550e8400-e29b-41d4-a716-446655440000

Bodyobject[]

Масив товарних позицій, які необхідно додати до замовлення. Необхідно передати щонайменше одну товарну позицію.

objectIdstringRequired

Ідентифікатор товару.

quantityinteger · min: 1 · max: 1000Required

Кількість товару.

pricenumber · floatOptional

Ціна за одиницю товару.

sumnumber · floatOptional

Загальна сума за товарною позицією.

Responses

201

Товари успішно додано до замовлення. Відповідь містить повний перелік товарних позицій замовлення.

application/json

idstring · uuidRequired

Унікальний ідентифікатор позиції замовлення.

objectIdstringRequired

Ідентифікатор товару.

quantityintegerRequired

Кількість товару.

pricenumber · floatOptional

Ціна за одиницю товару.

sumnumber · floatOptional

Загальна сума за товарною позицією.

post/fulfillment/{countrycode}/v1/orders/{id}/details

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

[
  {
    "objectId": "ITEM-02",
    "quantity": 10,
    "price": 10,
    "sum": 100
  },
  {
    "objectId": "ITEM-03",
    "quantity": 10,
    "price": 10,
    "sum": 100
  }
]

201

Товари успішно додано до замовлення. Відповідь містить повний перелік товарних позицій замовлення.

[
  {
    "id": "0519dba3-e1df-4379-a3b9-b544a4f22376",
    "objectId": "ITEM-01",
    "quantity": 10,
    "price": 10,
    "sum": 100
  },
  {
    "id": "0620dba3-e1df-4379-a3b9-b544a4f33487",
    "objectId": "ITEM-02",
    "quantity": 10,
    "price": 10,
    "sum": 100
  },
  {
    "id": "0721dba3-e1df-4379-a3b9-b544a4f78334",
    "objectId": "ITEM-03",
    "quantity": 10,
    "price": 10,
    "sum": 100
  }
]

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

get

/fulfillment/{countrycode}/v1/orders/status

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

Значення в межах одного параметра фільтрації поєднуються через OR, а між різними параметрами — через AND.

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

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

Authorizations

AuthorizationstringRequired

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

Query parameters

ids[]string · uuid[]Optional

Масив системних ідентифікаторів замовлень.

externalNumbers[]string[]Optional

Масив зовнішніх номерів замовлень.

destWarehouses[]string[]Optional

Масив кодів складів.

startDatestring · date-timeOptional

Початкова дата створення замовлень у форматі ISO 8601.

Example: 2026-05-01T00:00:00Z

endDatestring · date-timeOptional

Кінцева дата створення замовлень у форматі ISO 8601.

Example: 2026-05-31T23:59:59Z

pageintegerOptional

Номер сторінки (до 25 об'єктів на сторінку).

Example: 1

Responses

200

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

application/json

linksobjectRequired

Посилання пагінації.

metaobjectRequired

Метадані пагінації.

get/fulfillment/{countrycode}/v1/orders/status

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

200

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

{
  "data": [
    {
      "id": "ed3bd7e9-545c-4a34-9c58-f17e2b92ed32",
      "externalNumber": "TEST-EXTRA-001",
      "destWarehouse": "000063146",
      "status": 1,
      "statusTime": null,
      "waybillNumber": null
    },
    {
      "id": "dup-test-001",
      "externalNumber": "DUP-TEST-EXT",
      "destWarehouse": "000063146",
      "status": 13,
      "statusTime": "2026-05-10T15:34:00Z",
      "waybillNumber": "20450000000001"
    }
  ],
  "links": {},
  "meta": {}
}

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

patch

/fulfillment/{countrycode}/v1/orders/{id}/cancel

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

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

Якщо із замовленням пов'язаний номер накладної Nova Post, його буде автоматично видалено.

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор замовлення.

Example: 550e8400-e29b-41d4-a716-446655440000

Responses

200

Клієнтське замовлення успішно скасовано. Відповідь містить оновлений об'єкт замовлення.

application/json

patch/fulfillment/{countrycode}/v1/orders/{id}/cancel

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

200

Клієнтське замовлення успішно скасовано. Відповідь містить оновлений об'єкт замовлення.

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalNumber": "ORD-20240129-001",
    "destWarehouse": "WMS-UK-02",
    "deliveryType": 1,
    "waybillNumber": null,
    "additionalInfo": "Updated Info",
    "status": "10",
    "createdAt": "2026-05-09T14:32:00+00:00",
    "updatedAt": "2026-05-10T15:34:00+00:00",
    "details": [
      {
        "id": "3279cadb-daeb-4c62-a2fa-8fdb105c85a4",
        "objectId": "0519dba3-e1df-4379-a3b9-b544a4f22376",
        "quantity": 5,
        "price": 10.5,
        "sum": 157.5
      }
    ]
  }
}

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

get

/fulfillment/{countrycode}/v1/orders/{id}/details

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstringRequired

Унікальний ідентифікатор замовлення.

Example: 0123456789

Responses

200

Дані успішно отримано. У відповіді повертається повна деталізація замовлення.

application/json

idstringRequired

Унікальний ідентифікатор замовлення.

externalNumberstringRequired

Зовнішній номер замовлення.

get/fulfillment/{countrycode}/v1/orders/{id}/details

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

200

Дані успішно отримано. У відповіді повертається повна деталізація замовлення.

{
  "id": "0123456789",
  "externalNumber": "Num-01",
  "details": [
    {
      "id": "3279cadb-daeb-4c62-a2fa-8fdb105c85a4",
      "objectId": "0102030405",
      "sku": "SKU-001",
      "measureUnitName": "шт",
      "plannedQuantity": 4,
      "actualQuantity": 0,
      "condition": 0,
      "series": [
        "SN-001",
        "SN-002",
        "SN-003",
        "SN-004"
      ]
    }
  ]
}

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

patch

/fulfillment/{countrycode}/v1/orders/{id}

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

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор замовлення.

Example: 550e8400-e29b-41d4-a716-446655440000

Body

Тіло запиту для оновлення замовлення. Необхідно передавати лише ті поля, які потрібно змінити. Має бути передано щонайменше одне поле.

destWarehousestringOptional

Код складу для відправлення.

deliveryTypeinteger · enumOptional

Тип доставки (2 = Nova Post, 5 = Pickup).

Possible values:

waybilNumberstring · nullableOptional

Номер накладної. Обов’язковий, якщо deliveryType = 2.

additionalInfostring · min: 2 · max: 255Optional

Додаткова інформація або коментар.

Responses

200

Клієнтське замовлення успішно оновлено.

application/json

patch/fulfillment/{countrycode}/v1/orders/{id}

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

{
  "destWarehouse": "WMS-UK-02",
  "deliveryType": 2,
  "waybilNumber": "20450012345678",
  "additionalInfo": "Оновлена інформація",
  "details": [
    {
      "objectId": "0519dba3-e1df-4379-a3b9-b544a4f22376",
      "quantity": 15,
      "price": 10.5,
      "sum": 157.5
    }
  ]
}

200

Клієнтське замовлення успішно оновлено.

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalNumber": "ORD-20240129-001",
    "destWarehouse": "WMS-UK-02",
    "deliveryType": 2,
    "waybilNumber": "20450012345678",
    "additionalInfo": "Оновлена інформація",
    "createdAt": "2026-05-09T14:32:00+00:00",
    "updatedAt": "2026-05-10T15:34:00+00:00",
    "details": [
      {
        "id": "3279cadb-daeb-4c62-a2fa-8fdb105c85a4",
        "objectId": "0519dba3-e1df-4379-a3b9-b544a4f22376",
        "quantity": 15,
        "price": 10.5,
        "sum": 157.5
      }
    ]
  }
}

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

post

/fulfillment/{countrycode}/v1/orders/{id}/details/multiple-delete

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

Дозволяється видалення всіх товарів із замовлення. При цьому статус замовлення залишається 13 (Incomplete).

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstring · uuidRequired

Унікальний ідентифікатор замовлення.

Example: 550e8400-e29b-41d4-a716-446655440000

Bodyobject[]

Масив товарних позицій, які необхідно видалити із замовлення. Необхідно передати щонайменше одну товарну позицію.

objectIdstringRequired

Ідентифікатор товару.

Responses

200

Товари успішно видалено із замовлення. Відповідь містить лише товарні позиції, що залишилися у замовленні.

application/json

idstring · uuidRequired

Унікальний ідентифікатор позиції замовлення.

objectIdstringRequired

Ідентифікатор товару.

quantityintegerRequired

Кількість товару.

pricenumber · floatOptional

Ціна за одиницю товару.

sumnumber · floatOptional

Загальна сума за товарною позицією.

post/fulfillment/{countrycode}/v1/orders/{id}/details/multiple-delete

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

[
  {
    "objectId": "ITEM-03"
  }
]

200

Товари успішно видалено із замовлення. Відповідь містить лише товарні позиції, що залишилися у замовленні.

[
  {
    "id": "0519dba3-e1df-4379-a3b9-b544a4f22376",
    "objectId": "ITEM-01",
    "quantity": 10,
    "price": 10,
    "sum": 100
  },
  {
    "id": "0620dba3-e1df-4379-a3b9-b544a4f33487",
    "objectId": "ITEM-02",
    "quantity": 10,
    "price": 10,
    "sum": 100
  }
]

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

get

/fulfillment/{countrycode}/v1/stock-remains

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

Значення в межах одного параметра фільтрації поєднуються через OR, а між різними параметрами — через AND.

Доступна для замовлення кількість розраховується за формулою: availableQuantity = quantity - reservedQuantity (якщо результат менше 0, повертається 0).

🔹Якщо запит не містить точкових товарних фільтрів (objectIds, objectArts, objectTitles), повертаються лише товари, для яких хоча б одне зі значень quantity, reservedQuantity або availableQuantity більше 0.

🔹Якщо використано точкові фільтри (objectIds, objectArts, objectTitles), запитані товари повертаються завжди, навіть якщо всі показники залишків дорівнюють 0.

Інформація повертається незалежно від наявності штрихкоду у товару. Залишки групуються за датою терміну придатності (expiryDate).

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

Authorizations

AuthorizationstringRequired

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

Query parameters

objectIds[]string[]Optional

Масив ID товарів.

objectArts[]string[]Optional

Масив артикулів товарів.

objectTitles[]string[]Optional

Масив назв товарів.

destWarehouses[]string[]Optional

Масив кодів складів.

remainDatestringOptional

Дата актуальності залишків у форматі YYYY-MM-DD.

Example: 2026-05-10

conditioninteger · enumOptional

Ознака дефекту:

• 0 — кондиція;
• 1 — некондиція.

Possible values:

pageintegerOptional

Номер сторінки (до 25 об'єктів на сторінку).

Example: 1

Responses

200

Дані успішно отримано. Повертаються залишки товарів із пагінацією.

application/json

linksobjectRequired

Посилання пагінації.

metaobjectRequired

Метадані пагінації.

get/fulfillment/{countrycode}/v1/stock-remains

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

200

Дані успішно отримано. Повертаються залишки товарів із пагінацією.

{
  "data": [
    {
      "objectId": "O1",
      "sku": "ART-1",
      "measureUnitName": "шт",
      "quantity": 125,
      "reservedQuantity": 30,
      "availableQuantity": 95,
      "destWarehouse": "WH-01",
      "expiryDate": null
    },
    {
      "objectId": "O2",
      "sku": "ART-2",
      "measureUnitName": null,
      "quantity": 0,
      "reservedQuantity": 0,
      "availableQuantity": 0,
      "destWarehouse": null,
      "expiryDate": null
    }
  ],
  "links": {
    "first": "https://api.novapost.com/v.1.0/fulfillment/pl/stock-remains?page=1",
    "last": "https://api.novapost.com/v.1.0/fulfillment/pl/stock-remains?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.novapost.com/v.1.0/fulfillment/pl/stock-remains",
    "per_page": 25,
    "to": 2,
    "total": 2
  }
}