Draft

Список відправлень

get

/shipments

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

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

SCHEMA

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

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

EXAMPLE

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

Authorizations

AuthorizationstringRequired

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

Query parameters

numbers[]stringOptional

Пошук відправлень за номером транспортного документа. Може приймати як один номер для пошуку, так і масив номерів.

Example: SHPL6145344878

ids[]integer · int32Optional

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

Example: 113622

limitinteger · int32Optional

Максимальна кількість елементів на сторінці.

Default: 15Example: 1

pageinteger · int32Optional

Номер сторінки для повернення.

Example: 1

inRegistrybooleanOptional

Прапорець, що показує, чи включено відправлення до реєстру. Лише для європейських посилок.

Example: true

registerNumberstringOptional

Номер реєстру, який містить усі відправлення. Лише для європейських посилок.

Example: CRPL0000004855

senderDivisionIdinteger · min: 1Optional

Ідентифікатор відділення, з якого здійснюється відправлення.

Example: 12

Responses

200

shipments

application/json

current_pageinteger · min: 1Optional

Поточна сторінка.

last_pageinteger · min: 1Optional

Загальна кількість сторінок.

per_pageinteger · min: 1Optional

Поточний ліміт об’єктів на сторінці.

totalintegerOptional

Загальна кількість знайдених об’єктів.

frominteger · nullableOptional

tointeger · nullableOptional

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

get/shipments

GET /v.1.0/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 438,
  "per_page": 1,
  "total": 438,
  "from": 1,
  "to": 1,
  "items": [
    {
      "id": "860344",
      "version": 1,
      "number": "SHPL9719840000",
      "dateTime": "2023-11-01T10:49:39.965000Z",
      "scheduledDeliveryDate": "2023-11-05T16:00:00.000000Z",
      "closingDate": null,
      "createdAt": "2023-11-01T10:49:41.860000Z",
      "updatedAt": "2023-11-01T10:49:41.860000Z",
      "deletedAt": null,
      "userCreate": "6e1ad1af-6595-44ba-ba3c-a748f6c10000",
      "status": "ReadyToShip",
      "gtid": "2000000000000439545",
      "paymentStatus": "NeedPay",
      "currencyCode": "PLN",
      "parcelsAmount": 1,
      "note": "",
      "payerType": "Sender",
      "payerContractId": null,
      "payerContractNumber": null,
      "postomatCellReservation": "",
      "postomatOrderRef": "",
      "firstDayStorage": null,
      "cargoAutoReturnDate": null,
      "marketplacePartner": "",
      "registerNumber": "",
      "customerNote": "",
      "creationDateNote": "",
      "sender": {
        "companyId": null,
        "companyTin": "",
        "companyName": null,
        "phone": "48993450000",
        "email": "example@mail.pl",
        "name": "LastName Name",
        "countryCode": "PL",
        "settlementId": "22326",
        "cityId": null,
        "address": "02144, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Sasanki, 12, , 1, ",
        "addressParts": {
          "city": "Warszawa",
          "region": "Warszawa County",
          "street": "Sasanki",
          "post_code": "02144",
          "building": "12",
          "flat": "1",
          "block": "",
          "note": ""
        },
        "divisionId": "",
        "divisionCategory": "",
        "archive": false
      },
      "recipient": {
        "companyId": null,
        "companyTin": "",
        "companyName": null,
        "phone": "380991230000",
        "email": "example@mail.com",
        "name": "LastName Name",
        "countryCode": "UA",
        "settlementId": "127808",
        "cityId": null,
        "address": "36023, Україна,Полтавська область,,місто Полтава,Відділення №11 (до 30 кг на одне місце): вул. Героїв АТО, 79,,,",
        "addressParts": {
          "city": "місто Полтава",
          "region": "Полтавська область",
          "street": "Відділення №11 (до 30 кг на одне місце): вул. Героїв АТО",
          "post_code": "36023",
          "building": "79",
          "flat": "",
          "block": "",
          "note": ""
        },
        "divisionId": "11664",
        "divisionCategory": "PostBranch",
        "archive": false
      },
      "parcels": [
        {
          "number": "SHPL9719840000",
          "row_number": 1,
          "untied": false,
          "cargo_category_id": "2",
          "cargo_category_group": "Parcel",
          "parcel_description": "Example",
          "insurance_cost": 30,
          "length": 350,
          "width": 200,
          "height": 100,
          "actual_weight": 2000,
          "volumetric_weight": 1750,
          "length_check": null,
          "width_check": null,
          "height_check": null,
          "actual_weight_check": null,
          "volumetric_weight_check": null
        }
      ],
      "services": [
        {
          "id": 2068473,
          "shipment_parcel_row_number": null,
          "service_id": "5637144594",
          "service_type": "MainService",
          "service_name": "Delivery/pickup by courier",
          "parcel_number": "",
          "payer_type": "Sender",
          "amount": 1,
          "price": 10,
          "discount": 0,
          "cost": 10,
          "cost_before_check": null,
          "payment_status": "NeedPay",
          "additional_parameters": {
            "cod": null,
            "date": null,
            "from": null,
            "to": null,
            "string": null,
            "fullName": null,
            "phone": null
          }
        },
        {
          "id": 2068474,
          "shipment_parcel_row_number": 1,
          "service_id": "5637144588",
          "service_type": "InternationalServices",
          "service_name": "Parcel international delivery (small)",
          "parcel_number": "1",
          "payer_type": "Sender",
          "amount": 1,
          "price": 45,
          "discount": 0,
          "cost": 45,
          "cost_before_check": null,
          "payment_status": "NeedPay",
          "additional_parameters": {
            "cod": null,
            "date": null,
            "from": null,
            "to": null,
            "string": null,
            "fullName": null,
            "phone": null
          }
        }
      ],
      "onlineTracking": {
        "tracking_status_code": 1,
        "tracking_update_date": "2023-11-01T10:49:42.167337Z",
        "short_description": "ECN created",
        "long_description": "Waiting for your parcel to ship",
        "info": "",
        "label": "orange"
      },
      "tracking": [
        {
          "number": "SHPL9719840000",
          "date": "2023-11-01T10:49:41.860000Z",
          "division": "",
          "settlement": "22326",
          "event": "CreateID",
          "event_status": "now",
          "code": "1",
          "division_name": "",
          "settlement_name": "Warsaw",
          "event_name": "Waybill prepared, waiting for the parcel"
        }
      ],
      "totalWeight": 2,
      "totalInsuranceCost": 30,
      "totalCost": 55,
      "invoice": {
        "customerNumber": "INV-001",
        "customerCreatedAt": "2023-11-01T10:00:00.000000Z",
        "type": "Invoice",
        "incoterm": "DAP",
        "exportReason": "Selling",
        "cost": 30,
        "currency": "EUR",
        "payerFeesCustoms": "Recipient",
        "items": [
          {
            "id": "1",
            "hsCode": "84701000",
            "name": "Calculator",
            "nameEng": "Calculator",
            "material": "plastic",
            "materialEng": "plastic",
            "madeInCountryCode": "PL",
            "producerAndModel": "Casio JR15",
            "actualWeight": 2000,
            "measurementCode": "pieces",
            "amount": 1,
            "cost": 30
          }
        ]
      }
    }
  ]
}

