Заявки через REST API

01 / Доступ

Подготовьте ключ и своего бота

Для списка и одной заявки ключу нужно право applications:read; для создания и изменения тегов — applications:write. Владелец выдаёт отдельный ключ с нужными правами в разделе «Данные → API и интеграции». Если ключ уже действует, проверьте права через GET /me. Как безопасно ввести адрес и ключ для первого запроса. REST API доступен по действующим условиям начиная с тарифа «Автоматизация».

bot_id — числовой идентификатор уже подключённого бота той же организации, а не слово BOT_ID. Уточните его в доступных данных проекта или через разрешённый метод ботов API. Чужой или несуществующий идентификатор не подойдёт. Базовый адрес /api/v1 и ключ возьмите из текущего кабинета вашего контура; старый домен из архивной инструкции не используйте.

02 / Чтение

Получите список по страницам

GET /applications возвращает только заявки доступной организации. Параметры page и per_page выбирают страницу и размер: по умолчанию 20, максимум 100 записей на страницу. Фильтры включают bot_id, status[], source[], tag и даты created_from/created_to. Для сортировки используйте sort=created_at или sort=submitted_at и direction=asc или desc; по умолчанию применяется created_at desc. Укажите только параметры, которые нужны задаче.

# После безопасного ввода адреса и ключа по инструкции первого запроса:
printf 'header = "Authorization: Bearer %s"\n' "$APPSMAX_API_TOKEN" | \
  curl --fail-with-body --config - -H 'Accept: application/json' \
  "$APPSMAX_API_BASE/applications?page=1&per_page=20"

Базовый адрес заканчивается на /api/v1. В ответе data содержит заявки, а links и meta помогают пройти страницы. Первые 20 записей не равны всему списку. Для одной известной заявки используйте GET /applications/{id}; недоступный или отсутствующий объект вернёт 404.

03 / Создание

Создайте одну согласованную тестовую заявку

POST /applications требует bot_id и право applications:write. Дополнительно можно передать title, contact, channel, source и payload по текущему OpenAPI. Верхнеуровневое status не поддерживается: AppsMax задаёт начальный статус сам.

{"bot_id": 123, "title": "Учебная заявка API"}

Перед отправкой придумайте новый случайный Idempotency-Key для этой одной заявки: от 1 до 128 символов. Первый символ — латинская буква или цифра; дальше допустимы латинские буквы, цифры и знаки ._:-. Сохраните ключ повтора, точное тело запроса и результат. При повторе используйте тот же API-ключ: другой ключ доступа, даже в той же организации, образует отдельную область проверки повторов и может создать вторую заявку. Новый ключ повтора нужен для следующей отдельной заявки. Не включайте в него личные данные; секрет API-ключа не записывайте в журнал операции.

05 / Теги

Синхронизируйте только нужный набор тегов

POST /applications/{application}/tags требует applications:write и непустой массив tags — до 20 названий по текущему контракту. Этот метод заменяет набор тегов заявки переданным списком. Сначала прочитайте имеющиеся теги и решите, какие должны остаться. Отправка одного нового тега отдельно удалит прежние теги из связей этой заявки.

Входной объект должен принадлежать вашей организации. Для первоначальной проверки пути заявок изменение тегов не требуется.

06 / Проверка

Сверьте результат и завершите тест

После разрешённого создания прочитайте GET /applications/{id} и сверьте data.id, data.bot_id, data.status, data.source, контакты data.contact, ответы data.answers и теги data.tags. Название, если оно задано, находится в data.form_meta.title. При 401 проверьте ключ; при 403 — право и доступ к организации; при 422 — поля тела, в том числе bot_id; при 429 учитывайте ограничение частоты. Для разбора сохраните время, метод, код и X-Request-Id, но не сам ключ и не личные данные заявки.

Публичный API не обещает удаление заявки. Договоритесь заранее, как в вашем тестовом контуре пометить или обработать учебную запись штатным способом. Как искать ошибку в журнале; полный OpenAPI для разработчика. Если нужен готовый путь без собственного кода, выберите интеграцию AppsMax.