Разное

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

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

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

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

Для детального разбора инцидента используйте Логи вызовов операций или их выгрузку.

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

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

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

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

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

Подробнее о работе с V3 API, URL запросов и заголовках: Документация V3 API.

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": "<Системное имя операции>",
      "endpointId": "<Идентификатор точки интеграции>"
    }
  ]
}

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

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

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

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

POST https://api.mindbox.ru/v3/operations/sync?endpointId=demo.Website&operation=MonitoringOperacii

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

{
  "operations": [
    { 
      "systemName": "Website.OrderCreate", 
      "endpointId": "demo.Website" 
    }
  ]
}

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

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

POST https://api.mindbox.ru/v3/operations/sync?endpointId=demo.Website&operation=MonitoringOperacii

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

{
  "operations": [
    { 
      "systemName": "Website.OrderCreate", 
      "endpointId": "demo.Website" 
      },
    { 
      "systemName": "Website.OrderCreate", 
      "endpointId": "demo.Ios" 
      },
    { 
      "systemName": "Website.OrderCreate", 
      "endpointId": "demo.Android" 
      }
  ]
}

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

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

POST https://api.mindbox.ru/v3/operations/sync?endpointId=demo.Website&operation=MonitoringOperacii

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

{
  "operations": [
    { "endpointId": "demo.Website" }
  ]
}

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

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

POST https://api.mindbox.ru/v3/operations/sync?endpointId=demo.Website&operation=MonitoringOperacii

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

{
  "operations": [
    { 
      "systemName": "Website.OrderCreate", 
      "endpointId": "demo.Website" 
    },
    { 
      "systemName": "Website.OrderCrete", 
      "endpointId": "demo.Website" 
      },
    { 
      "systemName": "Website.OrderCreate", 
      "endpointId": "demo.Webste" }
  ]
}

Ответ

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

{
  "status": "Success",
  "operationStatistics": [
    {
      "endpointId": "demo.Website",
      "operationSystemName": "Website.OrderCreate",
      "totalCalls": 142,
      "successCalls": 138,
      "failedCalls": 4,
      "errorRate": 2.82,
      "status": "hasData"
    }
  ]
}

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

Поле	Описание
`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 минут. Изменить интервал нельзя — для других периодов используйте выгрузку логов.

Из-за задержки агрегации последние секунды могут не попасть в счетчики: для критичных алертов работайте с окном «60 минут назад минус 1 минуту», не используйте самые свежие данные.

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

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

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

Безопасный интервал между запросами — 60 секунд + время ответа предыдущего запроса + небольшой запас. При среднем времени ответа около 1 секунды безопасный интервал равен 62 секундам.

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

При фильтре, в котором задано только одно из полей (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 по расписанию и отправляет метрики куда нужно: в очередь, базу данных, корпоративный мониторинг или сразу в мессенджер. Это подходит, если готовая система мониторинга недоступна или нужна нестандартная логика обработки.

Во всех случаях соблюдайте лимит: не более одного вызова в минуту на точку интеграции. Инструмент должен поддерживать интервал опроса 60–62 секунды — иначе запросы начнут возвращать 429.

Last modified on October 30, 2026

Интеграция с сервисом SLA Мониторинг вебхуков