Створення Відправлення

post

/shipments

Створення документа відправлення. Цей API-метод призначений для спрощення процесу формування транспортного документа для логістичних операцій через Nova Post. Передаючи ключові дані, такі як адреси відправлення та доставки, користувачі можуть легко створити документ, що описує транспортування вантажу. Метод також включає додаткові поля для митних органів, що дозволяє обробляти міжнародні відправлення. У відповіді API буде повернено унікальний ідентифікатор створеного документа разом з іншою релевантною інформацією.

Правила валідації населеного пункту: Для відправлень до або з Молдови та України населений пункт (місто) має бути успішно визначений. Якщо передане значення міста не може бути співставлене з населеним пунктом, запит завершиться помилкою: validation.condition.recipient_settlement_not_defined.

Додаткова вимога: Для відправлень, що потребують митного оформлення (імпорт), клієнтський інвойс необхідно завантажити як файл через метод POST /shipments/uploads/{id} (після створення відправлення).

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

SCHEMA

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

EXAMPLE

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

Authorizations

AuthorizationstringRequired

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

Body

statusstring · enumOptional

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

Draft: Документ знаходиться на початковій стадії, ще не завершений.
Accepted: Перевірений та прийнятий, документ готовий до наступних етапів.
Issued: Документ завершено та готовий до відправлення.
ReadyToShip: Вказує, що відправлення підготовлено до транспортування після створення експрес-накладної. Лише це значення може бути вказане при створенні відправлення.
Deleted: Документ видалено із системи.
Returned: Відправлення повернено відправнику.
Utilized: Вказує, що фізичні товари, пов’язані з транспортним документом, були утилізовані або знищені, і документ закрито.

Possible values:

clientOrderstring · max: 50Optional

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

notestring · max: 255Optional

Тут може бути вказана будь-яка додаткова інформація або спеціальні інструкції щодо замовлення. Це можуть бути інструкції з доставки, особливі умови обробки або інші важливі деталі, що сприяють обробці відправлення.

deliveryTypestringOptional

Визначає тип тарифу, який буде застосовано до відправлення під час створення або оновлення.

standard: Стандартний міжнародний тариф доставки.
economy: Економний міжнародний тариф доставки.
express: Експрес міжнародний тариф доставки.

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

🔹Це поле є необов’язковим.

payerType*string · enumOptional

Визначає, хто несе відповідальність за оплату послуг доставки. Тип платника визначає сторону, яка покриває витрати:

Sender: Відправник оплачує доставку.
Recipient: Одержувач оплачує доставку.
ThirdPerson: Третя сторона, не відправник і не одержувач, оплачує доставку. При виборі 'ThirdPerson' поле 'payerContractNumber' має містити номер договору платника. Детальніше див. статтю Оплата послуг доставки через API Nova Post. Це поле також використовується при формуванні інвойсу.

🔻Це поле є обов’язковим

Possible values:

payerContractNumberstring · min: 2 · max: 20 · nullableOptional

Це поле є обов’язковим у таких випадках:

Коли payerType має значення ThirdPerson. Воно повинно містити номер договору платника. Для клієнтів з України також дозволено передавати код ЄДРПОУ замість номера договору.
Коли payerType має значення Sender або Recipient і використовується безготівковий спосіб оплати.

Якщо це поле не передано у зазначених випадках, спосіб оплати автоматично буде встановлений як готівковий.

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

Детальніше див. статтю Оплата послуг доставки через API Nova Post.

Responses

201

Відправлення успішно створено.

application/json

idstring · uuid · min: 1Optional

Унікальний ідентифікатор, що призначається кожному відправленню, який використовується для внутрішніх операцій, таких як модифікація, пошук у системі та видалення відправлень. Поле id слугує ключовим посиланням для адміністративних і логістичних процесів у системі доставки, забезпечуючи точний доступ і керування записами відправлень. Формат значення id залежить від напрямку відправлення (first/last mile):

Для відправлень у Європі значення є числовим ідентифікатором (наприклад, 754116), який використовується для пошуку.
Для відправлень в Україні значення є UUID (наприклад, 56abe014-451c-11f0-a1d5-48df37b921da), який використовується для пошуку за ref.

numberstringOptional

Номер транспортного документа, який надається клієнтам для відстеження та доступу до друкованих форм. Також використовується для пошуку відправлень у системі, забезпечуючи зручний спосіб моніторингу їхнього статусу. Хоча number використовується зовні для відстеження та документації, у деяких випадках він може застосовуватись і для внутрішньої ідентифікації, подібно до id.

Pattern: ^[A-Z]{4}\d{10}$

scheduledDeliveryDatestring · date-time · nullableOptional

Орієнтовна дата доставки, розрахована на основі маршруту та рівня сервісу. Може змінюватися залежно від логістичних та зовнішніх факторів. Дата у форматі ISO 8601.

Example: 2023-04-14T09:00:00Z

statusstringOptional

Поточний статус відправлення. Під час створення встановлюється значення "ReadyToShip", що означає готовність до відправки.

costnumber · floatOptional

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

Example: 31.5

parcelsAmountinteger · min: 1Optional

Загальна кількість місць (посилок) у відправленні. Використовується для планування логістики та відстеження.

createdAtstring · date-timeOptional

Дата та час створення запису відправлення в системі. Формат ISO 8601.

Example: 2023-04-11T10:42:05Z

updatedAtstring · date-timeOptional

Дата та час останнього оновлення відправлення. Використовується для відстеження змін. Формат ISO 8601.

Example: 2023-04-11T10:42:05Z

deletedAtstring · date-time · nullableOptional

Дата та час видалення або скасування відправлення. Якщо відправлення не скасовано — значення null.

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

post/shipments

POST /v.1.0/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 882

{
  "status": "ReadyToShip",
  "clientOrder": "",
  "note": "",
  "payerType": "Sender",
  "invoice": null,
  "services": [],
  "parcels": [
    {
      "cargoCategory": "parcel",
      "number": null,
      "parcelDescription": "parcel for redirect test",
      "insuranceCost": 100,
      "rowNumber": 1,
      "width": 200,
      "length": 350,
      "height": 100,
      "actualWeight": 2000,
      "volumetricWeight": 2000
    },
    {
      "cargoCategory": "parcel",
      "number": null,
      "parcelDescription": "parcel for redirect test",
      "insuranceCost": 100,
      "rowNumber": 2,
      "width": 200,
      "length": 350,
      "height": 100,
      "actualWeight": 2000,
      "volumetricWeight": 2000
    }
  ],
  "sender": {
    "companyTin": "",
    "companyName": "",
    "phone": "380007654321",
    "email": "sender@test.com",
    "name": "Maks Tester",
    "countryCode": "CZ",
    "divisionId": 1834581,
    "addressParts": {},
    "ioss": null
  },
  "recipient": {
    "companyTin": "",
    "companyName": "",
    "phone": "380001234567",
    "email": "recipient@test.com",
    "name": "Chuck Norris",
    "countryCode": "PL",
    "divisionId": 27255,
    "addressParts": {}
  }
}

