АРМ "Розничная торговля"→Полезные статьи для АРМ→Открытый API АРМ «Розничная торговля»

Открытый API АРМ «Розничная торговля»

ChatGPT Image 30 янв. 2026 г., 19_16_48

API АРМ «Розничная торговля» – это HTTP-интерфейс для интеграторов: он позволяет получать данные из базы данных через запросы из JSON. Это удобно, когда нужно «подружить» учёт/склад с сайтом, CRM, ERP или любым внешним сервисом.

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

Быстрая навигация по мануалу (ссылка на разделы)

Зачем подключать это API

Наиболее типичные сценарии интеграции выглядят так (и да, почти все они сводятся к «синхронизировать справочники»):

  • Каталог товаров: выгрузка номенклатуры, цен, единиц измерения, категорий для сайта/маркетплейса.
  • Поставщики и контрагенты: синхронизация справочников по бухгалтерии/ERP или CRM.
  • Дисконтные карты и промо: подтянуть скидки/программы лояльности во внешние системы.
  • Отчеты: получать продажи, чеки, отмены, остатки, товары, итоги и т.д. в JSON.
  • Касса: контроль инкассаций/внесений, сведение по кассовым операциям.
  • Администрирование: унифицировано читать/обновлять пользователей и другие справочники без ручного экспорта.

Официальное описание возможностей и логики построения API: «Об API».

Как устроено API: один endpoint + method

В документации это объясняется просто: вы отправляете POST на один и тот же endpoint, а действие определяете полем method. Параметры передаются в params, служебные поля (например, локальный пользователь) meta.

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

С чего начать интеграцию (практический маршрут по документации)

  1. Прочтите «Об API», чтобы сразу понять модель «один endpoint+method»: раздел «Об API».
  2. Сделайте первый тестовый запрос service.ping, чтобы проверить доступность endpoint и связь с базой (после авторизации): Первый запрос: service.ping.
  3. Выберите способ авторизации: Basic Auth в заголовке или (чаще) логин/пароль в JSON: обзор авторизации.
  4. Проверьте формат запроса/ответа, чтобы не ловить ошибки на ровном месте: структура запроса да структура ответа.
  5. Начните с чтения справочников (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 должно быть в вашем коде.