> 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/stvorennya-vidpravlen/mizhnarodni-vidpravlennya-z-ukrayini.md).

# Міжнародні відправлення з України

<details>

<summary>Shipment API Interaction Flow</summary>

```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
```

</details>

<details>

<summary>Схема (Об'єкт)</summary>

<table><thead><tr><th width="127">Поле</th><th width="91" align="center">Тип</th><th width="132" align="center">Обов'язкове</th><th>Опис</th></tr></thead><tbody><tr><td><strong>status</strong></td><td align="center">enum</td><td align="center">так</td><td><p>Визначає поточний статус транспортного документа, відстежуючи його проходження через життєвий цикл доставки. Статуси відображають кожен ключовий етап:</p><ul><li><code>Draft</code>: Документ знаходиться на початковій стадії, ще не завершений.</li><li><code>Accepted</code>: Перевірений та прийнятий, документ готовий до наступних етапів.</li><li><code>Issued</code>: Документ завершено та готовий до відправлення.</li><li><code>ReadyToShip</code>: Вказує, що відправлення підготовлено до транспортування після створення експрес-накладної. Лише це значення може бути вказане при створенні відправлення.</li><li><code>Deleted</code>: Документ видалено із системи.</li><li><code>Returned</code>: Відправлення повернено відправнику.</li><li><code>Utilized</code>: Вказує, що фізичні товари, пов’язані з транспортним документом, були утилізовані або знищені, і документ закрито.</li></ul><p>Allowed: <code>ReadyToShip</code></p></td></tr><tr><td><strong>clientOrder</strong></td><td align="center">string</td><td align="center">так</td><td><p>Представляє всі можливі ідентифікатори замовлення, пов’язані з відправленням. Ці ідентифікатори задаються клієнтом для внутрішнього відстеження та є важливими для контролю відправлення протягом усього його маршруту. Усі введені значення можуть відстежуватися в системі трекінгу.</p><p>Constraints: Max 50 chars</p></td></tr><tr><td><strong>note</strong></td><td align="center">string</td><td align="center">так</td><td><p>Тут може бути вказана будь-яка додаткова інформація або спеціальні інструкції щодо замовлення. Це можуть бути інструкції з доставки, особливі умови обробки або інші важливі деталі, що сприяють обробці відправлення.</p><p>Constraints: Max 255 chars</p></td></tr><tr><td><strong>deliveryType</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Визначає тип тарифу, який буде застосовано до відправлення під час створення або оновлення.</p><ul><li><code>standard</code>: Стандартний міжнародний тариф доставки.</li><li><code>economy</code>: Економний міжнародний тариф доставки.</li><li><code>express</code>: Експрес міжнародний тариф доставки.</li></ul><p>Якщо поле не передано, тип тарифу визначається автоматично відповідно до поточних бізнес-правил, і існуюча логіка створення відправлення залишається без змін.</p></td></tr><tr><td><strong>payerType</strong></td><td align="center">enum</td><td align="center">так</td><td><p>Визначає, хто несе відповідальність за оплату послуг доставки. Тип платника визначає сторону, яка покриває витрати:</p><ul><li><code>Sender</code>: Відправник оплачує доставку.</li><li><code>Recipient</code>: Одержувач оплачує доставку.</li><li><code>ThirdPerson</code>: Третя сторона, не відправник і не одержувач, оплачує доставку. При виборі 'ThirdPerson' поле 'payerContractNumber' має містити номер договору платника. Детальніше див. статтю <a href="https://api-portal.novapost.com/en/api-methods/payment/">Оплата послуг доставки через API Nova Post</a>. Це поле також використовується при формуванні інвойсу.</li></ul><p>Allowed: <code>Sender</code>┃<code>Recipient</code>┃<code>ThirdPerson</code></p></td></tr><tr><td><strong>payerContractNumber</strong></td><td align="center">string┃null</td><td align="center">так</td><td><p>Це поле є обов’язковим у таких випадках:</p><ul><li>Коли <code>payerType</code> має значення <code>ThirdPerson</code>. Воно повинно містити номер договору платника. Для клієнтів з України також дозволено передавати код ЄДРПОУ замість номера договору.</li><li>Коли <code>payerType</code> має значення <code>Sender</code> або <code>Recipient</code> і використовується безготівковий спосіб оплати.</li></ul><p>Якщо це поле не передано у зазначених випадках, спосіб оплати автоматично буде встановлений як готівковий.</p><p>Переконайтеся, що надана інформація є коректною, оскільки вона необхідна для правильної обробки платежу.</p><p>Детальніше див. статтю <a href="https://api-portal.novapost.com/en/api-methods/payment/">Оплата послуг доставки через API Nova Post</a>.</p><p>Constraints: 2 to 20 chars</p></td></tr><tr><td><strong>services</strong></td><td align="center">array</td><td align="center">ні</td><td>Містить інформацію про додаткові послуги для відправлення.</td></tr><tr><td>services.<strong>shipmentParcelRowNumber</strong></td><td align="center">integer</td><td align="center">так</td><td>Вказує номер рядка посилки, до якої застосовується послуга. Значення має відповідати <code>rowNumber</code> існуючої посилки в масиві <code>parcels</code>. Для послуг, що застосовуються до <strong>всього відправлення</strong> (наприклад, <code>ExpBackwardGoods</code>), це поле повинно мати значення <code>null</code>.</td></tr><tr><td>services.<strong>serviceCode</strong></td><td align="center">string</td><td align="center">так</td><td><p>Код, що визначає послугу. <strong>Перелік доступних кодів та їх значень:</strong></p><ul><li><p><code>COD</code> — Послуга накладеного платежу (COD) дозволяє одержувачу оплатити товар безпосередньо при отриманні без необхідності передоплати. Відправник може додати цю послугу до відправлення, а одержувач має можливість оплатити товар під час доставки та оглянути його перед оплатою, з урахуванням обмежень способів оплати, встановлених для конкретних країн. Доступні напрямки:</p><ul><li>Польща → Україна</li><li>Чехія → Україна</li><li>Німеччина → Україна</li><li>Словаччина → Україна</li><li>Чехія → Чехія</li><li>Польща → Польща</li><li>Німеччина → Німеччина</li><li>Румунія → Молдова</li></ul></li></ul><p>🔸<strong>Послуга COD планується до розширення на інші країни та напрямки доставки в майбутньому, як для міжнародних відправлень, так і в межах європейських країн.</strong></p><ul><li><code>ExpBackwardGoods</code> — Дозволяє оформити зворотну доставку для основного відправлення</li><li><code>ExpBackwardCreditDoc</code> — Дозволяє оформити зворотну доставку підписаних документів для внутрішніх відправлень документів у Молдові. Послуга доступна лише для юридичних осіб і лише для відправлень типу <strong>Documents</strong>. Зворотне відправлення створюється як окрема доставка документів (кур'єром або оператором), і платником завжди є Одержувач за безготівковим договором. Недоступна для каналів Parcel Locker та PUDO. На першому етапі послуга доступна лише для обраних юридичних осіб.</li></ul><p>🔹<strong>Це поле є обов’язковим для групи</strong> <code>services</code><strong>.</strong></p></td></tr><tr><td>services.<strong>serviceName</strong></td><td align="center">string</td><td align="center">так</td><td><p>Назва послуги.</p><p>Допустимі значення включають:</p><ul><li><code>PaymentControl</code> — послуга контролю оплати.</li><li><code>MoneyTransfer</code> — послуга грошового переказу.</li><li>Інші типи послуг, доступні в групі <code>services</code>.</li></ul><p>🔹<strong>Це поле є обов’язковим у межах групи</strong> <code>services</code><strong>.</strong></p></td></tr><tr><td>services.<strong>serviceId</strong></td><td align="center">string</td><td align="center">так</td><td><p>Унікальний ідентифікатор (reference ID) обраної послуги.</p><p>Це значення має відповідати ідентифікатору послуги, який повертається системою. При створенні або оновленні відправлення необхідно скопіювати та використати точне значення <code>serviceId</code>, отримане у відповіді довідника послуг, без змін.</p><p>🔹<strong>Це поле є обов’язковим у межах групи</strong> <code>services</code><strong>.</strong></p></td></tr><tr><td>services.<strong>amount</strong></td><td align="center">number</td><td align="center">так</td><td><p>Загальна сума, яку одержувач має сплатити в рамках послуги COD.</p><p>🔹<strong>Це поле є обов’язковим для групи</strong> <code>services</code><strong>.</strong></p></td></tr><tr><td>services.<strong>contractNumber</strong></td><td align="center">string┃null</td><td align="center">так</td><td><p>Номер договору платника, відповідального за обрану послугу. Цей параметр використовується для ідентифікації договору, в рамках якого здійснюється оплата послуги.</p><p>Поле є обов’язковим, якщо платником послуги виступає <strong>третя сторона</strong> або використовується безготівкова форма оплати. Якщо поле не передано, оплата може бути оброблена відповідно до стандартних правил білінгу.</p></td></tr><tr><td>services.<strong>payerType</strong></td><td align="center">string</td><td align="center">так</td><td><p>Визначає, хто відповідає за оплату послуги. Тип платника визначає сторону, яка покриває витрати:</p><ul><li><code>Recipient</code> — єдине допустиме значення для послуги COD.</li><li><code>Sender</code>, <code>Recipient</code> — допустимі значення для послуги ExpBackwardGoods.</li><li><code>Sender</code>, <code>Recipient</code>, <code>ThirdPerson</code> — допустимі значення для послуги BackwardDelGoods.</li></ul><p><strong>🔻Це поле є обов’язковим</strong></p></td></tr><tr><td>services.<strong>additionalParameters</strong></td><td align="center">string</td><td align="center">так</td><td>Додаткові параметри для послуги.</td></tr><tr><td>services.additionalParameters.<strong>cod</strong></td><td align="center">string</td><td align="center">так</td><td><p>Додаткові параметри для налаштування COD.</p><p>🔹<strong>Ці параметри є обов’язковими та застосовуються лише для послуги COD</strong></p></td></tr><tr><td>services.additionalParameters.cod.<strong>bankAccount</strong></td><td align="center">object</td><td align="center">ні</td><td>Інформація про банківський рахунок, на який буде здійснено переказ коштів. Включає суму переказу, валюту операції, ідентифікатори рахунку та сторону, яка сплачує комісію.</td></tr><tr><td>services.additionalParameters.cod.bankAccount.<strong>amount</strong></td><td align="center">number</td><td align="center">так</td><td><p>Сума, яка буде перерахована на рахунок відправника після оплати. Визначає суму, яку одержувач має сплатити при отриманні. Можлива автоматична конвертація валюти залежно від країни відправника або одержувача.</p><p>🔹<strong>Це поле є обов’язковим для групи</strong> <code>services.additionalParameters.cod.bankAccount</code><strong>.</strong></p></td></tr><tr><td>services.additionalParameters.cod.bankAccount.<strong>currencyCode</strong></td><td align="center">string</td><td align="center">так</td><td><p>Валюта транзакції, визначена договором відправника. Вказується відповідно до стандарту ISO 4217.</p><p>🔸<strong>За замовчуванням використовується валюта країни відправника, але можливе ручне встановлення (функціонал у розробці).</strong><br>Pattern: ^[A-Z]{3}$</p></td></tr><tr><td>services.additionalParameters.cod.bankAccount.<strong>bankAccountId</strong></td><td align="center">string</td><td align="center">так</td><td><p>Ідентифікаційний код фізичної або юридичної особи, який використовується для її унікальної ідентифікації в системі та перевірки наявності активного договору і фінансових послуг. Аналогічний значенню, що передається у полі <code>companyTin</code>.</p><p>🔹<strong>Це поле є обов’язковим для групи</strong> <code>services.additionalParameters.cod.bankAccount</code><strong>.</strong></p><p>🔸<strong>Має містити податковий номер або аналогічний ідентифікатор (ЄДРПОУ, TIN, NIP).</strong></p></td></tr><tr><td>services.additionalParameters.cod.bankAccount.<strong>bankAccountName</strong></td><td align="center">string</td><td align="center">так</td><td><p>IBAN</p><p>🔹<strong>Це поле є обов’язковим для групи</strong> <code>services.additionalParameters.cod.bankAccount</code><strong>.</strong></p><p>🔸<strong>Має містити повний номер рахунку у форматі IBAN.</strong></p></td></tr><tr><td>services.additionalParameters.cod.bankAccount.<strong>description</strong></td><td align="center">string</td><td align="center">так</td><td>Додатковий опис платіжних реквізитів.</td></tr><tr><td>services.additionalParameters.cod.bankAccount.<strong>commissionPayer</strong></td><td align="center">string</td><td align="center">так</td><td><p>Визначає сторону, яка сплачує комісію:</p><ul><li><code>Recipient</code></li><li><code>Sender</code></li></ul><p>🔹<strong>Це поле є обов’язковим для групи</strong> <code>services.additionalParameters.cod.bankAccount</code><strong>.</strong></p></td></tr><tr><td>services.additionalParameters.<strong>backwardDelivery</strong></td><td align="center">object</td><td align="center">так</td><td><p>Додаткові параметри для налаштування зворотної доставки.</p><p>🔹<strong>Ці параметри є обов’язковими та застосовуються лише для послуги ExpBackwardGoods.</strong></p></td></tr><tr><td>services.additionalParameters.backwardDelivery.<strong>description</strong></td><td align="center">string</td><td align="center">ні</td><td>Опис товарів, що підлягають поверненню. Це значення використовується для інформаційних та операційних цілей під час процесу зворотної доставки.</td></tr><tr><td><strong>invoice</strong></td><td align="center">object</td><td align="center">ні</td><td><p>Цей об’єкт містить необхідні дані для митних органів для ефективної обробки відправлення, включаючи розрахунок мит та податків, а також підтвердження відповідності імпортно-експортним вимогам. Структурований формат інвойсу забезпечує легкий доступ до всієї необхідної інформації, що сприяє більш швидкому проходженню через кордон.</p><p>Оновлена логіка обробки значень інвойсу. Клієнти повинні передавати лише два параметри в об’єкті invoice:</p><ul><li><code>cost</code> — загальна задекларована вартість інвойсу</li><li><code>currency</code> — код валюти інвойсу</li></ul><p><strong>🔸Містить деталі інвойсу, які є обов’язковими для міжнародних відправлень, що проходять митне оформлення.</strong></p></td></tr><tr><td>invoice.<strong>customerNumber</strong></td><td align="center">string┃null</td><td align="center">так</td><td><p>Унікальний ідентифікатор/номер інвойсу, що супроводжує товари у відправленні, який генерується безпосередньо клієнтом. Використовується для митного оформлення (експорт та імпорт), оскільки забезпечує чіткий зв’язок між товарами у відправленні та супровідною документацією, включаючи вартість, походження та інші необхідні дані.</p><p>Якщо інвойс у відправленні існує, але його дані відсутні — зокрема, його номер — обробка відправлення в інформаційній системі буде призупинена, термін митного оформлення збільшиться, а в гіршому випадку митні органи можуть відмовити в оформленні та ініціювати повернення в країну відправлення.</p></td></tr><tr><td>invoice.<strong>customerCreatedAt</strong></td><td align="center">string</td><td align="center">так</td><td><p>Необхідно передати дату, вказану в інвойсі, що супроводжує відправлення. Якщо дата відсутня у документі клієнта, можна використати дату створення відправлення.</p><p><strong>🔹Це поле є обов’язковим, якщо заповнено поле</strong> <code>invoice.customerNumber</code><strong>.</strong></p><p>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$</p></td></tr><tr><td>invoice.<strong>type</strong></td><td align="center">string</td><td align="center">так</td><td><p>Тип інвойсу клієнта, що супроводжує відправлення та використовується для митного декларування. Це поле повинно відповідати фактичному типу документа, вкладеного у відправлення. Доступні значення:</p><ul><li><code>Invoice</code> — комерційний інвойс для відправлень комерційного характеру</li><li><code>ProformaInvoice</code> — проформа-інвойс для відправлень некомерційного характеру</li></ul><p><strong>🔹Це поле є обов’язковим, якщо заповнено поле</strong> <code>invoice.customerNumber</code><strong>.</strong></p><p>Possible values: <code>Invoice</code> | <code>ProformaInvoice</code></p></td></tr><tr><td>invoice.<strong>incoterm</strong></td><td align="center">string</td><td align="center">так</td><td><p>Визначає умови поставки між продавцем і покупцем відповідно до правил Incoterms®. Ці умови регулюють розподіл витрат на доставку, страхування, митні платежі та ризики. Доступний обмежений набір значень:</p><ul><li><code>DAP</code> (Delivered at Place) - Одержувач відповідає за митне оформлення імпорту, сплату мит та податків.</li><li><code>DDP</code> (Delivered Duty Paid) - Відправник відповідає за митне оформлення імпорту та оплату всіх мит і податків.</li></ul><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p><p>Possible values: <code>DAP</code>,<code>DDP</code></p></td></tr><tr><td>invoice.<strong>exportReason</strong></td><td align="center">string</td><td align="center">так</td><td><p>Визначає загальну причину експорту товарів, що є необхідною для митних та інших регуляторних органів. Класифікація дозволяє визначити тип відправлення без деталізації. Використовується для спрощення обробки на митниці. Доступні значення:</p><ul><li><code>ForPersonalPurposes</code>: Товари для особистого використання або подарунки.</li><li><code>Selling</code>: Товари призначені для продажу.</li><li><code>Repair</code>: Товари відправляються на ремонт.</li><li><code>Return</code>: Товари повертаються відправнику або виробнику.</li><li><code>Other</code>: Інша причина, не зазначена вище.</li></ul><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p><p>Possible values: <code>ForPersonalPurposes</code>,<code>Selling</code>,<code>Repair</code>,<code>Return</code>,<code>Other</code></p></td></tr><tr><td>invoice.<strong>cost</strong></td><td align="center">number</td><td align="center">так</td><td><p>Загальна задекларована вартість інвойсу у вихідній валюті, яка повинна дорівнювати сумі всіх позицій інвойсу, розрахованій як <strong>(amount × cost)</strong> для кожного товару. Використовується для митного декларування.</p><p><strong>🔸Якщо передане значення <code>cost</code> не дорівнює сумі значень у масиві</strong> <code>items</code><strong>, воно буде автоматично перераховане системою.</strong></p><p><strong>🔸Значення перевіряються на точність десяткових знаків, і цифри після другого знака після коми ігноруються.</strong></p><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p><p>Constraints: Min 0┃Max 9999999.99</p></td></tr><tr><td>invoice.<strong>currency</strong></td><td align="center">string</td><td align="center">так</td><td><p>Код валюти інвойсу відповідно до стандарту ISO 4217. Усі товари в інвойсі повинні бути в одній валюті.</p><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p><p>Pattern: ^[A-Z]{3}$</p></td></tr><tr><td>invoice.<strong>payerFeesCustoms</strong></td><td align="center">string</td><td align="center">так</td><td><p>Визначає, хто оплачує митні послуги. Параметр визначає сторону, яка покриває витрати:</p><ul><li><code>Sender</code>: Відправник оплачує митні платежі.</li><li><code>Recipient</code>: Одержувач оплачує митні платежі.</li><li><code>ThirdPerson</code>: Третя сторона може оплачувати митні послуги лише за умови, що це дозволено і платник за доставку також є третьою стороною.</li></ul><p>Значення за замовчуванням — <strong>"Recipient"</strong>.<br>Це значення також буде застосовано автоматично, якщо вартість відправлення перевищує максимально допустиму (у валюті країни одержувача), при якій відправник може оплачувати митні платежі.</p><p><strong>🔹Цей параметр є обов’язковим і застосовується лише для напрямку UA-EU.</strong></p><p>Possible values: <code>Sender</code> | <code>Recipient</code> | <code>ThirdPerson</code></p></td></tr><tr><td>invoice.<strong>items</strong></td><td align="center">object</td><td align="center">так</td><td><p>Деталізований перелік товарів, що відправляються, включаючи обов’язкові описи та значення, необхідні для митного декларування та розрахунку митних платежів.</p><p><strong>Логіка:</strong> Якщо блок items передано, система перевіряє, чи дорівнює загальна сума всіх (<code>items.cost</code> × <code>items.amount</code>) значенню <code>invoice.cost</code>. Якщо ні — система оновлює <code>invoice.cost</code>, щоб вона дорівнювала сумі всіх товарів.</p><p><strong>🔸Необхідно передавати інформацію для кожного окремого товару у відправленні у вигляді масиву.</strong></p></td></tr><tr><td>invoice.items.<strong>id</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Унікальний ідентифікатор кожного товару у відправленні.</p><p><strong>🔹Це поле є необов’язковим.</strong></p></td></tr><tr><td>invoice.items.<strong>hsCode</strong></td><td align="center">string | null</td><td align="center">так</td><td><p>Код Гармонізованої системи (HS code) для кожного товару — стандартизований числовий метод класифікації товарів у міжнародній торгівлі. Це поле є обов’язковим для міжнародних відправлень, що проходять митне оформлення. Отримати коректний <code>hsCode</code> можна з довідника Класифікаторів вантажів (UKT ZED). Правила валідації:</p><ul><li><p><strong>Якщо країна відправника або отримувача — Молдова (MD) або Канада (CA):</strong></p><ul><li><code>hsCode</code> повинен складатися рівно з 10 цифрових символів.</li><li>Якщо значення містить більше ніж 10 цифр, воно буде <strong>скорочено</strong> праворуч.</li><li>Якщо значення містить менше ніж 10 цифр — помилка валідації.</li></ul></li><li><p><strong>Для всіх інших країн:</strong></p><ul><li><code>hsCode</code> повинен містити <strong>від 8 до 10 цифрових символів</strong> (включно).</li><li>Якщо значення містить менше ніж 8 цифр — помилка валідації.</li></ul></li><li><strong>Усі нецифрові символи автоматично видаляються перед валідацією.</strong></li><li><p><strong>Якщо значення поля <code>hsCode</code> дорівнює <code>210690</code> або <code>630900</code>, повинні виконуватися наступні умови:</strong></p><ul><li><code>measurementCode</code> повинен бути встановлений у значення <code>kg</code>.</li><li>Кожен товар із таким <code>hsCode</code> повинен бути унікальним — інвойс не може містити більше одного товару з кодом <code>210690</code> або <code>630900</code>.</li><li>Значення кількості не повинно перевищувати 10.</li></ul></li></ul><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або прямують за межі ЄС.</strong></p><p>Constraints: Max 255 chars</p></td></tr><tr><td>invoice.items.<strong>name</strong></td><td align="center">string</td><td align="center">так</td><td><p>Назва товару локальною мовою, що забезпечує точний опис для митного оформлення та логістичного планування. Назва повинна відповідати термінам з довідника Cargo Classifiers (UKT ZED), що гарантує відповідність стандартним класифікаційним кодам. Детальний опис допомагає точно ідентифікувати товар під час митного оформлення. Це поле підтримує Unicode-кодування, що дозволяє використовувати спеціальні символи через формат \uXXXX. Це забезпечує точне відображення назв товарів мовами з нелатинськими символами, підвищуючи зрозумілість у різних регуляторних середовищах.</p><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p><p>Constraints: Max 512 chars</p></td></tr><tr><td>invoice.items.<strong>nameEng</strong></td><td align="center">string</td><td align="center">так</td><td><p>Назва товару англійською мовою, що забезпечує його зрозумілість у міжнародній торгівлі та логістиці. Полегшує комунікацію з міжнародними партнерами та органами. Аналогічно полю <code>name</code>, підтримує Unicode-кодування через формат \uXXXX.</p><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p><p>Constraints: Max 512 chars</p></td></tr><tr><td>invoice.items.<strong>material</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Основний матеріал, з якого виготовлено товар, важливий для митного декларування та можливих обмежень.</p><p><strong>🔸Якщо поле не передано, буде застосовано значення за замовчуванням.</strong></p><p>Constraints: Max 50 chars</p></td></tr><tr><td>invoice.items.<strong>materialEng</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Опис матеріалу товару англійською мовою, що забезпечує універсальне розуміння його складу.</p><p><strong>🔸Якщо поле не передано, буде застосовано значення за замовчуванням.</strong></p><p>Constraints: Max 255 chars</p></td></tr><tr><td>invoice.items.<strong>madeInCountryCode</strong></td><td align="center">string | null</td><td align="center">ні</td><td><p>Код країни виробництва за стандартом ISO 3166-1 alpha-2, необхідний для визначення митних платежів та дотримання торговельних угод.</p><p><strong>🔸Поле не є обов’язковим, але відправлення з цим полем мають пріоритет під час митного оформлення.</strong></p><p>Pattern: ^[A-Z]{2}$</p></td></tr><tr><td>invoice.items.<strong>producerAndModel</strong></td><td align="center">string | null</td><td align="center">ні</td><td><p>Параметр містить виробника та модель пристрою в одному полі. Обов’язковий для таких категорій:</p><ul><li>Електроніка</li><li>Ноутбуки</li><li>Телефони</li><li>Побутова техніка</li><li>Інші подібні товари</li></ul><p><strong>🔸Поле не є обов’язковим, але відправлення з ним мають пріоритет під час митного оформлення.</strong></p><p>Constraints: Max 255 chars</p></td></tr><tr><td>invoice.items.<strong>actualWeight</strong></td><td align="center">integer | null</td><td align="center">так</td><td><p>Фактична загальна вага всіх одиниць товару в грамах (g).</p><p>Підтримувана точність: 10 грам (0.01 кг). Значення, що не кратні 10 г, округлюються вниз до найближчого меншого кратного.</p><p><strong>🔸Це поле є обов’язковим, якщо передано масив</strong> <code>invoice.items</code>.<br>Система перевіряє, що сума <code>actualWeight</code> по всіх товарах дорівнює загальній вазі відправлення (<code>parcels[].actualWeight</code>).</p><p>⚠️ВАЖЛИВО: Переконайтесь, що всі ваги коректно округлені і їх сума точно дорівнює вазі відправлення.</p><p>Constraints: Min 1┃Max 2147483647</p></td></tr><tr><td>invoice.items.<strong>measurementCode</strong></td><td align="center">string</td><td align="center">так</td><td><p>Одиниця виміру кількості товару (наприклад, штуки, кілограми, метри тощо), що стандартизує спосіб зазначення кількості.</p><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p><p>Constraints: Max 255 chars</p></td></tr><tr><td>invoice.items.<strong>amount</strong></td><td align="center">number</td><td align="center">так</td><td><p>Кількість товару, що відправляється, у відповідних одиницях виміру (<code>measurementCode</code>).</p><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p><p>Constraints: Min 0┃Max 9999999.99</p></td></tr><tr><td>invoice.items.<strong>cost</strong></td><td align="center">number</td><td align="center">так</td><td><p>Вартість за одиницю товару у валюті відправника.</p><p><strong>🔸Значення перевіряються на точність десяткових знаків, і цифри після другого знака після коми ігноруються.</strong></p><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p><p>Constraints: Min 0┃Max 9999999.99</p></td></tr><tr><td><strong>parcels</strong></td><td align="center">object</td><td align="center">так</td><td><p>Блок опису посилок. Масив містить об’єкти, кожен з яких відповідає за інформацію про окрему посилку.</p><p><strong>🔻Усі поля в цьому масиві є обов’язковими для заповнення.</strong></p></td></tr><tr><td>parcels.<strong>cargoCategory</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Визначає тип відправлення, що використовується для класифікації товарів у логістиці та митному оформленні. Категорія впливає на обробку відправлення, вартість доставки та необхідну документацію. Доступні категорії:</p><ul><li><code>parcel</code>: Невеликі та середні посилки, зазвичай для споживчих товарів.</li><li><code>documents</code>: Поштові відправлення з документами (листи, контракти, офіційні папери). Обмеження: вага до 1 кг, розміри — не більше 35 × 25 × 2 см.</li><li><p><code>pallet</code>: Вантаж у вигляді палети з фіксованими розмірами та ваговими обмеженнями (доступно для юридичних осіб у Business Cabinet Europe):</p><ul><li>До 250 кг, площа ~0.48 м², розміри 80 × 60 × 170 см</li><li>До 500 кг, площа ~0.96 м², розміри 120 × 80 × 170 см</li><li>До 750 кг, площа ~1.2 м², розміри 120 × 100 × 170 см</li><li>До 1000 кг, площа ~1.2 м², розміри 120 × 100 × 170 см</li></ul></li></ul><p>Possible values: <code>parcel</code> | <code>documents</code> | <code>pallet</code></p></td></tr><tr><td>parcels.<strong>parcelDescription</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Короткий опис вмісту посилки, що містить основну інформацію про характер вкладення. Використовується для логістики та митного оформлення. Опис повинен включати тип товарів, їх призначення та інші важливі деталі. Це поле підтримує Unicode-кодування (\uXXXX), що дозволяє використовувати спеціальні символи та нелатинські алфавіти.</p><p>Constraints: Max 255 chars</p></td></tr><tr><td>parcels.<strong>insuranceCost</strong></td><td align="center">number</td><td align="center">так</td><td><p>Задекларована вартість відправлення для страхування. Визначає максимальну суму компенсації у разі втрати або пошкодження.</p><p><strong>Обробка валюти:</strong></p><ul><li>Якщо <code>insuranceCurrencyCode</code> <strong>не передано</strong>, значення повинно бути у валюті країни відправника.</li><li>Якщо <code>insuranceCurrencyCode</code> <strong>передано</strong>, значення може бути в будь-якій підтримуваній валюті (ISO 4217), система автоматично конвертує її.</li></ul><p>🔸 <strong>Якщо використовується</strong> <code>insuranceCurrencyCode</code><strong>, всі посилки повинні мати однаковий код валюти. Інакше — помилка валідації.</strong></p><p><strong>Значення завжди повинно бути більше 0 незалежно від напрямку відправлення.</strong>"</p><p>Example: <code>1.5</code></p></td></tr><tr><td>parcels.<strong>insuranceCurrencyCode</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Код валюти ISO 4217 для страхувальної вартості (<code>insuranceCost</code>).</p><ul><li>Якщо поле передано — система автоматично конвертує значення у валюту країни відправника.</li><li>Якщо використовується — всі посилки повинні мати однаковий код валюти.</li></ul><p>🔹<strong>Це поле є необов’язковим.</strong>"</p><p>Pattern: ^[A-Z]{3}$</p></td></tr><tr><td>parcels.<strong>rowNumber</strong></td><td align="center">integer</td><td align="center">так</td><td><p>Порядковий номер посилки у відправленні. Якщо посилка одна — значення має бути 1.</p><p>Constraints: Min 1</p></td></tr><tr><td>parcels.<strong>width</strong></td><td align="center">integer</td><td align="center">так</td><td><p>Ширина посилки в міліметрах. Використовується разом з довжиною та висотою для розрахунку об’єму.</p><p>Constraints: Min 1</p></td></tr><tr><td>parcels.<strong>length</strong></td><td align="center">integer</td><td align="center">так</td><td><p>Довжина посилки в міліметрах. Використовується разом з шириною та висотою для розрахунку об’єму.</p><p>Constraints: Min 1</p></td></tr><tr><td>parcels.<strong>height</strong></td><td align="center">integer</td><td align="center">так</td><td><p>Висота посилки в міліметрах. Використовується разом з довжиною та шириною для розрахунку об’єму.</p><p>Constraints: Min 1</p></td></tr><tr><td>parcels.<strong>actualWeight</strong></td><td align="center">integer</td><td align="center">так</td><td><p>Фактична вага посилки у грамах (g).</p><p>Підтримувана точність: 10 грам (0.01 кг). Значення, що не кратні 10 г, округлюються вниз.</p><p><strong>🔸Це поле є обов’язковим, якщо передано масив</strong> <code>invoice.items</code>.<br>Система перевіряє, що <strong>сума</strong> <code>actualWeight</code> по всіх товарах дорівнює <strong>загальній вазі відправлення</strong> (<code>parcels[].actualWeight</code>).</p><p>⚠️ВАЖЛИВО: Переконайтесь, що вага всіх товарів співпадає із загальною вагою посилок."</p><p>Constraints: Min 1┃Max 2147483647</p></td></tr><tr><td><strong>sender</strong></td><td align="center">object</td><td align="center">так</td><td><p>Інформація про відправника, включаючи дані про фізичну або юридичну особу, відповідальну за відправлення.</p><p><strong>🔻Цей набір полів є обов’язковим</strong></p></td></tr><tr><td>sender.<strong>companyTin</strong></td><td align="center">string</td><td align="center">так</td><td><p>Податковий номер або аналогічний ідентифікатор юридичної особи (EDRPOU, TIN, NIP, IČO — для Словаччини).</p><p><strong>🔸Ці поля є обов’язковими для юридичної особи. Якщо вони не заповнені — відправник вважається фізичною особою</strong></p><p>Constraints: Max 20 chars</p></td></tr><tr><td>sender.<strong>companyName</strong></td><td align="center">string | null</td><td align="center">так</td><td><p>Офіційна назва компанії відправника. Використовується, якщо відправник є юридичною особою, для ідентифікації організації в документах та системі.</p><p>Constraints: Max 100 chars</p></td></tr><tr><td>sender.<strong>eoriCode</strong></td><td align="center">string | null</td><td align="center">так</td><td><p>Код EORI (Economic Operators Registration and Identification) використовується в Європейському Союзі для ідентифікації суб'єктів зовнішньоекономічної діяльності. Рекомендується для міжнародних відправлень до ЄС для коректного митного оформлення та уникнення затримок.</p><p>Constraints: 3 to 17 chars</p></td></tr><tr><td>sender.<strong>phone</strong></td><td align="center">string</td><td align="center">так</td><td><p>Контактний номер телефону відправника або представника компанії. Використовується для комунікації щодо відправлення (забір, уточнення, проблемні ситуації).</p><p><strong>Формат:</strong> Номер повинен бути у <strong>міжнародному форматі</strong> відповідно до стандарту <strong>E.164</strong>.</p><p>Приклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX</p><p><strong>Обмеження:</strong></p><ul><li>Номер повинен бути дійсним і доступним для зв’язку.</li><li>Якщо номер передано у локальному форматі, система спробує <strong>нормалізувати</strong> його, але така логіка обмежена. Рекомендується реалізувати <strong>front-end валідацію</strong> для перевірки формату.</li></ul><p><strong>🔻Це поле є обов’язковим</strong></p></td></tr><tr><td>sender.<strong>email</strong></td><td align="center">string</td><td align="center">так</td><td><p>Email-адреса відправника для отримання повідомлень, оновлень та комунікації щодо відправлення.</p><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.</strong></p></td></tr><tr><td>sender.<strong>name</strong></td><td align="center">string</td><td align="center">так</td><td><p>Повне ім’я відправника або контактної особи компанії. Використовується у всіх документах і комунікації.</p><p><strong>🔸Важливо для міжнародних відправлень EU → UA:</strong> Ім’я має бути вказане <strong>виключно латиницею</strong>. Використання кирилиці (включаючи українські літери) <strong>заборонено</strong> та призведе до помилки обробки на стороні Last Mile партнера.</p><p><strong>🔻Це поле є обов’язковим</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>sender.<strong>ioss</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Номер IOSS (Import One-Stop Shop) — необов’язковий параметр, який використовується для спрощення процесу декларування ПДВ для відправлень із країн, що не входять до ЄС, із задекларованою вартістю до 150 євро. Актуально для відправлень з країн поза ЄС до ЄС.</p><p>Constraints: Max 12 chars </p><p>Pattern: /^[a-zA-Z0-9]*$/u</p></td></tr><tr><td>sender.<strong>countryCode</strong></td><td align="center">string</td><td align="center">так</td><td><p>Дволітерний код країни відправника згідно стандарту ISO 3166-1 Alpha-2.</p><p><strong>🔻Це поле є обов’язковим</strong></p><p>Pattern: ^[A-Z]{2}$</p></td></tr><tr><td>sender.<strong>divisionNumber</strong></td><td align="center">string | null</td><td align="center">так</td><td><p>Обов’язкове поле, якщо відправлення здійснюється з відділення або поштомату. Містить унікальний номер відділення.</p><p><strong>🔹Це поле є обов’язковим, якщо відсутні</strong> <code>sender.addressParts</code> <strong>та</strong> <code>sender.divisionID</code></p><p>Example: <code>32521/1</code></p></td></tr><tr><td>sender.<strong>divisionID</strong></td><td align="center">integer | null</td><td align="center">так</td><td><p>Ідентифікатор відділення для точного визначення локації.</p><p><strong>🔹Це поле є обов’язковим, якщо відсутні</strong> <code>sender.addressParts</code> <strong>та</strong> <code>sender.divisionNumber</code></p><p>Constraints: Min 1</p></td></tr><tr><td>sender.<strong>addressParts</strong></td><td align="center">object</td><td align="center">так</td><td>Цей набір полів є обов’язковим при відправленні безпосередньо з адреси. Він містить детальні компоненти місця, з якого здійснюється відправлення, забезпечуючи точну ідентифікацію локації забору.</td></tr><tr><td>sender.addressParts.<strong>city</strong></td><td align="center">string</td><td align="center">так</td><td><p>Назва міста, з якого здійснюється відправлення. Використовується для точного визначення населеного пункту для забору або відправлення.</p><p><strong>🔹Це поле є обов’язковим, якщо</strong> <code>sender.divisionNumber</code> <strong>та</strong> <code>sender.divisionID</code> <strong>відсутні або порожні.</strong><br>🔸Для відправлень, де країна відправника — <strong>Молдова</strong> або <strong>Україна</strong>, значення міста перевіряється за внутрішніми довідниками населених пунктів. Якщо значення не може бути зіставлене з жодним населеним пунктом, створення відправлення буде відхилено.</p><p>Constraints: Max 100 chars</p></td></tr><tr><td>sender.addressParts.<strong>region</strong></td><td align="center">string</td><td align="center">так</td><td><p>Визначає ширшу адміністративну одиницю (наприклад, штат або область), до якої належить місто, надаючи додатковий контекст для місця відправлення.</p><p><strong>🔹Це поле є обов’язковим для відправлень, якщо країна відправника або отримувача — США, Ірландія або Канада.</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>sender.addressParts.<strong>street</strong></td><td align="center">string</td><td align="center">так</td><td><p>Назва вулиці за адресою відправника, необхідна для точного визначення місця забору або доставки.</p><p><strong>🔹Це поле є обов’язковим, якщо</strong> <code>sender.divisionNumber</code> <strong>та</strong> <code>sender.divisionID</code> <strong>відсутні або порожні.</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>sender.addressParts.<strong>postCode</strong></td><td align="center">string</td><td align="center">так</td><td><p>Поштовий індекс (ZIP-код), що відповідає адресі відправника. Використовується для сортування та маршрутизації відправлення.</p><p><strong>🔹Це поле є обов’язковим, якщо</strong> <code>sender.divisionNumber</code> <strong>та</strong> <code>sender.divisionID</code> <strong>відсутні або порожні.</strong></p><p>Constraints: Max 10 chars</p></td></tr><tr><td>sender.addressParts.<strong>building</strong></td><td align="center">string</td><td align="center">так</td><td><p>Номер або назва будівлі за вказаною адресою, що дозволяє точно ідентифікувати місце забору.</p><p><strong>🔹Це поле є обов’язковим, якщо</strong> <code>sender.divisionNumber</code> <strong>та</strong> <code>sender.divisionID</code> <strong>відсутні або порожні.</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>sender.addressParts.<strong>flat</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Номер квартири, офісу або приміщення в межах будівлі, якщо це застосовно, для точної ідентифікації місця відправлення.</p><p>Constraints: Max 10 chars</p></td></tr><tr><td>sender.addressParts.<strong>block</strong></td><td align="center">string | null</td><td align="center">ні</td><td><p>Позначає блок або секцію в межах житлового комплексу чи великої території (за наявності), допомагаючи точніше визначити місце відправлення.</p><p>Constraints: Max 100 chars</p></td></tr><tr><td>sender.addressParts.<strong>note</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Дозволяє вказати додаткову інформацію або інструкції щодо адреси відправника (наприклад, код домофона, вхід, бажаний час контакту), які можуть полегшити процес забору.</p><p>Constraints: Max 100 chars</p></td></tr><tr><td><strong>recipient</strong></td><td align="center">object</td><td align="center">так</td><td><p>Інформація про отримувача відправлення, що містить дані про фізичну або юридичну особу, відповідальну за отримання вантажу.</p><p><strong>🔻Цей набір полів є обов’язковим</strong></p></td></tr><tr><td>recipient.<strong>companyTin</strong></td><td align="center">string | null</td><td align="center">так</td><td><p>Податковий номер або еквівалентний ідентифікатор юридичної особи (EDRPOU, TIN, NIP, IČO — для Словаччини).</p><p><strong>🔸Ці поля є обов’язковими для юридичної особи. Якщо вони не заповнені — отримувач вважається фізичною особою</strong></p><p>Constraints: Max 20 chars</p></td></tr><tr><td>recipient.<strong>companyName</strong></td><td align="center">string | null</td><td align="center">так</td><td><p>Офіційна назва компанії отримувача. Використовується, якщо отримувач є юридичною особою, для ідентифікації організації у документах та системі.</p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.<strong>eoriCode</strong></td><td align="center">string | null</td><td align="center">так</td><td><p>Код EORI отримувача є важливим для митного оформлення при доставці до країн Європейського Союзу, особливо для юридичних осіб. Код не є обов’язковим, але рекомендований, оскільки сприяє швидшому митному оформленню та зменшує ризик затримок. Вимога залежить від типу товарів:</p><ol><li>Неакцизні товари: код EORI не є обов’язковим при доставці з України юридичній особі в Європі. Якщо код відсутній — він буде присвоєний автоматично.</li><li>Акцизні товари: код EORI є обов’язковим. Отримувач повинен отримати його до здійснення відправлення.</li></ol><p>Constraints: 3 to 17 chars</p></td></tr><tr><td>recipient.<strong>phone</strong></td><td align="center">string</td><td align="center">так</td><td><p>Контактний номер телефону отримувача або представника компанії. Використовується для повідомлень про доставку та комунікації під час обробки відправлення.</p><p><strong>Формат:</strong> номер повинен бути у <strong>міжнародному форматі</strong> відповідно до стандарту <strong>E.164</strong>.</p><p>Приклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX</p><p><strong>Обмеження:</strong></p><ul><li>Для доставки у відділення Nova Post в Європі допускаються українські мобільні номери.</li><li>Для доставки у <strong>партнерські точки</strong> (InPost, GLS, Venipak, Cargus тощо) та <strong>міжнародної адресної доставки</strong> номер повинен належати мобільному оператору країни отримувача. Якщо номер передано у локальному (неміжнародному) форматі, система спробує <strong>нормалізувати</strong> його до міжнародного формату, але внутрішній алгоритм не охоплює всі можливі варіанти. Якщо ваша система не підтримує front-end валідацію телефонних номерів, рекомендується повідомляти про некоректні кейси для можливого вдосконалення логіки нормалізації.</li></ul><p><strong>🔻Це поле є обов’язковим</strong></p></td></tr><tr><td>recipient.<strong>email</strong></td><td align="center">string</td><td align="center">так</td><td><p>Email-адреса отримувача, що використовується як цифровий канал зв’язку для отримання оновлень, повідомлень та важливої інформації щодо відправлення.</p><p><strong>🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або здійснюються за його межами.</strong></p></td></tr><tr><td>recipient.<strong>name</strong></td><td align="center">string</td><td align="center">так</td><td><p>Повне ім’я отримувача або основної контактної особи компанії. Це ім’я використовується у всій документації та комунікації, пов’язаній із відправленням.</p><p><strong>🔸Важливо для міжнародних відправлень EU → UA:</strong> Ім’я має бути вказане <strong>виключно латиницею</strong>. Використання кирилиці (включаючи українські літери) <strong>заборонено</strong> та призведе до помилок обробки.</p><p><strong>🔻Це поле є обов’язковим</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.<strong>countryCode</strong></td><td align="center">string</td><td align="center">так</td><td><p>Дволітерний код країни отримувача відповідно до стандарту ISO 3166-1 Alpha-2, який визначає країну призначення відправлення.</p><p><strong>🔻Це поле є обов’язковим</strong></p><p>Pattern: ^[A-Z]{2}$</p></td></tr><tr><td>recipient.<strong>divisionNumber</strong></td><td align="center">string | null</td><td align="center">так</td><td><p>Це поле є обов’язковим для посилок, що мають бути отримані у відділенні або поштоматі, та містить унікальний ідентифікатор відповідної локації.</p><p><strong>🔹Це поле є обов’язковим, якщо обидва поля</strong> <code>recipient.addressParts</code> <strong>та</strong> <code>recipient.divisionID</code> <strong>відсутні або порожні</strong></p></td></tr><tr><td>recipient.<strong>divisionID</strong></td><td align="center">integer | null</td><td align="center">так</td><td><p>Ідентифікатор відділення для точного визначення конкретної точки отримання.</p><p><strong>🔹Це поле є обов’язковим, якщо обидва поля</strong> <code>recipient.addressParts</code> <strong>та</strong> <code>recipient.divisionNumber</code> <strong>відсутні або порожні</strong></p><p>Constraints: Min 1</p></td></tr><tr><td>recipient.<strong>addressParts</strong></td><td align="center">object</td><td align="center">так</td><td><p>Цей набір полів використовується у випадках доставки за конкретною адресою та містить детальні компоненти місця доставки, забезпечуючи точну ідентифікацію локації отримання.</p><p><strong>🔸Значення вкладених полів не повинні дублювати одне одного. Надання однакової інформації у кількох внутрішніх полях призведе до помилки.</strong></p></td></tr><tr><td>recipient.addressParts.<strong>city</strong></td><td align="center">string</td><td align="center">так</td><td><p>Назва міста, до якого здійснюється доставка. Це поле забезпечує точне визначення населеного пункту отримувача.</p><p><strong>🔹Це поле є обов’язковим, якщо</strong> <code>recipient.divisionNumber</code> <strong>та</strong> <code>recipient.divisionID</code> <strong>відсутні або порожні.</strong><br>🔸Для відправлень, де країна отримувача — <strong>Молдова</strong> або <strong>Україна</strong>, значення міста перевіряється за внутрішніми довідниками населених пунктів. Якщо значення не може бути зіставлене з жодним записом, запит буде відхилено з помилкою:<code>validation.condition.recipient_settlement_not_defined</code>.</p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.addressParts.<strong>region</strong></td><td align="center">string</td><td align="center">так</td><td><p>Визначає адміністративну одиницю (штат, область або провінцію), до якої належить місто отримувача. Це поле є критично важливим для точної маршрутизації відправлення.</p><p><strong>🔹Це поле є обов’язковим для відправлень, якщо країна відправника або отримувача — США, Ірландія або Канада.</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.addressParts.<strong>street</strong></td><td align="center">string</td><td align="center">так</td><td><p>Назва вулиці за адресою отримувача, необхідна для точного визначення місця доставки.</p><p><strong>🔹Це поле є обов’язковим, якщо</strong> <code>recipient.divisionNumber</code> <strong>та</strong> <code>recipient.divisionID</code> <strong>відсутні або порожні.</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.addressParts.<strong>postCode</strong></td><td align="center">string</td><td align="center">так</td><td><p>Поштовий індекс (ZIP-код), що відповідає адресі отримувача. Використовується для сортування та маршрутизації відправлення до кінцевої точки.</p><p><strong>🔹Це поле є обов’язковим, якщо</strong> <code>recipient.divisionNumber</code> <strong>та</strong> <code>recipient.divisionID</code> <strong>відсутні або порожні.</strong></p><p>Constraints: Max 10 chars</p></td></tr><tr><td>recipient.addressParts.<strong>building</strong></td><td align="center">string</td><td align="center">так</td><td><p>Номер або назва будівлі за адресою отримувача, що дозволяє точно ідентифікувати місце доставки.</p><p><strong>🔹Це поле є обов’язковим, якщо</strong> <code>recipient.divisionNumber</code> <strong>та</strong> <code>recipient.divisionID</code> <strong>відсутні або порожні.</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.addressParts.<strong>flat</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Номер квартири або офісу, якщо доставка здійснюється до будівлі з кількома приміщеннями.</p><p>Constraints: Max 10 chars</p></td></tr><tr><td>recipient.addressParts.<strong>block</strong></td><td align="center">string | null</td><td align="center">ні</td><td><p>Ідентифікує корпус або секцію в межах великого комплексу чи житлового масиву для адреси отримувача.</p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.addressParts.<strong>note</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Дозволяє вказати додаткові інструкції або деталі щодо адреси отримувача (наприклад, код домофона, особливості доступу, бажаний час доставки), що можуть полегшити процес доставки.</p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.<strong>registrationAddressRecipient</strong></td><td align="center">object</td><td align="center">ні</td><td>Об’єкт registrationAddressRecipient надає детальний опис зареєстрованої адреси отримувача та є обов’язковим при доставці до країн із підвищеними вимогами до митного оформлення, таких як Німеччина, Словаччина, Угорщина та Франція. Це забезпечує відповідність локальним регуляторним вимогам і сприяє коректному та безперешкодному проходженню митного контролю.</td></tr><tr><td>recipient.registrationAddressRecipient.<strong>city</strong></td><td align="center">string</td><td align="center">так</td><td><p>Назва міста, де зареєстрований отримувач. Повинна відповідати локальним правилам найменування.</p><p><strong>🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції.</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.registrationAddressRecipient.<strong>street</strong></td><td align="center">string</td><td align="center">так</td><td><p>Назва вулиці зареєстрованої адреси отримувача. Повинна відповідати локальним стандартам адресації.</p><p><strong>🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції.</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.registrationAddressRecipient.<strong>zipCode</strong></td><td align="center">string</td><td align="center">так</td><td><p>Поштовий індекс зареєстрованої адреси отримувача.</p><p><strong>🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції.</strong><br>Constraints: Max 10 chars</p></td></tr><tr><td>recipient.registrationAddressRecipient.<strong>building</strong></td><td align="center">string</td><td align="center">так</td><td><p>Номер або назва будівлі, в якій зареєстрований отримувач.</p><p><strong>🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції.</strong></p><p>Constraints: Max 100 chars</p></td></tr><tr><td>recipient.registrationAddressRecipient.<strong>apartment</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Номер квартири або офісу в межах будівлі (за наявності).</p><p>Constraints: Max 10 chars</p></td></tr><tr><td>recipient.registrationAddressRecipient.<strong>state</strong></td><td align="center">string</td><td align="center">ні</td><td><p>Регіон або область реєстрації отримувача, використовується у країнах, де це є обов’язковим для точнішої ідентифікації.</p><p>Constraints: Max 100 chars</p></td></tr></tbody></table>

