> 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/readme/vidpravlennya.md). # Відправлення
Список методів роботи з відправленнями
Method nameDescription
Create Shipment

Create a Shipment Document. This API method is engineered to streamline the process of generating a shipping document for logistics operations through Nova Post. By submitting key data, such as the originating and destination addresses for the shipment, users can effortlessly create a document detailing the transportation of goods. This method includes optional fields for customs authorities, accommodating shipments that cross borders. The API response will provide the unique identifier of the generated document along with other relevant information.

Settlement validation rules: For shipments to or from Moldova and Ukraine, the settlement (city) must be successfully resolved. If the provided city value cannot be matched to a settlement, the request will fail with the error: validation.condition.recipient_settlement_not_defined.

Additional requirement: For shipments that require customs clearance (imports), the client invoice must be uploaded as a file through the POST /shipments/uploads/{id} method (after shipment creation).

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

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

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

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

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

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

1. Європа:

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

2. Україна:

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

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

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

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

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

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

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

  • Поведінка методу залежить від напрямку відправлення:

    • Для напрямку UA-UA: метод працює для доставок у поштомат, PUDO або за адресою.
    • Для напрямку EU-EU: метод працює для доставок у PUDO або за адресою. Не підтримується, якщо батьківське відправлення було доставлене у поштомат.
  • Якщо доставка батьківського відправлення була за адресою, створюється заявка на забір автоматично. Заявка на забір створюється лише якщо повернення не було відправлене з відділення.

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

Розрахунок вартості доставкиЦей API-метод дозволяє розрахувати орієнтовну вартість доставки та термін доставки для вашого вантажу. Вартість та термін доставки розраховуються на основі таких факторів, як вага, габарити, місце призначення та спосіб доставки. Надавши необхідні дані про вантаж і відправлення, ви можете отримати орієнтовну вартість доставки товарів. Відповідь зазвичай містить розраховану вартість та заплановану дату доставки на основі наданої інформації.
Отримання статусу верифікації для відправлень UA→WorldПовертає статуси верифікації для міжнародних відправлень для напрямку UA→World («міжнародне відправлення з України у світ»). Відповіді та помилки від основної системи проксируются без змін.
Завантажити файл до відправлення

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

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

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

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

  1. "Я хочу завантажити PDF-інвойс клієнта до відправлення 980911" — передайте вміст, закодований у base64, у параметрі "file" та встановіть "fileName": "invoice.pdf".
  2. "Я хочу додати фотографію товару у форматі JPEG" — закодуйте фотографію у base64 та встановіть "fileName": "product-photo.jpeg".
Друк транспортних документівЦей API-метод дозволяє отримати маркування транспортного документа у форматі PDF за номером документа. Маркування документа є документом для друку, який клієнти можуть прикріпити або наклеїти на свій вантаж під час його відправлення. Вказавши номер документа в запиті, ви можете згенерувати PDF-файл, що містить маркування документа, для зручного друку.
Базове відстеження

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Скасування доступне лише доти, доки замовлення на повторну доставку ще перебуває в обробці.
  • Після завершення повторної доставки її неможливо скасувати.
