Передать подписанный пакет внешних событий аудита

Авторизация

x-hallify-signature: <HALLIFY_SIGNATURE>

Подпись HMAC-SHA256. Точный протокол каждой операции указан в метаданных x-hallify-hmac и её описании.

Руководство по подключению

Параметры

organizationIdПуть · Обязательно: Организация-арендатор, чьи ресурсы и правила используются. Идентификатор участвует в проверке членства, прав и изоляции арендаторов.
string · uuid
Полное определение
{ "type": "string", "format": "uuid", "example": "9b6163a8-afea-4877-818b-8e2ae28a2845" }
sourceKeyПуть · Обязательно: Стабильный ключ настроенного источника входящего аудита, чей HMAC-секрет проверяет доставку.
string
Полное определение
{ "type": "string", "example": "example" }
x-hallify-timestampЗаголовок · Обязательно: Время в целых секундах Unix; допустимое расхождение часов — ±300 секунд.
string
Полное определение
{ "type": "string", "example": "example" }

Тело запроса

Обязательно

Исходный пакет OCSF NDJSON в UTF-8. Точные байты входят в каноническое сообщение HMAC.

application/x-ndjson

string

Полное определение

{
  "type": "string",
  "description": "От 1 до 500 объектов OCSF JSON, по одному событию на строку; максимальный размер исходного запроса — 2 МБ.",
  "example": "{\"class_uid\":1001,\"activity_id\":1}\n"
}

application/ndjson

string

Полное определение

{
  "type": "string",
  "description": "От 1 до 500 объектов OCSF JSON, по одному событию на строку; максимальный размер исходного запроса — 2 МБ.",
  "example": "{\"class_uid\":1001,\"activity_id\":1}\n"
}

Ответы

201Идентификатор принятого пакета и количество записанных либо распознанных повторными событий аудита.

AuditIngestionResultDto

Полное определение

{
  "$ref": "#/components/schemas/AuditIngestionResultDto"
}

Пример ответа · 201 · application/json

{
  "batchId": "example-id",
  "accepted": 0,
  "deduplicated": 0,
  "events": [
    {
      "id": "64edc395-c85f-4e3b-8e3a-d593a4973acc",
      "receivedAt": "2026-01-15T12:00:00.000Z",
      "deduplicated": true
    }
  ]
}

400Некорректный пакет NDJSON или тело события аудита.

TranslatedErrorDto

Полное определение

{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}

Пример ответа · 400 · application/json

{
  "statusCode": 400,
  "error": "errors:http.badRequest",
  "code": "HTTP_BAD_REQUEST",
  "message": "errors:http.badRequest",
  "translationKey": "errors:http.badRequest"
}

401Недействительная, некорректная или просроченная HMAC-подпись аудита.

TranslatedErrorDto

Полное определение

{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}

Пример ответа · 401 · application/json

{
  "statusCode": 401,
  "error": "errors:http.unauthorized",
  "code": "HTTP_UNAUTHORIZED",
  "message": "errors:http.unauthorized",
  "translationKey": "errors:http.unauthorized"
}

404Активный источник входящего аудита не найден.

TranslatedErrorDto

Полное определение

{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}

Пример ответа · 404 · application/json

{
  "statusCode": 404,
  "error": "errors:http.notFound",
  "code": "HTTP_NOT_FOUND",
  "message": "errors:http.notFound",
  "translationKey": "errors:http.notFound"
}

409Подписанный запрос аудита уже обработан.

TranslatedErrorDto

Полное определение

{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}

Пример ответа · 409 · application/json

{
  "statusCode": 409,
  "error": "errors:http.conflict",
  "code": "HTTP_CONFLICT",
  "message": "errors:http.conflict",
  "translationKey": "errors:http.conflict"
}

503Не удалось расшифровать секрет подписи аудита.

TranslatedErrorDto

Полное определение

{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}

Пример ответа · 503 · application/json

{
  "statusCode": 503,
  "error": "errors:http.serviceUnavailable",
  "code": "HTTP_SERVICE_UNAVAILABLE",
  "message": "errors:http.serviceUnavailable",
  "translationKey": "errors:http.serviceUnavailable"
}

Схемы

AuditIngestionResultDto

Идентификатор принятого пакета и количество записанных либо распознанных повторными событий аудита.

