Як передати штрих-коди

Передача штрих-кодів на сервер — необов'язковий крок.

Кожен документ, який приходить на ТСД, уже несе власний список номенклатури, з яким працює оператор.

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

Щоб сервер ComboPocket зміг знайти такий товар, його штрих-коди мають бути передані заздалегідь.

Приклад. Під час переобліку оператор знаходить товар, який раніше вважався списаним. Якщо база штрих-кодів завантажена, товар автоматично додається до документа перерахунку й ставиться на прихід.

Якщо такий сценарій вам не потрібен — розділ можна повністю пропустити.

Як влаштовано передачу

Щоб увімкнути пошук по всій базі штрих-кодів, таблицю штрих-кодів потрібно передати на сервер.

Передача йде покроково, пакетами: спочатку відкривається сесія вивантаження, потім дані надсилаються порціями, і в кінці сесія закривається.

Такий підхід береже інтернет-канал і вашу облікову базу, розбиваючи велику таблицю на керовані порції.

Передача складається з трьох кроків:

Відкрили сесію вивантаження.
Пакетно передали дані.
Закрили сесію.

Передача не впливає на роботу операторів із ТСД: оновлений набір штрих-кодів стає доступним на терміналі лише після повного й успішного вивантаження всієї бази.

Основи взаємодії

Базова адреса API: https://combopocket.online/v2/exchange.

Усі операції виконуються методом POST, тіло запиту — JSON у кодуванні UTF-8.

Кожен запит несе заголовок X-API-Token з токеном вашої бази — входу в систему й сесій авторизації немає.

Результат операції сервер кладе в тіло — у поле ok: true — виконано, false — відмова з причиною в error і підказкою в recommendation.

HTTP-код — рівень транспорту (чи доїхав запит до обробки): 200 — запит оброблено, 4xx — до обробки не дійшов, 5xx — збій у нас.

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

Протокол: сесія й порції

Таблиця штрих-кодів може налічувати сотні тисяч рядків. Передавати її одним запитом не можна — це важко і для каналу, і для вашої облікової системи. Тому обмін побудовано навколо двох понять:

Сесія вивантаження таблиці штрих-кодів — «дужки» навколо всієї передачі: ви відкриваєте сесію, передаєте дані, закриваєте сесію.

Ідентифікатор сесії session_id (UUID) генеруєте ви самі. Завдяки цьому будь-який крок можна безпечно повторити: сервер розпізнає «свою» сесію й не задвоює дані.

На одну базу допустима лише одна активна сесія — таблиця штрих-кодів передається як єдине ціле, паралельні завантаження конфліктували б між собою.

Порція (chunk) — пакет рядків таблиці штрих-кодів. Розмір порції диктує сервер: у відповіді на відкриття сесії прийде chunk_limit — максимум рядків в одному пакеті.

Порції нумеруються строго послідовно: 1, 2, 3… Це гарантія цілісності: сервер завжди знає, що нічого не втратилося й не прийшло двічі.

Повтор уже прийнятої порції безпечний — під час обриву зв'язку просто надішліть останній запит ще раз.

Усі передані рядки накопичуються в проміжному сховищі й переносяться до робочої таблиці штрих-кодів лише в момент закриття сесії.

Поки передачу не завершено, термінали продовжують працювати з попереднім набором штрих-кодів.

Схема обміну

Крок 1

session_open

відкрити сесію вивантаження, отримати chunk_limit

× N

Крок 2

upload_chunk

надсилати порції, chunk_no = 1, 2, 3…

Крок 3

session_close

зафіксувати: Saved + кількість рядків

Контроль

status

підсумок сесії в будь-який момент

обрив зв'язку — повторіть останній запит, повтор безпечний у відповіді socket_status: "Close" — сесію закрито сервером, починайте нову

POST /barcodes/session_open відкрити сесію вивантаження

Відкриває сесію вивантаження таблиці штрих-кодів.

У відповідь сервер повідомляє chunk_limit — розмір порції, який він готовий приймати, і next_chunk — номер порції, яку очікує наступною (для нової сесії це завжди 1).

Поле	Тип		Призначення
session_id	uuid	обов.	Ідентифікатор сесії. Генеруєте ви — це робить повтор будь-якого кроку безпечним.
force	bool		Витіснити чужу незакриту сесію. Потрібен, коли попередня передача обірвалася й «висить»: її недозавантажені дані будуть стерті, ваша сесія відкриється.
sku_settings	object		Параметри вагових кодів вашої облікової системи: `pref` — префікс вагового коду, `sku_length` — довжина коду товару всередині штрих-коду, `sku_point` — знаків після коми у вазі. Передавайте, якщо використовуєте ваговий товар: сервер запам'ятає налаштування й правильно розбиратиме коди, надруковані вагами.

ЗапитPOST /v2/exchange/barcodes/session_open

