З чого почати інтеграцію

Спільна частина, однакова для всіх операцій API: базова адреса, авторизація, конверт відповіді та HTTP-коди.

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

Базова адреса й формат

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

Усі операції виконуються методом POST, тіло запиту — JSON у кодуванні UTF-8 із заголовком Content-Type: application/json. На GET сервер відповідає 405.

Повний шлях операції — це базова адреса плюс шлях операції з її розділу. Наприклад, відкриття сесії вивантаження штрих-кодів (/barcodes/session_open) — це https://combopocket.online/v2/exchange/barcodes/session_open.

Авторизація: входу в систему немає

Не потрібно логінитися, отримувати сесії та продовжувати їх.

Замість цього кожен запит несе заголовок X-API-Token з токеном вашої бази — система перевіряє його й сама визначає, до якої бази належать дані.

Токени видаються безкоштовно й автоматично — на сторінці тарифу Free, без оплати.

POST /v2/exchange/barcodes/session_open HTTP/1.1
Host: combopocket.online
Content-Type: application/json
X-API-Token: 11111111-2222-3333-4444-555555555555

Токенів два види, і не переплутайте їх.

Токен бази — у заголовку X-API-Token, один на всю облікову систему.

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

Якщо токен бази не передано або він невідомий, будь-яка операція відповість ok: false з помилкою unauthorized.

Багаторазові запити з неправильним токеном з однієї адреси тимчасово блокуються захистом від перебору.

Конверт відповіді

Результат операції сервер кладе в тіло — у поле ok.

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

ok: true — операцію виконано. ok: false — відмова: причина в полі error, а в recommendation — підказка, що робити далі.

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

HTTP-коди

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

• 200 — запит оброблено, результат дивіться в ok;
• 4xx — запит до обробки не дійшов, виправте запит або токен;
• 5xx — збій на нашому боці.

{
  "ok": false,
  "error": "доступ відключено",
  "recommendation": "Обслуговування бази припинено, зверніться до оператора ComboPocket",
  "block_reason": "оплата не надійшла з 01.07.2026"
}

Зверніть увагу: відмова за змістом даних — це так само HTTP 200 з ok: false. Ваші дані дійшли до обробки, просто результат негативний.

Код 4xx означає, що до обробки справа не дійшла взагалі.

Повтори безпечні

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

У передачі штрих-кодів це забезпечує ваш власний session_id і нумерація порцій, у документах — ваш external_id і мітка версії docversion, у видаленні — ідемпотентність самої операції.

Тому обробку помилок можна починати з простого «повторити ще раз».

Час у полях дати

Дата й час передаються та повертаються у форматі ISO 8601 зі зсувом часового поясу: 2026-07-28T12:00:00+03:00. Зсув — це частина значення, саме він робить момент однозначним. Завдяки цьому ваша облікова система і термінал оператора можуть жити в різних поясах.

Що надсилаєте ви. Приймаються три форми:

Усі три рядки вище позначають один і той самий момент.

Що повертає сервер. Завжди зі зсувом київського поясу. Зсув рахується на момент самої дати, а не на сьогодні: +03:00 для літніх дат, +02:00 для зимових.

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

Перетворювати отриманий момент у свій пояс вручну не треба: більшість мов і платформ роблять це самі — зокрема ПрочитатьДатуJSON у 1С.

Незаповнений час повертається як null — наприклад, completed_at у документа, який ще не завершено.

Окремої операції синхронізації часу немає — вона не потрібна: сервер не зберігає ваш пояс і нічого не «калібрує». Якщо треба звірити власний годинник із серверним, у відповіді ping є поле server_time.

Порядок під'єднання

1. Отримайте токен бази й токени операторів — безкоштовно й автоматично на сторінці тарифу Free.
2. Перевірте зв'язок викликом ping: якщо він не відповідає ok: true, далі йти немає сенсу — проблема в адресі, токені або каналі.
3. Якщо оператор має право додавати товар поза завданням — вивантажте таблицю штрих-кодів. Якщо такий сценарій не потрібен, розділ можна пропустити.
4. Надішліть перше завдання: перерахунок або надходження. Обидва види документів влаштовано однаково.
5. Опитуйте status за розкладом. Статус Done — заберіть результат через download, проведіть його у себе й видаліть документ через delete.