> 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/metodi-1/metodi/draft.md).

# Draft

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

> Цей API-метод дозволяє отримати список транспортних документів (відправлень), які ви створили. Використовуючи цей метод, ви можете отримати доступ до транспортних документів, що належать вам або вашому обліковому запису. Відповідь міститиме деталі кожного відправлення, такі як ідентифікатор відправлення, номер, отримувач, деталі вантажу та іншу релевантну інформацію.\</br>\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\
> \
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, що вміщується в один рядок; текст, який не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, що відображає більше одного рядка тексту.\
> &#x20; \
> \*\*EXAMPLE\*\*\
> \
> Показує готовий приклад JSON із коректно заповненими значеннями для демонстрації того, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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":{"/shipments":{"get":{"tags":["Shipments"],"description":"Цей API-метод дозволяє отримати список транспортних документів (відправлень), які ви створили. Використовуючи цей метод, ви можете отримати доступ до транспортних документів, що належать вам або вашому обліковому запису. Відповідь міститиме деталі кожного відправлення, такі як ідентифікатор відправлення, номер, отримувач, деталі вантажу та іншу релевантну інформацію.</br>\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**\n\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, що вміщується в один рядок; текст, який не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, що відображає більше одного рядка тексту.\n  \n**EXAMPLE**\n\nПоказує готовий приклад JSON із коректно заповненими значеннями для демонстрації того, як має виглядати валідний запит або відповідь.\n","parameters":[{"in":"query","name":"numbers[]","description":"Пошук відправлень за номером транспортного документа. Може приймати як один номер для пошуку, так і масив номерів.","schema":{"type":"string"}},{"in":"query","name":"ids[]","description":"Пошук відправлень за ідентифікаторами транспортних документів.","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"limit","description":"Максимальна кількість елементів на сторінці.","schema":{"type":"integer","format":"int32","default":15}},{"in":"query","name":"page","description":"Номер сторінки для повернення.","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"inRegistry","description":"Прапорець, що показує, чи включено відправлення до реєстру. Лише для європейських посилок.","schema":{"type":"boolean"}},{"in":"query","name":"registerNumber","description":"Номер реєстру, який містить усі відправлення. Лише для європейських посилок.","schema":{"type":"string"}},{"in":"query","name":"senderDivisionId","description":"Ідентифікатор відділення, з якого здійснюється відправлення.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"shipments","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},"from":{"type":"integer","nullable":true},"to":{"type":"integer","nullable":true},"items":{"type":"array","description":"Інформація про елементи у відправленнях.","items":{"type":"object","properties":{"id":{"type":"string","description":"Унікальний ідентифікатор, присвоєний кожному відправленню, який використовується для внутрішніх операцій, таких як модифікація, пошук у системі та видалення відправлень. Поле 'id' слугує ключовим посиланням для адміністративних і логістичних процесів, забезпечуючи точний доступ і керування записами відправлень.","minimum":1},"version":{"type":"integer","description":"Версія документа, кожна зміна документа збільшує значення на +1."},"number":{"type":"string","description":"Номер транспортного документа.","pattern":"^[A-Z]{4}\\d{10}$"},"dateTime":{"type":"string","description":"Дата та час створення документа."},"scheduledDeliveryDate":{"type":"string","description":"Запланована дата доставки.","nullable":true},"closingDate":{"type":"string","description":"Дата закриття документа. Відображається після успішної доставки.","nullable":true},"createdAt":{"type":"string","description":"Дата та час створення відправлення."},"updatedAt":{"type":"string","description":"Дата та час оновлення відправлення."},"deletedAt":{"type":"string","description":"Дата та час видалення відправлення, або null, якщо не видалено.","nullable":true},"userCreate":{"type":"string","description":"Внутрішні дані, не для використання."},"status":{"type":"string","description":"Поточний статус документа (наприклад, ReadyToShip, Accepted, Issued, Draft, Deleted)."},"gtid":{"type":"string","description":"Внутрішні дані, не для використання."},"paymentStatus":{"type":"string","description":"Статус оплати послуг доставки (наприклад, Paid, NeedPay, ContractAfterPayment)."},"currencyCode":{"type":"string","description":"Код валюти відповідно до умов договору платника згідно стандарту ISO-4217."},"parcelsAmount":{"type":"integer","description":"Кількість об’єктів у посилках.","minimum":1},"clientOrder":{"type":"string","description":"Містить усі можливі ідентифікатори замовлення, пов’язані з відправленням. Ці ідентифікатори задаються клієнтом для внутрішнього трекінгу та використовуються для відстеження відправлення протягом усього його маршруту. Усі передані значення можуть використовуватись у системі відстеження.","maxLength":50},"note":{"type":"string","description":"Додаткова інформація або спеціальні інструкції щодо замовлення. Може включати інструкції з доставки, особливі умови обробки або інші важливі деталі.","maxLength":255},"payerType":{"type":"string","description":"Інформація про те, хто оплачує доставку (наприклад, Sender, Recipient, ThirdPerson)."},"payerContractId":{"type":"integer","description":"Ідентифікатор особи або організації, що оплачує доставку.","nullable":true},"payerContractNumber":{"type":"string","description":"Містить номер договору, якщо \"payerType\" встановлено як \"ThirdPerson\". Також може містити номер договору відправника як платника при безготівкових розрахунках.","nullable":true},"postomatCellReservation":{"type":"string","description":"Внутрішні дані, не для використання."},"postomatOrderRef":{"type":"string","description":"Внутрішні дані, не для використання."},"firstDayStorage":{"type":"string","description":"Дата початку зберігання відправлення.","nullable":true},"cargoAutoReturnDate":{"type":"string","description":"Дата автоматичного повернення відправлення, якщо послугу замовлено.","nullable":true},"marketplacePartner":{"type":"string","description":"Внутрішні дані, не для використання."},"registerNumber":{"type":"string","description":"Внутрішні дані, не для використання."},"customerNote":{"type":"string","description":"Внутрішні дані, не для використання."},"creationDateNote":{"type":"string","description":"Внутрішні дані, не для використання."},"sender":{"type":"object","description":"Інформація про відправника. Параметр містить набір полів для опису фізичної особи або організації, яка відправляє вантаж (власник вантажу).","properties":{"companyId":{"type":"integer","description":"Внутрішні дані, не для використання.","nullable":true},"companyTin":{"type":"string","description":"ІПН компанії, якщо відправник є юридичною особою. Порожній параметр, якщо відправник не є компанією.","maxLength":20},"companyName":{"type":"string","description":"Назва компанії, якщо відправник є юридичною особою. Якщо відправник не є компанією — фізична особа.","maxLength":255},"phone":{"type":"string","description":"Контактний номер телефону відправника або представника компанії відправника.\nВикористовується для комунікації щодо відправлення, включаючи координацію забору та вирішення проблем.\n\n**Формат:** Номер телефону має бути вказаний у **міжнародному форматі** відповідно до стандарту **E.164**.\n\nПриклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX\n\n**Обмеження:**\n- Номер телефону відправника має бути дійсним і доступним у разі виникнення проблем із доставкою.\n- Якщо номер передано в локальному (не міжнародному) форматі, система спробує його **нормалізувати**, але така логіка обмежена і може не покривати всі варіанти для різних країн.\nНаполегливо рекомендується реалізувати **валідацію на фронтенді**, щоб забезпечити введення номерів у правильному міжнародному форматі.\n","minimum":8,"maximum":15},"email":{"type":"string","description":"Електронна адреса відправника."},"name":{"type":"string","description":"Контактна особа.","maxLength":100},"countryCode":{"type":"string","description":"Код країни відправника відповідно до стандарту ISO 3166-1 Alpha-2. Наприклад, PL.","pattern":"^[A-Z]{2}$"},"settlementId":{"type":"string","description":"Ідентифікатор населеного пункту."},"cityId":{"type":"integer","description":"Ідентифікатор міста.","nullable":true},"address":{"type":"string","description":"Домашня адреса або опис складу."},"addressParts":{"type":"object","description":"Адреса відправника у разі відправлення з адреси. Параметр містить набір полів для опису адреси забору або іншого місця, окрім складів.","properties":{"postCode":{"type":"string","description":"Поштовий індекс. Використовується для коректного сортування вантажу, лише для адресної доставки.","maxLength":10},"region":{"type":"string","description":"Назва району міста, лише для адресної доставки. Рекомендується використовувати значення з довідника населених пунктів.","maxLength":100},"city":{"type":"string","description":"Назва міста або населеного пункту, лише для адресної доставки. Рекомендується використовувати коректне значення з довідника населених пунктів.","maxLength":100},"street":{"type":"string","description":"Назва вулиці, лише для адресної доставки.","maxLength":100},"building":{"type":"string","description":"Номер будівлі, лише для адресної доставки.","maxLength":100},"block":{"type":"string","description":"Корпус.","maxLength":100},"flat":{"type":"string","description":"Номер квартири, лише для адресної доставки.","maxLength":10},"note":{"type":"string","description":"Додаткова інформація про адресу відправника.","maxLength":100}}},"divisionId":{"type":"string","description":"Ідентифікатор відділення. Якщо відправлення здійснюється зі складу, цей параметр є обов’язковим."},"divisionCategory":{"type":"string","description":"Тип відділення."},"archive":{"type":"boolean","description":"Внутрішні дані, не для використання."}}},"recipient":{"type":"object","description":"Інформація про отримувача. Параметр містить набір полів для опису фізичної особи або організації, яка повинна отримати вантаж.","properties":{"companyId":{"type":"integer","description":"Внутрішні дані, не для використання.","nullable":true},"companyTin":{"type":"string","description":"ІПН компанії, якщо отримувач є юридичною особою. Порожній параметр, якщо отримувач не є компанією.","maxLength":20},"companyName":{"type":"string","description":"Назва компанії, якщо отримувач є юридичною особою. Якщо отримувач не є компанією — фізична особа.","maxLength":255},"phone":{"type":"string","description":"Контактний номер телефону отримувача або представника компанії отримувача. Використовується для повідомлень про доставку та комунікації під час обробки відправлення.\n  \n  **Формат:** номер телефону має бути вказаний у **міжнародному форматі** відповідно до стандарту **E.164**.\n\n  Приклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX\n\n  **Обмеження:**\n  - Для доставки у відділення Nova Post в Європі допускаються українські мобільні номери.\n  - Для доставки у **партнерські точки** (InPost, GLS, Venipak, Cargus тощо) та при **міжнародній адресній доставці** номер має належати мобільному оператору країни отримувача. Якщо номер передано в локальному форматі, система спробує його нормалізувати, але алгоритм не покриває всі випадки. Рекомендується реалізувати валідацію на стороні клієнта або повідомляти про проблемні кейси.\n","minimum":8,"maximum":15},"email":{"type":"string","description":"Електронна адреса отримувача."},"name":{"type":"string","description":"Прізвище та ім’я отримувача або представника компанії.","maxLength":100},"countryCode":{"type":"string","description":"Код країни отримувача відповідно до ISO 3166-1 Alpha-2. Наприклад, UA.","pattern":"^[A-Z]{2}$"},"settlementId":{"type":"string","description":"Ідентифікатор населеного пункту."},"cityId":{"type":"integer","description":"Ідентифікатор міста.","nullable":true},"address":{"type":"string","description":"Домашня адреса або опис складу."},"addressParts":{"type":"object","description":"Адреса отримувача у разі доставки на адресу. Параметр містить набір полів для опису адреси доставки отримувача або іншого місця, окрім відділень.","properties":{"postCode":{"type":"string","description":"Поштовий індекс.","maxLength":10},"region":{"type":"string","description":"Назва району міста, лише для адресної доставки.","maxLength":100},"city":{"type":"string","description":"Назва міста або населеного пункту, лише для адресної доставки.","maxLength":100},"street":{"type":"string","description":"Назва вулиці, лише для адресної доставки.","maxLength":100},"building":{"type":"string","description":"Номер будівлі, лише для адресної доставки.","maxLength":100},"block":{"type":"string","description":"Корпус.","maxLength":100},"flat":{"type":"string","description":"Номер квартири, лише для адресної доставки.","maxLength":100},"note":{"type":"string","description":"Додаткова інформація про адресу отримувача.","maxLength":100}}},"divisionId":{"type":"string","description":"Ідентифікатор відділення. Якщо отримання у відділенні, цей параметр є обов’язковим."},"divisionCategory":{"type":"string","description":"Тип відділення."},"archive":{"type":"boolean","description":"Внутрішні дані, не для використання."}}},"parcels":{"type":"array","description":"Блок опису посилок. Масив містить об’єкти, кожен з яких відповідає за інформацію про посилку.","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер транспортного документа.","pattern":"^[A-Z]{4}\\d{10}$"},"row_number":{"type":"integer","description":"Номер посилки.","minimum":1},"untied":{"type":"boolean","description":"Внутрішні дані, не для використання."},"cargo_category_id":{"type":"string","description":"Внутрішні дані, не для використання."},"cargo_category_group":{"type":"string","description":"Тип посилки."},"parcel_description":{"type":"string","description":"Короткий опис вмісту посилки.","maxLength":255},"insurance_cost":{"type":"number","description":"Сума оголошеної вартості.","minimum":0,"exclusiveMinimum":true},"length":{"type":"integer","description":"Фактична довжина посилки у мм.","minimum":1},"width":{"type":"integer","description":"Фактична ширина посилки у мм.","minimum":1},"height":{"type":"integer","description":"Фактична висота посилки у мм.","minimum":1},"actual_weight":{"type":"integer","description":"Фактична вага посилки у грамах.","minimum":0,"maximum":2147483647},"volumetric_weight":{"type":"integer","description":"Об’ємна вага посилки.","minimum":0,"maximum":2147483647},"length_check":{"type":"integer","nullable":true},"width_check":{"type":"integer","nullable":true},"height_check":{"type":"integer","nullable":true},"actual_weight_check":{"type":"integer","nullable":true},"volumetric_weight_check":{"type":"integer","nullable":true}}}},"services":{"type":"array","description":"Інформація про міжнародну доставку.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Унікальний ідентифікатор. Внутрішні дані, не для використання."},"service_id":{"type":"string","description":"Ідентифікатор сервісу. Внутрішні дані, не для використання."},"service_type":{"type":"string","description":"Тип сервісу (наприклад, InternationalServices, MainService, AdditionalServices)."},"service_name":{"type":"string","description":"Назва сервісу, який входить до вартості відправлення.\n\nПриклад: `Parcel international delivery (medium)`, `Parcel from home`.\n\nЦе поле представляє один із окремих сервісів, які разом формують загальну вартість доставки. Відповідь може містити кілька таких сервісів залежно від обраних опцій доставки та конфігурації відправлення.\nЩоб отримати повний перелік можливих сервісів і зрозуміти, які комбінації можуть застосовуватись, зверніться до вашого менеджера облікового запису.\n"},"parcel_number":{"type":"string","description":"Номер позиції в транспортному документі."},"payer_type":{"type":"string","description":"Інформація про те, хто оплачує доставку (наприклад, Sender, Recipient, ThirdPerson)."},"amount":{"type":"number","description":"Кількість об’єктів у позиції.","minimum":0},"price":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"cost":{"type":"number","minimum":0},"cost_before_check":{"type":"number","nullable":true},"payment_status":{"type":"string","description":"Статус оплати послуг доставки (наприклад, Paid, NeedPay, ContractAfterPayment, FreeOfCharge, Holded)."},"additional_parameters":{"type":"object","properties":{"cod":{"type":"integer","nullable":true,"description":"Інформація про переказ коштів."},"date":{"type":"integer","nullable":true},"from":{"type":"integer","nullable":true},"to":{"type":"integer","nullable":true},"string":{"type":"integer","nullable":true},"fullName":{"type":"integer","nullable":true},"phone":{"type":"integer","nullable":true}}}}}},"onlineTracking":{"type":"object","description":"Загальні статуси руху відправлення (створено/в дорозі/прибуло/отримано). Відображаються типи статусів, у які згруповано детальні статуси.","properties":{"tracking_status_code":{"type":"integer","description":"Код статусу відстеження."},"tracking_update_date":{"type":"string","description":"Дата оновлення статусу відстеження."},"short_description":{"type":"string","description":"Короткий опис статусу відстеження."},"long_description":{"type":"string","description":"Повний опис статусу відстеження."},"info":{"type":"string"},"label":{"type":"string"}}},"tracking":{"type":"array","description":"Масив статусів, що відображає всі етапи руху відправлення від відправника до отримувача з детальною інформацією.","items":{}},"totalWeight":{"type":"integer","description":"Загальна вага документа."},"totalInsuranceCost":{"type":"number","description":"Загальна задекларована вартість документа. Значення має бути більше нуля.","minimum":1,"exclusiveMinimum":true},"totalCost":{"type":"number","description":"Вартість послуг доставки. Значення має бути більше нуля.","minimum":1,"exclusiveMinimum":true},"invoice":{"type":"object","description":"Дані інвойсу, що використовуються для митного оформлення, включаючи задекларовану вартість, валюту та інформацію про товари.\n\nСтруктура об’єкта invoice у відповіді залежить від даних, переданих під час створення відправлення.\n\n🔹Якщо деякі поля не були передані в запиті, вони можуть бути відсутні у відповіді.\n","properties":{"customerNumber":{"type":"string","description":"Унікальний ідентифікатор/номер інвойсу, що супроводжує товари у відправленні, згенерований клієнтом. Використовується для митного оформлення для зв’язку товарів із супровідною документацією.","maxLength":50,"nullable":true},"customerCreatedAt":{"type":"string","format":"date-time","description":"Дата, зазначена в інвойсі, що супроводжує відправлення."},"type":{"type":"string","description":"Тип клієнтського інвойсу, що супроводжує відправлення та використовується для митної декларації."},"incoterm":{"type":"string","description":"Визначає торгові умови договору між покупцем і продавцем відповідно до правил Incoterms®."},"exportReason":{"type":"string","description":"Визначає загальну причину експорту товарів."},"cost":{"type":"number","description":"Загальна задекларована вартість інвойсу в оригінальній валюті."},"currency":{"type":"string","description":"Код валюти інвойсу згідно стандарту ISO 4217."},"payerFeesCustoms":{"type":"string","description":"Визначає, хто оплачує митні послуги."},"items":{"type":"array","description":"Деталізований перелік товарів у відправленні.\n\n🔹Об’єкти можуть містити лише ті поля, які були передані під час створення відправлення. Опціональні поля можуть бути відсутні у відповіді.\n","items":{"type":"object","properties":{"id":{"type":"string","description":"Унікальний ідентифікатор товару у відправленні."},"hsCode":{"type":"string","description":"Код товару за Гармонізованою системою."},"name":{"type":"string","description":"Назва товару мовою оригіналу для митної ідентифікації."},"nameEng":{"type":"string","description":"Назва товару англійською мовою для міжнародної обробки та документування."},"material":{"type":"string","description":"Основний матеріал товару."},"materialEng":{"type":"string","description":"Опис матеріалу англійською мовою."},"madeInCountryCode":{"type":"string","description":"Код країни походження (ISO 3166-1 alpha-2).","nullable":true},"producerAndModel":{"type":"string","description":"Виробник і модель товару."},"actualWeight":{"type":"integer","description":"Загальна вага всіх одиниць товару в грамах."},"measurementCode":{"type":"string","description":"Одиниця виміру (наприклад, штуки, кг)."},"amount":{"type":"number","description":"Кількість товару у вказаній одиниці виміру."},"cost":{"type":"number","description":"Вартість за одиницю товару у валюті відправника."}}}}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Список відправлень"}}}}
```

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

> Створення документа відправлення. Цей API-метод призначений для спрощення процесу формування транспортного документа для логістичних операцій через Nova Post. Передаючи ключові дані, такі як адреси відправлення та доставки, користувачі можуть легко створити документ, що описує транспортування вантажу. Метод також включає додаткові поля для митних органів, що дозволяє обробляти міжнародні відправлення. У відповіді API буде повернено унікальний ідентифікатор створеного документа разом з іншою релевантною інформацією.\
> \
> \*\*Правила валідації населеного пункту\*\*: \</br>\
> Для відправлень \*\*до або з Молдови та України\*\* населений пункт (місто) має бути успішно визначений. \</br>\
> Якщо передане значення міста не може бути співставлене з населеним пунктом, запит завершиться помилкою: \`validation.condition.recipient\_settlement\_not\_defined\`.\
> \
> Додаткова вимога:\
> Для відправлень, що потребують митного оформлення (імпорт), клієнтський інвойс необхідно завантажити як файл через метод \[POST /shipments/uploads/{id}]\(<https://api.novapost.com/developers/index.html#post-/shipments/uploads/-id->) (після створення відправлення).\</br>\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\
> \
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, що відображає більше одного рядка тексту.\
> &#x20; \
> \*\*EXAMPLE\*\*\
> \
> Показує готовий приклад JSON із правильно сформованими значеннями для демонстрації того, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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":{"/shipments":{"post":{"tags":["Shipments"],"description":"Створення документа відправлення. Цей API-метод призначений для спрощення процесу формування транспортного документа для логістичних операцій через Nova Post. Передаючи ключові дані, такі як адреси відправлення та доставки, користувачі можуть легко створити документ, що описує транспортування вантажу. Метод також включає додаткові поля для митних органів, що дозволяє обробляти міжнародні відправлення. У відповіді API буде повернено унікальний ідентифікатор створеного документа разом з іншою релевантною інформацією.\n\n**Правила валідації населеного пункту**: </br>\nДля відправлень **до або з Молдови та України** населений пункт (місто) має бути успішно визначений. </br>\nЯкщо передане значення міста не може бути співставлене з населеним пунктом, запит завершиться помилкою: `validation.condition.recipient_settlement_not_defined`.\n\nДодаткова вимога:\nДля відправлень, що потребують митного оформлення (імпорт), клієнтський інвойс необхідно завантажити як файл через метод [POST /shipments/uploads/{id}](https://api.novapost.com/developers/index.html#post-/shipments/uploads/-id-) (після створення відправлення).</br>\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**\n\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, що відображає більше одного рядка тексту.\n  \n**EXAMPLE**\n\nПоказує готовий приклад JSON із правильно сформованими значеннями для демонстрації того, як має виглядати валідний запит або відповідь.\n","requestBody":{"description":"Optional description in *Markdown*","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sender","invoice"],"properties":{"status":{"type":"string","description":"Визначає поточний статус транспортного документа, відстежуючи його проходження через життєвий цикл доставки. Статуси відображають кожен ключовий етап:\n- Draft: Документ знаходиться на початковій стадії, ще не завершений.\n- Accepted: Перевірений та прийнятий, документ готовий до наступних етапів.\n- Issued: Документ завершено та готовий до відправлення.\n- ReadyToShip: Вказує, що відправлення підготовлено до транспортування після створення експрес-накладної. Лише це значення може бути вказане при створенні відправлення.\n- Deleted: Документ видалено із системи.\n- Returned: Відправлення повернено відправнику.\n- Utilized: Вказує, що фізичні товари, пов’язані з транспортним документом, були утилізовані або знищені, і документ закрито.\n","enum":["ReadyToShip"]},"clientOrder":{"type":"string","description":"Представляє всі можливі ідентифікатори замовлення, пов’язані з відправленням. Ці ідентифікатори задаються клієнтом для внутрішнього відстеження та є важливими для контролю відправлення протягом усього його маршруту. Усі введені значення можуть відстежуватися в системі трекінгу.","maxLength":50},"note":{"type":"string","description":"Тут може бути вказана будь-яка додаткова інформація або спеціальні інструкції щодо замовлення. Це можуть бути інструкції з доставки, особливі умови обробки або інші важливі деталі, що сприяють обробці відправлення.","maxLength":255},"deliveryType":{"type":"string","description":"Визначає тип тарифу, який буде застосовано до відправлення під час створення або оновлення.\n- `standard`: Стандартний міжнародний тариф доставки.\n- `economy`: Економний міжнародний тариф доставки.\n- `express`: Експрес міжнародний тариф доставки.\n\nЯкщо поле не передано, тип тарифу визначається автоматично відповідно до поточних бізнес-правил, і існуюча логіка створення відправлення залишається без змін.\n\n**🔹Це поле є необов’язковим.**\n"},"payerType*":{"type":"string","description":"Визначає, хто несе відповідальність за оплату послуг доставки. Тип платника визначає сторону, яка покриває витрати:\n  - Sender: Відправник оплачує доставку.\n  - Recipient: Одержувач оплачує доставку.\n  - ThirdPerson: Третя сторона, не відправник і не одержувач, оплачує доставку. При виборі 'ThirdPerson' поле 'payerContractNumber' має містити номер договору платника. Детальніше див. статтю [Оплата послуг доставки через API Nova Post](https://api-portal.novapost.com/en/api-methods/payment/).\nЦе поле також використовується при формуванні інвойсу.\n\n**🔻Це поле є обов’язковим**\n","enum":["Sender","Recipient","ThirdPerson"]},"payerContractNumber":{"type":"string","description":"Це поле є обов’язковим у таких випадках:\n\n- Коли `payerType` має значення `ThirdPerson`. Воно повинно містити номер договору платника. Для клієнтів з України також дозволено передавати код ЄДРПОУ замість номера договору.\n- Коли `payerType` має значення `Sender` або `Recipient` і використовується безготівковий спосіб оплати.\n\nЯкщо це поле не передано у зазначених випадках, спосіб оплати автоматично буде встановлений як готівковий.\n\nПереконайтеся, що надана інформація є коректною, оскільки вона необхідна для правильної обробки платежу.\n\nДетальніше див. статтю [Оплата послуг доставки через API Nova Post](https://api-portal.novapost.com/en/api-methods/payment/).\n","minLength":2,"maxLength":20,"nullable":true},"services":{"type":"array","description":"Містить інформацію про додаткові послуги для відправлення.","properties":{"shipmentParcelRowNumber":{"type":"integer","nullable":true,"description":"Вказує номер рядка посилки, до якої застосовується послуга. Значення має відповідати `rowNumber` існуючої посилки в масиві `parcels`.\nДля послуг, що застосовуються до **всього відправлення** (наприклад, `ExpBackwardGoods`), це поле повинно мати значення `null`."},"serviceCode":{"type":"string","description":"Код, що визначає послугу.\n**Перелік доступних кодів та їх значень:**\n- `COD` — Послуга накладеного платежу (COD) дозволяє одержувачу оплатити товар безпосередньо при отриманні без необхідності передоплати. Відправник може додати цю послугу до відправлення, а одержувач має можливість оплатити товар під час доставки та оглянути його перед оплатою, з урахуванням обмежень способів оплати, встановлених для конкретних країн. Доступні напрямки:\n- Польща → Україна\n- Чехія → Україна\n- Німеччина → Україна\n- Словаччина → Україна\n- Чехія → Чехія\n- Польща → Польща\n- Німеччина → Німеччина\n- Румунія → Молдова\n\n🔸**Послуга COD планується до розширення на інші країни та напрямки доставки в майбутньому, як для міжнародних відправлень, так і в межах європейських країн.**\n\n- `ExpBackwardGoods` — Дозволяє оформити зворотну доставку для основного відправлення\n- `ExpBackwardCreditDoc` — Дозволяє оформити зворотну доставку підписаних документів для внутрішніх відправлень документів у Молдові. Послуга доступна лише для юридичних осіб і лише для відправлень типу **Documents**. Зворотне відправлення створюється як окрема доставка документів (кур'єром або оператором), і платником завжди є Одержувач за безготівковим договором. Недоступна для каналів Parcel Locker та PUDO. На першому етапі послуга доступна лише для обраних юридичних осіб.\n\n🔹**Це поле є обов’язковим для групи `services`.**\n"},"serviceName":{"type":"string","description":"Назва послуги.\n\nДопустимі значення включають:\n\n- `PaymentControl` — послуга контролю оплати.\n- `MoneyTransfer` — послуга грошового переказу.\n- Інші типи послуг, доступні в групі `services`.\n\n🔹**Це поле є обов’язковим у межах групи `services`.**\n"},"serviceId":{"type":"string","description":"Унікальний ідентифікатор (reference ID) обраної послуги.\n\nЦе значення має відповідати ідентифікатору послуги, який повертається системою.\nПри створенні або оновленні відправлення необхідно скопіювати та використати точне значення `serviceId`, отримане у відповіді довідника послуг, без змін.\n\n🔹**Це поле є обов’язковим у межах групи `services`.**\n"},"amount":{"type":"number","description":"Загальна сума, яку одержувач має сплатити в рамках послуги COD.\n\n🔹**Це поле є обов’язковим для групи `services`.**\n"},"contractNumber":{"type":"string","nullable":true,"description":"Номер договору платника, відповідального за обрану послугу.\nЦей параметр використовується для ідентифікації договору, в рамках якого здійснюється оплата послуги.\n\nПоле є обов’язковим, якщо платником послуги виступає **третя сторона** або використовується безготівкова форма оплати. Якщо поле не передано, оплата може бути оброблена відповідно до стандартних правил білінгу.\n"},"payerType":{"type":"string","description":"Визначає, хто відповідає за оплату послуги. Тип платника визначає сторону, яка покриває витрати:\n\n- `Recipient` — єдине допустиме значення для послуги COD.\n- `Sender`, `Recipient` — допустимі значення для послуги ExpBackwardGoods.\n- `Sender`, `Recipient`, `ThirdPerson` — допустимі значення для послуги BackwardDelGoods.\n\n**🔻Це поле є обов’язковим**\n"},"additionalParameters":{"type":"string","description":"Додаткові параметри для послуги.","properties":{"cod":{"type":"string","description":"Додаткові параметри для налаштування COD.\n\n🔹**Ці параметри є обов’язковими та застосовуються лише для послуги COD**\n","properties":{"bankAccount":{"type":"object","description":"Інформація про банківський рахунок, на який буде здійснено переказ коштів. Включає суму переказу, валюту операції, ідентифікатори рахунку та сторону, яка сплачує комісію.","properties":{"amount":{"type":"number","description":"Сума, яка буде перерахована на рахунок відправника після оплати. Визначає суму, яку одержувач має сплатити при отриманні. Можлива автоматична конвертація валюти залежно від країни відправника або одержувача.\n\n🔹**Це поле є обов’язковим для групи `services.additionalParameters.cod.bankAccount`.**\n"},"currencyCode":{"type":"string","description":"Валюта транзакції, визначена договором відправника.\nВказується відповідно до стандарту ISO 4217.\n\n🔸**За замовчуванням використовується валюта країни відправника, але можливе ручне встановлення (функціонал у розробці).**\n**Pattern:** ^[A-Z]{3}$\n"},"bankAccountId":{"type":"string","description":"Ідентифікаційний код фізичної або юридичної особи, який використовується для її унікальної ідентифікації в системі та перевірки наявності активного договору і фінансових послуг. Аналогічний значенню, що передається у полі `companyTin`.\n\n🔹**Це поле є обов’язковим для групи `services.additionalParameters.cod.bankAccount`.**\n\n🔸**Має містити податковий номер або аналогічний ідентифікатор (ЄДРПОУ, TIN, NIP).**\n"},"bankAccountName":{"type":"string","description":"IBAN\n\n🔹**Це поле є обов’язковим для групи `services.additionalParameters.cod.bankAccount`.**\n\n🔸**Має містити повний номер рахунку у форматі IBAN.**\n"},"description":{"type":"string","description":"Додатковий опис платіжних реквізитів.\n"},"commissionPayer":{"type":"string","description":"Визначає сторону, яка сплачує комісію:\n- `Recipient`\n- `Sender`\n\n🔹**Це поле є обов’язковим для групи `services.additionalParameters.cod.bankAccount`.**\n"}}}}},"backwardDelivery":{"type":"array","description":"Додаткові параметри для налаштування зворотної доставки.\n\n🔹**Ці параметри є обов’язковими та застосовуються лише для послуги ExpBackwardGoods**\n","items":{"type":"object","properties":{"description":{"type":"string","description":"Опис товарів, що підлягають поверненню.\nЦе значення використовується для інформаційних та операційних цілей під час процесу зворотної доставки.\n"}}}}}}}},"invoice":{"type":"object","description":"Цей об’єкт містить необхідні дані для митних органів для ефективної обробки відправлення, включаючи розрахунок мит та податків, а також підтвердження відповідності імпортно-експортним вимогам. Структурований формат інвойсу забезпечує легкий доступ до всієї необхідної інформації, що сприяє більш швидкому проходженню через кордон.\n\nОновлена логіка обробки значень інвойсу.\nКлієнти повинні передавати лише два параметри в об’єкті invoice:\n  - `cost` — загальна задекларована вартість інвойсу\n  - `currency` — код валюти інвойсу\n  \n  **🔸Містить деталі інвойсу, які є обов’язковими для міжнародних відправлень, що проходять митне оформлення.**\n","properties":{"customerNumber":{"type":"string","description":"Унікальний ідентифікатор/номер інвойсу, що супроводжує товари у відправленні, який генерується безпосередньо клієнтом. Використовується для митного оформлення (експорт та імпорт), оскільки забезпечує чіткий зв’язок між товарами у відправленні та супровідною документацією, включаючи вартість, походження та інші необхідні дані.\n\nЯкщо інвойс у відправленні існує, але його дані відсутні — зокрема, його номер — обробка відправлення в інформаційній системі буде призупинена, термін митного оформлення збільшиться, а в гіршому випадку митні органи можуть відмовити в оформленні та ініціювати повернення в країну відправлення.\n","maxLength":50,"nullable":true},"customerCreatedAt":{"type":"string","format":"date-time","description":"Необхідно передати дату, вказану в інвойсі, що супроводжує відправлення.\nЯкщо дата відсутня у документі клієнта, можна використати дату створення відправлення.\n\n**🔹Це поле є обов’язковим, якщо заповнено поле `invoice.customerNumber`.**\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$"},"type":{"type":"string","description":"Тип інвойсу клієнта, що супроводжує відправлення та використовується для митного декларування.\nЦе поле повинно відповідати фактичному типу документа, вкладеного у відправлення.\nДоступні значення:\n\n- `Invoice` — комерційний інвойс для відправлень комерційного характеру\n- `ProformaInvoice` — проформа-інвойс для відправлень некомерційного характеру\n\n**🔹Це поле є обов’язковим, якщо заповнено поле `invoice.customerNumber`.**\n","enum":["Invoice","ProformaInvoice"]},"incoterm":{"type":"string","description":"Визначає умови поставки між продавцем і покупцем відповідно до правил Incoterms®. Ці умови регулюють розподіл витрат на доставку, страхування, митні платежі та ризики. Доступний обмежений набір значень:\n- DAP (Delivered at Place) - Одержувач відповідає за митне оформлення імпорту, сплату мит та податків.\n- DDP (Delivered Duty Paid) - Відправник відповідає за митне оформлення імпорту та оплату всіх мит і податків.\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n","enum":["DAP","DDP"]},"exportReason":{"type":"string","description":"Визначає загальну причину експорту товарів, що є необхідною для митних та інших регуляторних органів. Класифікація дозволяє визначити тип відправлення без деталізації. Використовується для спрощення обробки на митниці. Доступні значення:\n- ForPersonalPurposes: Товари для особистого використання або подарунки.\n- Selling: Товари призначені для продажу.\n- Repair: Товари відправляються на ремонт.\n- Return: Товари повертаються відправнику або виробнику.\n- Other: Інша причина, не зазначена вище.\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n","enum":["ForPersonalPurposes","Selling","Repair","Return","Other"]},"cost":{"type":"number","description":"Загальна задекларована вартість інвойсу у вихідній валюті, яка повинна дорівнювати сумі всіх позицій інвойсу, розрахованій як **(amount × cost)** для кожного товару. Використовується для митного декларування.\n\n**🔸Якщо передане значення `cost` не дорівнює сумі значень у масиві `items`, воно буде автоматично перераховане системою.**\n\n**🔸Значення перевіряються на точність десяткових знаків, і цифри після другого знака після коми ігноруються.**\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n","minimum":0,"maximum":9999999.99},"currency":{"type":"string","description":"Код валюти інвойсу відповідно до стандарту ISO 4217. Усі товари в інвойсі повинні бути в одній валюті.\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n","pattern":"^[A-Z]{3}$"},"payerFeesCustoms":{"type":"string","description":"Визначає, хто оплачує митні послуги. Параметр визначає сторону, яка покриває витрати:\n- Sender: Відправник оплачує митні платежі.\n- Recipient: Одержувач оплачує митні платежі.\n- ThirdPerson: Третя сторона може оплачувати митні послуги лише за умови, що це дозволено і платник за доставку також є третьою стороною.\n\nЗначення за замовчуванням — **\"Recipient\"**.</br>\nЦе значення також буде застосовано автоматично, якщо вартість відправлення перевищує максимально допустиму (у валюті країни одержувача), при якій відправник може оплачувати митні платежі.\n\n**🔹Цей параметр є обов’язковим і застосовується лише для напрямку UA-EU.**\n","enum":["Sender","Recipient","ThirdPerson"]},"items":{"type":"array","description":"Деталізований перелік товарів, що відправляються, включаючи обов’язкові описи та значення, необхідні для митного декларування та розрахунку митних платежів.\n\n**Логіка:** Якщо блок items передано, система перевіряє, чи дорівнює загальна сума всіх (`items.cost` × `items.amount`) значенню `invoice.cost`. Якщо ні — система оновлює `invoice.cost`, щоб вона дорівнювала сумі всіх товарів.\n\n**🔸Необхідно передавати інформацію для кожного окремого товару у відправленні у вигляді масиву.**\n","items":{"type":"object","properties":{"id":{"type":"string","description":"Унікальний ідентифікатор кожного товару у відправленні.\n\n**🔹Це поле є необов’язковим.**\n"},"hsCode":{"type":"string","description":"Код Гармонізованої системи (HS code) для кожного товару — стандартизований числовий метод класифікації товарів у міжнародній торгівлі.\nЦе поле є обов’язковим для міжнародних відправлень, що проходять митне оформлення. Отримати коректний `hsCode` можна з довідника Класифікаторів вантажів (UKT ZED).\nПравила валідації:\n- **Якщо країна відправника або отримувача — Молдова (MD) або Канада (CA):**\n  - `hsCode` повинен складатися рівно з 10 цифрових символів.\n  - Якщо значення містить більше ніж 10 цифр, воно буде **скорочено** праворуч.\n  - Якщо значення містить менше ніж 10 цифр — помилка валідації.\n- **Для всіх інших країн:**\n  - `hsCode` повинен містити **від 8 до 10 цифрових символів** (включно).\n  - Якщо значення містить менше ніж 8 цифр — помилка валідації.\n- **Усі нецифрові символи автоматично видаляються перед валідацією.** \n- **Якщо значення поля `hsCode` дорівнює `210690` або `630900`, повинні виконуватися наступні умови:**\n  - `measurementCode` повинен бути встановлений у значення `kg`.\n  - Кожен товар із таким `hsCode` повинен бути унікальним — інвойс не може містити більше одного товару з кодом `210690` або `630900`.\n  - Значення кількості не повинно перевищувати 10.\n  \n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або прямують за межі ЄС.**\n","maxLength":255,"nullable":true},"name":{"type":"string","description":"Назва товару локальною мовою, що забезпечує точний опис для митного оформлення та логістичного планування. Назва повинна відповідати термінам з довідника Cargo Classifiers (UKT ZED), що гарантує відповідність стандартним класифікаційним кодам. Детальний опис допомагає точно ідентифікувати товар під час митного оформлення.\nЦе поле підтримує Unicode-кодування, що дозволяє використовувати спеціальні символи через формат \\uXXXX. Це забезпечує точне відображення назв товарів мовами з нелатинськими символами, підвищуючи зрозумілість у різних регуляторних середовищах.\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n","maxLength":512},"nameEng":{"type":"string","description":"Назва товару англійською мовою, що забезпечує його зрозумілість у міжнародній торгівлі та логістиці. Полегшує комунікацію з міжнародними партнерами та органами.\nАналогічно полю `name`, підтримує Unicode-кодування через формат \\uXXXX.\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n","maxLength":512},"material":{"type":"string","description":"Основний матеріал, з якого виготовлено товар, важливий для митного декларування та можливих обмежень.\n\n**🔸Якщо поле не передано, буде застосовано значення за замовчуванням.**\n","maxLength":50},"materialEng":{"type":"string","description":"Опис матеріалу товару англійською мовою, що забезпечує універсальне розуміння його складу.\n\n**🔸Якщо поле не передано, буде застосовано значення за замовчуванням.**\n","maxLength":255},"madeInCountryCode":{"type":"string","description":"Код країни виробництва за стандартом ISO 3166-1 alpha-2, необхідний для визначення митних платежів та дотримання торговельних угод.\n\n**🔸Поле не є обов’язковим, але відправлення з цим полем мають пріоритет під час митного оформлення.**\n","pattern":"^[A-Z]{2}$","nullable":true},"producerAndModel":{"type":"string","description":"Параметр містить виробника та модель пристрою в одному полі. Обов’язковий для таких категорій:\n- Електроніка\n- Ноутбуки\n- Телефони\n- Побутова техніка\n- Інші подібні товари\n\n**🔸Поле не є обов’язковим, але відправлення з ним мають пріоритет під час митного оформлення.**\n","maxLength":255,"nullable":true},"actualWeight":{"type":"integer","description":"Фактична загальна вага всіх одиниць товару в грамах (g).\n\nПідтримувана точність: 10 грам (0.01 кг).\nЗначення, що не кратні 10 г, округлюються вниз до найближчого меншого кратного.\n\n**🔸Це поле є обов’язковим, якщо передано масив** `invoice.items`.</br>\nСистема перевіряє, що сума `actualWeight` по всіх товарах дорівнює загальній вазі відправлення (`parcels[].actualWeight`).\n\n⚠️ВАЖЛИВО: Переконайтесь, що всі ваги коректно округлені і їх сума точно дорівнює вазі відправлення.\n","minimum":1,"maximum":2147483647,"nullable":true},"measurementCode":{"type":"string","description":"Одиниця виміру кількості товару (наприклад, штуки, кілограми, метри тощо), що стандартизує спосіб зазначення кількості.\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n","maxLength":255},"amount":{"type":"number","description":"Кількість товару, що відправляється, у відповідних одиницях виміру (`measurementCode`).\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n","minimum":0,"maximum":9999999.99},"cost":{"type":"number","description":"Вартість за одиницю товару у валюті відправника.\n\n**🔸Значення перевіряються на точність десяткових знаків, і цифри після другого знака після коми ігноруються.**\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n","minimum":0,"maximum":9999999.99}}}}}},"parcels*":{"type":"array","description":"Блок опису посилок. Масив містить об’єкти, кожен з яких відповідає за інформацію про окрему посилку.\n\n**🔻Усі поля в цьому масиві є обов’язковими для заповнення.**\n","items":{"type":"object","properties":{"cargoCategory*":{"type":"string","description":"Визначає тип відправлення, що використовується для класифікації товарів у логістиці та митному оформленні. Категорія впливає на обробку відправлення, вартість доставки та необхідну документацію. Доступні категорії:\n  - parcel: Невеликі та середні посилки, зазвичай для споживчих товарів.\n  - documents: Поштові відправлення з документами (листи, контракти, офіційні папери). Обмеження: вага до 1 кг, розміри — не більше 35 × 25 × 2 см.\n  - pallet: Вантаж у вигляді палети з фіксованими розмірами та ваговими обмеженнями (доступно для юридичних осіб у Business Cabinet Europe):\n    - До 250 кг, площа ~0.48 м², розміри 80 × 60 × 170 см\n    - До 500 кг, площа ~0.96 м², розміри 120 × 80 × 170 см\n    - До 750 кг, площа ~1.2 м², розміри 120 × 100 × 170 см\n    - До 1000 кг, площа ~1.2 м², розміри 120 × 100 × 170 см\n","enum":["parcel","documents","pallet"]},"parcelDescription*":{"type":"string","description":"Короткий опис вмісту посилки, що містить основну інформацію про характер вкладення. Використовується для логістики та митного оформлення.\nОпис повинен включати тип товарів, їх призначення та інші важливі деталі. Це поле підтримує Unicode-кодування (\\uXXXX), що дозволяє використовувати спеціальні символи та нелатинські алфавіти.\n","maxLength":255},"insuranceCost*":{"type":"number","format":"float","description":"Задекларована вартість відправлення для страхування. Визначає максимальну суму компенсації у разі втрати або пошкодження.\n\n**Обробка валюти:**\n- Якщо `insuranceCurrencyCode` **не передано**, значення повинно бути у валюті країни відправника.\n- Якщо `insuranceCurrencyCode` **передано**, значення може бути в будь-якій підтримуваній валюті (ISO 4217), система автоматично конвертує її.\n\n🔸 **Якщо використовується `insuranceCurrencyCode`, всі посилки повинні мати однаковий код валюти. Інакше — помилка валідації.**\n\n**Значення завжди повинно бути більше 0 незалежно від напрямку відправлення.**\"\n","minimum":1,"exclusiveMinimum":true},"insuranceCurrencyCode":{"type":"string","description":"Код валюти ISO 4217 для страхувальної вартості (`insuranceCost`). \n\n- Якщо поле передано — система автоматично конвертує значення у валюту країни відправника. \n- Якщо використовується — всі посилки повинні мати однаковий код валюти.\n\n🔹**Це поле є необов’язковим.**\"\n","pattern":"^[A-Z]{3}$"},"rowNumber*":{"type":"integer","description":"Порядковий номер посилки у відправленні. Якщо посилка одна — значення має бути 1.","minimum":1},"width*":{"type":"integer","description":"Ширина посилки в міліметрах. Використовується разом з довжиною та висотою для розрахунку об’єму.","minimum":1},"length*":{"type":"integer","description":"Довжина посилки в міліметрах. Використовується разом з шириною та висотою для розрахунку об’єму.","minimum":1},"height*":{"type":"integer","description":"Висота посилки в міліметрах. Використовується разом з довжиною та шириною для розрахунку об’єму.","minimum":1},"actualWeight*":{"type":"integer","description":"Фактична вага посилки у грамах (g).\n\nПідтримувана точність: 10 грам (0.01 кг).\nЗначення, що не кратні 10 г, округлюються вниз.\n\n**🔸Це поле є обов’язковим, якщо передано масив** `invoice.items`.</br>\nСистема перевіряє, що сума `actualWeight` по всіх товарах дорівнює загальній вазі відправлення (`parcels[].actualWeight`).\n\n⚠️ВАЖЛИВО: Переконайтесь, що вага всіх товарів співпадає із загальною вагою посилок.\"\n","minimum":1,"maximum":2147483647}}}},"sender*":{"type":"object","description":"Інформація про відправника, включаючи дані про фізичну або юридичну особу, відповідальну за відправлення.\n\n**🔻Цей набір полів є обов’язковим**\n","properties":{"companyTin":{"type":"string","description":"Податковий номер або аналогічний ідентифікатор юридичної особи (EDRPOU, TIN, NIP, IČO — для Словаччини).\n\n**🔸Ці поля є обов’язковими для юридичної особи. Якщо вони не заповнені — відправник вважається фізичною особою**\n","maxLength":20,"nullable":true},"companyName":{"type":"string","description":"Офіційна назва компанії відправника. Використовується, якщо відправник є юридичною особою, для ідентифікації організації в документах та системі.","maxLength":100,"nullable":true},"eoriCode":{"type":"string","description":"Код EORI (Economic Operators Registration and Identification) використовується в Європейському Союзі для ідентифікації суб'єктів зовнішньоекономічної діяльності. Рекомендується для міжнародних відправлень до ЄС для коректного митного оформлення та уникнення затримок.","minLength":3,"maxLength":17,"nullable":true},"phone*":{"type":"string","description":"Контактний номер телефону відправника або представника компанії.\nВикористовується для комунікації щодо відправлення (забір, уточнення, проблемні ситуації).\n\n**Формат:** Номер повинен бути у **міжнародному форматі** відповідно до стандарту **E.164**.\n\nПриклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX\n\n**Обмеження:**\n- Номер повинен бути дійсним і доступним для зв’язку.\n- Якщо номер передано у локальному форматі, система спробує **нормалізувати** його, але така логіка обмежена.\nРекомендується реалізувати **front-end валідацію** для перевірки формату.\n\n**🔻Це поле є обов’язковим**\n"},"email":{"type":"string","description":"Email-адреса відправника для отримання повідомлень, оновлень та комунікації щодо відправлення.\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.**\n"},"name*":{"type":"string","description":"Повне ім’я відправника або контактної особи компанії. Використовується у всіх документах і комунікації.\n\n**🔸Важливо для міжнародних відправлень EU → UA:**\nІм’я має бути вказане **виключно латиницею**.\nВикористання кирилиці (включаючи українські літери) **заборонено** та призведе до помилки обробки на стороні Last Mile партнера.\n\n**🔻Це поле є обов’язковим**\n","maxLength":100},"ioss":{"type":"string","description":"Номер IOSS (Import One-Stop Shop) — необов’язковий параметр, який використовується для спрощення процесу декларування ПДВ для відправлень із країн, що не входять до ЄС, із задекларованою вартістю до 150 євро. Актуально для відправлень з країн поза ЄС до ЄС.","maxLength":12,"pattern":"/^[a-zA-Z0-9]*$/u"},"countryCode*":{"type":"string","description":"Дволітерний код країни відправника згідно стандарту ISO 3166-1 Alpha-2.\n\n**🔻Це поле є обов’язковим**\n","pattern":"^[A-Z]{2}$"},"divisionNumber":{"type":"string","description":"Обов’язкове поле, якщо відправлення здійснюється з відділення або поштомату. Містить унікальний номер відділення.\n\n**🔹Це поле є обов’язковим, якщо відсутні `sender.addressParts` та `sender.divisionID`**\n","nullable":true},"divisionID":{"type":"integer","description":"Ідентифікатор відділення для точного визначення локації.\n\n**🔹Це поле є обов’язковим, якщо відсутні `sender.addressParts` та `sender.divisionNumber`**\n","minimum":1,"nullable":true},"addressParts":{"type":"object","description":"Цей набір полів є обов’язковим при відправленні безпосередньо з адреси. Він містить детальні компоненти місця, з якого здійснюється відправлення, забезпечуючи точну ідентифікацію локації забору.\n","properties":{"city":{"type":"string","description":"Назва міста, з якого здійснюється відправлення. Використовується для точного визначення населеного пункту для забору або відправлення.\n\n**🔹Це поле є обов’язковим, якщо** `sender.divisionNumber` **та** `sender.divisionID` **відсутні або порожні.**</br>\n🔸Для відправлень, де країна відправника — **Молдова** або **Україна**, значення міста перевіряється за внутрішніми довідниками населених пунктів. Якщо значення не може бути зіставлене з жодним населеним пунктом, створення відправлення буде відхилено.\n","maxLength":100},"region":{"type":"string","description":"Визначає ширшу адміністративну одиницю (наприклад, штат або область), до якої належить місто, надаючи додатковий контекст для місця відправлення.\n\n**🔹Це поле є обов’язковим для відправлень, якщо країна відправника або отримувача — США, Ірландія або Канада.**\n","maxLength":100},"street":{"type":"string","description":"Назва вулиці за адресою відправника, необхідна для точного визначення місця забору або доставки.\n\n**🔹Це поле є обов’язковим, якщо** `sender.divisionNumber` **та** `sender.divisionID` **відсутні або порожні.**\n","maxLength":100},"postCode":{"type":"string","description":"Поштовий індекс (ZIP-код), що відповідає адресі відправника. Використовується для сортування та маршрутизації відправлення.\n\n**🔹Це поле є обов’язковим, якщо** `sender.divisionNumber` **та** `sender.divisionID` **відсутні або порожні.**\n","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі за вказаною адресою, що дозволяє точно ідентифікувати місце забору.\n\n**🔹Це поле є обов’язковим, якщо** `sender.divisionNumber` **та** `sender.divisionID` **відсутні або порожні.**\n","maxLength":100},"flat":{"type":"string","description":"Номер квартири, офісу або приміщення в межах будівлі, якщо це застосовно, для точної ідентифікації місця відправлення.","maxLength":10},"block":{"type":"string","description":"Позначає блок або секцію в межах житлового комплексу чи великої території (за наявності), допомагаючи точніше визначити місце відправлення.","maxLength":100,"nullable":true},"note":{"type":"string","description":"Дозволяє вказати додаткову інформацію або інструкції щодо адреси відправника (наприклад, код домофона, вхід, бажаний час контакту), які можуть полегшити процес забору.","maxLength":100}}}}},"recipient*":{"type":"object","description":"Інформація про отримувача відправлення, що містить дані про фізичну або юридичну особу, відповідальну за отримання вантажу.\n\n**🔻Цей набір полів є обов’язковим**\n","properties":{"companyTin":{"type":"string","description":"Податковий номер або еквівалентний ідентифікатор юридичної особи (EDRPOU, TIN, NIP, IČO — для Словаччини).\n\n**🔸Ці поля є обов’язковими для юридичної особи. Якщо вони не заповнені — отримувач вважається фізичною особою**\n","maxLength":20,"nullable":true},"companyName":{"type":"string","description":"Офіційна назва компанії отримувача. Використовується, якщо отримувач є юридичною особою, для ідентифікації організації у документах та системі.","maxLength":100,"nullable":true},"eoriCode":{"type":"string","description":"Код EORI отримувача є важливим для митного оформлення при доставці до країн Європейського Союзу, особливо для юридичних осіб. Код не є обов’язковим, але рекомендований, оскільки сприяє швидшому митному оформленню та зменшує ризик затримок. Вимога залежить від типу товарів:\n\n1. Неакцизні товари: код EORI не є обов’язковим при доставці з України юридичній особі в Європі. Якщо код відсутній — він буде присвоєний автоматично.\n2. Акцизні товари: код EORI є обов’язковим. Отримувач повинен отримати його до здійснення відправлення.\n","minLength":3,"maxLength":17,"nullable":true},"phone*":{"type":"string","description":"Контактний номер телефону отримувача або представника компанії. \nВикористовується для повідомлень про доставку та комунікації під час обробки відправлення.\n\n**Формат:** номер повинен бути у **міжнародному форматі** відповідно до стандарту **E.164**.\n\nПриклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX\n\n**Обмеження:**\n- Для доставки у відділення Nova Post в Європі допускаються українські мобільні номери.\n- Для доставки у **партнерські точки** (InPost, GLS, Venipak, Cargus тощо) та **міжнародної адресної доставки** номер повинен належати мобільному оператору країни отримувача. Якщо номер передано у локальному (неміжнародному) форматі, система спробує **нормалізувати** його до міжнародного формату, але внутрішній алгоритм не охоплює всі можливі варіанти. Якщо ваша система не підтримує front-end валідацію телефонних номерів, рекомендується повідомляти про некоректні кейси для можливого вдосконалення логіки нормалізації.\n\n**🔻Це поле є обов’язковим**\n"},"email":{"type":"string","description":"Email-адреса отримувача, що використовується як цифровий канал зв’язку для отримання оновлень, повідомлень та важливої інформації щодо відправлення.\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або здійснюються за його межами.**\n"},"name*":{"type":"string","description":"Повне ім’я отримувача або основної контактної особи компанії. Це ім’я використовується у всій документації та комунікації, пов’язаній із відправленням.\n\n**🔸Важливо для міжнародних відправлень EU → UA:**\nІм’я має бути вказане **виключно латиницею**.\nВикористання кирилиці (включаючи українські літери) **заборонено** та призведе до помилок обробки.\n\n**🔻Це поле є обов’язковим**\n","maxLength":100},"countryCode*":{"type":"string","description":"Дволітерний код країни отримувача відповідно до стандарту ISO 3166-1 Alpha-2, який визначає країну призначення відправлення.\n\n**🔻Це поле є обов’язковим**\n","pattern":"^[A-Z]{2}$"},"divisionNumber":{"type":"string","description":"Це поле є обов’язковим для посилок, що мають бути отримані у відділенні або поштоматі, та містить унікальний ідентифікатор відповідної локації.\n\n**🔹Це поле є обов’язковим, якщо обидва поля `recipient.addressParts` та `recipient.divisionID` відсутні або порожні**\n","nullable":true},"divisionID":{"type":"integer","description":"Ідентифікатор відділення для точного визначення конкретної точки отримання.\n\n**🔹Це поле є обов’язковим, якщо обидва поля `recipient.addressParts` та `recipient.divisionNumber` відсутні або порожні**\n","minimum":1,"nullable":true},"addressParts":{"type":"object","description":"Цей набір полів використовується у випадках доставки за конкретною адресою та містить детальні компоненти місця доставки, забезпечуючи точну ідентифікацію локації отримання.\n\n**🔸Значення вкладених полів не повинні дублювати одне одного. Надання однакової інформації у кількох внутрішніх полях призведе до помилки.**\n","properties":{"city":{"type":"string","description":"Назва міста, до якого здійснюється доставка. Це поле забезпечує точне визначення населеного пункту отримувача.\n\n**🔹Це поле є обов’язковим, якщо** `recipient.divisionNumber` **та** `recipient.divisionID` **відсутні або порожні.**</br>\n🔸Для відправлень, де країна отримувача — **Молдова** або **Україна**, значення міста перевіряється за внутрішніми довідниками населених пунктів. Якщо значення не може бути зіставлене з жодним записом, запит буде відхилено з помилкою:`validation.condition.recipient_settlement_not_defined`.\n","maxLength":100},"region":{"type":"string","description":"Визначає адміністративну одиницю (штат, область або провінцію), до якої належить місто отримувача. Це поле є критично важливим для точної маршрутизації відправлення.\n\n**🔹Це поле є обов’язковим для відправлень, якщо країна відправника або отримувача — США, Ірландія або Канада.**\n","maxLength":100},"street":{"type":"string","description":"Назва вулиці за адресою отримувача, необхідна для точного визначення місця доставки.\n\n**🔹Це поле є обов’язковим, якщо** `recipient.divisionNumber` **та** `recipient.divisionID` **відсутні або порожні.**\n","maxLength":100},"postCode":{"type":"string","description":"Поштовий індекс (ZIP-код), що відповідає адресі отримувача. Використовується для сортування та маршрутизації відправлення до кінцевої точки.\n\n**🔹Це поле є обов’язковим, якщо** `recipient.divisionNumber` **та** `recipient.divisionID` **відсутні або порожні.**\n","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі за адресою отримувача, що дозволяє точно ідентифікувати місце доставки.\n\n**🔹Це поле є обов’язковим, якщо** `recipient.divisionNumber` **та** `recipient.divisionID` **відсутні або порожні.**\n","maxLength":100},"flat":{"type":"string","description":"Номер квартири або офісу, якщо доставка здійснюється до будівлі з кількома приміщеннями.","maxLength":10},"block":{"type":"string","description":"Ідентифікує корпус або секцію в межах великого комплексу чи житлового масиву для адреси отримувача.","maxLength":100,"nullable":true},"note":{"type":"string","description":"Дозволяє вказати додаткові інструкції або деталі щодо адреси отримувача (наприклад, код домофона, особливості доступу, бажаний час доставки), що можуть полегшити процес доставки.","maxLength":100}}},"registrationAddressRecipient":{"type":"object","description":"Об’єкт registrationAddressRecipient надає детальний опис зареєстрованої адреси отримувача та є обов’язковим при доставці до країн із підвищеними вимогами до митного оформлення, таких як Німеччина, Словаччина, Угорщина та Франція.\nЦе забезпечує відповідність локальним регуляторним вимогам і сприяє коректному та безперешкодному проходженню митного контролю.\n","properties":{"city":{"type":"string","description":"Назва міста, де зареєстрований отримувач. Повинна відповідати локальним правилам найменування.\n\n**🔹Це поле є обов’язковим для відправлень до країн із підвищеними вимогами до митного оформлення (DE, SK, HU, FR).**\n","maxLength":100},"street":{"type":"string","description":"Назва вулиці зареєстрованої адреси отримувача. Повинна відповідати локальним стандартам адресації.\n\n**🔹Це поле є обов’язковим для зазначених країн.**\n","maxLength":100},"zipCode":{"type":"string","description":"Поштовий індекс зареєстрованої адреси отримувача.\n\n**🔹Це поле є обов’язковим для зазначених країн.**\n","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі, в якій зареєстрований отримувач.\n\n**🔹Це поле є обов’язковим для зазначених країн.**\n","maxLength":100},"apartment":{"type":"string","description":"Номер квартири або офісу в межах будівлі (за наявності).","maxLength":10},"state":{"type":"string","description":"Регіон або область реєстрації отримувача, використовується у країнах, де це є обов’язковим для точнішої ідентифікації.","maxLength":100}}}}}}}}}},"responses":{"201":{"description":"Відправлення успішно створено.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Унікальний ідентифікатор, що призначається кожному відправленню, який використовується для внутрішніх операцій, таких як модифікація, пошук у системі та видалення відправлень. Поле `id` слугує ключовим посиланням для адміністративних і логістичних процесів у системі доставки, забезпечуючи точний доступ і керування записами відправлень.\nФормат значення `id` залежить від напрямку відправлення (first/last mile):\n- Для відправлень у Європі значення є числовим ідентифікатором (наприклад, `754116`), який використовується для пошуку.\n- Для відправлень в Україні значення є UUID (наприклад, `56abe014-451c-11f0-a1d5-48df37b921da`), який використовується для пошуку за `ref`.\n","minimum":1},"number":{"type":"string","description":"Номер транспортного документа, який надається клієнтам для відстеження та доступу до друкованих форм. Також використовується для пошуку відправлень у системі, забезпечуючи зручний спосіб моніторингу їхнього статусу. Хоча `number` використовується зовні для відстеження та документації, у деяких випадках він може застосовуватись і для внутрішньої ідентифікації, подібно до `id`.","pattern":"^[A-Z]{4}\\d{10}$"},"scheduledDeliveryDate":{"type":"string","format":"date-time","description":"Орієнтовна дата доставки, розрахована на основі маршруту та рівня сервісу. Може змінюватися залежно від логістичних та зовнішніх факторів. Дата у форматі ISO 8601.","nullable":true},"status":{"type":"string","description":"Поточний статус відправлення. Під час створення встановлюється значення \"ReadyToShip\", що означає готовність до відправки."},"cost":{"type":"number","format":"float","description":"Загальна вартість послуг доставки, розрахована на основі розміру, ваги, напрямку та обраних сервісів."},"parcelsAmount":{"type":"integer","description":"Загальна кількість місць (посилок) у відправленні. Використовується для планування логістики та відстеження.","minimum":1},"createdAt":{"type":"string","format":"date-time","description":"Дата та час створення запису відправлення в системі. Формат ISO 8601."},"updatedAt":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення відправлення. Використовується для відстеження змін. Формат ISO 8601."},"deletedAt":{"type":"string","format":"date-time","description":"Дата та час видалення або скасування відправлення. Якщо відправлення не скасовано — значення `null`.","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Створення Відправлення"}}}}
```

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

> Створює відправлення для повернення після доставки початкового замовлення.\
> Цей метод дозволяє клієнтам створити відправлення повернення після доставки — незалежно від того, хто здійснював останню милю (Нова Пошта або партнер).\
> \
> ℹ️ \*\*Інформація:\*\* \</br>\
> Повернення може бути створене лише якщо батьківське відправлення має статус \*\*Delivered\*\* та містить послугу \*\*AllowedLightReturn\*\*. \</br>\
> Поточний статус відправлення можна знайти у полі \`\\"items\\" → \\"statusCode\\"\` методу \[Список відправлень]\(<https://api.novapost.com/developers/index.html#get-/shipments).\\></br>\
> \*\*AllowedLightReturn\*\* визначає кількість днів, протягом яких отримувач може ініціювати повернення після доставки.\
> Внутрішньо система перевіряє кілька умов перед тим, як дозволити створення відправлення легкого повернення:\
> \
> \- Статус батьківського відправлення має бути одним із: \`Issued (9, 10, 11, 106)\`.\
> \- Система обчислює дозволений період повернення за такою логікою: \</br>\
> &#x20; \`finalDate = toTZ(parentShipment.RecipientDateTime) + returnDays + 1 day\`\</br>\
> &#x20; де returnDays береться з послуги AllowedLightReturn, а toTZ застосовує відповідний часовий пояс системи (наприклад, регіон ЄС).\
> \- Повернення може бути створене лише якщо поточний час (nowTZ) є меншим за finalDate.\
> \- Система також перевіряє, що для цього ж батьківського відправлення ще не було створено легке повернення.\
> \
> Якщо всі ці умови виконані, запит на створення повернення приймається; в іншому випадку система повертає помилку валідації з поясненням причини відмови.\
> \
> \*\*Як працює відправлення легкого повернення\*\*\
> \- Запит повинен містити один \*\*обов’язковий параметр\*\* — \`number\` (номер батьківського відправлення). \*\*Усі інші параметри є опціональними\*\*.\
> \- Клієнт може вказати валідне відділення або адресу безпосередньо для повернення.\
> \- Якщо \*\*опціональні параметри\*\* не вказані, їх значення автоматично наслідуються з батьківського відправлення.\
> \- Поведінка методу залежить від напрямку відправлення:\
> &#x20; \- Для напрямку \*\*UA-UA\*\*: метод працює для доставок у \*\*поштомат, PUDO або за адресою\*\*.\
> &#x20; \- Для напрямку \*\*EU-EU\*\*: метод працює для доставок у \*\*PUDO або за адресою\*\*. Не підтримується, якщо батьківське відправлення було доставлене у \*\*поштомат\*\*.\
> \- Якщо доставка батьківського відправлення була за адресою, створюється заявка на забір автоматично. \</br>Заявка на забір створюється лише якщо повернення не було відправлене з відділення.\
> \
> Після створення повернення система автоматично генерує накладну повернення.\
> Детальніше про створення батьківського відправлення дивіться у \[Створення Відправлення]\(<https://api.novapost.com/developers/index.html#post-/shipments)\\></br>\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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 годину у заголовку"}}},"paths":{"/shipments/light-return":{"post":{"tags":["Shipments"],"summary":"Створення відправлення для легкого повернення","description":"Створює відправлення для повернення після доставки початкового замовлення.\nЦей метод дозволяє клієнтам створити відправлення повернення після доставки — незалежно від того, хто здійснював останню милю (Нова Пошта або партнер).\n\nℹ️ **Інформація:** </br>\nПовернення може бути створене лише якщо батьківське відправлення має статус **Delivered** та містить послугу **AllowedLightReturn**. </br>\nПоточний статус відправлення можна знайти у полі `\\\"items\\\" → \\\"statusCode\\\"` методу [Список відправлень](https://api.novapost.com/developers/index.html#get-/shipments).</br>\n**AllowedLightReturn** визначає кількість днів, протягом яких отримувач може ініціювати повернення після доставки.\nВнутрішньо система перевіряє кілька умов перед тим, як дозволити створення відправлення легкого повернення:\n\n- Статус батьківського відправлення має бути одним із: `Issued (9, 10, 11, 106)`.\n- Система обчислює дозволений період повернення за такою логікою: </br>\n  `finalDate = toTZ(parentShipment.RecipientDateTime) + returnDays + 1 day`</br>\n  де returnDays береться з послуги AllowedLightReturn, а toTZ застосовує відповідний часовий пояс системи (наприклад, регіон ЄС).\n- Повернення може бути створене лише якщо поточний час (nowTZ) є меншим за finalDate.\n- Система також перевіряє, що для цього ж батьківського відправлення ще не було створено легке повернення.\n\nЯкщо всі ці умови виконані, запит на створення повернення приймається; в іншому випадку система повертає помилку валідації з поясненням причини відмови.\n\n**Як працює відправлення легкого повернення**\n- Запит повинен містити один **обов’язковий параметр** — `number` (номер батьківського відправлення). **Усі інші параметри є опціональними**.\n- Клієнт може вказати валідне відділення або адресу безпосередньо для повернення.\n- Якщо **опціональні параметри** не вказані, їх значення автоматично наслідуються з батьківського відправлення.\n- Поведінка методу залежить від напрямку відправлення:\n  - Для напрямку **UA-UA**: метод працює для доставок у **поштомат, PUDO або за адресою**.\n  - Для напрямку **EU-EU**: метод працює для доставок у **PUDO або за адресою**. Не підтримується, якщо батьківське відправлення було доставлене у **поштомат**.\n- Якщо доставка батьківського відправлення була за адресою, створюється заявка на забір автоматично. </br>Заявка на забір створюється лише якщо повернення не було відправлене з відділення.\n\nПісля створення повернення система автоматично генерує накладну повернення.\nДетальніше про створення батьківського відправлення дивіться у [Створення Відправлення](https://api.novapost.com/developers/index.html#post-/shipments)</br>\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["number"],"properties":{"number":{"type":"string","description":"Номер **батьківського відправлення**, для якого ініціюється повернення.\n\nЦей параметр є обов’язковим для створення повернення.\n"},"divisionId":{"type":"string","description":"Ідентифікатор відділення, яке буде обробляти повернення."},"senderPhone":{"type":"string","description":"Номер телефону відправника для відправлення повернення."},"addressParts":{"type":"object","description":"Структура, що описує адресу для забору або доставки.","properties":{"city":{"type":"string","description":"Назва міста для адреси забору або доставки."},"region":{"type":"string","description":"Регіон або адміністративна одиниця адреси."},"street":{"type":"string","description":"Назва вулиці адреси для забору або доставки."},"postCode":{"type":"string","description":"Поштовий індекс адреси для забору або доставки."},"building":{"type":"string","description":"Номер будівлі адреси для забору або доставки."},"flat":{"type":"string","description":"Номер квартири або офісу за вказаною адресою."},"block":{"type":"string","description":"Блок або секція адреси, якщо застосовується."},"note":{"type":"string","description":"Додаткова інформація або коментар до адреси (наприклад, під’їзд, поверх або коментар для доставки)."}}},"invoice":{"type":"object","description":"Цей об’єкт містить необхідні дані для митних органів для ефективної обробки відправлення, включаючи оцінку митних зборів і податків, а також підтвердження дотримання правил імпорту/експорту. Структурований формат інвойсу забезпечує легкий доступ до всієї необхідної інформації та її зрозумілість, що сприяє більш швидкому проходженню через кордон.","properties":{"customerNumber":{"type":"string","description":"Унікальний ідентифікатор інвойсу, наданий клієнтом, що відповідає товарам у відправленні.","maxLength":50,"nullable":true},"incoterm":{"type":"string","description":"Визначає умови торгівлі відповідно до правил Incoterms® (наприклад, DAP). Обов’язковий для міжнародних відправлень.","enum":["DAP"]},"exportReason":{"type":"string","description":"Причина експорту (ForPersonalPurposes, Selling, Repair, Return, Other).","enum":["ForPersonalPurposes","Selling","Repair","Return","Other"]},"cost":{"type":"number","description":"Загальна задекларована вартість інвойсу у вихідній валюті, яка повинна дорівнювати сумі всіх товарних позицій, розрахованих як **(amount × cost)** для кожної позиції.","minimum":1,"maximum":9999999.99},"currency":{"type":"string","description":"Код валюти інвойсу згідно ISO 4217. Усі позиції інвойсу повинні використовувати одну валюту.","pattern":"^[A-Z]{3}$"},"items":{"type":"array","description":"Детальний перелік товарів у відправленні, необхідний для митного оформлення.","items":{"type":"object","properties":{"id":{"type":"string","description":"Унікальний ідентифікатор товару в межах відправлення."},"hsCode":{"type":"string","description":"Код Гармонізованої системи для кожного товару (8–10 цифр)."},"name":{"type":"string","description":"Назва товару локальною мовою."},"nameEng":{"type":"string","description":"Назва товару англійською мовою."},"material":{"type":"string","description":"Основний матеріал товару."},"madeInCountryCode":{"type":"string","description":"Код країни виробництва відповідно до стандарту ISO 3166-1 alpha-2."},"actualWeight":{"type":"integer","description":"Фактична загальна вага всіх одиниць товару в грамах (g)."},"measurementCode":{"type":"string","description":"Одиниця виміру (наприклад, pcs, kg, m)."},"amount":{"type":"number","description":"Кількість товару, що відправляється, необхідна для обліку та митного оформлення."},"cost":{"type":"number","description":"Вартість однієї одиниці товару у валюті відправника, важлива для страхування та митної оцінки."}}}}}},"parcels":{"type":"array","description":"Parcels` — блок опису посилок.\nКожен об’єкт містить інформацію про одну посилку у відправленні.\n","items":{"type":"object","properties":{"cargoCategory":{"type":"string","enum":["parcel","documents","pallet"],"description":"Тип відправлення (посилка або документи)."},"parcelDescription":{"type":"string","description":"Короткий опис вмісту посилки."},"insuranceCost":{"type":"number","format":"float","description":"Оголошена страхова вартість посилки."},"rowNumber":{"type":"integer","description":"Порядковий ідентифікатор посилки у відправленні."},"width":{"type":"integer","description":"Ширина посилки в міліметрах."},"length":{"type":"integer","description":"Довжина посилки в міліметрах."},"height":{"type":"integer","description":"Висота посилки в міліметрах."},"actualWeight":{"type":"integer","description":"Фактична загальна вага всіх одиниць товару в грамах (g)."}}}}}}}}},"responses":{"200":{"description":"Successfully created Light Return shipment.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized request — invalid or missing authentication token.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}},"403":{"description":"Parent shipment is missing the AllowedLightReturn parameter.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}},"404":{"description":"Parent shipment not found or status not allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}},"422":{"description":"Parent shipment not found or status not allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}},"503":{"description":"Service unavailable or request timeout.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}}}}}}}
```

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

> Повертає статуси верифікації для міжнародних відправлень для напрямку UA→World («міжнародне відправлення з України у світ»).\
> Відповіді та помилки від основної системи проксируются без змін.\</br>\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/shipments/international/status":{"get":{"tags":["Shipments"],"summary":"Отримання статусу верифікації для відправлень UA→World","description":"Повертає статуси верифікації для міжнародних відправлень для напрямку UA→World («міжнародне відправлення з України у світ»).\nВідповіді та помилки від основної системи проксируются без змін.</br>\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","parameters":[{"in":"query","name":"refs[]","required":true,"description":"Масив референсів відправлень. Не повинен бути порожнім. Передається як повторювані параметри запиту. \nПриклад запиту: \nrefs[]=`38e4fe97-9484-11f0-903f-005056bd9e02`\n","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"in":"query","name":"state","required":true,"description":"Фільтр стану верифікації. Доступні значення: Order, Closed, allOrders.\n","schema":{"type":"string","enum":["Order","Closed","allOrders"]}}],"responses":{"200":{"description":"Список статусів верифікації","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"array","items":{"type":"object","properties":{"Ref":{"type":"string"},"State":{"type":"string","description":"наприклад: NotVerified, Verified, Rejected"},"Date":{"type":"string","format":"date-time"},"StatusOfInternationalExpressWaybill":{"type":"string","description":"Зрозумілий для користувача статус верифікації"},"Note":{"type":"string"},"ClosedDate":{"type":"string","format":"date-time"}}}},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/Time-out"}}}}}}
```

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

> Цей API-метод дозволяє розрахувати орієнтовну вартість доставки та термін доставки для вашого вантажу.\
> Вартість та термін доставки розраховуються на основі таких факторів, як вага, габарити, місце призначення та спосіб доставки.\
> Надавши необхідні дані про вантаж і відправлення, ви можете отримати орієнтовну вартість доставки товарів.\
> Відповідь зазвичай містить розраховану вартість та заплановану дату доставки на основі наданої інформації.\</br>\
> \
> 🔹\*\*Description of control elements:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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":{"/shipments/calculations":{"post":{"tags":["Shipments"],"description":"Цей API-метод дозволяє розрахувати орієнтовну вартість доставки та термін доставки для вашого вантажу.\nВартість та термін доставки розраховуються на основі таких факторів, як вага, габарити, місце призначення та спосіб доставки.\nНадавши необхідні дані про вантаж і відправлення, ви можете отримати орієнтовну вартість доставки товарів.\nВідповідь зазвичай містить розраховану вартість та заплановану дату доставки на основі наданої інформації.</br>\n\n🔹**Description of control elements:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","requestBody":{"description":"Optional description in *Markdown*","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payerType":{"type":"string","description":"Визначає, хто відповідає за оплату послуг доставки. Тип платника визначає, яка сторона несе витрати:\n- `Sender`: Сторона, що відправляє товар, оплачує доставку.\n- `Recipient`: Сторона, що отримує товар, відповідає за оплату доставки.\n- `ThirdPerson`: Третя сторона оплачує доставку.\n- Для відправлень у межах Європи або з Європи в Україну необхідно передати поле `payerContractNumber`.\n- Для відправлень з України `payerContractNumber` не є обов’язковим.\"\n","enum":["Sender","Recipient","ThirdPerson"]},"payerContractNumber":{"type":"string","description":"Обов’язковий, якщо `payerType` = `ThirdPerson` для відправлень у межах Європи або з Європи в Україну.\nВказує номер договору платника-третьої сторони (наприклад, `CNPP-00001797`).\n"},"deliveryTypes":{"type":"array","items":{"type":"string"},"description":"Визначає список тарифних типів, які використовуються для розрахунку вартості доставки.\nУ відповіді розрахунку повертаються результати вартості для кожного переданого типу доставки.\n\n- `standard`: Стандартний тариф міжнародної доставки.\n- `economy`: Економ-тариф міжнародної доставки.\n- `express`: Експрес-тариф міжнародної доставки.\n\nЯкщо поле не передано, відповідний тариф визначається автоматично згідно з поточними бізнес-правилами, а поведінка розрахунку залишається без змін.\n\n**🔹Це поле є необов’язковим.**\n","enum":["standard","economy","express"]},"invoice":{"type":"object","description":"Інформація для розрахунку вартості доставки та митних платежів.","properties":{"incoterm":{"type":"string","description":"Тип розрахунку податків.\n- `DAP` – Поставка в місце призначення\n- `DDP` – Поставка зі сплатою мита\n","enum":["DAP","DDP"]},"currency":{"type":"string","description":"Код валюти у форматі ISO 4217 (наприклад, USD, EUR, GBP)."},"cost":{"type":"number","description":"Загальна задекларована вартість інвойсу у вихідній валюті, яка повинна дорівнювати сумі всіх позицій інвойсу, розрахованих як **(amount × cost)** для кожної позиції.\nЗадекларована вартість відправлення, що використовується для розрахунку митних платежів.\nТакож визначає максимальну суму компенсації у випадку втрати або пошкодження.\nОбов’язковий параметр, якщо incoterm = `DDP`.\n","minimum":1},"payerFeesCustoms":{"type":"string","description":"Визначає, хто відповідає за оплату митних платежів.\nВизначає сторону, яка несе витрати: `Sender`, `Recipient` або `ThirdPerson`.\n","enum":["Sender","Recipient","ThirdPerson"]}}},"parcels":{"type":"array","description":"Масив об’єктів посилок, де кожен об’єкт представляє окрему посилку у відправленні.\nЦей параметр є важливим для розрахунку вартості доставки, оскільки містить інформацію про габарити, вагу та інші характеристики кожної посилки.\nКожен об’єкт у цьому масиві містить необхідну інформацію для точного розрахунку вартості доставки з урахуванням розміру, ваги посилки та, за потреби, типу товару, що може впливати на спосіб доставки та тарифікацію.\n","items":{"type":"object","properties":{"cargoCategory":{"type":"string","description":"Визначає тип відправлення, що допомагає класифікувати товари для логістики та митного оформлення. Категорія впливає на обробку відправлення, його вартість та необхідну документацію. Доступні категорії:\n- parcel: Посилки малого та середнього розміру, зазвичай для споживчих товарів.\n- documents: Поштові відправлення, що містять документи, такі як листи, договори та офіційні документи. Ця категорія призначена для відправлень вагою не більше 1 кг та з габаритами, що не перевищують 35 см у довжину, 25 см у ширину та 2 см у висоту.\n- pallet: Тип вантажу, сформований як палетне відправлення з фіксованими габаритами та обмеженнями по вазі, доступний у Бізнес-кабінеті Європи для юридичних осіб:\n  - До 250 кг, площа ~0.48 м², габарити 80 × 60 × 170 см\n  - До 500 кг, площа ~0.96 м², габарити 120 × 80 × 170 см\n  - До 750 кг, площа ~1.2 м², габарити 120 × 100 × 170 см\n  - До 1000 кг, площа\n","enum":["parcel","documents","pallet"]},"insuranceCost":{"type":"number","format":"float","description":"Задекларована вартість відправлення для страхового покриття у валюті країни відправника. Визначає максимальну суму компенсації у разі втрати або пошкодження. Це значення визначає максимальну суму компенсації у разі пошкодження або втрати під час транспортування. Коректне встановлення цього значення є критично важливим для забезпечення належного страхового покриття. Важливо точно задекларувати цю вартість відповідно до фактичної вартості вмісту відправлення, оскільки її заниження може призвести до недостатньої компенсації.","minimum":0,"exclusiveMinimum":true},"rowNumber":{"type":"integer","description":"Послідовний ідентифікатор кожної посилки у відправленні, що використовується для впорядкування та відстеження окремих місць, особливо у випадку, коли відправлення містить кілька позицій. Якщо відправлення складається з однієї посилки, значення має бути 1.","minimum":1},"width":{"type":"integer","description":"Ширина посилки в міліметрах, що використовується разом із довжиною та висотою для розрахунку загального об’єму з метою логістичного планування.","minimum":1},"length":{"type":"integer","description":"Довжина посилки в міліметрах, що використовується разом із висотою та шириною для розрахунку загального об’єму з метою логістичного планування.","minimum":1},"height":{"type":"integer","description":"Висота посилки в міліметрах, що використовується разом із довжиною та шириною для розрахунку загального об’єму з метою логістичного планування.","minimum":1},"actualWeight":{"type":"integer","description":"Фактична загальна вага всіх одиниць товару в грамах (g), що є критичною для розрахунку вартості доставки та відповідності обмеженням перевізника щодо ваги.\nОчікувана одиниця виміру: грами (g)\nПідтримується точність лише до 10 грамів (0.01 кг). Значення, не кратні 10 г, округлюються вниз до найближчого меншого кратного 10 г.\n\n⚠️ВАЖЛИВО: Рекомендується округлювати значення ваги до найближчих 10 г перед відправкою, щоб уникнути неочікуваних коригувань.\n","minimum":1,"maximum":2147483647},"volumetricWeight":{"type":"integer","description":"Розрахункова вага, визначена на основі габаритів посилки, що використовується для тарифікації у випадках, коли об’єм впливає на вартість більше, ніж фактична вага. Відображає об’ємну (габаритну) вагу посилки.","minimum":0,"maximum":2147483647}}}},"sender":{"type":"object","description":"Містить основну інформацію про сторону, що відправляє вантаж. Надана тут інформація використовується для керування даними про місце відправлення з метою логістичного планування та впливає на розрахунок вартості доставки залежно від місцезнаходження відправника та застосовних правил перевезення. \nЯкщо платником є Відправник і відправлення здійснюється від юридичної особи, параметри \"companyTin\" та \"companyName\" використовуються для застосування індивідуальної знижки контрагента. Якщо знижка не застосовується або її не потрібно враховувати, ці параметри можуть бути порожніми або виключені із запиту.\n","properties":{"companyTin":{"type":"string","description":"Податковий ідентифікаційний номер або еквівалентний ідентифікатор (ЄДРПОУ, TIN, NIP, IČO) юридичної особи.\n\n🔹**Обов’язковий для юридичних та митних документів, якщо відправник є юридичною особою.**\n","maxLength":20,"nullable":true},"companyName":{"type":"string","description":"Офіційна назва компанії відправника. Використовується, якщо відправник є юридичною особою, для ідентифікації організації у документах та облікових записах. Вкажіть \"Private person\", якщо відправник не є компанією.","maxLength":100,"nullable":true},"countryCode":{"type":"string","description":"Дволітерний код країни відправника відповідно до стандарту ISO 3166-1 Alpha-2, що визначає країну походження відправлення.","pattern":"^[A-Z]{2}$"},"divisionNumber":{"type":"string","description":"Необов’язковий ідентифікатор, що визначає унікальний номер відділення або поштомата, з якого здійснюється відправлення. Використовується, якщо відправлення здійснюється з конкретного відділення. Поле взаємозамінне з 'divisionId', достатньо передати одне з них. Залишайте null, якщо відправлення здійснюється з адреси без прив’язки до відділення.","nullable":true},"divisionId":{"type":"integer","description":"Необов’язковий ідентифікатор, що представляє унікальний код відділення, з якого здійснюється відправлення. Використовується, коли потрібна обробка через конкретне відділення. Може використовуватись як альтернатива 'divisionNumber', достатньо одного з цих параметрів. Повинен бути null, якщо відправлення здійснюється з адреси без прив’язки до відділення.","nullable":true},"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":"Поштовий індекс (ZIP-код), що відповідає адресі відправника. Необхідний для ефективного сортування та маршрутизації відправлення.","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі за вказаною адресою, що дозволяє точно визначити місце забору відправлення.","maxLength":100},"flat":{"type":"string","description":"За наявності - номер квартири або офісу в будівлі, з якої здійснюється відправлення, що дозволяє кур’єру точно знайти потрібне приміщення.","maxLength":10},"block":{"type":"string","description":"Вказує конкретний корпус або секцію в межах великого житлового масиву чи комплексу (за потреби), що допомагає точно визначити місце відправлення вантажу.","maxLength":100,"nullable":true},"note":{"type":"string","description":"Дозволяє вказати додаткову інформацію або інструкції щодо адреси відправника, які можуть полегшити процес забору, такі як коди доступу, конкретні входи або бажаний час для зв’язку.","maxLength":100}}}}},"recipient":{"type":"object","description":"Інформація про отримувача відправлення, що описує фізичну особу або організацію, відповідальну за отримання вантажу.","properties":{"countryCode":{"type":"string","description":"Дволітерний код, що ідентифікує країну отримувача відповідно до стандарту ISO 3166-1 Alpha-2, який визначає країну призначення відправлення.","pattern":"^[A-Z]{2}$"},"divisionNumber":{"type":"string","description":"Необов’язковий ідентифікатор, що використовується для зазначення унікального номера відділення або поштомата, з якого здійснюється отримання відправлення. Актуальний у випадках, коли відправлення спрямоване до конкретного відділення. Це поле є взаємозамінним із 'divisionId', і достатньо передати один із цих ідентифікаторів. Це поле слід залишати null, якщо відправлення адресоване безпосередньо на адресу без прив’язки до відділення.","nullable":true},"divisionId":{"type":"integer","description":"Необов’язковий ідентифікатор, що представляє унікальний код відділення, до якого має бути доставлене відправлення. Як і recipientDivisionNumber, цей ідентифікатор є важливим у випадках, коли доставка передбачає обробку через конкретне відділення. Може використовуватися як альтернатива до divisionNumber, достатньо передати один із цих ідентифікаторів для визначення відділення отримання. Це поле слід залишати null, якщо відправлення доставляється на адресу без прив’язки до конкретного відділення.","nullable":true},"addressParts":{"type":"object","description":"Цей набір полів є необхідним, коли відправлення спрямоване на конкретну адресу, і визначає точні деталі місця доставки посилки. Він містить повну адресну інформацію, що забезпечує точну ідентифікацію місця доставки.","properties":{"city":{"type":"string","description":"Місто, до якого здійснюється доставка відправлення. Ця інформація забезпечує спрямування посилки до правильного населеного пункту отримувача.","maxLength":100},"region":{"type":"string","description":"Визначає штат або провінцію отримувача в межах країни призначення, що є критично важливим для коректної маршрутизації та доставки відправлення. При відправленні до США обов’язково слід вказувати дволітерний код штату, наприклад \"WA\" для Вашингтона або \"DC\" для округу Колумбія, відповідно до стандарту ISO 3166-2:US.","maxLength":100},"street":{"type":"string","description":"Назва вулиці за адресою отримувача, необхідна для точного визначення місця доставки.","maxLength":100},"postCode":{"type":"string","description":"Поштовий індекс (ZIP-код) адреси отримувача, критично важливий для точного сортування та маршрутизації посилки до кінцевого пункту призначення.","maxLength":10},"building":{"type":"string","description":"Визначає номер або назву будівлі за адресою отримувача, що дозволяє доставити відправлення до конкретної будівлі на відповідній вулиці.","maxLength":100},"flat":{"type":"string","description":"Номер квартири або офісу (за наявності), якщо доставка здійснюється до будівлі з кількома приміщеннями, що забезпечує доставку посилки до конкретного приміщення отримувача.","maxLength":10},"block":{"type":"string","description":"Визначає корпус або секцію в межах великого житлового масиву чи комплексу для отримувача, що є корисним у великих житлових забудовах для точнішого визначення місця доставки.","maxLength":100,"nullable":true},"note":{"type":"string","description":"Поле для додаткових інструкцій або деталей щодо адреси отримувача, які можуть допомогти під час доставки, таких як умови доступу, конкретні двері для доставки або бажаний час доставки.","maxLength":100}}}}}}}}}},"responses":{"200":{"description":"Successful cost calculation","content":{"application/json":{"schema":{"type":"object","properties":{"scheduledDeliveryDate":{"type":"string","format":"date-time","description":"Орієнтовна дата доставки, розрахована на основі маршрутизації та рівня сервісу. Може змінюватися залежно від логістичних та зовнішніх факторів. Дата у форматі ISO 8601.","nullable":true},"sender":{"type":"object","description":"Надає базову географічну інформацію про відправника як частину даних про місце відправлення у відповіді. Об’єкт містить інформацію про країну відправника та може включати додаткові ідентифікатори місця, такі як settlementId та divisionId, якщо вони доступні.","properties":{"countryCode":{"type":"string","description":"Дволітерний код країни відправника відповідно до стандарту ISO 3166-1 Alpha-2, що визначає країну походження відправлення.","pattern":"^[A-Z]{2}$"},"settlementId":{"type":"integer","description":"Ідентифікатор населеного пункту (міста або селища), з якого здійснюється відправлення, якщо було вказано `divisionId`. Якщо було вказано домашню адресу відправника, це поле матиме значення null.","nullable":true},"divisionId":{"type":"integer","description":"Унікальний ідентифікатор відділення відправника, з якого здійснюється відправлення, якщо його було вказано. Якщо було вказано домашню адресу відправника, це поле матиме значення null.","nullable":true}}},"recipient":{"type":"object","description":"Надає базову географічну інформацію про отримувача як частину даних про доставку у відповіді. Об’єкт містить інформацію про країну отримувача та може включати додаткові ідентифікатори місця, такі як settlementId та divisionId, якщо вони доступні.","properties":{"countryCode":{"type":"string","description":"Дволітерний код країни отримувача відповідно до стандарту ISO 3166-1 Alpha-2, що визначає країну призначення відправлення.","pattern":"^[A-Z]{2}$"},"settlementId":{"type":"integer","description":"Ідентифікатор населеного пункту (міста або селища), до якого відправляється відправлення, якщо було вказано `divisionId`. Якщо було вказано домашню адресу отримувача, це поле матиме значення null.","nullable":true},"divisionId":{"type":"integer","description":"Унікальний ідентифікатор відділення або пункту видачі отримувача, якщо його було вказано. Якщо було вказано домашню адресу отримувача, це поле матиме значення null.","nullable":true}}},"services":{"type":"array","description":"Набір сервісів, пов’язаних із відправленням, де кожен елемент описує конкретну послугу, застосовану або запитану для відправлення. Об’єкт містить деталі сервісу, такі як тип послуги, кількість, договірні дані, а також додаткові параметри, що визначають умови або особливості сервісу.","items":{"type":"object","properties":{"shipmentId":{"type":"integer","description":"Унікальний ідентифікатор відправлення, до якого належить ця послуга. Використовується для зв’язування послуги з конкретним відправленням у системі. Це поле може мати значення null або 0, якщо послуга попередньо налаштовується або якщо відправлення ще не створене чи не призначене в системі.","nullable":true},"shipmentParcelRowNumber":{"type":"string","description":"Ідентифікатор місця (посилки) у відправленні, до якого застосовується послуга. Використовується для управління кількома місцями в одному відправленні.","nullable":true},"serviceId":{"type":"string","description":"Унікальний ідентифікатор, призначений конкретній послузі, що описується, необхідний для відстеження та управління послугою."},"serviceType":{"type":"string","description":"Тип послуги.</br>\n**🔹Це поле є необов’язковим.**\n"},"serviceName":{"type":"string","description":"Назва послуги.</br>\n**🔹Це поле є необов’язковим.**\n"},"serviceCode":{"type":"string","description":"Код послуги.</br>\n**🔹Це поле є необов’язковим.**\n"},"amount":{"type":"number","description":"Загальна кількість одиниць або об’єктів, що входять до цієї послуги.","minimum":0},"contractNumber":{"type":"string","description":"Номер договору, в межах якого надається послуга (за наявності). Використовується в B2B або B2C сценаріях.","minLength":2,"maxLength":20,"nullable":true},"payer_type":{"type":"string","description":"Визначає, хто відповідає за оплату послуги. Типові значення: Sender, Recipient або ThirdPerson."},"paymentStatus":{"type":"string","description":"Статус оплати послуг доставки (наприклад, 'Paid', 'NeedPay', 'ContractAfterPayment', 'FreeOfCharge', 'Holded')."},"divisionId":{"type":"string","description":"Унікальний ідентифікатор відділення (за наявності).","nullable":true},"price":{"type":"number","description":"Вартість послуги до застосування будь-яких знижок.","minimum":0},"discount":{"type":"number","description":"Будь-яка знижка, застосована до послуги, що зменшує загальну вартість.","minimum":0},"cost":{"type":"number","format":"float","description":"Загальна вартість послуги після застосування знижок.","minimum":0},"user":{"type":"string","description":"Визначає тип користувача, який взаємодіє з послугою. Використовується для внутрішніх потреб.","maxLength":50},"shipmentLockVersion":{"type":"integer","description":"Версія даних відправлення для контролю конкурентного доступу."},"additional_parameters":{"type":"object","description":"Цей об’єкт містить додаткові параметри, що надають критично важливу інформацію для забезпечення коректної обробки та доставки відправлення.","properties":{"cod":{"type":"number","description":"Сума післяплати (COD), якщо застосовується. Визначає суму, яку необхідно стягнути під час доставки, що є критично важливим для операцій, які передбачають оплату при отриманні.","nullable":true},"date":{"type":"integer","description":"Орієнтовна дата доставки, розрахована на основі логістичних даних та інформації про маршрут. Якщо дату доставки неможливо визначити через недостатність даних для обраного напрямку, це поле може містити значення 0.","nullable":true},"from":{"type":"integer","description":"Відображає орієнтовний час початку інтервалу доставки. Це поле може містити значення 0, якщо недостатньо даних для визначення часу початку доставки.","nullable":true},"to":{"type":"integer","description":"Відображає орієнтовний час завершення інтервалу доставки. Аналогічно до параметра from, це поле може містити значення 0, якщо недостатньо даних для визначення часу завершення доставки.","nullable":true},"string":{"type":"integer","description":"Відображає категорію вантажу, визначену в параметрі 'cargoCategory'. Може містити значення, такі як 'Parcel', 'Documents', 'Cargo' або 'Pallet', що відображають тип відправлених товарів.","nullable":true},"fullName":{"type":"integer","description":"Повне ім’я отримувача. Використовується для забезпечення доставки конкретній особі та є необхідним для перевірки під час вручення.","nullable":true},"phone":{"type":"integer","description":"Контактний номер телефону отримувача або представника компанії отримувача. Використовується для сповіщень про доставку та комунікації з клієнтом під час обробки відправлення.\n\n**Формат:** Номер телефону має бути вказаний у **міжнародному форматі** відповідно до стандарту **E.164**.\n\nПриклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX\n\n**Обмеження:**\n- Для доставки до відділень Nova Post у Європі допускаються українські мобільні номери.\n- Для доставки до **партнерських локацій** (таких як InPost, GLS, Venipak, Cargus тощо) та при **міжнародній адресній доставці**, номер телефону повинен належати мобільному оператору країни отримувача. Якщо номер передано у локальному (не міжнародному) форматі, система намагатиметься нормалізувати його до міжнародного формату, однак внутрішній алгоритм не охоплює всі можливі випадки. Якщо ваша система не підтримує валідацію номерів на стороні інтерфейсу (front-end), рекомендується повідомляти про випадки некоректних номерів для подальшого вдосконалення логіки нормалізації.\n","nullable":true}}},"createdAt":{"type":"string","format":"date-time","description":"Дата та час створення запису, у форматі ISO 8601."},"updatedAt":{"type":"string","format":"date-time","description":"Дата та час останнього оновлення запису, у форматі ISO 8601."},"deliveryType":{"type":"string","description":"Унікальний ідентифікатор (UUID) типу тарифу доставки, використаного в результаті розрахунку.\nЦе значення відповідає внутрішньому ідентифікатору обраного тарифу.\n"},"deliveryTypeName":{"type":"string","description":"Код типу тарифу доставки, застосованого в результаті розрахунку.\n- `standard`: Стандартний тариф на міжнародну доставку.\n- `economy`: Економний тариф на міжнародну доставку.\n- `express`: Експрес-тариф на міжнародну доставку.\n"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Розрахунок вартості доставки"}}}}
```

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

