Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Кур'єрська доставка

Отримати список заявок на кур’єрський забір

get
/pickups

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

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

Поведінка: Запит на забір із послугою CourierPickupService може бути переведений у статус Created без пов'язаних відправлень. Відправлення можуть бути додані пізніше після створення запиту на забір.

Доступність: Послуга є обмеженою та доступна лише для авторизованих бізнес-акаунтів відповідно до індивідуальних умов договору. Наразі послуга доступна в Молдові.

Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post.

Authorizations
AuthorizationstringRequired

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

Query parameters
numbers[]stringOptional

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

Example: PUCZ0000002671
ids[]integer · int32Optional

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

🔹Ідентифікатор id можна отримати з відповіді на метод Створити заявку на кур’єрський забір або шляхом пошуку заявки на забір за номером документа.

Example: 28813
serviceCodes[]stringOptional

Фільтрація запитів на забір за кодом послуги.

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

  • CourierPickupService

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

Example: CourierPickupService
limitinteger · int32Optional

Максимальна кількість елементів, що повертаються на сторінці.

Default: 15Example: 1
pageinteger · int32Optional

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

Example: 1
Body
idsstring · max: 296132Optional

A list of pickup request IDs to search.

Responses
200

Список заявок на кур’єрський забір успішно отримано

application/json
current_pageinteger · min: 1Optional

Поточна сторінка результатів у пагінованій відповіді.

last_pageinteger · min: 1Optional

Остання доступна сторінка в пагінованій відповіді.

per_pageinteger · min: 1Optional

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

totalintegerOptional

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

get/pickups
GET /v.1.0/pickups HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "ids": [
    296132
  ]
}
{
  "current_page": 1,
  "last_page": 1,
  "per_page": 15,
  "total": 1,
  "items": [
    {
      "id": "28813",
      "number": "PUPL0000013342",
      "versionTracking": null,
      "status": "Draft",
      "statusDateTime": "2024-12-20T09:01:56.927000Z",
      "createdAt": "2024-12-20T09:01:56.928000Z",
      "updatedAt": "2024-12-20T11:58:08.731000Z",
      "deletedAt": null,
      "lastPublishedAt": "2024-12-20T11:58:08.000000Z",
      "lastUpdatedAt": "2024-12-20T11:58:08.831311Z",
      "source": "clientapi",
      "executor": null,
      "companyTin": "",
      "companyName": null,
      "fullName": "Chulkov Ihor",
      "phone": "380001234567",
      "email": "i.s.chulkov@gmail.com",
      "country": "Poland",
      "countryCode": "PL",
      "createdByUser": "84dbbfac-3508-11ee-a361-48df37b92096",
      "deliveryPartner": null,
      "lockVersion": 2,
      "divisionId": null,
      "settlementId": 22326,
      "settlementExternalId": null,
      "settlementName": "Warsaw",
      "cityDistrict": null,
      "cityDistrictExternalId": null,
      "address": {
        "postCode": "17890",
        "region": "Warszawa County",
        "city": "Warszawa",
        "street": "15 Sierpnia",
        "building": "1",
        "block": "",
        "flat": "",
        "note": "",
        "address": "17890, Polska, Województwo mazowieckie, Warszawa County, Warszawa, 15 Sierpnia, 1, , , ",
        "addressId": null,
        "latitude": 52.3264159,
        "longitude": 20.9854961,
        "timeZoneId": 367,
        "timeZone": "Europe/Warsaw"
      },
      "addressParts": {
        "postCode": "17890",
        "region": "Warszawa County",
        "city": "Warszawa",
        "street": "15 Sierpnia",
        "building": "1",
        "block": "",
        "flat": "",
        "note": "Information about building entrance for courier access"
      },
      "pickedTimeFrom": "2024-12-01T15:00:00.000000Z",
      "pickedTimeTo": "2024-12-01T18:00:00.000000Z",
      "note": "Test pickup request",
      "currencyCode": "CZK",
      "shipments": [],
      "services": [
        {
          "id": 1040,
          "shipmentParcelRowNumber": "",
          "serviceId": "12292132641000939",
          "pickupId": 604431,
          "serviceType": "PickUpManual",
          "serviceName": "",
          "serviceCode": "CourierPickupService",
          "parcelNumber": "",
          "payerType": "Sender",
          "contractNumber": "string",
          "amount": 150,
          "price": 250,
          "discount": 0,
          "cost": 250,
          "costBeforeCheck": false,
          "paymentStatus": "ContractAfterPayment",
          "currencyCode": "MDL",
          "executionAt": "2026-06-16T10:20:42.564463Z",
          "additionalParameters": {
            "parcel_description": "string",
            "parcels_amount": 10,
            "total_actual_weight": 0,
            "total_volumetric_weight": 0,
            "length": 0,
            "width": 0,
            "height": 0
          }
        }
      ],
      "statuses": [
        {
          "id": 109777,
          "pickupId": 28813,
          "status": "Draft",
          "dateTime": "2024-12-01T13:55:57.350277Z",
          "note": null,
          "user": "d389d1ec-2078-4b62-8bc0-696c72a52a65",
          "createdAt": "2025-01-22T07:58:52.388849Z",
          "updatedAt": "2025-01-22T07:58:52.388849Z",
          "deletedAt": null
        }
      ]
    }
  ]
}

