Быстрый старт
В веб-панели создайте стороннее приложение для нужной компании. Скопируйте App ID и App Secret, а при необходимости итогового результата укажите необязательный Callback URL. Engine создаёт запись в центре уведомлений для каждого активного подходящего пользователя компании и пытается отправить системный Push только на подходящие зарегистрированные устройства.
Адрес и аутентификация
Среды API:
- Тестовая: https://aim-api-test.proton-system.com
- Рабочая: https://aim-api.proton-system.com
Каждый межсерверный JSON-запрос должен передавать Authorization: Basic Base64(KEY:SECRET) через HTTP Basic Authentication, где KEY — это App ID, а SECRET — App Secret:
Endpoint: POST /openapi/v1/notifications.
curl --request POST 'https://<your-engine-host>/openapi/v1/notifications' \
--header 'Authorization: Basic <Base64(AppID:AppSecret)>' \
--header 'Content-Type: application/json' \
--data '{"requestId":"order-20260819-001","title":"Заказ выполнен","body":"Ваш заказ выполнен.","imageUrls":["https://cdn.example.com/order/001-1.webp","https://cdn.example.com/order/001-2.webp"]}'Контракт запроса
Строгий JSON принимает обязательные поля requestId, title и body, а также необязательное imageUrls. Если imageUrls отсутствует, равен null или [], изображений нет; иначе передайте 1-9 URL в порядке отображения. Каждое значение обрезается, должно быть уникальным, быть абсолютным URL HTTPS без имени пользователя и пароля и содержать не более 2048 символов Unicode. Любой неверный URL отклоняет запрос целиком. Engine хранит URL, но не загружает, не проверяет, не проксирует и не кэширует изображения. Размер тела не превышает 256 KiB, длина requestId — 128 символов Unicode, title — 100, body — 1000. На каждый App ID действует лимит 10 запросов в минуту и 100 в час.
Повтор с теми же requestId, title, body и упорядоченным imageUrls возвращает исходный сохранённый результат; после обработки его status может быть SUCCESS, PARTIAL_SUCCESS или FAILED, а не ACCEPTED. Повторное использование requestId с другим содержимым или порядком изображений даёт IDEMPOTENCY_CONFLICT.
Ответ о принятии
Корректный запрос возвращает HTTP 202:
{
"requestId": "order-20260819-001",
"notificationId": "00000000-0000-0000-0000-000000000001",
"status": "ACCEPTED"
}ACCEPTED означает, что Engine сохранил запрос для отправки, но не подтверждает показ уведомления через APNs/FCM на устройстве.
Результат Callback
Если настроен Callback URL, Engine отправляет итоговый результат:
{
"requestId": "order-20260819-001",
"status": "PARTIAL_SUCCESS",
"recipientCount": 8,
"pushAcceptedCount": 1,
"pushFailedCount": 1
}recipientCount — число пользователей-получателей в центре уведомлений. pushAcceptedCount и pushFailedCount — количество пакетов Push Outbox, а не пользователей или устройств и не подтверждение показа системного баннера.
Проверка Callback
Каждая проверка Callback из панели администратора отправляет отдельное тестовое событие:
{
"requestId": "callback-test-<unique-id>",
"status": "SUCCESS",
"recipientCount": 1,
"pushAcceptedCount": 1,
"pushFailedCount": 0,
"test": true
}Если test равно true, проверьте структуру и верните 2xx, но не сопоставляйте тестовое событие с отправленным запросом уведомления и не изменяйте состояние бизнес-доставки. Счётчики содержат фиксированные тестовые значения, а не число реальных получателей или пакетов Push Outbox.
Итоговый status: SUCCESS, PARTIAL_SUCCESS или FAILED. Подтвердите получение любым ответом 2xx; иначе повторы выполняются через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов и 24 часа. Сейчас HMAC-подписи нет: используйте HTTPS, сверяйте requestId для нетестовых результатов, ограничивайте доступ и обрабатывайте Callback идемпотентно.
Ошибки
| HTTP | Code | Значение |
|---|---|---|
| 400 | INVALID_REQUEST | Ошибка Content-Type, JSON, размера или полей. |
| 401 | INVALID_APP_CREDENTIALS | Неверные App ID или App Secret. |
| 403 | APPLICATION_INACTIVE | Приложение или компания неактивны. |
| 409 | IDEMPOTENCY_CONFLICT | requestId повторён с другим содержимым. |
| 429 | RATE_LIMITED | Превышен лимит приложения. |
| 503 | NOTIFICATION_UNAVAILABLE | Сервис временно недоступен. |
Безопасность и область доставки
Mobile client принимает не более 5 MiB на изображение, а тайм-аут всей операции загрузки изображения составляет 10 секунд. Client не следует редиректам 3xx, поэтому каждый URL должен возвращать изображение напрямую.
App ID и App Secret предназначены только для связи сервер-сервер. Не помещайте их в браузер, мобильное приложение, открытый репозиторий, URL или клиентское хранилище. При утечке сбросьте App Secret. Каждый активный подходящий пользователь связанной компании получает запись в центре уведомлений и учитывается в recipientCount. Системный Push выполняется только для активного PushInstallation, разрешающего категорию BUSINESS, и не гарантирует системный баннер на каждом устройстве. imageUrls показываются только в detail уведомления и не входят в payload Push или Callback. title и body должны оставаться полными и понятными без изображений. Ошибка загрузки или отображения изображения не изменяет статус accepted, Callback или Push. Mobile client загружает изображения напрямую из публичного CDN, поэтому используйте URL без аутентификации и Cookie, сохраняйте их доступными не менее 90 дней и учитывайте, что CDN получает IP пользователя, время запроса и User-Agent. Для стабильной истории используйте immutable object URL.