> Цей метод API дозволяє оновити існуючий транспортний документ шляхом передачі ідентифікатора документа та повного набору оновлених даних. Вказавши ідентифікатор документа та надавши всі необхідні дані, ви можете замінити попередню версію документа новими даними з запиту. У відповіді зазвичай міститься інформація про успішність операції оновлення, а також можуть бути наведені деталі зміненого документа.\
> \
> Обмеження оновлення:\
> \- Дані відправлення можуть бути оновлені \*\*лише тоді, коли відправлення перебуває у статусі \`ReadyToShip\`\*\*. \
> \- Оновлення дозволені \*\*лише якщо ярлик (лейбл) відправлення ще не був надрукований\*\*.\
> \- Якщо відправлення не перебуває у статусі \`ReadyToShip\` або ярлик уже був надрукований, запит на оновлення буде відхилено з помилкою валідації.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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":{"/shipments/{id}":{"put":{"tags":["Shipments"],"description":"Цей метод API дозволяє оновити існуючий транспортний документ шляхом передачі ідентифікатора документа та повного набору оновлених даних. Вказавши ідентифікатор документа та надавши всі необхідні дані, ви можете замінити попередню версію документа новими даними з запиту. У відповіді зазвичай міститься інформація про успішність операції оновлення, а також можуть бути наведені деталі зміненого документа.\n\nОбмеження оновлення:\n- Дані відправлення можуть бути оновлені **лише тоді, коли відправлення перебуває у статусі `ReadyToShip`**. \n- Оновлення дозволені **лише якщо ярлик (лейбл) відправлення ще не був надрукований**.\n- Якщо відправлення не перебуває у статусі `ReadyToShip` або ярлик уже був надрукований, запит на оновлення буде відхилено з помилкою валідації.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","parameters":[{"name":"id","in":"path","description":"Ідентифікатор транспортного документа.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"Optional description in *Markdown*","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Визначає поточний статус транспортного документа, відображаючи його рух у межах життєвого циклу відправлення. Статуси описують ключові етапи:\n  - Draft: Документ перебуває на етапі створення та ще не завершений.\n  - Accepted: Документ перевірено та прийнято, готовий до наступних кроків.\n  - Issued: Документ сформовано та підготовлено до відправлення.\n  - ReadyToShip: Вказує, що відправлення готове до транспортування після створення експрес-накладної. Лише це значення може бути вказане при створенні відправлення.\n  - Deleted: Документ видалено із системи.\n  - Returned: Відправлення повернено відправнику.\n  - Utilized: Вказує, що фізичний вантаж, пов’язаний із транспортним документом, утилізовано або знищено, а документ закрито.\n","enum":["ReadyToShip"]},"clientOrder":{"type":"string","description":"Представляє всі можливі ідентифікатори замовлення, пов’язані з відправленням. Ці ідентифікатори встановлюються клієнтом для внутрішнього обліку та є важливими для відстеження відправлення протягом усього його маршруту. Усі введені значення можуть використовуватись у системі відстеження відправлення.","maxLength":50},"note":{"type":"string","description":"Додаткова інформація або спеціальні інструкції щодо замовлення. Може включати інструкції з доставки, особливі вимоги до обробки або інші важливі деталі, що полегшують обробку та виконання відправлення.","maxLength":255},"deliveryType":{"type":"string","description":"Визначає тип тарифу, який буде застосовано до відправлення під час створення або оновлення.\n- `standard`: Стандартний тариф на міжнародну доставку.\n- `economy`: Економний тариф на міжнародну доставку.\n- `express`: Експрес-тариф на міжнародну доставку.\n\nЯкщо поле не передано, тип тарифу визначається автоматично відповідно до поточних бізнес-правил, і поведінка оновлення відправлення залишається без змін.\n\n**🔹Це поле є необов’язковим.**\n"},"payerType":{"type":"string","description":"Визначає, хто відповідає за оплату послуг доставки. Тип платника визначає сторону, яка несе витрати:\n- Sender: Відправник оплачує доставку.\n- Recipient: Отримувач оплачує доставку.\n- ThirdPerson: Третя сторона (не відправник і не отримувач) оплачує послуги доставки. У разі вибору `ThirdPerson` поле `payerContractNumber` повинно містити номер договору платника. Детальніше див. у статті [Оплата послуг доставки через API Nova Post](https://api-portal.novapost.com/en/api-methods/payment/).\n","enum":["Sender","Recipient","ThirdPerson"]},"payerContractNumber":{"type":"string","description":"Номер договору платника. Обов’язковий, якщо `payerType = ThirdPerson`. Для клієнтів з України також допускається використання коду ЄДРПОУ замість номера договору. Поле також обов’язкове, якщо платником є відправник при безготівковій оплаті. Якщо значення не надано, за замовчуванням застосовується готівковий спосіб оплати. Коректність даних є критично важливою для обробки платежу. Більш детальну інформацію можна знайти у статті [Оплата послуг доставки через API Nova Post](https://api-portal.novapost.com/en/api-methods/payment/).\n","minLength":2,"maxLength":20,"nullable":true},"invoice":{"type":"object","description":"This object encapsulates the invoice details crucial for international shipments undergoing customs clearance. It presents the necessary data for customs authorities to process the consignment efficiently, including the assessment of duties and taxes, and to confirm adherence to import/export regulations. The structured format of the invoice ensures that all pertinent information is easily accessible and clear, facilitating a smoother transit across borders.","properties":{"customerNumber":{"type":"string","description":"Унікальний ідентифікатор/номер інвойсу, що супроводжує товари у відправленні, сформований клієнтом. Використовується для митного оформлення (експортного та імпортного), оскільки забезпечує однозначний зв’язок між товарами у відправленні та супровідною документацією, включаючи вартість, походження та іншу необхідну інформацію для митного контролю.\n\nЯкщо інвойс клієнта присутній у відправленні, але відсутні його дані — зокрема номер — обробка відправлення в інформаційній системі буде зупинена, термін митного оформлення збільшиться, а в найгіршому випадку митні органи можуть відмовити в оформленні та ініціювати повернення до країни експорту.\n","maxLength":50,"nullable":true},"customerCreatedAt":{"type":"string","format":"date-time","description":"Необхідно вказати дату, зазначену в інвойсі, що супроводжує відправлення.\n\nЯкщо дата відсутня в клієнтському документі, може бути використана дата створення відправлення.\n\n**🔹Це поле є обов’язковим, якщо заповнене поле `invoice.customerNumber`.**\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$"},"type":{"type":"string","description":"Тип клієнтського інвойсу, що супроводжує відправлення та використовується для митного декларування.\n\nЦе поле має відповідати фактичному типу документа, вкладеного у відправлення.\n\nДоступні значення:\n\n- `Invoice` — комерційний інвойс для відправлень комерційного характеру\n- `ProformaInvoice` — проформа-інвойс для відправлень некомерційного характеру\n\n**🔹Це поле є обов’язковим, якщо заповнене поле `invoice.customerNumber`.**\n","enum":["Invoice","ProformaInvoice"]},"incoterm":{"type":"string","description":"Визначає торгові умови договору перевезення між покупцем і продавцем відповідно до правил Incoterms®. Ці умови регламентують розподіл витрат на доставку, страхування, митні платежі та розподіл ризиків. Доступний лише обмежений набір правил Incoterms®:\n- DAP: Delivered at Place\n","enum":["DAP"]},"exportReason":{"type":"string","description":"Визначає загальну причину експорту товарів, що є обов’язковою для митних та інших регуляторних органів. Ця класифікація допомагає визначити тип відправлення на високому рівні без необхідності деталізації, що спрощує митне оформлення. Доступні значення:\n- ForPersonalPurposes: Товари для особистого використання або подарунки.\n- Selling: Товари призначені для продажу.\n- Repair: Товари, що відправляються для ремонту.\n- Return: Товари повертаються відправнику або виробнику.\n- Other: Інша причина, не передбачена вищенаведеними варіантами.\n","enum":["ForPersonalPurposes","Selling","Repair","Return","Other"]},"cost":{"type":"number","description":"Загальна задекларована вартість інвойсу в оригінальній валюті. Використовується для митного оформлення та декларування відправлення.\n\n**🔸Значення перевіряються на точність десяткових знаків, цифри після другого знака після коми ігноруються.**\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або здійснюються за його межі.**\n","minimum":0,"maximum":9999999.99},"currency":{"type":"string","description":"Код валюти інвойсу відповідно до ISO 4217. Усі позиції інвойсу повинні використовувати одну валюту.\n\n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або здійснюються за його межі.**\n","pattern":"^[A-Z]{3}$"},"payerFeesCustoms":{"type":"string","description":"Визначає, хто відповідає за оплату митних послуг. Параметр визначає сторону, яка несе витрати:\n\n- Sender: Відправник сплачує митні платежі.\n- Recipient: Отримувач сплачує митні платежі.\n- ThirdPerson: Третя сторона може сплачувати митні послуги лише у випадку, якщо це дозволено та якщо платник за послуги доставки також є третьою стороною.\n\nЗначення за замовчуванням — **Recipient**.</br>\nЦе значення також буде застосовано автоматично, якщо посилка перевищує максимально допустиму вартість (у валюті країни отримувача), за якої відправник може оплачувати митні платежі.\n\n**🔹Цей параметр є обов’язковим і застосовується лише для напрямку UA–EU.**\n","enum":["Sender","Recipient","ThirdPerson"]},"items":{"type":"array","description":"Детальний список товарів, що відправляються, включаючи описи та вартість, необхідний для митного оформлення та оцінки митних зборів.","items":{"type":"object","properties":{"id":{"type":"string","description":"Унікальний ідентифікатор кожного товару в межах відправлення."},"hsCode":{"type":"string","description":"Код Гармонізованої системи (HS code) для кожного товару — стандартизований числовий метод класифікації товарів у міжнародній торгівлі.\nЦе поле є обов’язковим для міжнародних відправлень, що проходять митне оформлення. Отримати коректний `hsCode` можна з довідника Класифікаторів вантажів (UKT ZED).\nПравила валідації:\n- **Якщо країна відправника або отримувача — Молдова (MD) або Канада (CA):**\n  - `hsCode` повинен складатися рівно з 10 цифрових символів.\n  - Якщо значення містить більше ніж 10 цифр, воно буде **скорочено** праворуч.\n  - Якщо значення містить менше ніж 10 цифр — помилка валідації.\n- **Для всіх інших країн:**\n  - `hsCode` повинен містити **від 8 до 10 цифрових символів** (включно).\n  - Якщо значення містить менше ніж 8 цифр — помилка валідації.\n- **Усі нецифрові символи автоматично видаляються перед валідацією.** \n- **Якщо значення поля `hsCode` дорівнює `210690` або `630900`, повинні виконуватися наступні умови:**\n  - `measurementCode` повинен бути встановлений у значення `kg`.\n  - Кожен товар із таким `hsCode` повинен бути унікальним — інвойс не може містити більше одного товару з кодом `210690` або `630900`.\n  - Значення кількості не повинно перевищувати 10.\n  \n**🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або прямують за межі ЄС.**\n","maxLength":255,"nullable":true},"name":{"type":"string","description":"Назва товару локальною мовою, що забезпечує точний опис для митного оформлення та логістичного планування. Назва повинна відповідати термінам з довідника Cargo Classifiers (UKT ZED), що гарантує відповідність стандартним класифікаційним кодам. Детальний опис допомагає точно ідентифікувати товар під час митного оформлення.\nЦе поле підтримує Unicode-кодування, що дозволяє використовувати спеціальні символи через формат \\uXXXX. Це забезпечує точне відображення назв товарів мовами з нелатинськими символами, підвищуючи зрозумілість у різних регуляторних середовищах.\n","maxLength":512},"nameEng":{"type":"string","description":"Вказує назву товару англійською мовою, що є критично важливим для забезпечення ідентифікації та розуміння товару в міжнародних торговельних і логістичних процесах. Англомовна назва спрощує комунікацію та документообіг при взаємодії з міжнародними партнерами та державними органами, сприяючи безперешкодному здійсненню міжнародних відправлень.\n\nПодібно до поля `name`, цей параметр також підтримує кодування Unicode. Використання формату \\uXXXX дозволяє коректно відображати будь-які спеціальні символи, необхідні для правильного написання назви товару англійською мовою.\n","maxLength":512},"materialEng":{"type":"string","description":"Опис матеріалу товару англійською мовою, що сприяє універсальному розумінню складу продукції.","maxLength":255},"madeInCountryCode":{"type":"string","description":"Код країни виробництва у форматі ISO 3166-1 alpha-2, необхідний для визначення митних зборів та відповідності торговельним угодам.","pattern":"^[A-Z]{2}$","nullable":true},"producerAndModel":{"type":"string","description":"Параметр містить виробника та модель пристрою під час створення відправлення. Обидва значення передаються в одному параметрі. Цей параметр є обов’язковим для таких категорій:\n- Електроприлади\n- Ноутбуки\n- Телефони\n- Велика та дрібна побутова техніка\n- Інші подібні товари\n","maxLength":255,"nullable":true},"actualWeight":{"type":"integer","description":"Фактична загальна вага всіх одиниць товару в грамах (g), необхідна для розрахунку вартості доставки та перевірки відповідності обмеженням перевізника.\n\nОчікувана одиниця вимірювання: грами (g)\n\nПідтримується точність лише до 10 грамів (0.01 кг). Значення, які не кратні 10 г, будуть округлені вниз до найближчого меншого кратного 10 г.\n\n⚠️ВАЖЛИВО: Рекомендується округлювати значення ваги до найближчих 10 г перед відправленням запиту, щоб уникнути неочікуваних коригувань.\n","minimum":1,"maximum":2147483647,"nullable":true},"measurementCode":{"type":"string","description":"Одиниця вимірювання кількості товару, наприклад штуки, кілограми, метри тощо, що стандартизує спосіб зазначення кількості.","maxLength":255},"amount":{"type":"number","description":"Кількість товару, що відправляється, необхідна для складського обліку та митної документації. Значення в одиницях вимірювання, що відповідають полю \"measurementCode\".","minimum":0,"maximum":9999999.99},"cost":{"type":"number","description":"Вартість однієї одиниці товару у валюті відправника, важлива для страхування та митної оцінки.\n\n**🔸Значення перевіряються на точність десяткових знаків, а цифри після другого знака після коми ігноруються.**\n","minimum":0,"maximum":9999999.99}}}}}},"services":{"type":"array","description":"Містить інформацію про додаткові послуги для відправлення.","properties":{"shipmentParcelRowNumber":{"type":"integer","nullable":true,"description":"Вказує номер рядка посилки, до якої застосовується послуга.\nЗначення має відповідати `rowNumber` існуючої посилки в масиві `parcels`.\n\nДля послуг, що застосовуються до **всього відправлення** (наприклад, `ExpBackwardGoods`), це поле повинно мати значення `null`.\n"},"serviceCode":{"type":"string","description":"Код, що позначає послугу.\n\n**Перелік доступних кодів та опис їх значення:**  \n\n- `ExpBackwardGoods` — активує можливість зворотної доставки для батьківського відправлення\n- `BackwardDelGoods` — підтверджує зворотну доставку в дочірньому відправленні\n- `ExpBackwardCreditDoc` — активує зворотну доставку підписаних документів для внутрішніх документарних відправлень у межах Молдови. Послуга доступна лише для юридичних осіб і тільки для відправлень типу “Documents”. Зворотне відправлення створюється як окрема доставка документів (кур’єром або оператором), а платником завжди є Recipient за безготівковим договором. Недоступно для каналів доставки Parcel Locker та PUDO. На першому етапі послуга активується лише для вибраних юридичних осіб.\n\n🔹**Це поле є обов’язковим для групи `services`.**\n"},"amount":{"type":"number","description":"Загальна сума, яку отримувач повинен сплатити в межах послуги COD.\n\n🔹**Це поле є обов’язковим для групи `services`.**\n"},"contractNumber":{"type":"string","nullable":true,"description":"Номер договору платника, відповідального за вибрану послугу.\n\nЦей параметр використовується для ідентифікації договору, в межах якого оплачується послуга.\n\nПоле є обов’язковим, якщо платником послуги є **третя сторона** або застосовуються умови безготівкової оплати. Якщо значення не вказано, оплата може бути оброблена відповідно до стандартних правил білінгу.\n"},"payerType":{"type":"string","description":"Визначає, хто відповідає за оплату послуги. Тип платника визначає, яка сторона несе витрати:\n\n- `Recipient` — єдине допустиме значення для послуги COD.\n- `Sender`, `Recipient` — допустимі значення платника для послуги ExpBackwardGoods.\n- `Sender`, `Recipient`, `ThirdPerson` — допустимі значення платника для послуги BackwardDelGoods.\n\n🔹**Це поле є обов’язковим для групи `services`.**\n"},"additionalParameters":{"type":"string","description":"Додаткові параметри для послуги.","properties":{"backwardDelivery":{"type":"array","description":"Додаткові параметри для налаштування зворотної доставки.\n🔹**These parameters are mandatory and required only for the ExpBackwardGoods service**","items":{"type":"object","properties":{"description":{"type":"string","description":"Опис товарів, що підлягають поверненню.\n\nЦе значення використовується для інформаційних та операційних цілей під час процесу зворотної доставки.\n"}}}}}}}},"parcels":{"type":"array","description":"Блок опису посилок. Масив містить об’єкти, кожен з яких відповідає за інформацію про посилку.","items":{"type":"object","properties":{"cargoCategory":{"type":"string","description":"Визначає тип відправлення, допомагаючи класифікувати товари для логістичної та митної обробки. Категорія впливає на спосіб обробки відправлення, вартість доставки та необхідну документацію. Доступні категорії:\n- parcel: Малі та середні посилки, зазвичай для споживчих товарів і роздрібної продукції.\n- documents: Поштові відправлення, що містять документи, такі як листи, договори та офіційні папери. Ця категорія призначена виключно для вкладень вагою не більше 1 кг та габаритами не більше 35 см у довжину, 25 см у ширину та 2 см у висоту.\n- cargo: Великогабаритні та об’ємні вантажі, включаючи палети або контейнери, призначені для комерційних перевезень і масштабного транспортування.\n- pallet: Тип вантажу, сформований як палетне відправлення з фіксованими габаритами та ваговими обмеженнями, доступний у Бізнес Кабінеті Європи для юридичних осіб:   \n  - До 250 кг, площа ~0.48 м², розміри 80 × 60 × 170 см\n  - До 500 кг, площа ~0.96 м², розміри 120 × 80 × 170 см\n  - До 750 кг, площа ~1.2 м², розміри 120 × 100 × 170 см \n  - До 1000 кг, площа ~1.2 м², розміри 120 × 100 × 170 см\n","enum":["parcel","documents","cargo","pallet"]},"parcelDescription":{"type":"string","description":"Це поле потребує стислого опису вмісту відправлення, який надає основну інформацію про характер вкладених товарів. Такий опис допомагає в логістичних процесах, забезпечуючи чітке розуміння вмісту посилки для планування транспортування та митного оформлення. Опис має містити відомості про тип товарів, їх призначення та будь-яку іншу релевантну інформацію, що характеризує вміст. Це важливо для забезпечення відповідності відправлення правилам перевезення та сприяє безперешкодному проходженню митних процедур.\n\nКрім того, це поле підтримує дані в кодуванні Unicode, що дозволяє використовувати спеціальні символи та знаки у форматі \\uXXXX. Ця можливість є особливо корисною для мов, які використовують нелатинські символи, забезпечуючи коректне відображення описів товарів у різних мовних середовищах.\n","maxLength":255},"insuranceCost*":{"type":"number","format":"float","description":"Відображає оголошену вартість відправлення для страхового покриття. Це значення визначає максимальну суму компенсації у разі пошкодження або втрати під час транспортування. Важливо точно вказувати це значення відповідно до фактичної вартості вмісту відправлення, оскільки заниження вартості може призвести до недостатньої компенсації.\n\n**Обробка валюти:**\n- Якщо `insuranceCurrencyCode` **не вказано**, значення повинно бути зазначене у **валюті країни відправника**.\n- Якщо `insuranceCurrencyCode` **вказано**, значення може бути зазначене в будь-якій підтримуваній валюті (ISO 4217). Система автоматично конвертує його у валюту країни відправника перед подальшою обробкою.\n\n🔸**Якщо використовується** `insuranceCurrencyCode`, **усі посилки повинні містити однаковий код валюти. Змішані або частково заповнені значення валюти призведуть до помилки валідації.**\n\n**Значення завжди повинно бути більше 0 незалежно від напрямку відправлення.**\n","minimum":1,"exclusiveMinimum":true},"insuranceCurrencyCode":{"type":"string","description":"Код валюти ISO 4217 для оголошеної страхової вартості (`insuranceCost`).\n\n- Якщо значення вказано, система автоматично конвертує `insuranceCost` у валюту країни відправника.\n- Якщо поле використовується, усі посилки повинні мати однаковий `insuranceCurrencyCode`.\n\n🔹**Це поле є необов’язковим.**\n","pattern":"^[A-Z]{3}$"},"rowNumber":{"type":"integer","description":"Послідовний ідентифікатор кожного місця у відправленні, який використовується для впорядкування та відстеження окремих місць, особливо якщо відправлення містить кілька місць. Якщо відправлення містить лише одне місце, значення має дорівнювати 1.","minimum":1},"untied":{"type":"boolean","description":"Дозволяє скасувати окремі місця у багатомісному відправленні до того, як відправлення набуде статусу **Accepted**. Щоб скасувати одне місце, необхідно передати повний масив усіх місць у запиті на оновлення та встановити параметр `untied: true` для місця, яке потрібно скасувати.\n\n⚠️ВАЖЛИВО:\n\n- Перше місце (`rowNumber: 1`) не можна відокремити. Якщо воно містить помилку, необхідно скасувати все відправлення та створити його повторно.\n- Якщо параметр `untied` використовується **для одного місця**, його необхідно передати **для всіх місць** у запиті.\n- Якщо для `untied: true` вказано неіснуюче значення `rowNumber`, система поверне помилку: `Impossible to delete a non-existent parcel`.\n- Якщо в запиті передано не всі місця, система поверне помилку: `Required parcel [rowNumber] is missing.`\n"},"width":{"type":"integer","description":"Ширина місця у міліметрах. Використовується разом із довжиною та висотою для розрахунку загального об'єму під час логістичного планування.","minimum":1},"length":{"type":"integer","description":"Довжина місця у міліметрах. Використовується разом із шириною та висотою для розрахунку загального об'єму під час логістичного планування.","minimum":1},"height":{"type":"integer","description":"Висота місця у міліметрах. Використовується разом із довжиною та шириною для розрахунку загального об'єму під час логістичного планування.","minimum":1},"actualWeight":{"type":"integer","description":"Фактична загальна вага всіх одиниць товару в грамах (g), яка використовується для розрахунку вартості доставки та перевірки відповідності ваговим обмеженням перевізника.\n\nОчікувана одиниця вимірювання: грами (g)\n\nПідтримується точність лише до 10 грамів (0,01 кг). Значення, які не кратні 10 г, будуть округлені вниз до найближчого меншого значення, кратного 10 г.\n\n⚠️ВАЖЛИВО: Перед надсиланням рекомендується округлювати значення ваги до найближчих 10 г, щоб уникнути неочікуваних коригувань.\n","minimum":1,"maximum":2147483647}}}},"sender":{"type":"object","description":"Інформація про сторону, що здійснює відправлення, включаючи дані про фізичну або юридичну особу, відповідальну за відправлення.","properties":{"companyTin":{"type":"string","description":"Податковий номер або інший ідентифікатор юридичної особи (ЄДРПОУ, TIN, NIP, IČO).\n\n🔹**Обов'язковий для юридичних та митних документів, якщо відправником є юридична особа.**\n","maxLength":20,"nullable":true},"companyName":{"type":"string","description":"Офіційна назва компанії-відправника. Це поле використовується, якщо відправником є юридична особа, та допомагає ідентифікувати організацію-відправника в документах і записах.","maxLength":100,"nullable":true},"eoriCode":{"type":"string","description":"Код EORI (Economic Operators Registration and Identification) використовується Європейським Союзом для ідентифікації суб'єктів господарювання, які здійснюють міжнародну торгівлю. Код EORI відправника необхідно вказати в інвойсі для забезпечення коректного митного оформлення та оподаткування під час відправлення товарів до країн ЄС. Код не є обов'язковим, але наполегливо рекомендується для міжнародних відправлень до ЄС, оскільки спрощує митне оформлення та допомагає уникнути затримок.","minLength":3,"maxLength":17,"nullable":true},"phone":{"type":"string","description":"Контактний номер телефону відправника або представника компанії-відправника.\n\nВикористовується для комунікації щодо відправлення, включаючи координацію забору та вирішення можливих питань.\n\n**Формат:** Номер телефону необхідно передавати у **міжнародному форматі** відповідно до стандарту **E.164**.\n\nПриклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX\n\n**Обмеження:**\n- Номер телефону відправника має бути дійсним і доступним у разі виникнення питань щодо доставки.\n- Якщо номер передано в локальному (неміжнародному) форматі, система спробує **нормалізувати** його, однак така логіка є обмеженою і може не підтримувати всі варіанти форматування для різних країн.\n\nНаполегливо рекомендуємо реалізувати **валідацію на стороні клієнта (front-end)**, щоб забезпечити введення номерів у правильному міжнародному форматі.\n"},"email":{"type":"string","description":"Адреса електронної пошти відправника, яка використовується як електронний канал зв'язку для отримання оновлень, запитів та важливих повідомлень щодо відправлення."},"name":{"type":"string","description":"Повне ім'я фізичної особи-відправника або основної контактної особи компанії-відправника. Це ім'я використовується в усій кореспонденції та документах, пов'язаних із відправленням.","maxLength":100},"ioss":{"type":"string","description":"Номер IOSS (Import One-Stop Shop) є необов'язковим параметром, який використовується для спрощення декларування ПДВ під час відправлення товарів із країн, що не входять до ЄС, із заявленою вартістю до 150 євро. Він використовується відправниками, які застосовують процедуру IOSS, для спрощення митного оформлення доставки приватним одержувачам у країнах ЄС. Це поле доступне для відправлень, у яких країна відправника знаходиться за межами ЄС, а країна призначення — у межах ЄС.","maxLength":12,"pattern":"/^[a-zA-Z0-9]*$/u"},"countryCode":{"type":"string","description":"Дволітерний код країни відправника відповідно до стандарту ISO 3166-1 Alpha-2, який визначає країну походження відправлення.","pattern":"^[A-Z]{2}$"},"divisionNumber":{"type":"string","description":"Це поле є обов'язковим для посилок, що відправляються з відділення або поштомата. Необхідно вказати унікальний ідентифікатор місця відправлення.","nullable":true},"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":"Поштовий індекс (ZIP-код), що відповідає адресі відправника. Є необхідним для ефективного сортування та маршрутизації відправлення.","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі за вказаною адресою, що дозволяє точно визначити місце забору відправлення.","maxLength":100},"flat":{"type":"string","description":"За потреби — номер квартири або офісу в будівлі, з якої здійснюється відправлення, що дозволяє працівникам служби забору знайти точне приміщення відправника.","maxLength":10},"block":{"type":"string","description":"Вказує конкретний блок або секцію великого житлового району чи комплексу, якщо це застосовується, що допомагає визначити точне місце початку маршруту відправлення.","maxLength":100,"nullable":true},"note":{"type":"string","description":"Дозволяє додати додаткові відомості або інструкції щодо адреси відправника, які можуть полегшити процес забору, наприклад код домофона, конкретний вхід або бажаний час зв'язку.","maxLength":100}}}}},"recipient":{"type":"object","description":"Інформація про сторону, яка отримує відправлення, включаючи дані про фізичну або юридичну особу, відповідальну за отримання відправленого товару.","properties":{"companyTin":{"type":"string","description":"Податковий номер або еквівалентний ідентифікатор юридичної особи (ЄДРПОУ, TIN, NIP, IČO).\n\n🔹**Обов'язковий для юридичної та митної документації, якщо одержувачем є юридична особа.**\n","maxLength":20,"nullable":true},"companyName":{"type":"string","description":"Офіційна назва компанії-одержувача. Використовуйте це поле, якщо одержувач є юридичною особою. Воно допомагає ідентифікувати організацію-одержувача в документах і записах.","maxLength":100,"nullable":true},"eoriCode":{"type":"string","description":"Код EORI одержувача є важливим для митного оформлення під час відправлення товарів до країн Європейського Союзу, особливо у разі відправлення юридичним особам. Код не є обов'язковим, але рекомендований, оскільки допомагає забезпечити безперешкодне митне оформлення та мінімізує ризик затримок. Необхідність зазначення `eoriCode` одержувача залежить від типу товарів, що відправляються:\n1. Неакцизні товари: код EORI не є обов'язковим, якщо неакцизні товари відправляються з України юридичній особі в Європі. Якщо одержувач не має коду EORI, його буде присвоєно автоматично.\n2. Підакцизні товари: код EORI є обов'язковим для відправлень підакцизних товарів. Одержувач повинен отримати код EORI до того, як товари можуть бути відправлені.\n","minLength":3,"maxLength":17,"nullable":true},"phone":{"type":"string","description":"Контактний номер телефону одержувача або представника компанії-одержувача. Використовується для сповіщень про доставку та зв'язку з клієнтом під час обробки відправлення.\n\n**Формат:** Номер телефону необхідно передавати у **міжнародному форматі** відповідно до стандарту **E.164**.\n\nПриклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX\n\n**Обмеження:**\n- Для доставки до відділень Nova Post у Європі допускається використання українських мобільних номерів.\n- Для доставки до **партнерських пунктів** (таких як InPost, GLS, Venipak, Cargus тощо) та **міжнародної адресної доставки** номер телефону має належати мобільному оператору країни одержувача. Якщо номер телефону передано у локальному (неміжнародному) форматі, система спробує **нормалізувати** його до міжнародного формату, однак внутрішній алгоритм не охоплює всі можливі випадки. Якщо ваша система не підтримує валідацію номерів телефонів на стороні клієнта (front-end), рекомендуємо повідомляти нам про випадки некоректної обробки номерів телефонів, щоб ми могли оцінити можливість удосконалення логіки нормалізації.\n"},"email":{"type":"string","description":"Адреса електронної пошти одержувача, яка використовується як цифровий контактний канал для отримання оновлень щодо відправлення, запитів та важливих сповіщень."},"name":{"type":"string","description":"Повне ім'я фізичної особи-одержувача або основної контактної особи компанії-одержувача. Це ім'я використовується в усій кореспонденції та документації, пов'язаній із відправленням.","maxLength":100},"countryCode":{"type":"string","description":"Дволітерний код, що ідентифікує країну одержувача відповідно до стандарту ISO 3166-1 Alpha-2 та визначає країну призначення відправлення.","pattern":"^[A-Z]{2}$"},"divisionNumber":{"type":"string","description":"Це поле є обов'язковим для посилок, які мають бути отримані у відділенні або поштоматі. Необхідно вказати унікальний ідентифікатор визначеного місця отримання.","nullable":true},"addressParts":{"type":"object","description":"Цей набір полів є необхідним, якщо відправлення доставляється на конкретну адресу. Він описує точні дані про місце, до якого має бути доставлена посилка. Містить повну інформацію про адресу, що забезпечує точну ідентифікацію місця доставки.","properties":{"city":{"type":"string","description":"Місто, до якого доставляється відправлення. Ця інформація забезпечує спрямування посилки до правильного населеного пункту одержувача.","maxLength":100},"region":{"type":"string","description":"Вказує штат або область одержувача в країні призначення, що є важливим для точної маршрутизації та доставки відправлення. Під час відправлення до США необхідно вказувати дволітерний код штату, наприклад \"WA\" для Вашингтона або \"DC\" для округу Колумбія, відповідно до стандарту ISO 3166-2:US.","maxLength":100},"street":{"type":"string","description":"Назва вулиці за адресою одержувача, необхідна для точного визначення місця доставки.","maxLength":100},"postCode":{"type":"string","description":"Поштовий індекс (ZIP-код) адреси одержувача, необхідний для точного сортування та маршрутизації посилки до кінцевого пункту призначення.","maxLength":10},"building":{"type":"string","description":"Вказує номер або назву будівлі за адресою одержувача, що забезпечує доставку до точної будівлі на відповідній вулиці.","maxLength":100},"flat":{"type":"string","description":"Номер квартири або офісу, якщо доставка здійснюється до багатоквартирної або багатофункціональної будівлі, що забезпечує доставку посилки до конкретного приміщення одержувача.","maxLength":10},"block":{"type":"string","description":"Вказує блок або секцію великого комплексу чи житлового району одержувача, якщо це застосовується, що є корисним у великих житлових комплексах для точнішого визначення місця доставки.","maxLength":100,"nullable":true},"note":{"type":"string","description":"Поле для зазначення будь-яких додаткових інструкцій або відомостей щодо адреси одержувача, які можуть допомогти під час доставки, наприклад інструкцій щодо доступу, конкретних дверей для доставки або бажаного часу доставки.","maxLength":100}}},"registrationAddressRecipient":{"type":"object","description":"Об'єкт registrationAddressRecipient містить детальну інформацію про адресу реєстрації одержувача та є обов'язковим під час відправлення до країн зі спеціальними митними вимогами, таких як Німеччина, Словаччина, Угорщина та Франція. Це забезпечує відповідність місцевим вимогам і сприяє безперешкодному проходженню митного оформлення.\n\nОб'єкт дозволяє точно та повністю представити адресу реєстрації одержувача, що є особливо важливим для міжнародних відправлень до країн із суворими митними вимогами.\n","properties":{"city":{"type":"string","description":"Назва міста, у якому зареєстрований одержувач. Вона повинна відповідати місцевим правилам найменування для точної ідентифікації.\n\n**🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції.**\n","maxLength":100},"street":{"type":"string","description":"Назва вулиці в адресі одержувача. Вона повинна відповідати місцевим правилам найменування для точної ідентифікації.\n\n**🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції.**\n","maxLength":100},"zipCode":{"type":"string","description":"Поштовий індекс адреси реєстрації одержувача.\n\n**🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції.**\n","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі, у якій зареєстрований одержувач.\n\n**🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції.**\n","maxLength":100},"apartment":{"type":"string","description":"Номер квартири або апартаментів у будівлі.","maxLength":10},"state":{"type":"string","description":"Штат або регіон, у якому зареєстрований одержувач. У деяких країнах є обов'язковим для детальної географічної ідентифікації.","maxLength":100}}}}}}}}}},"responses":{"202":{"description":"Відправлення успішно оновлено. Ця відповідь підтверджує, що дані зазначеного транспортного документа були змінені відповідно до переданих вхідних параметрів.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Унікальний ідентифікатор, призначений кожному відправленню, який використовується для внутрішніх операцій, таких як внесення змін, пошук у системі та видалення відправлень. Поле `id` слугує основним ідентифікатором для адміністративних і логістичних процесів у системі доставки, забезпечуючи точний доступ до записів про відправлення та керування ними.","minimum":1},"number":{"type":"string","description":"Номер транспортного документа, який надається клієнтам для відстеження відправлення та доступу до друкованих форм. Також використовується для пошуку відправлення в системі, забезпечуючи зручний для клієнта спосіб контролю його статусу. Хоча поле `number` використовується переважно для зовнішнього відстеження та документації, у певних системних операціях воно також може використовуватися для внутрішньої ідентифікації відправлення аналогічно до поля `id`.","pattern":"^[A-Z]{4}\\d{10}$"},"scheduledDeliveryDate":{"type":"string","description":"Орієнтовна дата доставки, розрахована на основі маршруту та рівня сервісу. Може змінюватися залежно від логістичних та зовнішніх факторів.","nullable":true},"status":{"type":"string","description":"Поточний статус відправлення. Після створення початково встановлюється значення `ReadyToShip`, що означає готовність відправлення до відправки."},"cost":{"type":"number","format":"float","description":"Загальна вартість розрахованих послуг доставки, що визначається на основі розміру, ваги, пункту призначення та вибраних сервісів."},"parcelsAmount":{"type":"integer","description":"Загальна кількість місць у відправленні. Це значення використовується для логістичного планування та відстеження.","minimum":1},"createdAt":{"type":"string","format":"date-time","description":"Дата й час створення запису про відправлення в системі."},"updatedAt":{"type":"string","format":"date-time","description":"Дата й час останнього оновлення запису про відправлення. Використовується для відстеження змін і оновлень, внесених до даних відправлення."},"deletedAt":{"type":"string","format":"date-time","description":"Дата й час скасування або видалення відправлення із системи. Якщо відправлення не було скасовано, це поле містить значення `null`.","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Оновити транспортний документ"}}}}
```

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

