↑↓ вибірEnter відкритиEsc закрити

    1. Elbuz
    2. Керівництво користувача Elbuz
    3. Продажі та документи
    4. Обробка замовлень покупця
    5. Служби доставки в Elbuz

    Укрпошта API в Elbuz: накладна із замовлення, ярлик і статуси посилок

    8 хв читанняОновлено

    Elbuz підключається до Укрпошта API і виписує накладну прямо з картки замовлення, друкує ярлик і кожні 10 хвилин приносить статус посилки — без переписування даних у сервіси Укрпошти.

    Коли це знадобиться:

    • Відправляєте Укрпоштою за договором — одержувач, індекс і сума підставляються із замовлення, накладна — однією кнопкою.
    • Клієнт платить при отриманні — післяплата на суму замовлення ставиться сама, якщо замовлення не оплачене.
    • Посилок багато — накладні пачкою зі списку замовлень, статуси всіх посилок — у вікні «Відправлення».

    З чого почати: отримайте ключі API в менеджера Укрпошти → впишіть їх у запис Укрпошти в Elbuz.

    Що вміє Укрпошта в Elbuz

    Реєстри, переадресація, повернення, зміна й видалення накладної та виклик кур'єра з Elbuz серед українських служб є лише в Нової пошти. Для Укрпошти ці дії — в її сервісах.

    Як підключити Укрпошту: ключі API і відправник

    Де взяти ключі API Укрпошти

    Ключі видає менеджер Укрпошти після підписання договору — в особистому кабінеті на сайті їх немає. За документацією API Укрпошти після договору ви отримуєте таблицю доступів:

    • Bearer eCom — для створення відправлень;
    • Bearer StatusTracking — для статусів посилок;
    • Counterparty token — токен користувача;
    • Counterparty UUID — ідентифікатор контрагента.

    Ще потрібен UUID відправника — ідентифікатор клієнта-відправника з вашою адресою в системі Укрпошти. Його створюють через API; попросіть менеджера або технічну підтримку API (api-support@ukrposhta.ua) дати готовий UUID. Особистий кабінет на сайті Укрпошти — окрема послуга для фізичних осіб: відправлень, створених через API, у ньому не видно.

    Куди вписати ключі в Elbuz

    Де: Зовнішні сервіси та інтеграції → група «Доставка» → запис Укрпошти.

    1. У поле «Токен» вставте Bearer eCom.
    2. У блоці «Параметри Укрпошти» заповніть «Токен контрагента (counterparty token)» і «UUID відправника».
    3. Якщо менеджер видав окремий Bearer StatusTracking, впишіть його в «Токен відстеження (StatusTracking)». Порожнє поле — статуси запитуються з тим самим «Токен».
    4. Увімкніть «Активність».

    Поля «Користувач» і «Пароль» для Укрпошти не потрібні. Збереженого ключа не видно: поле «Токен» показує крапки, порожнє поле ключ не стирає.

    Форма підключення Укрпошти: токен, параметри Укрпошти та UUID відправника
    1Токен (Bearer eCom)
    2Токен контрагента
    3Токен відстеження
    4Статуси замовлень для перевірки
    5UUID відправника
    1. Токен — Bearer-ключ eCom, у полі показано лише крапки.
    2. Токен контрагента (counterparty token) — його видає Укрпошта під час підключення до API.
    3. Токен відстеження (StatusTracking) — окремий ключ для запитів статусів; може бути порожнім.
    4. Список статусів замовлень, за якими перевіряється статус посилки.
    5. UUID відправника — ідентифікатор відправника в Укрпошті.
    Elbuz не перевіряє ключі під час збереження. Помилку ключа ви побачите лише в першій накладній — текстом відповіді Укрпошти.

    Статуси доставки: які коди Укрпошти вписати

    Elbuz міняє статус замовлення лише для замовлень у статусах, позначених у списку «Статуси замовлень, за якими перевіряти статус посилки в службі доставки». Що на що міняти, задають три вікна в блоці «Налаштування повідомлень»: «Статуси замовлення», «Статуси доставки», «Статуси оплати».

    Коди Укрпошти в «Статуси доставки» Elbuz вписує сам, за ними «Відправлення» показують стан посилки. «Статуси замовлення» й «Статуси оплати» заповнюєте ви, через кому. Коди — з документації статус-трекінгу Укрпошти:

    Ваш статус доставкиКоди УкрпоштиЩо означають
    Чекання від відправника10100Прийнято у відділенні
    У дорозі20700, 20800, 20900, 21500Сортувальний центр, відправлено, прямує до відділення доставки
    У пункті призначення21700, 21400, 31400Надійшло у відділення доставки, на зберіганні
    Доставлено41000Вручено
    Відмова від отримання31200, 41010Посилка повертається відправнику, повернення вручено вам
    Вікно «Статуси доставки» Укрпошти з кодами статусів
    1Колонка кодів Укрпошти
    2У пункті призначення
    3Відмова від отримання
    1. Колонка «Код (назва) на сайті (API)» — коди статусів Укрпошти.
    2. «У пункті призначення» — коди 21700, 21400, 31400.
    3. «Відмова від отримання» — коди 31200 і 41010.

    Щоб замовлення саме ставало «Доставлено», у «Статуси замовлення» навпроти «Доставлено» впишіть 41000. Elbuz перестає питати про посилку, лише коли її код стоїть навпроти «Доставлено» чи «Доставлено частково» в «Статуси доставки».

    Повернення, вручене вам, Укрпошта позначає кодом вручення з причиною «відправнику» — Elbuz показує його як 41010, окремо від 41000.

    Як створити накладну Укрпошти із замовлення

    Де: картка замовлення → секція «Доставка» → «Створити накладну». Посилання є, якщо вид доставки замовлення — Укрпошта; після першого відкриття форми воно називається «Редагувати накладну».

    Що форма заповнить сама і що перевірити

    ПолеЗвідки береться
    Прізвище, Ім'я, По батькові, Телефон, E-MailІз замовлення
    ІндексІндекс відділення, обраного на вашому сайті Elbuz CMS; інакше — індекс з адреси доставки
    Область, Населений пункт, ВулицяЗ адреси доставки
    Загальна вага, кгСума ваг товарів; порожньо — піде 1 кг
    Оголошена вартість, грнСума замовлення
    Зворотна доставка (одержувач)«Гроші» на суму замовлення, якщо воно не оплачене й оплата — при отриманні
    Платник за доставку«Одержувач», якщо доставка в замовленні 0; інакше «Відправник». Комісію за післяплату сплачує одержувач

    «Спосіб відправлення» — «Відділення» або «Адреса». Курʼєрське замовлення з сайту Elbuz CMS форма відкриває одразу з «Адреса».

    Для відділення Укрпошта бере лише індекс, тому перевірте саме його. Для адреси з'являються «Вулиця», «Дім», «Квартира».

    Форма створення накладної Укрпошти в замовленні
    1Спосіб відправлення
    2Індекс
    3Зворотна доставка
    4SMS-сповіщення
    5Створити накладну
    1. Спосіб відправлення — відділення або адреса.
    2. Індекс — поштовий індекс одержувача, місто підставляється із замовлення.
    3. Зворотна доставка (одержувач) — вибрано «Гроші», сума береться із замовлення.
    4. Перемикач SMS-сповіщення отримувачу.
    5. Кнопка «Створити накладну» — відправляє запит в Укрпошту.

    Форма зберігається в замовлення за кожної зміни поля: відкрили наступного разу — побачите свої значення.

    Що відбувається після «Створити накладну»

    1. Elbuz перевіряє, чи є в записі Укрпошти токен контрагента й UUID відправника, а у формі — прізвище, ім'я, телефон, індекс, місто й оголошена вартість.
    2. Створює в Укрпошті адресу одержувача, потім одержувача, потім саме відправлення.
    3. Номер накладної (штрихкод) записує в замовлення, вікно закривається з повідомленням «Створено товарно-транспортну накладну №…».

    Доставку Укрпошті оплачує той, кого обрано в «Платник за доставку». Другу накладну на те саме замовлення Elbuz не створить: «Накладну вже створено: … — пропущено.»

    Накладна потрапляє в систему Укрпошти одразу. Видалити її з Elbuz не можна — лише в сервісах Укрпошти, після чого очистіть номер у полі «Сервіс доставки: номер» замовлення.

    Якщо зв'язок обірвався, номера в замовленні не буде. Повторне натискання створить нове відправлення, навіть якщо попереднє Укрпошта встигла зареєструвати, — за сумніву уточніть у менеджера Укрпошти.

    Накладні пачкою

    Де: список замовлень → позначте замовлення → «Створити ТТН (доставка)». Служба береться з виду доставки кожного замовлення, значення — із збереженої форми або із замовлення.

    Замовлення з номером накладної пропускаються. Детальніше: накладні пачкою.

    Як надрукувати ярлик

    Де: картка замовлення → «Перегляд накладної» → «Друк» або «Відправлення» → рядок → «Друк накладної».

    Elbuz сам завантажує в Укрпошти адресний ярлик PDF 100×100 мм і відкриває його у вікні. Ключі в браузер не потрапляють. Пачкою з «Відправлення» друкуються лише накладні Нової пошти — ярлики Укрпошти друкуйте по одному.

    Як Elbuz стежить за посилками Укрпошти

    Кожні 10 хвилин Elbuz питає Укрпошту про останній статус кожної накладної. За один прохід — до 100 накладних, першими ті, що найдовше не перевірялися. Номери зі старого модуля Укрпошти теж відстежуються.

    • Які замовлення — створені за останні 60 днів або в позначених статусах, доки код посилки не стане навпроти «Доставлено» в «Статуси доставки».
    • Замовлення в позначеному статусі — статус замовлення, доставки й оплати міняється за вашими таблицями, зміна йде в журнал.
    • Решта замовлень — оновлюються лише код і текст статусу Укрпошти.

    Усі посилки видно у «Відправленні»: стан, плитки, фільтри, SMS одержувачу. Стан береться з таблиці «Статуси доставки»; щоб оновити зараз — «Оновити статуси».

    Сценарії

    Перше підключення

    Що зробити. Підпишіть договір, отримайте в менеджера Bearer, токен контрагента й UUID відправника. Впишіть їх у запис Укрпошти, позначте статуси «Відвантажено» й «Доставлено», заповніть коди в «Статуси доставки» і 41000 навпроти «Доставлено» в «Статуси замовлення».

    Що вийде. Накладні виписуються з картки замовлення, а замовлення самі переходять у «Доставлено», коли Укрпошта вручила посилку.

    Оплата при отриманні

    Що зробити. Залиште в замовленні оплату при отриманні й не відмічайте його оплаченим.

    Що вийде. У формі накладної вже стоїть «Гроші» на суму замовлення, одержувач заплатить у відділенні.

    Замовлення з вашого сайту

    Що зробити. Нічого: покупець на сайті Elbuz CMS обирає відділення Укрпошти.

    Що вийде. Індекс відділення вже у формі, накладна — однією кнопкою.

    Відвантаження дня

    Що зробити. У списку замовлень позначте замовлення Укрпошти → «Створити ТТН (доставка)», потім у «Відправленні» — «Друк» по кожному рядку.

    Що вийде. Номери в замовленнях, ярлики надруковані, статуси підтягнуться самі.

    Що робити, коли щось пішло не так

    Розбір частих проблем
    Що ви бачитеЧому такЩо зробити
    «Служба доставки не підключена: заповніть налаштування API цієї служби…» замість форми У записі Укрпошти порожній «Токен» або вимкнено «Активність» Впишіть Bearer і ввімкніть «Активність» (куди вписати ключі)
    «Error: sender uuid is required (API settings)» або «counterparty token is required (API settings)» Не заповнено «UUID відправника» чи «Токен контрагента» Заповніть блок «Параметри Укрпошти» (ключі API)
    «Error: postcode is required for recipient» (або first_name, last_name, phone, city), «declared_price is required for shipment»; кілька — через кому У формі порожнє обов'язкове поле Заповніть ім'я, прізвище, телефон, індекс, місто чи оголошену вартість (форма)
    «Error: …» з текстом Укрпошти Укрпошта відхилила дані: ключ, індекс, адресу, суму післяплати Виправте поле з тексту помилки; про ключі — до менеджера Укрпошти
    Посилки Укрпошти у «Відправленні» в стані «Невідомо» Таблиця «Статуси доставки» запису Укрпошти порожня Впишіть коди (таблиця кодів)
    Накладні створюються, а статуси посилок не приходять Укрпошта видала окремий Bearer для статус-трекінгу, а поле для нього порожнє Впишіть його в «Токен відстеження (StatusTracking)» (куди вписати ключі)
    «print error: …» у вікні друку Укрпошта не віддала ярлик: накладну видалено або ключ не дійсний Перевірте накладну в сервісах Укрпошти й ключі в записі

    Часті запитання

    Скільки коштує інтеграція з Укрпоштою?

    Elbuz за накладні, ярлики й статуси нічого не списує. Доставку ви оплачуєте Укрпошті за вашим договором.

    Хто платить за доставку — я чи одержувач?

    Як оберете в полі «Платник за доставку». Типово — одержувач, якщо доставка в замовленні 0, інакше ви. Комісію за післяплату завжди сплачує одержувач.

    Чи можна відправити на поштомат чи за кордон?

    Ні, у формі лише відділення та адреса в Україні.

    Чи видно накладні з Elbuz в особистому кабінеті Укрпошти?

    Ні, за документацією Укрпошти відправлення, створені через API, в особистому кабінеті не показуються. Їх видно в Elbuz у «Відправленні».

    Скільки важить посилка максимум?

    За документацією API Укрпошти — до 30 кг для одномісного відправлення. На адресу поза зоною кур'єрської доставки — до 2 кг і 70 см.

    Де це і хто має доступ

    Меню
    Кабінет → Налаштування системи → Інші налаштування → Зовнішні сервіси та інтеграції → Доставка
    Інші входи
    Довідники → Документи → Відправлення → «Служби доставки»; картка замовлення → секція «Доставка»
    Право доступу
    підключення — «API та токени доступу»; накладна — вікно «Створення ТТН служби доставки»; посилки — «Відправлення»
    Підготувати
    договір з Укрпоштою, Bearer, токен контрагента, UUID відправника

    Накладну можна виписати лише для замовлення, яке користувач бачить за налаштуванням «Чиї дані».

    1. Отримати ключі APIМенеджер Укрпошти
    2. Вписати ключі й UUID відправникаЗовнішні сервіси та інтеграції → Укрпошта
    3. Позначити статуси й заповнити кодиТам само, «Налаштування повідомлень»
    4. Виписати накладнуКартка замовлення, секція «Доставка»
    5. Надрукувати ярликКартка замовлення або Відправлення

    Суміжні теми

    Чи була стаття корисною?

    Не вистачає функції? Напишіть нам.

    Ми додамо її безкоштовно, якщо вона знадобиться й іншим.

    Якщо це потрібно тільки вам — домовимося окремо.

    Зміст статті

    Запропонувати доробку

    Спробувати безкоштовно