Довідник сутностей обміну

Цей документ описує що саме облікова система може надіслати в ApexSFA і як портал це застосовує: для кожного entity_type — призначення, ключ ідемпотентності, поля payload, семантика delete, залежності, ліміти й формати.

Транспорт (підпис X-Signature, X-Tenant-Id, ліміти, загальні коди відповіді) описано в розділі 3; тут — лише те, що потрібно для побудови конвертів.

Зміст

• 1. Конверт і ендпоінти
• 2. Загальні правила
• 3. Рекомендований порядок першого завантаження
• 4. Зведена таблиця entity_type
• 5. Оргструктура й постачання
• 6. Каталог і ціни
• 7. Контрагенти, точки, привʼязки
• 8. Люди й транспорт
• 9. Обладнання
• 10. Залишки, WMS, акциз
• 11. Продажі й документи руху товару
• 12. Борги
• 13. Каса
• 14. Стан заявок порталу в обліку
• 15. Рейси (ходки)
• 16. Модуль логістики
• 17. Приклади конвертів

1. Конверт і ендпоінти

Конверт

Примітка. Рекомендуємо GUID обʼєкта (36 символів). Ідентифікатори довші за 50 символів не використовуйте.

Відповідь

• Одиночний конверт, успіх — 200:

{"data": {"accepted": true, "entity_id": "3f2a9c1e-7b4d-4e0a-9f51-2c8d6a1b0e47", "operation_performed": "upsert", "details": {"upserted": 412, "depleted": 3}}}

details — лічильники обробника (є не в усіх сутностей; напр. {"skipped": "manual_override"}).

• Одиночний конверт, бізнес-помилка (запис не знайдено, порушене правило) — 422:

{"error": {"accepted": false, "error": "Product with code_1c=… not found — create it first"}}

• Батч — 200 з результатом по кожному рядку:

{"data": {"accepted_count": 2, "failed_count": 1, "results": [
  {"index": 0, "entity_type": "product", "external_id": "…", "accepted": true, "entity_id": "…", "operation_performed": "upsert", "error": null, "details": null},
  {"index": 1, "entity_type": "price_list_item", "external_id": "…", "accepted": false, "entity_id": null, "operation_performed": null, "error": "Product with code_1c=… not found — create it first", "details": null}
]}}

• partial: true (за замовчуванням) — кожен конверт у власній точці збереження; помилка одного не скасовує інших. Будь-яка помилка рядка стає accepted: false з текстом, а не помилкою всього пакета.
• partial: false — увесь батч атомарно: на першій бізнес-помилці все відкочується, відповідь 422 {"error": {"code": "BATCH_ATOMIC_FAILURE", "message": "…", "accepted_so_far": N, "failed_at_index": N}}. У цьому режимі details по рядках не повертаються.
• Порожній items → 200 з нулями (легальний «порожній хвіст» вигрузки).
• Понад 5000 конвертів → 422 VALIDATION_ERROR з текстом batch too large.

Порада. Завжди надсилайте дані через /inbound/batch з partial: true — так кожен рядок отримує власний результат і текст помилки.

Постобробка лише батчу. Після батчу, у якому був хоча б один agent, портал підвʼязує документи обліку (goods_document, cash_document, борги), що прийшли раніше за торгового. Після батчу з counterparty — долінковує ієрархію контрагентів (дитина, що прийшла раніше за папку-батька). В одиночному ендпоінті цього не відбувається.

2. Загальні правила

Ідемпотентність. Повтор того самого конверта безпечний: майже всі сутності — upsert за природним ключем (зазвичай external_id). Окремого ключа запиту (request id) немає. Винятки, де повтор має побічний ефект, позначено в описі сутності (напр. debt_reset видаляє всі борги, trip перебудовує склад рейсу).

Частковий payload. Для більшості довідників поле оновлюється, лише якщо ключ присутній у payload. Відсутній ключ = «не чіпати». Явне null / "" = «очистити» (якщо поле не обовʼязкове).

Ручні правки на порталі. Записи, які редагували на порталі, обмін оновлює лише частково — зазвичай тільки is_active. Відповідь тоді містить details: {"skipped": "manual_override"}. Так поводяться product, manufacturer, counterparty, client_assignment; у agent/driver — поля ПІБ і телефону, виправлені в картці.

Філія. Тенант = одна точка синхронізації з одним рядком філії. Усі склади, торгові, водії, точки й рейси з обміну лягають у філію тенанта, від імені якого прийшов запит. Коди філії в payload (branch_code, branch_external_id, branch_code_1c, filial_code) приймаються, але не читаються.