> Цей метод дозволяє видалити транспортний документ на підставі його унікального ідентифікатора (ID).\
> Для успішного видалення документа із системи запит повинен містити його ID.\
> Відповідь міститиме інформацію про успішність виконання операції.\
> \
> \*\*Особливості реалізації для різних регіонів:\*\*\
> \
> \*\*1. Європа:\*\*\
> \- Метод насамперед очікує унікальний ID (Ref ID) документа.\
> \- Додатково підтримується видалення за номером відправлення (наприклад, \`SHPL0123456789\`).\
> \
> \*\*2. Україна:\*\*\
> \- Видалення підтримується лише за Ref ID (унікальним ідентифікатором документа).\
> \- Видалення за номером відправлення (наприклад, номером експрес-накладної) не підтримується.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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":{"/shipments/{id}":{"delete":{"tags":["Shipments"],"description":"Цей метод дозволяє видалити транспортний документ на підставі його унікального ідентифікатора (ID).\nДля успішного видалення документа із системи запит повинен містити його ID.\nВідповідь міститиме інформацію про успішність виконання операції.\n\n**Особливості реалізації для різних регіонів:**\n\n**1. Європа:**\n- Метод насамперед очікує унікальний ID (Ref ID) документа.\n- Додатково підтримується видалення за номером відправлення (наприклад, `SHPL0123456789`).\n\n**2. Україна:**\n- Видалення підтримується лише за Ref ID (унікальним ідентифікатором документа).\n- Видалення за номером відправлення (наприклад, номером експрес-накладної) не підтримується.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","parameters":[{"name":"id","in":"path","description":"ID транспортного документа (відправлення).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"відправлення","content":{"application/json":{"schema":{"type":"object","properties":{"deletedAt":{"type":"string","description":"Дата й час видалення документа."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Видалити транспортний документ"}}}}
```

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

> Завантажує супровідні документи до конкретного відправлення за його ID.\
> Цей метод використовується для додавання інвойсів, специфікацій товарів, митних декларацій або інших документів, пов'язаних із відправленням, необхідних для обробки та митного оформлення.\
> Файли зберігаються та прив'язуються до відправлення, забезпечуючи кращу простежуваність і відповідність вимогам.\
> \
> ⚠️ Обмеження за регіоном:\</br>\
> Цей метод доступний лише для європейських відправлень (напрямки EU/EU та EU/UA).\</br>\
> Він недоступний для відправлень, що відправляються з України.\
> \
> Ім'я файлу:\
> • Якщо передано параметр "fileName", завантажений файл буде збережено з указаним ім'ям.\
> • Якщо параметр "fileName" не передано, за замовчуванням буде встановлено ім'я файлу "invoice".\
> \
> Приклади використання:\
> 1\) "Я хочу завантажити PDF-інвойс клієнта до відправлення 980911" — передайте вміст, закодований у base64, у параметрі "file" та встановіть \`"fileName": "invoice.pdf"\`.\
> 2\) "Я хочу додати фотографію товару у форматі JPEG" — закодуйте фотографію у base64 та встановіть \`"fileName": "product-photo.jpeg"\`.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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":{"/shipments/uploads/{id}":{"post":{"tags":["Shipments"],"description":"Завантажує супровідні документи до конкретного відправлення за його ID.\nЦей метод використовується для додавання інвойсів, специфікацій товарів, митних декларацій або інших документів, пов'язаних із відправленням, необхідних для обробки та митного оформлення.\nФайли зберігаються та прив'язуються до відправлення, забезпечуючи кращу простежуваність і відповідність вимогам.\n\n⚠️ Обмеження за регіоном:</br>\nЦей метод доступний лише для європейських відправлень (напрямки EU/EU та EU/UA).</br>\nВін недоступний для відправлень, що відправляються з України.\n\nІм'я файлу:\n• Якщо передано параметр \"fileName\", завантажений файл буде збережено з указаним ім'ям.\n• Якщо параметр \"fileName\" не передано, за замовчуванням буде встановлено ім'я файлу \"invoice\".\n\nПриклади використання:\n1) \"Я хочу завантажити PDF-інвойс клієнта до відправлення 980911\" — передайте вміст, закодований у base64, у параметрі \"file\" та встановіть `\"fileName\": \"invoice.pdf\"`.\n2) \"Я хочу додати фотографію товару у форматі JPEG\" — закодуйте фотографію у base64 та встановіть `\"fileName\": \"product-photo.jpeg\"`.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","parameters":[{"name":"id","in":"path","description":"Унікальний ідентифікатор відправлення, до якого додаються файли.</br>\nЦе значення відповідає `shipmentId` європейської системи.</br>\nВикористання номера українського відправлення призведе до помилки валідації.\n","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"Тіло JSON, що містить файл, закодований у base64, та необов'язкове ім'я файлу.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Файл документа, закодований у base64 (PDF, JPEG або інші підтримувані формати)."},"fileName":{"type":"string","description":"Необов'язкове ім'я файлу. Якщо не вказано, за замовчуванням використовується значення \"invoice\"."}}}}}},"responses":{"201":{"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":"Завантажити файл до відправлення"}}}}
```

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

> Цей API-метод дозволяє отримати маркування транспортного документа у форматі PDF за номером документа. \
> Маркування документа є документом для друку, який клієнти можуть прикріпити або наклеїти на свій вантаж під час його відправлення. \
> Вказавши номер документа в запиті, ви можете згенерувати PDF-файл, що містить маркування документа, для зручного друку.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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":{"/shipments/print":{"get":{"tags":["Shipments"],"description":"Цей API-метод дозволяє отримати маркування транспортного документа у форматі PDF за номером документа. \nМаркування документа є документом для друку, який клієнти можуть прикріпити або наклеїти на свій вантаж під час його відправлення. \nВказавши номер документа в запиті, ви можете згенерувати PDF-файл, що містить маркування документа, для зручного друку.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","parameters":[{"in":"query","name":"numbers[]","description":"Номери відправлень. Може приймати як один номер, так і масив номерів. Якщо використовується `type=marking`, у межах одного запиту дозволяється передавати лише один номер.","schema":{"type":"string"}},{"in":"query","name":"type","description":"Тип документа для друку.\n- `marking`: для маркування відправлення 100×100 (внутрішнього або міжнародного)\n- `international`: для митної декларації/інвойсу\n- `invoice`: для комерційного інвойсу\n","schema":{"type":"array","items":{"type":"string","enum":["marking","international","invoice"]}}},{"in":"query","name":"printSizeType","description":"Вибір розміру документа.\n\nДля `type=marking` цей параметр визначає тип запиту на друк маркування, але не гарантує кінцевий фізичний формат PDF-файлу, який повертає сервіс.\n\nКінцевий формат етикетки визначається автоматично відповідно до створеного відправлення.\n\nЯкщо параметр не передано:\n- для `type=marking` використовується внутрішня логіка друку маркування;\n- для `type=international` та `type=invoice` за замовчуванням використовується `size_A4`.\n\nЗворотна сумісність зі значеннями `100_100` та `size_100_100` збережена.\n","schema":{"type":"array","items":{"type":"string","enum":["size_100_100","size_A4"]}}},{"in":"query","name":"deliveryType","description":"Тип логістичного процесу для друку документа маркування. Застосовується лише для `type=marking`.\n- `Pickup`: перша миля\n- `Shipment`: остання миля\n","required":false,"schema":{"type":"string","enum":["Pickup","Shipment"]}}],"responses":{"200":{"description":"PDF-файл.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Друк транспортних документів"}}}}
```

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