Отримати доступні часові інтервали для кур’єрського забору

post
/time-intervals/find

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

Обов'язкові параметри:

  • countryCode: Вказує код країни відповідно до стандарту ISO 3166-1 Alpha-2.

  • type: Визначає тип забору. Допустимі значення: PickupDayToDay (забір день у день) або PickupNextDay (забір на наступний день).

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

Рекомендовані параметри для точних результатів:

  • addressParts: Надайте повну адресу забору, включаючи будівлю, вулицю, місто, регіон та поштовий індекс. Це гарантує повернення точних часових інтервалів для вказаної адреси.

  • latitude та longitude: Використовуйте географічні координати для визначення зони, якщо повна адреса недоступна.

  • divisionId: Вкажіть ID найближчого відділення, якщо точна адреса невідома. Проте зауважте, що близькість до відділення не гарантує, що кур'єр, який обслуговує цю адресу, працює саме з цього відділення.

Додаткові параметри:

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

Важливі примітки:

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

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

Логіка вибору часових інтервалів:

  • Якщо існує конфігурація PickupDayToDay:

    • Вона має пріоритет над PickupNextDay.

    • Поточний день (сьогодні) доступний, якщо:

      • День не є святковим (holiday == false);

      • Існує робочий графік (from != null);

      • Поточний час < orderTo.

    • Може бути повернуто до 7 календарних днів (включаючи сьогодні), якщо:

      • Дні не є святковими;

      • Параметр from задано;

      • Перевірка orderTo застосовується лише для сьогоднішнього дня.

  • Якщо конфігурація PickupDayToDay відсутня, але налаштовано PickupNextDay:

    • Поточний день (сьогодні) недоступний.

    • Може бути повернуто до 7 календарних днів (виключаючи сьогодні), якщо:

      • Дні не є святковими;

      • Параметр from задано.

    • Обмеження orderTo застосовується наступного дня. Якщо поточний час > orderTo, завтрашній день виключається.

  • Якщо конфігурація часових інтервалів відсутня (резервний режим / fallback):

    • Поточний день (сьогодні) недоступний.

    • Може бути повернуто до 7 календарних днів (виключаючи сьогодні, вихідні та святкові дні).

    • Фіксоване значення orderTo = 17:00 застосовується лише для завтрашнього дня.

Примітка:

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

Поведінка валідації:

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

  • Якщо часовий інтервал недійсний або порожній, кур'єр прибуде протягом усього робочого періоду.

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

