Elbuz підключається до Укрпошта API і виписує накладну прямо з картки замовлення, друкує ярлик і кожні 10 хвилин приносить статус посилки — без переписування даних у сервіси Укрпошти.
Коли це знадобиться:
- Відправляєте Укрпоштою за договором — одержувач, індекс і сума підставляються із замовлення, накладна — однією кнопкою.
- Клієнт платить при отриманні — післяплата на суму замовлення ставиться сама, якщо замовлення не оплачене.
- Посилок багато — накладні пачкою зі списку замовлень, статуси всіх посилок — у вікні «Відправлення».
З чого почати: отримайте ключі API в менеджера Укрпошти → впишіть їх у запис Укрпошти в Elbuz.
Що вміє Укрпошта в Elbuz
- Накладна із замовлення — на відділення або на адресу, з післяплатою й SMS одержувачу; по одній або пачкою.
- Ярлик — PDF з картки замовлення або з «Відправлення».
- Статуси посилок — кожні 10 хвилин; за вашою таблицею кодів Elbuz міняє статус замовлення, доставки й оплати.
- Стан посилки у «Відправленні» — у дорозі, у відділенні, отримано, відмова.
Реєстри, переадресація, повернення, зміна й видалення накладної та виклик кур'єра з Elbuz серед українських служб є лише в Нової пошти. Для Укрпошти ці дії — в її сервісах.
Як підключити Укрпошту: ключі API і відправник
Де взяти ключі API Укрпошти
Ключі видає менеджер Укрпошти після підписання договору — в особистому кабінеті на сайті їх немає. За документацією API Укрпошти після договору ви отримуєте таблицю доступів:
- Bearer eCom — для створення відправлень;
- Bearer StatusTracking — для статусів посилок;
- Counterparty token — токен користувача;
- Counterparty UUID — ідентифікатор контрагента.
Ще потрібен UUID відправника — ідентифікатор клієнта-відправника з вашою адресою в системі Укрпошти. Його створюють через API; попросіть менеджера або технічну підтримку API (api-support@ukrposhta.ua) дати готовий UUID. Особистий кабінет на сайті Укрпошти — окрема послуга для фізичних осіб: відправлень, створених через API, у ньому не видно.
Куди вписати ключі в Elbuz
Де: Зовнішні сервіси та інтеграції → група «Доставка» → запис Укрпошти.
- У поле «Токен» вставте Bearer eCom.
- У блоці «Параметри Укрпошти» заповніть «Токен контрагента (counterparty token)» і «UUID відправника».
- Якщо менеджер видав окремий Bearer StatusTracking, впишіть його в «Токен відстеження (StatusTracking)». Порожнє поле — статуси запитуються з тим самим «Токен».
- Увімкніть «Активність».
Поля «Користувач» і «Пароль» для Укрпошти не потрібні. Збереженого ключа не видно: поле «Токен» показує крапки, порожнє поле ключ не стирає.
1
Токен (Bearer eCom)2
Токен контрагента3
Токен відстеження4
Статуси замовлень для перевірки5
UUID відправника- Токен — Bearer-ключ eCom, у полі показано лише крапки.
- Токен контрагента (counterparty token) — його видає Укрпошта під час підключення до API.
- Токен відстеження (StatusTracking) — окремий ключ для запитів статусів; може бути порожнім.
- Список статусів замовлень, за якими перевіряється статус посилки.
- UUID відправника — ідентифікатор відправника в Укрпошті.
Статуси доставки: які коди Укрпошти вписати
Elbuz міняє статус замовлення лише для замовлень у статусах, позначених у списку «Статуси замовлень, за якими перевіряти статус посилки в службі доставки». Що на що міняти, задають три вікна в блоці «Налаштування повідомлень»: «Статуси замовлення», «Статуси доставки», «Статуси оплати».
Коди Укрпошти в «Статуси доставки» Elbuz вписує сам, за ними «Відправлення» показують стан посилки. «Статуси замовлення» й «Статуси оплати» заповнюєте ви, через кому. Коди — з документації статус-трекінгу Укрпошти:
| Ваш статус доставки | Коди Укрпошти | Що означають |
|---|---|---|
| Чекання від відправника | 10100 | Прийнято у відділенні |
| У дорозі | 20700, 20800, 20900, 21500 | Сортувальний центр, відправлено, прямує до відділення доставки |
| У пункті призначення | 21700, 21400, 31400 | Надійшло у відділення доставки, на зберіганні |
| Доставлено | 41000 | Вручено |
| Відмова від отримання | 31200, 41010 | Посилка повертається відправнику, повернення вручено вам |
1
Колонка кодів Укрпошти2
У пункті призначення3
Відмова від отримання- Колонка «Код (назва) на сайті (API)» — коди статусів Укрпошти.
- «У пункті призначення» — коди 21700, 21400, 31400.
- «Відмова від отримання» — коди 31200 і 41010.
Щоб замовлення саме ставало «Доставлено», у «Статуси замовлення» навпроти «Доставлено» впишіть 41000. Elbuz перестає питати про посилку, лише коли її код стоїть навпроти «Доставлено» чи «Доставлено частково» в «Статуси доставки».
Повернення, вручене вам, Укрпошта позначає кодом вручення з причиною «відправнику» — Elbuz показує його як 41010, окремо від 41000.
Як створити накладну Укрпошти із замовлення
Де: картка замовлення → секція «Доставка» → «Створити накладну». Посилання є, якщо вид доставки замовлення — Укрпошта; після першого відкриття форми воно називається «Редагувати накладну».
Що форма заповнить сама і що перевірити
| Поле | Звідки береться |
|---|---|
| Прізвище, Ім'я, По батькові, Телефон, E-Mail | Із замовлення |
| Індекс | Індекс відділення, обраного на вашому сайті Elbuz CMS; інакше — індекс з адреси доставки |
| Область, Населений пункт, Вулиця | З адреси доставки |
| Загальна вага, кг | Сума ваг товарів; порожньо — піде 1 кг |
| Оголошена вартість, грн | Сума замовлення |
| Зворотна доставка (одержувач) | «Гроші» на суму замовлення, якщо воно не оплачене й оплата — при отриманні |
| Платник за доставку | «Одержувач», якщо доставка в замовленні 0; інакше «Відправник». Комісію за післяплату сплачує одержувач |
«Спосіб відправлення» — «Відділення» або «Адреса». Курʼєрське замовлення з сайту Elbuz CMS форма відкриває одразу з «Адреса».
Для відділення Укрпошта бере лише індекс, тому перевірте саме його. Для адреси з'являються «Вулиця», «Дім», «Квартира».
1
Спосіб відправлення2
Індекс3
Зворотна доставка4
SMS-сповіщення5
Створити накладну- Спосіб відправлення — відділення або адреса.
- Індекс — поштовий індекс одержувача, місто підставляється із замовлення.
- Зворотна доставка (одержувач) — вибрано «Гроші», сума береться із замовлення.
- Перемикач SMS-сповіщення отримувачу.
- Кнопка «Створити накладну» — відправляє запит в Укрпошту.
Форма зберігається в замовлення за кожної зміни поля: відкрили наступного разу — побачите свої значення.
Що відбувається після «Створити накладну»
- Elbuz перевіряє, чи є в записі Укрпошти токен контрагента й UUID відправника, а у формі — прізвище, ім'я, телефон, індекс, місто й оголошена вартість.
- Створює в Укрпошті адресу одержувача, потім одержувача, потім саме відправлення.
- Номер накладної (штрихкод) записує в замовлення, вікно закривається з повідомленням «Створено товарно-транспортну накладну №…».
Доставку Укрпошті оплачує той, кого обрано в «Платник за доставку». Другу накладну на те саме замовлення 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 відправника
Накладну можна виписати лише для замовлення, яке користувач бачить за налаштуванням «Чиї дані».
- Отримати ключі APIМенеджер Укрпошти
- Вписати ключі й UUID відправникаЗовнішні сервіси та інтеграції → Укрпошта
- Позначити статуси й заповнити кодиТам само, «Налаштування повідомлень»
- Виписати накладнуКартка замовлення, секція «Доставка»
- Надрукувати ярликКартка замовлення або Відправлення
Суміжні теми
- Якщо потрібно бачити посилки всіх служб в одному списку — Відправлення.
- Якщо відправляєте ще й Новою поштою — Нова пошта API в Elbuz.
- Якщо замовлення прийшло з Rozetka й накладну треба виписати через маркетплейс — накладна через Rozetka.
- Якщо накладні треба виписати по десятках замовлень — накладні пачкою.