> Цей API-метод дозволяє отримати статус відправлення, вказавши номер транспортного документа. Зазначивши номер документа в запиті, ви можете отримати інформацію про поточне місцезнаходження або статус відправлення, надаючи клієнтам оновлення в режимі реального часу щодо переміщення їхнього вантажу.\</br>\
> 🔸Цей метод працює \*\*лише з номером транспортного документа (номером відправлення)\*\* і \*\*не підтримує пошук за номерами замовлень клієнта або будь-якими зовнішніми ідентифікаторами\*\*.\</br>\
> 🔸\*\*Базове відстеження\*\* надає спрощену відповідь відстеження, зосереджену на історії статусів відправлення та, за потреби, пов'язаних номерах відправлень. На відміну від \*\*Повне відстеження\*\*, цей метод не повертає детальну інформацію про маршрут, дані на рівні окремих місць, причини недоставки, записи про повернення/переадресацію або розширені метадані. Цей метод призначений для швидкої та легкої перевірки статусів.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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":{"/shipments/tracking/history":{"get":{"tags":["Shipments"],"description":"Цей API-метод дозволяє отримати статус відправлення, вказавши номер транспортного документа. Зазначивши номер документа в запиті, ви можете отримати інформацію про поточне місцезнаходження або статус відправлення, надаючи клієнтам оновлення в режимі реального часу щодо переміщення їхнього вантажу.</br>\n🔸Цей метод працює **лише з номером транспортного документа (номером відправлення)** і **не підтримує пошук за номерами замовлень клієнта або будь-якими зовнішніми ідентифікаторами**.</br>\n🔸**Базове відстеження** надає спрощену відповідь відстеження, зосереджену на історії статусів відправлення та, за потреби, пов'язаних номерах відправлень. На відміну від **Повне відстеження**, цей метод не повертає детальну інформацію про маршрут, дані на рівні окремих місць, причини недоставки, записи про повернення/переадресацію або розширені метадані. Цей метод призначений для швидкої та легкої перевірки статусів.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","parameters":[{"in":"query","name":"numbers[]","description":"Номери відправлень. Може приймати як один номер, так і масив номерів.","schema":{"type":"string"}},{"in":"query","name":"extended","description":"Параметр, що відповідає за включення до відповіді масиву об'єктів зі списком усіх пов'язаних відправлень.\n\nЩоб отримати ці дані у відповіді, встановіть значення `1`.\n","schema":{"type":"string","default":0},"required":false}],"responses":{"200":{"description":"Схема відповіді відстеження","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Масив елементів в інвойсі.","items":{"type":"object","properties":{"id":{"type":"string","description":"Ідентифікатор транспортного документа."},"number":{"type":"string","description":"Номер транспортного документа."},"history_tracking":{"type":"array","description":"Масив статусів історії відстеження для зазначеного відправлення.","items":{"type":"object","properties":{"code":{"type":"string","description":"Номер коду статусу відстеження.\n\n**Список доступних статусів із їх кодами та описом їхнього значення:**\n\n- `1` — Ready to send\n- `2` — Deleted\n- `4` — Accepted for sending\n- `5` — Sent from the Sender''s Division\n- `6` — Arrived in the city of the Recipient\n- `7` — Arrived (at the Division)\n- `8` — Arrived (at the Postomat)\n- `9` — Closed\n- `10` — The shipment is closed and the money transfer is sent to the Sender\n- `11` — The shipment is closed and the sender has received the money transfer\n- `13` — Arrival at the transit sorting center\n- `16` — Departure from the transit sorting center\n- `17` — ArrivalTransitWarehouse (currently not used)\n- `19` — DepartureFromTransitWarehouse (currently not used)\n- `30` — Arrived at customs terminal\n- `31` — Departed from customs terminal\n- `99` — Delivery to Postomat is impossible (technical issues or oversized parcel)\n- `101` — Uploaded to the courier for delivery to the address\n- `102` — Returns (sender ordered a return)\n- `103` — Refusal of shipment\n- `104` — Redirecting\n- `105` — Utilization\n- `106` — Received and created return shipment of Documents/Document Subtypes\n- `110` — Shipment transferred to temporary storage\n- `111` — Failed delivery attempt (in case of targeted delivery)\n- `112` — Delivery date postponed (for targeted delivery)\n- `113` — Storage period expired (Postomat)\n- `114` — Awaiting customs clearance\n- `115` — Arrived at customs terminal\n- `116` — Broker refusal — under resolution\n- `117` — Cargo not found or lost (customs)\n- `118` — Forbidden content — delivery impossible (customs)\n- `119` — Customs clearance in progress\n- `120` — Customs clearance completed\n- `121` — Sent to destination city after customs\n- `122` — Preparing for transfer to customs\n- `123` — Awaiting information from the recipient\n- `125` — Preparing for transfer to customs\n- `126` — Preparing for transfer to customs\n- `127` — Customs declaration data verification in progress\n- `128` — Processing accompanying documents prior to customs\n- `130` — Import prohibited by customs\n- `131` — Return of uncleared cargo\n- `132` — Preparing for return\n- `133` — Client communication regarding a customs comment\n- `134` — The international shipment has been handed over to the customs broker for processing\n- `135` — The international shipment has been placed in Storage Area\n- `138` — Shipment delay due to incorrect recipient information\n- `141` — Storage period expired\n- `144` — Storage period expired\n- `149` — In storage\n- `155` — Shipment transferred for disposal\n- `197` — Processing customs documents\n- `198` — Cargo inspection by customs\n- `199` — Shipment requires customs clearance\n- `999` — Undetermined\n"},"code_name":{"type":"string","description":"Назва статусу відстеження.\n\nЯкщо в запиті передано параметр `extended`=`1`, це поле у відповіді міститиме детальну назву статусу відстеження.\n\n🔸**Це поле надається лише для інформаційних цілей, і його значення може змінюватися з часом. Для обробки статусів відстеження рекомендується використовувати поле** `history_tracking.code`.\n"},"country_code":{"type":"string","description":"Код країни місця, у якому було створено статус відстеження."},"settlement":{"type":"string","description":"Назва населеного пункту місця, у якому було створено статус відстеження."},"date":{"type":"string","description":"Дата й час створення статусу відстеження."}}}},"related_numbers":{"type":"array","description":"Масив об'єктів, що містить список пов'язаних відправлень.\n\n🔸**Номери відправлень, наведені тут, можуть змінюватися.**\n","items":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Базове відстеження"}}}}
```

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

> Цей API-метод дозволяє отримати статус відправлення, вказавши номер транспортного документа. Зазначивши номер документа в запиті, ви можете отримати інформацію про поточне місцезнаходження або статус відправлення, надаючи клієнтам оновлення в режимі реального часу щодо переміщення їхнього вантажу.\
> \
> За замовчуванням відповідь містить такі блоки даних:\
> \- Поточний статус відправлення;\
> \- Історія відстеження;\
> \- Актуальна історія відстеження;\
> \- Опис відправлення;\
> \- Розширена інформація про пов'язані відправлення.\
> \
> За потреби до відповіді можна включити додаткові блоки, передавши відповідні параметри:\
> \- \`withUndeliveryReason = true\` — додає масив об'єктів з інформацією про причини недоставки відправлень.\
> \- \`withCreatedOnTheBasis = true\` — додає масив об'єктів з інформацією про повернення або переадресації, пов'язані з відправленням.\
> \
> 🔸\*\*Повне відстеження\*\* надає вичерпну відповідь відстеження, що містить детальні дані про статус відправлення, повну історію переміщення, опис місць, причини недоставки та інформацію про пов'язані або похідні відправлення. На відміну від \*\*Базового відстеження\*\*, воно надає розширені операційні дані та призначене для випадків, коли потрібна повна видимість логістичного життєвого циклу відправлення.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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":{"/shipments/tracking":{"get":{"tags":["Shipments"],"description":"Цей API-метод дозволяє отримати статус відправлення, вказавши номер транспортного документа. Зазначивши номер документа в запиті, ви можете отримати інформацію про поточне місцезнаходження або статус відправлення, надаючи клієнтам оновлення в режимі реального часу щодо переміщення їхнього вантажу.\n\nЗа замовчуванням відповідь містить такі блоки даних:\n- Поточний статус відправлення;\n- Історія відстеження;\n- Актуальна історія відстеження;\n- Опис відправлення;\n- Розширена інформація про пов'язані відправлення.\n\nЗа потреби до відповіді можна включити додаткові блоки, передавши відповідні параметри:\n- `withUndeliveryReason = true` — додає масив об'єктів з інформацією про причини недоставки відправлень.\n- `withCreatedOnTheBasis = true` — додає масив об'єктів з інформацією про повернення або переадресації, пов'язані з відправленням.\n\n🔸**Повне відстеження** надає вичерпну відповідь відстеження, що містить детальні дані про статус відправлення, повну історію переміщення, опис місць, причини недоставки та інформацію про пов'язані або похідні відправлення. На відміну від **Базового відстеження**, воно надає розширені операційні дані та призначене для випадків, коли потрібна повна видимість логістичного життєвого циклу відправлення.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","parameters":[{"in":"query","name":"numbers[]","description":"Номери відправлень. Може приймати як один номер, так і масив номерів.","schema":{"type":"string"}},{"in":"query","name":"ids[]","description":"Пошук відправлень за ідентифікаторами транспортних документів. Може приймати як один ідентифікатор, так і масив ідентифікаторів для виконання пошуку.","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"withUndeliveryReason","description":"Параметр, що відповідає за включення до відповіді масиву об'єктів з інформацією про причини недоставки.\n\nЩоб отримати ці дані у відповіді, встановіть значення `true`.\n","schema":{"type":"boolean","default":false},"required":false},{"in":"query","name":"withCreatedOnTheBasis","description":"Параметр, що відповідає за включення до відповіді масиву об'єктів з інформацією про пов'язані відправлення (типи: `Redirecting`, `Return`, `Utilization`, `Redelivery`).\n\nЩоб отримати ці дані у відповіді, встановіть значення `true`.\n","schema":{"type":"boolean","default":false},"required":false},{"in":"query","name":"countryCode","description":"Дволітерний код країни відправника відповідно до стандарту ISO 3166-1 Alpha-2.\n\nЯкщо цей параметр указано, Історія відстеження та Актуальна історія відстеження відображатимуться лише для зазначеної країни.\n\nPattern: ^[A-Z]{2}$\n","schema":{"type":"string"}},{"in":"query","name":"external","description":"Параметр, що відповідає за включення до відповіді масиву об'єктів зі списком усіх пов'язаних відправлень, а також масиву, що містить розширену інформацію про ці відправлення — зокрема ім'я власника відправлення, номер відправлення та дату створення відправлення.\n\nЩоб отримати ці дані у відповіді, встановіть значення `1`.\n","schema":{"type":"string","default":0},"required":false},{"in":"query","name":"trackingByBarcode","description":"Система фільтрує агреговані дані та повертає інформацію лише для зазначеного місця. Це дозволяє відстежувати маршрут доставки конкретного місця у складі багатомісного відправлення.","schema":{"type":"string"},"required":false},{"in":"query","name":"withAllParcels","description":"Система агрегує події з усіх місць в один масив, згрупований за номером місця. Це дозволяє відстежувати маршрут доставки кожного місця у складі багатомісного відправлення.\n","schema":{"type":"boolean","default":false},"required":false}],"responses":{"200":{"description":"Схема відповіді відстеження","content":{"application/json":{"schema":{"type":"object","properties":{"currentStatus":{"type":"array","description":"Масив об'єктів, що містить детальну інформацію про поточний статус відправлення.","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер відправлення."},"createdDate":{"type":"string","format":"date-time","description":"Дата створення відправлення.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"scheduledDate":{"type":"string","format":"date-time","description":"Розрахункова дата доставки.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"scheduledDateOriginal":{"type":"string","format":"date-time","nullable":true,"description":"Початкова розрахункова дата доставки.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"adjustedDate":{"type":"string","format":"date-time","nullable":true,"description":"Скоригована дата доставки.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"closingDate":{"type":"string","format":"date-time","nullable":true,"description":"Дата закриття відправлення (завершення всіх операцій).\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"statusCode":{"type":"string","description":"Номер коду статусу відстеження.\n\n**Список доступних статусів із їх кодами та описом їхнього значення:**\n\n- `1` — Ready to send\n- `2` — Deleted\n- `4` — Accepted for sending\n- `5` — Sent from the Sender''s Division\n- `6` — Arrived in the city of the Recipient\n- `7` — Arrived (at the Division)\n- `8` — Arrived (at the Postomat)\n- `9` — Closed\n- `10` — The shipment is closed and the money transfer is sent to the Sender\n- `11` — The shipment is closed and the sender has received the money transfer\n- `13` — Arrival at the transit sorting center\n- `16` — Departure from the transit sorting center\n- `17` — ArrivalTransitWarehouse (currently not used)\n- `19` — DepartureFromTransitWarehouse (currently not used)\n- `30` — Arrived at customs terminal\n- `31` — Departed from customs terminal\n- `99` — Delivery to Postomat is impossible (technical issues or oversized parcel)\n- `101` — Uploaded to the courier for delivery to the address\n- `102` — Returns (sender ordered a return)\n- `103` — Refusal of shipment\n- `104` — Redirecting\n- `105` — Utilization\n- `106` — Received and created return shipment of Documents/Document Subtypes\n- `110` — Shipment transferred to temporary storage\n- `111` — Failed delivery attempt (in case of targeted delivery)\n- `112` — Delivery date postponed (for targeted delivery)\n- `113` — Storage period expired (Postomat)\n- `114` — Awaiting customs clearance\n- `115` — Arrived at customs terminal\n- `116` — Broker refusal — under resolution\n- `117` — Cargo not found or lost (customs)\n- `118` — Forbidden content — delivery impossible (customs)\n- `119` — Customs clearance in progress\n- `120` — Customs clearance completed\n- `121` — Sent to destination city after customs\n- `122` — Preparing for transfer to customs\n- `123` — Awaiting information from the recipient\n- `125` — Preparing for transfer to customs\n- `126` — Preparing for transfer to customs\n- `127` — Customs declaration data verification in progress\n- `128` — Processing accompanying documents prior to customs\n- `130` — Import prohibited by customs\n- `131` — Return of uncleared cargo\n- `132` — Preparing for return\n- `133` — Client communication regarding a customs comment\n- `134` — The international shipment has been handed over to the customs broker for processing\n- `135` — The international shipment has been placed in Storage Area\n- `138` — Shipment delay due to incorrect recipient information\n- `141` — Storage period expired\n- `144` — Storage period expired\n- `149` — In storage\n- `155` — Shipment transferred for disposal\n- `197` — Processing customs documents\n- `198` — Cargo inspection by customs\n- `199` — Shipment requires customs clearance\n- `999` — Undetermined\n"},"status":{"type":"string","description":"Назва коду статусу."},"statusDate":{"type":"string","format":"date-time","description":"Дата й час встановлення цього статусу.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"deliveryType":{"type":"string","description":"Тип доставки."},"deliveryCountry":{"type":"string","pattern":"^[A-Z]{2}$","description":"Дволітерний код країни призначення відповідно до стандарту ISO 3166-1 Alpha-2."}}}},"detailsTracking":{"type":"array","description":"Масив об'єктів, що містить детальну інформацію про весь маршрут переміщення відправлення, включаючи переміщення пов'язаних відправлень, якщо вони доступні.\n\nНе заповнюється, якщо використовується відстеження на рівні посилки (тобто коли передано `trackingByBarcode` або `withAllParcels` = `true`).\n","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер відправлення."},"date":{"type":"string","format":"date-time","nullable":true,"description":"Дата й час встановлення цього статусу.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"event":{"type":"string","description":"Назва події.\n\n**Доступні назви подій:**\n\n- `CreateID` — Shipment ID created\n- `CreateIDFullfilment` — Shipment ID created (fulfillment)\n- `Deleted` — Deleted\n- `CanceledSender` — Shipment cancelled by sender\n- `DeclarationDeleted` — Declaration cancelled\n- `ArrivalSenderWarehouse` — Arrival at sender’s warehouse\n- `ArrivalSenderPostomat` — Arrival at sender’s parcel locker\n- `ArrivalSenderDoors` — Courier picked up the shipment from sender\n- `DepartureSenderWarehouseFullfilment` — Shipped from sender's warehouse (fulfillment)\n- `DepartureSenderWarehouse` — Shipment dispatched from sender’s warehouse\n- `Departure` — Shipment\n- `Arrival` — Arrival\n- `DepartureSenderWarehouseFuture` — Shipment from sender’s warehouse (future event)\n- `DepartureFuture` — Shipment (future event)\n- `ArrivalFuture` — Arrival (future event)\n- `OnTheWayArrival` — En route to arrival point\n- `OnTheWayArrivalFuture` — En route to arrival point (future event)\n- `OnTheWayDeparture` — Shipment in transit\n- `OnTheWayDepartureFuture` — Shipment in transit (future event)\n- `ArrivalSenderDoorsFuture` — Courier picked up the shipment from sender (future event)\n- `ArrivalSenderCityDeliveryService` — Delivery service in recipient’s city (arrival)\n- `ArrivalTerminal` — Arrival at terminal\n- `ArrivalCustomsBrokerPartner` — Partner customs broker (arrival)\n- `DepartureDeliveryService` — Delivery service (dispatch)\n- `DepartureSenderCityDeliveryService` — Delivery service in sender’s city (dispatch)\n- `DepartureCustomsBrokerPartner` — Partner customs broker (dispatch)\n- `ArrivalDeliveryServiceFuture` — Delivery service (arrival, future event)\n- `ArrivalSenderCityDeliveryServiceFuture` — Delivery service in sender’s city (arrival, future event)\n- `ArrivalTerminalFuture` — Arrival at terminal (future event)\n- `ArrivalCustomsBrokerPartnerFuture` — Partner customs broker (arrival, future event)\n- `DepartureDeliveryServiceFuture` — Delivery service (dispatch, future event)\n- `DepartureSenderCityDeliveryServiceFuture` — Delivery service in sender’s city (dispatch, future event)\n- `DepartureTerminalFuture` — Dispatch from terminal (future event)\n- `DepartureTerminal` — Dispatch from terminal\n- `ArrivalDepot` — Arrival at depot\n- `DepartureDepot` — Dispatch from depot\n- `ArrivalDepotFuture` — Arrival at depot (future event)\n- `DepartureDepotFuture` — Dispatch from depot (future event)\n- `ArrivalSenderCityDepot` — Depot in sender’s city (arrival)\n- `DepartureSenderCityDepot` — Depot in sender’s city (dispatch)\n- `ArrivalSenderCityDepotFuture` — Depot in sender’s city (arrival, future event)\n- `DepartureSenderCityDepotFuture` — Depot in sender’s city (dispatch, future event)\n- `CustomsClearanceInitiated` — Customs clearance\n- `ArrivalSenderCityTerminal` — Terminal in sender’s city (arrival)\n- `ArrivalSenderCityTerminalFuture` — Terminal in sender’s city (arrival, future event)\n- `DepartureSenderCityTerminal` — Terminal in sender’s city (dispatch)\n- `DepartureSenderCityTerminalFuture` — Terminal in sender’s city (dispatch, future event)\n- `SentForCustomsClearance` — Sent for customs clearance\n- `CustomClearanceIsCompleted` — Customs processing completed\n- `SentToDestinationCountry` — Sent to destination city after customs\n- `ArrivalCustomTerminal` — Arrived at customs terminal\n- `ArrivalDeliveryService` — Delivery service (arrival)\n- `MovingPostomat` — Awaiting transportation / In transit to parcel locker\n- `InCityRecipientDeparture` — In recipient's city (dispatch)\n- `InCityRecipientArrival` — In recipient's city (arrival)\n- `InCityRecipientPlan` — In recipient's city (planned event)\n- `InCityRecipientFuture` — In recipient’s city (future event)\n- `InCityRecipient` — In recipient’s city\n- `InCityRecipientArrivalFuture` — In recipient’s city (future arrival event)\n- `InCityRecipientDepartureFuture` — In recipient’s city (future dispatch event)\n- `InCityRecipientPlanFuture` — In recipient’s city (future planned event)\n- `ArrivalDestinationDepot` — Destination city warehouse (arrival)\n- `DepartureDestinationDepot` — Destination city warehouse (dispatch)\n- `ArrivalDestinationDepotFuture` — Destination city warehouse (arrival, future event)\n- `DepartureDestinationDepotFuture` — Destination city warehouse (dispatch, future event)\n- `ArrivalDestinationDeliveryService` — Delivery service in recipient’s city (arrival)\n- `DepartureDestinationDeliveryService` — Delivery service in recipient’s city (dispatch)\n- `ArrivalDestinationDeliveryServiceFuture` — Delivery service in recipient’s city (arrival, future event)\n- `DepartureDestinationDeliveryServiceFuture` — Delivery service in recipient’s city (dispatch, future event)\n- `ArrivalDestinationTerminal` — Terminal in recipient’s city (arrival)\n- `ArrivalDestinationTerminalFuture` — Terminal in recipient’s city (arrival, future event)\n- `DepartureDestinationTerminal` — Terminal in recipient’s city (dispatch)\n- `DepartureDestinationTerminalFuture` — Terminal in recipient’s city (dispatch, future event)\n- `ArrivalSameSettlementImport` — Single locality (import, arrival)\n- `NoFreeSlotsInPostomat` — No free parcel locker cells available\n- `LoadingCourierForMoving` — Courier picked up the shipment\n- `ArrivalSameSettlementImportFuture` — Single locality (import, arrival, future event)\n- `ParcelWasTransferredToPartner` — Transferred to partner for further delivery\n- `ArrivalSameSettlementLocal` — Single locality (local, arrival)\n- `ArrivalSameSettlementLocalFuture` — Single locality (local, arrival, future event)\n- `ArrivalDuplicate` — Shipment pending processing at partner warehouse\n- `ArrivalDuplicatePassed` — Shipment was pending processing at partner warehouse\n- `DepartureDuplicate` — Shipment in the process of dispatching from partner warehouse\n- `DepartureDuplicatePassed` — Shipment was in dispatch process from partner warehouse\n- `InRouteDuplicate` — Shipment in transit — temporary partner-side delay\n- `InRouteDuplicatePassed` — Temporary partner-side delay resolved\n- `TransferPoint` — Transfer point\n- `MovingPoint` — At pickup point\n- `TransferPointPostomat` — Arrival at parcel locker\n- `ArrivalRecipientWarehouse` — Arrival at recipient’s warehouse\n- `ArrivalRecipientWarehouseFuture` — Arrival at recipient’s warehouse (future event)\n- `ArrivalRecipientPartnerWarehouse` — Arrived at partner warehouse\n- `ArrivalRecipientPostomat` — Arrived at recipient’s parcel locker\n- `ReceivedDoorsFuture` — Delivery to address (future event)\n- `ReceivedWarehouse` — Received at warehouse\n- `ReceivedDoors` — Delivered to address\n- `ReceivedPartner` — Shipment received by partner\n- `AlternativeDelivery` — Alternative delivery type applied (delivered to neighbor, left at the door, placed in mailbox, etc.)\n- `MoneyTransferAddress` — Money transfer (to address)\n- `MoneyTransfer` — Money transfer (to branch)\n- `MoneyTransferAddressFuture` — Money transfer (to address, future event)\n- `ArrivalSC` — Arrival at sorting center (SC)\n- `TransferToPartner` — Handed over to partner\n- `ArrivalTransitWarehouse` — Arrived at transit warehouse\n- `DepartureFromTransitWarehouse` — Departed from transit warehouse\n- `ProblemWithPostomat` — Delivery to Postomat impossible\n- `LoadingCourier` — Courier loading\n- `LoadingCourierFuture` — Courier loading (future event)\n- `ReturnTransferPoint` — Return to transfer point\n- `EWCargoAutoReturnRecipient` — Automatic return to sender\n- `OrderCargoReturn` — Return requested\n- `UndeliveryReasonsClient` — Not delivered (recipient refused the shipment)\n- `OrderRedirecting` — Redirection requested\n- `Utilization` — Sent for utilization\n- `DeclarationUtilization` — Shipment disposed\n- `EWRedeliveryAddress` — Redelivery (to address)\n- `EWRedeliveryDivision` — Redelivery (to branch)\n- `EWRedeliveryAddressFuture` — Redelivery (to address, future event)\n- `UndeliveryReasonsNoConnection` — Not delivered (no contact with recipient)\n- `ChangingTheDateWithTimeInterval` — Delivery rescheduled (time slot specified)\n- `ChangingTheDate` — Delivery rescheduled\n- `ShelfLifeHasExpired` — Storage period expired\n- `DeclarationArrivalCustomTerminalOutsideManifest` — Customs control started (outside manifest)\n- `DeclarationArrivalCustomTerminal` — Customs control started\n- `DeclarationInRoute` — Shipment en route to customs control\n- `DeclarationBrokerRejection` — Broker rejection — under review\n- `DeclarationCargoLost` — Shipment lost\n- `DeclarationCargoNotArrive` — Shipment did not arrive on schedule — under additional verification\n- `DeclarationCargoProhibitedForImport` — Prohibited content — delivery impossible\n- `DeclarationCustomsCargoSeizedBySmugglingDepartment` — Shipment seized by customs anti-smuggling department\n- `DeclarationCustomsCargoInspection` — Shipment undergoing customs inspection\n- `DeclarationCargoUnderInspectionCustoms` — Shipment under additional customs inspection\n- `DeclarationCustomsClearanceInitiated` — Customs clearance in progress\n- `DeclarationCustomsHold` — Shipment temporarily on hold by customs\n- `DeclarationCustomClearanceIsCompleted` — Customs clearance completed\n- `DeclarationSentToDestinationCountry` — Cleared customs — en route to destination country\n- `DeclarationAddedToManifest` — Added to the manifest\n- `DeclarationCustomerNoResponse` — Awaiting information from the recipient\n- `DeclarationPackagingDamaged` — Packaging damaged\n- `DeclarationShipmentDamaged` — Shipment damaged\n- `DeclarationInvalidCustomerData` — Verifying declaration data\n- `DeclarationNoSupportingDocuments` — Supporting documents missing\n- `CustomsRefusal` — Import prohibited by customs\n- `DeclarationAwaitingCustomsRelease` — Processing customs documents\n- `DeclarationCustomsDocumentsReceived` — Customs documents received, clearance in progress\n- `DeclarationShipmentAudit` — Cargo inspection by customs\n- `DeclarationRequireCustomsClearance` — Customs clearance required\n- `PickUpCreated` — Pickup order created\n- `PickUpAppointedCourier` — Courier assigned\n- `PickUpInProgress` — Courier en route for pickup\n- `PickUpReceivedByCourier` — Shipment received by courier\n- `PickUpDone` — Shipment picked up by courier\n- `PickUpNotPacked` — Pickup not completed — shipment was not packed\n- `PickUpNotCompleted` — Pickup not completed by courier\n\n- `DepartureCustomsBrokerPartnerFuture` — Partner customs broker (dispatch, future event)\n- `ShelfLifeHasExpiredReturn` — Not collected from Postomat — moved to the nearest division\n- `Lost` — Shipment lost\n"},"eventStatus":{"type":"string","description":"Статуси виконання події.\n\n**Можливі значення:**\n- `Passed` — подія вже відбулася\n- `Now` — подія відбувається зараз\n- `Future` — подія запланована на майбутнє\n"},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","nullable":true,"description":"Дволітерний код країни, що позначає країну, в якій сталася подія, відповідно до стандарту ISO 3166-1 Alpha-2."},"code":{"type":"string","description":"Номер коду статусу відстеження.\n\n**Допустимі значення відповідають значенням, визначеним для поля `currentStatus.statusCode`.**\n"},"divisionName":{"type":"string","description":"Відділення, у якому відбувається відповідна подія."},"postCode":{"type":"string","description":"Фактичний поштовий індекс."},"settlementName":{"type":"string","description":"Назва населеного пункту, у якому відбувається подія."},"eventName":{"type":"string","description":"Назва події для клієнта."},"postCode1":{"type":"string","description":"Початок діапазону поштових індексів для населеного пункту."},"postCode2":{"type":"string","description":"Кінець діапазону поштових індексів для населеного пункту."}}}},"historyOnlineTracking":{"type":"array","description":"Масив об'єктів, що містить інформацію про історію онлайн-відстеження статусів відправлення, за винятком дубльованих подій.\n\nНе заповнюється, якщо використовується відстеження на рівні посилки (тобто коли передано `trackingByBarcode` або `withAllParcels` = `true`).\n","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер відправлення."},"date":{"type":"string","format":"date-time","nullable":true,"description":"Дата й час встановлення цього статусу.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"event":{"type":"string","description":"Назва події.\n\n**Допустимі значення відповідають значенням, визначеним для поля `detailsTracking.event`.**\n"},"eventStatus":{"type":"string","description":"Статуси виконання події.\n\n**Можливі значення:**\n- `Passed` — подія вже відбулася\n- `Now` — подія відбувається зараз\n"},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","nullable":true,"description":"Дволітерний код країни, що позначає країну походження відправлення, відповідно до стандарту ISO 3166-1 Alpha-2."},"code":{"type":"string","description":"Номер коду статусу відстеження.\n\n**Допустимі значення відповідають значенням, визначеним для поля `currentStatus.statusCode`.**\n"},"divisionName":{"type":"string","description":"Відділення, у якому відбувається відповідна подія."},"postCode":{"type":"string","description":"Фактичний поштовий індекс."},"settlementName":{"type":"string","description":"Назва населеного пункту, у якому відбувається подія."},"eventName":{"type":"string","description":"Назва події для клієнта."},"postCode1":{"type":"string","description":"Початок діапазону поштових індексів для населеного пункту."},"postCode2":{"type":"string","description":"Кінець діапазону поштових індексів для населеного пункту."}}}},"parcelsDetailsTracking":{"type":"object","description":"Масив об'єктів, що містить детальну інформацію про весь маршрут переміщення посилки.\n\nЗаповнюється, якщо використовується відстеження на рівні посилки (тобто коли передано `trackingByBarcode` або `withAllParcels` = `true`).\n","additionalProperties":{"type":"array","description":"Динамічний ключ об'єкта, значенням якого є номер посилки. Використовується для групування подій відстеження за конкретною посилкою.","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер відправлення."},"date":{"type":"string","format":"date-time","nullable":true,"description":"Дата й час встановлення цього статусу.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"event":{"type":"string","description":"Назва події.\n\n**Доступні назви подій:**\n- `CreateID` — Shipment ID created\n- `CreateIDFullfilment` — Shipment ID created (fulfillment)\n- `Deleted` — Deleted\n- `CanceledSender` — Shipment cancelled by sender\n- `DeclarationDeleted` — Declaration cancelled\n- `ArrivalSenderWarehouse` — Arrival at sender’s warehouse\n- `ArrivalSenderPostomat` — Arrival at sender’s parcel locker\n- `ArrivalSenderDoors` — Courier picked up the shipment from sender\n- `DepartureSenderWarehouseFullfilment` — Shipped from sender's warehouse (fulfillment)\n- `DepartureSenderWarehouse` — Shipment dispatched from sender’s warehouse\n- `Departure` — Shipment\n- `Arrival` — Arrival\n- `DepartureSenderWarehouseFuture` — Shipment from sender’s warehouse (future event)\n- `DepartureFuture` — Shipment (future event)\n- `ArrivalFuture` — Arrival (future event)\n- `OnTheWayArrival` — En route to arrival point\n- `OnTheWayArrivalFuture` — En route to arrival point (future event)\n- `OnTheWayDeparture` — Shipment in transit\n- `OnTheWayDepartureFuture` — Shipment in transit (future event)\n- `ArrivalSenderDoorsFuture` — Courier picked up the shipment from sender (future event)\n- `ArrivalSenderCityDeliveryService` — Delivery service in recipient’s city (arrival)\n- `ArrivalTerminal` — Arrival at terminal\n- `ArrivalCustomsBrokerPartner` — Partner customs broker (arrival)\n- `DepartureDeliveryService` — Delivery service (dispatch)\n- `DepartureSenderCityDeliveryService` — Delivery service in sender’s city (dispatch)\n- `DepartureCustomsBrokerPartner` — Partner customs broker (dispatch)\n- `ArrivalDeliveryServiceFuture` — Delivery service (arrival, future event)\n- `ArrivalSenderCityDeliveryServiceFuture` — Delivery service in sender’s city (arrival, future event)\n- `ArrivalTerminalFuture` — Arrival at terminal (future event)\n- `ArrivalCustomsBrokerPartnerFuture` — Partner customs broker (arrival, future event)\n- `DepartureDeliveryServiceFuture` — Delivery service (dispatch, future event)\n- `DepartureSenderCityDeliveryServiceFuture` — Delivery service in sender’s city (dispatch, future event)\n- `DepartureTerminalFuture` — Dispatch from terminal (future event)\n- `DepartureTerminal` — Dispatch from terminal\n- `ArrivalDepot` — Arrival at depot\n- `DepartureDepot` — Dispatch from depot\n- `ArrivalDepotFuture` — Arrival at depot (future event)\n- `DepartureDepotFuture` — Dispatch from depot (future event)\n- `ArrivalSenderCityDepot` — Depot in sender’s city (arrival)\n- `DepartureSenderCityDepot` — Depot in sender’s city (dispatch)\n- `ArrivalSenderCityDepotFuture` — Depot in sender’s city (arrival, future event)\n- `DepartureSenderCityDepotFuture` — Depot in sender’s city (dispatch, future event)\n- `CustomsClearanceInitiated` — Customs clearance\n- `ArrivalSenderCityTerminal` — Terminal in sender’s city (arrival)\n- `ArrivalSenderCityTerminalFuture` — Terminal in sender’s city (arrival, future event)\n- `DepartureSenderCityTerminal` — Terminal in sender’s city (dispatch)\n- `DepartureSenderCityTerminalFuture` — Terminal in sender’s city (dispatch, future event)\n- `SentForCustomsClearance` — Sent for customs clearance\n- `CustomClearanceIsCompleted` — Customs processing completed\n- `SentToDestinationCountry` — Sent to destination city after customs\n- `ArrivalCustomTerminal` — Arrived at customs terminal\n- `ArrivalDeliveryService` — Delivery service (arrival)\n- `MovingPostomat` — Awaiting transportation / In transit to parcel locker\n- `InCityRecipientDeparture` — In recipient's city (dispatch)\n- `InCityRecipientArrival` — In recipient's city (arrival)\n- `InCityRecipientPlan` — In recipient's city (planned event)\n- `InCityRecipientFuture` — In recipient’s city (future event)\n- `InCityRecipient` — In recipient’s city\n- `InCityRecipientArrivalFuture` — In recipient’s city (future arrival event)\n- `InCityRecipientDepartureFuture` — In recipient’s city (future dispatch event)\n- `InCityRecipientPlanFuture` — In recipient’s city (future planned event)\n- `ArrivalDestinationDepot` — Destination city warehouse (arrival)\n- `DepartureDestinationDepot` — Destination city warehouse (dispatch)\n- `ArrivalDestinationDepotFuture` — Destination city warehouse (arrival, future event)\n- `DepartureDestinationDepotFuture` — Destination city warehouse (dispatch, future event)\n- `ArrivalDestinationDeliveryService` — Delivery service in recipient’s city (arrival)\n- `DepartureDestinationDeliveryService` — Delivery service in recipient’s city (dispatch)\n- `ArrivalDestinationDeliveryServiceFuture` — Delivery service in recipient’s city (arrival, future event)\n- `DepartureDestinationDeliveryServiceFuture` — Delivery service in recipient’s city (dispatch, future event)\n- `ArrivalDestinationTerminal` — Terminal in recipient’s city (arrival)\n- `ArrivalDestinationTerminalFuture` — Terminal in recipient’s city (arrival, future event)\n- `DepartureDestinationTerminal` — Terminal in recipient’s city (dispatch)\n- `DepartureDestinationTerminalFuture` — Terminal in recipient’s city (dispatch, future event)\n- `ArrivalSameSettlementImport` — Single locality (import, arrival)\n- `NoFreeSlotsInPostomat` — No free parcel locker cells available\n- `LoadingCourierForMoving` — Courier picked up the shipment\n- `ArrivalSameSettlementImportFuture` — Single locality (import, arrival, future event)\n- `ParcelWasTransferredToPartner` — Transferred to partner for further delivery\n- `ArrivalSameSettlementLocal` — Single locality (local, arrival)\n- `ArrivalSameSettlementLocalFuture` — Single locality (local, arrival, future event)\n- `ArrivalDuplicate` — Shipment pending processing at partner warehouse\n- `ArrivalDuplicatePassed` — Shipment was pending processing at partner warehouse\n- `DepartureDuplicate` — Shipment in the process of dispatching from partner warehouse\n- `DepartureDuplicatePassed` — Shipment was in dispatch process from partner warehouse\n- `InRouteDuplicate` — Shipment in transit — temporary partner-side delay\n- `InRouteDuplicatePassed` — Temporary partner-side delay resolved\n- `TransferPoint` — Transfer point\n- `MovingPoint` — At pickup point\n- `TransferPointPostomat` — Arrival at parcel locker\n- `ArrivalRecipientWarehouse` — Arrival at recipient’s warehouse\n- `ArrivalRecipientWarehouseFuture` — Arrival at recipient’s warehouse (future event)\n- `ArrivalRecipientPartnerWarehouse` — Arrived at partner warehouse\n- `ArrivalRecipientPostomat` — Arrived at recipient’s parcel locker\n- `ReceivedDoorsFuture` — Delivery to address (future event)\n- `ReceivedWarehouse` — Received at warehouse\n- `ReceivedDoors` — Delivered to address\n- `ReceivedPartner` — Shipment received by partner\n- `AlternativeDelivery` — Alternative delivery type applied (delivered to neighbor, left at the door, placed in mailbox, etc.)\n- `MoneyTransferAddress` — Money transfer (to address)\n- `MoneyTransfer` — Money transfer (to branch)\n- `MoneyTransferAddressFuture` — Money transfer (to address, future event)\n- `ArrivalSC` — Arrival at sorting center (SC)\n- `TransferToPartner` — Handed over to partner\n- `ArrivalTransitWarehouse` — Arrived at transit warehouse\n- `DepartureFromTransitWarehouse` — Departed from transit warehouse\n- `ProblemWithPostomat` — Delivery to Postomat impossible\n- `LoadingCourier` — Courier loading\n- `LoadingCourierFuture` — Courier loading (future event)\n- `ReturnTransferPoint` — Return to transfer point\n- `EWCargoAutoReturnRecipient` — Automatic return to sender\n- `OrderCargoReturn` — Return requested\n- `UndeliveryReasonsClient` — Not delivered (recipient refused the shipment)\n- `OrderRedirecting` — Redirection requested\n- `Utilization` — Sent for utilization\n- `DeclarationUtilization` — Shipment disposed\n- `EWRedeliveryAddress` — Redelivery (to address)\n- `EWRedeliveryDivision` — Redelivery (to branch)\n- `EWRedeliveryAddressFuture` — Redelivery (to address, future event)\n- `UndeliveryReasonsNoConnection` — Not delivered (no contact with recipient)\n- `ChangingTheDateWithTimeInterval` — Delivery rescheduled (time slot specified)\n- `ChangingTheDate` — Delivery rescheduled\n- `ShelfLifeHasExpired` — Storage period expired\n- `DeclarationArrivalCustomTerminalOutsideManifest` — Customs control started (outside manifest)\n- `DeclarationArrivalCustomTerminal` — Customs control started\n- `DeclarationInRoute` — Shipment en route to customs control\n- `DeclarationBrokerRejection` — Broker rejection — under review\n- `DeclarationCargoLost` — Shipment lost\n- `DeclarationCargoNotArrive` — Shipment did not arrive on schedule — under additional verification\n- `DeclarationCargoProhibitedForImport` — Prohibited content — delivery impossible\n- `DeclarationCustomsCargoSeizedBySmugglingDepartment` — Shipment seized by customs anti-smuggling department\n- `DeclarationCustomsCargoInspection` — Shipment undergoing customs inspection\n- `DeclarationCargoUnderInspectionCustoms` — Shipment under additional customs inspection\n- `DeclarationCustomsClearanceInitiated` — Customs clearance in progress\n- `DeclarationCustomsHold` — Shipment temporarily on hold by customs\n- `DeclarationCustomClearanceIsCompleted` — Customs clearance completed\n- `DeclarationSentToDestinationCountry` — Cleared customs — en route to destination country\n- `DeclarationAddedToManifest` — Added to the manifest\n- `DeclarationCustomerNoResponse` — Awaiting information from the recipient\n- `DeclarationPackagingDamaged` — Packaging damaged\n- `DeclarationShipmentDamaged` — Shipment damaged\n- `DeclarationInvalidCustomerData` — Verifying declaration data\n- `DeclarationNoSupportingDocuments` — Supporting documents missing\n- `CustomsRefusal` — Import prohibited by customs\n- `DeclarationAwaitingCustomsRelease` — Processing customs documents\n- `DeclarationCustomsDocumentsReceived` — Customs documents received, clearance in progress\n- `DeclarationShipmentAudit` — Cargo inspection by customs\n- `DeclarationRequireCustomsClearance` — Customs clearance required\n- `PickUpCreated` — Pickup order created\n- `PickUpAppointedCourier` — Courier assigned\n- `PickUpInProgress` — Courier en route for pickup\n- `PickUpReceivedByCourier` — Shipment received by courier\n- `PickUpDone` — Shipment picked up by courier\n- `PickUpNotPacked` — Pickup not completed — shipment was not packed\n- `PickUpNotCompleted` — Pickup not completed by courier\n\n- `DepartureCustomsBrokerPartnerFuture` — Partner customs broker (dispatch, future event)\n- `ShelfLifeHasExpiredReturn` — Not collected from Postomat — moved to the nearest division\n- `Lost` — Shipment lost\n"},"eventStatus":{"type":"string","description":"Статуси виконання події.\n\n**Можливі значення:**\n- `Passed` — подія вже відбулася\n- `Now` — подія відбувається зараз\n- `Future` — подія запланована на майбутнє\n"},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","nullable":true,"description":"Дволітерний код країни, що позначає країну, в якій сталася подія, відповідно до стандарту ISO 3166-1 Alpha-2."},"code":{"type":"string","description":"Номер коду статусу відстеження.\n\n**Допустимі значення відповідають значенням, визначеним для поля `currentStatus.statusCode`.**\n"},"divisionName":{"type":"string","description":"Відділення, у якому відбувається відповідна подія."},"postCode":{"type":"string","description":"Фактичний поштовий індекс."},"settlementName":{"type":"string","description":"Назва населеного пункту, у якому відбувається подія."},"eventName":{"type":"string","description":"Назва події для клієнта."},"postCode1":{"type":"string","description":"Початок діапазону поштових індексів для населеного пункту."},"postCode2":{"type":"string","description":"Кінець діапазону поштових індексів для населеного пункту."}}}}},"parcelsHistoryOnlineTracking":{"type":"object","description":"Масив об'єктів, що містить інформацію про історію онлайн-відстеження статусів посилки, за винятком дубльованих подій.\n\nЗаповнюється, якщо використовується відстеження на рівні посилки (тобто коли передано `trackingByBarcode` або `withAllParcels` = `true`).\n","additionalProperties":{"type":"array","description":"Динамічний ключ об'єкта, значенням якого є номер посилки. Використовується для групування подій відстеження за конкретною посилкою.","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер відправлення."},"date":{"type":"string","format":"date-time","nullable":true,"description":"Дата й час встановлення цього статусу.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"event":{"type":"string","description":"Назва події.\n\n**Допустимі значення відповідають значенням, визначеним для поля `detailsTracking.event`.**\n"},"eventStatus":{"type":"string","description":"Статуси виконання події.\n\n**Можливі значення:**\n- `Passed` — подія вже відбулася\n- `Now` — подія відбувається зараз\n"},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","nullable":true,"description":"Дволітерний код країни, що позначає країну походження відправлення, відповідно до стандарту ISO 3166-1 Alpha-2."},"code":{"type":"string","description":"Номер коду статусу відстеження.\n\n**Допустимі значення відповідають значенням, визначеним для поля `currentStatus.statusCode`.**\n"},"divisionName":{"type":"string","description":"Відділення, у якому відбувається відповідна подія."},"postCode":{"type":"string","description":"Фактичний поштовий індекс."},"settlementName":{"type":"string","description":"Назва населеного пункту, у якому відбувається подія."},"eventName":{"type":"string","description":"Назва події для клієнта."},"postCode1":{"type":"string","description":"Початок діапазону поштових індексів для населеного пункту."},"postCode2":{"type":"string","description":"Кінець діапазону поштових індексів для населеного пункту."}}}}},"parcels":{"type":"array","description":"Блок опису посилок. Масив містить об'єкти, кожен з яких відповідає за інформацію про посилку.","items":{"type":"object","properties":{"number":{"type":"string","pattern":"^[A-Z]{4}\\d{10}$","description":"Номер транспортного документа."},"rowNumber":{"type":"integer","minimum":1,"nullable":true,"description":"Номер посилки."},"untied":{"type":"boolean","description":"Внутрішні дані. Не використовувати."},"cargoCategoryGroup":{"type":"string","description":"Тип відправлення (посилка, документи, палета тощо)."},"cargoCategoryId":{"type":"string","description":"Внутрішні дані. Не використовувати."},"categoryCargoName":{"type":"string","description":"Назва категорії відправлення."},"parcelDescription":{"type":"string","maxLength":255,"description":"Короткий опис вмісту посилки."},"insuranceCost":{"type":"number","minimum":0,"description":"Сума оголошеної вартості."},"insuranceCostCurrencyCode":{"type":"string","description":"Валюта, у якій указано оголошену вартість відправлення, відповідно до стандарту ISO 4217."},"length":{"type":"integer","minimum":1,"description":"Фактична довжина посилки в мм."},"width":{"type":"integer","minimum":1,"description":"Фактична ширина посилки в мм."},"height":{"type":"integer","minimum":1,"description":"Фактична висота посилки в мм."},"actualWeight":{"type":"number","minimum":0,"maximum":2147483647,"description":"Фактична вага посилки в грамах."},"volumetricWeight":{"type":"number","minimum":0,"maximum":2147483647,"description":"Об'ємна вага посилки."},"lengthCheck":{"type":"number","nullable":true,"description":"Фактична скоригована довжина відправлення в міліметрах після контрольного вимірювання."},"widthCheck":{"type":"number","nullable":true,"description":"Фактична скоригована ширина відправлення в міліметрах після контрольного вимірювання."},"heightCheck":{"type":"number","nullable":true,"description":"Фактична скоригована висота відправлення в міліметрах після контрольного вимірювання."},"actualWeightCheck":{"type":"number","nullable":true,"description":"Фактична скоригована вага відправлення в грамах після контрольного вимірювання."},"volumetricWeightCheck":{"type":"number","nullable":true,"description":"Фактична скоригована об'ємна вага відправлення в грамах після контрольного вимірювання."}}}},"alternativeNumbers":{"type":"array","description":"Масив об'єктів, що містить список пов'язаних відправлень.","items":{"type":"string"}},"alternativeNumbersGW":{"type":"array","description":"Масив об'єктів, що містить розширену інформацію про пов'язані відправлення.","items":{"type":"object","properties":{"name":{"type":"string","description":"Ім'я власника відправлення."},"number":{"type":"string","description":"Номер відправлення."},"date":{"type":"string","format":"date-time","description":"Дата створення відправлення.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"}}}},"undeliveryReasons":{"type":"array","description":"Масив об'єктів, що містить інформацію про причини невручення відправлення.","items":{"type":"object","properties":{"reasonName":{"type":"string","description":"Назва причини невручення."},"reasonDate":{"type":"string","format":"date-time","description":"Дата невручення.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"},"reasonId":{"type":"string","description":"Унікальний ідентифікатор причини невручення."},"subtypeOfReasonId":{"type":"string","description":"Унікальний ідентифікатор підпричини невручення."},"subtypeOfReasonName":{"type":"string","description":"Назва підпричини невручення."}}}},"createdOnTheBasis":{"type":"array","description":"Масив об'єктів, що містить інформацію про відправлення, створені на основі інших відправлень.","items":{"type":"object","properties":{"number":{"type":"string","description":"Номер документа."},"type":{"type":"string","description":"Тип документа.\n\n**Можливі значення:**\n- `Redirecting`\n- `Return`\n- `Utilization`\n- `Redelivery`\n"},"createdDate":{"type":"string","format":"date-time","description":"Дата невручення.\n\nДата у форматі ISO 8601 із часовою зоною UTC.\n"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Повне відстеження"}}}}
```

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

