Інтеграція з Укрпоштою в Python
! ! |- | recipient_client_id | uuid | Клієнт-одержувач. |- | Внутрішні листи | Окремий API-сценарій для листів. |- | AC-20 | виступає як повернення. Реальні URI API потрібно брати з актуальної Swagger-документації Укрпошти. | Потрібен для UI та валідації. |- | sms_enabled | boolean | Чи замовлено SMS. |- | Некоректна адреса | API здатна повернути помилку. |- | declared_price | numeric | Оголошена вартість. continue
if old_status != new_status:
Критично критично: user token і authorization bearer потрібно зберігати тільки в зашифрованому вигляді або secret storage. | Перевести в NEEDS_CORRECTION.=== 27.4. Друк ярлика === ! Заборонено зберігати їх у коді, Git, frontend-змінних або відкритих логах. | style="background:#eeeeee;" | Сірий |}
method=method,
def get_shipment(self, shipment_id: str) -> "ShipmentResponse":
params.setdefault("token", self.user_token)
! Критерій
- ID або код відділення;
- поштовий індекс;
- назву;
- адресу;
- населений пункт;
- координати, якщо доступні;
- графік роботи;
- ознаку активності;
- доступні сервіси. |-
| Відстеження відправлень | Отримання статусів доставки. |- | AC-2 | Адміністратор перевіряє підключення. |}
15.8. оновлення версій відправлення
- Який тип договору та доступу до API застосовується для? |-
| Recipient Address | Адреса одержувача. Одержувач
"street": "Хрещатик",
|- | Внутрішня посилка | DOMESTIC_PARCEL | Відправлення по Україні. | Print count збільшується, дія логуються. Дія системи
delivery_queue.enqueue(| Статус стає UNKNOWN_STATUS і потрапляє в список ручної перевірки. | Винести в окремий етап. |- | Ukrposhta Client | - | AC-8 | - | entity_type | varchar | - | height | numeric | - | Міжнародні відправлення | Повернення, retry, неправильна адреса. |- | raw_request | jsonb | Запит. Подія
return existing 22.1. Базовий API-клієнт | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Замовлень до відправки | - | shipment_id | uuid | - | building | varchar | - | Recipient Client | style="background:#c8e6c9;" | Зелений | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Повертається | RETURNING | Відправлення повертається відправнику. payload={"shipment_id": str(shipment.id)},
|
Скасування відправлення | Високий | - | Sender Client | - | Невідомі статуси | - | PostcodeError | інтеграційні функції ERP зберігається в системі. | Довідник відділень оновлюється. №
"postpay_enabled": command.delivery.postpay_enabled, path: str, shipment.status = "CREATED" "external_order_id": command.external_order_id, sender_address = await address_service.ensure_sender_address(shipment) Python-сервіс:
=== 15.7. Створення відправлення ===
=== 22.4. Синхронізація статусів ===
sender_client=sender_client,
! |-
| AC-19
| виступає як помилки створення відправлень. Дія
1. | Перевести в NEEDS_CORRECTION. Поле
"recipient": {
"address_id": "sender-address-id",
try:
audit_logger.log(
db.commit()
10. | style="background:#fff9c4;" | Додаткова
|-
| Група відправлень
| SHIPMENT_GROUP
| Пакетна передача декількох відправлень. №
<syntaxhighlight lang="python">
* менеджер;
* комірник;
* оператор складу. Стан
=== 13.1. Призначення ===
if response.content:
=== 15.12. Dashboard ===
[[Категорія:Технічні завдання]]
K2 ERP / Dashboard / складський облік / Менеджер
! | базовий сценарій для MVP. def track_shipments(self, barcodes: list [str]) -> "TrackingListResponse":
* PDF або інший формат, який повертає API;
* файл зберігається у картці відправлення;
* статус змінюється на LABEL_PRINTED;
* дія логуються в аудиті.=== 21.3. ukrposhta_clients ===
<syntaxhighlight lang="python">
old_status=old_status,
"client_id": "sender-client-id",
!<pre>
return {}
url=f"{self.base_url}/{path.lstrip('/')}",
API Укрпошти має окрему документацію для внутрішніх листів. | style="background:#fff9c4;" | Увага
|-
| Відправлень створено
| Кількість створених відправлень. Дата
def create_shipment_group(self, payload: "ShipmentGroupPayload") -> "ShipmentGroupResponse":
щоб контролювати якість логістики, повернення, затримки та помилки. | style="background:#bbdefb;" | Блакитний
|-
| У дорозі
| IN_TRANSIT
| Відправлення рухається. |-
| new_status
| varchar
| Новий статус. # Як часто синхронізувати статуси? pass
"postcode": "01001", shipment.raw_response = response.raw_payload щоб наклеїти його на посилку. |- |
Фіолетовий | #f3e5f5 | Спеціальний або невідомий статус. SEO-опис
pass
! |-
| Некоректний індекс
| Відправлення здатна не створитись. |-
| print_count
| integer
| Кількість друків. KPI
== 28. MVP ==
user_token: str,
"building": "10",
}
new_status="CREATED",
payload={"external_order_id": command.external_order_id},
{| class="wikitable"
except Exception as exc:
"city": "Львів",
=== 23.1. Типи помилок ===
existing = shipment_repository.get_by_idempotency_key(
self.bearer_token = bearer_token
=== 27.2. Довідники ===
<pre>
! | Barcode зберігається в K2 ERP. * зберігання налаштувань інтеграції;
* перевірку підключення до API;
* створення адреси відправника;
* створення адреси одержувача;
* створення клієнта-відправника;
* створення клієнта-одержувача;
* створення відправлення або групи відправлень;
* друк супровідних документів / ярликів;
* розрахунок вартості доставки, якщо підтримується API;
* перевірку доступності маршруту доставки;
* пошук поштових індексів;
* пошук відділень;
* отримання статусів відправлень;
* синхронізацію статусів назад у K2 ERP;
* підтримку внутрішніх відправлень по Україні;
* підтримку міжнародних відправлень як окремого сценарію;
* журналювання всіх API-запитів;
* dashboard для контролю логістики. |-
| TrackingError
| Не вдалося отримати статус. |}
на `REGISTERED` виступає ключовою рисою У документації для міжнародних відправлень описується lifecycle із полями `status` та `statusDate`; після створення статус змінюється на `CREATED`, а після реєстрації. | Address classifier і ручна перевірка. | платформа повертає успішний або помилковий статус. | style="background:#fff9c4;" | Жовтий
|-
| Створюється
| CREATING
| Виконується API-запит до Укрпошти. |-
| Directory Sync Worker
| Оновлює адресний класифікатор, індекси, відділення. |-
| Дублювання відправлень
| Повторний запит здатна створити друге відправлення.
Як керівник, 6.1. Створення відправлення з K2 ERP"declared_price": command.delivery.declared_price, pass 21.6. ukrposhta_events | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Integration Account | - | postcode | varchar | Поштовий індекс. "first_name": "Іван", | Замовлення | }
платформа повинна не допускати дублювання відправлень. Label Service отримує супровідний ярлик. До MVP не входить: v new_status=new_status, 21.5. ukrposhta_labels15.11. Синхронізація статусів13.2. Основні методи Python-клієнта | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ValidationError | Некоректні інформаційні дані замовлення. |
Він бачить замовлення, відправлення, доставки, повернення та помилки. Очікуваний результат
21.4. ukrposhta_shipments6.3. Синхронізація статусів | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Зелений | #c8e6c9 | - | created_at | timestamp | - | Друк ярлика | }
Технічний стек: Python 3.11+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, httpx, Pydantic, Celery/RQ/APScheduler, Redis, Docker. |- |
error_message | text | Помилка. )
db: "Session", POST /api/v1/ukrposhta/integrations |
- | AC-11 | користувач системи натискає «Друк ярлика». SEO-опис | Check-connection і повідомлення адміністратору.</syntaxhighlight>
"street": "Січових Стрільців", Як комірник, shipment.status = "NEEDS_RETRY"критично: для роботи з API Укрпошти використовуються user token та authorization bearer, які потрібно отримати після підписання договору. ! |-
| file_id
| uuid
| Файл у сховищі. self.timeout_seconds = timeout_seconds
! # Чи потрібна післяплата? |}
}
{| class="wikitable"
shipment.sent_at = utc_now()
def create_address(self, payload: "AddressPayload") -> "AddressResponse":
new_status="PENDING_CREATE",
)
shipment=shipment,
я хочу надрукувати супровідний ярлик по створеному відправленню,
UKRPOSHTA_LABEL_BASE_URL=https://www.ukrposhta.ua/ecom/0.0.1/
=== Етап 6. Статуси та друк ===
=== 21.2. ukrposhta_addresses ===
verify_ssl: bool = True
timeout_seconds: int = 30
'''критично:''' методи Python-клієнта виступає як внутрішньою абстракцією. |-
| Swagger
| Технічна документація API. | Черга, API-статуси, транспортування. |-
| ukrposhta_status
| varchar
| Оригінальний статус API. SEO-опис
! SEO-опис
self.user_token = user_token
v
<pre>
|-
| AC-4
| платформа запускає синхронізацію індексів. Очікуваний результат
async def send_ukrposhta_shipment(shipment_id: str, db: "Session") -> None:
entity_id=shipment.id,
UKRPOSHTA_BEARER_TOKEN=********
== 31. Відкриті питання ==
=== Етап 3. Ukrposhta Client ===
! |-
| Створення відправлення
| Shipment ID, barcode, дата, відповідь API. | style="background:#bbdefb;" | Групова
|}
{| class="wikitable"
"building": "1",
if existing:
)
POST /api/v1/ukrposhta/shipments
def track_shipment(self, barcode: str) -> "TrackingResponse":
|-
| Чернетка
| DRAFT
| Замовлення виступає як в K2 ERP, але відправлення ще не створено. !=== 8.4. Dashboard керівника ===
* створити FastAPI-проєкт;
* налаштувати PostgreSQL;
* створити моделі інтеграції, адрес, клієнтів, відправлень, ярликів, подій;
* налаштувати Alembic;
* реалізувати healthcheck. ! |-
| Помилка API
| Код, повідомлення, raw-відповідь. | Не створювати відправлення, показати список помилок. |-
| payload
| jsonb
| Технічні інформаційні дані.=== 15.9. Скасування / видалення відправлення ===
{| class="wikitable"
== 18. Адресний класифікатор і довідники ==
=== 23.2. Retry-логіка ===
{| class="wikitable"
shipment = shipment_repository.get_by_id(db, shipment_id)
payload={
== 24. Dashboard менеджера і керівника ==
shipment.delivered_at = utc_now()
v
== 3. Основні функції ERP API Укрпошти ==
[[Категорія:Ukrposhta API]]
Retry заборонений для:
! SEO-опис
def update_shipment(self, shipment_id: str, payload: "ShipmentPayload") -> "ShipmentResponse":
}
=== 8.1. Створення відправлення ===
! Поле
"middle_name": "Іванович",
sender_client = await client_service.ensure_sender_client(shipment, sender_address)
<pre>
=== 22.2. Створення відправлення ===
! Замовлення, клієнт ERP, адреса, вантаж
K2 ERP / CRM / Website / WMS
event_type="UKRPOSHTA_SHIPMENT_QUEUED",
|
| 2. | Потрібен для синхронізації з K2 ERP.== 10. Статуси відправлень ==
* https://dev.ukrposhta.ua/
* https://dev.ukrposhta.ua/documentation
* https://dev.ukrposhta.ua/faq
* https://dev.ukrposhta.ua/for-business
* API documentation 2025. |-
| AC-17
| API повертає невідомий статус. Розділ API
* неправильного user token;
* неправильного bearer token;
* помилок валідації;
* неправильного індексу;
* недоступного маршруту;
* некоректного телефону;
* відправлення, яке вже створене;
* відправлення, яке вже доставлене;
* відправлення, яке вже скасоване. SEO-опис
6. Критерій
платформа повинна забезпечити:
офіційний портал API Укрпошти містить такі ключові напрями:
! |-
| created_at
| timestamp
| Дата створення. Python-сервіс виконує валідацію. | style="background:#fff9c4;" | Контроль
|-
| Доставлено
| Успішні доставки.[[Категорія:Python]]
<syntaxhighlight lang="python">
* інший формат створення;
* митний SEO-опис;
* категорію вкладення;
* країну призначення;
* англомовні адресні поля;
* обмеження по вазі;
* додаткові статуси;
* друк митних або супровідних документів. | style="background:#ffcc80;" | Потрібна дія
|-
| Помилки API
| Помилки створення або статусів. Сутність
finally:
</pre>
=== Етап 5. Відправлення і валідація ===
! Колір
response = await client.request(
def delete_shipment(self, shipment_id: str) -> "DeleteShipmentResponse":
},
== 7. Основні сутності ==
command: "CreateUkrposhtaShipmentCommand",
* перевіряє замовлення;
* перевіряє одержувача;
* перевіряє адресу та індекс;
* створює або знаходить адресу відправника;
* створює або знаходить адресу одержувача;
* створює або знаходить клієнта-відправника;
* створює або знаходить клієнта-одержувача;
* створює відправлення;
* зберігає barcode / shipment UUID / номер відправлення;
* формує супровідний ярлик;
* передає номер відправлення назад у K2 ERP. |-
| Відділення
| 1 раз на добу або за потреби
| Потрібні для вибору точки відправлення/видачі. Тип
def get_label(self, shipment_id: str, format: str = "pdf") -> bytes:
audit_logger.log(
params: dict | None = None,
self,
|-
| API Layer
| REST API для прийому замовлень і команд із K2 ERP. |-
| region
| varchar
| Область. SEO-опис
{| class="wikitable"
Як менеджер,
ukrposhta_validator.validate(command)
payload=status_response.raw_payload,
<pre>
"idempotency_key": "K2-ORDER-2026-000123-ukrposhta-v1",
POST /api/v1/ukrposhta/shipments/{shipment_id}/cancel
Приклад hash:
from pydantic_settings import BaseSettings
def __init__(
<pre>
status_response = await ukrposhta_client.track_shipment(barcode)
if new_status == "DELIVERED":
<pre>
if shipment.status in ["CREATED", "REGISTERED", "DELIVERED"] and shipment.barcode:
{| class="wikitable"
=== 24.1. Основні KPI ===
shipment.error_message = str(exc)
</div>
"postpay_enabled": true,
! # Чи потрібно експортувати журнал відправлень в Excel? | style="background:#ffcc80;" | Потрібна дія
|}
Для реалізації задачі необхідно отримати:
=== 15.4. Пошук індексів ===
"height": 15,
=== 27.5. Статуси ===
"barcode": shipment.barcode,
|-
| Замовлень до відправки
| 42
| style="background:#fff9c4;" | Увага
|-
| Відправлень створено сьогодні
| 185
| style="background:#c8e6c9;" | Норма
|-
| Ярлики надруковано
| 172
| style="background:#c8e6c9;" | Норма
|-
| У дорозі
| 620
| style="background:#bbdefb;" | В роботі
|-
| Прибуло
| 88
| style="background:#fff9c4;" | Контроль
|-
| Доставлено
| 410
| style="background:#c8e6c9;" | Норма
|-
| Повернення
| 21
| style="background:#ffcc80;" | Потрібна дія
|-
| Помилки створення
| 5
| style="background:#ef9a9a;" | Критично
|-
| Потребують виправлення
| 9
| style="background:#ffcc80;" | Потрібна дія
|}
=== 6.5. Внутрішні листи ===
Перед створенням відправлення платформа повинна перевірити:
},
'''Критично критично:''' якщо відправлення вже створене, повторний запит не повинен створювати нове відправлення. ! Ризик
== 2. Область сценарії використання ==
</pre>
"Authorization": f"Bearer {self.bearer_token}",
== 17. Валідація перед створенням відправлення ==
! Код
=== 15.3. Синхронізація адресних довідників ===
створення відправлень забезпечується через '''Головна ідея:''' розробити Python-сервіс, який інтегрує K2 ERP / CRM / інтернет-магазин / WMS з API Укрпошти; так само реалізовано адрес, клієнтів, друку супровідних ярликів, розрахунку вартості, трекінгу статусів і контролю доставки. Worker створює клієнта-відправника, якщо потрібно. №
3. # Чи потрібно формувати групи відправлень? |-
| AC-3
| Token неправильний. | платформа повертає PDF або інший доступний формат.=== Етап 8. Production hardening ===
! платформа повинна повернути існуючий barcode / shipment_id та його поточний статус. | Окремий сценарій із власними правилами. ! |-
| idempotency_key
| Унікальний ключ конкретної спроби створення відправлення. # Чи потрібно підтримувати декілька відправників? | Перевести в NEEDS_RETRY. |-
| raw_response
| jsonb
| Відповідь API. # Який формат друку потрібен: A4, термопринтер, PDF? | style="background:#c8e6c9;" | Зелений
|-
| Ярлик надруковано
| LABEL_PRINTED
| Супровідний ярлик отримано або надруковано. Worker створює адресу відправника, якщо її ще немає. | платформа показує AuthError і не створює відправлення. |-
| Address Classifier
| Адресний класифікатор. |-
| shipment_id
| varchar
| ID відправлення в API Укрпошти. | Черга, retry, dashboard помилок. SEO-опис
import httpx
Метою задачі виступає як створення Python-сервісу для інтеграції з Укрпоштою з метою автоматизації процесів доставки. |-
| event_type
| varchar
| Тип події. |-
| Міжнародні відправлення складніші
| Потрібні митні й країнові поля. SEO-опис
Результат:
Python Ukrposhta Integration Service
{| class="wikitable"
"phone": "+380501112233",
! "phone": "+380671112233",
* реалізувати dashboard API;
* реалізувати список проблемних відправлень;
* реалізувати фільтри;
* реалізувати експорт, якщо потрібно. |}
</pre>
pass
[[Категорія:Логістика]]
entity_type="ukrposhta_shipment",
retry_backoff_seconds: int = 5
pass
UKRPOSHTA_LANGUAGE=ua
POST /api/v1/ukrposhta/routes/check-availability
response = await ukrposhta_client.create_shipment(payload)
== 16. Приклад запиту на створення відправлення ==
== Див. 33. так само ==
pass
db=db,
13. |-
| AC-5
| платформа запускає синхронізацію відділень. |-
| Shipment Group
| Група відправлень. |-
| Адресний класифікатор
| 1 раз на добу або за регламентом
| здатна бути великим довідником. |-
| district
| varchar
| Район. Worker створює адресу одержувача. №
"apartment": "5"
shipment.ukrposhta_status = status_response.status
=== Етап 4. Адреси та клієнти ===
'''Для K2 ERP:''' цей workflow потрібно приховати від користувача. Колір
"last_name": "Петренко",
"length": 30,
<pre>
GET /api/v1/ukrposhta/shipments/{shipment_id}/label
"region": "Київська",
<pre>
shipment.status = new_status
=== 24.3. Проблемні відправлення ===
<syntaxhighlight lang="python">
До MVP входить:
db=db,
return response.json()
json: dict | None = None,
{| class="wikitable"
bearer_token: str,
"sms": true
! |-
| Типи відправлень
| 1 раз на добу або після зміни API
| Потрібні для валідації. Критерій
|-
| AC-7
| K2 ERP передає валідне замовлення. | Валідація індексу до API-запиту. | Повернути існуюче відправлення. |-
| client_type
| varchar
| sender або recipient. # Чи потрібна інтеграційні функції ERP з K2 ERP документами реалізації та оплат? Критерій
'''Управлінський результат:''' менеджер, складський облік і керівник повинні бачити, скільки відправлень створено, скільки ярликів надруковано, які посилки доставлені, які повертаються, які мають помилки адреси, індексу, оплати або статусу. |-
| Зміна API
| Можуть змінитись URI або поля. Очікуваний результат
):
== 15. API Python-сервісу ==
== 19. Дедублікація ==
=== 27.3. Створення відправлення ===
entity_type="ukrposhta_shipment",
Ukrposhta API Client
language: str = "ua"
! |-
| Недоступність API
| Відправлення не створюються. |-
| PhoneValidationError
| Некоректний телефон одержувача. Що зберігати
params = params or {}
"address": {
shipment = shipment_repository.create(
! |}
{| class="wikitable"
! |}
"shipment_type": command.shipment_type,
shipment = shipment_repository.get_by_barcode(db, barcode)
__TOC__
}
<div style="border-left: 6px solid #2e7d32; background: #e8f5e9; padding: 12px 16px; margin: 16px 0;">
|-
| id
| uuid
| ID ярлика. | здатна бути окремим модулем. |-
| source
| varchar
| K2_ERP, PYTHON_SERVICE, UKRPOSHTA, USER. |}
<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">
except TemporaryUkrposhtaError as exc:
POST /api/v1/ukrposhta/directories/sync
== 32. Джерела ==
! "city": "Київ",
<pre>
! |-
| style="background:#ef9a9a;" | Червоний
| #ef9a9a
| Помилка або негативний результат. ! |-
| user_token_encrypted
| text
| Зашифрований user token. |-
| TimeoutError
| Перевищено час очікування. "declared_price": 1500.00,
"shipment_type": "DOMESTIC_PARCEL",
"description": "Одяг",
def create_shipment(self, payload: "ShipmentPayload") -> "ShipmentResponse":
12. | Повторити фоново. |-
| street
| varchar
| Вулиця. |-
| Dashboard API
| інформаційні дані для менеджера, складу та керівника. | style="background:#ef9a9a;" | Критично
|-
| Потребують виправлення
| Некоректні адреси, індекси, телефони. Worker створює клієнта-одержувача. |-
| style="background:#bbdefb;" | Блакитний
| #bbdefb
| операційна дія виконується або доставка в процесі. | Відправлення не створюється без виправлення. SEO-опис
* індекс;
* область;
* район;
* населений пункт;
* вулицю, якщо доступна;
* відділення, якщо прив'язане;
* ознаку активності;
* дату оновлення версій. |-
| is_active
| boolean
| Активність. | Статус стає RETURNING і підсвічується помаранчевим. Призначення
=== 6.2. Друк ярлика ===
! Де застосовується для
</div>
"shipment_id": shipment.shipment_id,
{| class="wikitable"
if not shipment:
Потрібно зберігати:
{| class="wikitable"
Retry дозволений для:
{
"address": {
{{DISPLAYTITLE:Технічне завдання: Інтеграція з Укрпоштою для Python}}
я хочу натиснути кнопку «Створити відправлення Укрпошта»,
{| class="wikitable"
4. |-
| Пошук відділень та індексів
| Пошук індексів, відділень, адресних даних.</pre>
POST /api/v1/ukrposhta/tracking/sync
== 26. Логування та аудит ==
|-
| Поштові індекси
| 1 раз на добу або за потреби
| Потрібні для валідації адрес. recipient_address = await address_service.ensure_recipient_address(shipment)
user_token: str
payload = ukrposhta_mapper.to_shipment_payload(
[[Категорія:Доставка]]
2. |-
| AuthError
| Невірний user token або bearer token. Як зменшити
|-
| Неправильний token
| інтеграційні функції ERP не працюватиме. |}
Ukrposhta Client — це Python-клас або пакет, який інкапсулює роботу з API Укрпошти. # Чи потрібно зберігати адреси одержувачів у K2 ERP? |-
| delivered_at
| timestamp
| Дата доставки. Призначення
{| class="wikitable"
)
Після створення відправлення платформа повинна отримати супровідний документ / sticker / label. Створити адресу відправника. | style="background:#ef9a9a;" | Червоний
|-
| Потребує повтору
| NEEDS_RETRY
| Технічна помилка, можна повторити. | Відправлення не створюється, статус NEEDS_CORRECTION. |-
| Друк ярлика
| Високий
| Потрібно для складу. |}
=== 18.2. Відділення ===
)
{| class="wikitable"
* підписаний договір з Укрпоштою;
* user token;
* authorization bearer;
* доступ до API-документації;
* тестове середовище або тестові інформаційні дані, якщо надаються;
* інформаційні дані відправника;
* адресу відправника;
* контактну особу відправника;
* правила оплати доставки;
* правила післяплати;
* правила міжнародних відправлень, якщо потрібні;
* правила друку ярликів;
* правила оновлення версій статусів;
* перелік сервісів доставки, які будуть використовуватись;
* вимоги K2 ERP до збереження номерів відправлень. | style="background:#ffcc80;" | Помаранчевий
|-
| Потребує виправлення
| NEEDS_CORRECTION
| Некоректна адреса, індекс або інформаційні дані одержувача. Створити клієнта-відправника. |-
| RouteUnavailableError
| Маршрут доставки недоступний. Tracking Worker оновлює статуси доставки. |-
| Адресний класифікатор
| Робота з адресами, індексами та населеними пунктами.</pre>
Укрпошта
<pre>
</pre>
</pre>
<pre>
=== 12.2. Основні компоненти Python-сервісу ===
</div>
class UkrposhtaApiError(Exception):
платформа повинна логувати:
GET /api/v1/ukrposhta/postcodes?query=01001
інтеграційні функції ERP призначена для:
new_status = ukrposhta_status_mapper.from_api(status_response)
Офіційна інструкція «Як почати роботу з API» описує базовий workflow: створити адресу відправника, створити адресу одержувача, створити клієнта-відправника, створити клієнта-одержувача, створити відправлення або групу відправлень, після чого надрукувати супровідні документи. |-
| Post Office
| Відділення Укрпошти. | Вони підсвічуються помаранчевим. )
UKRPOSHTA_RETRY_BACKOFF_SECONDS=5
</div>
headers = {
Як менеджер інтернет-магазину,
<pre>
async def sync_ukrposhta_statuses(barcodes: list [str], db: "Session") -> None:
3. Ключ
! Створюється запис delivery_order зі статусом PENDING_CREATE. ! Критерій
|-
| Відправлення по Україні
| Створення внутрішніх поштових відправлень. SEO-опис
pass
pass
def search_postcodes(self, filters: dict) -> "PostcodeListResponse":
def search_post_offices(self, filters: dict) -> "PostOfficeListResponse":
! |-
| default_sender_address_id
| varchar
| Адреса відправника за замовчуванням. Коментар
shipment.error_message = str(exc)
shipment.shipment_id = response.id
! Довідник
Міжнародні відправлення потрібно реалізовувати окремим модулем, тому що вони можуть мати:
</pre>
entity_id=shipment.id,
) -> "UkrposhtaShipment":
! Worker створює відправлення. |-
| Audit Logger
| Зберігає запити, відповіді, помилки та зміни статусів. |-
| AC-15
| Відправлення доставлено. |-
| DuplicateShipmentError
| Відправлення вже створено. | застосовується для розробниками. API повертає shipment_id / barcode. |}
timeout_seconds: int = 30,
}
return
entity_type="ukrposhta_shipment",
UKRPOSHTA_USER_TOKEN=********
|-
| id
| uuid
| Внутрішній ID. | style="background:#f3e5f5;" | Фіолетовий
|-
| Скасовано
| CANCELLED
| Відправлення або замовлення скасовано.<div style="border-left: 6px solid #2e7d32; background: #e8f5e9; padding: 12px 16px; margin: 16px 0;">
* реалізувати створення адреси відправника;
* реалізувати створення адреси одержувача;
* реалізувати кешування адрес;
* реалізувати створення клієнтів;
* реалізувати повторне використання клієнтів. |-
| barcode
| Штрихкод / номер відправлення. Статус K2 ERP
=== 8.2. Друк ярлика ===
* наявність external_order_id;
* наявність idempotency_key;
* чи не створено вже відправлення для цього замовлення;
* user token активний;
* bearer token активний;
* ПІБ або назву одержувача;
* телефон одержувача;
* індекс одержувача;
* адресу одержувача;
* індекс відправника;
* адресу відправника;
* доступність маршруту між індексами, якщо застосовується для перевірка;
* вагу більше 0;
* габарити більше 0, якщо обов'язкові;
* оголошену вартість;
* післяплату, якщо застосовується для;
* SMS-опцію, якщо застосовується для;
* коректність типу відправлення;
* коректність міжнародних полів, якщо це міжнародне відправлення. |-
| Sender Address
| Адреса відправника. Критерій
я хочу бачити статистику по доставках Укрпоштою,
</div>
|
| 1. | Показати менеджеру. |-
| Синхронізація статусів
| Середній
| Фоновий бізнес-процес. 14. | style="background:#ffcc80;" | Важлива
|-
| Внутрішній лист
| DOMESTIC_LETTER
| Лист по Україні. SEO-опис
|-
| AC-1
| Адміністратор створює інтеграцію Укрпошти. |-
| Валідація
| Результат, список помилок. Створити відправлення або групу відправлень. |-
| AC-13
| Ярлик друкується повторно. |-
| city
| varchar
| Місто / населений пункт. retry_count: int = 3
* реалізувати базовий request method;
* реалізувати create_address;
* реалізувати create_client;
* реалізувати create_shipment;
* реалізувати get_label;
* реалізувати track_shipment;
* реалізувати check_route_availability;
* реалізувати обробку помилок. | style="background:#ffcc80;" | Помаранчевий
|-
| Помилка
| ERROR
| Помилка створення або синхронізації. |-
| barcode
| varchar
| Штрихкод / номер відправлення. '''Критично критично:''' інтеграційні функції ERP не повинна створювати дублікати відправлень. * створено;
* зареєстровано;
* прийнято;
* у дорозі;
* прибуло;
* доставлено;
* вручено;
* повертається;
* повернуто;
* скасовано;
* помилка;
* невідомий статус. | style="background:#fff9c4;" | Жовтий
|-
| Доставлено
| DELIVERED
| Відправлення вручено / доставлено. |-
| weight
| numeric
| Вага. |-
| AddressError
| Некоректна адреса. |}
! |-
| shipment_id
| ID відправлення в API Укрпошти. |-
| postpay_enabled
| boolean
| Чи виступає як післяплата. |}
{| class="wikitable"
for barcode in barcodes:
idempotency_key=command.idempotency_key,
bearer_token: str
=== 8.3. Контроль статусів ===
[[Категорія:API]]
! Тип
! |-
| AC-10
| Адреса некоректна. |-
| shipment_hash
| Hash основних параметрів відправлення. |-
| status
| varchar
| Статус K2 ERP. Користувачі:
UKRPOSHTA_TIMEOUT_SECONDS=30
! | style="background:#c8e6c9;" | Зелений
|-
| Передано Укрпошті
| ACCEPTED_BY_UKRPOSHTA
| Відправлення прийнято оператором. class UkrposhtaClient:
! Тип
! |-
| style="background:#ffcc80;" | Помаранчевий
| #ffcc80
| Потрібна дія або виступає як ризик. |}
я хочу бачити статус доставки прямо в K2 ERP,
! |-
| provider
| varchar
| ukrposhta. |-
| default_sender_client_id
| varchar
| Клієнт-відправник за замовчуванням. |-
| entity_id
| uuid
| ID сутності. |-
| API Event
| Подія інтеграції. {| class="wikitable"
щоб оперативно реагувати на повернення, затримки та проблемні доставки.== 4. Передумови ==
sha256(external_order_id + recipient_phone + recipient_postcode + declared_price + weight) params=params, 20. Черга створення відправленьasync def create_ukrposhta_shipment( 9. Типи відправленьif response.status_code >= 400: event_type="UKRPOSHTA_SHIPMENT_CREATED", pass
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||