{
  "id": 113677,
  "number": "SHLT4009860665",
  "scheduledDeliveryDate": "2023-04-14T09:00:00.000000Z",
  "status": "ReadyToShip",
  "cost": 31,
  "parcelsAmount": 1,
  "createdAt": "2023-04-11T10:42:05.543380Z",
  "updatedAt": "2023-04-11T10:42:05.543380Z",
  "deletedAt": null
}

Створення відправлення для легкого повернення

post

/shipments/light-return

Створює відправлення для повернення після доставки початкового замовлення. Цей метод дозволяє клієнтам створити відправлення повернення після доставки — незалежно від того, хто здійснював останню милю (Нова Пошта або партнер).

ℹ️ Інформація: Повернення може бути створене лише якщо батьківське відправлення має статус Delivered та містить послугу AllowedLightReturn. Поточний статус відправлення можна знайти у полі \"items\" → \"statusCode\" методу Список відправлень. AllowedLightReturn визначає кількість днів, протягом яких отримувач може ініціювати повернення після доставки. Внутрішньо система перевіряє кілька умов перед тим, як дозволити створення відправлення легкого повернення:

Статус батьківського відправлення має бути одним із: Issued (9, 10, 11, 106).
Система обчислює дозволений період повернення за такою логікою: finalDate = toTZ(parentShipment.RecipientDateTime) + returnDays + 1 day де returnDays береться з послуги AllowedLightReturn, а toTZ застосовує відповідний часовий пояс системи (наприклад, регіон ЄС).
Повернення може бути створене лише якщо поточний час (nowTZ) є меншим за finalDate.
Система також перевіряє, що для цього ж батьківського відправлення ще не було створено легке повернення.

Якщо всі ці умови виконані, запит на створення повернення приймається; в іншому випадку система повертає помилку валідації з поясненням причини відмови.

Як працює відправлення легкого повернення

Запит повинен містити один обов’язковий параметр — number (номер батьківського відправлення). Усі інші параметри є опціональними.
Клієнт може вказати валідне відділення або адресу безпосередньо для повернення.
Якщо опціональні параметри не вказані, їх значення автоматично наслідуються з батьківського відправлення.
Поведінка методу залежить від напрямку відправлення:
- Для напрямку UA-UA: метод працює для доставок у поштомат, PUDO або за адресою.
- Для напрямку EU-EU: метод працює для доставок у PUDO або за адресою. Не підтримується, якщо батьківське відправлення було доставлене у поштомат.
Якщо доставка батьківського відправлення була за адресою, створюється заявка на забір автоматично. Заявка на забір створюється лише якщо повернення не було відправлене з відділення.

Після створення повернення система автоматично генерує накладну повернення. Детальніше про створення батьківського відправлення дивіться у Створення Відправлення

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

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

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

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

Authorizations

AuthorizationstringRequired

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

Body

numberstringRequired

Номер батьківського відправлення, для якого ініціюється повернення.

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

Example: SHMD0000000000

divisionIdstringOptional

Ідентифікатор відділення, яке буде обробляти повернення.

Example: 1835903

senderPhonestringOptional

Номер телефону відправника для відправлення повернення.

Example: 490000000000

Responses

200

Successfully created Light Return shipment.

application/json

objectOptional

401

Unauthorized request — invalid or missing authentication token.

application/json

403

Parent shipment is missing the AllowedLightReturn parameter.

application/json

404

Parent shipment not found or status not allowed.

application/json

422

Parent shipment not found or status not allowed.

application/json

503

Service unavailable or request timeout.

application/json

post/shipments/light-return

POST /v.1.0/shipments/light-return HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "number": "SHMD0000000000",
  "senderPhone": "490000000000"
}

