Журнал API-операций
Все операции. Авторизация. Запросы и повторы.
Все пути в этом файле дополняют /api/v1 на домене организации.
Описание и ограничения
Назначение
Проверка исхода команды после превышения времени ожидания, состояния длительной работы и сохранённого результата без повторного исполнения.
Поля и назначение
| Публичное поле | Формат и смысл | Доступ |
|---|---|---|
id |
непрозрачный ID | только чтение |
state |
processing / succeeded / failed / needs_reconciliation | только чтение |
method, path |
POST и канонический путь | только чтение |
created_at, completed_at |
дата и время/null | только чтение |
resource_refs |
массив of объект | только чтение |
error |
объект/null | только чтение |
response_available |
логическое значение | только чтение |
http_status, response |
целое число/null, объект data/meta/null; только при текущем доступе | только чтение |
items |
массив type/id/state/error; при пакетной операции | только чтение |
Обязательность и null указаны в схемах каждой операции ниже.
Доступ и выборка
api_operations:read в пределах текущего api_client; метаданные доступны только владельцу операции, а ссылки/тело ответа дополнительно требуют текущего доступа к объектам.
Фильтры: state, created_from/to, ограниченный период; без чтения чужих ключей или request payload. operation_id возвращается в meta любого принятого POST. Если ответ потерян до получения ID, клиент повторяет исходный POST с прежним ключом: сервер выдаёт сохранённый результат/operation_id, включая IDEMPOTENCY_RESULT_EXPIRED после очистки тела.
Правила и связи
- GET не повторяет команду и не служит скрытой кнопкой retry.
- Журнал не возвращает полный
Idempotency-Key, секреты и тела исходных запросов. - Ключ операции сохраняется при ротации токена, а её результат не даёт права обойти отзыв доступа.
- needs_reconciliation блокирует автоматический повтор эффекта до сверки его исхода.
- Постоянный журнал записей об операциях отделён от краткосрочного хранения HTTP-тел ответа.
- Для processing/needs_reconciliation
http_statusиresponseравны null, опрос состояния возвращает 200 иRetry-After: 2. Для succeeded/failed возвращаются финальный код и сохранённый результат, покаresponse_available=true. Очистка тела оставляетstate,resource_refsи безопасную ошибку, но не восстанавливает изменившуюся карточку как прежний ответ. - Для JSON-команд 202 исходное ответ о принятии хранится отдельно от окончательного response. Повтор POST воспроизводит исходный 202, а GET журнала показывает текущее processing/succeeded/failed/needs_reconciliation. Исходный 202 не выдаётся как окончательный результат. При failed без отдельного финального тела
response_available=false,errorиitemsсохраняют безопасный исход. - Пакет с неуспешными элементами имеет failed или needs_reconciliation, а не succeeded;
itemsсообщает подтверждённые результаты. Тела с недоступными объектами не выдаются частично под видом исходного ответа. - Сохранённый
responseсодержит исходный результат команды без request_id и ETag. НовыйX-Request-Idотносится к текущему GET журнала и передаётся только заголовком. Если GET журнала выдаётETag, тот валидирует всё текущее представление операции, а не историческую карточку изresponse; версии внутриresponseсохраняются прежними.
Операции
| Метод | Путь | Назначение |
|---|---|---|
| GET | /api-operations |
Ограниченный журнал операций текущего подключения |
| GET | /api-operations/{id} |
Исход операции, её ресурсы и состояние |
GET /api-operations
Ограниченный журнал операций текущего подключения.
Доступ. Разрешения подключения: api_operations:read. Права сотрудника: «Системные настройки → Базовый доступ к системе». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
filter[state] |
параметр запроса | строка | нет | нет | Допустимо: "processing", "succeeded", "failed", "needs_reconciliation" |
filter[created_from] |
параметр запроса | строка (дата и время) | нет | нет | не более 64 символов; Шаблон: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})$ |
filter[created_to] |
параметр запроса | строка (дата и время) | нет | нет | не более 64 символов; Шаблон: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})$ |
sort |
параметр запроса | строка | нет | нет | Допустимо: "id", "-id" |
page[size] |
параметр запроса | целое число | нет | нет | ≥ 1; ≤ 100 |
page[cursor] |
параметр запроса | строка | нет | нет | не более 8192 символов |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/api-operations" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"
GET /api-operations/{id}
Исход операции, её ресурсы и состояние.
Доступ. Разрешения подключения: api_operations:read. Права сотрудника: «Системные настройки → Базовый доступ к системе». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
id |
путь | строка | да | нет | — |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/api-operations/ef62763b-87f9-4c90-83bb-e919f3c8e111" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"