Інтеграція з Prom, Rozetka, Hotline
async def check_connection(self) -> dict:
db.commit()
marketplace=marketplace,
! |-
| customer_email
| string
| Email. | API-токени керуються в кабінеті компанії. |-
| Status Export Worker
| Передача статусів і ТТН. "channels": ["PROM", "ROZETKA", "HOTLINE"]
<syntaxhighlight lang="python">
pass
=== 14.10. Публікація фіду Hotline ===
2. | Він бачить товари, замовлення, фіди, помилки по Prom/Rozetka/Hotline.=== 27.3. Ціни та залишки ===
Як комерційний менеджер,
[[Категорія:Hotline]]
pass
=== 12.1. Загальна схема ===
pass
{| class="wikitable"
! |-
| оновлення версій залишків
| Критичний
| Захищає від продажу відсутнього товару. |-
| marketplace
| varchar
| PROM або ROZETKA. |-
| Bid
| Ставка Hotline по товарній пропозиції. Якщо замовлення нове — створює його в K2 ERP. # Чи потрібна повна синхронізація товарів у Prom через API? ! | Передати менеджеру каталогу. |-
| Помилки категорій
| Товари не проходять модерацію. Якщо все коректно — статус IMPORTED. * реалізувати XML/YML generator;
* реалізувати валідацію XML;
* реалізувати публікацію файлу;
* реалізувати журнал генерацій;
* реалізувати фід акцій, якщо потрібно. |-
| оновлення версій цін
| Високий
| Впливає на маржу. |}
external_order_id=external_order_id,
mp_product = marketplace_product_repository.get_or_create(
1. |-
| images
| array
| Фото. Коментар
event_type="PRODUCT_SYNCED",
payload=order_payload,
<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">
== 17. Валідація товарів ==
error=str(exc),
{| class="wikitable"
=== 8.3. Замовлення з маркетплейса ===
! |-
| external_order_id
| varchar
| ID замовлення в каналі. |-
| AC-11
| Залишок став 0.=== 24.1. Основні KPI ===
=== 18.2. Дедублікація замовлень ===
Retry заборонений для:
<id>K2-PRODUCT-000123</id>
|-
| Marketplace Integration
| конфігурація інтеграції з Prom, Rozetka або Hotline. |-
| Hotline
| XML/YML/CSV/XLS/TXT фіди + API ставок
| Передача товарів через фід, контроль акцій, керування ставками. @abstractmethod
* додати rate limiting;
* додати retry policy;
* додати dead letter queue;
* додати alerting;
* додати моніторинг;
* додати резервне копіювання;
* додати безпечне зберігання secret-ів. |-
| Помилки характеристик
| Rozetka часто потребує точних характеристик категорій. Очікуваний результат
"marketplace": marketplace,
|-
| integration_name
| string
| Так
| Назва інтеграції. | style="background:#ffcc80;" | Помаранчевий
|-
| Підтверджено
| CONFIRMED
| Замовлення прийнято в роботу. |-
| order_number
| string
| Номер замовлення. Канал
"name": "Смартфон Example X 128GB",
|-
| sku
| базовий артикул. |-
| old_status
| varchar
| Старий статус. SEO-опис
response = await client.sync_product(payload)
"status": "IMPORTED",
async def import_orders(self, filters: dict) -> list [dict]:
|-
| AC-5
| Товар має всі обов'язкові поля. )
* централізовану картку інтеграції по кожному каналу;
* синхронізацію товарів;
* синхронізацію цін;
* синхронізацію залишків;
* отримання замовлень;
* оновлення версій статусів замовлень;
* передачу номерів ТТН / ЕН;
* генерацію товарних фідів;
* валідацію товарів перед передачею;
* контроль помилок API;
* контроль помилок фідів;
* журнал усіх запитів і відповідей;
* dashboard по маркетплейсах;
* захист від дублювання товарів і замовлень. |}
Як менеджер товарного каталогу,
POST /api/v1/marketplaces/hotline/feed/generate
POST /api/v1/marketplaces/products/sync-batch
product_id=product.id,
Prom і Rozetka можуть бути джерелами замовлень. |-
| k2_order_id
| uuid
| ID замовлення K2 ERP. №
! |-
| price
| numeric
| Базова ціна. Статус
=== 14.9. Генерація фіду Hotline ===
Python-сервіс повинен:
=== 24.3. Проблемні товари ===
До MVP не входить:
! v
Marketplace Adapters
async def update_stock(self, external_product_id: str, stock: dict) -> dict:
v
{
! |-
| Помилка API
| Код, текст, raw-відповідь. |-
| Генерація фідів
| Середній
| Hotline / Rozetka feed. |-
| total_amount
| numeric
| Сума замовлення. Тип
"customer_phone": order_payload.get("customer_phone"),
[[Категорія:Python]]
mp_product.external_product_id = response.get("external_product_id")
)
db=db,
"description": "SEO-опис товару без HTML-помилок та заборонених символів.",
self.token = token
</category>
=== 27.5. Hotline ===
"marketplace": channel,
! |-
| raw_response
| jsonb
| Відповідь API. | Вони підсвічуються помаранчевим. |-
| customer_name
| string
| ПІБ покупця. |-
| sync_products_enabled
| boolean
| Так
| Чи синхронізувати товари. Заборонено зберігати API token, логіни, паролі або auth token у коді, Git, frontend-змінних або відкритих логах. | Він переходить у NEEDS_CORRECTION. Ключ
інтеграційні функції ERP призначена для:
K2 ERP / Dashboard / Менеджери
4. Python-сервіс отримує подію. |-
| name
| varchar
| Назва. Поле
=== 12.2. Основні компоненти Python-сервісу ===
! Тип
<priceRUAH>12999</priceRUAH>
! Тип
pass
=== 13.4. Hotline Client ===
! Валідація, мапінг, черги, дедублікація
<name>Смартфони</name>
K2 ERP передає залишки по складах. |-
| marketplace
| varchar
| PROM, ROZETKA, HOTLINE. | Ставка передається через API ставок і логуються. |}
[[Категорія:Маркетплейси]]
async def update_stock(self, external_product_id: str, stock: dict) -> dict:
'''Критично критично:''' інтеграційні функції ERP не повинна створювати дублікати товарів, замовлень або фідів. |-
| sync_orders_enabled
| boolean
| Так
| Чи імпортувати замовлення. Очікуваний результат
{| class="wikitable"
! # Чи потрібні окремі склади для залишків по каналах? |-
| Зміна ціни
| Стара ціна, нова ціна, канал. Що зберігати
"external_order_id": external_order_id,
product = product_repository.get_by_id(db, product_id)
! | style="background:#bbdefb;" | Блакитний
|-
| Синхронізується
| SYNCING
| Виконується API-запит або генерація фіду. ! | style="background:#ef9a9a;" | Критично
|-
| Нові замовлення
| Отримані з Prom/Rozetka. K2 ERP змінює товар. Production-фід потрібно формувати за актуальною специфікацією Hotline XML або YML. |-
| Синхронізація товарів
| Середній
| Каталог. # Чи потрібно оновлювати статуси замовлень у маркетплейсах? |-
| оновлення версій статусу
| Старий статус, новий статус, канал. Python-сервіс повинен:
return
</item>
POST /api/v1/marketplaces/products/{product_id}/sync
я хочу, щоб залишки з K2 ERP автоматизовано оновлювались на маркетплейсах,
</pre>
if existing:
== 29. Етапи реалізації ==
щоб контролювати якість інтеграції. product_status_service.set_status(
{| class="wikitable"
async def sync_product(self, product: dict) -> dict:
* отримувати статус із K2 ERP;
* мапити статус у статус маркетплейса;
* передавати статус у Prom / Rozetka;
* передавати номер ТТН / ЕН;
* зберігати історію статусів;
* логувати помилки оновлення версій. # Як часто оновлювати залишки? |-
| external_order_id
| ID замовлення в маркетплейсі. pass
<items>
validation_result = product_validator.validate(product)
</price>
До MVP входить:
<pre>
[[Категорія:Інтеграції]]
"price": 12999.00, async def update_stock(self, external_product_id: str, stock: dict) -> dict:
! Стан
[[Категорія:API]]
=== 14.7. Імпорт замовлень ===
self.username = username
db.commit()
! | style="background:#c8e6c9;" | Норма
|-
| Фіди сформовані
| XML/YML-фіди згенеровані. |-
| payment_type
| string
| Оплата. Колір
pass
! Задача
* реалізувати price engine;
* реалізувати stock engine;
* реалізувати чергу оновлення версій;
* реалізувати історію змін. | Заблокувати синхронізацію ціни. |-
| status
| varchar
| Статус генерації. |-
| warranty
| string
| Гарантія. |-
| status
| string
| Статус. |-
| feed_public_url
| varchar
| URL фіду. |-
| style="background:#f3e5f5;" | Фіолетовий
| #f3e5f5
| Спеціальний або ручний сценарій. Дія системи
except Exception as exc:
pass
external_order_id = order_payload ["external_order_id"]
<firmName>Example Store</firmName>
=== 14.2. Перевірка підключення ===
[[Категорія:Rozetka]]
"category_id": "phones",
db=db,
Як складський облік,
payload={
data={
{| class="wikitable"
"attributes": {
! SEO-опис
! |-
| status
| varchar
| Статус K2 ERP. |-
| order_date
| datetime
| Дата замовлення. |}
Окремо варто відзначити який інтегрує K2 ERP / CRM / інтернет-магазин із маркетплейсами і прайс-агрегаторами '''Prom.=== Етап 7. Фіди Hotline / Rozetka ===
pass
|-
| AC-16
| платформа генерує Hotline XML. # Які категорії товарів потрібно підтримати в MVP? Канал
== 28. MVP ==
"warranty": "12 місяців"
|-
| Синхронізація товару
| SKU, канал, статус, відповідь. |-
| entity_id
| uuid
| ID сутності. |-
| sync_prices_enabled
| boolean
| Так
| Чи синхронізувати ціни. | Зберегти raw-відповідь. |-
| errors_count
| integer
| Кількість помилок. :contentReference [oaicite:1]{index=1}
! |-
| UnknownStatusError
| Канал повернув невідомий статус. | style="background:#ef9a9a;" | Червоний
|-
| Приховано
| HIDDEN
| Товар приховано через залишок, правило або вручну. Поле
K2 ERP виступає як джерелом операційних статусів. №
errors=validation_result.errors,
<categories>
external_order_id=external_order_id,
<syntaxhighlight lang="python">
я хочу отримувати замовлення з Prom і Rozetka в K2 ERP,
@abstractmethod
async def import_orders(self, filters: dict) -> list [dict]:
entity_id=mp_product.id,
1. class RozetkaClient(MarketplaceClient):
<firmId>12345</firmId>
* отримати Prom API token;
* отримати Rozetka API credentials;
* отримати Hotline feed specs;
* отримати Hotline bid API token, якщо потрібно;
* перевірити тестові запити;
* визначити список категорій;
* визначити правила мапінгу. # Який формат фіду Rozetka потрібен? |-
| external_product_id
| varchar
| ID товару в каналі. | style="background:#c8e6c9;" | Зелений
|-
| Скасовано
| CANCELLED
| Замовлення скасовано. Призначення
audit_logger.log(
! Ключ
=== 14.12. Dashboard ===
=== 14.4. Масова синхронізація товарів ===
* визначити активні канали для товару;
* застосувати правила націнки;
* застосувати промо-ціну, якщо виступає як;
* застосувати мінімальну ціну;
* сформувати зміну ціни;
* передати зміну в Prom;
* передати зміну в Rozetka;
* оновити XML/YML-фід Hotline;
* зберегти історію зміни ціни. ! Код
5. №
щоб вона автоматизовано оновилась у всіх підключених каналах. Де застосовується для
mp_product.status = "SYNCED"
=== 7.3. Залишки ===
<item>
|-
| marketplace
| Джерело замовлення. |-
| tracking_number
| varchar
| ТТН / ЕН. | платформа передає новий залишок.=== 7.6. Dashboard керівника ===
* реалізувати product mapper;
* реалізувати category mapper;
* реалізувати attribute mapper;
* реалізувати валідацію;
* реалізувати sync workers. |-
| raw_payload
| jsonb
| інформаційні дані замовлення. |-
| Продаж відсутнього товару
| Залишки не оновились вчасно. |-
| sync_orders_enabled
| boolean
| Імпорт замовлень. |-
| style="background:#c8e6c9;" | Зелений
| #c8e6c9
| Успішно: синхронізовано, опубліковано, імпортовано, виконано. # Чи потрібно передавати ТТН Нової пошти / Укрпошти? |-
| AC-3
| Адміністратор створює інтеграцію Hotline. # Чи потрібна технічна підтримка декількох магазинів Prom? |-
| external_order_id
| string
| ID замовлення в маркетплейсі. Товари, ціни, залишки, статуси
pass
"prom": "prom-category-ref",
|
| 2. Для реалізації задачі необхідно отримати:
"marketplace_categories": {
class HotlineClient:
payload = marketplace_mapper.to_payload(product, marketplace)
def __init__(self, feed_storage_url: str, bid_api_token: str | None = None):
=== Етап 1. Аналіз API та вимог ===
!
2. Область сценарії використання
21.3. Імпорт замовлень
21.2. Worker передачі товару
async def generate_product_feed(self, products: list [dict], format: str = "xml") -> bytes:
платформа повинна логувати:
pass
я хочу один раз вести товар у K2 ERP,
5. Основні бізнес-сценарії
finally:
я хочу змінити ціну в K2 ERP,
"stock_quantity": 12,
"old_price": 13999.00,
| Червоний | #ef9a9a | - | items | array | Товари замовлення. SEO-опис | }
POST /api/v1/marketplaces/hotline/bids/update </syntaxhighlight>24.2. Приклад dashboard)
|
XML validation перед публікацією. :contentReference [oaicite:3]{index=3} | style="background:#c8e6c9;" | Зелений | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Потребує перевірки | NEEDS_REVIEW | }
3. |- |
Hotline Bid Client | style="background:#c8e6c9;" | Норма | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| На модерації | платформа передає нову ціну в канали. ! |- | customer_phone | varchar | - | sync_stocks_enabled | boolean | Так | style="background:#eeeeee;" | Сірий | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Помилка | ERROR | Помилка імпорту або оновлення версій. SEO-опис | }
sync_queue.enqueue(
|
idempotency_key | Ключ повторної обробки.<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;"> ! Якщо товар не знайдено — статус NEEDS_REVIEW. |- | AC-4 | Token неправильний. | Версіонування клієнтів і contract-тести. |- | style="background:#bbdefb;" | Блакитний | #bbdefb | операційна дія виконується або інформаційні дані в процесі передачі. |- | payload | jsonb | Технічні інформаційні дані. платформа повинна не допускати дублювання товарів і замовлень.<description>SEO-опис товару</description> 5.2. Синхронізація цін
</syntaxhighlight> | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| AuthError | - | sync_prices_enabled | boolean | class="wikitable"
pass }, |
- | delivery_service | string | - | external_product_id | string | ID товару в маркетплейсі. Колір
|