{
  "id": 1000000,
  "number": "SHPL0000000000",
  "dateTime": "2025-01-01T10:00:00.000000Z",
  "scheduledDeliveryDate": "2025-01-02T10:00:00.000000Z",
  "actualDeliveryDate": "2025-01-01T10:00:01.000000Z",
  "closingDate": null,
  "status": "ReadyToShip",
  "statusDateTime": "2025-01-01T10:00:01.000000Z",
  "createdByUser": "00000000-0000-0000-0000-000000000000",
  "acceptedByUser": null,
  "createdOnDivisionId": null,
  "lastModifiedByUser": "00000000-0000-0000-0000-000000000000",
  "firstLogisticDivisionId": 100001,
  "lastLogisticDivisionId": 100002,
  "sender": {
    "eoriCode": null,
    "companyTin": "",
    "companyName": "",
    "phone": "380000000000",
    "email": "sender@example.com",
    "name": "Sender name",
    "countryCode": "PL",
    "settlementId": 10000,
    "address": {
      "string": "00-000, Polska, Warszawa, Default Street, 1",
      "latitude": 52.2297,
      "longitude": 21.0122
    },
    "addressParts": {
      "postCode": "00-000",
      "building": "1",
      "street": "Default Street",
      "city": "Warszawa",
      "region": "Mazowieckie",
      "flat": "1",
      "note": "Default note",
      "block": "A"
    },
    "divisionId": 1000001,
    "cityDistrict": "Default District",
    "registrationAddress": "Polska, Warszawa, Default Street, 1",
    "registrationAddressParts": {
      "city": "Warszawa",
      "street": "Default Street",
      "building": "1",
      "postCode": "00-000"
    },
    "cid": "00000000-0000-0000-0000-000000000001"
  },
  "recipient": {
    "eoriCode": "CZ1234567890",
    "companyTin": "CZ0000000000",
    "companyName": "Default Recipient Company",
    "phone": "420000000000",
    "email": "recipient@example.com",
    "name": "Default Recipient",
    "countryCode": "CZ",
    "settlementId": 20000,
    "address": {
      "string": "100-00, Česko, Praha, Default Street, 10",
      "latitude": 50.0755,
      "longitude": 14.4378
    },
    "addressParts": {
      "postCode": "100-00",
      "building": "10",
      "street": "Default Street",
      "city": "Praha",
      "region": "Praha",
      "flat": "2",
      "note": "Default address note",
      "block": "B"
    },
    "divisionId": 2000001,
    "cityDistrict": "Default District",
    "registrationAddress": "Česko, Praha, Default Street, 10",
    "registrationAddressParts": {
      "city": "Praha",
      "street": "Default Street",
      "building": "10",
      "postCode": "100-00"
    },
    "cid": "00000000-0000-0000-0000-000000000002"
  },
  "payerType": "Recipient",
  "payerContractNumber": "GNP000000000",
  "paymentStatus": "ContractAfterPayment",
  "currencyCode": "EUR",
  "parcelsAmount": 1,
  "note": "",
  "lockVersion": 1,
  "clientOrder": "",
  "gtid": "0000000000000000001",
  "firstMileDeliveryPartner": "Nova Post",
  "lastMileDeliveryPartner": "Nova Post",
  "parcels": [
    {
      "number": "SHPL0000000000",
      "rowNumber": 1,
      "untied": false,
      "status": "ReadyToShip",
      "pricingType": "parcel",
      "cargoCategoryId": 1,
      "parcelDescription": "Default parcel",
      "insuranceCost": 100,
      "length": 20,
      "width": 15,
      "height": 10,
      "actualWeight": 500,
      "volumetricWeight": 600,
      "recipient": null
    }
  ],
  "services": [
    {
      "id": 100001,
      "shipmentId": 1000000,
      "shipmentParcelRowNumber": 1,
      "serviceId": 5000001,
      "serviceCode": "LightReturn",
      "type": "SystemManual",
      "countryCode": "CZ",
      "routeId": 100,
      "amount": 1,
      "contractNumber": "GNPCZ-00000000",
      "payerType": "Recipient",
      "paymentStatus": "ContractAfterPayment",
      "divisionId": 2000001,
      "price": 50,
      "discount": 0,
      "cost": 50,
      "user": "00000000-0000-0000-0000-000000000010",
      "shipmentLockVersion": 1,
      "additionalParameters": {
        "divisionId": 2000001,
        "addressParts": {
          "city": "Praha",
          "region": "Praha",
          "street": "Default Street",
          "postCode": "100-00",
          "building": "10",
          "flat": "2",
          "note": "",
          "block": ""
        },
        "cod": null,
        "backwardDelivery": null,
        "partner": null,
        "sameDay": false,
        "longStorageDays": 0,
        "recipientPhoneAlternative": null,
        "quantity": 1,
        "date": "2025-01-01T00:00:00.000000Z",
        "from": "Praha",
        "to": "Warszawa",
        "string": "SHCZ0000000000",
        "fullName": "Default Sender",
        "phone": "380000000000"
      },
      "currencyCode": "EUR",
      "createdAt": "2025-01-01T10:00:00.000000Z",
      "updatedAt": "2025-01-01T10:00:00.000000Z",
      "executionAt": null
    }
  ],
  "deliveryPartners": [
    {
      "partnerCode": "NP",
      "name": "Nova Post",
      "country": "CZ"
    }
  ],
  "shipmentAttachments": [
    {
      "id": 1,
      "fileName": "invoice.pdf",
      "fileType": "pdf",
      "uploadedAt": "2025-01-01T10:01:00.000000Z"
    }
  ],
  "createdAt": "2025-01-01T10:00:00.000000Z",
  "updatedAt": "2025-01-01T10:05:00.000000Z",
  "deletedAt": null,
  "invoice": {
    "number": "INV00000001",
    "date": "2025-01-01T00:00:00.000000Z",
    "totalAmount": 150,
    "currencyCode": "EUR"
  },
  "currentRouteId": 100,
  "additionalParameters": {
    "promoCode": "DEFAULTPROMO",
    "sourceApplication": "clientapi",
    "preferredDeliveryDate": "2025-01-02T00:00:00.000000Z",
    "invoiceInspection": false,
    "parentShipment": {
      "number": "SHCZ0000000000",
      "id": 999999
    },
    "childShipment": null,
    "userMod": "00000000-0000-0000-0000-000000000020",
    "cargoAutoReturnDate": null
  },
  "markingPrinted": true
}

Отримання статусу верифікації для відправлень UA→World

get

/shipments/international/status

Повертає статуси верифікації для міжнародних відправлень для напрямку UA→World («міжнародне відправлення з України у світ»). Відповіді та помилки від основної системи проксируются без змін.

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

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

Authorizations

AuthorizationstringRequired

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

Query parameters

refs[]string[]Required

Масив референсів відправлень. Не повинен бути порожнім. Передається як повторювані параметри запиту. Приклад запиту: refs[]=38e4fe97-9484-11f0-903f-005056bd9e02

statestring · enumRequired

Фільтр стану верифікації. Доступні значення: Order, Closed, allOrders.

Possible values:

Responses

200

Список статусів верифікації

application/json

jsonrpcstringOptional

idone ofOptional

stringOptional

integerOptional

400

Invalid request parameters

application/json

401

Неавторизований доступ

application/json

503

Час очікування з’єднання вичерпано

application/json

get/shipments/international/status

GET /v.1.0/shipments/international/status?refs[]=text&state=Order HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "jsonrpc": "2.0",
  "result": [
    {
      "Ref": "38e4fe97-9484-11f0-903f-005056bd9e02",
      "State": "NotVerified",
      "Date": "2025-09-18 14:45:31",
      "StatusOfInternationalExpressWaybill": "Відсутні скан-копії документів",
      "Note": "test comment",
      "ClosedDate": "0001-01-01 00:00:00"
    }
  ],
  "id": "1"
}

Розрахунок вартості доставки

post

/shipments/calculations

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

🔹Description of control elements:

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

Authorizations

AuthorizationstringRequired

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

Body

payerTypestring · enumOptional

Визначає, хто відповідає за оплату послуг доставки. Тип платника визначає, яка сторона несе витрати:

Sender: Сторона, що відправляє товар, оплачує доставку.
Recipient: Сторона, що отримує товар, відповідає за оплату доставки.
ThirdPerson: Третя сторона оплачує доставку.
Для відправлень у межах Європи або з Європи в Україну необхідно передати поле payerContractNumber.
Для відправлень з України payerContractNumber не є обов’язковим."

Example: SenderPossible values:

payerContractNumberstringOptional

Обов’язковий, якщо payerType = ThirdPerson для відправлень у межах Європи або з Європи в Україну. Вказує номер договору платника-третьої сторони (наприклад, CNPP-00001797).

Example: CNPP-00001797

deliveryTypesarray · enumOptional

Визначає список тарифних типів, які використовуються для розрахунку вартості доставки. У відповіді розрахунку повертаються результати вартості для кожного переданого типу доставки.

standard: Стандартний тариф міжнародної доставки.
economy: Економ-тариф міжнародної доставки.
express: Експрес-тариф міжнародної доставки.

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

🔹Це поле є необов’язковим.

Possible values:

Responses

200

Successful cost calculation

application/json

scheduledDeliveryDatestring · date-time · nullableOptional

Орієнтовна дата доставки, розрахована на основі маршрутизації та рівня сервісу. Може змінюватися залежно від логістичних та зовнішніх факторів. Дата у форматі ISO 8601.

Example: 2023-04-14T09:00:00Z

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

post/shipments/calculations

POST /v.1.0/shipments/calculations HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 522