Authorizations
AuthorizationstringRequired

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

Body
typestring · enumRequired

Тип часового інтервалу. Доступні значення: PickupDayToDay або PickupNextDay.

Possible values:
countryCodestringRequired

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

Pattern: ^[A-Z]{2}$
divisionIdinteger · min: 1 · nullableOptional

Ідентифікатор відділення для визначення конкретного відділення.

latitudenumber · min: -90 · max: 90 · nullableOptional

Широта для пошуку за географічними координатами.

longitudenumber · min: -180 · max: 180 · nullableOptional

Довгота для пошуку за географічними координатами.

maxWeightPlaceRecipientinteger · nullableOptional

Вага відправлення в кілограмах. Необов’язковий параметр для інтервалів, які не залежать від ваги.

Responses
200

Часові інтервали успішно отримано

application/json
idinteger · min: 1Optional

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

countryCodestringOptional

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

Pattern: ^[A-Z]{2}$
divisionIdinteger · min: 1 · nullableOptional

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

typestring · enumOptional

Тип часового інтервалу.

Possible values:
deliveryPartnerstring · nullableOptional

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

ignoreNonWorkingDaysbooleanOptional

Визначає, чи враховуються неробочі дні під час пошуку.

createdAtstring · date-timeOptional

Дата та час первинного створення запису.

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$
updatedAtstring · date-timeOptional

Дата та час останнього оновлення запису.

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$
deletedAtstring · date-time · nullableOptional

Дата та час видалення запису.

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$
post/time-intervals/find
POST /v.1.0/time-intervals/find HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 264

{
  "type": "PickupNextDay",
  "countryCode": "CZ",
  "latitude": 50.0755,
  "longitude": 14.4378,
  "maxWeightPlaceRecipient": 5,
  "addressParts": {
    "building": "30",
    "street": "Václavské náměstí",
    "city": "Prague",
    "region": "Central Bohemia",
    "postCode": "11000",
    "note": "Near the statue"
  }
}
{
  "id": 1,
  "countryCode": "CZ",
  "divisionId": null,
  "type": "PickupNextDay",
  "deliveryPartner": null,
  "ignoreNonWorkingDays": false,
  "monday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "tuesday": {
    "from": "08:00",
    "to": "20:00",
    "orderTo": "19:30",
    "timeIntervals": [
      {
        "from": "08:00",
        "to": "12:00",
        "orderTo": "11:30"
      },
      {
        "from": "13:00",
        "to": "20:00",
        "orderTo": "19:30"
      }
    ]
  },
  "wednesday": {
    "from": "08:00",
    "to": "20:00",
    "orderTo": "19:00",
    "timeIntervals": []
  },
  "thursday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "friday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "saturday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "sunday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "createdAt": "2024-12-01T13:55:57.350861Z",
  "updatedAt": "2024-12-01T13:55:57.350861Z",
  "deletedAt": null
}

Створити заявку на кур’єрський забір

post
/pickups

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

Початковий статус (Draft): Заявка на кур’єрський забір створюється зі статусом Draft, що дозволяє клієнтам додати до заявки всі необхідні відправлення.

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

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

Додаткова послуга – CourierPickupService: Клієнти можуть додатково передавати інформацію про плановий вантаж у масиві services за допомогою послуги CourierPickupService. Це дозволяє вказати орієнтовні характеристики відправлення, такі як опис вантажу, кількість місць, фактична та об'ємна вага, а також додаткові габарити. Наразі послуга доступна в Молдові. Ця інформація використовується під час планування забору та обробки кур'єрського запиту.

Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post.

Authorizations
AuthorizationstringRequired

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

Body
notestring · max: 255Optional

Необов’язкові примітки або інструкції для кур’єра.

servicesarray · nullableOptional

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

Наразі підтримується наступна послуга:

  • CourierPickupService — дозволяє клієнту передати інформацію про плановий вантаж, яка буде використана під час планування забору та обробки кур'єрського запиту.
