Надходження

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

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

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

Базова адреса 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": "TTN-2026-0778",
  "assignee_token": "22222222-3333-4444-5555-666666666666",
  "name": "Постачання за накладною №778",
  "date": "2026-07-10T08:30:00+03:00",
  "vendor": "ТОВ Постачальник",
  "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": 120, "line_num": 1, "qty_int_only": true,
      "bc_array": [ { "code": "4820000001234", "is_sku": false } ] },
    { "item_id": "SYR-40", "name": "Сир Гауда",
      "qty_plan": 12.6, "line_num": 2,
      "bc_array": [ { "code": "210", "is_sku": true } ] }
  ]
}

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

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

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

{
  "ok": false,
  "error": "validation_failed",
  "recommendation": "повтор item_id у документі: MLK-001"
}

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

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

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

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

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

{
  "ok": true,
  "truncated": false,
  "docs": [
    { "name": "Постачання за накладною №778",
      "external_id": "TTN-2026-0778",
      "status": "Done",
      "docversion": "v1",
      "assignee_token": "22222222-3333-4444-5555-666666666666",
      "created_on_tsd": false,
      "started_at": "2026-07-10T09:05:00+03:00",
      "completed_at": "2026-07-10T10:20:00+03:00" }
  ]
}

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

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

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

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

{ "external_id": "TTN-2026-0778" }

{
  "ok": true,
  "status": "InProgress",
  "started_at": "2026-07-10T09:05:00+03:00",
  "completed_at": null,
  "items_total": 45,
  "items_counted": 30,
  "items_extra": 1,
  "progress_percent": 66,
  "discrepancy_count": 2,
  "settings": { "show_fact_qty": true, "show_progress": true,
                "allow_add_unlisted": false, "show_book_qty": true }
}

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

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

У шапці відповіді є й vendor — постачальник із завдання, — і налаштування документа (settings).

{ "external_id": "TTN-2026-0778" }

{
  "ok": true,
  "external_id": "TTN-2026-0778",
  "status": "Done",
  "docversion": "v1",
  "vendor": "ТОВ Постачальник",
  "created_at": "2026-07-10T08:30:00+03:00",
  "started_at": "2026-07-10T09:05:00+03:00",
  "completed_at": "2026-07-10T10:20:00+03:00",
  "comment_initial": "Прийняти до 11:00, машина під розвантаженням",
  "comment_user": "Дві коробки молока пошкоджені, не прийняв",
  "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": 120, "qty_fact": 118, "line_num": 1, "is_counted": true,
      "bc_array": [ { "code": "4820000001234", "is_sku": false } ] }
  ],
  "extra_rows": [
    { "item_id": "manual-3f2a…", "name": "Кефір 1%",
      "qty_plan": 0, "qty_fact": 6, "line_num": -1, "is_counted": true,
      "bc_array": [ { "code": "4820000007777", "is_sku": false } ] }
  ],
  "photos": [
    { "name": "da75cf11-a672-4965-a545-3556ba4f1c4e",
      "comment": "Пошкоджена коробка, вид збоку" }
  ]
}

Поділ 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": "TTN-2026-0778" }

{
  "ok": true,
  "photos": [
    { "name": "da75cf11-a672-4965-a545-3556ba4f1c4e",
      "thumb_name": "da75cf11-a672-4965-a545-3556ba4f1c4e.thumb",
      "comment": "Пошкоджена коробка, вид збоку",
      "thumb_b64": "/9j/4AAQSkZJRgABAQ…" }
  ]
}

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

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

{ "name": "da75cf11-a672-4965-a545-3556ba4f1c4e" }

{
  "ok": true,
  "name": "da75cf11-a672-4965-a545-3556ba4f1c4e",
  "comment": "Пошкоджена коробка, вид збоку",
  "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:30: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 — приймань, створених оператором вручну.