batchIdОбязательно: Непрозрачный идентификатор batchId; клиент не должен предполагать формат UUID.
string
Полное определение
{ "type": "string", "description": "Непрозрачный идентификатор `batchId`; клиент не должен предполагать формат UUID.", "example": "example-id" }
acceptedОбязательно: Целочисленное значение accepted. Ограничения: минимум 0.
integer
Полное определение
{ "type": "integer", "minimum": 0, "description": "Целочисленное значение `accepted`. Ограничения: минимум 0.", "example": 0 }
deduplicatedОбязательно: Целочисленное значение deduplicated. Ограничения: минимум 0.
integer
Полное определение
{ "type": "integer", "minimum": 0, "description": "Целочисленное значение `deduplicated`. Ограничения: минимум 0.", "example": 0 }
eventsОбязательно: Коллекция events в составе представления.
array
Полное определение
{ "type": "array", "items": { "type": "object", "required": [ "id", "receivedAt", "deduplicated" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID Hallify для `id`.", "example": "64edc395-c85f-4e3b-8e3a-d593a4973acc" }, "receivedAt": { "type": "string", "format": "date-time", "description": "Время `receivedAt` в формате RFC3339; разные часовые смещения могут обозначать один абсолютный момент.", "example": "2026-01-15T12:00:00.000Z" }, "deduplicated": { "type": "boolean", "description": "Совпало ли входящее событие аудита с ранее принятым по правилам повторов источника.", "example": true } }, "example": { "id": "64edc395-c85f-4e3b-8e3a-d593a4973acc", "receivedAt": "2026-01-15T12:00:00.000Z", "deduplicated": true } }, "description": "Коллекция `events` в составе представления.", "example": [ { "id": "64edc395-c85f-4e3b-8e3a-d593a4973acc", "receivedAt": "2026-01-15T12:00:00.000Z", "deduplicated": true } ] }

Полное определение

{
  "type": "object",
  "required": [
    "batchId",
    "accepted",
    "deduplicated",
    "events"
  ],
  "properties": {
    "batchId": {
      "type": "string",
      "description": "Непрозрачный идентификатор `batchId`; клиент не должен предполагать формат UUID.",
      "example": "example-id"
    },
    "accepted": {
      "type": "integer",
      "minimum": 0,
      "description": "Целочисленное значение `accepted`. Ограничения: минимум 0.",
      "example": 0
    },
    "deduplicated": {
      "type": "integer",
      "minimum": 0,
      "description": "Целочисленное значение `deduplicated`. Ограничения: минимум 0.",
      "example": 0
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "receivedAt",
          "deduplicated"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID Hallify для `id`.",
            "example": "64edc395-c85f-4e3b-8e3a-d593a4973acc"
          },
          "receivedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Время `receivedAt` в формате RFC3339; разные часовые смещения могут обозначать один абсолютный момент.",
            "example": "2026-01-15T12:00:00.000Z"
          },
          "deduplicated": {
            "type": "boolean",
            "description": "Совпало ли входящее событие аудита с ранее принятым по правилам повторов источника.",
            "example": true
          }
        },
        "example": {
          "id": "64edc395-c85f-4e3b-8e3a-d593a4973acc",
          "receivedAt": "2026-01-15T12:00:00.000Z",
          "deduplicated": true
        }
      },
      "description": "Коллекция `events` в составе представления.",
      "example": [
        {
          "id": "64edc395-c85f-4e3b-8e3a-d593a4973acc",
          "receivedAt": "2026-01-15T12:00:00.000Z",
          "deduplicated": true
        }
      ]
    }
  },
  "description": "Идентификатор принятого пакета и количество записанных либо распознанных повторными событий аудита.",
  "example": {
    "batchId": "example-id",
    "accepted": 0,
    "deduplicated": 0,
    "events": [
      {
        "id": "64edc395-c85f-4e3b-8e3a-d593a4973acc",
        "receivedAt": "2026-01-15T12:00:00.000Z",
        "deduplicated": true
      }
    ]
  }
}

TranslatedErrorDto

Стабильная оболочка ошибки общего обработчика HTTP-исключений. Дополнительные машинные данные домена вложены в details.

