Відкрите API АРМ «Роздрібна торгівля»

API АРМ «Роздрібна торгівля» — це HTTP-інтерфейс для інтеграторів: він дозволяє отримувати дані з бази даних через запити з JSON. Це зручно, коли треба «подружити» облік/склад із сайтом, CRM, ERP або будь-яким зовнішнім сервісом.

Ключова особливість: API зроблено як один «endpoint«, а потрібна дія задається полем method у JSON.

Швидка навігація по мануалу (посилання на розділи)

Для чого підключати це API

Найтиповіші сценарії інтеграції виглядають так (і так, майже всі вони зводяться до «синхронізувати довідники»):

Каталог товарів: вивантаження номенклатури, цін, одиниць виміру, категорій для сайту/маркетплейсу.
Постачальники та контрагенти: синхронізація довідників із бухгалтерією/ERP або CRM.
Дисконтні картки та промо: підтягнути знижки/програми лояльності у зовнішні системи.
Звіти: отримувати продажі, чеки, скасування, залишки, рух товарів, підсумки тощо в JSON.
Каса: контроль інкасацій/внесень, зведення по касових операціях.
Адміністрування: уніфіковано читати/оновлювати користувачів та інші довідники без «ручного експорту».

Офіційний опис можливостей і логіки побудови API: «Про API».

Як влаштовано API: один endpoint + `method`

У документації це пояснюється просто: ви надсилаєте POST на один і той самий endpoint, а дію визначаєте полем method. Параметри передаються в params, службові поля (наприклад, локальний користувач) — у meta.

Базові терміни, щоб не вигадувати «свою реальність» під час інтеграції: «Базові поняття».

З чого почати інтеграцію (практичний маршрут по документації)

Прочитайте «Про API», щоб одразу зрозуміти модель «один endpoint + method»: розділ «Про API».
Зробіть перший тестовий запит service.ping, щоб перевірити доступність endpoint і зв’язок із базою (після авторизації): «Перший запит: service.ping».
Виберіть спосіб авторизації: Basic Auth у заголовку або (частіше) логін/пароль у JSON: огляд авторизації.
Перевірте формат запиту/відповіді, щоб не ловити помилки на рівному місці: структура запиту та структура відповіді.
Почніть з читання довідників (get.*) і лише потім переходьте до змін (set.*): get.*, set.*.

Авторизація: що важливо знати до першого «чому не працює?»

1) Basic Auth (Header)

Класичний варіант: логін/пароль передаються в заголовку Authorization. Деталі й приклад curl: Basic Auth.

2) Авторизація в JSON (POST) — рекомендовано

Надійний практичний варіант: логін/пароль їдуть прямо в JSON тілі запиту, і проксі/балансувальники «випадково» не з’їдають заголовки. Опис і формат: «Авторизація в JSON (POST)».

3) `meta.user_card`: локальний користувач

Окрім логіна/пароля, API може вимагати локального користувача з вашої бази (поле meta.user_card). Це потрібно, щоб коректно вести журнал дій користувачів у системі. Пояснення «навіщо» і «що саме передавати»: meta.user_card (локальний користувач).

Формат запитів і відповідей

Структура запиту

Опис полів (що куди класти і які поля очікуються) зібрано тут: «Структура запиту».

Типовий шаблон (для розуміння логіки, не як догма):

{
  "auth": { "login": "<LOGIN>", "password": "<PASSWORD>" },
  "method": "get.products.list",
  "params": { "limit": 50, "offset": 0 },
  "meta": { "user_card": "<USER_CARD>", "client_name": "MyApp", "client_version": "1.0" },
  "id": "req-001"
}

Структура відповіді

Формат результату (де шукати result, як виглядають error, як читати ok) описано тут: «Структура відповіді».

Коди помилок

Коли API повертає помилку, найкорисніше мати під рукою довідник кодів: «Довідник кодів помилок».

Пагінація, фільтри, сортування і пошук: щоб не тягнути «весь світ» одним запитом

Для списків (товари, контрагенти, чеки, операції тощо) майже завжди потрібні:

пагінація (limit/offset)
фільтри (щоб брати лише потрібні записи)
сортування (щоб стабільно «доганяти» синхронізацію)
пошук (наприклад, через параметр q)

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

Кодування (UTF‑8 ↔ cp1251): типова «дрібниця», яка ламає все

Якщо у вас «кракозябри» у назвах товарів або контрагентах, це майже завжди питання кодування. У мануалі є окремий розділ з поясненням, як працювати з UTF‑8 та cp1251: «Кодування (UTF‑8 ↔ cp1251)».

Що саме «вміє» API: основні групи методів і де їх брати

1) Сервісні методи: перевірка API і службова інформація

Це стартова точка для діагностики та «розвідки»: «Сервісні методи».

service.schema — показує схему/дозволені таблиці, корисно для розуміння «що взагалі доступно»: опис методу.
service.table.describe — опис колонок таблиці (зручно для мапінгу полів під інтеграцію): опис методу.

2) Довідники: перегляд (get.*)

Усі методи цього розділу повертають дані без змін у базі. Це те, з чого майже завжди починають інтеграції: «Довідники: перегляд (get.*)».

Приклад найбільш «народного» методу для інтеграцій каталогу: get.products.list — список товарів.

3) Довідники: зміни (set.*)

Методи цього розділу змінюють дані (створення/оновлення/видалення/відновлення). Тут варто бути дисциплінованими з правами доступу, логуванням і тестовим середовищем: «Довідники: зміни (set.*)».

Приклад методу для оновлення товару: set.products.update — оновлення товару.

4) Звіти (get.reports.*)

Звіти повертають дані, розраховані на сервері (як у десктопній програмі), але у вигляді JSON. Для більшості потрібен діапазон дат (date_from/date_to), а частина звітів має обмеження по календарному року. Розділ: «Звіти (get.reports.*)».

Один з найпотрібніших звітів для інтеграцій аналітики: get.reports.sales — продажі/повернення (рядки продажів).

5) Каса та інкасації

Окремий блок методів для роботи з касами та операціями інкасації/внесення коштів: «Каса та інкасації».

Типовий приклад запиту для журналу операцій: get.cash.operations.list — інкасації та внесення.

Де «шукати відповідь», коли терміново треба знайти метод

Пошук по документації (по всьому тексту сторінок у лівому меню): пошук.
Мокапи — готові JSON-приклади запитів/відповідей, корисні як «еталон формату»: мокапи.
FAQ — якщо питання типове, воно вже могло трапитися комусь до вас: FAQ.

Кілька практичних порад, щоб інтеграція була схожа на інженерію, а не на шаманство

Починайте з service.ping: це найшвидший спосіб відокремити «мережа/endpoint/авторизація» від «помилка в методі».
Працюйте від read до write: спочатку налаштуйте get.*, перевірте мапінг і кодування, потім беріться за set.*.
Завжди ставте id у запиті: з ним легше трекати, який саме запит відповів помилкою, особливо в чергах/батчах.
Не забувайте про meta.user_card, якщо методи змінюють дані або потрібне коректне логування.
Не тягніть «все і одразу»: використовуйте пагінацію/фільтри/пошук, інакше отримаєте повільну синхронізацію та зайве навантаження.
Для звітів плануйте роботу з датами: частина звітів може мати логіку по роках, тому валідація date_from/date_to має бути у вашому коді.