{
  "session_id": "6f1a2b3c-0000-4000-8000-000000000001",
  "force": false,
  "sku_settings": { "pref": "22", "sku_length": 5, "sku_point": 3 }
}

Відповідь — сесію відкрито

{
  "ok": true,
  "error": "",
  "chunk_limit": 1000,
  "next_chunk": 1
}

Якщо інша сесія вже відкрита, сервер відмовить і підкаже, коли вона почалася. Рішення за вами: почекати на її завершення або витіснити повтором із force: true.

Відповідь — уже йде інша передача

{
  "ok": false,
  "error": "already_open",
  "opened_at": "2026-07-09T10:15:00",
  "recommendation": "Іде інше вивантаження. Повторіть з force:true, щоб перервати його"
}

Особливий випадок — відповідь busy: сервер саме зараз переносить попереднє вивантаження до робочої таблиці штрих-кодів. Витіснити його не можна, дочекайтеся завершення, опитуючи status.

Повторне відкриття своєї ж сесії (той самий session_id) — не помилка: сервер відповість успіхом і поверне актуальний next_chunk, щоб ви могли продовжити з місця обриву.

POST /barcodes/upload_chunk передати порцію

Передає одну порцію рядків таблиці штрих-кодів. Кількість рядків у items не повинна перевищувати chunk_limit, отриманий під час відкриття сесії.

Поле	Тип		Призначення
session_id	uuid	обов.	Сесія, відкрита на кроці 1.
chunk_no	int ≥ 1	обов.	Номер порції, строго за порядком: 1, 2, 3… Так сервер контролює цілісність потоку: ніщо не пропало й не прийшло двічі.
items	array	обов.	Рядки таблиці штрих-кодів. Один рядок — один штрих-код товару.

Поля рядка items[]:

Поле	Тип		Призначення
item_id	string ≤ 100	обов.	Ідентифікатор товару у вашій обліковій системі. Ключове поле: за ним штрих-коди групуються в картку товару, і за ним же знайдений товар повернеться до вас у документах. Якщо товар обліковується з характеристиками (колір, розмір), включіть характеристику в ідентифікатор — кожна характеристика стає окремою карткою зі своїм `item_id`. Той самий `item_id` має приходити й у рядках документів, інакше знайдений під час сканування товар не збіжиться з позицією завдання.
code	string ≤ 50		Штрих-код. Може бути порожнім — тоді товар потрапить до бази без коду й знаходитиметься пошуком за назвою.
is_sku	bool		Ознака вагового коду: `true`, якщо в `code` передано код товару для вагів, а не звичайний штрих-код. Дозволяє одному товару одночасно мати і звичайні штрих-коди, і ваговий код.
name	string ≤ 150		Назва товару — її побачить оператор на екрані термінала.
char	string ≤ 150		Характеристика (колір, розмір, варіант). Показується поруч із назвою.
qty_int_only	bool		Товар вважається лише цілими числами (штуки). Термінал не дасть оператору ввести дробову кількість.

ЗапитPOST /v2/exchange/barcodes/upload_chunk

{
  "session_id": "6f1a2b3c-0000-4000-8000-000000000001",
  "chunk_no": 1,
  "items": [
    { "item_id": "A-00017", "code": "4820000999888", "name": "Кава зернова 1кг", "qty_int_only": true },
    { "item_id": "A-00017", "code": "4820000999895", "name": "Кава зернова 1кг", "qty_int_only": true },
    { "item_id": "A-00093", "code": "22", "is_sku": true, "name": "Яблуко Голден", "char": "вага" },
    { "item_id": "A-00105", "code": "", "name": "Пакет фірмовий" }
  ]
}

Зверніть увагу: один товар може мати кілька штрих-кодів — просто передайте кілька рядків з одним item_id, як у прикладі вище.

Відповідь — порцію прийнято

{
  "ok": true,
  "error": "",
  "socket_status": "Open",
  "next_chunk": 2
}

Поле socket_status — сигнал, чи можна продовжувати: Open — сервер чекає наступну порцію, Close — сесію закрито сервером, подальша передача в ній неможлива.

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

Якщо порядок нумерації порушено (наприклад, частина запитів пішла паралельно й обігнала один одного), сервер закриває сесію з помилкою desync — дані в такому потоці вже не можна вважати цілими. Почніть нову сесію.

Відповідь — порушено послідовність

{
  "ok": false,
  "error": "desync",
  "socket_status": "Close",
  "next_chunk": null,
  "recommendation": "Відкрийте нову сесію й почніть вивантаження заново"
}

POST /barcodes/session_close закрити сесію

Завершує передачу.

Без параметра abort — це фіксація: усе, що накопичено за сесію, переноситься до робочої таблиці штрих-кодів і з цієї миті доступне терміналам.

З abort: true — скасування: накопичене стирається, робоча таблиця не змінюється.