Рядки. Пробіли по краях обрізаються, невидимі символи нульової ширини видаляються (у довідниках оргструктури, контрагентів, людей, транспорту, обладнання). Більшість текстових полів довідників обрізаються до розміру колонки без помилки. У client і product текстові поля пишуться як є — задовге значення дасть помилку рядка (у partial-батчі — accepted: false).

Числа.

Рекомендація: гроші й кількості передавати рядком з крапкою ("1234.50") — так не губиться точність.

Дати й час.

Закритий місяць. Для goods_document і goods_period документи з датою в закритому періоді не змінюються. Місяць M закривається з дня sales_close_day (за замовчуванням 10, допустимо 1–28) місяця M+1 за київським часом; адміністратор може відкрити період у налаштуваннях. Для каси (cash_*) такого захисту немає.

3. Рекомендований порядок першого завантаження

Порядок випливає з того, як обробники шукають посилання: «жорстке» посилання (немає — помилка) вимагає, щоб залежність прийшла раніше; «мʼяке» (немає — запис приймається без звʼязку) лише відкладає звʼязок до наступного обміну.

1. branch
2. warehouse, logistics_warehouse
3. supplier → supplier_point
4. price_type
5. manufacturer
6. product_category (батьки раніше за дітей) → product
7. agent, driver
8. vehicle → transport_list
9. counterparty (папки раніше за елементи — бажано) → client
10. client_assignment, manufacturer_price_type, manufacturer_payment_term
11. equipment_type → equipment_unit
12. price_list_item, product_external_code
13. Модуль логістики: logistics_manufacturer / logistics_own_manufacturer,
    logistics_counterparty → logistics_point,
    logistics_product_category → logistics_product → logistics_product_code
14. Залишки: product_stock, wms_stock, product_stock_snapshot, logistics_stock,
    stock_document, excise_marks
15. Документи: sale, logistics_order, debt_reset → debt_document,
    goods_document → goods_period, trip, cash_document + cash_balance → cash_period,
    order_state → order_state_period

4. Зведена таблиця entity_type

«Не підтримується» = delete повертає 422.

5. Оргструктура й постачання

branch

Філія — це сама точка синхронізації. Обмін записує в її єдиний рядок GUID і адресу; другого рядка філії не створює.

• Ключ. Береться єдиний рядок філії тенанта. Якщо в нього ще немає GUID — external_id записується в нього (якщо цей GUID не стоїть на іншому рядку). Якщо рядка немає взагалі — створюється (тоді name обовʼязкове).
• Інший GUID (друга філія довідника обліку) → 200, details.skipped = "other branch of the same point", нічого не змінюється.
• Повтор — ідемпотентний.

delete: 200, details.skipped = "point branch is not deactivated" — філія не вимикається. Якщо рядка філії немає — 422.

При першій привʼязці GUID етапи заявки виставляються так, що етап «перевірка» на порталі вимкнено (цикл заявки веде облікова система).

warehouse

Склад торгового контуру.

• Ключ: external_id. Склад завжди належить філії тенанта.
• Новий склад веде залишки з облікової системи (product_stock).

delete: is_active=false; немає складу — 422.

supplier

Постачальник. Ключ: external_id.

delete: is_active=false; немає — 422.

supplier_point

Точка постачання (адреса відвантаження) постачальника. Ключ: external_id.

delete: is_active=false; немає — 422.

price_type

Тип ціни. Його code збігається з кодом прайсу (price_list_code) у price_list_item і client — з нього береться назва автоматично створеного прайсу.

Ключ: external_id.

delete: is_active=false; немає — 422.

6. Каталог і ціни

manufacturer

Виробник (бренд-власник), у розрізі якого працюють торгові команди, продажі, борги.

• Ключ: external_id. Цей самий код передається в інших сутностях як manufacturer_external_id.
• Запис із ручними правками на порталі: оновлюється лише is_active, details.skipped = "manual_override".

delete: is_active=false; немає — 422.

product_category

Категорія товарів, дерево.

• Ключ: external_id.

delete: мʼяке видалення; немає — 422.

product

Товар основного каталогу (КПК, B2B, звіти).

• Ключ: external_id.
• Повтор: upsert, поля з payload перезаписуються.
• Ручні правки на порталі: оновлюються лише is_active та is_in_stock, details.skipped = "manual_override".
• Назва: name завжди пишеться в «назву з обліку»; видима назва змінюється, лише якщо джерелом назви товару обрано облік (на порталі можна обрати інше джерело).
• Артикул і штрихкод: порожні → null; довші за 50 символів або вже зайняті іншим товаром — поле пропускається (товар приймається, у лозі попередження).
• Новий штрихкод у товару без фото ставить товар у чергу фонового збагачення (фото, вага, бренд з відкритих каталогів).

