Copy page

Разное

Мониторинг операций

Описание метода

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

По возвращаемым данным можно настроить дашборды и алерты — например, «доля ошибок по передаче заказов больше 5% за последние 60 минут» или «нет ни одного вызова кассы за последние 60 минут». Это позволяет узнать о проблеме раньше, чем ее заметят бизнес-пользователи или клиенты.

Если статистика нужна только в интерфейсе Mindbox — используйте раздел Мониторинг интеграций.

---

Предварительная настройка

Создайте операцию мониторинга в разделе Кампании → Операции (как создать операцию V3) со следующими параметрами:

• Системное имя — произвольное, используется в URL запроса;
• Для точек интеграции — точка, на которой будет работать метод, используется в URL запроса;
• Шаг — Мониторинг → Статистика по операциям.

Формат запроса

URL и параметры

POST на адрес:

Code

https://api.mindbox.ru/v3/operations/sync?endpointId={`Идентификатор точки интеграции`}&operation={Системное имя операции мониторинга}

Заголовки

Заголовок	JSON	XML	Обязательное
Content-Type	application/json; charset=utf-8	application/xml; charset=utf-8	✅
Accept	application/json	application/xml	✅
Authorization	SecretKey {секретный_ключ_точки_интеграции}		✅

Тело запроса

В массив operations можно передать несколько фильтров: статистика возвращается отдельно для каждого. Фильтры комбинируются:

Содержимое элемента	Что вернется
systemName + endpointId	Статистика по операции в конкретной точке интеграции
systemName	Статистика по операции на всех точках интеграции, у которых были вызовы за последние 60 минут
endpointId	Список операций, у которых были вызовы в переданной точке интеграции за последние 60 минут
Пустой массив "operations":[] или пустой запрос	Статистика по всем операциям проекта
Массив с пустым объектом "operations":[{}]	Ошибка валидации

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

Статистика по одной операции

Сравнение операции на нескольких точках интеграции

В ответе — три записи, по одной на каждую точку интеграции.

Список всех операций точки интеграции

В ответе — все операции, у которых на точке были вызовы за последний час, с системными именами в нижнем регистре.

Поиск опечаток в фильтре

Во втором и третьем элементе есть опечатки. В ответе для этих элементов будет status: "notFound" — это помогает находить опечатки на этапе настройки дашборда.

Ответ

Пример успешного ответа

Описание параметров ответа

Поле	Описание
status	Результат обработки запроса в целом
operationStatistics[].endpointId	Точка интеграции, к которой относится статистика
operationStatistics[].operationSystemName	Системное имя операции, к которой относится статистика
operationStatistics[].totalCalls	Количество вызовов за последние 60 минут. Значение всегда равно сумме успешных и ошибочных запросов: totalCalls = successCalls + failedCalls
operationStatistics[].successCalls	Количество успешных вызовов (HTTP 200 + status: "Success" в теле ответа Mindbox)
operationStatistics[].failedCalls	Количество вызовов с ошибкой (4xx, 5xx, ProtocolError, ValidationError)
operationStatistics[].errorRate	Доля ошибок в процентах: failedCalls / totalCalls × 100
operationStatistics[].status	Состояние записи (см. ниже)

Значения поля operationStatistics[].status

• hasData — за последние 60 минут есть вызовы, статистика рассчитана;
• noCallsInPeriod — операция и точка интеграции существуют, но за последние 60 минут вызовов не было. Все счетчики возвращаются равными 0;
• notFound — указанные systemName или endpointId не существуют на проекте. Возникает, например, при опечатке в значении. Все счетчики возвращаются равными 0.

Обработка ошибок

Ситуация	HTTP	Содержимое
Массив с пустым объектом "operations":[{}]	400	ProtocolError: «Each filter item must contain at least one of the fields: 'systemName' or 'endpointId'»
Несуществующий systemName или endpointId	200	Запись со статусом status: "notFound" в operationStatistics. Остальные элементы запроса обрабатываются как обычно
Превышение лимита частоты опроса	429	ProtocolError: «Too many requests.». Подробнее
Кратковременная недоступность сервиса	503	Service unavailable. Реализуйте повторные попытки с экспоненциальной паузой между попытками не короче минуты

---

Окно агрегации

Окно — скользящие последние 60 минут от момента запроса. Каждый вызов попадает в счетчики через 30–90 секунд после приема Mindbox и покидает окно ровно через 60 минут. Изменить интервал нельзя — для других периодов используйте выгрузку логов.

Лимит частоты опроса

На каждую точку интеграции действует ограничение: не более одного вызова метода в минуту. При нарушении возвращается HTTP 429.

• Окно блокировки = 60 секунд от момента, когда клиент получил тело последнего успешного ответа.
• Запросы внутри окна блокировки получают 429 и не продлевают окно, но и не дают новых данных — повторять запрос внутри окна не нужно.
• Не поддерживаются заголовки Retry-After или X-RateLimit-*.

Особенности неполных фильтров

При фильтре, в котором задано только одно из полей (systemName или endpointId):

• возвращаются только операции/точки, у которых был хотя бы один вызов за последние 60 минут;
• операции с totalCalls = 0 в список не попадают — для таких случаев используйте фильтр с явно заданной парой systemName + endpointId, он вернет запись со status: "noCallsInPeriod";
• системные имена операций возвращаются в нижнем регистре.

Чтобы получить полный список — в том числе нулевые операции и в исходном регистре имен — используйте явный фильтр systemName + endpointId для каждой операции.

---

Как использовать метод

Данные метода — это метрики временных рядов (time series): счетчики вызовов и доля ошибок за скользящее окно в 60 минут. Такой формат понимают большинство систем мониторинга и визуализации.

• Дашборд и алерты. Опрашивайте API раз в минуту и передавайте метрики в системы наблюдаемости (Prometheus/VictoriaMetrics + Grafana, Datadog, Zabbix, Yandex Cloud Monitoring и др.)

  В системе наблюдаемости можно построить дашборд с графиками totalCalls и errorRate, а также алерты на пороги — например, «errorRate > 5% за 5 минут» или «нет вызовов больше 10 минут».

• Проверка «жив или мертв». Если графики не нужны, достаточно инструмента типа Uptime Kuma или Better Stack: он периодически делает POST-запрос и проверяет конкретное поле ответа — например, что status == "hasData" и errorRate ниже порога. При нарушении — алерт в чат.

• Скрипт или Cloud Function. Небольшой скрипт (Python, Go, Node) опрашивает API по расписанию и отправляет метрики куда нужно: в очередь, базу данных, корпоративный мониторинг или сразу в мессенджер. Это подходит, если готовая система мониторинга недоступна или нужна нестандартная логика обработки.