{
  "payerType": "ThirdPerson",
  "payerContractNumber": "CNPP-00001797",
  "parcels": [
    {
      "cargoCategory": "parcel",
      "insuranceCost": 1.5,
      "rowNumber": 1,
      "width": 500,
      "length": 500,
      "height": 500,
      "actualWeight": 1000,
      "volumetricWeight": 1000
    }
  ],
  "sender": {
    "companyTin": "",
    "companyName": "",
    "countryCode": "PL",
    "divisionId": null,
    "addressParts": {
      "city": "Warsaw",
      "region": "Warszawa County",
      "street": "15 Sierpnia",
      "postCode": "000100",
      "building": "1",
      "flat": "",
      "block": "",
      "note": ""
    }
  },
  "recipient": {
    "countryCode": "CZ",
    "divisionId": 1834946,
    "addressParts": {}
  }
}

{
  "scheduledDeliveryDate": "2023-04-14T09:00:00.000000Z",
  "sender": {
    "countryCode": "PL",
    "settlementId": null,
    "divisionId": null
  },
  "recipient": {
    "countryCode": "CZ",
    "settlementId": 142473,
    "divisionId": 1834946
  },
  "services": [
    {
      "shipmentId": null,
      "shipmentParcelRowNumber": null,
      "serviceId": "5637144594",
      "serviceType": "COD",
      "serviceName": "COD",
      "serviceCode": "COD",
      "amount": 1,
      "contractNumber": null,
      "payerType": "Recipient",
      "paymentStatus": "NeedPay",
      "divisionId": null,
      "price": 25,
      "discount": 0,
      "cost": 25,
      "user": "",
      "shipmentLockVersion": 1,
      "additionalParameters": {
        "cod": null,
        "date": null,
        "from": null,
        "to": null,
        "string": null,
        "fullName": null,
        "phone": null
      },
      "currencyCode": "PLN",
      "createdAt": null,
      "updatedAt": null,
      "deliveryType\"": "fe0a07b5-a212-11eb-94e4-b8830365bd14",
      "deliveryTypeName\"": "standard"
    },
    {
      "shipmentId": null,
      "shipmentParcelRowNumber": 1,
      "serviceId": "5637146076",
      "serviceType": "COD",
      "serviceName": "COD",
      "serviceCode": "COD",
      "amount": 1,
      "contractNumber": null,
      "payerType": "Recipient",
      "paymentStatus": "NeedPay",
      "divisionId": null,
      "price": 109.38,
      "discount": 0,
      "cost": 109.38,
      "user": "",
      "shipmentLockVersion": 1,
      "additionalParameters": {
        "cod": null,
        "date": null,
        "from": null,
        "to": null,
        "string": null,
        "fullName": null,
        "phone": null
      },
      "createdAt": null,
      "updatedAt": null,
      "deliveryType\"": "fe0a07b5-a212-11eb-94e4-b8830365bd14",
      "deliveryTypeName\"": "standard"
    }
  ]
}

Оновити транспортний документ

put

/shipments/{id}

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

Обмеження оновлення:

Дані відправлення можуть бути оновлені лише тоді, коли відправлення перебуває у статусі ReadyToShip.
Оновлення дозволені лише якщо ярлик (лейбл) відправлення ще не був надрукований.
Якщо відправлення не перебуває у статусі ReadyToShip або ярлик уже був надрукований, запит на оновлення буде відхилено з помилкою валідації.

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idinteger · int32Required

Ідентифікатор транспортного документа.

Example: 113677

Body

statusstring · enumOptional

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

Draft: Документ перебуває на етапі створення та ще не завершений.
Accepted: Документ перевірено та прийнято, готовий до наступних кроків.
Issued: Документ сформовано та підготовлено до відправлення.
ReadyToShip: Вказує, що відправлення готове до транспортування після створення експрес-накладної. Лише це значення може бути вказане при створенні відправлення.
Deleted: Документ видалено із системи.
Returned: Відправлення повернено відправнику.
Utilized: Вказує, що фізичний вантаж, пов’язаний із транспортним документом, утилізовано або знищено, а документ закрито.

Possible values:

clientOrderstring · max: 50Optional

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

notestring · max: 255Optional

Додаткова інформація або спеціальні інструкції щодо замовлення. Може включати інструкції з доставки, особливі вимоги до обробки або інші важливі деталі, що полегшують обробку та виконання відправлення.

deliveryTypestringOptional

Визначає тип тарифу, який буде застосовано до відправлення під час створення або оновлення.

standard: Стандартний тариф на міжнародну доставку.
economy: Економний тариф на міжнародну доставку.
express: Експрес-тариф на міжнародну доставку.

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

🔹Це поле є необов’язковим.

payerTypestring · enumOptional

Визначає, хто відповідає за оплату послуг доставки. Тип платника визначає сторону, яка несе витрати:

Sender: Відправник оплачує доставку.
Recipient: Отримувач оплачує доставку.
ThirdPerson: Третя сторона (не відправник і не отримувач) оплачує послуги доставки. У разі вибору ThirdPerson поле payerContractNumber повинно містити номер договору платника. Детальніше див. у статті Оплата послуг доставки через API Nova Post.

Possible values:

payerContractNumberstring · min: 2 · max: 20 · nullableOptional

Номер договору платника. Обов’язковий, якщо payerType = ThirdPerson. Для клієнтів з України також допускається використання коду ЄДРПОУ замість номера договору. Поле також обов’язкове, якщо платником є відправник при безготівковій оплаті. Якщо значення не надано, за замовчуванням застосовується готівковий спосіб оплати. Коректність даних є критично важливою для обробки платежу. Більш детальну інформацію можна знайти у статті Оплата послуг доставки через API Nova Post.

Responses

202

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

application/json

idinteger · min: 1Optional

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

numberstringOptional

Номер транспортного документа, який надається клієнтам для відстеження відправлення та доступу до друкованих форм. Також використовується для пошуку відправлення в системі, забезпечуючи зручний для клієнта спосіб контролю його статусу. Хоча поле number використовується переважно для зовнішнього відстеження та документації, у певних системних операціях воно також може використовуватися для внутрішньої ідентифікації відправлення аналогічно до поля id.

Pattern: ^[A-Z]{4}\d{10}$

scheduledDeliveryDatestring · nullableOptional

Орієнтовна дата доставки, розрахована на основі маршруту та рівня сервісу. Може змінюватися залежно від логістичних та зовнішніх факторів.

statusstringOptional

Поточний статус відправлення. Після створення початково встановлюється значення ReadyToShip, що означає готовність відправлення до відправки.

costnumber · floatOptional

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

Example: 32.5

parcelsAmountinteger · min: 1Optional

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

createdAtstring · date-timeOptional

Дата й час створення запису про відправлення в системі.

updatedAtstring · date-timeOptional

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

deletedAtstring · date-time · nullableOptional

Дата й час скасування або видалення відправлення із системи. Якщо відправлення не було скасовано, це поле містить значення null.

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