delete: мʼяке видалення; немає — 422.

price_list_item

Ціна товару в прайсі (типі цін).

• Ключ: пара (прайс за price_list_code, товар за product_code_1c). external_id рекомендовано у вигляді "<price_list_code>:<product_code_1c>" — якщо полів у payload немає, вони беруться з двох половин external_id.
• Прайс з таким кодом створюється автоматично, якщо його ще немає.
• Товар має існувати → інакше 422 «create it first».

delete: запис фізично видаляється; немає — 422.

product_external_code

Артикул товару в мережі (код, під яким товар фігурує в замовленнях мережі). Портал використовує його для розпізнавання файлів замовлень.

• Ключ: (товар за product_code_1c, sync_kind_external_id). external_id — довільний унікальний ідентифікатор рядка (не використовується для пошуку).
• Товару немає на порталі → 200, details.skipped = "product not on portal" (не помилка).

delete: рядок видаляється; немає — 200 без помилки.

manufacturer_price_type

Тип цін, за яким точка купує товари конкретного виробника (перекриває загальний прайс точки).

• Ключ: (точка client_code_1c, виробник manufacturer_external_id). external_id зберігається; рекомендований формат "<GUID точки>-<код виробника>".
• Невідома точка → 200, details = {"skipped": "client_not_found", "client_code_1c": "…"}.
• Невідомий виробник → 422.
• Відповідь: details.price_list_resolved — чи знайдено прайс з таким кодом (код зберігається завжди; прайс може прийти пізніше).
• Мʼяко видалений рядок оживає при наступному upsert.

delete: якщо передано обидва ключі — пошук за парою; інакше — за external_id. Мʼяке видалення; немає — 422.

7. Контрагенти, точки, привʼязки

counterparty

Контрагент — юридична особа (власник точок, постачальник).

• Ключ: external_id.
• Ручні правки на порталі: оновлюється лише is_active, details.skipped = "manual_override".
• Нова відстрочка (payment_terms_days) перераховує терміни оплати відкритих боргів точок цього контрагента, у яких немає власної відстрочки (лише документи, де облік не дав пізнішого терміну сам).

delete: is_active=false; немає — 422.

client

Торгова точка — адреса, куди ходить торговий і везуть товар.

• Ключ: external_id. Цей же код передається як client_code_1c в інших сутностях.
• При створенні точки портал допривʼязує до неї документи руху товару, що прийшли раніше з цим кодом.
• Точка завжди належить філії тенанта.

delete: мʼяке видалення; немає — 422.

client_assignment

Привʼязка точки до торгового (хто обслуговує точку).

• Ключ: пара (точка, торговий). external_id для пошуку не використовується.
• Якщо торгового на порталі обʼєднано з іншим (дубль), привʼязка йде на основного.
• На точці може бути лише одна основна (primary) привʼязка: якщо вже є основний торговий іншого виробника, нова привʼязка стає secondary.
• Ручна привʼязка порталу не змінюється: details.skipped = "manual_override".

delete: привʼязка видаляється (ручна — ні). Точка й торговий мусять існувати навіть для delete, інакше 422.

8. Люди й транспорт

agent

Торговий. Створюється як користувач порталу з роллю «торговий».

• Ключ: external_id.
• Новий торговий створюється неактивним і без пароля. Якщо agent_kind = "mobile" (або торговий за ознаками «для КПК»), картка одразу активується й отримує запрошення на встановлення пароля (посилання — у картці торгового на порталі). accounting — довідковий запис без доступу.
• Email: якщо передана пошта вже зайнята, ставиться службова технічна адреса.
• Відповідь при створенні: details.created = true.
• Користувач, позначений на видалення на порталі, обміном не оживає й дубль не створюється.
• Існуючий торговий: ПІБ і телефон оновлюються, якщо їх не виправляли в картці на порталі; роль змінюється лише між «торговий» і «супервайзер»; email не змінюється.
• Порожній елемент (немає ні імені, ні прізвища) для нового торгового → 200, details.skipped = "no name"; для існуючого → 422.

delete: торговий позначається довідковим (accounting), доступ знімається, торговий виходить з команд; запис і документи лишаються. Невідомий → 200, details.skipped = "unknown". Керівників (роль не «торговий») не вимикає.

driver