Діаграма взаємодії систем при створенні відправлення ```mermaid flowchart LR A((Start)) -->|POST shipments| B([Shipment created]) B -->|PUT shipments by id| C([Edit shipment]) B -->|GET shipment by id| D([Shipment info]) B -->|GET shipment label| E([Label print]) E --> F((End)) B -->|GET shipment status| G([Shipment status]) G -->|POST redirect shipment| H([Redirect]) G -->|POST add parcel info| I([Add parcel info]) G -->|POST cancel shipment| J([Cancellation]) J --> K((End)) G -->|GET print document| L([Label print]) L --> M((End)) style A fill:#ffffff,color:#E30613,stroke:#E30613,stroke-width:2px style B fill:#E30613,color:#ffffff,stroke:#E30613,stroke-width:2px style C fill:#ffffff,color:#222222,stroke:#E30613,stroke-width:2px style D fill:#ffffff,color:#222222,stroke:#E30613,stroke-width:2px style E fill:#ffffff,color:#222222,stroke:#E30613,stroke-width:2px style G fill:#ffffff,color:#222222,stroke:#E30613,stroke-width:2px style H fill:#ffffff,color:#222222,stroke:#E30613,stroke-width:2px style I fill:#ffffff,color:#222222,stroke:#E30613,stroke-width:2px style J fill:#ffffff,color:#222222,stroke:#E30613,stroke-width:2px style L fill:#ffffff,color:#222222,stroke:#E30613,stroke-width:2px style F fill:#E30613,color:#000000,stroke:#E30613,stroke-width:2px style K fill:#E30613,color:#000000,stroke:#E30613,stroke-width:2px style M fill:#E30613,color:#000000,stroke:#E30613,stroke-width:2px ```
## Список відправлень > Цей API-метод дозволяє отримати список транспортних документів (відправлень), які ви створили. Використовуючи цей метод, ви можете отримати доступ до транспортних документів, що належать вам або вашому обліковому запису. Відповідь міститиме деталі кожного відправлення, такі як ідентифікатор відправлення, номер, отримувач, деталі вантажу та іншу релевантну інформацію.\
\ > \ > 🔹\*\*Опис елементів керування:\*\*\ > \ > \*\*SCHEMA\*\*\ > \ > Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\ > \- \*\*Single line description\*\*\
\ > Опис, що вміщується в один рядок; текст, який не вміщується, залишається прихованим.\ > \- \*\*Multiline description\*\*\
\ > Розширений опис, що відображає більше одного рядка тексту.\ > \ > \*\*EXAMPLE\*\*\ > \ > Показує готовий приклад JSON із коректно заповненими значеннями для демонстрації того, як має виглядати валідний запит або відповідь.
```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-метод дозволяє отримати список транспортних документів (відправлень), які ви створили. Використовуючи цей метод, ви можете отримати доступ до транспортних документів, що належать вам або вашому обліковому запису. Відповідь міститиме деталі кожного відправлення, такі як ідентифікатор відправлення, номер, отримувач, деталі вантажу та іншу релевантну інформацію.
\n\n🔹**Опис елементів керування:**\n\n**SCHEMA**\n\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**
\n Опис, що вміщується в один рядок; текст, який не вміщується, залишається прихованим.\n- **Multiline description**
\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 дозволяє оновити існуючий транспортний документ шляхом передачі ідентифікатора документа та повного набору оновлених даних. Вказавши ідентифікатор документа та надавши всі необхідні дані, ви можете замінити попередню версію документа новими даними з запиту. У відповіді зазвичай міститься інформація про успішність операції оновлення, а також можуть бути наведені деталі зміненого документа.\ > \ > Обмеження оновлення:\ > \- Дані відправлення можуть бути оновлені \*\*лише тоді, коли відправлення перебуває у статусі \`ReadyToShip\`\*\*. \ > \- Оновлення дозволені \*\*лише якщо ярлик (лейбл) відправлення ще не був надрукований\*\*.\ > \- Якщо відправлення не перебуває у статусі \`ReadyToShip\` або ярлик уже був надрукований, запит на оновлення буде відхилено з помилкою валідації.\ > \ > 🔹\*\*Опис елементів керування:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\ > \- \*\*Single line description\*\*\
\ > Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\ > \- \*\*Multiline description\*\*\
\ > Розширений опис, який відображає більше одного рядка тексту.\ > \ > \*\*EXAMPLE\*\*\
\ > Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.
```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**
\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**
\n Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**
\n Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**
\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**.
\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\*\*\
\ > Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\ > \- \*\*Single line description\*\*\
\ > Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\ > \- \*\*Multiline description\*\*\
\ > Розширений опис, який відображає більше одного рядка тексту.\ > \ > \*\*EXAMPLE\*\*\
\ > Показує готовий приклад JSON з коректно заповненими значеннями, щоб продемонструвати, як має виглядати валідний запит або відповідь.
```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**
\nВідображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.\n- **Single line description**
\n Опис, який вміщується в один рядок; текст, що не вміщується, залишається прихованим.\n- **Multiline description**
\n Розширений опис, який відображає більше одного рядка тексту.\n\n**EXAMPLE**
\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":"Видалити транспортний документ"}}}} ``` --- # 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/readme/vidpravlennya.md?ask=&goal= ``` `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.