put/shipments/{id}

PUT /v.1.0/shipments/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1529

{
  "status": "ReadyToShip",
  "clientOrder": "string",
  "note": "string",
  "payerType": "Sender",
  "payerContractNumber": null,
  "invoice": {
    "incoterm": "DAP",
    "exportReason": "Selling",
    "cost": 20,
    "currency": "UAH",
    "payerFeesCustoms": "Sender",
    "items": [
      {
        "id": 25227,
        "name": "Обладнання та електрика/Складське обладнання: Калькулятори",
        "nameEng": "Hardware and Electrical/Storage Equipment: Calculators",
        "measurementCode": "pieces",
        "hsCode": "84701000",
        "producerAndModel": "Casio JR15",
        "amount": 1,
        "cost": 20
      }
    ]
  },
  "parcels": [
    {
      "cargoCategory": "parcel",
      "parcelDescription": "Clothes",
      "insuranceCost": 20,
      "rowNumber": 1,
      "untied": false,
      "width": 200,
      "length": 350,
      "height": 100,
      "actualWeight": 2000
    },
    {
      "cargoCategory": "parcel",
      "parcelDescription": "Clothes",
      "insuranceCost": 15,
      "rowNumber": 2,
      "untied": false,
      "width": 215,
      "length": 345,
      "height": 110,
      "actualWeight": 2000
    },
    {
      "cargoCategory": "parcel",
      "parcelDescription": "Clothes",
      "insuranceCost": 20,
      "rowNumber": 3,
      "untied": true,
      "width": 190,
      "length": 340,
      "height": 120,
      "actualWeight": 2000
    }
  ],
  "sender": {
    "companyTin": "",
    "companyName": "",
    "phone": 48993453453,
    "email": "example@mail.pl",
    "name": "Surname Name",
    "ioss": null,
    "countryCode": "LT",
    "divisionNumber": null,
    "addressParts": {
      "city": "Vilnius",
      "region": "Vilniaus apskritis",
      "street": "Žalgirio g",
      "postCode": "12546",
      "building": "92",
      "flat": "",
      "block": "",
      "note": ""
    }
  },
  "recipient": {
    "companyTin": "",
    "companyName": "",
    "phone": 380001234567,
    "email": "example@mail.com",
    "name": "Surname Name",
    "countryCode": "UA",
    "divisionNumber": "32521/1",
    "addressParts": {}
  }
}

{
  "id": 113677,
  "number": "SHLT4009860665",
  "scheduledDeliveryDate": "2023-04-14T09:00:00.000000Z",
  "status": "ReadyToShip",
  "cost": 31,
  "parcelsAmount": 1,
  "createdAt": "2023-04-11T10:42:05.543380Z",
  "updatedAt": "2023-04-11T10:42:05.543380Z",
  "deletedAt": null
}

Видалити транспортний документ

delete

/shipments/{id}

Цей метод дозволяє видалити транспортний документ на підставі його унікального ідентифікатора (ID). Для успішного видалення документа із системи запит повинен містити його ID. Відповідь міститиме інформацію про успішність виконання операції.

Особливості реалізації для різних регіонів:

1. Європа:

Метод насамперед очікує унікальний ID (Ref ID) документа.
Додатково підтримується видалення за номером відправлення (наприклад, SHPL0123456789).

2. Україна:

Видалення підтримується лише за Ref ID (унікальним ідентифікатором документа).
Видалення за номером відправлення (наприклад, номером експрес-накладної) не підтримується.

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstringRequired

ID транспортного документа (відправлення).

Example: {"summary":"International shipment","value":456931}

Responses

200

відправлення

application/json

deletedAtstringOptional

Дата й час видалення документа.

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

delete/shipments/{id}

DELETE /v.1.0/shipments/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{ "deletedAt": "2023-04-18T11:47:19.290462Z" }

Завантажити файл до відправлення

post

/shipments/uploads/{id}

Завантажує супровідні документи до конкретного відправлення за його ID. Цей метод використовується для додавання інвойсів, специфікацій товарів, митних декларацій або інших документів, пов'язаних із відправленням, необхідних для обробки та митного оформлення. Файли зберігаються та прив'язуються до відправлення, забезпечуючи кращу простежуваність і відповідність вимогам.

⚠️ Обмеження за регіоном: Цей метод доступний лише для європейських відправлень (напрямки EU/EU та EU/UA). Він недоступний для відправлень, що відправляються з України.

Ім'я файлу: • Якщо передано параметр "fileName", завантажений файл буде збережено з указаним ім'ям. • Якщо параметр "fileName" не передано, за замовчуванням буде встановлено ім'я файлу "invoice".

Приклади використання:

"Я хочу завантажити PDF-інвойс клієнта до відправлення 980911" — передайте вміст, закодований у base64, у параметрі "file" та встановіть "fileName": "invoice.pdf".
"Я хочу додати фотографію товару у форматі JPEG" — закодуйте фотографію у base64 та встановіть "fileName": "product-photo.jpeg".

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idinteger · int32Required

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

Body

filestringOptional

Файл документа, закодований у base64 (PDF, JPEG або інші підтримувані формати).

fileNamestringOptional

Необов'язкове ім'я файлу. Якщо не вказано, за замовчуванням використовується значення "invoice".

Responses

201

Результат завантаження файлу

application/json

successbooleanOptional

Вказує, чи було файл успішно завантажено.

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

post/shipments/uploads/{id}

POST /v.1.0/shipments/uploads/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "file": "/9j/4AAQSkZJRgABAQEAYABgAAD... (base64 content truncated)",
  "fileName": "product-photo.jpeg"
}

{
  "success": true
}

Друк транспортних документів

get

/shipments/print

Цей API-метод дозволяє отримати маркування транспортного документа у форматі PDF за номером документа. Маркування документа є документом для друку, який клієнти можуть прикріпити або наклеїти на свій вантаж під час його відправлення. Вказавши номер документа в запиті, ви можете згенерувати PDF-файл, що містить маркування документа, для зручного друку.

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

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

Authorizations

AuthorizationstringRequired

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

Query parameters

numbers[]stringOptional

Номери відправлень. Може приймати як один номер, так і масив номерів. Якщо використовується type=marking, у межах одного запиту дозволяється передавати лише один номер.

Example: SHPL1234567890

deliveryTypestring · enumOptional

Тип логістичного процесу для друку документа маркування. Застосовується лише для type=marking.

Pickup: перша миля
Shipment: остання миля

Possible values:

Responses

200

PDF-файл.

application/pdf

string · binaryOptional

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

get/shipments/print

GET /v.1.0/shipments/print HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

binary

Базове відстеження

get

/shipments/tracking/history