Водій або експедитор. Створюється як користувач з роллю «водій», неактивним — доступ до мобільного застосунку видає адміністратор на порталі.

• Ключ: external_id. На цей код посилаються vehicle.driver_external_id і trip.driver_external_id.
• Email: зайнята пошта → службова технічна адреса.
• Існуючий: оновлюються ПІБ і телефон (якщо не виправлені вручну) та реквізити; роль не змінюється.

delete: не використовуйте — щоб вивести водія з обміну, передайте transport_list без нього.

vehicle

Автомобіль.

• Ключ: external_id.
• Кожен upsert вмикає авто (is_active=true), якщо в payload немає явного is_active.

delete: is_active=false; немає — 422.

transport_list

Повний список авто й водіїв, що беруть участь в обміні. Хто поза списком — неактивне авто й водій «поза списком»; у рейсі з ними буде «Не визначено».

• Ключ: немає (снапшот). external_id — довільний, operation не впливає.
• Відповідь: details = {"vehicles_active", "vehicles_off", "drivers_active", "drivers_off"}.

9. Обладнання

equipment_type

Тип обладнання (модель холодильника, вітрини тощо). Ключ: external_id.

delete: is_active=false; немає — 422.

equipment_unit

Конкретна одиниця обладнання та її розміщення на точці.

• Ключ: external_id.
• Тип задається лише при створенні; пізніше type_external_id ігнорується.
• Якщо серійний та інвентарний номери не передано, портал шукає їх у назві типу за шаблонами сер. № … та інв. № … / инв. № ….
• Зміна точки створює запис в історії переміщень (встановлення / зняття / переміщення) з датою installed_at.

delete: мʼяке видалення; немає — 422.

10. Залишки, WMS, акциз

product_stock

Знімок поточних залишків складу без партій — для КПК, B2B і звіту «Залишки».

• Ключ: склад warehouse_code_1c (external_id конверта не використовується для пошуку).
• Повна заміна (REPLACE): товари складу, яких немає в знімку, обнуляються (рядок не видаляється).
• Склад має існувати й бути активним, інакше 422. Склад, що веде залишки у WMS (залишки ведуться у WMS), → 200 з details.skipped (знімок пропущено, не помилка).
• Невідомі товари пропускаються, їхні коди (до 50) — у details.skipped_unknown_products.
• Дублікат коду в items — діє останній.
• Відʼємний залишок записується як 0.
• Одночасно оновлюється денний зріз за сьогодні (для історії залишків).
• Відповідь: details = {"upserted", "depleted", "touched", "skipped_unknown_products"}.

delete: 422 (не підтримується).

product_stock_snapshot

Залишок складу на кінець конкретного дня — для історії залишків і днів запасу. Поточний залишок не змінює.

• Ключ: (склад, on_date). Повтор за той самий день перезаписує зріз.
• День вважається вигруженим повністю: товари зрізу цього складу за цю дату, яких немає в конверті, обнуляються.
• Склад шукається без перевірки активності; невідомий → 422. Невідомі товари пропускаються (details.unknown_products — кількість).
• Відповідь: details = {"on_date", "rows", "unknown_products"}.

wms_stock

Повний знімок партій WMS-складу.

• Ключ: склад warehouse_code_1c; партія — за batches[].external_id.
• Склад має існувати й бути активним (WMS-модуль на складі вмикати не обовʼязково — партії лягають заздалегідь).
• Вхідна партія спершу «усиновлює» тимчасову партію порталу з тим самим товаром і номером партії (створену при прийманні до обміну) — дубля не буде.
• Партія з GUID, який уже належить іншому товару, пропускається (batches_skipped_conflict).
• Повна заміна: партії складу, яких немає в знімку, обнуляються (не видаляються). Дублікати партії в знімку — кількості сумуються.
• Невідомі товари пропускаються (details.skipped_unknown_products).
• Ліміт: 10 000 партій у конверті, понад — 422.
• Відповідь: details = {"batches_upserted", "batches_adopted", "batches_created", "batches_skipped_conflict", "stocks_updated", "stocks_depleted", "skipped_unknown_products"}.

delete: 422.

stock_document

Документ інвентаризації, який облік передає на портал для перерахунку (ревізії) комірником або аудитором.

• Ключ: external_id.
• Повтор: рядки повністю замінюються, але лише поки документ у статусі new. Якщо його вже взяли в роботу — 422.
• Ліміт: 5000 рядків.
• Відповідь: details = {"doc_status", "lines_count", "lines_replaced"}.

delete: 422.

excise_marks

