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

Ця сторінка описує процес створення відправлень з-за кордону в Україну.

Shipment API Interaction Flow

Схема (Об'єкт)

Поле

Тип

Обов'язкове

Опис

status

enum

так

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

Draft: Документ знаходиться на початковій стадії, ще не завершений.
Accepted: Перевірений та прийнятий, документ готовий до наступних етапів.
Issued: Документ завершено та готовий до відправлення.
ReadyToShip: Вказує, що відправлення підготовлено до транспортування після створення експрес-накладної. Лише це значення може бути вказане при створенні відправлення.
Deleted: Документ видалено із системи.
Returned: Відправлення повернено відправнику.
Utilized: Вказує, що фізичні товари, пов’язані з транспортним документом, були утилізовані або знищені, і документ закрито.

Allowed: ReadyToShip

clientOrder

string

так

Представляє всі можливі ідентифікатори замовлення, пов’язані з відправленням. Ці ідентифікатори задаються клієнтом для внутрішнього відстеження та є важливими для контролю відправлення протягом усього його маршруту. Усі введені значення можуть відстежуватися в системі трекінгу.

Constraints: Max 50 chars

note

string

так

Тут може бути вказана будь-яка додаткова інформація або спеціальні інструкції щодо замовлення. Це можуть бути інструкції з доставки, особливі умови обробки або інші важливі деталі, що сприяють обробці відправлення.

Constraints: Max 255 chars

deliveryType

string

ні

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

standard: Стандартний міжнародний тариф доставки.
economy: Економний міжнародний тариф доставки.
express: Експрес міжнародний тариф доставки.

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

payerType

enum

так

Визначає, хто несе відповідальність за оплату послуг доставки. Тип платника визначає сторону, яка покриває витрати:

Sender: Відправник оплачує доставку.
Recipient: Одержувач оплачує доставку.
ThirdPerson: Третя сторона, не відправник і не одержувач, оплачує доставку. При виборі 'ThirdPerson' поле 'payerContractNumber' має містити номер договору платника. Детальніше див. статтю Оплата послуг доставки через API Nova Post. Це поле також використовується при формуванні інвойсу.

Allowed: Sender┃Recipient┃ThirdPerson

payerContractNumber

string┃null

так

Це поле є обов’язковим у таких випадках:

Коли payerType має значення ThirdPerson. Воно повинно містити номер договору платника. Для клієнтів з України також дозволено передавати код ЄДРПОУ замість номера договору.
Коли payerType має значення Sender або Recipient і використовується безготівковий спосіб оплати.

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

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

Детальніше див. статтю Оплата послуг доставки через API Nova Post.

Constraints: 2 to 20 chars

services

array

ні

Містить інформацію про додаткові послуги для відправлення.

services.shipmentParcelRowNumber

integer

так

Вказує номер рядка посилки, до якої застосовується послуга. Значення має відповідати rowNumber існуючої посилки в масиві parcels. Для послуг, що застосовуються до всього відправлення (наприклад, ExpBackwardGoods), це поле повинно мати значення null.

services.serviceCode

string

так

Код, що визначає послугу. Перелік доступних кодів та їх значень:

COD — Послуга накладеного платежу (COD) дозволяє одержувачу оплатити товар безпосередньо при отриманні без необхідності передоплати. Відправник може додати цю послугу до відправлення, а одержувач має можливість оплатити товар під час доставки та оглянути його перед оплатою, з урахуванням обмежень способів оплати, встановлених для конкретних країн. Доступні напрямки:
- Польща → Україна
- Чехія → Україна
- Німеччина → Україна
- Словаччина → Україна
- Чехія → Чехія
- Польща → Польща
- Німеччина → Німеччина
- Румунія → Молдова

🔸Послуга COD планується до розширення на інші країни та напрямки доставки в майбутньому, як для міжнародних відправлень, так і в межах європейських країн.

ExpBackwardGoods — Дозволяє оформити зворотну доставку для основного відправлення
ExpBackwardCreditDoc — Дозволяє оформити зворотну доставку підписаних документів для внутрішніх відправлень документів у Молдові. Послуга доступна лише для юридичних осіб і лише для відправлень типу Documents. Зворотне відправлення створюється як окрема доставка документів (кур'єром або оператором), і платником завжди є Одержувач за безготівковим договором. Недоступна для каналів Parcel Locker та PUDO. На першому етапі послуга доступна лише для обраних юридичних осіб.

🔹Це поле є обов’язковим для групи services.

services.serviceName

string

так

Назва послуги.

Допустимі значення включають:

PaymentControl — послуга контролю оплати.
MoneyTransfer — послуга грошового переказу.
Інші типи послуг, доступні в групі services.

🔹Це поле є обов’язковим у межах групи services.

services.serviceId

string

так

Унікальний ідентифікатор (reference ID) обраної послуги.

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

🔹Це поле є обов’язковим у межах групи services.

services.amount

number

так

Загальна сума, яку одержувач має сплатити в рамках послуги COD.

🔹Це поле є обов’язковим для групи services.

services.contractNumber

string┃null

так

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

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

services.payerType

string

так

Визначає, хто відповідає за оплату послуги. Тип платника визначає сторону, яка покриває витрати:

Recipient — єдине допустиме значення для послуги COD.
Sender, Recipient — допустимі значення для послуги ExpBackwardGoods.
Sender, Recipient, ThirdPerson — допустимі значення для послуги BackwardDelGoods.

🔻Це поле є обов’язковим

services.additionalParameters

string

так

Додаткові параметри для послуги.

services.additionalParameters.cod

string

так

Додаткові параметри для налаштування COD.

🔹Ці параметри є обов’язковими та застосовуються лише для послуги COD

services.additionalParameters.cod.bankAccount

object

ні

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

services.additionalParameters.cod.bankAccount.amount

number

так

Сума, яка буде перерахована на рахунок відправника після оплати. Визначає суму, яку одержувач має сплатити при отриманні. Можлива автоматична конвертація валюти залежно від країни відправника або одержувача.

🔹Це поле є обов’язковим для групи services.additionalParameters.cod.bankAccount.

services.additionalParameters.cod.bankAccount.currencyCode

string

так

Валюта транзакції, визначена договором відправника. Вказується відповідно до стандарту ISO 4217.

🔸За замовчуванням використовується валюта країни відправника, але можливе ручне встановлення (функціонал у розробці). Pattern: ^[A-Z]{3}$

services.additionalParameters.cod.bankAccount.bankAccountId

string

так

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

🔹Це поле є обов’язковим для групи services.additionalParameters.cod.bankAccount.

🔸Має містити податковий номер або аналогічний ідентифікатор (ЄДРПОУ, TIN, NIP).

services.additionalParameters.cod.bankAccount.bankAccountName

string

так

IBAN

🔹Це поле є обов’язковим для групи services.additionalParameters.cod.bankAccount.

🔸Має містити повний номер рахунку у форматі IBAN.

services.additionalParameters.cod.bankAccount.description

string

так

Додатковий опис платіжних реквізитів.

services.additionalParameters.cod.bankAccount.commissionPayer

string

так

Визначає сторону, яка сплачує комісію:

Recipient
Sender

🔹Це поле є обов’язковим для групи services.additionalParameters.cod.bankAccount.

services.additionalParameters.backwardDelivery

object

так

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

🔹Ці параметри є обов’язковими та застосовуються лише для послуги ExpBackwardGoods.

services.additionalParameters.backwardDelivery.description

string

ні

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

invoice

object

ні

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

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

cost — загальна задекларована вартість інвойсу
currency — код валюти інвойсу

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

invoice.customerNumber

string┃null

так

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

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

invoice.customerCreatedAt

string

так

Необхідно передати дату, вказану в інвойсі, що супроводжує відправлення. Якщо дата відсутня у документі клієнта, можна використати дату створення відправлення.

🔹Це поле є обов’язковим, якщо заповнено поле invoice.customerNumber.

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$

invoice.type

string

так

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

Invoice — комерційний інвойс для відправлень комерційного характеру
ProformaInvoice — проформа-інвойс для відправлень некомерційного характеру

🔹Це поле є обов’язковим, якщо заповнено поле invoice.customerNumber.

Possible values: Invoice | ProformaInvoice

invoice.incoterm

string

так

Визначає умови поставки між продавцем і покупцем відповідно до правил Incoterms®. Ці умови регулюють розподіл витрат на доставку, страхування, митні платежі та ризики. Доступний обмежений набір значень:

DAP (Delivered at Place) - Одержувач відповідає за митне оформлення імпорту, сплату мит та податків.
DDP (Delivered Duty Paid) - Відправник відповідає за митне оформлення імпорту та оплату всіх мит і податків.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

Possible values: DAP,DDP

invoice.exportReason

string

так

Визначає загальну причину експорту товарів, що є необхідною для митних та інших регуляторних органів. Класифікація дозволяє визначити тип відправлення без деталізації. Використовується для спрощення обробки на митниці. Доступні значення:

ForPersonalPurposes: Товари для особистого використання або подарунки.
Selling: Товари призначені для продажу.
Repair: Товари відправляються на ремонт.
Return: Товари повертаються відправнику або виробнику.
Other: Інша причина, не зазначена вище.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

Possible values: ForPersonalPurposes,Selling,Repair,Return,Other

invoice.cost

number

так

Загальна задекларована вартість інвойсу у вихідній валюті, яка повинна дорівнювати сумі всіх позицій інвойсу, розрахованій як (amount × cost) для кожного товару. Використовується для митного декларування.

🔸Якщо передане значення cost не дорівнює сумі значень у масиві items, воно буде автоматично перераховане системою.

🔸Значення перевіряються на точність десяткових знаків, і цифри після другого знака після коми ігноруються.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

Constraints: Min 0┃Max 9999999.99

invoice.currency

string

так

Код валюти інвойсу відповідно до стандарту ISO 4217. Усі товари в інвойсі повинні бути в одній валюті.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

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

invoice.payerFeesCustoms

string

так

Визначає, хто оплачує митні послуги. Параметр визначає сторону, яка покриває витрати:

Sender: Відправник оплачує митні платежі.
Recipient: Одержувач оплачує митні платежі.
ThirdPerson: Третя сторона може оплачувати митні послуги лише за умови, що це дозволено і платник за доставку також є третьою стороною.

Значення за замовчуванням — "Recipient". Це значення також буде застосовано автоматично, якщо вартість відправлення перевищує максимально допустиму (у валюті країни одержувача), при якій відправник може оплачувати митні платежі.

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

Possible values: Sender | Recipient | ThirdPerson

invoice.items

object

так

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

Логіка: Якщо блок items передано, система перевіряє, чи дорівнює загальна сума всіх (items.cost × items.amount) значенню invoice.cost. Якщо ні — система оновлює invoice.cost, щоб вона дорівнювала сумі всіх товарів.

🔸Необхідно передавати інформацію для кожного окремого товару у відправленні у вигляді масиву.

invoice.items.id

string

ні

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

🔹Це поле є необов’язковим.

invoice.items.hsCode

string | null

так

Код Гармонізованої системи (HS code) для кожного товару — стандартизований числовий метод класифікації товарів у міжнародній торгівлі. Це поле є обов’язковим для міжнародних відправлень, що проходять митне оформлення. Отримати коректний hsCode можна з довідника Класифікаторів вантажів (UKT ZED). Правила валідації:

Якщо країна відправника або отримувача — Молдова (MD) або Канада (CA):
- hsCode повинен складатися рівно з 10 цифрових символів.
- Якщо значення містить більше ніж 10 цифр, воно буде скорочено праворуч.
- Якщо значення містить менше ніж 10 цифр — помилка валідації.
Для всіх інших країн:
- hsCode повинен містити від 8 до 10 цифрових символів (включно).
- Якщо значення містить менше ніж 8 цифр — помилка валідації.
Усі нецифрові символи автоматично видаляються перед валідацією.
Якщо значення поля hsCode дорівнює 210690 або 630900, повинні виконуватися наступні умови:
- measurementCode повинен бути встановлений у значення kg.
- Кожен товар із таким hsCode повинен бути унікальним — інвойс не може містити більше одного товару з кодом 210690 або 630900.
- Значення кількості не повинно перевищувати 10.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або прямують за межі ЄС.

Constraints: Max 255 chars

invoice.items.serialNumber

string┃null

ні

Серійний номер пристрою або обладнання. Це значення може використовуватися для ідентифікації товару під час процесу легкого повернення.

Constraints: Max 20 chars

invoice.items.name

string

так

Назва товару локальною мовою, що забезпечує точний опис для митного оформлення та логістичного планування. Назва повинна відповідати термінам з довідника Cargo Classifiers (UKT ZED), що гарантує відповідність стандартним класифікаційним кодам. Детальний опис допомагає точно ідентифікувати товар під час митного оформлення. Це поле підтримує Unicode-кодування, що дозволяє використовувати спеціальні символи через формат \uXXXX. Це забезпечує точне відображення назв товарів мовами з нелатинськими символами, підвищуючи зрозумілість у різних регуляторних середовищах.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

Constraints: Max 512 chars

invoice.items.nameEng

string

так

Назва товару англійською мовою, що забезпечує його зрозумілість у міжнародній торгівлі та логістиці. Полегшує комунікацію з міжнародними партнерами та органами. Аналогічно полю name, підтримує Unicode-кодування через формат \uXXXX.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

Constraints: Max 512 chars

invoice.items.material

string

ні

Основний матеріал, з якого виготовлено товар, важливий для митного декларування та можливих обмежень.

🔸Якщо поле не передано, буде застосовано значення за замовчуванням.

Constraints: Max 50 chars

invoice.items.materialEng

string

ні

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

🔸Якщо поле не передано, буде застосовано значення за замовчуванням.

Constraints: Max 255 chars

invoice.items.madeInCountryCode

string | null

ні

Код країни виробництва за стандартом ISO 3166-1 alpha-2, необхідний для визначення митних платежів та дотримання торговельних угод.

🔸Поле не є обов’язковим, але відправлення з цим полем мають пріоритет під час митного оформлення.

Pattern: ^[A-Z]{2}$

invoice.items.producerAndModel

string | null

ні

Параметр містить виробника та модель пристрою в одному полі. Обов’язковий для таких категорій:

Електроніка
Ноутбуки
Телефони
Побутова техніка
Інші подібні товари

🔸Поле не є обов’язковим, але відправлення з ним мають пріоритет під час митного оформлення.

Constraints: Max 255 chars

invoice.items.actualWeight

integer | null

так

Фактична загальна вага всіх одиниць товару в грамах (g).

Підтримувана точність: 10 грам (0.01 кг). Значення, що не кратні 10 г, округлюються вниз до найближчого меншого кратного.

🔸Це поле є обов’язковим, якщо передано масив invoice.items. Система перевіряє, що сума actualWeight по всіх товарах дорівнює загальній вазі відправлення (parcels[].actualWeight).

⚠️ВАЖЛИВО: Переконайтесь, що всі ваги коректно округлені і їх сума точно дорівнює вазі відправлення.

Constraints: Min 1┃Max 2147483647

invoice.items.measurementCode

string

так

Одиниця виміру кількості товару (наприклад, штуки, кілограми, метри тощо), що стандартизує спосіб зазначення кількості.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

Constraints: Max 255 chars

invoice.items.amount

number

так

Кількість товару, що відправляється, у відповідних одиницях виміру (measurementCode).

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

Constraints: Min 0┃Max 9999999.99

invoice.items.cost

number

так

Вартість за одиницю товару у валюті відправника.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

Constraints: Min 0┃Max 9999999.99

parcels

object

так

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

🔻Усі поля в цьому масиві є обов’язковими для заповнення.

parcels.cargoCategory

string

ні

Визначає тип відправлення, що використовується для класифікації товарів у логістиці та митному оформленні. Категорія впливає на обробку відправлення, вартість доставки та необхідну документацію. Доступні категорії:

parcel: Невеликі та середні посилки, зазвичай для споживчих товарів.
documents: Поштові відправлення з документами (листи, контракти, офіційні папери). Обмеження: вага до 1 кг, розміри — не більше 35 × 25 × 2 см.
pallet: Вантаж у вигляді палети з фіксованими розмірами та ваговими обмеженнями (доступно для юридичних осіб у Business Cabinet Europe):
- До 250 кг, площа ~0.48 м², розміри 80 × 60 × 170 см
- До 500 кг, площа ~0.96 м², розміри 120 × 80 × 170 см
- До 750 кг, площа ~1.2 м², розміри 120 × 100 × 170 см
- До 1000 кг, площа ~1.2 м², розміри 120 × 100 × 170 см

Possible values: parcel | documents | pallet

parcels.parcelDescription

string

ні

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

Constraints: Max 255 chars

parcels.insuranceCost

number

так

Задекларована вартість відправлення для страхування. Визначає максимальну суму компенсації у разі втрати або пошкодження.

Обробка валюти:

Якщо insuranceCurrencyCode не передано, значення повинно бути у валюті країни відправника.
Якщо insuranceCurrencyCode передано, значення може бути в будь-якій підтримуваній валюті (ISO 4217), система автоматично конвертує її.

🔸 Якщо використовується insuranceCurrencyCode, всі посилки повинні мати однаковий код валюти. Інакше — помилка валідації.

Значення завжди повинно бути більше 0 незалежно від напрямку відправлення."

Example: 1.5

parcels.insuranceCurrencyCode

string

ні

Код валюти ISO 4217 для страхувальної вартості (insuranceCost).

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

🔹Це поле є необов’язковим."

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

parcels.rowNumber

integer

так

Порядковий номер посилки у відправленні. Якщо посилка одна — значення має бути 1.

Constraints: Min 1

parcels.width

integer

так

Ширина посилки в міліметрах. Використовується разом з довжиною та висотою для розрахунку об’єму.

Constraints: Min 1

parcels.length

integer

так

Довжина посилки в міліметрах. Використовується разом з шириною та висотою для розрахунку об’єму.

Constraints: Min 1

parcels.height

integer

так

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

Constraints: Min 1

parcels.actualWeight

integer

так

Фактична вага посилки у грамах (g).

Підтримувана точність: 10 грам (0.01 кг). Значення, що не кратні 10 г, округлюються вниз.

🔸Це поле є обов’язковим, якщо передано масив invoice.items. Система перевіряє, що сума actualWeight по всіх товарах дорівнює загальній вазі відправлення (parcels[].actualWeight).

⚠️ВАЖЛИВО: Переконайтесь, що вага всіх товарів співпадає із загальною вагою посилок."

Constraints: Min 1┃Max 2147483647

sender

object

так

Інформація про відправника, включаючи дані про фізичну або юридичну особу, відповідальну за відправлення.

🔻Цей набір полів є обов’язковим

sender.companyTin

string

так

Податковий номер або аналогічний ідентифікатор юридичної особи (EDRPOU, TIN, NIP, IČO — для Словаччини).

🔸Ці поля є обов’язковими для юридичної особи. Якщо вони не заповнені — відправник вважається фізичною особою

Constraints: Max 20 chars

sender.companyName

string | null

так

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

Constraints: Max 100 chars

sender.eoriCode

string | null

так

Код EORI (Economic Operators Registration and Identification) використовується в Європейському Союзі для ідентифікації суб'єктів зовнішньоекономічної діяльності. Рекомендується для міжнародних відправлень до ЄС для коректного митного оформлення та уникнення затримок.

Constraints: 3 to 17 chars

sender.phone

string

так

Контактний номер телефону відправника або представника компанії. Використовується для комунікації щодо відправлення (забір, уточнення, проблемні ситуації).

Формат: Номер повинен бути у міжнародному форматі відповідно до стандарту E.164.

Приклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX

Обмеження:

Номер повинен бути дійсним і доступним для зв’язку.
Якщо номер передано у локальному форматі, система спробує нормалізувати його, але така логіка обмежена. Рекомендується реалізувати front-end валідацію для перевірки формату.

🔻Це поле є обов’язковим

sender.email

string

так

Email-адреса відправника для отримання повідомлень, оновлень та комунікації щодо відправлення.

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або виходять за його межі.

sender.name

string

так

Повне ім’я відправника або контактної особи компанії. Використовується у всіх документах і комунікації.

🔸Важливо для міжнародних відправлень EU → UA: Ім’я має бути вказане виключно латиницею. Використання кирилиці (включаючи українські літери) заборонено та призведе до помилки обробки на стороні Last Mile партнера.

🔻Це поле є обов’язковим

Constraints: Max 100 chars

sender.ioss

string

ні

Номер IOSS (Import One-Stop Shop) — необов’язковий параметр, який використовується для спрощення процесу декларування ПДВ для відправлень із країн, що не входять до ЄС, із задекларованою вартістю до 150 євро. Актуально для відправлень з країн поза ЄС до ЄС.

Constraints: Max 12 chars

Pattern: /^[a-zA-Z0-9]*$/u

sender.countryCode

string

так

Дволітерний код країни відправника згідно стандарту ISO 3166-1 Alpha-2.

🔻Це поле є обов’язковим

Pattern: ^[A-Z]{2}$

sender.divisionNumber

string | null

так

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

🔹Це поле є обов’язковим, якщо відсутні sender.addressParts та sender.divisionID

Example: 32521/1

sender.divisionID

integer | null

так

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

🔹Це поле є обов’язковим, якщо відсутні sender.addressParts та sender.divisionNumber

Constraints: Min 1

sender.addressParts

object

так

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

sender.addressParts.city

string

так

Назва міста, з якого здійснюється відправлення. Використовується для точного визначення населеного пункту для забору або відправлення.

🔹Це поле є обов’язковим, якщо sender.divisionNumber та sender.divisionID відсутні або порожні. 🔸Для відправлень, де країна відправника — Молдова або Україна, значення міста перевіряється за внутрішніми довідниками населених пунктів. Якщо значення не може бути зіставлене з жодним населеним пунктом, створення відправлення буде відхилено.

Constraints: Max 100 chars

sender.addressParts.region

string

так

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

🔹Це поле є обов’язковим для відправлень, якщо країна відправника або отримувача — США, Ірландія або Канада.

Constraints: Max 100 chars

sender.addressParts.street

string

так

Назва вулиці за адресою відправника, необхідна для точного визначення місця забору або доставки.

🔹Це поле є обов’язковим, якщо sender.divisionNumber та sender.divisionID відсутні або порожні.

Constraints: Max 100 chars

sender.addressParts.postCode

string

так

Поштовий індекс (ZIP-код), що відповідає адресі відправника. Використовується для сортування та маршрутизації відправлення.

🔹Це поле є обов’язковим, якщо sender.divisionNumber та sender.divisionID відсутні або порожні.

Constraints: Max 10 chars

sender.addressParts.building

string

так

Номер або назва будівлі за вказаною адресою, що дозволяє точно ідентифікувати місце забору.

🔹Це поле є обов’язковим, якщо sender.divisionNumber та sender.divisionID відсутні або порожні.

Constraints: Max 100 chars

sender.addressParts.flat

string

ні

Номер квартири, офісу або приміщення в межах будівлі, якщо це застосовно, для точної ідентифікації місця відправлення.

Constraints: Max 10 chars

sender.addressParts.block

string | null

ні

Позначає блок або секцію в межах житлового комплексу чи великої території (за наявності), допомагаючи точніше визначити місце відправлення.

Constraints: Max 100 chars

sender.addressParts.note

string

ні

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

Constraints: Max 100 chars

recipient

object

так

Інформація про отримувача відправлення, що містить дані про фізичну або юридичну особу, відповідальну за отримання вантажу.

🔻Цей набір полів є обов’язковим

recipient.companyTin

string | null

так

Податковий номер або еквівалентний ідентифікатор юридичної особи (EDRPOU, TIN, NIP, IČO — для Словаччини).

🔸Ці поля є обов’язковими для юридичної особи. Якщо вони не заповнені — отримувач вважається фізичною особою

Constraints: Max 20 chars

recipient.companyName

string | null

так

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

Constraints: Max 100 chars

recipient.eoriCode

string | null

так

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

Неакцизні товари: код EORI не є обов’язковим при доставці з України юридичній особі в Європі. Якщо код відсутній — він буде присвоєний автоматично.
Акцизні товари: код EORI є обов’язковим. Отримувач повинен отримати його до здійснення відправлення.

Constraints: 3 to 17 chars

recipient.phone

string

так

Контактний номер телефону отримувача або представника компанії. Використовується для повідомлень про доставку та комунікації під час обробки відправлення.

Формат: номер повинен бути у міжнародному форматі відповідно до стандарту E.164.

Приклад: 380XXXXXXXXX, 491234567890, 371XXXXXXXX

Обмеження:

Для доставки у відділення Nova Post в Європі допускаються українські мобільні номери.
Для доставки у партнерські точки (InPost, GLS, Venipak, Cargus тощо) та міжнародної адресної доставки номер повинен належати мобільному оператору країни отримувача. Якщо номер передано у локальному (неміжнародному) форматі, система спробує нормалізувати його до міжнародного формату, але внутрішній алгоритм не охоплює всі можливі варіанти. Якщо ваша система не підтримує front-end валідацію телефонних номерів, рекомендується повідомляти про некоректні кейси для можливого вдосконалення логіки нормалізації.

🔻Це поле є обов’язковим

recipient.email

string

так

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

🔹Це поле є обов’язковим для відправлень, що перетинають кордон ЄС або здійснюються за його межами.

recipient.name

string

так

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

🔻Це поле є обов’язковим

Constraints: Max 100 chars

recipient.countryCode

string

так

Дволітерний код країни отримувача відповідно до стандарту ISO 3166-1 Alpha-2, який визначає країну призначення відправлення.

🔻Це поле є обов’язковим

Pattern: ^[A-Z]{2}$

recipient.divisionNumber

string | null

так

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

🔹Це поле є обов’язковим, якщо обидва поля recipient.addressParts та recipient.divisionID відсутні або порожні

recipient.divisionID

integer | null

так

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

🔹Це поле є обов’язковим, якщо обидва поля recipient.addressParts та recipient.divisionNumber відсутні або порожні

Constraints: Min 1

recipient.addressParts

object

так

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

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

recipient.addressParts.city

string

так

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

🔹Це поле є обов’язковим, якщо recipient.divisionNumber та recipient.divisionID відсутні або порожні. 🔸Для відправлень, де країна отримувача — Молдова або Україна, значення міста перевіряється за внутрішніми довідниками населених пунктів. Якщо значення не може бути зіставлене з жодним записом, запит буде відхилено з помилкою:validation.condition.recipient_settlement_not_defined.

Constraints: Max 100 chars

recipient.addressParts.region

string

так

Визначає адміністративну одиницю (штат, область або провінцію), до якої належить місто отримувача. Це поле є критично важливим для точної маршрутизації відправлення.

Constraints: Max 100 chars

recipient.addressParts.street

string

так

Назва вулиці за адресою отримувача, необхідна для точного визначення місця доставки.

🔹Це поле є обов’язковим, якщо recipient.divisionNumber та recipient.divisionID відсутні або порожні.

Constraints: Max 100 chars

recipient.addressParts.postCode

string

так

Поштовий індекс (ZIP-код), що відповідає адресі отримувача. Використовується для сортування та маршрутизації відправлення до кінцевої точки.

🔹Це поле є обов’язковим, якщо recipient.divisionNumber та recipient.divisionID відсутні або порожні.

Constraints: Max 10 chars

recipient.addressParts.building

string

так

Номер або назва будівлі за адресою отримувача, що дозволяє точно ідентифікувати місце доставки.

🔹Це поле є обов’язковим, якщо recipient.divisionNumber та recipient.divisionID відсутні або порожні.

Constraints: Max 100 chars

recipient.addressParts.flat

string

ні

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

Constraints: Max 10 chars

recipient.addressParts.block

string | null

ні

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

Constraints: Max 100 chars

recipient.addressParts.note

string

ні

Дозволяє вказати додаткові інструкції або деталі щодо адреси отримувача (наприклад, код домофона, особливості доступу, бажаний час доставки), що можуть полегшити процес доставки.

Constraints: Max 100 chars

recipient.registrationAddressRecipient

object

ні

Об’єкт registrationAddressRecipient надає детальний опис зареєстрованої адреси отримувача та є обов’язковим при доставці до країн із підвищеними вимогами до митного оформлення, таких як Німеччина, Словаччина, Угорщина та Франція. Це забезпечує відповідність локальним регуляторним вимогам і сприяє коректному та безперешкодному проходженню митного контролю.

recipient.registrationAddressRecipient.city

string

так

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

🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції.

Constraints: Max 100 chars

recipient.registrationAddressRecipient.street

string

так

Назва вулиці зареєстрованої адреси отримувача. Повинна відповідати локальним стандартам адресації.

Constraints: Max 100 chars

recipient.registrationAddressRecipient.zipCode

string

так

Поштовий індекс зареєстрованої адреси отримувача.

🔹Це поле є обов'язковим для відправлень до країн зі спеціальними митними вимогами, зокрема Німеччини, Словаччини, Угорщини та Франції. Constraints: Max 10 chars

recipient.registrationAddressRecipient.building

string

так

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

Constraints: Max 100 chars