> Повертає список доступних файлів, прикріплених до відправлення (фотографії та/або підпис), для вказаного відправлення \*\*лише якщо відправлення належить автентифікованому клієнту\*\*.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/shipments/{shipmentNumber}/attachments":{"get":{"tags":["Shipments"],"description":"Повертає список доступних файлів, прикріплених до відправлення (фотографії та/або підпис), для вказаного відправлення **лише якщо відправлення належить автентифікованому клієнту**.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","parameters":[{"in":"path","name":"shipmentNumber","required":true,"description":"Номер відправлення.","schema":{"type":"string"}}],"responses":{"200":{"description":"Структура метаданих","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"shipmentId":{"type":"integer","description":"Внутрішній ідентифікатор відправлення."},"storageInfo":{"type":"object","description":"Містить інформацію про файл.","properties":{"id":{"type":"string","description":"Унікальний ідентифікатор файлу `{fileId}` у сховищі."},"name":{"type":"string","description":"Назва файлу."},"documentType":{"type":"string","description":"Тип документа:\n\n- Signature\n- ProofOfDelivery\n"}}},"createdAt":{"type":"string","description":"Дата й час завантаження файлу. Дата у форматі ISO 8601."}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Можливі відповіді з помилками","content":{"application/json":{}}},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Список вкладень"}}}}
```

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

> Повертає \*\*потік файлу\*\*, вказаного за \`fileId\`, якщо відправлення належить автентифікованому клієнту.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/shipments/{shipmentNumber}/attachments/{fileId}":{"get":{"tags":["Shipments"],"description":"Повертає **потік файлу**, вказаного за `fileId`, якщо відправлення належить автентифікованому клієнту.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","parameters":[{"in":"path","name":"shipmentNumber","required":true,"description":"Номер відправлення.","schema":{"type":"string"}},{"in":"path","name":"fileId","required":true,"description":"Унікальний ідентифікатор файлу.","schema":{"type":"string"}}],"responses":{"200":{"description":"Файл.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Неможливо обробити сутність.","content":{"application/json":{}}},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Завантажити вкладення"}}}}
```

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

