REST API AppsMax v1: опубликовали документацию и OpenAPI

У REST API AppsMax v1 есть единая публичная документация и машиночитаемый OpenAPI JSON. Мы сверили reference с действующими production-маршрутами, валидацией и ответами сервиса, чтобы разработчику не приходилось собирать контракт по отдельным экранам кабинета.

Что вошло в публичную reference

• 21 метод и 12 scopes для ботов, подключений, мини-приложений, сценариев, меню, заявок, кампаний и подписчиков.
• Авторизация через Authorization: Bearer и запасной заголовок X-Api-Token.
• Фильтры, пагинация, структура ошибок, заголовки версии и базовый rate limit.
• Примеры cURL и отдельный OpenAPI 3.0.3 JSON для инструментов разработчика.

Канонический production base URL: https://telegram.appsmax.ru/api/v1. Название рабочего домена историческое и не означает, что API ограничен Telegram: доступные объекты определяются организацией, её проектами и правилами подключённого канала.

Что изменилось в контракте 1.1.0

• Ошибки всегда возвращаются в JSON, в том числе для неизвестного адреса и неверного метода.
• Каждый ответ содержит X-Request-Id: по нему проще найти конкретный запрос, не передавая поддержке токен или персональные данные.
• Создание заявки и кампании поддерживает Idempotency-Key. Безопасный повтор не создаёт дубль, а конфликтующий запрос получает 409.
• API явно различает повреждённый JSON, слишком большое тело, неверный Content-Type и ошибки полей.
• Новый ключ нельзя создать без явного выбора хотя бы одного scope.

Обновлённый контракт проверен на production изолированным набором из 13 HTTP-сценариев: авторизация, scopes, чтение, валидация, создание, безопасный повтор, конфликт, rate limit и отзыв токена. Тестовые записи и ключи после проверки удалены автоматически.

Обновление от 9 августа 2026 года

Текущий OpenAPI-контракт обновлён до 1.1.1. В кабинете путь к настройкам теперь начинается с Данные → Интеграции → API: там отдельно доступны подключение, ключи API, исходящие webhook и журнал.

Для исходящих событий опубликован отдельный webhook-контракт 1.0.0. Он описывает события заявок, HMAC-SHA256 подпись, повторную доставку и границы режимов Bitrix24, n8n, amoCRM через обработчик и собственной системы. Webhook не добавлен в REST OpenAPI, потому что направление вызова другое.

Что можно делать через API

Интеграция может читать проекты и рабочие объекты AppsMax, создавать заявки с обязательным bot_id, синхронизировать теги, работать с подписчиками и создавать кампании. Создание кампании и её запуск намеренно разделены на два действия: сначала система получает запись и параметры, затем интеграция отдельно вызывает запуск после собственных проверок.

curl --request GET 
  --url https://telegram.appsmax.ru/api/v1/me 
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Метод GET /me помогает проверить организацию токена, scopes и фактический индивидуальный лимит до начала обмена данными.

Границы, которые мы не прячем

• Это API платформы AppsMax, а не официальный API MAX или Telegram.
• REST API предназначен для server-to-server интеграций. Секретный токен нельзя помещать в браузерный JavaScript, мобильное приложение, публичный репозиторий или URL.
• На 3 августа 2026 года REST API входит в тариф «Профи» либо включается по индивидуальному праву.
• Официальные Python, PHP или JavaScript SDK AppsMax сейчас не заявлены: достаточно обычного HTTPS-клиента и OpenAPI.
• Исходящие webhook описаны отдельно от REST API: используйте публичный контракт webhook 1.0.0 и не смешивайте его с OpenAPI.
• Наличие API-метода не отменяет согласие адресата, требования закона и правила конкретного мессенджера.

Где открыть документацию

Полная reference доступна на странице REST API AppsMax v1 для разработчиков. Рядом можно посмотреть обзор готовых интеграций и API и актуальные тарифы.

Если API уже включён для вашей организации, токен создаётся в кабинете: Данные → Интеграции → API. Передавать рабочий токен в обычном письме или чате поддержки не нужно.

Документация, OpenAPI 1.1.1 и webhook-контракт 1.0.0 повторно сверены с production-контуром 9 августа 2026 года. Материал описывает доступный технический интерфейс и не обещает совместимость с любой внешней системой или коммерческий результат.

Если хотите сначала посмотреть механику вживую, откройте Товарища М. для групп и сообществ или Екатерину М. для бизнес-сценариев: по вопросам в ботах мы лучше понимаем, какие задачи нужно разбирать подробнее.