Поле	Тип		Призначення
session_id	uuid	обов.	Сесія, яку закриваємо.
abort	bool		`true` — скасувати передачу й стерти накопичені дані. Типово `false` — зафіксувати.

ЗапитPOST /v2/exchange/barcodes/session_close

{
  "session_id": "6f1a2b3c-0000-4000-8000-000000000001"
}

Відповідь — таблицю штрих-кодів оновлено

{
  "ok": true,
  "error": "",
  "status": "Saved",
  "written": 4
}

written — скільки рядків записано до таблиці штрих-кодів. Число може бути меншим, ніж ви надіслали: точні дублікати рядків згортаються в один запис.

На великих таблицях штрих-кодів перенесення забирає час, і відповідь може прийти зі статусом Busy — сервер продовжує роботу у фоні.

Це не помилка: опитуйте status раз на кілька секунд, доки не побачите Saved.

Відповідь — сервер ще зберігає

{
  "ok": true,
  "error": "",
  "status": "Busy"
}

Повторне закриття вже збереженої сесії — не помилка: сервер знову відповість Saved з тим самим written. Це дозволяє безпечно повторювати запит під час обриву зв'язку.

POST /barcodes/status перевірити підсумок

Повертає стан останньої сесії вашої бази. Параметри не потрібні — достатньо порожнього тіла {}.

Використовуйте цю операцію, щоб дочекатися завершення перенесення після Busy, перевірити підсумок передачі або розібратися, чим закінчилася сесія після обриву зв'язку.

ЗапитPOST /v2/exchange/barcodes/status

{}

Відповідь — передачу завершено успішно

{
  "ok": true,
  "status": "Saved",
  "written": 4,
  "last_sessionid": "6f1a2b3c-0000-4000-8000-000000000001"
}

Можливі значення status:

Значення	Що означає
Open	Сесія відкрита, сервер чекає порції.
Busy	Іде перенесення даних до робочої таблиці штрих-кодів. Почекайте й опитайте статус ще раз.
Saved	Передачу зафіксовано, у відповіді `written` — кількість записаних рядків.
Aborted	Сесію скасовано (вами через `abort` або витіснено іншою сесією).
ServerError	Сесія завершилася помилкою, причина — у полі `reason`.

Відповідь — сесія завершилася помилкою

{
  "ok": true,
  "status": "ServerError",
  "reason": "Очікувався чанк 2, отримано 4",
  "last_sessionid": "6f1a2b3c-0000-4000-8000-000000000001"
}

Зверніть увагу: ok: true тут означає «запит статусу виконано успішно», а сам підсумок сесії описує поле status.

Перевірка даних

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

Правило	Навіщо
Порожній `item_id` — відмова	Без ідентифікатора товару рядок ні до чого прив'язати.
Один `code` у двох різних `item_id` — відмова	Один штрих-код не може вести до двох товарів: термінал не зміг би вирішити, який товар знайдено. Перевіряється і в межах порції, і по всіх раніше переданих порціях сесії.
`item_id` довший за 100 або `code` довший за 50 — відмова	Ключові поля не усікаються мовчки: обрізання змінило б ідентичність товару.
`name` і `char` усікаються до 150 символів	Описові поля безпечно скорочувати — ідентичність товару вони не задають.
Пробіли всередині `item_id` та `code` видаляються	Числові коди часто приходять із розділювачами розрядів («4 820 000…») — сервер очищає їх автоматично.
Точний повтор рядка згортається	Повні дублікати не вважаються помилкою — записується один рядок.

Під час помилки валідації сесія закривається (socket_status: "Close"), а накопичені в ній дані стираються — частково завантажена таблиця штрих-кодів ніколи не потрапить у роботу.

Виправте дані в обліковій системі й почніть нову сесію.

Відповідь — помилка в даних

{
  "ok": false,
  "error": "Помилка валідації даних: дубль ключових полів - штрих-код 4820000999888 у номенклатур A-00017 та A-00021",
  "socket_status": "Close",
  "next_chunk": null,
  "recommendation": "Виправте дані в обліковій системі й повторіть вивантаження"
}

Довідник відмов

error	Коли виникає	Що робити
unauthorized	Токен не передано або він невідомий.	Перевірте заголовок `X-API-Token` і значення токена.
already_open	Відкрито іншу сесію.	Дочекатися її завершення або повторити відкриття з `force: true`.
busy	Сервер переносить попереднє вивантаження.	Опитувати `status` до `Saved`, потім відкривати сесію.
session_not_found	Сесії немає або вона вже закрита.	Звіритися зі `status`; за потреби відкрити нову сесію.
desync	Порушено послідовність порцій.	Відкрити нову сесію й передати таблицю штрих-кодів заново.
Помилка валідації даних: …	У порції знайдено помилку (текст указує рядок).	Виправити дані, відкрити нову сесію.
виявлено брутфорс	Забагато запитів із неправильним токеном.	Перевірити токен; блокування знімається автоматично.