> Цей метод створює запит на повторну доставку для відправлення, яке наразі зберігається на складі довгострокового зберігання (LTS).\
> \
> Основні правила:\
> \
> \- Доступний лише для відправлень, які наразі перебувають на довгостроковому зберіганні (LTS).\
> \- Для одного відправлення дозволено не більше 4 завершених послуг повторної доставки.\
> \- Послугу повторної доставки не можна замовити, якщо для відправлення вже існує запит на переадресацію (Redirecting), повернення (Return) або повторну доставку (Repeat Delivery) зі статусом \`NeedProcessing\` або \`InProgress\`.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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"}}}},"Time-out":{"description":"Час очікування з’єднання вичерпано","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/shipments/modification/repeat-delivery":{"post":{"tags":["Shipments"],"summary":"Створити повторну доставку","description":"Цей метод створює запит на повторну доставку для відправлення, яке наразі зберігається на складі довгострокового зберігання (LTS).\n\nОсновні правила:\n\n- Доступний лише для відправлень, які наразі перебувають на довгостроковому зберіганні (LTS).\n- Для одного відправлення дозволено не більше 4 завершених послуг повторної доставки.\n- Послугу повторної доставки не можна замовити, якщо для відправлення вже існує запит на переадресацію (Redirecting), повернення (Return) або повторну доставку (Repeat Delivery) зі статусом `NeedProcessing` або `InProgress`.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shipmentId","recipient"],"properties":{"shipmentId":{"type":"integer","description":"Ідентифікатор відправлення на довгостроковому зберіганні.\n\n**🔻Це поле є обов'язковим.**\n"},"payerType":{"type":"string","nullable":true,"description":"Визначає, хто відповідає за оплату послуги повторної доставки.\n\nДопустимі значення:\n- Sender\n- Recipient\n- ThirdPerson\n\nЯкщо поле не передано, послугу оплачує користувач, який створює замовлення.\n","enum":["Sender","Recipient","ThirdPerson"]},"payerContractNumber":{"type":"string","nullable":true,"description":"Обов'язковий параметр для B2B-клієнтів (юридичних осіб з оплатою за договором).\n"},"note":{"type":"string","description":"Будь-який коментар до замовлення.\n"},"recipient":{"type":"object","description":"Дані одержувача для повторної доставки.\n\n**🔻Це поле є обов'язковим.**\n","required":["name","phone","email","countryCode"],"properties":{"name":{"type":"string","description":"Повне ім'я одержувача.\n\n**🔻Це поле є обов'язковим.**\n"},"phone":{"type":"string","description":"Номер телефону одержувача.\n\n**🔻Це поле є обов'язковим.**\n"},"email":{"type":"string","description":"Електронна адреса одержувача.\n\n**🔻Це поле є обов'язковим.**\n"},"companyTin":{"type":"string","nullable":true,"description":"Податковий ідентифікаційний номер компанії, якщо одержувачем є юридична особа.\n"},"companyName":{"type":"string","nullable":true,"description":"Назва компанії.\n"},"countryCode":{"type":"string","description":"Код країни доставки відповідно до стандарту ISO 3166-1 Alpha-2.\n\n**🔻Це поле є обов'язковим.**\n","pattern":"^[A-Z]{2}$"},"eoriCode":{"type":"string","nullable":true,"description":"Код EORI.\n"},"divisionId":{"type":"integer","nullable":true,"description":"Ідентифікатор відділення/поштомата.\n\n**🔹Це поле є обов'язковим, якщо доставка здійснюється до відділення.**\n"},"settlementId":{"type":"integer","nullable":true,"description":"Ідентифікатор населеного пункту.\n"},"address":{"type":"object","nullable":true,"description":"Об'єкт адреси.\n"},"latitude":{"type":"number","nullable":true,"description":"Координата широти.\n"},"longitude":{"type":"number","nullable":true,"description":"Координата довготи.\n"},"addressParts":{"type":"object","nullable":true,"description":"Деталі адреси доставки.\n\nОбов'язковий, якщо `divisionId` має значення `null`.\n\nЯкщо `divisionId` має значення `null`, доставка здійснюється за адресою, і поля `city`, `street` та `building` стають обов'язковими.\n","properties":{"city":{"type":"string","nullable":true,"description":"Назва міста.\n\n**🔹Це поле є обов'язковим, якщо доставка здійснюється за адресою.**\n"},"street":{"type":"string","nullable":true,"description":"Назва вулиці.\n\n**🔹Це поле є обов'язковим, якщо доставка здійснюється за адресою.**\n"},"building":{"type":"string","nullable":true,"description":"Номер будинку.\n\n**🔹Це поле є обов'язковим, якщо доставка здійснюється за адресою.**\n"},"postCode":{"type":"string","nullable":true,"description":"Поштовий індекс.\n"},"region":{"type":"string","nullable":true,"description":"Регіон.\n"},"flat":{"type":"string","nullable":true,"description":"Номер квартири.\n"},"block":{"type":"string","nullable":true,"description":"Блок.\n"},"note":{"type":"string","nullable":true,"description":"Додаткові примітки щодо доставки.\n"}}}}}}}}}},"responses":{"200":{"description":"Запит на повторну доставку успішно створено.","content":{"application/json":{"schema":{"type":"object","properties":{"cost":{"type":"number","description":"Вартість послуги повторної доставки."},"currency":{"type":"string","description":"Код валюти відповідно до стандарту ISO 4217."},"currencySymbol":{"type":"string","description":"Символ валюти."},"scheduledDeliveryDate":{"type":"string","format":"date-time","description":"Орієнтовна дата доставки у форматі ISO 8601."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Помилка валідації.","content":{"application/json":{}}},"503":{"$ref":"#/components/responses/Time-out"}}}}}}
```

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