Пакет акцизних марок (УІ).

• Ключ: УІ марки (GTIN + серійний номер). Повтор — ідемпотентний.
• Зі складом (warehouse_code_1c; склад має бути активним і з excise_enabled) — марки приймаються на склад (in_stock); вже продана марка пропускається. Без складу — нова марка створюється як «видана» (issued), існуюча не змінюється.
• Некоректні рядки не валять пакет — потрапляють у skipped_details (до 50) з причиною.
• Товар визначається за GTIN; невідомий GTIN — рядок пропускається.
• Ліміт: 5000 марок.
• Відповідь: details = {"received", "created", "updated", "skipped", "skipped_details"}.

delete: 422.

11. Продажі й документи руху товару

sale

Факт відвантаження по заявці, створеній на порталі: облік провів реалізацію.

• Пошук заявки (по черзі): external_id як UUID заявки порталу → order_number (з payload, інакше external_id) → external_id як ключ заявки, що прийшла з обліку (logistics_order). Не знайдено → 422.
• Заявка переходить у статус «відвантажено» (скасовані й відхилені — ні), фіксується фактична кількість по рядках.
• Клієнт B2B отримує сповіщення лише при першому переході у «відвантажено» — повтор не дублює листи.
• Відповідь: details = {"lines_matched", "shipped_total"}.

goods_document

Документ руху товару: реалізація, повернення, надходження, переміщення, оприходування, списання, відповідальне зберігання. На порталі — розділ «Продажі» і «Документи обліку».

• Ключ: external_id.
• Повтор: шапка оновлюється, рядки повністю замінюються.
• Закритий місяць: документ з датою (новою або вже збереженою) у закритому періоді не змінюється — 200, details.skipped = "period closed".
• Посилання (склад, контрагент, точка, торговий, виробник, товар) шукаються мʼяко: не знайдено — зберігаються код і назва з payload. Точка: спершу серед торгових точок, потім серед точок логістики. Документ без торгового зовсім (ні коду, ні ПІБ) ставиться на службового «Віртуального торгового».
• Звʼязок із заявкою порталу — за order_number.
• Ліміт: 2000 рядків.
• Відповідь: details = {"lines", "unmatched_products"}.

Шапка:

Рядки lines[]:

delete: документ знімається з обліку (is_posted=false). Невідомий → 200, details.skipped = "unknown document". Закритий період → details.skipped = "period closed".

goods_period

Завершення вигрузки вікна документів руху товару: документи вікна, яких у цій вигрузці не було, знімаються з обліку. Плюс звірка контрольних сум «облік / портал».

• Надсилати останнім, після всіх goods_document вікна.
• Ключ: немає — кожен конверт створює новий запис звірки. external_id — довільний.
• Знімаються (is_posted=false) документи вікна з видами doc_types, які портал востаннє отримував раніше за started_at. Закритий місяць не чіпається.
• Звірка рахується по всьому вікну (разом із закритою частиною).
• Відповідь: details = {"unposted", "closed_until", "run_id"}.

Порада. Тримайте годинник облікової системи синхронізованим (NTP) і передавайте started_at на кілька хвилин раніше реального старту вигрузки.

12. Борги

debt_reset

Скидання всіх боргів тенанта перед повною вигрузкою відкритих документів: усе, що не прийде після скидання, вважається закритим.

• Видаляє всі документи заборгованості тенанта і обнуляє борг усіх точок. external_id і payload не читаються.
• Відповідь: details.cleared — кількість видалених документів.

Увага. Між скиданням і приходом нових документів борги на порталі нульові. Надсилайте debt_reset першим конвертом у тому самому пакеті, що й документи боргу, з partial: false (атомарно).

debt_document

Відкритий (або закритий) документ заборгованості точки.

• Ключ: external_id.
• Точка (client_code_1c) потрібна лише при створенні. Якщо точки немає, вона створюється з полів client_* (і контрагент із полів counterparty_*, якщо є counterparty_external_id і counterparty_name) — тими самими правилами, що client і counterparty. Без client_name → 422.
• Статус: status з payload, інакше open, якщо remaining_amount > 0, інакше closed.
• Термін оплати: якщо облік передав due_date пізніше за doc_date — він головний. Інакше портал рахує doc_date + відстрочка, де відстрочка — з регістру «контрагент × виробник» (manufacturer_payment_term), інакше точки, інакше контрагента.
• Поля client_payment_terms_days / counterparty_payment_terms_days (> 0) оновлюють відстрочку вже існуючих точки / контрагента.
• Борг точки на порталі перераховується один раз наприкінці пакета.
• Відповідь: details = {"status", "remaining"}.