phonestring · min: 8 · max: 14Optional

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

emailstring · nullableOptional

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

fullNamestring · max: 100Optional

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

companyTinstring · min: 2 · max: 20Optional

Податковий ідентифікаційний номер (ІПН) юридичної особи.

companyNamestring · min: 2 · max: 255Optional

Назва компанії, яка оформлює заявку на кур’єрський забір.

countryCodestringOptional

Код країни місця кур’єрського забору відповідно до стандарту ISO Alpha-2.

Pattern: ^[A-Z]{2}$
pickedTimeFromstring · date-time · nullableOptional

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

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$
pickedTimeTostring · date-time · nullableOptional

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

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$
Responses
201

Заявку на кур’єрський забір успішно створено

application/json
idinteger · min: 1Optional

Унікальний ідентифікатор заявки на кур’єрський забір.

numberstringOptional

Реєстраційний номер заявки на кур’єрський забір.

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

Поточний статус заявки на кур’єрський забір, що відображає етап її обробки.

Можливі значення:

  • Draft — початковий статус, у якому заявку створено, але ще не завершено її оформлення.
  • Created — заявку створено та підготовлено до обробки.
  • AppointedCourier — для заявки призначено кур’єра.
  • InProgress — кур’єрський забір виконується.
  • Done — кур’єрський забір успішно завершено.
  • ClientCanceled — заявку скасовано клієнтом.
  • NotCompleted — кур’єрський забір не вдалося виконати.
  • Deleted — заявку видалено із системи.
  • ReceivedByCourier — відправлення отримано кур’єром.
statusDateTimestring · date-timeOptional

Дата та час останнього оновлення статусу.

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$
sourcestring · max: 50Optional

Джерело створення заявки, зазвичай "clientapi".

executorstring · max: 50 · nullableOptional

Виконавець, призначений для виконання кур’єрського забору, якщо такий є.

companyTinstring · min: 2 · max: 20Optional

ІПН юридичної особи.

companyNamestring · min: 2 · max: 255Optional

Назва компанії.

fullNamestring · max: 100Optional

Повне ім’я заявника.

phonestring · min: 8 · max: 14Optional

Контактний номер телефону.

emailstring · nullableOptional

Контактна електронна адреса, якщо вказана.

countryCodestringOptional

Код країни місця кур’єрського забору.

Pattern: ^[A-Z]{2}$
createdByUserstring · max: 50Optional

Ідентифікатор користувача, який створив заявку.

deliveryPartnerstring · nullableOptional

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

lockVersioninteger · min: 1Optional

Номер версії для контролю одночасних змін.

divisionIdinteger · min: 1 · nullableOptional

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

settlementIdinteger · min: 1Optional

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

cityDistrictstring · max: 50 · nullableOptional

Район міста місця кур’єрського забору, якщо застосовується.

pickedTimeFromstring · date-time · nullableOptional

Початок часового інтервалу кур’єрського забору, вказаного у запиті.

pickedTimeTostring · date-time · nullableOptional

Кінець часового інтервалу кур’єрського забору, вказаного у запиті.

notestring · max: 255 · nullableOptional

Примітка або інструкції для кур’єра.

currencyCodestringOptional

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

Pattern: ^[A-Z]{3}$
externalIdstring · nullableOptional

Внутрішні дані. Не призначено для використання.

shipmentsobject[]Optional

Список відправлень, пов’язаних із цією заявкою на кур’єрський забір.

createdAtstring · date-timeOptional

Дата та час створення заявки на кур’єрський забір.

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$
updatedAtstring · date-timeOptional

Дата та час останнього оновлення заявки на кур’єрський забір.

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$
deletedAtstring · date-time · nullableOptional

Дата та час видалення заявки на кур’єрський забір.

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$
post/pickups
POST /v.1.0/pickups HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 449