> Цей метод скасовує поточний активний запит на повторну доставку, пов'язаний із зазначеним відправленням.\
> \
> Використовуйте цей метод, якщо необхідно скасувати запит на повторну доставку, який ще не було оброблено. Скасування доступне лише доти, доки замовлення на повторну доставку ще перебуває в обробці.\
> \
> \*\*Основні правила:\*\*\
> \- Скасування доступне лише доти, доки замовлення на повторну доставку ще перебуває в обробці.\
> \- Після завершення повторної доставки її неможливо скасувати.\
> \
> 🔹\*\*Опис елементів керування:\*\*\
> \
> \*\*SCHEMA\*\*\</br>\
> Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\
> \- \*\*Single line description\*\*\</br>\
> &#x20; Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\
> \- \*\*Multiline description\*\*\</br>\
> &#x20; Розширений опис, який відображає більше одного рядка тексту.\
> \
> \*\*EXAMPLE\*\*\</br>\
> Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.<br>

```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"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 годину у заголовку"}}},"paths":{"/shipments/modification/repeat-delivery/delete/{shipmentID}":{"delete":{"tags":["Shipments"],"summary":"Скасувати повторну доставку","description":"Цей метод скасовує поточний активний запит на повторну доставку, пов'язаний із зазначеним відправленням.\n\nВикористовуйте цей метод, якщо необхідно скасувати запит на повторну доставку, який ще не було оброблено. Скасування доступне лише доти, доки замовлення на повторну доставку ще перебуває в обробці.\n\n**Основні правила:**\n- Скасування доступне лише доти, доки замовлення на повторну доставку ще перебуває в обробці.\n- Після завершення повторної доставки її неможливо скасувати.\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**</br>\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**</br>\n  Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**</br>\n  Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**</br>\nПоказує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.\n","operationId":"cancelRepeatDelivery","parameters":[{"name":"shipmentID","in":"path","required":true,"description":"Ідентифікатор відправлення, для якого необхідно скасувати замовлення на повторну доставку.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Замовлення на повторну доставку успішно скасовано. Повертає часову позначку скасування.","content":{"application/json":{"schema":{"type":"object","properties":{"deletedAt":{"type":"string","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$"}},"required":["deletedAt"]}}}},"422":{"description":"Неможливо обробити сутність. Скасування неможливо виконати.","content":{"application/json":{}}}}}}}}
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://api-portal.novapost.com/metodi-1/metodi/draft.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.