delete: документ закривається (status=closed, залишок 0), запис лишається. Немає — 422.

manufacturer_payment_term

Відстрочка платежу контрагента по конкретному виробнику (перекриває загальну відстрочку при розрахунку терміну боргу).

• Ключ: (контрагент counterparty_external_id, виробник manufacturer_external_id). external_id зберігається; рекомендований формат "<GUID контрагента>-<код виробника>".
• Невідомий контрагент → 200, details.skipped = "counterparty_not_found". Невідомий виробник → 422.
• Без виробника (all_manufacturers: true або порожній manufacturer_external_id) — це одна відстрочка на всіх виробників: записується як відстрочка контрагента; details.counterparty_payment_terms_days.
• Мʼяко видалений рядок оживає при наступному upsert.
• Відповідь: details.days.

delete: за парою ключів або (без ключів) за external_id; мʼяке видалення; немає — 422. Для all_manufacturers — details.skipped = "all_manufacturers_delete_ignored".

13. Каса

cash_document

Грошовий документ: прибутковий / видатковий касовий ордер, банківська виписка.

• Ключ: external_id. Повтор — upsert.
• Напрям визначається видом: cash_in, bank_in — надходження; cash_out, bank_out — витрата. Сума зберігається за модулем.
• Посилання (контрагент, точка, торговий, виробник) — мʼякі, як у goods_document.
• Закритого місяця для каси немає.
• Відповідь: details = {"doc_type", "direction"}.

delete: is_posted=false; невідомий → 200, details.skipped = "unknown document".

cash_balance

Залишок коштів по касі / рахунку на дату вигрузки.

• Ключ: (account_code, вид коштів). external_id не використовується.
• Відповідь: details.balance.

delete: рядок видаляється; details.deleted.

cash_period

Завершення вигрузки вікна каси: документи вікна, не отримані в цій вигрузці (востаннє отримані раніше за started_at), знімаються з обліку. Надсилати останнім.

Відповідь: details.unposted. На відміну від goods_period, фільтра за видами документів і захисту закритого місяця немає.

14. Стан заявок порталу в обліку

Заявка порталу потрапляє в облік як непроведений документ. Облік повідомляє про його стан; видалення документа в обліку скасовує заявку на порталі (з повідомленням торговому, керівникам і клієнту B2B). Назад в облік скасування не передається.

order_state

• Пошук заявки: external_id → ідентифікатор документа в обліку, отриманий порталом при підтвердженні заявки; або order_number. Заявки логістики не розглядаються. Не знайдено → 200, details.skipped = "unknown order".
• deleted: true → заявку скасовано (якщо вона в статусі, який можна скасувати). Розпроведення без видалення заявку не скасовує — стан лише запамʼятовується.
• Відповідь: details.cancelled.

order_state_period

Кінець списку станів: заявки, передані в облік у вікні, по яких у цій вигрузці не прийшло order_state, вважаються видаленими повністю й скасовуються.

• Розглядаються заявки, підтверджені обліком у проміжку від date_from + 1 день до started_at − 2 години, які не отримували order_state після started_at.
• count <= 0 → нічого не скасовується (details.skipped = "empty list") — захист від збою запиту в обліку.
• У батчі: якщо хоча б один order_state у цьому ж батчі не прийнято, order_state_period відхиляється (щоб не скасувати заявки, чий стан не записався).
• Відповідь: details.cancelled.

15. Рейси (ходки)

trip

Ходка обліку. Має два режими залежно від наявності payload.number.

Режим «рейс» (є number, а також для будь-якого delete) — ходка стає рейсом на порталі.

• Ключ: external_id. Якщо рейс не знайдено, але передано router_number — шукається рейс, створений на порталі й переданий в облік (щоб не завести дубль).
• Повтор: рейс з обліку перебудовується: водій, авто, статус, склад документів і заявок — за payload. Рейс, зібраний на порталі, облік лише доповнює (порожні поля, статус тільки вперед, точки додаються).
• Номер рейсу на порталі унікальний: при збігу додається суфікс з датою.
• Статус: дата в минулому — «завершено»; сьогодні — «в дорозі» (shipped) або «завантажено»; майбутня — «збирається» (за Europe/Kyiv).
• Водій / експедитор поза списком обміну (transport_list) або невідомий → «Не визначено»; pickup: true без авто → «Самовивіз».
• Документи (document_external_id) і заявки (order_number) привʼязуються до рейсу; ті, що вже в іншому рейсі, не забираються. Документи, що прийдуть пізніше, допривʼяжуться за номером ходки й датою відвантаження (goods_document.trip).
• Кілометраж рахується дорогами по точках; distance_km з обліку зберігається для звірки й використовується, лише якщо маршрут побудувати не вдалося.
• Відповідь: details = {"created", "distance_km", "trip_number", "documents", "documents_pending", "orders"} (+ driver: "not_found").