Цей API-метод дозволяє отримати статус відправлення, вказавши номер транспортного документа. Зазначивши номер документа в запиті, ви можете отримати інформацію про поточне місцезнаходження або статус відправлення, надаючи клієнтам оновлення в режимі реального часу щодо переміщення їхнього вантажу. 🔸Цей метод працює лише з номером транспортного документа (номером відправлення) і не підтримує пошук за номерами замовлень клієнта або будь-якими зовнішніми ідентифікаторами. 🔸Базове відстеження надає спрощену відповідь відстеження, зосереджену на історії статусів відправлення та, за потреби, пов'язаних номерах відправлень. На відміну від Повне відстеження, цей метод не повертає детальну інформацію про маршрут, дані на рівні окремих місць, причини недоставки, записи про повернення/переадресацію або розширені метадані. Цей метод призначений для швидкої та легкої перевірки статусів.

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

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

Authorizations

AuthorizationstringRequired

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

Query parameters

numbers[]stringOptional

Номери відправлень. Може приймати як один номер, так і масив номерів.

Example: SHPL1234567890

extendedstringOptional

Параметр, що відповідає за включення до відповіді масиву об'єктів зі списком усіх пов'язаних відправлень.

Щоб отримати ці дані у відповіді, встановіть значення 1.

Default: 0Example: 1

Responses

200

Схема відповіді відстеження

application/json

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

get/shipments/tracking/history

GET /v.1.0/shipments/tracking/history HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "id": "111003",
      "number": "SHPL1234567890",
      "history_tracking": [
        {
          "code": "1",
          "code_name": "Zamówienie zostało utworzone. Poczekaj na wysłanie przesyłki",
          "country_code": "PL",
          "settlement": "Głogów Małopolski",
          "date": "2023-03-10T05:57:09.626014Z"
        }
      ],
      "related_numbers": [
        "SHPL2345678901"
      ]
    }
  ]
}

Повне відстеження

get

/shipments/tracking

За замовчуванням відповідь містить такі блоки даних:

Поточний статус відправлення;
Історія відстеження;
Актуальна історія відстеження;
Опис відправлення;
Розширена інформація про пов'язані відправлення.

За потреби до відповіді можна включити додаткові блоки, передавши відповідні параметри:

withUndeliveryReason = true — додає масив об'єктів з інформацією про причини недоставки відправлень.
withCreatedOnTheBasis = true — додає масив об'єктів з інформацією про повернення або переадресації, пов'язані з відправленням.

🔸Повне відстеження надає вичерпну відповідь відстеження, що містить детальні дані про статус відправлення, повну історію переміщення, опис місць, причини недоставки та інформацію про пов'язані або похідні відправлення. На відміну від Базового відстеження, воно надає розширені операційні дані та призначене для випадків, коли потрібна повна видимість логістичного життєвого циклу відправлення.

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

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

Authorizations

AuthorizationstringRequired

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

Query parameters

numbers[]stringOptional

Номери відправлень. Може приймати як один номер, так і масив номерів.

Example: SHPL1234567890

ids[]integer · int32Optional

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

Example: 113622

withUndeliveryReasonbooleanOptional

Параметр, що відповідає за включення до відповіді масиву об'єктів з інформацією про причини недоставки.

Щоб отримати ці дані у відповіді, встановіть значення true.

Default: falseExample: true

withCreatedOnTheBasisbooleanOptional

Параметр, що відповідає за включення до відповіді масиву об'єктів з інформацією про пов'язані відправлення (типи: Redirecting, Return, Utilization, Redelivery).

Щоб отримати ці дані у відповіді, встановіть значення true.

Default: falseExample: true

countryCodestringOptional

Дволітерний код країни відправника відповідно до стандарту ISO 3166-1 Alpha-2.

Якщо цей параметр указано, Історія відстеження та Актуальна історія відстеження відображатимуться лише для зазначеної країни.

Pattern: ^[A-Z]{2}$

Example: DE

externalstringOptional

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

Щоб отримати ці дані у відповіді, встановіть значення 1.

Default: 0Example: 1

trackingByBarcodestringOptional

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

Example: SHRO1452163509

withAllParcelsbooleanOptional

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

Default: falseExample: true

Responses

200

Схема відповіді відстеження

application/json

alternativeNumbersstring[]Optional

Масив об'єктів, що містить список пов'язаних відправлень.

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

get/shipments/tracking

GET /v.1.0/shipments/tracking HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "currentStatus": {
        "number": "SHPL2326420334",
        "createdDate": "2025-07-01T09:18:44.000000Z",
        "scheduledDate": "2025-07-01T15:00:00.000000Z",
        "scheduledDateOriginal": null,
        "adjustedDate": null,
        "closingDate": "2025-07-01T09:20:04.000000Z",
        "statusCode": 9,
        "status": "Delivered 01.07",
        "statusDate": "2025-07-01T09:20:11.299982Z",
        "deliveryType": "Division",
        "deliveryCountry": "DE"
      },
      "detailsTracking": [
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:46.000000Z",
          "event": "ArrivalSenderDoors",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "The courier picked up the parcel",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:50.000000Z",
          "event": "Arrival",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": null,
          "settlementName": "Amsterdam",
          "eventName": "Arrived at branch 2",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "103-00160415",
          "date": "2025-07-01T09:19:37.000000Z",
          "event": "OrderRedirecting",
          "eventStatus": "passed",
          "code": "104",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "Delivery location has been changed",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": null
        },
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:20:04.000000Z",
          "event": "ReceivedWarehouse",
          "eventStatus": "now",
          "code": "9",
          "postCode": "1011AB",
          "divisionName": "branch 5",
          "settlementName": "Amsterdam",
          "eventName": "Delivered at branch 5",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": "NL"
        }
      ],
      "historyOnlineTracking": [
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:46.000000Z",
          "event": "ArrivalSenderDoors",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "The courier picked up the parcel",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "103-00160415",
          "date": "2025-07-01T09:19:37.000000Z",
          "event": "OrderRedirecting",
          "eventStatus": "passed",
          "code": "104",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "Delivery location has been changed",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": null
        },
        {
          "number": "51499647910100",
          "date": "2025-07-01T09:20:04.000000Z",
          "event": "ReceivedWarehouse",
          "eventStatus": "now",
          "code": "9",
          "postCode": "1011AB",
          "divisionName": "branch 5",
          "settlementName": "Amsterdam",
          "eventName": "Delivered at branch 5",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": "NL"
        }
      ],
      "parcelsDetailsTracking": null,
      "parcelsHistoryOnlineTracking": null,
      "parcels": [
        {
          "number": "SHPL2326420334",
          "rowNumber": null,
          "untied": false,
          "cargoCategoryGroup": "parcel",
          "cargoCategoryId": "",
          "categoryCargoName": "Parcel",
          "parcelDescription": null,
          "insuranceCost": 25,
          "insuranceCostCurrencyCode": "EUR",
          "length": 25,
          "width": 15,
          "height": 18,
          "actualWeight": 5,
          "volumetricWeight": 1.69,
          "lengthCheck": null,
          "widthCheck": null,
          "heightCheck": null,
          "actualWeightCheck": null,
          "volumetricWeightCheck": null
        }
      ],
      "alternativeNumbers": [],
      "alternativeNumbersGW": [],
      "deliveryInfo": null,
      "undeliveryReasons": [
        {
          "reasonName": "Delivery date rescheduling has been agreed with the client",
          "reasonDate": "2025-07-01T09:35:46.000000Z",
          "reasonId": "66a936c6-f223-11dd-a18e-001d92f78697",
          "subtypeOfReasonId": "c30ec884-d9ff-11ed-a361-48df37b92096",
          "subtypeOfReasonName": "Recipient does not respond / Sender rescheduled the date to"
        }
      ],
      "createdOnTheBasis": [
        {
          "number": "51499647910100",
          "type": "Redirecting",
          "createdAt": "2025-07-01T09:19:49.000000Z"
        }
      ]
    }
  ]
}