{
  "note": "Test pickup 777",
  "services": [],
  "phone": "48900555111",
  "email": "chucknorris@roundhouse.kick",
  "fullName": "Chuck Norris",
  "companyTin": "",
  "companyName": "",
  "countryCode": "PL",
  "addressParts": {
    "city": "Warszawa",
    "region": "Warszawa County",
    "street": "Admiralska",
    "postCode": "01234",
    "building": "1",
    "flat": "1",
    "block": "",
    "note": "Test shipment, do not process"
  },
  "pickedTimeFrom": "2025-12-11T10:36:25.000000Z",
  "pickedTimeTo": "2025-12-11T10:36:25.000000Z"
}
{
  "id": 296132,
  "number": "PUPL7092967496",
  "status": "Draft",
  "statusDateTime": null,
  "source": "clientapi",
  "executor": null,
  "companyTin": "",
  "companyName": "",
  "fullName": "Chuck Norris",
  "phone": "48900555111",
  "email": "chucknorris@roundhouse.kick",
  "countryCode": "PL",
  "createdByUser": "acab5818-0944-5595-b30c-b788ae280f61",
  "deliveryPartner": null,
  "lockVersion": 1,
  "divisionId": null,
  "settlementId": 22326,
  "cityDistrict": null,
  "address": {
    "string": "01234, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Admiralska, 1, , 1, Test shipment, do not process",
    "latitude": 52.26215209999999,
    "longitude": 21.1792149
  },
  "addressParts": {
    "postCode": "01234",
    "building": "1",
    "street": "Admiralska",
    "city": "Warszawa",
    "region": "Warszawa County",
    "flat": "1",
    "note": "Test shipment, do not process",
    "block": ""
  },
  "pickedTimeFrom": "2025-12-11T10:36:25.000000Z",
  "pickedTimeTo": "2025-12-11T10:36:25.000000Z",
  "note": "Test pickup 777? Тестовий пікап, не обробляйте!",
  "currencyCode": "PLN",
  "externalId": null,
  "shipments": [],
  "services": [],
  "statuses": [
    {
      "id": 634036,
      "pickupId": 296132,
      "status": "Draft",
      "dateTime": "2025-12-11T10:36:28.551560Z",
      "note": null,
      "user": "acab5818-0944-4395-b30c-b788ae280f61",
      "createdAt": "2025-12-11T10:36:28.552814Z",
      "updatedAt": "2025-12-11T10:36:28.552814Z",
      "deletedAt": null
    }
  ],
  "createdAt": "2025-12-11T10:36:28.552814Z",
  "updatedAt": "2025-12-11T10:36:28.552814Z",
  "deletedAt": null
}

Оновити заявку на кур’єрський забір

put
/pickups/{id}

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

Authorizations
AuthorizationstringRequired

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

Path parameters
idinteger · min: 1Required

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

🔹Ідентифікатор id можна отримати з відповіді на метод Створити заявку на кур’єрський забір або за допомогою методу Отримати список заявок на кур’єрський забір, виконавши пошук заявки за номером документа.

Body
notestring · max: 255Optional

Додаткові примітки або інструкції для кур’єра.

servicesstring[] · nullableOptional

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

phonestring · min: 8 · max: 14Optional

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

emailstring · nullableOptional

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

fullNamestring · max: 100Optional

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

companyTinstring · min: 2 · max: 20Optional

ІПН юридичної особи.

companyNamestring · min: 2 · max: 255Optional

Назва компанії, яка створила заявку на кур’єрський забір.

lockVersioninteger · min: 1Optional

Номер версії для запобігання конфліктам під час оновлення даних. При кожному наступному оновленні заявки значення цього параметра необхідно збільшувати на 1.

countryCodestringOptional

Код країни місця кур’єрського забору у форматі ISO Alpha-2.

Pattern: ^[A-Z]{2}$
pickedTimeFromstring · date-time · nullableOptional

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

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$
pickedTimeTostring · date-time · nullableOptional