delete: рейс скасовується, документи й заявки відчіплюються. Не знайдено → 200, details.skipped = "trip_not_found".

Режим «призначення водія» (немає number) — лише проставляє водія заявкам порталу, статуси не змінює.

Відповідь: details = {"assigned", "orders_not_found"}.

16. Модуль логістики

Модуль логістики (3PL-доставка для виробників) має власні довідники й каталог, незалежні від торгового контуру.

logistics_order

Заявка на доставку, створена в обліку: на порталі одразу підтверджена й видима на дошці рейсів. Відвантаження по ній — звичайний sale з тим самим external_id.

• Ключ: external_id серед заявок, що прийшли з облікової системи.
• Повтор: заявка не перестворюється (details.skipped = "already imported"); заявка вже в рейсі чи далі — details.skipped = "status=…".
• Заявка оформлюється на віртуального B2B-торгового філії, інакше — на першого активного адміністратора; немає жодного → 422.
• Відповідь: details = {"order_number", "lines", "missed_products"}.

delete: скасування, якщо заявка ще в статусі «нова» / «підтверджена» і не в рейсі; інакше details.skipped. Немає — 422.

logistics_manufacturer

Виробник торгового довідника з позначкою «логістика». Поля, ключ і delete — як у manufacturer; при upsert додатково ставиться позначка логістики.

logistics_own_manufacturer

Виробник модуля логістики. Ключ: external_id (спільний довідник виробників).

delete: is_active=false; немає — 422.

logistics_counterparty

Контрагент логістики. Ключ: external_id.

delete: is_active=false; немає — 422.

logistics_point

Точка доставки логістики. Ключ: external_id. При створенні допривʼязує документи руху товару, що прийшли раніше з цим кодом точки.

delete: is_active=false; немає — 422.

logistics_warehouse

Склад модуля логістики (той самий довідник складів, з позначкою «логістика»). Ключ: external_id.

delete: is_active=false; немає — 422. Спершу передайте branch.

logistics_product_category

Категорія каталогу логістики. Ключ: external_id.

delete: is_active=false; немає — 422.

logistics_product

Товар каталогу логістики. Ключ: external_id. Новий штрихкод без фото — у чергу збагачення.

delete: is_active=false; немає — 422.

logistics_product_code

Код товару логістики в мережі.

• Ключ: (товар product_external_id — за замовчуванням external_id конверта; kind_external_id).
• Товару немає → 422.

delete: рядок видаляється.

logistics_stock

Знімок залишків складу логістики. Аналог product_stock над каталогом логістики.

• Склад має бути активним і саме складом логістики, інакше 422.
• Товар шукається за external_id товару логістики, запасний варіант — його code_1c.
• Частина невідомих кодів — допустимо (details.unknown_products); жодного знайденого → 422 (захист від обнулення складу через неправильне поле).
• Повна заміна з обнуленням відсутніх + денний зріз за сьогодні.
• Відповідь: details = {"upserted", "depleted", "unknown_products", "unknown_sample"}.

delete: 422.

17. Приклади конвертів

Готові батчі: examples/exchange-inbound-batch-catalog.json, examples/exchange-inbound-batch-stock.json, examples/exchange-inbound-batch-sales.json.

client

{
  "entity_type": "client",
  "operation": "upsert",
  "external_id": "5c1e8a20-4b7f-11ee-9d3c-0050569a1b2c",
  "payload": {
    "name": "Маркет «Колосок»",
    "legal_name": "ФОП Петренко О. В.",
    "address": "вул. Шевченка, 12",
    "city": "Полтава",
    "region": "Полтавська",
    "phone": "+380671234567",
    "channel": "Традиційна торгівля",
    "counterparty_external_id": "7a2d4f10-4b7f-11ee-9d3c-0050569a1b2c",
    "price_list_code": "000000002",
    "payment_terms_days": "14",
    "credit_limit": "25000.00",
    "external_codes": [{"kind": "GLN", "code": "4820000123456"}],
    "latitude": "49.5883",
    "longitude": "34.5514"
  }
}

product

