Аудит изменений через API

Аудит МойСклад — это системный журнал, куда сервис пишет каждое создание, изменение и удаление сущности. Через JSON API 1.2 его можно читать программно: получать список контекстов событий, разворачивать конкретное событие в набор изменённых полей и связывать правки с сотрудником, документом и временем.

Что такое аудит и зачем читать его через API

Аудит в МойСклад — это неизменяемый журнал действий пользователей и интеграций. Каждое событие фиксирует кто, когда и что сделал: создал товар, изменил цену, удалил заказ, провёл отгрузку. В интерфейсе журнал доступен в разделе «Аудит», а через JSON API 1.2 те же данные читаются программно.

Типичные задачи, которые закрывает чтение аудита из внешней системы:

• восстановить, кто и когда поменял остаток, цену или статус документа;
• построить отчёт «изменения за сутки» для контроля менеджеров;
• инкрементально забирать правки в хранилище (DWH) без выгрузки всех сущностей;
• расследовать инциденты — например, почему заказ вдруг стал непроведённым.

Эндпоинты аудита: контексты и события

Базовый адрес API — https://api.moysklad.ru/api/remap/1.2. Аудит устроен двухуровнево: сначала вы получаете список контекстов события (event context), затем разворачиваете конкретный контекст в набор событий по полям.

Запрос списка контекстов:

GET /api/remap/1.2/audit?limit=100&order=moment,desc

Каждый элемент rows — это контекст с полями moment (время), entityType (тип сущности), eventType (create/update/delete), uid сотрудника и ссылкой на events.

Типы событий и структура контекста

Поле eventType в контексте описывает характер действия. Наиболее частые значения:

Дополнительно в контексте приходят objectCount (сколько объектов затронуто — важно для массовых операций), source (например, api или jsonApi) и supportAccess. Именно по source удобно отделять правки, сделанные вашей интеграцией, от ручных изменений в интерфейсе.

Разворачиваем изменения полей (diff)

Сам контекст не содержит, какие именно поля изменились. Чтобы получить diff, обратитесь к событиям контекста:

GET /api/remap/1.2/audit/{contextId}/events

В ответе rows — список изменённых полей, каждое со структурой:

• entityType и entityHref — на какую сущность указывает событие;
• name — человекочитаемое имя сущности на момент правки;
• diff — объект вида { "поле": { "oldValue": ..., "newValue": ... } }.

Например, при смене статуса заказа в diff увидите state со старым и новым значением, а при правке цены — соответствующий salePrice. Это позволяет собрать полноценную ленту «поле: было → стало» без сравнения снимков сущности вручную.

Фильтрация журнала по дате, сотруднику и типу

Журнал за всё время читать бессмысленно — его фильтруют параметром filter и сортируют order. Основные фильтры:

Формат даты в фильтрах — yyyy-MM-dd HH:mm:ss, пробел в URL кодируется как %20. Несколько условий по одному полю задаются повторением параметра filter и объединяются логикой сервиса (например, диапазон дат — два условия с >= и <=).

Инкрементальная выгрузка правок

Для регулярной синхронизации в хранилище используйте связку «фильтр по времени + сортировка + пагинация». Алгоритм:

1. сохраните метку последней успешной выгрузки lastMoment;
2. запросите GET /audit?filter=moment>={lastMoment}&order=moment,asc&limit=1000;
3. идите по страницам через offset или ссылку meta.nextHref;
4. для нужных контекстов подтяните /events и обновите lastMoment временем последнего обработанного события.

Сортировка по возрастанию moment гарантирует, что вы не пропустите события при разбивке на страницы. Чтобы не упереться в лимиты API, держите паузу между запросами и обрабатывайте события пачками.

Итог

Аудит через JSON API 1.2 — это два уровня чтения: список контекстов GET /audit и разворот в diff-события GET /audit/{id}/events. Фильтры по moment, employee, eventType и source позволяют собрать точную ленту изменений, а сортировка по времени и пагинация — организовать надёжную инкрементальную выгрузку в хранилище.

Если аудит нужно связать с сайтом на 1С-Битрикс — например, показывать историю правок каталога или логировать, кто и когда менял цены при обмене, — мы проектируем такие интеграции и обмен данными под нагрузку и с прозрачным логированием. Поможем построить надёжный конвейер выгрузки событий из МойСклад в вашу систему.