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

 

=== 24.1.; інтеграційні функціональні можливості ===

!; |-
| AC-9
| Маршрут має точки доставки.; | style="background:#ffcc80;" | Потрібна дія
|-
| Без координат
| Точки, які потребують геокодування.; Сутність

=== 11.2.; Основні компоненти Python-сервісу ===
[[Категорія:Маршрутизація]]

18.1. ant_integrations

K2 ERP передає в ANT-Logistics список клієнтів або торгових точок.; |- | ant_point_id | varchar | ID точки в ANT-Logistics.; |- | amount | decimal | Ні | Сума замовлення.; | Внутрішній контроль для логіста та керівника.; |- | ANT-Logistics / Мурашина логістика | Сервіс планування оптимальних маршрутів доставки.; |}

"comment": "Зателефонувати за 30 хвилин до прибуття",

audit_logger.log(

</syntaxhighlight> !; |}

!; |- | idempotency_key | Унікальний ключ конкретної версії передачі.; |- | AC-16 | є собою недоставлені заявки.; |- | TimeoutError | Перевищено час очікування.; |- | ANT-Logistics Client | Python-клієнт для API ANT-Logistics.; | Черга, очікування маршруту.; | Не передавати заявку, показати список помилок.; |- | amount | numeric | Сума.; Київ, вул.; |- | Delivery Queue | Черга передачі заявок.; |- | latitude | decimal | Ні | Широта.; |- | Синхронізація довідників | Низький | Точки, авто, водії, товари.; | Передача, маршрут, виконання.; |}

except Exception as exc: entity_id=order.id,

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