{
  "entity_type": "product",
  "operation": "upsert",
  "external_id": "b3f61c42-4b7f-11ee-9d3c-0050569a1b2c",
  "payload": {
    "name": "Сік яблучний 1 л",
    "sku": "JA-1000",
    "barcode": "4820017000123",
    "unit": "шт",
    "base_price": "18.50",
    "vat_rate": 20,
    "manufacturer_external_id": "000000017",
    "manufacturer": "ТОВ «Сади Приклад»",
    "category_code_1c": "c9d02e11-4b7f-11ee-9d3c-0050569a1b2c",
    "pack_size": 6,
    "weight_kg": "1.1",
    "is_active": true
  }
}

price_list_item

{
  "entity_type": "price_list_item",
  "operation": "upsert",
  "external_id": "000000002:b3f61c42-4b7f-11ee-9d3c-0050569a1b2c",
  "payload": {
    "price_list_code": "000000002",
    "product_code_1c": "b3f61c42-4b7f-11ee-9d3c-0050569a1b2c",
    "price": "17.90"
  }
}

counterparty

{
  "entity_type": "counterparty",
  "operation": "upsert",
  "external_id": "7a2d4f10-4b7f-11ee-9d3c-0050569a1b2c",
  "payload": {
    "name": "ФОП Петренко Олена Василівна",
    "kind": "buyer",
    "edrpou": "3012345678",
    "tax_number": "3012345678",
    "legal_address": "м. Полтава, вул. Шевченка, 12",
    "payment_terms_days": 7,
    "is_group": false,
    "parent_external_id": "1e44a9b0-4b7f-11ee-9d3c-0050569a1b2c",
    "is_active": true
  }
}

goods_document

{
  "entity_type": "goods_document",
  "operation": "upsert",
  "external_id": "e7a1c3d5-6f80-11ef-8a1b-0050569a1b2c",
  "payload": {
    "doc_type": "sale",
    "doc_number": "РН-0004512",
    "doc_date": "2026-10-26T14:35:00",
    "warehouse_code": "2f6c9e30-4b7f-11ee-9d3c-0050569a1b2c",
    "client_code_1c": "5c1e8a20-4b7f-11ee-9d3c-0050569a1b2c",
    "client_name": "Маркет «Колосок»",
    "counterparty_code": "7a2d4f10-4b7f-11ee-9d3c-0050569a1b2c",
    "agent_external_id": "a8b9c0d1-4b7f-11ee-9d3c-0050569a1b2c",
    "agent_name": "Іваненко Ігор",
    "manufacturer_external_id": "000000017",
    "trade_kind": "Безготівковий розрахунок",
    "order_number": "ORD-20261026-0042",
    "lines": [
      {"line_no": 1, "product_code_1c": "b3f61c42-4b7f-11ee-9d3c-0050569a1b2c", "quantity": "24", "price": "17,90", "amount": "429,60"}
    ]
  }
}

product_stock

{
  "entity_type": "product_stock",
  "operation": "upsert",
  "external_id": "2f6c9e30-4b7f-11ee-9d3c-0050569a1b2c",
  "payload": {
    "warehouse_code_1c": "2f6c9e30-4b7f-11ee-9d3c-0050569a1b2c",
    "items": [
      {"product_code_1c": "b3f61c42-4b7f-11ee-9d3c-0050569a1b2c", "qty": "1320", "amount": "19140.00"},
      {"product_code_1c": "b3f61c43-4b7f-11ee-9d3c-0050569a1b2c", "qty": "0"}
    ]
  }
}

debt_document

{
  "entity_type": "debt_document",
  "operation": "upsert",
  "external_id": "d2c4e6f8-6f80-11ef-8a1b-0050569a1b2c",
  "payload": {
    "client_code_1c": "5c1e8a20-4b7f-11ee-9d3c-0050569a1b2c",
    "client_name": "Маркет «Колосок»",
    "doc_number": "РН-0004512",
    "doc_type": "realization",
    "doc_date": "2026-10-26",
    "due_date": "2026-10-26",
    "amount": "429.60",
    "remaining_amount": "429.60",
    "payment_form": "безнал",
    "manufacturer_external_id": "000000017",
    "agent_external_id": "a8b9c0d1-4b7f-11ee-9d3c-0050569a1b2c"
  }
}

order_state

{
  "entity_type": "order_state",
  "operation": "upsert",
  "external_id": "f1e2d3c4-6f80-11ef-8a1b-0050569a1b2c",
  "payload": {
    "order_number": "ORD-20261026-0042",
    "posted": false,
    "deleted": true,
    "reason": "Клієнт відмовився"
  }
}