Список вкладень

get

/shipments/{shipmentNumber}/attachments

Повертає список доступних файлів, прикріплених до відправлення (фотографії та/або підпис), для вказаного відправлення лише якщо відправлення належить автентифікованому клієнту.

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

shipmentNumberstringRequired

Номер відправлення.

Example: SHDE2072834273

Responses

200

Структура метаданих

application/json

shipmentIdintegerOptional

Внутрішній ідентифікатор відправлення.

createdAtstringOptional

Дата й час завантаження файлу. Дата у форматі ISO 8601.

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Можливі відповіді з помилками

application/json

503

Час очікування з’єднання вичерпано

application/json

get/shipments/{shipmentNumber}/attachments

GET /v.1.0/shipments/{shipmentNumber}/attachments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

[
  {
    "shipmentId": 279708,
    "storageInfo": {
      "id": "c0da6fe9-997b-4f8d-b798-0150e50a6655",
      "name": "string (11).png",
      "documentType": "signature"
    },
    "createdAt": "2025-07-29T14:07:30.135738Z"
  },
  {
    "shipmentId": 279708,
    "storageInfo": {
      "id": "da2dc99f-c7e9-478d-9597-9ccca38f6bdb",
      "name": "IMG_8034.JPG.png",
      "documentType": "proofOfDelivery"
    },
    "createdAt": "2025-07-29T14:08:16.476107Z"
  },
  {
    "shipmentId": 279708,
    "storageInfo": {
      "id": "038a5340-f2a1-4982-a88b-8ad01b80bd81",
      "name": "IMG_7298.JPG.png",
      "documentType": "proofOfDelivery"
    },
    "createdAt": "2025-07-29T14:07:30.135738Z"
  },
  {
    "shipmentId": 279708,
    "storageInfo": {
      "id": "257f5a42-1c0f-48aa-9805-0af3a757b863",
      "name": "IMG_8000.JPG.png",
      "documentType": "proofOfDelivery",
      "createdAt": "2025-07-29T14:07:30.135738Z"
    }
  }
]

Завантажити вкладення

get

/shipments/{shipmentNumber}/attachments/{fileId}

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

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

shipmentNumberstringRequired

Номер відправлення.

Example: SHDE2072834273

fileIdstringRequired

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

Example: 60946ff4-8170-415b-ab66-719848ef1da7

Responses

200

Файл.

application/pdf

string · binaryOptional

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Неможливо обробити сутність.

application/json

503

Час очікування з’єднання вичерпано

application/json

get/shipments/{shipmentNumber}/attachments/{fileId}

GET /v.1.0/shipments/{shipmentNumber}/attachments/{fileId} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

binary

Створити повторну доставку

post

/shipments/modification/repeat-delivery

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

Основні правила:

Доступний лише для відправлень, які наразі перебувають на довгостроковому зберіганні (LTS).
Для одного відправлення дозволено не більше 4 завершених послуг повторної доставки.
Послугу повторної доставки не можна замовити, якщо для відправлення вже існує запит на переадресацію (Redirecting), повернення (Return) або повторну доставку (Repeat Delivery) зі статусом NeedProcessing або InProgress.

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

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

Authorizations

AuthorizationstringRequired

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

Body

shipmentIdintegerRequired

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

🔻Це поле є обов'язковим.

payerTypestring · enum · nullableOptional

Визначає, хто відповідає за оплату послуги повторної доставки.

Допустимі значення:

Sender
Recipient
ThirdPerson

Якщо поле не передано, послугу оплачує користувач, який створює замовлення.

Possible values:

payerContractNumberstring · nullableOptional

Обов'язковий параметр для B2B-клієнтів (юридичних осіб з оплатою за договором).

notestringOptional

Будь-який коментар до замовлення.

Responses

200

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

application/json

costnumberOptional

Вартість послуги повторної доставки.

currencystringOptional

Код валюти відповідно до стандарту ISO 4217.

currencySymbolstringOptional

Символ валюти.

scheduledDeliveryDatestring · date-timeOptional

Орієнтовна дата доставки у форматі ISO 8601.

401

Неавторизований доступ

application/json

422

Помилка валідації.

application/json

503

Час очікування з’єднання вичерпано

application/json

post/shipments/modification/repeat-delivery

POST /v.1.0/shipments/modification/repeat-delivery HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 502

{
  "shipmentId": 440459,
  "payerContractNumber": "String",
  "payerType": "Sender",
  "note": "Repeat delivery to a new address",
  "recipient": {
    "name": "John Doe",
    "phone": "37360123456",
    "email": "john.doe@example.com",
    "companyTin": "38130410",
    "companyName": "String",
    "countryCode": "MD",
    "eoriCode": null,
    "settlementId": null,
    "divisionId": null,
    "address": {},
    "addressParts": {
      "postCode": "1345",
      "building": "3",
      "street": "Mircea cel Batrin",
      "city": "Chișinău",
      "region": "Chișinău",
      "flat": "",
      "note": "Near central park",
      "block": ""
    }
  }
}

{
  "cost": 69,
  "currency": "MDL",
  "currencySymbol": "",
  "scheduledDeliveryDate": "2026-03-31T15:00:00.000000Z"
}

Скасувати повторну доставку

delete

/shipments/modification/repeat-delivery/delete/{shipmentID}

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

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

Основні правила:

Скасування доступне лише доти, доки замовлення на повторну доставку ще перебуває в обробці.
Після завершення повторної доставки її неможливо скасувати.

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

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

Authorizations

AuthorizationstringRequired

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

Path parameters

shipmentIDintegerRequired

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

Example: 440459

Responses

200

Замовлення на повторну доставку успішно скасовано. Повертає часову позначку скасування.

application/json

deletedAtstringRequired

Часова позначка, коли замовлення на повторну доставку було скасовано.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$

422

Неможливо обробити сутність. Скасування неможливо виконати.

application/json

delete/shipments/modification/repeat-delivery/delete/{shipmentID}

DELETE /v.1.0/shipments/modification/repeat-delivery/delete/{shipmentID} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "deletedAt": "2026-06-08T15:15:33.043730Z"
}

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