# Укрпошта + Krokul CRM

Так. Krokul CRM інтегрується з Укрпоштою через eCom API. Менеджер створює відправлення прямо з картки угоди, а Krokul заводить в Укрпошті адресу й одержувача, повертає штрихкод і сам оновлює статус посилки в угоді.

**Статус:** Через API і вебхуки.

## Що отримує команда

### Відправлення Укрпоштою з картки угоди

Менеджер відкриває угоду й натискає «Відправити Укрпоштою». Krokul бере ім’я, телефон і адресу з її контакту, створює в Укрпошті адресу (`/addresses`), клієнта-одержувача (`/clients`) і відправлення (`/shipments`) саме в тому порядку, якого вимагає документація. Штрихкод з’являється у відправленні угоди й у її стрічці.

### Післяплата в межах оголошеної цінності

Для оплати при отриманні менеджер вказує суму, і Krokul передає її в поле postPay відправлення. Укрпошта приймає postPay не більше за declaredPrice, тому Krokul сам ставить оголошену цінність не нижче за цю суму. Стан переказу післяплати Krokul читає з `/transfers/shipment-postpays/{barcode}/with-recipient` і закриває оплату в угоді, коли гроші переказано.

### Рух посилки поруч із листуванням

За розкладом Krokul читає `/shipments/{barcodeOrUuid}/lifecycle` для кожного активного штрихкоду. Статуси на зразок IN_DEPARTMENT чи DELIVERED з’являються в стрічці угоди, а за правилом компанії угода переходить на потрібний етап. Менеджер бачить, де посилка, і не відкриває трекінг окремо.

### Задача менеджеру, коли відправлення повертається

Коли відправлення отримує статус RETURNING, Krokul ставить відповідальному задачу з угодою й штрихкодом. Менеджер устигає зателефонувати клієнту, поки посилка їде назад, а статус RETURNED фіксує в угоді, що товар повернувся.

### Ярлик і форма 103а для групи відправлень

Адресний ярлик відправлення менеджер друкує з картки угоди. Для передачі кількох посилок на відділення Krokul збирає вибрані відправлення й отримує від сервісу форм Укрпошти супровідну форму 103а, яку склад друкує одним файлом.

## Що передається між системами

| Укрпошта | Krokul | Напрям | Коли |
|---|---|---|---|
| Адреса (`/addresses`) і клієнт-одержувач (`/clients`) | Контакт угоди: ім’я, телефон, адреса | Krokul → Укрпошта | Менеджер створює відправлення |
| Відправлення (`/shipments`): вага, declaredPrice, postPay, deliveryType | Відправлення угоди й сума післяплати | Krokul → Укрпошта | Одразу після створення одержувача |
| Штрихкод відправлення | Відправлення в картці угоди, стрічка угоди | Укрпошта → Krokul | У відповідь на створення відправлення |
| Життєвий цикл (`/lifecycle`): IN_DEPARTMENT, DELIVERED, RETURNING, RETURNED | Статус відправлення, запис у стрічці, етап угоди | Укрпошта → Krokul | Krokul опитує за розкладом, доки відправлення активне |
| Статус RETURNING | Задача відповідальному | Укрпошта → Krokul | Відправлення їде назад до відправника |
| Переказ післяплати | Оплата-факт угоди | Укрпошта → Krokul | Коли Укрпошта переказала гроші |
| Адресний ярлик і форма 103а | Кнопки друку у відправленні та в реєстрі відправлень | Укрпошта → Krokul | На запит менеджера чи складу |

## Як підключити сьогодні

### Власний потік через API і вебхуки Krokul

1. Укладіть договір з Укрпоштою й отримайте в менеджера bearer для eCom, токен контрагента та окремі значення для тестового середовища dev.ukrposhta.ua.
2. У Krokul створіть ключ API зі scope на угоди та документи й підпишіть вебхук на подію `card.won` або `card.statusChanged` з фільтром за етапом. Кожна доставка несе заголовок `x-crm-signature`, який ви перевіряєте своїм секретом.
3. На подію створіть в Укрпошті адресу, клієнта-одержувача й відправлення в порядку /addresses → /clients → /shipments, взявши дані з угоди через `card/api-read`.
4. Збережіть штрихкод на угоді через `externalRef/api-upsert`, а статуси з /lifecycle записуйте в стрічку угоди через `activity/api-create`.

### Для інтеграторів

Через публічний API Krokul відправлення Укрпошти можна створювати, читати їхній статус і прив’язувати штрихкод до угоди зовнішнім ключем `externalRef`. Сигнал про готовність до відправки дає підписаний вебхук `card.won` або `card.statusChanged` з фільтром за етапом, а журнал доставок дозволяє повторити подію. Код можна перевірити в пісочниці Krokul на демо-компанії разом із тестовим середовищем Укрпошти.

[Документація API](https://app.krokul.com/api/v1/docs)

## Питання й відповіді

### Чи можна створити відправлення Укрпоштою прямо в картці угоди?

Так. Krokul бере одержувача з контакту угоди, створює адресу, клієнта й відправлення в Укрпошті й показує штрихкод у відправленні угоди.

### Як Krokul дізнається, що посилку Укрпошти вручено?

Krokul сам перепитує життєвий цикл відправлення за штрихкодом, бо Укрпошта не надсилає подій. Статус DELIVERED записується в угоду, і опитування цього відправлення припиняється.

### Що потрібно, щоб підключити Укрпошту до Krokul?

Договір з Укрпоштою. За ним менеджер видає bearer для eCom і для StatusTracking, токен контрагента та окремі значення для тестового середовища, які використовує ваш потік або підключення Krokul до Укрпошти.

### Чи працює післяплата Укрпошти з угодою Krokul?

Так. Сума післяплати йде в поле postPay, а коли Укрпошта переказала гроші, Krokul проводить оплату в угоді фактом.

## Обмеження

Укрпошта не надсилає подій про зміну статусу, тому Krokul читає життєвий цикл відправлення за розкладом. Доступ до API Укрпошта видає за договором, і ключі для бойового й тестового середовищ різні.

## Пов’язані сервіси

- [Нова пошта](https://krokul.com/uk/integrations/nova-poshta/index.md)
- [Meest](https://krokul.com/uk/integrations/meest/index.md)
- [Rozetka](https://krokul.com/uk/integrations/rozetka/index.md)
- [Хорошоп](https://krokul.com/uk/integrations/horoshop/index.md)
- [Checkbox](https://krokul.com/uk/integrations/checkbox/index.md)

[Доставка (Україна)](https://krokul.com/uk/integrations/category/delivery-ua/index.md)

Укрпошта є торговою маркою її власника. Krokul не афілійований з Укрпоштою.

Оновлено: 2026-10-12

---

Застосунок: https://app.krokul.com/ · API: https://app.krokul.com/api/v1/docs