> For the complete documentation index, see [llms.txt](https://api-portal.novapost.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-portal.novapost.com/methods/ua/overview/pickups.md). # Кур'єрська доставка API підтримує два напрямки: **UA** та **EU**. Вони відрізняються послідовністю обробки заявки, моментом початку обробки та форматом ідентифікатора заявки. Детальні відмінності в параметрах, запитах і відповідях описані у документації кожного endpoint.
UAEU
Процес обробкиСтворення заявки → Пошук кур’єра → Призначення кур’єра → Обробка заявкиСтворення заявки → Додавання відправлень → Зміна статусу → Обробка заявки
Початок обробкиОдразу після створення заявкиПісля додавання відправлень та зміни статусу заявки
Формат ID заявкиUUID, наприклад 01a0b46a-dfea-7f9c-b1dc-7c7046afbaf7Integer, наприклад 296132
## Отримати список заявок на кур’єрський забір > Цей метод дозволяє бізнес-клієнтам отримати список усіх створених ними заявок на кур’єрський забір. Клієнти можуть фільтрувати список за окремими параметрами, наприклад за ідентифікатором кур’єрського забору або номером заявки.\ > \ > \*\*CourierPickupService\*\*:\
\ > Ця послуга дозволяє бізнес-клієнтам замовляти платний кур'єрський забір без попереднього створення відправлень.\ > \ > \*\*Поведінка\*\*:\
\ > Запит на забір із послугою \`CourierPickupService\` може бути переведений у статус \`Created\` без пов'язаних відправлень. Відправлення можуть бути додані пізніше після створення запиту на забір.\ > \ > \*\*Доступність\*\*:\
\ > Послуга є обмеженою та доступна лише для авторизованих бізнес-акаунтів відповідно до індивідуальних умов договору. Наразі послуга доступна в Молдові.\ > \ > \*\*🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.\*\*
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Pickups"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT-токен авторизації зі строком дії 1 годину у заголовку"}},"responses":{"Unauthorized":{"description":"Неавторизований доступ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Вказаний ресурс не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Помилка валідації","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups":{"get":{"tags":["Pickups"],"description":"Цей метод дозволяє бізнес-клієнтам отримати список усіх створених ними заявок на кур’єрський забір. Клієнти можуть фільтрувати список за окремими параметрами, наприклад за ідентифікатором кур’єрського забору або номером заявки.\n\n**CourierPickupService**:
\nЦя послуга дозволяє бізнес-клієнтам замовляти платний кур'єрський забір без попереднього створення відправлень.\n\n**Поведінка**:
\nЗапит на забір із послугою `CourierPickupService` може бути переведений у статус `Created` без пов'язаних відправлень. Відправлення можуть бути додані пізніше після створення запиту на забір.\n\n**Доступність**:
\nПослуга є обмеженою та доступна лише для авторизованих бізнес-акаунтів відповідно до індивідуальних умов договору. Наразі послуга доступна в Молдові.\n\n**🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.**\n","parameters":[{"in":"query","name":"numbers[]","description":"Пошук заявок на кур’єрський забір за номером документа. Може приймати як один номер для пошуку, так і масив номерів.\n\n🔹Для України приймає значення у форматі `102-0032853`. \nЯкщо одночасно передати номери pickup у форматах, що використовуються для України та Європи, API поверне помилку.\n","schema":{"type":"string"}},{"in":"query","name":"ids[]","description":"Список ідентифікаторів заявок на кур’єрський забір для пошуку. Може приймати як один ідентифікатор, так і масив ідентифікаторів.\n\n🔹Для України приймає значення у форматі UUID, наприклад `01a0b46a-dfea-7f9c-b1dc-7c7046afbaf7`. \nЯкщо одночасно передати ідентифікатори pickup у форматах, що використовуються для України та Європи, API поверне помилку.\n\n🔹Ідентифікатор `id` можна отримати з відповіді на метод [Створити заявку на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#post-pickups) або шляхом пошуку заявки на забір за номером документа.\n","schema":{"oneOf":[{"type":"integer","format":"int32"},{"type":"string","format":"uuid"}]}},{"in":"query","name":"countryCodes[]","description":"Параметр використовується для пошуку pickup в Україні.\n\n🔹Для отримання pickup з України необхідно передати `UA` у масиві `countryCodes[]`. Якщо параметр не передано, повертаються лише pickup з країн ЄС.\n","schema":{"type":"array","items":{"type":"string"}}},{"in":"query","name":"serviceCodes[]","description":"Фільтрація запитів на забір за кодом послуги.\n\nДоступні значення:\n- CourierPickupService\n\nПовертає лише ті запити на забір, які містять зазначену послугу.\n","schema":{"type":"string"}},{"in":"query","name":"limit","description":"Максимальна кількість елементів, що повертаються на сторінці.","schema":{"type":"integer","format":"int32","default":15}},{"in":"query","name":"page","description":"Номер сторінки для повернення.","schema":{"type":"integer","format":"int32"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","description":"Ідентифікатор заявки на кур’єрський забір.\n\n🔹Для **UA** використовується `number` у форматі UUID, наприклад `01a0b43d-5649-7a06-bdb1-c9394536dbea`. \n\n🔹Для **EU** використовується `integer`, наприклад `38556`.\n","items":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]}}},"required":["ids"]}}}},"responses":{"200":{"description":"Список заявок на кур’єрський забір успішно отримано","content":{"application/json":{"schema":{"type":"object","properties":{"current_page":{"type":"integer","description":"Поточна сторінка результатів у пагінованій відповіді.","minimum":1},"last_page":{"type":"integer","description":"Остання доступна сторінка в пагінованій відповіді.","minimum":1},"per_page":{"type":"integer","description":"Кількість елементів на сторінці.","minimum":1},"total":{"type":"integer","description":"Загальна кількість заявок на кур’єрський забір, що відповідають критеріям фільтрації.","minimum":0},"items":{"type":"array","description":"Список заявок на кур’єрський забір.","items":{"type":"object","properties":{"id":{"description":"Унікальний ідентифікатор заявки на кур’єрський забір. \n- Для pickup у країнах ЄС використовується числовий ідентифікатор. \n- Для pickup в Україні використовується UUID.\n\n🔹Для України значення повертається у форматі UUID, наприклад `01a0b46a-dfea-7f9c-b1dc-7c7046afbaf7`.\n","oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]},"number":{"type":"string","description":"Реєстраційний номер заявки на кур’єрський забір.\n\n🔹Для України номер pickup повертається у форматі `102-00328539`.\n"},"status":{"type":"string","description":"Поточний статус заявки на кур’єрський забір, що відображає етап її обробки.\n\nМожливі значення:\n - **Draft**: Початковий етап, коли заявку створено, але ще не завершено її оформлення.\n - **Created**: Заявку створено та підготовлено до обробки.\n - **AppointedCourier**: Для заявки призначено кур’єра.\n - **InProgress**: Кур’єрський забір виконується.\n - **Done**: Кур’єрський забір успішно завершено.\n - **ClientCanceled**: Заявку скасовано клієнтом.\n - **NotCompleted**: Кур’єрський забір не вдалося виконати.\n - **Deleted**: Заявку видалено із системи.\n - **ReceivedByCourier**: Відправлення отримано кур’єром.\n"},"statusDateTime":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення статусу.","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$"},"source":{"type":"string","description":"Джерело створення заявки (наприклад, API або вебінтерфейс)."},"executor":{"type":"string","description":"Ідентифікатор виконавця (кур’єра або служби)."},"companyTin":{"type":"string","description":"ІПН юридичної особи."},"companyName":{"type":"string","description":"Назва компанії, що створила заявку."},"fullName":{"type":"string","description":"Повне ім’я клієнта-відправника.","maxLength":100},"phone":{"type":"string","description":"Контактний номер телефону відправника.","minLength":8,"maxLength":14},"email":{"type":"string","description":"Контактна адреса електронної пошти, якщо вказана.","nullable":true},"countryCode":{"type":"string","description":"Код країни місця кур’єрського забору у форматі ISO Alpha-2.","pattern":"^[A-Z]{2}$"},"externalId":{"type":"string","description":"Зовнішній ідентифікатор заявки на кур’єрський забір, наданий клієнтом."},"createdByUser":{"type":"string","description":"Ідентифікатор користувача, який створив заявку."},"divisionId":{"type":"integer","description":"Ідентифікатор відділення, відповідального за обробку заявки."},"settlementId":{"type":"integer","description":"Ідентифікатор населеного пункту місця кур’єрського забору."},"cityDistrict":{"type":"string","description":"Район міста місця кур’єрського забору."},"deliveryPartner":{"type":"string","description":"Партнер доставки, який обробляє заявку."},"lockVersion":{"type":"integer","description":"Номер версії для запобігання конфліктам під час оновлення даних."},"address":{"type":"object","description":"Повна інформація про адресу.","properties":{"address":{"type":"string","description":"Повна адреса у відформатованому вигляді."},"latitude":{"type":"string","description":"Географічна широта місця кур’єрського забору."},"longitude":{"type":"string","description":"Географічна довгота місця кур’єрського забору."},"timeZoneId":{"type":"integer","description":"Внутрішній ідентифікатор часового поясу."},"timeZone":{"type":"string","description":"Часовий пояс місця кур’єрського забору, визначений за координатами."},"floor":{"type":"string","nullable":true,"description":"Номер поверху.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"}}},"addressParts":{"type":"object","description":"Деталізовані складові адреси.","properties":{"postCode":{"type":"string","description":"Поштовий індекс місця кур’єрського забору.","maxLength":10},"building":{"type":"string","description":"Номер будівлі місця кур’єрського забору.","maxLength":100},"street":{"type":"string","description":"Назва вулиці місця кур’єрського забору.","maxLength":100},"city":{"type":"string","description":"Назва міста місця кур’єрського забору.","maxLength":100},"region":{"type":"string","description":"Назва регіону місця кур’єрського забору.","maxLength":100},"flat":{"type":"string","description":"Номер квартири або офісу.","maxLength":10},"note":{"type":"string","description":"Додаткові примітки щодо адреси.","maxLength":100},"block":{"type":"string","description":"Корпус або секція будівлі.","maxLength":100,"nullable":true}}},"pickedTimeFrom":{"type":"string","format":"date-time","description":"Початок часового інтервалу кур’єрського забору, вказаного у заявці.","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$","nullable":true},"pickedTimeTo":{"type":"string","format":"date-time","description":"Кінець часового інтервалу кур’єрського забору, вказаного у заявці.","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$","nullable":true},"currencyCode":{"type":"string","description":"Код валюти країни, що використовується для платіжних операцій.","pattern":"^[A-Z]{3}$"},"isExpressDelivery":{"type":"boolean","description":"Ознака експрес-доставки. \n- `true` — заявка створена для експрес-доставки. \n- `false` — для стандартної.\n\n🔹Цей параметр повертається лише для кур’єрських доставок у межах України (UA).\n"},"cargoType":{"type":"string","description":"Тип вантажу, який необхідно забрати кур’єру. Наприклад, `parcel`.\n\n🔹Цей параметр повертається лише для кур’єрських доставок у межах України (UA).\n"},"weight":{"type":"number","description":"Загальна фактична вага вантажу, зазначеного в заявці.\n\n🔹Цей параметр повертається лише для кур’єрських доставок у межах України (UA).\n"},"volumetricWeight":{"type":"number","description":"Загальна об’ємна вага вантажу, зазначеного в заявці.\n\n🔹Цей параметр повертається лише для кур’єрських доставок у межах України (UA).\n"},"parcelsAmount":{"type":"integer","description":"Загальна кількість місць у заявці на кур’єрський забір.\n\n🔹Цей параметр повертається лише для кур’єрських доставок у межах України (UA).\n"},"description":{"type":"string","nullable":true,"description":"Опис вантажу або додаткова інформація щодо вантажу.\n\n🔹Цей параметр повертається лише для кур’єрських доставок у межах України (UA).\n"},"payerType":{"type":"string","nullable":true,"description":"Тип платника.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"paymentMethod":{"type":"string","description":"Спосіб оплати послуги кур’єрського забору. Наприклад, `Cash`.\n\n🔹Цей параметр повертається лише для кур’єрських доставок у межах України (UA).\n"},"shipments":{"type":"array","items":{"type":"object"},"description":"Список відправлень, пов’язаних із цією заявкою на кур’єрський забір."},"services":{"type":"array","description":"Список додаткових послуг, пов'язаних із запитом на забір.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Унікальний ідентифікатор послуги."},"shipmentParcelRowNumber":{"type":"string","description":"Номер рядка місця відправлення, пов'язаного з послугою.","nullable":true},"serviceId":{"type":"string","description":"Внутрішній ідентифікатор послуги."},"pickupId":{"type":"integer","description":"Ідентифікатор запиту на забір."},"serviceType":{"type":"string","description":"Внутрішній тип послуги."},"serviceName":{"type":"string","description":"Назва послуги.","nullable":true},"serviceCode":{"type":"string","description":"Код послуги."},"parcelNumber":{"type":"string","description":"Номер пов'язаного відправлення.","nullable":true},"payerType":{"type":"string","description":"Сторона, відповідальна за оплату."},"contractNumber":{"type":"string","description":"Номер договору, який використовується для оплати послуги."},"amount":{"type":"number","description":"Кількість послуги."},"price":{"type":"number","description":"Вартість послуги до застосування знижок."},"discount":{"type":"number","description":"Сума застосованої знижки."},"cost":{"type":"number","description":"Підсумкова вартість послуги."},"costBeforeCheck":{"type":"boolean","description":"Вказує, чи була вартість розрахована до виконання перевірки."},"paymentStatus":{"type":"string","description":"Поточний статус оплати."},"currencyCode":{"type":"string","description":"Код валюти відповідно до стандарту ISO 4217."},"executionAt":{"type":"string","format":"date-time","description":"Дата та час виконання послуги."},"additionalParameters":{"type":"object","description":"Планові параметри вантажу, передані для послуги CourierPickupService.","properties":{"parcel_description":{"type":"string","description":"Опис вантажу."},"parcels_amount":{"type":"number","description":"Планова кількість місць."},"total_actual_weight":{"type":"number","description":"Загальна планова фактична вага."},"total_volumetric_weight":{"type":"number","description":"Загальна планова об'ємна вага."},"length":{"type":"number","description":"Планова довжина вантажу."},"width":{"type":"number","description":"Планова ширина вантажу."},"height":{"type":"number","description":"Планова висота вантажу."}}}}}},"statuses":{"type":"array","description":"Масив об’єктів статусів, що відстежують зміни статусу заявки на кур’єрський забір.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Унікальний ідентифікатор статусу.","minimum":1},"pickupId":{"type":"integer","description":"Ідентифікатор заявки на кур’єрський забір.","minimum":1},"status":{"type":"string","description":"Поточний статус заявки на кур’єрський забір, що відображає етап її обробки.\n\nМожливі значення: `Draft`, `Created`, `AppointedCourier`, `InProgress`, `Done`, `ClientCanceled`, `NotCompleted`, `Deleted`, `ReceivedByCourier`.\n"},"dateTime":{"type":"string","format":"date-time","description":"Дата та час оновлення статусу.","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$"},"note":{"type":"string","description":"Необов’язкові примітки, пов’язані зі статусом.","maxLength":255,"nullable":true},"user":{"type":"string","description":"Ідентифікатор користувача, який змінив статус.","maxLength":50},"createdAt":{"type":"string","format":"date-time","description":"Дата та час створення запису статусу.","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$"},"updatedAt":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення запису статусу.","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$"},"deletedAt":{"type":"string","format":"date-time","description":"Дата та час видалення запису статусу, якщо застосовується.","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$","nullable":true}}}},"createdAt":{"type":"string","format":"date-time","description":"Дата та час створення заявки на кур’єрський забір."},"updatedAt":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення заявки на кур’єрський забір."},"deletedAt":{"type":"string","format":"date-time","description":"Дата та час видалення заявки на кур’єрський забір, якщо застосовується.","nullable":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Отримати список заявок на кур’єрський забір"}}}} ``` ## Отримати доступні часові інтервали для кур’єрського забору > Цей метод повертає доступні часові інтервали для заборів.\ > Метод також дозволяє отримати доступні часові інтервали для конкретного пікапу, передавши \`pickupId\`.\ > \ > Алгоритм працює на основі географічних зон, які обслуговують кур'єри.\ > Ці зони є умовними областями на карті, що визначаються логістичними особливостями кур'єрських операцій.\ > Залежно від місця забору, система визначає конкретного кур'єра, відповідального за цю зону, і повертає детальні часові інтервали, доступні для виклику.\ > \ > \*\*Обов'язкові параметри:\*\*\ > \- \`countryCode\`: Вказує код країни відповідно до стандарту ISO 3166-1 Alpha-2.\ > \- \`type\`: Визначає тип забору. Допустимі значення: \`PickupDayToDay\` (забір день у день) або \`PickupNextDay\` (забір на наступний день).\ > \ > 🔹Якщо передано \`pickupId\`, параметри \`countryCode\` та \`type\` є необов'язковими та їх можна не передавати. Якщо \`pickupId\` не передано, параметри \`countryCode\` та \`type\` є обов'язковими.\ > \ > Якщо надано лише \`countryCode\` та \`type\`, метод поверне загальний робочий час кур'єрів для вказаної країни без детальних інтервалів для конкретної локації чи зони.\ > \ > \*\*Часові інтервали для конкретного пікапу:\*\*\ > \- \`pickupId\`: Вкажіть ідентифікатор існуючої заявки на кур’єрський забір, щоб отримати доступні часові інтервали для конкретного пікапу.\ > \- Якщо передано \`pickupId\`, у відповіді можуть повертатися \`pickupId\`, \`actionType\` та \`availableDays\` з доступними днями та часовими слотами для перенесення пікапу.\ > \ > \*\*Рекомендовані параметри для точних результатів:\*\*\ > \- \`addressParts\`: Надайте повну адресу забору, включаючи будівлю, вулицю, місто, регіон та поштовий індекс. Це гарантує повернення точних часових інтервалів для вказаної адреси.\ > \- \`latitude\` та \`longitude\`: Використовуйте географічні координати для визначення зони, якщо повна адреса недоступна.\ > \- \`divisionId\`: Вкажіть ID найближчого відділення, якщо точна адреса невідома. Проте зауважте, що близькість до відділення не гарантує, що кур'єр, який обслуговує цю адресу, працює саме з цього відділення.\ > \ > \*\*Додаткові параметри:\*\*\ > \- \`weight\`: Часові інтервали можуть залежати від ваги відправлення. Цей параметр є корисним для великих або чутливих до ваги вантажів.\ > \ > \*\*Важливі примітки:\*\*\ > 1\. Якщо вказано лише \`countryCode\` та \`type\`, система поверне загальний робочий час кур'єрів без детальних часових інтервалів для конкретної адреси.\ > 2\. Якщо передано \`pickupId\`, параметри \`countryCode\` та \`type\` є необов'язковими.\ > 3\. Для отримання найбільш точних часових інтервалів під час пошуку за місцем забору наполегливо рекомендується надавати повну адресу або координати.\ > \ > \*\*Логіка вибору часових інтервалів:\*\*\ > \ > \- Якщо існує конфігурація \`PickupDayToDay\`:\ > \- Вона має пріоритет над \`PickupNextDay\`.\ > \- Поточний день (сьогодні) доступний, якщо:\ > \- День не є святковим (\`holiday == false\`);\ > \- Існує робочий графік (\`from != null\`);\ > \- Поточний час < \`orderTo\`.\ > \- Може бути повернуто до 7 календарних днів (включаючи сьогодні), якщо:\ > \- Дні не є святковими;\ > \- Параметр \`from\` задано;\ > \- Перевірка \`orderTo\` застосовується лише для сьогоднішнього дня.\ > \- Якщо конфігурація \`PickupDayToDay\` відсутня, але налаштовано \`PickupNextDay\`:\ > \- Поточний день (сьогодні) недоступний.\ > \- Може бути повернуто до 7 календарних днів (виключаючи сьогодні), якщо:\ > \- Дні не є святковими;\ > \- Параметр \`from\` задано.\ > \- Обмеження \`orderTo\` застосовується \*\*наступного дня\*\*. Якщо поточний час > \`orderTo\`, завтрашній день виключається.\ > \- Якщо конфігурація часових інтервалів відсутня (резервний режим / fallback):\ > \- Поточний день (сьогодні) недоступний.\ > \- Може бути повернуто до 7 календарних днів (виключаючи сьогодні, вихідні та святкові дні).\ > \- Фіксоване значення \`orderTo = 17:00\` застосовується лише для завтрашнього дня.\ > \ > \*\*Примітка:\*\*\ > \ > Якщо параметр \`from\` задано, але масив \`timeIntervals\` порожній, кур'єр прибуде \*\*протягом дня\*\* без прив'язки до фіксованого слоту.\ > Ця логіка застосовується \*\*до всіх типів\*\* конфігурацій.\ > \ > \*\*Поведінка валідації:\*\*\ > \- Якщо обраний день більше не є дійсним, система автоматично призначає наступний доступний дійсний день.\ > \- Якщо часовий інтервал недійсний або порожній, кур'єр прибуде протягом усього робочого періоду.\ > \ > \*\*Рекомендація:\*\*\ > Для забезпечення точних результатів часових інтервалів під час пошуку за місцем забору наполегливо рекомендується надавати повні дані адреси або координати.\ > \ > \*\*🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.\*\*
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Pickups"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT-токен авторизації зі строком дії 1 годину у заголовку"}},"responses":{"Unauthorized":{"description":"Неавторизований доступ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Вказаний ресурс не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Помилка валідації","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/time-intervals/find":{"post":{"tags":["Pickups"],"description":"Цей метод повертає доступні часові інтервали для заборів.\nМетод також дозволяє отримати доступні часові інтервали для конкретного пікапу, передавши `pickupId`.\n\nАлгоритм працює на основі географічних зон, які обслуговують кур'єри.\nЦі зони є умовними областями на карті, що визначаються логістичними особливостями кур'єрських операцій.\nЗалежно від місця забору, система визначає конкретного кур'єра, відповідального за цю зону, і повертає детальні часові інтервали, доступні для виклику.\n\n**Обов'язкові параметри:**\n- `countryCode`: Вказує код країни відповідно до стандарту ISO 3166-1 Alpha-2.\n- `type`: Визначає тип забору. Допустимі значення: `PickupDayToDay` (забір день у день) або `PickupNextDay` (забір на наступний день).\n\n🔹Якщо передано `pickupId`, параметри `countryCode` та `type` є необов'язковими та їх можна не передавати. Якщо `pickupId` не передано, параметри `countryCode` та `type` є обов'язковими.\n\nЯкщо надано лише `countryCode` та `type`, метод поверне загальний робочий час кур'єрів для вказаної країни без детальних інтервалів для конкретної локації чи зони.\n\n**Часові інтервали для конкретного пікапу:**\n- `pickupId`: Вкажіть ідентифікатор існуючої заявки на кур’єрський забір, щоб отримати доступні часові інтервали для конкретного пікапу.\n- Якщо передано `pickupId`, у відповіді можуть повертатися `pickupId`, `actionType` та `availableDays` з доступними днями та часовими слотами для перенесення пікапу.\n\n**Рекомендовані параметри для точних результатів:**\n- `addressParts`: Надайте повну адресу забору, включаючи будівлю, вулицю, місто, регіон та поштовий індекс. Це гарантує повернення точних часових інтервалів для вказаної адреси.\n- `latitude` та `longitude`: Використовуйте географічні координати для визначення зони, якщо повна адреса недоступна.\n- `divisionId`: Вкажіть ID найближчого відділення, якщо точна адреса невідома. Проте зауважте, що близькість до відділення не гарантує, що кур'єр, який обслуговує цю адресу, працює саме з цього відділення.\n\n**Додаткові параметри:**\n- `weight`: Часові інтервали можуть залежати від ваги відправлення. Цей параметр є корисним для великих або чутливих до ваги вантажів.\n\n**Важливі примітки:**\n1. Якщо вказано лише `countryCode` та `type`, система поверне загальний робочий час кур'єрів без детальних часових інтервалів для конкретної адреси.\n2. Якщо передано `pickupId`, параметри `countryCode` та `type` є необов'язковими.\n3. Для отримання найбільш точних часових інтервалів під час пошуку за місцем забору наполегливо рекомендується надавати повну адресу або координати.\n\n**Логіка вибору часових інтервалів:**\n\n- Якщо існує конфігурація `PickupDayToDay`:\n - Вона має пріоритет над `PickupNextDay`.\n - Поточний день (сьогодні) доступний, якщо:\n - День не є святковим (`holiday == false`);\n - Існує робочий графік (`from != null`);\n - Поточний час < `orderTo`.\n - Може бути повернуто до 7 календарних днів (включаючи сьогодні), якщо:\n - Дні не є святковими;\n - Параметр `from` задано;\n - Перевірка `orderTo` застосовується лише для сьогоднішнього дня.\n- Якщо конфігурація `PickupDayToDay` відсутня, але налаштовано `PickupNextDay`:\n - Поточний день (сьогодні) недоступний.\n - Може бути повернуто до 7 календарних днів (виключаючи сьогодні), якщо:\n - Дні не є святковими;\n - Параметр `from` задано.\n - Обмеження `orderTo` застосовується **наступного дня**. Якщо поточний час > `orderTo`, завтрашній день виключається.\n- Якщо конфігурація часових інтервалів відсутня (резервний режим / fallback):\n - Поточний день (сьогодні) недоступний.\n - Може бути повернуто до 7 календарних днів (виключаючи сьогодні, вихідні та святкові дні).\n - Фіксоване значення `orderTo = 17:00` застосовується лише для завтрашнього дня.\n\n**Примітка:**\n\nЯкщо параметр `from` задано, але масив `timeIntervals` порожній, кур'єр прибуде **протягом дня** без прив'язки до фіксованого слоту.\nЦя логіка застосовується **до всіх типів** конфігурацій.\n\n**Поведінка валідації:**\n- Якщо обраний день більше не є дійсним, система автоматично призначає наступний доступний дійсний день.\n- Якщо часовий інтервал недійсний або порожній, кур'єр прибуде протягом усього робочого періоду.\n\n**Рекомендація:**\nДля забезпечення точних результатів часових інтервалів під час пошуку за місцем забору наполегливо рекомендується надавати повні дані адреси або координати.\n\n**🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pickupId":{"type":"integer","description":"Ідентифікатор заявки на кур’єрський забір, для якої необхідно отримати доступні часові інтервали.\n\nЯкщо передано `pickupId`, параметри `countryCode` та `type` є необов'язковими та їх можна не передавати.\n","minimum":1},"type":{"type":"string","description":"Тип часового інтервалу. Для країн ЄС доступні значення: `PickupDayToDay` або `PickupNextDay`.\n\n🔹Для викликів в Україні підтримується значення `Delivery`.\n","enum":["PickupDayToDay","PickupNextDay","Delivery"]},"countryCode":{"type":"string","description":"Код країни відповідно до стандарту ISO 3166-1 Alpha-2.\n\n🔹Для викликів в Україні значення параметра має бути `UA`.\n","pattern":"^[A-Z]{2}$"},"settlementId":{"type":"integer","description":"Ідентифікатор населеного пункту, до якого здійснюється доставка.\n\n🔹Цей параметр є обов'язковим лише для викликів в Україні.\n","minimum":1},"date":{"type":"string","description":"Дата кур'єрського забору у форматі `DD.MM.YYYY`.\n\n🔹Цей параметр використовується лише для викликів в Україні.\n","pattern":"^(0[1-9]|[12][0-9]|3[01])\\.(0[1-9]|1[0-2])\\.[0-9]{4}$"},"divisionId":{"type":"integer","description":"Ідентифікатор відділення для визначення конкретного відділення.","minimum":1,"nullable":true},"latitude":{"type":"number","description":"Широта для пошуку за географічними координатами.","minimum":-90,"maximum":90,"nullable":true},"longitude":{"type":"number","description":"Довгота для пошуку за географічними координатами.","minimum":-180,"maximum":180,"nullable":true},"maxWeightPlaceRecipient":{"type":"integer","description":"Вага відправлення в кілограмах. Необов’язковий параметр для інтервалів, які не залежать від ваги.","minimum":0,"nullable":true},"addressParts":{"type":"object","description":"Повна адреса для пошуку часових інтервалів. Якщо не передано, використовуються координати.","nullable":true,"properties":{"building":{"type":"string","description":"Номер або ідентифікатор будівлі.","maxLength":100},"street":{"type":"string","description":"Назва вулиці.","maxLength":100},"city":{"type":"string","description":"Назва міста.","maxLength":100},"region":{"type":"string","description":"Область або адміністративний регіон.","maxLength":100},"postCode":{"type":"string","description":"Поштовий індекс.","maxLength":10},"flat":{"type":"string","description":"Номер квартири або офісу, за наявності.","maxLength":10,"nullable":true},"note":{"type":"string","description":"Додаткова інформація для ідентифікації місця забору.","maxLength":100,"nullable":true}}}}}}}},"responses":{"200":{"description":"Часові інтервали успішно отримано","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Унікальний ідентифікатор часового інтервалу.","minimum":1},"countryCode":{"type":"string","description":"Код країни відповідно до стандарту ISO 3166-1 Alpha-2.","pattern":"^[A-Z]{2}$"},"divisionId":{"type":"integer","description":"Ідентифікатор відділення, пов’язаного з часовим інтервалом.","minimum":1,"nullable":true},"type":{"type":"string","description":"Тип часового інтервалу.","enum":["PickupDayToDay","PickupNextDay"]},"deliveryPartner":{"type":"string","description":"Партнер, відповідальний за кур’єрський забір, якщо застосовується.","nullable":true},"ignoreNonWorkingDays":{"type":"boolean","description":"Визначає, чи враховуються неробочі дні під час пошуку."},"monday":{"type":"object","description":"Часові інтервали, доступні в понеділок.","properties":{"from":{"type":"string","description":"Час початку інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей інтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"timeIntervals":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер інтервалу забору.","nullable":true},"from":{"type":"string","description":"Час початку підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей підінтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true}}}}}},"tuesday":{"type":"object","description":"Часові інтервали, доступні у вівторок.","properties":{"from":{"type":"string","description":"Час початку інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей інтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"timeIntervals":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер інтервалу забору.","nullable":true},"from":{"type":"string","description":"Час початку підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей підінтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true}}}}}},"wednesday":{"type":"object","description":"Часові інтервали, доступні в середу.","properties":{"from":{"type":"string","description":"Час початку інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей інтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"timeIntervals":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер інтервалу забору.","nullable":true},"from":{"type":"string","description":"Час початку підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей підінтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true}}}}}},"thursday":{"type":"object","description":"Часові інтервали, доступні в четвер.","properties":{"from":{"type":"string","description":"Час початку інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей інтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"timeIntervals":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер інтервалу забору.","nullable":true},"from":{"type":"string","description":"Час початку підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей підінтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true}}}}}},"friday":{"type":"object","description":"Часові інтервали, доступні в п’ятницю.","properties":{"from":{"type":"string","description":"Час початку інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей інтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"timeIntervals":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер інтервалу забору.","nullable":true},"from":{"type":"string","description":"Час початку підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей підінтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true}}}}}},"saturday":{"type":"object","description":"Часові інтервали, доступні в суботу.","properties":{"from":{"type":"string","description":"Час початку інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей інтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"timeIntervals":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер інтервалу забору.","nullable":true},"from":{"type":"string","description":"Час початку підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей підінтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true}}}}}},"sunday":{"type":"object","description":"Часові інтервали, доступні в неділю.","properties":{"from":{"type":"string","description":"Час початку інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення інтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей інтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"timeIntervals":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер інтервалу забору.","nullable":true},"from":{"type":"string","description":"Час початку підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"to":{"type":"string","description":"Час завершення підінтервалу.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true},"orderTo":{"type":"string","description":"Час, до якого можна оформити заявку на цей підінтервал.","pattern":"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$","nullable":true}}}}}},"createdAt":{"type":"string","format":"date-time","description":"Дата та час первинного створення запису.","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$"},"updatedAt":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення запису.","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$"},"deletedAt":{"type":"string","format":"date-time","description":"Дата та час видалення запису.","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$","nullable":true},"pickupId":{"type":"integer","description":"Ідентифікатор пікапу. Повертається, якщо `pickupId` було передано в запиті.","nullable":true},"actionType":{"type":"string","description":"Тип дії для пікапу.","nullable":true},"availableDays":{"type":"array","description":"Масив доступних днів із часовими інтервалами для перенесення пікапу.","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Доступна дата у форматі `YYYY-MM-DD`."},"weekday":{"type":"string","description":"День тижня. Наприклад: `Friday`.\n"},"idTimeInterval":{"type":"integer","description":"Ідентифікатор часового інтервалу."},"typeTimeInterval":{"type":"string","description":"Тип часового інтервалу. Наприклад: `PickupDayToDay`.\n"},"timeIntervals":{"type":"array","description":"Масив доступних часових слотів для вказаного дня.","items":{"type":"object","properties":{"from":{"type":"string","format":"time","description":"Початок часового інтервалу. Наприклад: `09:00`.\n"},"to":{"type":"string","format":"time","description":"Кінець часового інтервалу. Наприклад: `12:00`.\n"},"orderTo":{"type":"string","format":"time","description":"Граничний час замовлення. Наприклад: `08:00`.\n"},"allDay":{"type":"boolean","description":"Визначає, чи є часовий інтервал доступним протягом усього дня."}}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Отримати доступні часові інтервали для кур’єрського забору"}}}} ``` ## Створити заявку на кур’єрський забір > Цей метод дозволяє бізнес-клієнтам створити нову заявку на кур’єрський забір, вказавши основні параметри, такі як адреса забору, тип відправлення та додаткові відомості.\ > \ > \*\*Початковий статус\*\* (\`Draft\`): Заявка на кур’єрський забір створюється зі статусом \`Draft\`, що дозволяє клієнтам додати до заявки всі необхідні відправлення.\ > \ > \*\*Перехід до статусу\*\* \`Created\`: Після додавання всіх відправлень клієнт повинен скористатися методом \[\*\*Оновити статус заявки на кур’єрський забір\*\*]\(), щоб змінити статус на \`Created\`. Це означає, що заявку завершено та вона готова до обробки кур’єрською службою.\ > \ > \*\*🔹Заявки на кур’єрський забір в Україні одразу створюються у статусі \`ReadyToDone\`. Це означає, що заявку завершено та передано на подальшу обробку кур’єрською службою.\*\*\ > \ > \*\*Часові інтервали\*\*: Щоб вказати бажаний часовий інтервал для забору, клієнт повинен отримати доступні часові інтервали за допомогою відповідного методу. Це гарантує, що бажаний час кур’єрського забору відповідає графіку та доступності кур’єра.\ > \ > \*\*Додаткова послуга – CourierPickupService\*\*: Клієнти можуть додатково передавати інформацію про плановий вантаж у масиві \`services\` за допомогою послуги \`CourierPickupService\`. Це дозволяє вказати орієнтовні характеристики відправлення, такі як опис вантажу, кількість місць, фактична та об'ємна вага, а також додаткові габарити. Наразі послуга доступна в Молдові. Ця інформація використовується під час планування забору та обробки кур'єрського запиту.\ > \ > \*\*🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри запиту для Європи та України відрізняються.\*\*
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Pickups"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT-токен авторизації зі строком дії 1 годину у заголовку"}},"responses":{"Unauthorized":{"description":"Неавторизований доступ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Вказаний ресурс не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Помилка валідації","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups":{"post":{"tags":["Pickups"],"description":"Цей метод дозволяє бізнес-клієнтам створити нову заявку на кур’єрський забір, вказавши основні параметри, такі як адреса забору, тип відправлення та додаткові відомості.\n\n**Початковий статус** (`Draft`): Заявка на кур’єрський забір створюється зі статусом `Draft`, що дозволяє клієнтам додати до заявки всі необхідні відправлення.\n\n**Перехід до статусу** `Created`: Після додавання всіх відправлень клієнт повинен скористатися методом [**Оновити статус заявки на кур’єрський забір**](https://api-portal.novapost.com/methods/ua/overview/pickups#put-pickups-id-status), щоб змінити статус на `Created`. Це означає, що заявку завершено та вона готова до обробки кур’єрською службою.\n\n**🔹Заявки на кур’єрський забір в Україні одразу створюються у статусі `ReadyToDone`. Це означає, що заявку завершено та передано на подальшу обробку кур’єрською службою.**\n\n**Часові інтервали**: Щоб вказати бажаний часовий інтервал для забору, клієнт повинен отримати доступні часові інтервали за допомогою відповідного методу. Це гарантує, що бажаний час кур’єрського забору відповідає графіку та доступності кур’єра.\n\n**Додаткова послуга – CourierPickupService**: Клієнти можуть додатково передавати інформацію про плановий вантаж у масиві `services` за допомогою послуги `CourierPickupService`. Це дозволяє вказати орієнтовні характеристики відправлення, такі як опис вантажу, кількість місць, фактична та об'ємна вага, а також додаткові габарити. Наразі послуга доступна в Молдові. Ця інформація використовується під час планування забору та обробки кур'єрського запиту.\n\n**🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри запиту для Європи та України відрізняються.**\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Необов’язкові примітки або інструкції для кур’єра.","maxLength":255},"services":{"type":"array","nullable":true,"description":"Список додаткових послуг, пов'язаних із запитом на забір.\n\nНаразі підтримується наступна послуга:\n- `CourierPickupService` — дозволяє клієнту передати інформацію про плановий вантаж, яка буде використана під час планування забору та обробки кур'єрського запиту.\n"},"phone":{"type":"string","description":"Контактний номер телефону відправника, необхідний для того, щоб кур’єр міг зв’язатися у разі потреби.","minLength":8,"maxLength":14},"email":{"type":"string","description":"Хоча поле не є обов’язковим, рекомендується вказати електронну адресу як резервний спосіб зв’язку на випадок некоректного номера телефону або для отримання додаткових сповіщень щодо кур’єрського забору.","nullable":true},"fullName":{"type":"string","description":"Повне ім’я клієнта, який відправляє посилку. Необхідне для ідентифікації відправника та коректної обробки заявки на кур’єрський забір.","maxLength":100},"companyTin":{"type":"string","description":"Податковий ідентифікаційний номер (ІПН) юридичної особи.","minLength":2,"maxLength":20},"companyName":{"type":"string","description":"Назва компанії, яка оформлює заявку на кур’єрський забір.","minLength":2,"maxLength":255},"countryCode":{"type":"string","description":"Код країни місця кур’єрського забору відповідно до стандарту ISO Alpha-2.\n\n🔹Залежно від вибору країни ЄС або України (`UA`) використовуються різні обов’язкові параметри.\n","pattern":"^[A-Z]{2}$"},"addressParts":{"type":"object","description":"Детальна інформація про адресу місця кур’єрського забору.\n\n🔹Це поле є обов’язковим лише для кур’єрських заборів у Європі та не використовується для кур’єрських заборів в Україні.\n","properties":{"city":{"type":"string","description":"Назва міста місця кур’єрського забору.","maxLength":100},"region":{"type":"string","description":"Адміністративна область, штат або регіон місця кур’єрського забору.","maxLength":100},"street":{"type":"string","description":"Назва вулиці місця кур’єрського забору.","maxLength":100},"postCode":{"type":"string","description":"Поштовий індекс місця кур’єрського забору.","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі за адресою кур’єрського забору.","maxLength":100},"flat":{"type":"string","description":"Номер квартири або офісу в будівлі.","maxLength":10},"block":{"type":"string","description":"Корпус або секція будівлі, якщо застосовується.","maxLength":100},"note":{"type":"string","description":"Додаткові інструкції для кур’єра щодо доступу до місця кур’єрського забору.","maxLength":100}}},"settlementId":{"type":"integer","description":"Ідентифікатор населеного пункту, до якого здійснюється доставка.\n\n🔹Це поле є обов’язковим лише для кур’єрських заборів в Україні.\n"},"address":{"type":"object","description":"Об’єкт з адресними даними місця доставки.\n\n🔹Це поле є обов’язковим лише для кур’єрських заборів в Україні.\n","properties":{"postCode":{"type":"string","nullable":true,"description":"Поштовий індекс адреси доставки.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"region":{"type":"string","nullable":true,"description":"Область або регіон адреси доставки.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"city":{"type":"string","description":"Назва населеного пункту адреси доставки.\n\n🔹Це поле є обов’язковим лише для кур’єрських заборів в Україні.\n"},"street":{"type":"string","description":"Назва вулиці адреси доставки.\n\n🔹Це поле є обов’язковим лише для кур’єрських заборів в Україні.\n"},"building":{"type":"string","description":"Номер будинку адреси доставки.\n\n🔹Це поле є обов’язковим лише для кур’єрських заборів в Україні.\n"},"address":{"type":"string","nullable":true,"description":"Повна адреса доставки у текстовому форматі.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"block":{"type":"string","nullable":true,"description":"Номер або позначення корпусу будинку.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"flat":{"type":"string","nullable":true,"description":"Номер квартири.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"floor":{"type":"string","nullable":true,"description":"Номер поверху.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"note":{"type":"string","nullable":true,"description":"Додаткова інформація або коментар щодо адреси доставки.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"latitude":{"type":"number","nullable":true,"minimum":-90,"maximum":90,"description":"Географічна широта адреси доставки. Допустиме значення: від -90 до 90.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"longitude":{"type":"number","nullable":true,"minimum":-180,"maximum":180,"description":"Географічна довгота адреси доставки. Допустиме значення: від -180 до 180.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"}}},"isExpressDelivery":{"type":"boolean","description":"Ознака необхідності експрес-доставки. \n- `true` — експрес-доставка. \n- `false` — стандартна доставка.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"cargoType":{"type":"string","description":"Тип вантажу у відправленні.\n\n🔹Це поле є обов’язковим лише для кур’єрських заборів в Україні.\n"},"additionalParameters":{"type":"object","description":"Об’єкт з додатковими параметрами вантажу та відправлення.\n\n🔹Це поле є обов’язковим лише для кур’єрських заборів в Україні.\n","properties":{"totalActualWeight":{"type":"integer","description":"Загальна фактична вага відправлення.\n\n🔹Це поле є обов’язковим лише для кур’єрських заборів в Україні.\n"},"totalVolumetricWeight":{"type":"integer","nullable":true,"description":"Загальна об’ємна вага відправлення.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"parcelsAmount":{"type":"integer","nullable":true,"description":"Загальна кількість місць (посилок) у відправленні.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"parcelDescription":{"type":"string","nullable":true,"description":"Опис вмісту відправлення.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"length":{"type":"number","nullable":true,"description":"Довжина відправлення або вантажного місця.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"width":{"type":"number","nullable":true,"description":"Ширина відправлення або вантажного місця.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"},"height":{"type":"number","nullable":true,"description":"Висота відправлення або вантажного місця.\n\n🔹Це поле використовується лише для кур’єрських заборів в Україні.\n"}},"required":["totalActualWeight"]},"pickedTimeFrom":{"type":"string","format":"date-time","description":"Початок часового інтервалу кур’єрського забору, вибраного з доступних часових інтервалів, отриманих за допомогою методу повернення доступних часових слотів. Якщо часовий інтервал не вказано, кур’єр призначить час кур’єрського забору на власний розсуд.","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$","nullable":true},"pickedTimeTo":{"type":"string","format":"date-time","description":"Кінець часового інтервалу кур’єрського забору, вибраного з доступних часових інтервалів, отриманих за допомогою методу повернення доступних часових слотів. Якщо часовий інтервал не вказано, кур’єр призначить час кур’єрського забору на власний розсуд.","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$","nullable":true}},"required":["fullName","phone","countryCode"]}}}},"responses":{"201":{"description":"Заявку на кур’єрський забір успішно створено","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"description":"Ідентифікатор pickup. \n- Для України використовується `string` у форматі UUID, наприклад `01a0b43d-5649-7a06-bdb1-c9394536dbea`. \n- Для країн ЄС використовується `integer`, наприклад `296132`.\n","oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]},"number":{"type":"string","description":"Номер pickup. \n- Для України використовується формат `102-00328530`. \n- Для країн ЄС використовується формат `PUPL7092967496`.\n","pattern":"^[A-Z]{4}\\d{10}$"},"versionTracking":{"type":"integer","description":"Версія відстеження заявки на кур’єрський забір.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"status":{"type":"string","description":"Поточний статус заявки на кур’єрський забір, що відображає етап її обробки.\n\nМожливі значення:\n - **Draft** — початковий статус, у якому заявку створено, але ще не завершено її оформлення.\n - **Created** — заявку створено та підготовлено до обробки.\n - **AppointedCourier** — для заявки призначено кур’єра.\n - **InProgress** — кур’єрський забір виконується.\n - **Done** — кур’єрський забір успішно завершено.\n - **ClientCanceled** — заявку скасовано клієнтом.\n - **NotCompleted** — кур’єрський забір не вдалося виконати.\n - **Deleted** — заявку видалено із системи.\n - **ReceivedByCourier** — відправлення отримано кур’єром.\n - **ReadyToDone** — заявку завершено та передано на подальшу обробку кур’єрською службою. Значення використовується лише для кур’єрських заборів в Україні.\n"},"statusDateTime":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення статусу.","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$"},"source":{"type":"string","description":"Джерело створення заявки, зазвичай **clientapi**.","maxLength":50},"executor":{"type":"string","description":"Виконавець, призначений для виконання кур’єрського забору, якщо такий є.","maxLength":50,"nullable":true},"companyTin":{"type":"string","description":"ІПН юридичної особи.","minLength":2,"maxLength":20},"companyName":{"type":"string","description":"Назва компанії.","minLength":2,"maxLength":255},"fullName":{"type":"string","description":"Повне ім’я заявника.","maxLength":100},"phone":{"type":"string","description":"Контактний номер телефону.","minLength":8,"maxLength":14},"email":{"type":"string","description":"Контактна електронна адреса, якщо вказана.","nullable":true},"countryCode":{"type":"string","description":"Код країни місця кур’єрського забору.","pattern":"^[A-Z]{2}$"},"createdByUser":{"type":"string","description":"Ідентифікатор користувача, який створив заявку.","maxLength":50},"deliveryPartner":{"type":"string","description":"Партнер, відповідальний за доставку, якщо такий є.","nullable":true},"lockVersion":{"type":"integer","description":"Номер версії для контролю одночасних змін.","minimum":1},"divisionId":{"type":"integer","description":"Ідентифікатор відділення, пов’язаного із заявкою на кур’єрський забір, якщо застосовується.","minimum":1,"nullable":true},"settlementId":{"type":"integer","description":"Ідентифікатор населеного пункту місця кур’єрського забору.","minimum":1},"settlementName":{"type":"string","nullable":true,"description":"Назва населеного пункту.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"cityDistrict":{"type":"string","description":"Район міста місця кур’єрського забору, якщо застосовується.","maxLength":50,"nullable":true},"address":{"type":"object","description":"Відформатована адреса та географічні координати місця кур’єрського забору.","nullable":true,"properties":{"string":{"type":"string","description":"Повна адреса у відформатованому вигляді.","maxLength":255},"postCode":{"type":"string","nullable":true,"description":"Поштовий індекс адреси забору."},"region":{"type":"string","nullable":true,"description":"Область або регіон адреси забору."},"city":{"type":"string","nullable":true,"description":"Назва населеного пункту адреси забору."},"street":{"type":"string","nullable":true,"description":"Назва вулиці адреси забору."},"building":{"type":"string","nullable":true,"description":"Номер будинку адреси забору."},"block":{"type":"string","nullable":true,"description":"Номер або позначення корпусу будинку."},"flat":{"type":"string","nullable":true,"description":"Номер квартири."},"floor":{"type":"string","nullable":true,"description":"Номер поверху адреси забору.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"note":{"type":"string","nullable":true,"description":"Додаткова інформація щодо адреси забору."},"address":{"type":"string","nullable":true,"description":"Повна адреса забору у текстовому форматі.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"addressId":{"type":"string","nullable":true,"description":"Ідентифікатор адреси.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"latitude":{"type":"number","format":"float","description":"Географічна широта місця кур’єрського забору.","minimum":-90,"maximum":90},"longitude":{"type":"number","format":"float","description":"Географічна довгота місця кур’єрського забору.","minimum":-180,"maximum":180},"timeZoneId":{"type":"string","nullable":true,"description":"Ідентифікатор часового поясу адреси.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"timeZone":{"type":"string","nullable":true,"description":"Часовий пояс адреси.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"}}},"addressParts":{"type":"object","description":"Деталізовані складові адреси, вказані у запиті.","nullable":true,"properties":{"postCode":{"type":"string","description":"Поштовий індекс місця кур’єрського забору.","maxLength":10},"building":{"type":"string","description":"Номер будівлі місця кур’єрського забору.","maxLength":100},"street":{"type":"string","description":"Назва вулиці місця кур’єрського забору.","maxLength":100},"city":{"type":"string","description":"Назва міста місця кур’єрського забору.","maxLength":100},"region":{"type":"string","description":"Назва регіону місця кур’єрського забору.","maxLength":100},"flat":{"type":"string","description":"Номер квартири або офісу.","maxLength":10},"note":{"type":"string","description":"Додаткові примітки щодо адреси.","maxLength":100},"block":{"type":"string","description":"Корпус або секція будівлі.","maxLength":100,"nullable":true}}},"pickedTimeFrom":{"type":"string","format":"date-time","description":"Початок часового інтервалу кур’єрського забору, вказаного у запиті.","nullable":true},"pickedTimeTo":{"type":"string","format":"date-time","description":"Кінець часового інтервалу кур’єрського забору, вказаного у запиті.","nullable":true},"note":{"type":"string","description":"Примітка або інструкції для кур’єра.","maxLength":255,"nullable":true},"currencyCode":{"type":"string","description":"Код валюти країни, що використовується для платіжних операцій.","pattern":"^[A-Z]{3}$"},"cargoType":{"type":"string","description":"Тип вантажу.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"weight":{"type":"integer","description":"Загальна фактична вага вантажу.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"volumetricWeight":{"type":"integer","description":"Загальна об’ємна вага вантажу.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"parcelsAmount":{"type":"integer","description":"Кількість вантажних місць у заборі.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"description":{"type":"string","nullable":true,"description":"Опис вантажу.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"payerType":{"type":"string","nullable":true,"description":"Тип платника за послуги.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"paymentMethod":{"type":"string","description":"Спосіб оплати.\n\n🔹Цей параметр повертається лише для кур’єрських заборів в Україні.\n"},"externalId":{"type":"string","description":"Внутрішні дані. Не призначено для використання.","nullable":true},"shipments":{"type":"array","items":{"type":"object"},"description":"Список відправлень, пов’язаних із цією заявкою на кур’єрський забір."},"services":{"type":"array","description":"Список додаткових послуг, пов'язаних із запитом на забір.","items":{"type":"object","properties":{"serviceCode":{"type":"string","description":"Код послуги."},"contractNumber":{"type":"string","description":"Номер договору для оплати послуги."},"amount":{"type":"number","description":"Кількість послуги."},"payerType":{"type":"string","description":"Тип платника."},"additionalParameters":{"type":"object","description":"Планові параметри вантажу.","properties":{"parcelDescription":{"type":"string","description":"Опис вантажу."},"parcelsAmount":{"type":"number","description":"Планова кількість місць."},"totalActualWeight":{"type":"number","description":"Загальна планова фактична вага."},"totalVolumetricWeight":{"type":"number","description":"Загальна планова об'ємна вага."},"length":{"type":"number","description":"Планова довжина вантажу.","nullable":true},"width":{"type":"number","description":"Планова ширина вантажу.","nullable":true},"height":{"type":"number","description":"Планова висота вантажу.","nullable":true}}}}}},"statuses":{"type":"array","description":"Масив об’єктів статусів, що відстежують зміни статусу заявки на кур’єрський забір.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Унікальний ідентифікатор статусу.","minimum":1},"pickupId":{"type":"integer","description":"Ідентифікатор заявки на кур’єрський забір.","minimum":1},"status":{"type":"string","description":"Поточний статус заявки на кур’єрський забір, що відображає етап її обробки.\n\nМожливі значення: `Draft`, `Created`, `AppointedCourier`, `InProgress`, `Done`, `ClientCanceled`, `NotCompleted`, `Deleted`, `ReceivedByCourier`.\n"},"dateTime":{"type":"string","format":"date-time","description":"Дата та час зміни статусу.","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$"},"note":{"type":"string","description":"Необов’язкові примітки, пов’язані зі статусом.","maxLength":255,"nullable":true},"user":{"type":"string","description":"Ідентифікатор користувача, який змінив статус.","maxLength":50},"createdAt":{"type":"string","format":"date-time","description":"Дата та час створення запису статусу.","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$"},"updatedAt":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення запису статусу.","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$"},"deletedAt":{"type":"string","format":"date-time","description":"Дата та час видалення запису статусу.","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$","nullable":true}}}},"createdAt":{"type":"string","format":"date-time","description":"Дата та час створення заявки на кур’єрський забір.","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$"},"updatedAt":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення заявки на кур’єрський забір.","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$"},"deletedAt":{"type":"string","format":"date-time","description":"Дата та час видалення заявки на кур’єрський забір.","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$","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Створити заявку на кур’єрський забір"}}}} ``` ## Оновити заявку на кур’єрський забір > Цей метод використовується для оновлення даних уже створеної заявки на кур’єрський забір. Він дозволяє змінювати інформацію про заявку, зокрема адресу, контактні дані, часовий інтервал кур’єрського забору та інші параметри, у статусах \`Draft\`, \`Created\` та \`AppointedCourier\`, щоб забезпечити коректний і своєчасний забір відправлень.\ > \ > Для заявок у статусах \`Created\` та \`AppointedCourier\` часовий інтервал кур’єрського забору можна змінити лише за умови перенесення дати забору на наступний день або пізніше.\ > \ > \*\*🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.\*\*
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Pickups"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT-токен авторизації зі строком дії 1 годину у заголовку"}},"responses":{"Unauthorized":{"description":"Неавторизований доступ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Вказаний ресурс не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Помилка валідації","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}":{"put":{"description":"Цей метод використовується для оновлення даних уже створеної заявки на кур’єрський забір. Він дозволяє змінювати інформацію про заявку, зокрема адресу, контактні дані, часовий інтервал кур’єрського забору та інші параметри, у статусах `Draft`, `Created` та `AppointedCourier`, щоб забезпечити коректний і своєчасний забір відправлень.\n\nДля заявок у статусах `Created` та `AppointedCourier` часовий інтервал кур’єрського забору можна змінити лише за умови перенесення дати забору на наступний день або пізніше.\n\n**🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.**\n","tags":["Pickups"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]},"description":"Ідентифікатор pickup. Для EU використовується `integer`, наприклад `38556`.\n\n🔹Для UA використовується значення у форматі UUID, наприклад `01a0b43d-5649-7a06-bdb1-c9394536dbea`.\n\n🔹Ідентифікатор `id` можна отримати з відповіді на метод [Створити заявку на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#post-pickups) або за допомогою методу [Отримати список заявок на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#get-pickups), виконавши пошук заявки за номером документа.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fullName","phone","countryCode","lockVersion","addressParts"],"properties":{"note":{"type":"string","description":"Додаткові примітки або інструкції для кур’єра.","maxLength":255},"services":{"type":"array","items":{"type":"string"},"description":"Список додаткових послуг, які можна додати до заявки на кур’єрський забір. Наразі ця функціональність перебуває в розробці.","nullable":true},"phone":{"type":"string","description":"Контактний номер телефону відправника, необхідний для того, щоб кур’єр міг зв’язатися у разі потреби.","minLength":8,"maxLength":14},"email":{"type":"string","description":"Адреса електронної пошти. Не є обов’язковою, проте рекомендується як резервний спосіб зв’язку у випадку некоректного номера телефону або для отримання додаткових сповіщень щодо кур’єрського забору.","nullable":true},"fullName":{"type":"string","description":"Повне ім’я клієнта-відправника, необхідне для ідентифікації відправника та коректної обробки заявки на кур’єрський забір.","maxLength":100},"companyTin":{"type":"string","description":"ІПН юридичної особи.","minLength":2,"maxLength":20},"companyName":{"type":"string","description":"Назва компанії, яка створила заявку на кур’єрський забір.","minLength":2,"maxLength":255},"lockVersion":{"type":"integer","description":"Номер версії для запобігання конфліктам під час оновлення даних. При кожному наступному оновленні заявки значення цього параметра необхідно збільшувати на 1.","minimum":1},"countryCode":{"type":"string","description":"Код країни місця кур’єрського забору у форматі ISO Alpha-2.","pattern":"^[A-Z]{2}$"},"addressParts":{"type":"object","description":"Детальна інформація про адресу кур’єрського забору.","properties":{"city":{"type":"string","description":"Назва міста кур’єрського забору.","maxLength":100},"region":{"type":"string","description":"Назва області, регіону або адміністративно-територіальної одиниці кур’єрського забору.","maxLength":100},"street":{"type":"string","description":"Назва вулиці кур’єрського забору.","maxLength":100},"postCode":{"type":"string","description":"Поштовий індекс адреси кур’єрського забору.","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі за адресою кур’єрського забору.","maxLength":100},"flat":{"type":"string","description":"Номер квартири або офісу.","maxLength":10},"block":{"type":"string","description":"Номер корпусу, секції або блоку будівлі, якщо застосовується.","maxLength":100},"note":{"type":"string","description":"Додаткові інструкції для доступу кур’єра до місця кур’єрського забору.","maxLength":100}}},"preferredDeliveryDate":{"type":"string","description":"Бажана дата доставки у форматі `DD.MM.YYYY`.\n\n🔹Цей параметр є обов’язковим і використовується лише для виклику кур’єра в межах України (UA).\n"},"timeInterval":{"type":"string","description":"Бажаний часовий інтервал доставки.\n\n🔹Цей параметр використовується лише для виклику кур’єра в межах України (UA).\n"},"pickedTimeFrom":{"type":"string","format":"date-time","description":"Початок часового інтервалу кур’єрського забору, вибраного зі списку доступних часових інтервалів, отриманих через відповідний метод.\n\n🔹Для заявок у статусах `Created` та `AppointedCourier` часовий інтервал можна змінити лише за умови перенесення дати забору на наступний день або пізніше.\n","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$","nullable":true},"pickedTimeTo":{"type":"string","format":"date-time","description":"Кінець часового інтервалу кур’єрського забору, вибраного зі списку доступних часових інтервалів, отриманих через відповідний метод.\n\n🔹Для заявок у статусах `Created` та `AppointedCourier` часовий інтервал можна змінити лише за умови перенесення дати забору на наступний день або пізніше.\n","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$","nullable":true},"planedWeight":{"type":"number","description":"Запланована вага посилки.\n\n🔹Цей параметр використовується лише для виклику кур’єра в межах України (UA).\n"}}}}}},"responses":{"200":{"description":"Заявку на кур’єрський забір успішно оновлено","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}],"description":"Унікальний ідентифікатор оновленої заявки на кур’єрський забір."},"number":{"type":"string","description":"Реєстраційний номер заявки на кур’єрський забір."},"status":{"type":"string","description":"Поточний статус оновленої заявки на кур’єрський забір.\n\nМожливі значення:\n - **Draft**: Початковий етап, коли заявку створено, але ще не завершено її оформлення.\n - **Created**: Заявку створено та підготовлено до обробки.\n - **AppointedCourier**: Для заявки призначено кур’єра.\n","enum":["Draft","Created","AppointedCourier"]},"lockVersion":{"type":"integer","description":"Оновлений номер версії для запобігання конфліктам під час оновлення даних."},"note":{"type":"string","description":"Оновлені примітки для кур’єра.","maxLength":255},"pickedTimeFrom":{"type":"string","format":"date-time","description":"Оновлений початок часового інтервалу кур’єрського забору.","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$"},"pickedTimeTo":{"type":"string","format":"date-time","description":"Оновлений кінець часового інтервалу кур’єрського забору.","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$"},"addressParts":{"type":"object","description":"Оновлена інформація про адресу кур’єрського забору.","properties":{"city":{"type":"string","description":"Назва міста кур’єрського забору.","maxLength":100},"region":{"type":"string","description":"Назва області, регіону або адміністративно-територіальної одиниці кур’єрського забору.","maxLength":100},"street":{"type":"string","description":"Назва вулиці кур’єрського забору.","maxLength":100},"postCode":{"type":"string","description":"Поштовий індекс адреси кур’єрського забору.","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі за адресою кур’єрського забору.","maxLength":100},"flat":{"type":"string","description":"Номер квартири або офісу.","maxLength":10},"block":{"type":"string","description":"Номер корпусу, секції або блоку будівлі, якщо застосовується.","maxLength":100},"note":{"type":"string","description":"Додаткові інструкції для доступу кур’єра до місця кур’єрського забору.","maxLength":100}}},"statuses":{"type":"array","description":"Масив оновлених статусів заявки на кур’єрський забір.","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Оновити заявку на кур’єрський забір"}}}} ``` ## Видалити заявку на виклик кур'єра > Цей метод дозволяє бізнес-клієнтам повністю видалити існуючу заявку на виклик кур'єра. При видаленні заявки на виклик кур'єра вона позначається в системі як видалена, а також фіксується дата та час видалення.\ > \ > \*\*🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.\*\*
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Pickups"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT-токен авторизації зі строком дії 1 годину у заголовку"}},"responses":{"Unauthorized":{"description":"Неавторизований доступ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Вказаний ресурс не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Помилка валідації","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}":{"delete":{"description":"Цей метод дозволяє бізнес-клієнтам повністю видалити існуючу заявку на виклик кур'єра. При видаленні заявки на виклик кур'єра вона позначається в системі як видалена, а також фіксується дата та час видалення.\n\n**🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.**\n","tags":["Pickups"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]},"description":"Ідентифікатор pickup. Для ЄС використовується `integer`, наприклад `38556`.\n\n🔹Для України використовується значення у форматі UUID, наприклад `01a0b43d-5649-7a06-bdb1-c9394536dbea`.\n\n🔹Ідентифікатор `id` можна отримати з відповіді на метод [Створити заявку на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#post-pickups) або за допомогою методу [Отримати список заявок на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#get-pickups), виконавши пошук заявки за номером документа.\n"}],"responses":{"200":{"description":"Заявку на кур’єрський забір успішно видалено","content":{"application/json":{"schema":{"type":"object","properties":{"deletedAt":{"type":"string","format":"date-time","description":"Дата та час, коли заявку на кур’єрський забір було позначено як видалену.","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$"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Видалити заявку на виклик кур'єра"}}}} ``` ## Додати відправлення до заявки на кур’єрський забір > Цей метод використовується для додавання вже створених відправлень до існуючої заявки на виклик кур'єра. Відповідно до встановленого бізнес-процесу, вже створені відправлення мають бути додані до заявки на виклик кур'єра після того, як її було створено.\ > \ > \*\*🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.\*\*
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Pickups"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT-токен авторизації зі строком дії 1 годину у заголовку"}},"responses":{"Unauthorized":{"description":"Неавторизований доступ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Вказаний ресурс не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Помилка валідації","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}/shipments":{"post":{"description":"Цей метод використовується для додавання вже створених відправлень до існуючої заявки на виклик кур'єра. Відповідно до встановленого бізнес-процесу, вже створені відправлення мають бути додані до заявки на виклик кур'єра після того, як її було створено.\n\n**🔹Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post, та в Україні. Зверніть увагу, що параметри для відправки для Європи та України відрізняються.**\n","tags":["Pickups"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]},"description":"Унікальний ідентифікатор заявки на кур’єрський забір, до якої додаються відправлення.\n\n🔹Для кур’єрських заборів у Європі (EU) використовується `integer`.\n\n🔹Для кур’єрських заборів в Україні (UA) використовується UUID.\n\n🔹Ідентифікатор `id` можна отримати з відповіді на метод [Створити заявку на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#post-pickups) або за допомогою методу [Отримати список заявок на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#get-pickups), виконавши пошук заявки за номером документа.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","items":{"type":"object","properties":{"shipmentId":{"type":"integer","description":"Унікальний ідентифікатор відправлення, яке необхідно додати.\n\n🔹Цей параметр є обов’язковим лише для кур’єрських доставок у Європі (EU).\n\nІдентифікатор `shipmentId` відповідає значенню поля `id` відправлення, яке повертається у відповіді на метод [Створення відправлень](https://api-portal.novapost.com/methods/ua/overview/shipments/create). Його також можна отримати за допомогою методу [Список відправлень](https://api-portal.novapost.com/methods/ua/overview/shipments#get-shipments), виконавши пошук відправлення за номером транспортного документа.\n","minimum":1},"number":{"type":"string","description":"Номер відправлення.\n\n🔹Цей параметр є обов’язковим лише для кур’єрських доставок в Україні (UA). Для кур’єрських доставок в Україні використовується поле `number` у форматі `\"number\": \"20400009273357\"`.\n"}}},"description":"Список відправлень, які необхідно додати до заявки на кур’єрський забір."}}}}}},"responses":{"200":{"description":"Відправлення успішно додано до заявки на кур’єрський забір","content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Унікальний ідентифікатор запису відправлення у заявці на кур’єрський забір.","minimum":1,"nullable":true},"pickupId":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}],"description":"Унікальний ідентифікатор пов’язаної заявки на кур’єрський забір.\n\n🔹Для України (UA) повертається значення у форматі UUID.\n"},"shipmentId":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}],"description":"Унікальний ідентифікатор доданого відправлення.\n\n🔹Для України (UA) повертається значення у форматі UUID.\n\nДля Європи (EU) ідентифікатор `shipmentId` відповідає значенню поля `id` відправлення, яке повертається у відповіді на метод [Створення відправлень](https://api-portal.novapost.com/methods/ua/overview/shipments/create). Його також можна отримати за допомогою методу [Список відправлень](https://api-portal.novapost.com/methods/ua/overview/shipments#get-shipments), виконавши пошук відправлення за номером транспортного документа.\n"},"shipmentNumber":{"type":"string","description":"Номер відправлення.\n\n🔹Цей параметр повертається лише для кур’єрських доставок в Україні (UA).\n","nullable":true},"status":{"type":"string","description":"Поточний статус відправлення в межах заявки на кур’єрський забір. Значення повертається системою та відображає поточний стан відправлення.\n\nМожливі значення: `Accepted`, `NotReady`, `NotPacked`, `ClientCanceled`, `Deleted`, `Added`.\n","nullable":true},"note":{"type":"string","description":"Додаткові примітки щодо відправлення, якщо застосовується.","nullable":true},"deliveryPartners":{"type":"array","description":"Список партнерів доставки, пов’язаних із відправленням, якщо застосовується.","items":{"type":"object"}},"createdAt":{"type":"string","format":"date-time","description":"Дата та час додавання відправлення.","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$","nullable":true},"updatedAt":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення запису відправлення.","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$","nullable":true},"deletedAt":{"type":"string","format":"date-time","description":"Дата та час видалення запису відправлення, якщо застосовується.","nullable":true},"shipmentCreatedAt":{"type":"string","format":"date-time","description":"Дата та час створення відправлення.\n\n🔹Цей параметр повертається лише для кур’єрських доставок в Україні (UA).\n","nullable":true},"number":{"type":"string","description":"Номер відправлення, пов’язаний із записом відправлення у заявці на кур’єрський забір.\n\n🔹Цей параметр повертається лише для кур’єрських доставок в Україні (UA).\n","nullable":true},"paymentStatus":{"type":"string","description":"Статус оплати відправлення.\n\n🔹Цей параметр повертається лише для кур’єрських доставок в Україні (UA).\n","nullable":true},"currencyCode":{"type":"string","description":"Код валюти відправлення.\n\n🔹Цей параметр повертається лише для кур’єрських доставок в Україні (UA).\n","nullable":true},"parcels":{"type":"array","description":"Список місць відправлення.\n\n🔹Цей параметр повертається лише для кур’єрських доставок в Україні (UA).\n","items":{"type":"object"}},"services":{"type":"array","description":"Список послуг, пов’язаних із відправленням.\n\n🔹Цей параметр повертається лише для кур’єрських доставок в Україні (UA).\n","items":{"type":"object"}},"invoice":{"type":"object","description":"Інформація про інвойс відправлення.\n\n🔹Цей параметр повертається лише для кур’єрських доставок в Україні (UA).\n","nullable":true}}}},"failed":{"type":"array","description":"Список відправлень, які не вдалося додати до заявки на кур’єрський забір.\n\n🔹Цей параметр повертається лише для кур’єрських доставок в Україні (UA).\n","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Додати відправлення до заявки на кур’єрський забір"}}}} ``` ## Видалити відправлення із заявки на забір > Цей метод дозволяє видаляти конкретні відправлення з наявної заявки на кур’єрський забір.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Pickups"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT-токен авторизації зі строком дії 1 годину у заголовку"}},"responses":{"Unauthorized":{"description":"Неавторизований доступ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Вказаний ресурс не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Помилка валідації","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}/shipments":{"delete":{"description":"Цей метод дозволяє видаляти конкретні відправлення з наявної заявки на кур’єрський забір.\n","tags":["Pickups"],"parameters":[{"name":"id","in":"path","required":true,"description":"Унікальний ідентифікатор заявки на кур’єрський забір. Для Європи (EU) використовується `integer`.\n\n🔹Для України (UA) використовується UUID.\n\n🔹Ідентифікатор `id` можна отримати з відповіді на метод [Створити заявку на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#post-pickups) або за допомогою методу [Отримати список заявок на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#get-pickups), виконавши пошук заявки за номером документа.\n","schema":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","description":"Список відправлень, які необхідно видалити із заявки на кур’єрський забір.","items":{"type":"object","properties":{"shipmentId":{"type":"integer","description":"Унікальний ідентифікатор відправлення, яке необхідно видалити.\n\n🔹Цей параметр є обов’язковим лише для кур’єрських доставок у Європі (EU).\n\nІдентифікатор `shipmentId` відповідає значенню поля `id` відправлення, яке повертається у відповіді на метод [Створення відправлень](https://api-portal.novapost.com/methods/ua/overview/shipments/create). Його також можна отримати за допомогою методу [Список відправлень](hhttps://api-portal.novapost.com/methods/ua/overview/shipments#get-shipments), виконавши пошук відправлення за номером транспортного документа.\n","minimum":1},"number":{"type":"string","description":"Номер відправлення.\n\n🔹Цей параметр є обов’язковим лише для кур’єрських доставок в Україні (UA). Для кур’єрських доставок в Україні використовується поле `number` у форматі `\"number\": \"20400009273357\"`.\n"}}}}}}}}},"responses":{"200":{"description":"Відправлення успішно видалено","content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","description":"Інформація про видалені відправлення","items":{"type":"object","properties":{"deletedAt":{"type":"string","format":"date-time","description":"Дата та час видалення відправлення."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Видалити відправлення із заявки на забір"}}}} ``` ## Оновити статус заявки на забір > Цей метод дозволяє оновлювати статус наявної заявки на кур’єрський забір.\ > \ > \*\*🔹Цей метод працює тільки для країн Європи.\*\*\ > \ > Метод можна використовувати для:\ > \- переведення заявки на виклик кур'єра зі статусу \`Draft\` у статус \`Created\`;\ > \- скасування заявки у статусі \`Created\`, \`AppointedCourier\` або \`InProgress\` шляхом зміни її статусу на \`ClientCanceled\`.\ > \ > Поки заявка перебуває у статусі \`Draft\`, вона залишається на підготовчому етапі, під час якого можна додати всі необхідні відправлення. Щойно статус оновлюється на \`Created\`, система управління відправленнями розпізнає виклик кур'єра як завершений і готовий до обробки кур'єрською службою.\ > \ > Скасування заявки клієнтом дозволено лише для таких переходів між статусами:\ > \- \`Created\` → \`ClientCanceled\`;\ > \- \`AppointedCourier\` → \`ClientCanceled\`;\ > \- \`InProgress\` → \`ClientCanceled\`.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Pickups"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT-токен авторизації зі строком дії 1 годину у заголовку"}},"responses":{"Unauthorized":{"description":"Неавторизований доступ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Вказаний ресурс не знайдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Помилка валідації","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}/status":{"put":{"description":"Цей метод дозволяє оновлювати статус наявної заявки на кур’єрський забір.\n\n**🔹Цей метод працює тільки для країн Європи.**\n\nМетод можна використовувати для:\n- переведення заявки на виклик кур'єра зі статусу `Draft` у статус `Created`;\n- скасування заявки у статусі `Created`, `AppointedCourier` або `InProgress` шляхом зміни її статусу на `ClientCanceled`.\n\nПоки заявка перебуває у статусі `Draft`, вона залишається на підготовчому етапі, під час якого можна додати всі необхідні відправлення. Щойно статус оновлюється на `Created`, система управління відправленнями розпізнає виклик кур'єра як завершений і готовий до обробки кур'єрською службою.\n\nСкасування заявки клієнтом дозволено лише для таких переходів між статусами:\n- `Created` → `ClientCanceled`;\n- `AppointedCourier` → `ClientCanceled`;\n- `InProgress` → `ClientCanceled`.\n","tags":["Pickups"],"parameters":[{"name":"id","in":"path","required":true,"description":"Унікальний ідентифікатор заявки на кур’єрський забір.\n\n🔹Ідентифікатор `id` можна отримати з відповіді на метод [Створити заявку на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#post-pickups) або за допомогою методу [Отримати список заявок на кур’єрський забір](https://api-portal.novapost.com/methods/ua/overview/pickups#get-pickups), виконавши пошук заявки за номером документа.\n","schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Використовується для оновлення статусу заявки на кур’єрський забір.\n\nДля завершення формування заявки та передачі її на обробку системою управління відправленнями змініть статус з `Draft` на `Created`.\n\nДля скасування заявки встановіть статус `ClientCanceled`. Скасування доступне лише для заявок у статусі `Created`, `AppointedCourier` або `InProgress`.\n\nДозволені переходи між статусами:\n- `Draft` → `Created`;\n- `Created` → `ClientCanceled`;\n- `AppointedCourier` → `ClientCanceled`;\n- `InProgress` → `ClientCanceled`.\n\nМожливі поточні статуси: `Draft`, `Created`, `AppointedCourier`, `InProgress`.\n","enum":["Created","ClientCanceled"]},"lockVersion":{"type":"integer","description":"Номер версії для запобігання конфліктам під час оновлення даних. При кожному наступному оновленні заявки значення цього параметра необхідно збільшувати на 1.","minimum":1},"note":{"type":"string","description":"Обов’язкова примітка або коментар із додатковою інформацією щодо причини зміни статусу. Поле необхідно заповнювати під час зміни статусу для забезпечення належного відстеження та збереження контексту змін.","maxLength":255}},"required":["id","status","lockVersion"]}}}},"responses":{"200":{"description":"Статус успішно оновлено","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Визначає, чи було успішно оновлено статус заявки."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Оновити статус заявки на забір"}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://api-portal.novapost.com/methods/ua/overview/pickups.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.