Інтеграція з Мурашина логістика в Python

! |}

щоб контролювати проблемні доставки та відхилення. |- | ANT-Logistics Client | Python-клієнт для API ANT-Logistics. |- | Route | Маршрут, сформований у ANT-Logistics.== 23. Логування та аудит ==

entity_id=order.id,

18.3. ant_delivery_orders

|- | Integration Account | конфігурація підключення до ANT-Logistics. | style="background:#eeeeee;" | Сірий |- | Очікує передачі | PENDING_SEND | Заявка в черзі на передачу. Замовлення, точки, склади, авто, водії ! Route Sync Worker отримує маршрути. |- | is_active | boolean | Активність. | Статус підсвічується помаранчевим. |- | ANT Task | Задача / точка доставки в ANT-Logistics. | style="background:#ffcc80;" | Помаранчевий |- | Відмовлено | REJECTED_BY_CLIENT | клієнт ERP відмовився від доставки. |- | fact_arrival_at | timestamp | Фактичне прибуття. |- | planned_duration | integer | Планова тривалість. |}

інтеграційні функції ERP призначена для:

order.status = "SEND_ERROR"

! | style="background:#ffcc80;" | Потрібна дія |- | Потребують повтору | Технічні помилки передачі. |- | vehicle_id | uuid | Автомобіль. entity_type="delivery_order",

8.2. Замовлення / заявка на доставку

idempotency_key=command.idempotency_key,

|- | external_order_id | string | Так | ID замовлення в K2 ERP. Python-сервіс виконує валідацію. |- | style="background:#eeeeee;" | Сірий | #eeeeee | Чернетка, скасовано або неактивно. Значення

"external_order_id": "K2-ORDER-2026-000123",

Етап 1. Аналіз API ANT-Logistics

order.sent_at = utc_now()