Кінець часового інтервалу кур’єрського забору, вибраного зі списку доступних часових інтервалів, отриманих через відповідний метод.

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$
Responses
200

Заявку на кур’єрський забір успішно оновлено

application/json
idinteger · min: 1Optional

Унікальний ідентифікатор оновленої заявки на кур’єрський забір.

numberstringOptional

Реєстраційний номер заявки на кур’єрський забір.

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

Поточний статус заявки на кур’єрський забір, що відображає етап її обробки.

Можливі значення:

  • Draft: Початковий етап, коли заявку створено, але ще не завершено її оформлення.
  • Created: Заявку створено та підготовлено до обробки.
  • AppointedCourier: Для заявки призначено кур’єра.
  • InProgress: Кур’єрський забір виконується.
  • Done: Кур’єрський забір успішно завершено.
  • ClientCanceled: Заявку скасовано клієнтом.
  • NotCompleted: Кур’єрський забір не вдалося виконати.
  • Deleted: Заявку видалено із системи.
  • ReceivedByCourier: Відправлення отримано кур’єром.
lockVersionintegerOptional

Оновлений номер версії для запобігання конфліктам під час оновлення даних.

notestring · max: 255Optional

Оновлені примітки для кур’єра.

pickedTimeFromstring · date-timeOptional

Оновлений початок часового інтервалу кур’єрського забору.

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$
pickedTimeTostring · date-timeOptional

Оновлений кінець часового інтервалу кур’єрського забору.

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$
statusesobject[]Optional

Масив оновлених статусів заявки на кур’єрський забір.

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

{
  "note": "Update note for the pickup",
  "services": [],
  "phone": "420123456789",
  "email": "test@example.cz",
  "fullName": "Updated Test User",
  "companyTin": "CZ98765432",
  "companyName": "Updated Test Company CZ",
  "lockVersion": 2,
  "countryCode": "CZ",
  "addressParts": {
    "city": "Prague",
    "region": "Prague",
    "street": "Národní",
    "postCode": "11000",
    "building": "9",
    "flat": "2",
    "block": "1",
    "note": "Updated building entrance information"
  },
  "pickedTimeFrom": "2024-12-02T14:00:00.000000Z",
  "pickedTimeTo": "2024-12-02T18:00:00.000000Z"
}
{
  "id": 28813,
  "number": "PUCZ0000002671",
  "status": "Draft",
  "lockVersion": 2,
  "note": "Na Rizdvo Sobi",
  "pickedTimeFrom": "2024-12-02T14:00:00.000000Z",
  "pickedTimeTo": "2024-12-02T18:00:00.000000Z",
  "addressParts": {
    "city": "Prague",
    "region": "Prague",
    "street": "Národní",
    "postCode": "11000",
    "building": "9",
    "flat": "2",
    "block": "1",
    "note": "Updated building entrance information"
  },
  "statuses": [
    {
      "id": 109777,
      "status": "Draft",
      "dateTime": "2024-11-13T18:52:57.350277Z",
      "createdAt": "2024-11-13T18:52:57.350861Z",
      "updatedAt": "2024-12-02T14:10:00.000000Z"
    }
  ]
}

Видалити заявку на виклик кур'єра

delete
/pickups/{id}

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

Authorizations
AuthorizationstringRequired

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

Path parameters
idinteger · min: 1Required

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

🔹Ідентифікатор id можна отримати з відповіді на метод Створити заявку на кур’єрський забір або за допомогою методу Отримати список заявок на кур’єрський забір, виконавши пошук заявки за номером документа.

Responses
200

Заявку на кур’єрський забір успішно видалено

application/json
deletedAtstring · date-timeOptional

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

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$
delete/pickups/{id}
DELETE /v.1.0/pickups/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "deletedAt": "2024-11-13T20:29:47.285749Z"
}

Додати відправлення до заявки на кур’єрський забір

post
/pickups/{id}/shipments

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

