REST API: безопасный первый запрос

Быстрый старт

1. Откройте в кабинете AppsMax раздел Данные → Интеграции → API.
2. Создайте токен только с теми scopes, которые нужны интеграции. Скопируйте значение сразу: секрет не предназначен для повторного показа.
3. Сохраните токен в secret-хранилище серверного приложения. Не помещайте его в публичный JavaScript, мобильное приложение, репозиторий или URL.
4. Проверьте контекст токена методом GET /me.

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

Успешный ответ содержит объект data с организацией и сведениями о токене: его именем, scopes, индивидуальным rate limit и временем последнего использования.

Авторизация и формат

Рекомендуемый способ — заголовок Authorization: Bearer YOUR_API_TOKEN. Для совместимости поддерживается запасной заголовок X-Api-Token: YOUR_API_TOKEN. Токен в query string не поддерживается и не должен использоваться.

• Запросы и ответы: application/json.
• Текущая версия возвращается в заголовке X-Api-Version: v1.
• Все методы, включая /ping, требуют действующий API-токен.
• Токен всегда ограничен своей организацией; чужой объект возвращается как недоступный или не найденный.

Scopes доступа

Для нового подключения выбирайте минимально необходимые права. Токен без заданного списка scopes технически получает полный доступ в пределах организации, поэтому для новых интеграций такой режим не рекомендуется.

Методы REST API v1

Ниже перечислен весь публичный набор на дату проверки. Идентификаторы в фигурных скобках — целые числа. Для коллекций обычно действует per_page от 1 до 100; у интерактивного меню верхняя граница 200.

Примеры запросов

Получить ботов

curl --request GET \
  --url 'https://telegram.appsmax.ru/api/v1/bots?driver=max&per_page=50' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Создать заявку

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

curl --request POST \
  --url https://telegram.appsmax.ru/api/v1/applications \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "bot_id": 42,
    "source": "rest_api",
    "title": "Заявка с сайта",
    "channel": "website",
    "contact": {
      "name": "Тестовый контакт",
      "phone": "+70000000000",
      "email": "test@example.invalid"
    },
    "payload": {
      "comment": "Проверка интеграции"
    }
  }'

Ответ на успешное создание — 201 Created. В нём возвращаются идентификатор, бот, источник, статус, контакт, ответы, метаданные формы, теги и временные метки.

Добавить теги заявке

curl --request POST \
  --url https://telegram.appsmax.ru/api/v1/applications/123/tags \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"tags":["сайт","повторный контакт"]}'

Создать и затем запустить кампанию

Создание и запуск — два разных действия. Сначала создаётся запись кампании:

curl --request POST \
  --url https://telegram.appsmax.ru/api/v1/campaigns \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "bot_id": 42,
    "title": "Сервисное уведомление",
    "content": "Ваш запрос обработан.",
    "channel": "max"
  }'

После проверки аудитории, содержания, согласий и правил канала черновик запускается отдельным методом:

curl --request POST \
  --url https://telegram.appsmax.ru/api/v1/campaigns/321/run \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Важно: наличие API-метода не отменяет требования закона, согласия адресата и ограничения мессенджера. Массовые маркетинговые сообщения в личные чаты MAX доступны только при отдельном разрешении площадки.

Пагинация и фильтры

Коллекции Laravel возвращают массив data, ссылки пагинации и блок meta. Используйте URL следующей страницы из ответа либо параметр page. Значение per_page ограничивается сервером.

• Заявки: status[], source[], created_from, created_to, bot_id, tag, sort=created_at|submitted_at, direction=asc|desc.
• Кампании: bot_id, status[], type[], created_from, created_to, q, sort=created_at, direction.
• Подписчики: channel[], status[], bot_id, tag, group_id, q, даты и направление сортировки.

Ошибки, версия и лимиты

Основные API-ошибки имеют единый объект error:

{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed.",
    "details": {
      "fields": {
        "bot_id": ["The bot id field is required."]
      }
    }
  }
}

Базовый лимит — 60 запросов в минуту на токен. Для конкретного токена администратор может установить другое значение; фактический лимит виден в GET /me и заголовках X-RateLimit-*. Создание и запуск кампаний дополнительно защищены отдельными лимитами. При 429 используйте паузу и exponential backoff, не увеличивайте burst.

Исходящие webhook AppsMax

Webhook нужен, когда AppsMax должен сам сообщить вашей системе о новой заявке, изменении данных или статуса. Это отдельный механизм: REST API вызываете вы, а webhook отправляет AppsMax.

• Приёмник должен использовать HTTPS и проверять заголовок события и HMAC-SHA256 подпись по исходному телу запроса.
• Доставка выполняется как минимум один раз, поэтому обработчик должен безопасно распознавать повтор одного события.
• Прямой режим Bitrix24 поддерживает собственный ограниченный набор событий; amoCRM подключается через внешний обработчик, который выполняет авторизацию и вызов amoCRM.

Стабильная схема событий, payload, подписи, повторов и ошибок опубликована отдельно: контракт исходящих webhook 1.0.0. REST-методы по-прежнему описывает OpenAPI 1.1.1.

Безопасность и честные ограничения

• Только сервер-сервер. Не встраивайте токен в браузерный код. Произвольные cross-origin запросы из чужого сайта не являются поддерживаемым способом интеграции.
• Минимальные scopes. Разделяйте токены чтения и записи, если интеграция допускает это.
• Ротация. Отзывайте неиспользуемые токены и создавайте новый после подозрения на раскрытие.
• Персональные данные. Передавайте только необходимые поля, определите роли оператора и обработчика, сроки хранения и порядок удаления.
• Кампании. До запуска проверяйте содержание, аудиторию, основание коммуникации и правила конкретного канала.
• Webhooks. Исходящие события не входят в REST OpenAPI: для них действует отдельный публичный контракт webhook 1.0.0.
• Нет публичного SDK. Официальные Python, PHP, JavaScript или другие SDK AppsMax сейчас не заявлены. Используйте обычный HTTPS-клиент и OpenAPI.

Когда REST API не нужен

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

Для Bitrix24, n8n и других систем сначала проверьте обзор интеграций и доступные настройки кабинета: индивидуальная разработка требуется не всегда.