statusCodeОбязательно: HTTP-статус, повторённый из ответа.
integer
Полное определение
{ "type": "integer", "description": "HTTP-статус, повторённый из ответа.", "example": 400 }
errorОбязательно: Ключ перевода HTTP-категории, например errors:http.conflict. Конкретную причину определяют code и translationKey.
string
Полное определение
{ "type": "string", "description": "Ключ перевода HTTP-категории, например errors:http.conflict. Конкретную причину определяют code и translationKey.", "example": "errors.request.invalid" }
codeОбязательно: Стабильный машинный код домена либо стандартный HTTP_*, если доменный код не задан. Используйте это поле и HTTP-статус для программной логики; локализованная формулировка не управляет повторами или бизнес-решениями.
string
Полное определение
{ "type": "string", "example": "HTTP_BAD_REQUEST", "description": "Стабильный машинный код домена либо стандартный HTTP_*, если доменный код не задан. Используйте это поле и HTTP-статус для программной логики; локализованная формулировка не управляет повторами или бизнес-решениями." }
messageОбязательно: Ключ перевода, идентичный translationKey. API не возвращает локализованный текст интерфейса. Найдите перевод ключа и подставьте translationValues в приложении-потребителе.
string
Полное определение
{ "type": "string", "example": "errors:http.badRequest", "description": "Ключ перевода, идентичный translationKey. API не возвращает локализованный текст интерфейса. Найдите перевод ключа и подставьте translationValues в приложении-потребителе." }
translationKeyОбязательно: Канонический ключ перевода, идентичный message. Ключи errors:http.* соответствующего статуса описывают неуточнённые ошибки. Публичные ключи и пояснения EN/RU перечислены в Developers; неизвестный ключ требует локализованного запасного сообщения в клиенте.
string
Полное определение
{ "type": "string", "example": "errors:http.badRequest", "description": "Канонический ключ перевода, идентичный message. Ключи errors:http.* соответствующего статуса описывают неуточнённые ошибки. Публичные ключи и пояснения EN/RU перечислены в Developers; неизвестный ключ требует локализованного запасного сообщения в клиенте." }
translationValuesНеобязательно: Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.
object
Полное определение
{ "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "example": "example" }, { "type": "number", "example": 0 }, { "type": "boolean", "example": true } ], "example": "example" }, "description": "Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.", "example": { "exampleKey": "example" } }
validationErrorsНеобязательно: Ошибки проверки полей с ключами переводов и стабильными кодами валидаторов. Введённые значения и исходные тексты валидаторов не включаются.
array
Полное определение
{ "description": "Ошибки проверки полей с ключами переводов и стабильными кодами валидаторов. Введённые значения и исходные тексты валидаторов не включаются.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorDto" }, "example": [ { "field": "email", "translationKey": "validation:isEmail", "code": "isEmail", "message": "validation:isEmail" } ] }
detailsНеобязательно: Необязательные сведения о доменных препятствиях или ошибках валидации.
oneOf
Полное определение
{ "description": "Необязательные сведения о доменных препятствиях или ошибках валидации.", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" }, "example": [ "example" ] }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "example": { "exampleKey": "example" } } ], "example": [ "example" ] }

Полное определение

{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "integer",
      "description": "HTTP-статус, повторённый из ответа.",
      "example": 400
    },
    "error": {
      "type": "string",
      "description": "Ключ перевода HTTP-категории, например errors:http.conflict. Конкретную причину определяют code и translationKey.",
      "example": "errors.request.invalid"
    },
    "code": {
      "type": "string",
      "example": "HTTP_BAD_REQUEST",
      "description": "Стабильный машинный код домена либо стандартный HTTP_*, если доменный код не задан. Используйте это поле и HTTP-статус для программной логики; локализованная формулировка не управляет повторами или бизнес-решениями."
    },
    "message": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Ключ перевода, идентичный translationKey. API не возвращает локализованный текст интерфейса. Найдите перевод ключа и подставьте translationValues в приложении-потребителе."
    },
    "translationKey": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Канонический ключ перевода, идентичный message. Ключи errors:http.* соответствующего статуса описывают неуточнённые ошибки. Публичные ключи и пояснения EN/RU перечислены в Developers; неизвестный ключ требует локализованного запасного сообщения в клиенте."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.",
      "example": {
        "exampleKey": "example"
      }
    },
    "validationErrors": {
      "description": "Ошибки проверки полей с ключами переводов и стабильными кодами валидаторов. Введённые значения и исходные тексты валидаторов не включаются.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorDto"
      },
      "example": [
        {
          "field": "email",
          "translationKey": "validation:isEmail",
          "code": "isEmail",
          "message": "validation:isEmail"
        }
      ]
    },
    "details": {
      "description": "Необязательные сведения о доменных препятствиях или ошибках валидации.",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": [
            "example"
          ]
        },
        {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": {
            "exampleKey": "example"
          }
        }
      ],
      "example": [
        "example"
      ]
    }
  },
  "required": [
    "statusCode",
    "error",
    "code",
    "message",
    "translationKey"
  ],
  "description": "Стабильная оболочка ошибки общего обработчика HTTP-исключений. Дополнительные машинные данные домена вложены в details.",
  "example": {
    "statusCode": 400,
    "error": "errors:http.badRequest",
    "code": "HTTP_BAD_REQUEST",
    "message": "errors:http.badRequest",
    "translationKey": "errors:http.badRequest"
  }
}