== 15. Валідація заявки ==
 audit_logger.log(
=== Етап 7. Production hardening ===

Поля:

платформа повинна логувати:
== 5. Основні бізнес-сценарії ==
 "payment": {
 verify_ssl: bool = True

! Тип помилки

• створення інтеграції ANT-Logistics;
• перевірка підключення;
• передача торгових точок;
• передача заявок на доставку;
• передача складів;
• передача автомобілів;
• передача водіїв;
• збереження ANT task ID;
• синхронізація маршрутів;
• синхронізація статусів доставки;
• дедублікація;
• retry-механізм;
• журнал подій;
• dashboard API;
• базові unit-тести;
• mock ANT API для інтеграційних тестів. |-

| finished_at | timestamp | Завершення маршруту. | Внутрішній контроль для логіста та керівника. Що зберігати

12. ANT-Logistics Client

13.12. Dashboard

"cargo": {

=== 5.1. Передача замовлень на доставку ===
! клієнт ERP
Сервіс повинен забезпечити:
! | Зовнішня логістична платформа. Хрещатик, 1",
 task_payload = ant_mapper.to_task_payload(order, point_response.point_id)

Python-сервіс повинен:
 order = delivery_order_repository.get_by_id(db, delivery_order_id)
 payload=status_response.raw_payload,
! |-
| work_time_to
| time
| Кінець робочого часу. |-
| comment
| text
| Коментар. |-
| Route Stop
| Окрема точка маршруту. def create_delivery_task(self, payload: "DeliveryTaskPayload") -> "AntTaskResponse":

<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">

! |}

 new_status=new_status,

=== 13.5. Синхронізація водія ===
ANT_LOGISTICS_API_KEY=********
 order.ant_task_id = task_response.task_id

=== 13.4. Синхронізація автомобіля ===

ANT_LOGISTICS_BASE_URL=https://api.example.ant-logistics

 old_status=old_status,

=== 8.1. Торгові точки / клієнти ===
POST /api/v1/ant-logistics/delivery-orders/{order_id}/cancel
 entity_id=order.id,
! Подія

 audit_logger.log(

 def get_task_status(self, ant_task_id: str) -> "TaskStatusResponse":
<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
</div>

=== 8.3. Автомобіль ===

 "places": command.cargo.places,

new_status="PENDING_SEND",

! |- | weight | decimal | Ні | Вага. | Отримати доступ і тестовий ключ до старту. |}

retry_count: int = 3

5.3. Синхронізація автомобілів

Retry дозволений для:

|
| 1. Статус

)

20.1. Типи помилок

POST /api/v1/ant-logistics/routes/sync

29. Джерела

Водій / Кур'єр / Логіст

def get_routes(self, delivery_date: str) -> "RouteListResponse":

Критично критично: до початку розробки потрібно отримати реальну API-документацію ANT-Logistics v2 і перевірити методи створення / оновлення версій точок, машин, складів, завдань, маршрутів і статусів. # Чи потрібні push-сповіщення логісту або менеджеру? я хочу отримати з ANT-Logistics сформовані маршрути,

• реалізувати авторизацію;
• реалізувати check_connection;
• реалізувати create_or_update_point;
• реалізувати create_delivery_task;
• реалізувати cancel_delivery_task;
• реалізувати get_routes;
• реалізувати get_task_status;
• реалізувати обробку помилок. |-

Синхронізація статусів	Середній	style="background:#bbdefb;" | Блакитний
Заплановано	PLANNED	Заявку включено в маршрут.=== 13.8. Передача заявки в ANT-Logistics === 18.6. ant_events	Статуси виконання, фактичні інформаційні дані <pre> | | 6.== 17. Черга передачі == === 24.3. Маршрути === == 14. Приклад запиту на створення заявки == data={ == 1. Мета == ! |- | finish_warehouse_id | string | Кінцева точка. |- | Невідомі статуси ANT | API здатна повернути статус без мапінгу. |- | external_point_id | varchar | ID точки в K2 ERP. |- | Delivery Point | Торгова точка, клієнт ERP або адреса доставки. |- | sent_at | timestamp | Дата передачі. |- | phone | string | Ні | Телефон. | style="background:#eeeeee;" | Сірий |} ! |- | idempotency_key | string | Так | Ключ захисту від дублювання. Призначення 5. |- | Передача заявки | Час, endpoint, request ID, ANT task ID. Коментар def refresh_session(self) -> "AuthResult": == 25. MVP == task_name="send_delivery_order_to_ant", {| class="wikitable" ! Планування маршрутів, мобільний додаток водія, GPS ! |- | Product / Cargo | Товар або вантажні параметри. |- | status | varchar | Статус маршруту. |- | AC-3 | API key неправильний. | style="background:#ffcc80;" | Помаранчевий |- | Помилка передачі | SEND_ERROR | API повернув помилку. |- | delivered_at | timestamp | Дата доставки. |- | weight | numeric | Вага. |- | time_window_to | time | Ні | Кінець часового вікна. |- | amount | decimal | Ні | Сума замовлення. | Вони підсвічуються помаранчевим. | Зберегти raw-відповідь. |- | amount | numeric | Сума.== 10. Єдина логіка кольорів == === 12.3. Конфігурація клієнта === </pre> order = delivery_order_repository.create( pass "payment_type": command.payment.payment_type, "address": command.point.address, v ! |- | started_at | timestamp | Початок маршруту. # Чи потрібно підтримувати скасування заявки після планування? Тип order.raw_response = task_response.raw_payload * наявність external_order_id; * наявність idempotency_key; * дату доставки; * адресу доставки; * координати або можливість геокодування; * контактний телефон; * часові вікна; * вагу; * об'єм; * кількість місць; * суму післяплати, якщо виступає як; * складський облік відвантаження; * активність точки; * чи не була заявка вже передана; * чи дозволено змінювати заявку після планування; * чи немає скасування в K2 ERP. ! № sha256(external_order_id + delivery_date + point_id + address + amount) | | 5.</div> pass * служб доставки; * дистриб'юторів; * торгових компаній; * інтернет-магазинів; * виробничих компаній із власною доставкою; * логістичних підрозділів; * компаній із мобільними торговими представниками; * компаній, які використовують маршрутизацію водіїв або кур'єрів; * компаній, які ведуть замовлення в K2 ERP і планують маршрути в ANT-Logistics. |- | delivery_date + point_id + order_number | Бізнес-ключ доставки. |- | email | string | Ні | Email. | Заявка переходить у NEEDS_RETRY. |- | route_id | uuid | Маршрут.<syntaxhighlight lang="python"> pass {| class="wikitable" ! Колір {| class="wikitable" == 20. Обробка помилок == </div> db.commit() timeout_seconds: int = 30 === 18.5. ant_route_stops === '''Заборонено:''' зберігати API key, session ID або інші секрети у коді, Git-репозиторії, відкритих логах або frontend-змінних. |} {| class="wikitable" === 12.2. Основні методи === * акаунт ANT-Logistics; * доступ до API v2; * API key або інший ключ доступу; * механізм отримання ідентифікатора сесії, якщо він застосовується для API; * тестове середовище або тестовий акаунт; * список доступних API-методів; * структуру даних для торгових точок; * структуру даних для автомобілів; * структуру даних для складів; * структуру даних для завдань / заявок; * правила маршрутизації; * правила імпорту та експорту; * перелік статусів маршрутів і задач; * правила роботи з GPS; * правила авторизації; * ліміти API; * контакт технічної підтримки ANT-Logistics. Створюється delivery_order зі статусом DRAFT або PENDING_SEND. платформа повинна не допускати дублювання заявок. |- | DuplicateOrderError | Заявка вже передана. |- | TimeoutError | Перевищено час очікування. | Python-сервіс отримує маршрут і зберігає його в K2 ERP. pass * реалізувати чергу передачі; * реалізувати worker відправки; * реалізувати worker синхронізації статусів; * реалізувати worker синхронізації маршрутів; * реалізувати retry. |- | vehicle_id | string | Закріплений автомобіль. оновлення версій статусів ! |- | Дублювання заявок | Повторний запит здатна створити дубль доставки. Тип задачі </pre> ! |- | AC-9 | Маршрут має точки доставки. |- | address | string | Так | Адреса доставки. * Документація API v2 у кабінеті ANT-Logistics. SEO-опис <syntaxhighlight lang="python"> |- | API Layer | REST API для прийому заявок, точок, авто, водіїв. |} {| class="wikitable" <pre> ) {| class="wikitable" '''Технічний стек:''' Python 3.11+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, httpx, Pydantic, Celery/RQ/APScheduler, Redis, Docker. |- | ANT-Logistics / Мурашина логістика | Сервіс планування оптимальних маршрутів доставки. Поле <pre> <pre> K2 ERP / CRM / WMS / Website !== 26. Етапи реалізації == * створити FastAPI-проєкт; * налаштувати PostgreSQL; * створити моделі інтеграції, точок, заявок, маршрутів, подій; * налаштувати Alembic; * реалізувати healthcheck. Код '''критично:''' методи Python-клієнта виступає як внутрішньою абстракцією. |- | Driver | Водій або кур'єр. |- | address | text | Адреса. |- | Синхронізація маршрутів | Середній | Фоновий бізнес-процес. point_payload = ant_mapper.to_point_payload(order) * додати rate limiting; * додати моніторинг; * додати alerting; * додати dead letter queue; * додати резервне копіювання; * додати безпечне зберігання секретів. SEO-опис "service_time_minutes": 15, "status": "PENDING_SEND", status_response = ant_client.get_task_status(order.ant_task_id) try: return db.commit() == 9. Статуси доставки == == 7. User Story == === 7.5. Повернення статусів у K2 ERP === "weight": command.cargo.weight, "address": "м. |- | contact_name | string | Ні | Контактна особа. |} </div> # Яка реліз системи API застосовується для: v1 чи v2? # Чи потрібно отримувати фактичний GPS-трек? |- | longitude | decimal | Ні | Довгота. |- | ant_task_id | ID задачі в ANT-Logistics. |- | entity_type | varchar | integration, point, order, route, stop. SEO-опис K2 ERP передає в ANT-Logistics список клієнтів або торгових точок. SEO-опис <div style="border-left: 6px solid #2e7d32; background: #e8f5e9; padding: 12px 16px; margin: 16px 0;"> == 21. Dashboard логіста і керівника == event_type="DELIVERY_ORDER_CREATED", ! SEO-опис }, "idempotency_key": command.idempotency_key, </div> } |- | Заявок на сьогодні | 348 | style="background:#e3f2fd;" | інформаційні матеріали |- | Передано в ANT | 340 | style="background:#bbdefb;" | В роботі |- | Заплановано | 328 | style="background:#c8e6c9;" | Норма |- | Доставлено | 280 | style="background:#c8e6c9;" | Норма |- | Не доставлено | 12 | style="background:#ef9a9a;" | Критично |- | Частково доставлено | 6 | style="background:#ffcc80;" | Потрібна дія |- | Потребують повтору | 4 | style="background:#ffcc80;" | Потрібна дія |- | Без координат | 9 | style="background:#fff9c4;" | Увага |} ! | Не передавати заявку, показати список помилок. |- | volume | decimal | Ні | Об'єм. |} ! |- | delivery_date | date | Так | Дата доставки. Київ, вул. |- | latitude | decimal | Ні | Широта. Поле платформа повинна забезпечити: * перевіряє інформаційні дані замовлення; * визначає точку доставки; * формує заявку / задачу для ANT-Logistics; * передає адресу, координати, часове вікно, вагу, об'єм, суму, контакт; * зберігає ID задачі ANT-Logistics; * очікує включення задачі в маршрут. |- | sequence_number | integer | Порядок точки. |- | vehicle_type | string | Тип авто. |} {| class="wikitable" <pre> ! |- | Передача точки | інформаційні дані точки, ANT point ID. |- | Зміна заявки після планування | здатна зламати маршрут. Компонент "external_order_id": command.external_order_id, ! |- | session_id_encrypted | text | Зашифрований session ID, якщо застосовується для. |- | AddressError | Некоректна адреса або не визначені координати. API v2 ANT-Logistics Python Status Sync Worker order = delivery_order_repository.get_by_id(db, delivery_order_id) | | 4. |- | source | varchar | K2_ERP, PYTHON_SERVICE, ANT_LOGISTICS, USER. |- | base_url | varchar | URL API. |- | payload | jsonb | Технічні інформаційні дані. SEO-опис ! | Обмежити редагування після PLANNED. | Черга, retry, dashboard помилок. | здатна інтегруватись через ANT-Logistics або окремо. |- | id | uuid | ID точки маршруту. |- | comment | text | Ні | Коментар для логіста або водія. |- | Відсутність координат | Маршрутизація здатна бути неточною. Worker передає заявку / задачу. {| class="wikitable" entity_type="delivery_order", "payment_type": "cash_on_delivery" '''Управлінський результат:''' логіст і керівник повинні бачити, які заявки передано в ANT-Logistics, які маршрути сформовано, які замовлення доставлено, які не виконано, які водії мають відхилення, які точки проблемні та де потрібне втручання. |- | external_order_id | varchar | ID замовлення K2 ERP. | Статус у K2 ERP змінюється на DELIVERED. |- | longitude | numeric | Довгота. |- | AC-5 | Заявка проходить валідацію. |- | group | string | Ні | Група точок. | style="background:#e3f2fd;" | інформаційні матеріали |- | Передано в ANT | Заявки, які успішно передані. {| class="wikitable" ! | style="background:#fff9c4;" | Жовтий |- | Передається | SENDING | Виконується API-запит. | інтеграційні функції ERP зберігається в системі. 3. |- | GPS Sync Worker | Отримує фактичні треки, якщо доступно. HTML def authenticate(self) -> "AuthResult": return === 5.5. Отримання статусів доставки === ! |- | new_status | varchar | Новий статус. |} existing = delivery_order_repository.get_by_idempotency_key( {| class="wikitable" == 6. Основні сутності == <syntaxhighlight lang="python"> Retry заборонений для: __TOC__ event_type="DELIVERY_STATUS_SYNCED", === 21.2. Приклад dashboard === </pre> == 28. Відкриті питання == "time_window_to": "13:00" передачі заявок на доставку забезпечується через '''Головна ідея:''' розробити Python-сервіс. v K2 ERP або TMS передає перелік автомобілів. |- | style="background:#f3e5f5;" | Фіолетовий | #f3e5f5 | Спеціальний статус або ручна перевірка. db=db, * реалізувати створення заявки; * реалізувати мапінг K2 ERP → ANT; * реалізувати валідацію; * реалізувати hash заявки; * реалізувати дедублікацію. # Які саме методи API доступні у вашому тарифі? KPI if new_status == "DELIVERED": </div> v pass {| class="wikitable" Для надійності передача заявок повинна виконуватись через чергу. |- | fact_duration | integer | Фактична тривалість. | Внутрішня платформа замовника. |- | capacity_weight | decimal | Вантажопідйомність. SEO-опис db=db, * timeout; * HTTP 429; * HTTP 500; * HTTP 502; * HTTP 503; * HTTP 504; * тимчасової недоступності ANT-Logistics; * тимчасової помилки отримання статусу; * тимчасової помилки синхронізації маршрутів. SEO-опис <div style="border-left: 6px solid #6a1b9a; background: #f3e5f5; padding: 12px 16px; margin: 16px 0;"> |- | K2 ERP / CRM / WMS / інтернет-магазин | Джерело замовлень, клієнтів, товарів і складів.</pre> |- | AC-11 | Замовлення доставлено. SEO-опис base_url: str order.error_message = str(exc) |- | Заявок створено | Загальна кількість заявок за період. | Заборонити автоматичну зміну. | style="background:#ef9a9a;" | Критично |- | Частково доставлено | виступає як відхилення по кількості або сумі. | Статус підсвічується червоним. |- | created_at | timestamp | Дата створення. Пріоритет Як логіст, "external_point_id": "CLIENT-001", це Python-клас або пакет, який інкапсулює роботу з API ANT-Logistics виступає ключовою рисою ANT-Logistics Client. Сутність GET /api/v1/ant-logistics/dashboard?date_from=2026-05-01&date_to=2026-05-31 ! |- | Delivery Order | Замовлення на доставку з K2 ERP. |} === 19.1. Створення заявки === ! Обов'язковість '''Критично критично:''' інтеграційні функції ERP з логістичною системою не повинна втрачати заявки на доставку. * Сторінка API ANT-Logistics. Поле event_type="DELIVERY_ORDER_SENT_TO_ANT", ! task_response = ant_client.create_delivery_task(task_payload) pass ! |- | Python Integration Service | Інтеграційний шар між K2 ERP та ANT-Logistics. |- | Audit Logger | Зберігає всі запити, відповіді та помилки. Призначення |- | AC-8 | ANT-Logistics сформувала маршрут. Дата v 7. |- | Delivery Status | Статус доставки. |- | Status Sync Worker | Отримує статуси доставок. |- | is_active | boolean | Активність. |- | Отримання маршруту | ANT route ID, водій, автомобіль, точки. |- | email | string | Email.</pre> * офіційний сайт ANT-Logistics / Мурашина логістика.<pre> == 4. Передумови == |- | ValidationError | Некоректні інформаційні дані заявки. |- | Отримання статусу | Старий статус, новий статус, джерело. # Чи потрібно передавати автомобілі та водіїв?[[Категорія:ANT-Logistics]] def create_delivery_order(command: "CreateDeliveryOrderCommand", db: "Session") -> "DeliveryOrder": old_status = order.status POST /api/v1/ant-logistics/integrations/{integration_id}/check-connection До MVP не входить: ! | Таблиця status_mapping і статус UNKNOWN. |- | Неправильні адреси | Маршрути можуть будуватись некоректно. |} ! |- | RouteLockedError | Маршрут уже зафіксований. Де застосовується для if existing: {| class="wikitable"	}	Коментар "volume": 0.8,
id	uuid	Внутрішній ID точки. Критерій integration_mode: str = "api_v2"
Зелений	#c8e6c9	-	name	varchar	-	payment_type	varchar	-	group_name	varchar	Група. Замовлення except TemporaryAntError as exc: v 11.2. Основні компоненти Python-сервісу	№ номер автомобіля; вантажопідйомність; об'єм; тип кузова; доступність; водій; графік роботи; складський облік старту; складський облік завершення; група автомобілів. |-	Синхронізація довідників	Низький	-	AC-17	виступає як заявки без координат. POST /api/v1/ant-logistics/points/sync	} order.status = "SENDING" я хочу передати замовлення з K2 ERP у Мурашину логістику, ) Приклад hash:
external_driver_id	string	ID водія в K2 ERP. Компонент 20.2. Retry-логіка ANT_LOGISTICS_ACCOUNT_ID=account-001 17.1. Логіка черги { "places": 4 finally: audit_logger.log( return existing def create_or_update_driver(self, payload: "DriverPayload") -> "AntDriverResponse": ANT_LOGISTICS_INTEGRATION_MODE=api_v2 13. API Python-сервісу "amount": command.payment.amount, order.ant_status = status_response.status	-	Помилка передачі	Код, повідомлення, raw-відповідь. "delivery_date": "2026-05-08", повна технічна підтримка всіх методів ANT-Logistics; складна GPS-аналітика; власний компонент оптимізації маршрутів; заміна ANT-Logistics власним TMS; повна технічна підтримка всіх сценаріїв мобільної торгівлі; автоматичне геокодування без перевірки якості адрес; складний UI логіста, якщо dashboard API достатньо для першого етапу. Водій 8.4. Водій / кур'єр 7.4. Робота водія 8. Типи даних для передачі 16. Дедублікація </syntaxhighlight> 6. SEO-опис Критично критично: заявка, яка вже включена в маршрут або виконана водієм, не повинна автоматизовано змінюватись без окремого правила. K2 ERP створює замовлення на доставку. |-	name	string	Ручна обробка, нестандартні маршрути. |-	status	varchar	-	plate_number	string	Державний номер. Колір new_status = status_mapper.from_ant(status_response.status)
AC-4	K2 ERP створює заявку на доставку. Ключ "amount": 5700.00, 8. |-	ant_route_id	varchar	-	name	varchar	-	point_id	string	Так	-	latitude	decimal	Ні	-	idempotency_key	Зберігається ant_task_id. |-	idempotency_key	varchar	style="background:#ffcc80;" | Потрібна дія
Без координат	Точки, які потребують геокодування.=== 7.1. Передача заявки ===	-	places	integer	-	Скасування заявки	Високий	} 13.9. Скасування заявки	} pass	Помилки API, недоставка. | Робити GPS-синхронізацію опційною. №	-	AC-13	Замовлення частково доставлено. Статус
id	uuid	-	GPS-трекери	-	Жовтий	#fff9c4	-	AC-18	-	API недоступне	-	latitude	numeric	Широта. def check_connection(self) -> "ConnectionStatus": }, def create_or_update_point(self, payload: "DeliveryPointPayload") -> "AntPointResponse": застосовується для для: Етап 4. Заявки та валідація - Mapping Layer - planned_arrival_at timestamp - AC-14 - contact_name varchar Контактна особа. Тип pass "priority": 5 {| class="wikitable" ! Ризик ANT_LOGISTICS_RETRY_COUNT=3 POST /api/v1/ant-logistics/integrations - ant_status varchar Оригінальний статус ANT. Очікуваний результат Метою задачі виступає як створення Python-сервісу для інтеграції з сервісом Мурашина логістика / ANT-Logistics з метою автоматизації транспортної логістики.=== 12.1. Призначення === помилок валідації; неправильного API key; некоректної адреси; заявки, яка вже доставлена; заявки, яка скасована; маршруту, який уже зафіксований або виконується, якщо зміни заборонені. "latitude": 50.4501, old_status="SENDING", 11.1. Загальна схема 10. SEO-опис Додати геокодування та ручну перевірку. |- entity_id uuid Валідація координат і список проблемних точок. |- capacity_volume decimal style="background:#c8e6c9;" | Зелений Не доставлено NOT_DELIVERED Замовлення не доставлено. Поле <pre> ! ) "volume": command.cargo.volume, session_id: str | None = None {| class="wikitable" ! |- | time_window_to | time | Ні | Кінець часового вікна. | style="background:#ef9a9a;" | Червоний |- | Частково доставлено | PARTIALLY_DELIVERED | Доставлено не всі позиції або не вся кількість. |- | provider | varchar | ant_logistics. Worker передає точку доставки в ANT-Logistics. | В K2 ERP зберігається порядок точок. |- | service_time_minutes | integer | Ні | Час обслуговування точки. |- | status | varchar | Статус синхронізації. |- | Повторна передача | Хто запустив, причина, результат. № |- | id | uuid | ID маршруту. Поле def sync_delivery_order_status(delivery_order_id: str, db: "Session") -> None: order.status = "SENT_TO_ANT" === 13.3. Синхронізація торгової точки === db.commit() 2. | У K2 ERP відображається водій та автомобіль. |- | phone | string | Телефон. |- | longitude | decimal | Ні | Довгота. |- | fact_distance | numeric | Фактична відстань. |- | AC-16 | виступає як недоставлені заявки. |- | Vehicle | Автомобіль. "point": { |- | id | uuid | ID інтеграції. Status Sync Worker оновлює статуси. |} == 22. Безпека == <pre> == 3. Джерела інтеграції == <pre> ! | Зупинити інтеграцію, повідомити адміністратора. ! ! | style="background:#c8e6c9;" | Зелений |- | В маршруті | IN_ROUTE | Водій виконує маршрут. |- | name | string | Так | Назва клієнта або торгової точки. |- | style="background:#ef9a9a;" | Червоний | #ef9a9a | Помилка або невиконання.[[Категорія:Мурашина логістика]] === 7.2. Планування маршруту === pass [[Категорія:Python]] |- | external_point_id | string | Так | ID точки в K2 ERP. | style="background:#fff9c4;" | Увага |} ! |- | Валідація | Результат, список помилок. SEO-опис === 13.7. Створення заявки на доставку === def get_route_status(self, ant_route_id: str) -> "RouteStatusResponse": POST /api/v1/ant-logistics/delivery-orders Python ANT-Logistics Integration Service ANT_LOGISTICS_RETRY_BACKOFF_SECONDS=5 === 21.3. Проблемні доставки === ANT_LOGISTICS_TIMEOUT_SECONDS=30 == Див. 30. так само == 4. |- | api_key_encrypted | text | Зашифрований API key. # Як часто синхронізувати статуси? |- | route_id | uuid | Маршрут. |- | AC-7 | Повторний запит має той самий idempotency_key. |- | AC-12 | Замовлення не доставлено. |- | Dashboard API | інформаційні дані для логіста, керівника та диспетчера. Критерій я хочу бачити статуси виконання по маршрутах і точках, entity_type="delivery_order", === 18.1. ant_integrations === "weight": 120.5, order.delivered_at = status_response.fact_finished_at я хочу бачити свій маршрут у мобільному додатку ANT-Logistics, 19. Приклад Python-логіки передати задачі на дату; перевірити успішність імпорту; отримати список маршрутів; отримати порядок точок у маршруті; зберегти маршрут у K2 ERP; сформувати задачі водіям або логісту; показати маршрут у dashboard. |- CapacityError Черга, очікування маршруту. |- delivery_date date платформа показує AuthError і не передає заявки. |- start_warehouse_id string Початковий складський облік. order.error_message = str(exc) До MVP входить: external_order_id Архів, чернетки. SEO-опис 18.2. ant_delivery_points 13.10. Синхронізація маршруту Передати на ручну перевірку. |- Warehouse } pass 18.4. ant_routes pass class AntLogisticsClient: POST /api/v1/ant-logistics/drivers/sync - error_message text Помилка. № Ключі дедублікації: Після виконання маршруту Python-сервіс повинен отримати: Як логіст, постійних клієнтів; магазинів; точок доставки; геокодування адрес; прив'язки замовлень до існуючих точок; групування точок; планування регулярних маршрутів. |- time_window_from time Ні Початок часового вікна. K2 ERP / Dashboard / Документи / Замовлення pass return order Тип 19.2. Передача заявки в ANT-Logistics 18. Модель даних 24.4. Статуси Немає доступу до API v2 Перевести в NEEDS_CORRECTION. Колір - delivery_order_id uuid - SendError - event_type varchar Тип події. if old_status != new_status: реалізувати dashboard API; реалізувати список проблемних доставок; реалізувати фільтри; реалізувати експорт, якщо потрібно. Очікуваний результат - raw_request jsonb Запит. Критерій </syntaxhighlight> style="background:#c8e6c9;" | Норма Не доставлено Проблемні доставки. Дія системи ) 9. ! Значення "idempotency_key": "K2-ORDER-2026-000123-delivery-v1", 13.6. Синхронізація складу id uuid ID події.=== Етап 2. Базовий Python-сервіс === Python FastAPI K2 ERP ANT-Logistics Мурашина логістика TMS Маршрутизація Доставка Кур'єри GPS API інтеграція Логістика Внутрішній календар K2 ERP Dashboard логіста } </syntaxhighlight> 24.2. Заявки "raw_request": command.model_dump(), } Очікуваний результат entity_id=order.id, retry_backoff_seconds: int = 5 ) AC-1 style="background:#bbdefb;" | Блакитний Передано в ANT SENT_TO_ANT Заявка успішно передана. Тип if order.status in ["SENT_TO_ANT", "PLANNED", "DELIVERED"]: style="background:#bbdefb;" | Блакитний Доставлено DELIVERED Замовлення доставлено. Тип } 7.3. Контроль виконання критично: точні endpoint-и ANT-Logistics потрібно брати з офіційної API-документації, доступної в кабінеті або довідковому центрі. | Python-сервіс створює запис зі статусом PENDING_SEND. * Мобільний додаток Мурашина логістика для водіїв. |- volume numeric - AC-10 Маршрут призначений водію. Критерій 19.3. Синхронізація статусу }, щоб платформа врахувала їх під час планування маршрутів. |- priority integer Ні - AuthError - Мобільний додаток водія - AC-6 Заявка передана в ANT-Logistics. Очікуваний результат 13.1. Створення інтеграції 17.2. Пріоритети задач Перед передачею в ANT-Logistics платформа повинна перевірити: order.status = new_status K2 ERP формує список замовлень, які потрібно доставити, і передає їх у Python-сервіс. Поле 21.1. Основні KPI pass class AntLogisticsSettings(BaseSettings): external_vehicle_id string - planned_distance numeric платформа повертає успішний або помилковий статус. | style="background:#ffcc80;" | Частково доставлено Частина товару відсутня Перевірити залишки 08.05.2026 K2-ORDER-125 ТОВ «Бета» - Без координат Не знайдено адресу Геокодувати вручну === 13.11. Синхронізація статусів === * зберігання API key тільки у secret storage або в зашифрованому вигляді; * заборону логування API key та session ID; * HTTPS для всіх API-запитів; * перевірку SSL; * рольову модель доступу; * окремі права на відправку заявок; * окремі права на скасування заявок; * окремі права на повторну передачу; * журнал усіх дій; * захист від дублювання заявок; * маскування персональних даних клієнтів у логах; * контроль доступу до GPS-даних. |- | API Event | Подія інтеграції. |- | Route Sync Worker | Отримує маршрути та точки маршрутів. | Idempotency key і ant_task_id. "longitude": 30.5234, ! |- | driver_id | uuid | Водій. |- | Скасування | Хто скасував, причина. |- | ant_point_id | varchar | ID точки в ANT-Logistics. |- | fact_departure_at | timestamp | Фактичний виїзд. | застосовується для на стороні ANT-Logistics. Тип ! |- | Dashboard K2 ERP | Контроль передачі, маршрутів, статусів і помилок. |- | account_id | varchar | ID акаунта. Тип щоб бачити порядок доставки, водіїв, автомобілі та плановий час прибуття. | style="background:#ef9a9a;" | Не доставлено | клієнт ERP відсутній | Перенести доставку |- | 08.05.2026 | K2-ORDER-124 | ФОП Петренко | Сидоренко А.В. |- | old_status | varchar | Попередній статус. | style="background:#ef9a9a;" | Червоний |- | Скасовано | CANCELLED | Заявку скасовано. Мурашина логістика / ANT-Logistics new_status="SENT_TO_ANT", "delivery_date": command.delivery_date, ! 1. SEO-опис ! | Він бачить заявки, маршрути, статуси, проблеми та помилки. | Друга заявка не створюється. | Вони підсвічуються червоним. Як зменшити [[Категорія:API]] === 5.2. Синхронізація торгових точок === |- | Створення заявки | Замовлення, клієнт ERP, дата доставки, сума. |- | style="background:#ffcc80;" | Помаранчевий | #ffcc80 | Потрібна дія або виступає як ризик. |- | style="background:#bbdefb;" | Блакитний | #bbdefb | операційна дія в роботі. |- | updated_at | timestamp | Дата оновлення версій. |- | address | string | Так | Адреса доставки. Тип {| class="wikitable" == 27. Ризики == == 2. Область сценарії використання == v def send_delivery_order_to_ant(delivery_order_id: str, db: "Session") -> None: POST /api/v1/ant-logistics/vehicles/sync {| class="wikitable" payload={"delivery_order_id": str(order.id)}, account_id: str | None = None === Етап 5. Черга та статуси === {| class="wikitable" if not order.ant_task_id: ANT-Logistics виконує розрахунок оптимальних маршрутів. У цьому ТЗ endpoint-и Python-сервісу виступає як внутрішніми, а зовнішні методи ANT-Logistics повинні бути уточнені під API v2. Критерій "contact_name": "Іван Петренко", payload={"ant_task_id": task_response.task_id}, ! |} from pydantic_settings import BaseSettings {{SEO |title=Технічне завдання: Інтеграція з Мурашина логістика / ANT-Logistics для Python |description=Технічне завдання на реалізацію Python-сервісу для інтеграції K2 ERP, CRM або інтернет-магазину з ANT-Logistics / Мурашина логістика: заявки на доставку, торгові точки, маршрути, машини, водії, статуси, GPS, імпорт, експорт, API v2, dashboard та журналювання. |keywords=Python, ANT-Logistics, Мурашина логістика, API, логістика, маршрутизація, доставка, K2 ERP, TMS, FastAPI, GPS, водії, кур'єри, технічне завдання }} Для реалізації задачі необхідно отримати: </syntaxhighlight> POST /api/v1/ant-logistics/delivery-orders/{order_id}/send payload={"external_order_id": command.external_order_id}, |- | Чернетка | DRAFT | Заявка розроблена в K2 ERP, але ще не передана. |- | integration_mode | varchar | api_v2. | Вона додається в чергу передачі. |- | is_active | boolean | Чи активний автомобіль. |- | status | varchar | Статус точки. Тип я хочу бачити в K2 ERP, що замовлення доставлено або не доставлено, def get_route(self, ant_route_id: str) -> "RouteResponse": Як менеджер, def create_or_update_warehouse(self, payload: "WarehousePayload") -> "AntWarehouseResponse": <syntaxhighlight lang="python"> Як керівник доставки, Як водій, ! | Повернути існуючу заявку. | style="background:#c8e6c9;" | Норма |- | Доставлено | Успішно виконані доставки. |} db.commit() ! |- | Delivery Queue | Черга передачі заявок. | Вони підсвічуються жовтим. |- | ant_task_id | varchar | ID задачі в ANT-Logistics. |- | Data Validator | Перевіряє адреси, координати, дати, вагу, об'єм, часові вікна. |- | GPS Track | Фактичний рух автомобіля. Обов'язковість === 24.1. інтеграційні функції ERP === [[Категорія:K2 ERP]] === 5.4. Планування маршрутів === order.status = "NEEDS_RETRY" {| class="wikitable" ! Показник POST /api/v1/ant-logistics/statuses/sync |- | AC-15 | Логіст відкриває dashboard. Дія except Exception as exc: def cancel_delivery_task(self, ant_task_id: str, reason: str) -> "CancelTaskResponse": ! # Чи потрібно передавати товари або тільки вагу/об'єм? {| class="wikitable" щоб коректно закривати документи, оплату та взаєморозрахунки. |- | AC-2 | Адміністратор перевіряє підключення. |- | GPS-дані неповні | Неможливо оцінити фактичний маршрут. Очікуваний результат |- | 08.05.2026 | K2-ORDER-123 | ТОВ «Альфа» | Іваненко О.М. Поле "phone": "+380501112233", * отримати API v2-документацію; створити API key; перевірити авторизацію; перевірити тестові запити; визначити методи для точок; визначити методи для заявок; визначити методи для маршрутів; визначити методи для статусів; визначити ліміти API. |- address text Адреса. Стан }, Перевести в NEEDS_RETRY. |- created_at timestamp - time_window_from time Ні Реалізується в межах цього ТЗ. |- point_id uuid Dashboard, список доставок, маршрут. # Чи потрібно передавати часові вікна клієнтів? | style="background:#bbdefb;" | В роботі Заплановано Заявки включено в маршрути. * Довідковий центр API v2 ANT-Logistics. SEO-опис Приклад `.env`: - GeoCodingError - оновлення версій адреси / часу Високий - delivery_date date Дата маршруту. Поле Передача, маршрут, виконання. POST /api/v1/ant-logistics/warehouses/sync "time_window_from": "09:00", Передача заявки на доставку Високий - raw_response jsonb Відповідь. Валідація, мапінг, дедублікація, черга 24. Acceptance Criteria </syntaxhighlight> - phone varchar Телефон. Причина pass Python-сервіс: ANT-Logistics Client статус маршруту; статус кожної точки; фактичний час прибуття; фактичний час від'їзду; причину недоставки; коментар водія; фото / вкладення, якщо доступні; GPS-факт, якщо доступний; суму післяплати, якщо застосовується для. |- work_time_from time Показати логісту. | Retry, часткова доставка, відхилення. |- payment_type enum Ні style="background:#ef9a9a;" | Червоний Потребує повтору NEEDS_RETRY - driver_id string Закріплений водій. SEO-опис point_response = ant_client.create_or_update_point(point_payload) 11. технічна архітектура рішення для бізнесу delivery_validator.validate(command) delivery_queue.enqueue( def create_or_update_vehicle(self, payload: "VehiclePayload") -> "AntVehicleResponse": - name string ПІБ. Поле def update_delivery_task(self, ant_task_id: str, payload: "DeliveryTaskPayload") -> "AntTaskResponse": Етап 3. ANT-Logistics Client * передачу торгових точок / клієнтів; * передачу заявок на доставку; * передачу складів / сервісних точок; * передачу автомобілів; * передачу водіїв або співробітників; * передачу товарів або вантажних параметрів; * запуск або підготовку планування маршрутів; * отримання маршрутів; * отримання статусів маршрутів; * отримання статусів виконання точок доставки; * отримання фактичних даних виконання; * обмін із GPS-трекерами, якщо застосовується для; * синхронізацію результатів назад у K2 ERP; * журналювання всіх запитів; * контроль помилок; * dashboard для логіста і керівника. Кожне замовлення, точка доставки, маршрут, зміна статусу, помилка API та повторна передача повинні мати внутрішній ID, журнал подій і захист від дублювання. |} "name": "ТОВ «Альфа»", api_key: str "comment": "Зателефонувати за 30 хвилин до прибуття", Реальні API-методи ANT-Logistics потрібно взяти з офіційної API v2-документації. Поле Тип <syntaxhighlight lang="python"> щоб виконувати доставку в правильному порядку. ANT-Logistics повертає ID задачі.