Перерахунок

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

Завдання — звичайний документ вашої облікової системи: список товарів із плановими кількостями. Для приймання товару є окремий вид документа — Надходження, влаштований точно так само.

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

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

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

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

Відповідь завжди несе поле ok у тілі: true — успіх, false — відмова з причиною в error.

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

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

Ключові поняття

Зовнішній ідентифікатор (external_id) — ідентифікатор документа у вашій обліковій системі. Це головний ключ усього обміну: за ним ви оновлюєте завдання, опитуєте статус, забираєте результат і видаляєте документ.

Ідентифікатор унікальний у межах вашої бази — другого документа з таким самим external_id не буде.

Виконавець (assignee_token) — токен оператора, якому призначається завдання. Кожен оператор ТСД має власний токен, і завдання з'явиться на терміналі саме того оператора, чий токен ви вказали.

Токен виконавця потрібен лише під час надсилання — решта операцій працює за external_id.

Версія документа (docversion) — ваша мітка версії, будь-який рядок. Вона захищає від зайвої роботи: якщо ви повторно надішлете документ із тією самою версією, сервер відповість unchanged і нічого не перезапише.

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

Життєвий цикл

Поки завдання у статусі NotStarted, його можна вільно перезаписувати повторними upload — сервер замінить вміст цілком.

Щойно оператор почав роботу (InProgress) або завершив її (Done), перезапис заборонено: сервер відповість відмовою conflict, щоб робота оператора не була втрачена.

Надсилання завдання

Створює нове завдання або цілком замінює наявне (поки воно NotStarted).

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

Налаштування поведінки на терміналі settings

Необов'язковий об'єкт — задає, що оператор бачить на екрані завдання і що йому дозволено.

Передавати settings цілком не обов'язково; будь-яке відсутнє поле (як і весь об'єкт) трактується як true.

Налаштування зберігаються в документі й завжди повертаються назад у status і download — навіть якщо ви їх не надсилали.

Кожен рядок rows[] — одна товарна позиція:

{
  "external_id": "INV-2026-0042",
  "assignee_token": "22222222-3333-4444-5555-666666666666",
  "name": "Перерахунок залу №1",
  "date": "2026-07-10T12:00:00+03:00",
  "docversion": "v1",
  "store_name": "Магазин на Хрещатику",
  "settings": { "show_fact_qty": true, "show_progress": true,
                "allow_add_unlisted": false, "show_book_qty": true },
  "rows": [
    { "item_id": "MLK-001", "name": "Молоко 2,5%", "char": "0,9 л",
      "qty_plan": 10, "line_num": 1, "qty_int_only": true,
      "bc_array": [ { "code": "4820000001234", "is_sku": false },
                    { "code": "25", "is_sku": true } ] },
    { "item_id": "BRD-05", "name": "Хліб Бородинський",
      "qty_plan": 5, "line_num": 2, "qty_int_only": true }
  ]
}

{ "ok": true, "doc_status": "created" }

Поле doc_status каже, що саме сталося: created — завдання створено, updated — наявне замінено цілком, unchanged — версія збіглася, нічого не змінювалося.

{ "ok": false, "error": "conflict", "status": "InProgress" }

{
  "ok": false,
  "error": "validation_failed",
  "recommendation": "штрих-код 4820000001234 указано в різних номенклатур: MLK-001 і KEF-002"
}

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

Сервер перевіряє завдання до запису — або приймається все, або ніщо:

Отримання результату

Далі працюють три читальні операції та видалення. Токен виконавця їм не потрібен — тільки external_id.

Повертає всі перерахунки вашої бази — тіло запиту не потрібне (порожній {}). Зручний як огляд: що вивантажено, що в роботі, що готове до забирання.

{
  "ok": true,
  "truncated": false,
  "docs": [
    { "name": "Перерахунок залу №1",
      "external_id": "INV-2026-0042",
      "status": "Done",
      "docversion": "v1",
      "assignee_token": "22222222-3333-4444-5555-666666666666",
      "created_on_tsd": false,
      "started_at": "2026-07-10T09:15:00+03:00",
      "completed_at": "2026-07-10T11:40:00+03:00" }
  ]
}

Зверніть увагу на два поля.

created_on_tsd: true позначає перерахунки, які оператор створив просто на терміналі — вашій системі вони поки невідомі, і ви самі вирішуєте, чи забирати їх.

truncated: true означає, що список уперся в запобіжний ліміт (налаштовується для бази, типово 1000) і показано лише його частину — ознака того, що виконані документи пора видаляти.

Легка операція для опитування перебігу роботи: замість вивантаження всіх рядків сервер віддає готові лічильники. Саме її варто викликати за розкладом.

{ "external_id": "INV-2026-0042" }

{
  "ok": true,
  "status": "InProgress",
  "started_at": "2026-07-10T09:15:00+03:00",
  "completed_at": null,
  "items_total": 120,
  "items_counted": 45,
  "items_extra": 3,
  "progress_percent": 37,
  "discrepancy_count": 7,
  "settings": { "show_fact_qty": true, "show_progress": true,
                "allow_add_unlisted": false, "show_book_qty": true }
}