</details>

## POST /shipments

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

```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"],"requestBody":{"description":"Optional description in *Markdown*","required":true,"content":{"application/json":{"schema":{"type":"object","required":["sender","invoice"],"properties":{"status":{"type":"string","description":"Визначає поточний статус транспортного документа, відстежуючи його проходження через життєвий цикл доставки.","enum":["ReadyToShip"]},"clientOrder":{"type":"string","description":"Представляє всі можливі ідентифікатори замовлення, пов’язані з відправленням.","maxLength":50},"note":{"type":"string","description":"Тут може бути вказана будь-яка додаткова інформація або спеціальні інструкції щодо замовлення.","maxLength":255},"deliveryType":{"type":"string","description":"Визначає тип тарифу, який буде застосовано до відправлення під час створення або оновлення."},"payerType*":{"type":"string","description":"Визначає, хто несе відповідальність за оплату послуг доставки.","enum":["Sender","Recipient","ThirdPerson"]},"payerContractNumber":{"type":"string","description":"Обов’язковий для платежів із типом платника `ThirdPerson`, а також для безготівкових платежів, якщо `payerType` має значення Sender або `Recipient`.","minLength":2,"maxLength":20,"nullable":true},"services":{"type":"array","description":"Містить інформацію про додаткові послуги для відправлення.","properties":{"shipmentParcelRowNumber":{"type":"integer","nullable":true,"description":"Вказує номер рядка посилки, до якої застосовується послуга."},"serviceCode":{"type":"string","description":"Код, що визначає послугу."},"serviceName":{"type":"string","description":"Назва послуги."},"serviceId":{"type":"string","description":"Унікальний ідентифікатор (reference ID) обраної послуги."},"amount":{"type":"number","description":"Загальна сума, яку одержувач має сплатити в рамках послуги COD."},"contractNumber":{"type":"string","nullable":true,"description":"Номер договору платника, відповідального за обрану послугу."},"payerType":{"type":"string","description":"Визначає, хто відповідає за оплату послуги."},"additionalParameters":{"type":"string","description":"Додаткові параметри для послуги.","properties":{"cod":{"type":"string","description":"Додаткові параметри для налаштування COD.","properties":{"bankAccount":{"type":"object","description":"Інформація про банківський рахунок, на який буде здійснено переказ коштів.","properties":{"amount":{"type":"number","description":"Сума, яка буде перерахована на рахунок відправника після оплати."},"currencyCode":{"type":"string","description":"Валюта транзакції, визначена договором відправника."},"bankAccountId":{"type":"string","description":"Ідентифікаційний код фізичної або юридичної особи."},"bankAccountName":{"type":"string","description":"IBAN"},"description":{"type":"string","description":"Додатковий опис платіжних реквізитів."},"commissionPayer":{"type":"string","description":"Визначає сторону, яка сплачує комісію."}}}}},"backwardDelivery":{"type":"array","description":"Додаткові параметри для налаштування зворотної доставки.","items":{"type":"object","properties":{"description":{"type":"string","description":"Опис товарів, що підлягають поверненню."}}}}}}}},"invoice":{"type":"object","description":"Цей об’єкт містить необхідні дані для митних органів для ефективної обробки відправлення.","properties":{"customerNumber":{"type":"string","description":"Унікальний ідентифікатор/номер інвойсу, що супроводжує товари у відправленні, який генерується безпосередньо клієнтом.","maxLength":50,"nullable":true},"customerCreatedAt":{"type":"string","format":"date-time","description":"Необхідно передати дату, вказану в інвойсі, що супроводжує відправлення."},"type":{"type":"string","description":"Тип інвойсу клієнта, що супроводжує відправлення та використовується для митного декларування.","enum":["Invoice","ProformaInvoice"]},"incoterm":{"type":"string","description":"Визначає умови поставки між продавцем і покупцем.","enum":["DAP","DDP"]},"exportReason":{"type":"string","description":"Визначає загальну причину експорту товарів, що є необхідною для митних та інших регуляторних органів.","enum":["ForPersonalPurposes","Selling","Repair","Return","Other"]},"cost":{"type":"number","description":"Загальна задекларована вартість інвойсу у вихідній валюті.","minimum":0,"maximum":9999999.99},"currency":{"type":"string","description":"Код валюти інвойсу відповідно до стандарту ISO 4217."},"payerFeesCustoms":{"type":"string","description":"Визначає, хто оплачує митні послуги.","enum":["Sender","Recipient","ThirdPerson"]},"items":{"type":"array","description":"Деталізований перелік товарів, що відправляються.","items":{"type":"object","properties":{"id":{"type":"string","description":"Унікальний ідентифікатор кожного товару у відправленні."},"hsCode":{"type":"string","description":"Код Гармонізованої системи (HS code) для кожного товару — стандартизований числовий метод класифікації товарів у міжнародній торгівлі.","maxLength":255,"nullable":true},"name":{"type":"string","description":"Назва товару локальною мовою, що забезпечує точний опис для митного оформлення та логістичного планування.","maxLength":512},"nameEng":{"type":"string","description":"Назва товару англійською мовою, що забезпечує його зрозумілість у міжнародній торгівлі та логістиці.","maxLength":512},"material":{"type":"string","description":"Основний матеріал, з якого виготовлено товар, важливий для митного декларування та можливих обмежень.","maxLength":50},"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":"Параметр містить виробника та модель пристрою в одному полі.","maxLength":255,"nullable":true},"actualWeight":{"type":"integer","description":"Фактична загальна вага всіх одиниць товару в грамах (g).","minimum":1,"maximum":2147483647,"nullable":true},"measurementCode":{"type":"string","description":"Одиниця виміру кількості товару (наприклад, штуки, кілограми, метри тощо), що стандартизує спосіб зазначення кількості.","maxLength":255},"amount":{"type":"number","description":"Кількість товару, що відправляється.","minimum":0,"maximum":9999999.99},"cost":{"type":"number","description":"Вартість за одиницю товару у валюті відправника.","minimum":0,"maximum":9999999.99}}}}}},"parcels*":{"type":"array","description":"Блок опису посилок.","items":{"type":"object","properties":{"cargoCategory*":{"type":"string","description":"Визначає тип відправлення, що використовується для класифікації товарів у логістиці та митному оформленні.","enum":["parcel","documents","pallet"]},"parcelDescription*":{"type":"string","description":"Короткий опис вмісту посилки, що містить основну інформацію про характер вкладення.","maxLength":255},"insuranceCost*":{"type":"number","format":"float","description":"Задекларована вартість відправлення для страхування.","minimum":1,"exclusiveMinimum":true},"insuranceCurrencyCode":{"type":"string","description":"Код валюти ISO 4217 для страхувальної вартості (`insuranceCost`).","pattern":"^[A-Z]{3}$"},"rowNumber*":{"type":"integer","description":"Порядковий номер посилки у відправленні.","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).","minimum":1,"maximum":2147483647}}}},"sender*":{"type":"object","description":"Інформація про сторону, яка відправляє відправлення.","properties":{"companyTin":{"type":"string","description":"Податковий номер або аналогічний ідентифікатор юридичної особи (EDRPOU, TIN, NIP, IČO — для Словаччини).","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":"Контактний номер телефону відправника або представника компанії."},"email":{"type":"string","description":"Email-адреса відправника для отримання повідомлень, оновлень та комунікації щодо відправлення."},"name*":{"type":"string","description":"Повне ім’я відправника або контактної особи компанії.","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.","pattern":"^[A-Z]{2}$"},"divisionNumber":{"type":"string","description":"Обов’язкове поле, якщо відправлення здійснюється з відділення або поштомату.","nullable":true},"divisionID":{"type":"integer","description":"Ідентифікатор відділення для точного визначення локації.","minimum":1,"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":"Податковий номер або еквівалентний ідентифікатор юридичної особи (EDRPOU, TIN, NIP, IČO — для Словаччини).","maxLength":20,"nullable":true},"companyName":{"type":"string","description":"Офіційна назва компанії отримувача.","maxLength":100,"nullable":true},"eoriCode":{"type":"string","description":"Код EORI отримувача є важливим для митного оформлення при доставці до країн Європейського Союзу.","minLength":3,"maxLength":17,"nullable":true},"phone*":{"type":"string","description":"Контактний номер телефону отримувача або представника компанії."},"email":{"type":"string","description":"Email-адреса отримувача."},"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},"divisionID":{"type":"integer","description":"Ідентифікатор відділення для точного визначення конкретної точки отримання.","minimum":1,"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}}},"registrationAddressRecipient":{"type":"object","description":"Об’єкт registrationAddressRecipient надає детальний опис зареєстрованої адреси отримувача.","properties":{"city":{"type":"string","description":"Назва міста, де зареєстрований отримувач.","maxLength":100},"street":{"type":"string","description":"Назва вулиці зареєстрованої адреси отримувача.","maxLength":100},"zipCode":{"type":"string","description":"Поштовий індекс зареєстрованої адреси отримувача.","maxLength":10},"building":{"type":"string","description":"Номер або назва будівлі, в якій зареєстрований отримувач.","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` слугує ключовим посиланням для адміністративних і логістичних процесів у системі доставки, забезпечуючи точний доступ і керування записами відправлень.","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":"Створення Відправлення"}}}}
```


---

# 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/stvorennya-vidpravlen/mizhnarodni-vidpravlennya-z-ukrayini.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.