ValidationErrorDto

Ошибка проверки поля с путём поля, стабильным кодом валидатора и ключом перевода. Человекочитаемый текст принадлежит приложению-потребителю.

fieldОбязательно: Публичный путь поля. Вложенные свойства и индексы массива разделены точками.
string
Полное определение
{ "type": "string", "example": "email", "description": "Публичный путь поля. Вложенные свойства и индексы массива разделены точками." }
translationKeyОбязательно: Ключ перевода этого валидатора, идентичный message. Найдите его в клиентском словаре; см. публичный каталог ошибок Developers.
string
Полное определение
{ "type": "string", "example": "validation:isEmail", "description": "Ключ перевода этого валидатора, идентичный message. Найдите его в клиентском словаре; см. публичный каталог ошибок Developers." }
codeОбязательно: Стабильный идентификатор валидатора для ошибки поля. Пользовательские валидаторы могут определять дополнительные идентификаторы.
string
Полное определение
{ "type": "string", "example": "isEmail", "description": "Стабильный идентификатор валидатора для ошибки поля. Пользовательские валидаторы могут определять дополнительные идентификаторы." }
messageОбязательно: Ключ перевода, описывающий ошибку проверки поля, идентичный translationKey. Введённые значения и тексты валидаторов не включаются.
string
Полное определение
{ "type": "string", "example": "validation:isEmail", "description": "Ключ перевода, описывающий ошибку проверки поля, идентичный translationKey. Введённые значения и тексты валидаторов не включаются." }
translationValuesНеобязательно: Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.
object
Полное определение
{ "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "example": "example" }, { "type": "number", "example": 0 }, { "type": "boolean", "example": true } ], "example": "example" }, "description": "Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.", "example": { "exampleKey": "example" } }

Полное определение

{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "example": "email",
      "description": "Публичный путь поля. Вложенные свойства и индексы массива разделены точками."
    },
    "translationKey": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Ключ перевода этого валидатора, идентичный message. Найдите его в клиентском словаре; см. публичный каталог ошибок Developers."
    },
    "code": {
      "type": "string",
      "example": "isEmail",
      "description": "Стабильный идентификатор валидатора для ошибки поля. Пользовательские валидаторы могут определять дополнительные идентификаторы."
    },
    "message": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Ключ перевода, описывающий ошибку проверки поля, идентичный translationKey. Введённые значения и тексты валидаторов не включаются."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.",
      "example": {
        "exampleKey": "example"
      }
    }
  },
  "required": [
    "field",
    "translationKey",
    "code",
    "message"
  ],
  "description": "Ошибка проверки поля с путём поля, стабильным кодом валидатора и ключом перевода. Человекочитаемый текст принадлежит приложению-потребителю.",
  "example": {
    "field": "email",
    "translationKey": "validation:isEmail",
    "code": "isEmail",
    "message": "validation:isEmail"
  }
}

JsonValue

Рекурсивно допустимое JSON-значение. Используется только там, где контракт явно разрешает произвольные структурированные данные.

Полное определение

{
  "oneOf": [
    {
      "type": "string",
      "nullable": true,
      "example": "example"
    },
    {
      "type": "number",
      "example": 0
    },
    {
      "type": "boolean",
      "example": true
    },
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "description": "Рекурсивно допустимое JSON-значение. Используется только там, где контракт явно разрешает произвольные структурированные данные.",
  "example": "example"
}