Повний результат перерахунку. Рядки повертаються в порядку line_num — тому самому, у якому ви їх надсилали, тому зіставлення з вашим документом тривіальне.

Поля рядків симетричні надсиланню: що ви надіслали в upload, під тими самими іменами повернеться тут.

У шапці відповіді повертаються й налаштування документа (settings).

{ "external_id": "INV-2026-0042" }

{
  "ok": true,
  "external_id": "INV-2026-0042",
  "status": "Done",
  "docversion": "v1",
  "created_at": "2026-07-10T08:00:00+03:00",
  "started_at": "2026-07-10T09:15:00+03:00",
  "completed_at": "2026-07-10T11:40:00+03:00",
  "comment_initial": "Перерахувати до обіду",
  "comment_user": "Стелаж 4 перекрито, перераховано частково",
  "settings": { "show_fact_qty": true, "show_progress": true,
                "allow_add_unlisted": false, "show_book_qty": true },
  "rows": [
    { "item_id": "MLK-001", "name": "Молоко 2,5%", "char": "0,9 л",
      "qty_plan": 10, "qty_fact": 8, "line_num": 1, "is_counted": true,
      "bc_array": [ { "code": "4820000001234", "is_sku": false } ] }
  ],
  "extra_rows": [
    { "item_id": "SOK-11", "name": "Сік яблучний",
      "qty_plan": 0, "qty_fact": 4, "line_num": -1, "is_counted": true,
      "bc_array": [ { "code": "4820000009999", "is_sku": false } ] }
  ],
  "photos": [
    { "name": "181467df-d4ca-4e4b-b344-1aca7bbb9fb4",
      "comment": "Стелаж 4, розкрита упаковка" }
  ]
}

Поділ rows / extra_rows відповідає на головне питання інвентаризації.

rows — доля позицій вашого завдання: за різницею qty_plan і qty_fact видно недостачі й надлишки.

extra_rows — товар, який оператор знайшов у залі, хоча в завданні його не було.

Прапорець is_counted вирішує класичну неоднозначність нуля: qty_fact: 0 з is_counted: true означає «оператор перевірив — товару немає», а з is_counted: false — «до позиції не дійшли».

Без цього прапорця недостачу неможливо відрізнити від непорахованого залишку.

Масив photos — метадані фотографій, знятих оператором: name (ідентифікатор знімка) і comment (підпис). Самі зображення в документ не вкладаються — download залишається легким.

Показати знімки можна, взагалі не вивантажуючи документ (photos_thumbnails), а отримати оригінал — за іменем (download_photo).

Обидві операції нижче; усе про фото зібрано й на окремій сторінці «Фотографії».

Повертає за external_id масив мініатюр — для прев'ю без вивантаження документа.

У кожного знімка: ім'я оригіналу, ім'я мініатюри, підпис і сама мініатюра в base64.

{ "external_id": "INV-2026-0042" }

{
  "ok": true,
  "photos": [
    { "name": "181467df-d4ca-4e4b-b344-1aca7bbb9fb4",
      "thumb_name": "181467df-d4ca-4e4b-b344-1aca7bbb9fb4.thumb",
      "comment": "Стелаж 4, розкрита упаковка",
      "thumb_b64": "/9j/4AAQSkZJRgABAQ…" }
  ]
}

Повертає оригінал однієї фотографії в base64. Ім'я беріть із відповіді photos_thumbnails або з масиву photos в download.

Фото віддається по одному — так відповідь не розростається, і ви тягнете тільки те, що справді потрібно.

{ "name": "181467df-d4ca-4e4b-b344-1aca7bbb9fb4" }

{
  "ok": true,
  "name": "181467df-d4ca-4e4b-b344-1aca7bbb9fb4",
  "comment": "Стелаж 4, розкрита упаковка",
  "size": 148213,
  "data_b64": "/9j/4AAQSkZJRgABAQ…"
}

{ "ok": false, "error": "not_found" }

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

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

{ "ok": true, "doc_status": "deleted" }

Час у відповідях

Усі дати й час (created_at, started_at, completed_at) сервер віддає зі зсувом часового поясу: 2026-07-10T08:00:00+03:00. Незаповнений час — null.

Надсилаючи date, вказуйте власний зсув — момент буде зрозуміло однозначно, навіть якщо ваша система працює в іншому поясі. Форма без зсуву теж приймається й означає київський час.

Подробиці контракту часу — на сторінці «З чого почати».

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

Рекомендований алгоритм

1. Сформуйте завдання в обліковій системі й надішліть його upload-ом із новим docversion. Повтор запиту безпечний: завдяки версії сервер не зробить подвійної роботи.
2. Отримали created або updated — завдання на терміналі оператора. Отримали validation_failed — виправте дані за текстом recommendation і повторіть.
3. За розкладом опитуйте status (або оглядово — list).
4. Статус став Done — викличте download і проведіть результат: rows — по рядках вашого документа, extra_rows — як надлишки.
5. Результат проведено — викличте delete, щоб убрати виконане завдання з термінала.
6. Періодично проглядайте list на предмет created_on_tsd: true — перерахунків, створених оператором вручну.