Authorizations
AuthorizationstringRequired

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

Path parameters
idinteger · min: 1Required

Унікальний ідентифікатор заявки на кур’єрський забір, до якої додаються відправлення.

🔹Ідентифікатор id можна отримати з відповіді на метод Створити заявку на кур’єрський забір або за допомогою методу Отримати список заявок на кур’єрський забір, виконавши пошук заявки за номером документа.

Body
Responses
200

Відправлення успішно додано до заявки на кур’єрський забір

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

{
  "shipments": [
    {
      "shipmentId": 1517240
    },
    {
      "shipmentId": 1517330
    }
  ]
}
{
  "shipments": [
    {
      "id": 189608,
      "pickupId": 296132,
      "shipmentId": 1517240,
      "status": "Added",
      "note": null,
      "deliveryPartners": [],
      "processOptions": [],
      "createdAt": "2025-12-11T10:36:28.552814Z",
      "updatedAt": "2025-12-11T10:45:46.929962Z",
      "deletedAt": null
    },
    {
      "id": 189609,
      "pickupId": 296132,
      "shipmentId": 1517330,
      "status": "Added",
      "note": null,
      "deliveryPartners": [],
      "processOptions": [],
      "createdAt": "2025-12-11T10:36:28.552814Z",
      "updatedAt": "2025-12-11T10:45:46.929962Z",
      "deletedAt": null
    }
  ]
}

Видалити відправлення із заявки на забір

delete
/pickups/{id}/shipments

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

Authorizations
AuthorizationstringRequired

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

Path parameters
idinteger · min: 1Required

Унікальний ідентифікатор заявки на кур’єрський забір.

🔹Ідентифікатор id можна отримати з відповіді на метод Створити заявку на кур’єрський забір або за допомогою методу Отримати список заявок на кур’єрський забір, виконавши пошук заявки за номером документа.

Body
Responses
200

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

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

{
  "shipments": [
    {
      "shipmentId": 370681
    }
  ]
}
{
  "shipments": [
    {
      "deletedAt": "2024-11-13T20:22:56.818679Z"
    }
  ]
}

Оновити статус заявки на забір

put
/pickups/{id}/status

Цей метод дозволяє оновлювати статус наявної заявки на кур’єрський забір. Цей метод спеціально розроблений для переведення заявки на виклик кур'єра зі статусу Draft у статус Created.

Поки заявка перебуває у статусі Draft, вона залишається на підготовчому етапі, під час якого можна додати всі необхідні відправлення. Щойно статус оновлюється на Created, система управління відправленнями розпізнає виклик кур'єра як завершений і готовий до обробки кур'єрською службою.

Authorizations
AuthorizationstringRequired

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

Path parameters
idinteger · min: 1Required

Унікальний ідентифікатор заявки на кур’єрський забір.

🔹Ідентифікатор id можна отримати з відповіді на метод Створити заявку на кур’єрський забір або за допомогою методу Отримати список заявок на кур’єрський забір, виконавши пошук заявки за номером документа.

Body
statusstring · enumRequired

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

Можливі значення: Draft, Created, AppointedCourier, InProgress, Done, ClientCanceled, NotCompleted, Deleted, ReceivedByCourier.

Possible values:
lockVersioninteger · min: 1Required

Номер версії для запобігання конфліктам під час оновлення даних. При кожному наступному оновленні заявки значення цього параметра необхідно збільшувати на 1.

notestring · max: 255Optional

Обов’язкова примітка або коментар із додатковою інформацією щодо причини зміни статусу. Поле необхідно заповнювати під час зміни статусу для забезпечення належного відстеження та збереження контексту змін.

Responses
200

Статус успішно оновлено

application/json
successbooleanOptional

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

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

{
  "status": "Created",
  "lockVersion": 2,
  "note": "Test changhe status to Created!"
}
{
  "success": true
}
ПопередняРеєстри
НаступнаWebhooks

Останнє оновлення