Партнёрский код 36375
API ЕСП для интеграторов
Разбор публичной части REST API сервиса CashDesk (ЕСП) — того же API, который стоит за api.ao-esp.ru. Здесь только методы, рассчитанные на внешних вендоров кассового ПО и интеграторов: проверка лицензии ЕСМ, каталог дистрибутивов и документации, справочник ПМСР, FAQ. Внутренние административные методы личного кабинета (биллинг, раскатка обновлений, управление лицензиями) в эту документацию намеренно не включены.
Общие сведения
| Параметр | Значение |
|---|---|
| Базовый адрес | https://api.ao-esp.ru |
| Префикс методов из этого раздела | /api/v1/cashdesk/... |
| Формат данных | JSON, Content-Type: application/json |
| Авторизация | Authorization: Bearer <JWT> — токен личного кабинета ЕСП |
| Swagger UI | api.ao-esp.ru/api/v1/cashdesk/swagger-ui/index.html |
Авторизация
Почти все методы (кроме получения списка вендоров) закрыты схемой jwtAuth — это тот же Bearer-токен, который выдаётся при входе в личный кабинет ЕСП (lk.ao-esp.ru). Отдельного статичного API-ключа для внешних систем в этой версии спецификации не описано: чтобы дергать методы программно, нужна действующая сессия — токен получают через форму логина ЛК и обновляют по мере истечения. Если вам нужен постоянный сервисный доступ без интерактивного логина, уточните у ЕСП порядок выдачи технической учётной записи.
Формат ошибок
При ошибке (HTTP 400) тело ответа — объект RestErrorInfo:
Отдельное внимание — нестандартным кодам авторизации, специфичным для этого API:
| Код | Что значит |
|---|---|
| 401 | Токен недействителен и обновить его уже нельзя — нужно заново авторизовать пользователя (повторный логин). |
| 403 | Не хватает прав на метод, либо не прошла валидация токена. |
| 498 | Токен истёк, но ещё может быть обновлён — нужно выполнить REFRESH и повторить запрос. |
1. Вендоры ККТ и проверка лицензии ЕСМ
Эта группа методов решает конкретную задачу: кассовое ПО стороннего вендора (драйвер, POS-система) хочет программно узнать, куплена ли на конкретной кассе лицензия ТС ПИоТ/ЕСМ — не отправляя пользователя в личный кабинет. Идентифицировать кассу можно тремя способами: по паре «ИНН + заводской номер ККТ», по паре «ИНН + РНМ», либо просто по номеру фискального накопителя.
Получение списка вендоров. Справочный метод: возвращает список кодов вендоров ККТ, которые знает система (используются в других методах в поле vendor), человекочитаемое название и ссылку на иконку. Удобно, чтобы не хардкодить список у себя и подтягивать актуальные названия/иконки.
Известные коды вендоров (enum)
Пример ответа (200)
Проверка лицензии на ЕСМ для одной кассы. Ключевой метод для вендоров: по идентификаторам кассы возвращает, активна ли сейчас подписка ТС ПИоТ и до какого числа. Заполните один из вариантов идентификации: либо inn + znid, либо inn + rnm, либо просто fnid.
Тело запроса — VendorCheckLicenseRequest
| Поле | Тип | Описание |
|---|---|---|
| inn | string | ИНН организации |
| znid | string | Заводской номер ККТ |
| rnm | string | Регистрационный номер ККТ в ФНС |
| fnid | string | Номер фискального накопителя |
Запрос
Ответ (200) — VendorLicenseInformation
licenseActiveTill в формате yyyy-MM-dd HH:mm:ss; будет null, если licenseActive: false.
Пакетная проверка лицензий. То же самое, но сразу для списка касс — удобно, если у вендора тысячи устройств и гонять по одному запросу на кассу нерационально. В теле — массив таких же объектов, что и в одиночной проверке.
Запрос — массив VendorCheckLicenseRequest
Ответ (200) — массив VendorBatchLicenseInformation
Поле request в каждом элементе ответа — это тот же объект, что был передан в запросе (для сопоставления, какой ответ к какой кассе относится), а license — сам результат проверки.
2. Каталог ПО, дистрибутивы и совместимость
Методы этой группы отвечают на вопрос «а где скачать нужный дистрибутив/документацию под конкретного вендора и ОС» и «какое кассовое ПО вообще поддерживается». По сути это программный доступ к тому же самому каталогу, что показан на странице «Файлы для скачивания».
Ссылка на актуальный дистрибутив ЕСМ и документацию. Передаёте вендора кассы и ОС — получаете прямую ссылку на установщик ЕСМ этой версии и (если есть) на документацию по конкретному ПО кассира.
Тело запроса — ESMPackageDownloadRequest
| Поле | Тип | Описание |
|---|---|---|
| vendor | enum | Код вендора (см. список выше) |
| os | enum | Операционная система — см. список ниже |
| softwareCode | string | Код ПО кассира — нужен, если требуется ссылка именно на документацию к нему |
Значения os: WINDOWS WINDOWS_7 LINUX32 LINUX64 UBUNTU LINUX_TINY EVOTOR MSPOS ANDROID LINUX_RPM_X86_64 LINUX_RPM_I686 LINUX_DEB_AMD64 LINUX_DEB_ARM64 LINUX_DEB_ARMHF LINUX_DEB_I386 LINUX_RUN_TINYCORE8 LINUX_RUN_UBUNTU22
Запрос
Ответ (200) — ESMPackageInfo
Список бета-версий пакета. Тот же запрос, что и у packagelink (ESMPackageDownloadRequest), но в ответе — массив ESMPackageInfo по всем доступным бета-сборкам для указанных вендора/ОС. Полезно, если вы тестируете интеграцию заранее на пре-релизных версиях ЕСМ.
Весь каталог ссылок целиком. Без параметров — возвращает сразу по всем связкам «вендор × ОС» ссылку на ЕСМ и список ПО с документацией. Удобно один раз забрать целиком и кешировать у себя, вместо того чтобы дёргать packagelink под каждую комбинацию отдельно.
Ответ (200) — массив ESMPackageLinks
Прочая документация. Документы, которые не привязаны к конкретной паре «вендор + ПО» и не попали в основной каталог (например, общие инструкции, регламенты, whitepaper'ы).
Ответ (200) — массив SoftwareOthersDocLink
Таблица совместимости ПО. По каждому вендору — список поддерживаемого кассового ПО (тип модели, минимальная версия, список ОС) и отметка comingSoon, если поддержка ожидается, но ещё не готова.
| Параметр | В | Описание |
|---|---|---|
| mode | query, необязательный | DOWNLOAD_SOFTWARE (по умолчанию) — режим для страницы загрузки, CHECK_COMPATIBILITY — режим для проверки совместимости |
Ответ (200) — массив SoftwareCompatibility
Заявка «не нашёл нужное ПО». Если пользователь (или ваша интеграция от его лица) не находит в каталоге нужную связку вендор/ПО/ОС, этот метод фиксирует заявку на добавление поддержки — параметры передаются строкой в query, без тела запроса.
| Параметр | Обязательный | Описание |
|---|---|---|
| vendorName | да | Название вендора (строкой, как ввёл пользователь) |
| softwareName | да | Название нужного ПО |
| os | нет | Операционная система |
3. Справочник ПМСР (программно-механические средства регистрации)
ПМСР — используемый ЕСП термин для кассового оборудования/ПО, которое можно подключать через ТС ПИоТ. Эта группа методов — read-only справочники: категории, элементы справочника и таблица инструкций к ним.
Категории ПМСР. Возвращаются только те категории, в которых есть хотя бы один доступный элемент — удобно сразу строить фильтр/меню без пустых пунктов.
Элементы справочника ПМСР, у которых заполнены внешние инструкции (файл, ссылка на сайт или видео) — то есть те позиции, по которым уже есть готовый мануал для пользователя.
Ответ (200) — массив PmsrDictionaryItem
Элементы ПМСР с флагом «совместимость партнёра». Тот же формат ответа (PmsrDictionaryItem), но отфильтрован по элементам, отмеченным как совместимые в рамках партнёрской программы — обратите внимание на поле partnerCompetencies.
4. Документация и FAQ для интеграторов
Читающие методы каталога документации и базы вопрос-ответ, которые ЕСП показывает интеграторам в личном кабинете. Полезны, если хотите вывести тот же контент на своей стороне (например, во встроенной справке собственного продукта).
Список документации для интеграторов. Каждая запись — название, группа, дата загрузки и прямая ссылка на файл. Поле integratorFilter показывает, для кого предназначен документ.
Ответ (200) — массив IntegratorDocInfo
Значения integratorFilter: ANY ONLY_INTEGRATOR NOT_INTEGRATOR — определяют, кому документ должен показываться в интерфейсе.
Список FAQ для интеграторов. Вопрос/ответ плюс несколько флагов фильтрации по типу личного кабинета и режиму (демо/боевой), чтобы показывать пользователю только релевантные пункты.
Ответ (200) — массив IntegratorFaq
cabinetTypes: LKK (личный кабинет клиента), LKP (личный кабинет партнёра), LKM (личный кабинет менеджера) — в каком личном кабинете вопрос должен отображаться.
Что осталось за скобками
В спецификации ещё около сотни методов с тегом ADMIN | ... — управление пробными и предоплаченными лицензиями, раскатка версий ЕСМ через CI/CD, перенос касс между филиалами, мониторинг по ИНН и т.п. Это внутренняя механика личного кабинета ЕСП, требующая административных прав, и мы намеренно не публикуем её здесь — обратитесь напрямую в ЕСП, если для интеграции нужны возможности за пределами этого списка.