Skip to content

Реестр нарушений ​

Семейство violations.

norm_violations_list ​

Реестр нарушений правил компании страницами, от свежих к старым по дню фиксации. Строка — одно нарушение одного сотрудника или исправление нарушения: строка исправления несёт corrects_id — id исправленного нарушения, а само нарушение остаётся в реестре; повторное нарушение — отдельная строка. Строки добавляют агент (norm_violations_append) и люди; статус, срок и вес ведут люди в системе компании. Ответ — сырые строки: вес приходит, только если его поставил человек, а оценок участников и итогов по людям сервер не отдаёт. У строки, которую завёл человек, может не быть ключа и других полей, кроме id, status и recorded_on; пустое текстовое поле — человек его не заполнил. Фильтры, все необязательные: statuses — строки в этих статусах, как статус приходит в ответе: пустой и вне словаря — open; открытые нарушения — open и new_deadline; person_emails — до 200 почт участников, регистр не важен, строка без person_email под этот фильтр не попадает; occurred_from и occurred_to — дни нарушения, recorded_from и recorded_to — дни фиксации, включительно; строка без occurred_on под фильтр по дням нарушения не попадает. Значение не по формату поля сервер не отдаёт, строка при этом остаётся. Строка, записанная norm_violations_append, видна в списке сразу; правки людей могут приходить с задержкой — смотрите freshness. На странице не больше limit строк, и она укладывается в предел размера ответа; total — сколько строк подошло под фильтр до применения страницы. Для следующей страницы передайте page.next_cursor как cursor с теми же фильтрами. Реестр — про людей и их оценку: читать и писать его вправе только владелец и администратор компании, остальным реализация отвечает unauthorized_scope. Доменное состояние not_ready — реестр у компании не настроен.

Доступ: чтение · Списковый: да · Версии контракта: 1

Аргументы

ПолеОбязательноТипЗачем
cursorнетstringКакую страницу прислать: next_cursor из прошлого ответа. Без него — первую.
limitнетintegerСколько записей прислать на одной странице.
occurred_fromнетstring (date)С какого дня нарушения искать строки, включительно.
occurred_toнетstring (date)По какой день нарушения искать строки, включительно.
person_emailsнетсписок stringТолько нарушения этих сотрудников: их почты, регистр не важен.
recorded_fromнетstring (date)С какого дня фиксации искать строки, включительно.
recorded_toнетstring (date)По какой день фиксации искать строки, включительно.
statusesнетсписок ViolationStatusТолько строки в этих статусах; открытые нарушения — open и new_deadline.

Данные ответа (data)

ПолеПри успехеТипЗачем
entriesдасписок ViolationEntryСтроки этой страницы, от свежих к старым по дню фиксации.
totalдаintegerСколько строк подошло под фильтр всего, на всех страницах.
errorнетDomainErrorПочему данных нет: реестр у компании не настроен.
Пример: успешный ответ
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "violations",
      "label": "Реестр нарушений"
    }
  ],
  "freshness": {
    "as_of": "2026-10-14T18:30:00.000Z",
    "ttl_sec": 3600,
    "stale": false
  },
  "page": {
    "has_more": true,
    "next_cursor": "eyJvIjo1fQ"
  },
  "data": {
    "total": 12,
    "entries": [
      {
        "id": "v-2026-0118",
        "status": "open",
        "recorded_on": "2026-10-14",
        "occurred_on": "2026-10-13",
        "key": "2026-10-13|m.petrov@example.com|регламент-3.2|01K9F2QH7T8ZRC4M0X5B2VNJ3D",
        "person_email": "m.petrov@example.com",
        "person_id": "p-1042",
        "person_name": "Михаил Петров",
        "type": "Протокол не опубликован в срок",
        "basis": "Регламент встреч, п. 3.2",
        "fact": "Протокол планёрки 13.10 не опубликован к 10:00 14.10, а регламент требует публикации в течение суток после встречи.",
        "source": {
          "kind": "protocol",
          "url": "https://company.example/protocols/2026-10-13-planerka",
          "meeting_id": "01K9F2QH7T8ZRC4M0X5B2VNJ3D"
        },
        "due_on": "2026-10-15",
        "url": "https://company.example/violations/v-2026-0118"
      },
      {
        "id": "v-2026-0117",
        "status": "closed",
        "recorded_on": "2026-10-14",
        "occurred_on": "2026-10-13",
        "key": "исправление|v-2026-0102",
        "person_email": "s.ilina@example.com",
        "person_id": "p-1077",
        "person_name": "Светлана Ильина",
        "type": "Повестка не разослана",
        "basis": "Правила, п. 4.1",
        "fact": "Повестку встречи 09.10 разослала 13.10 — нарушение исправлено задним числом.",
        "source": {
          "kind": "email"
        },
        "corrects_id": "v-2026-0102",
        "url": "https://company.example/violations/v-2026-0117"
      },
      {
        "id": "v-2026-0109",
        "status": "open",
        "recorded_on": "2026-10-13"
      },
      {
        "id": "v-2026-0102",
        "status": "closed",
        "recorded_on": "2026-10-10",
        "occurred_on": "2026-10-09",
        "key": "2026-10-09|s.ilina@example.com|правила-4.1|01K9DZ4W8N2PQ6R0T3V5X7Z9B1",
        "person_email": "s.ilina@example.com",
        "person_id": "p-1077",
        "person_name": "Светлана Ильина",
        "type": "Повестка не разослана",
        "basis": "Правила, п. 4.1",
        "fact": "Повестка встречи 09.10 не разослана участникам за сутки до встречи.",
        "source": {
          "kind": "calendar",
          "meeting_id": "01K9DZ4W8N2PQ6R0T3V5X7Z9B1"
        },
        "due_on": "2026-10-10",
        "url": "https://company.example/violations/v-2026-0102"
      },
      {
        "id": "v-2026-0095",
        "status": "new_deadline",
        "recorded_on": "2026-10-08",
        "occurred_on": "2026-10-07",
        "key": "2026-10-07|d.orlov@example.com|правила-5.3|01K9B7M2C4E6G8J0K2M4P6R8T0",
        "person_email": "d.orlov@example.com",
        "person_id": "p-1013",
        "person_name": "Дмитрий Орлов",
        "type": "Поручение не внесено в систему задач",
        "basis": "Правила, п. 5.3",
        "fact": "Три поручения со встречи 07.10 не заведены задачами в системе компании.",
        "source": {
          "kind": "record",
          "url": "https://company.example/tasks?meeting=01K9B7M2C4E6G8J0K2M4P6R8T0",
          "meeting_id": "01K9B7M2C4E6G8J0K2M4P6R8T0"
        },
        "due_on": "2026-10-17",
        "weight": 2,
        "url": "https://company.example/violations/v-2026-0095"
      }
    ]
  }
}
Пример: случай «domain_error»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "violations"
    }
  ],
  "freshness": {
    "as_of": "2026-10-14T18:30:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "page": {
    "has_more": false
  },
  "data": {
    "error": {
      "code": "not_ready",
      "message": "Реестр нарушений у компании не настроен.",
      "retryable": false
    }
  }
}

norm_violations_append ​

Добавить строки в реестр нарушений правил компании пачкой — от 1 до 50 за вызов. Только добавление: строки, которые уже есть в реестре, запись не меняет и не удаляет. key ставит агент так, чтобы одно нарушение давало один ключ: только из частей, которые при повторе не меняются, — день нарушения, почта участника в нижнем регистре, документ и номер пункта в одном написании, meeting_id, — а не из текста модели. Тогда повторный прогон за тот же день реестр не задваивает, а повторное нарушение в другой день — новая строка. Ключ уже есть в реестре — новая строка не создаётся, а прежняя остаётся как была, даже если остальные поля записи другие: запись придёт в accepted с id этой строки и created: false. Ключ сравнивается целиком, с учётом регистра, в том числе со строками, записанными только что. Нарушение не снимают: исправление записывайте отдельной строкой с corrects_id — id строки нарушения из norm_violations_list — и своим ключом, например из corrects_id: с ключом нарушения запись вернёт строку нарушения с created: false, и исправление не запишется. Участник, тип и основание у исправления — как у нарушения. occurred_on — когда нарушение случилось, у исправления — когда нарушение исправили; recorded_on — день прогона, который строку фиксирует. Статус новой строки ставит сервер — open нарушению, closed исправлению; статус, срок и вес дальше ведут люди, агент их не пишет. Пачку, где запись не проходит схему входа — длина, формат дня, вид источника, — сервер вправе отклонить целиком: пределы и форматы проверяйте до отправки. Отказ записи по остальным причинам не отменяет другие: она придёт в rejected с ключом и кодом — invalid_input (occurred_on позже recorded_on или ключ повторяется в пачке: записана первая, она в accepted, поэтому записи с одним ключом склейте до отправки), unknown_user (сотрудника с этой почтой у компании нет), unknown_id (строки corrects_id в реестре нет), record_deleted (строку с этим ключом удалил человек, воссоздавать её нельзя), record_rejected (хранилище не приняло запись, повтор даст то же), temporary и rate_limited (временный сбой). Повторить пачку безопасно: записанное повтор не задвоит. Реестр — про людей и их оценку: читать и писать его вправе только владелец и администратор компании, остальным реализация отвечает unauthorized_scope. Доменные состояния вызова: not_ready — реестр у компании не настроен; temporary и rate_limited — повторите позже.

Доступ: запись · Списковый: нет · Версии контракта: 1

Аргументы

ПолеОбязательноТипЗачем
entriesдасписок NewViolationEntryСтроки для записи — нарушения и исправления; каждый ключ — один раз.

Данные ответа (data)

ПолеПри успехеТипЗачем
acceptedдасписок ViolationEntryRefПринятые записи: id строки за каждым ключом и создана ли она этим вызовом.
rejectedдасписок RejectedRecordКакие записи не приняты и почему; остальные приняты.
errorнетDomainErrorПочему ничего не записано и можно ли повторить.
noteнетstringПояснение сервера к записи.
Пример: успешный ответ
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "violations",
      "label": "Реестр нарушений"
    }
  ],
  "freshness": {
    "as_of": "2026-10-14T18:30:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "data": {
    "accepted": [
      {
        "key": "2026-10-13|m.petrov@example.com|регламент-3.2|01K9F2QH7T8ZRC4M0X5B2VNJ3D",
        "id": "v-2026-0118",
        "created": true
      },
      {
        "key": "исправление|v-2026-0102",
        "id": "v-2026-0117",
        "created": true
      },
      {
        "key": "2026-10-13|k.zueva@example.com|правила-2.4|01K9F2QH7T8ZRC4M0X5B2VNJ3D",
        "id": "v-2026-0112",
        "created": false
      }
    ],
    "rejected": [
      {
        "key": "2026-10-13|buyer@partner.example|правила-2.4|01K9F2QH7T8ZRC4M0X5B2VNJ3D",
        "code": "unknown_user",
        "message": "сотрудника с почтой buyer@partner.example у компании нет"
      },
      {
        "key": "исправление|v-2026-0102",
        "code": "invalid_input",
        "message": "ключ уже был в этом вызове — повтор не записан"
      }
    ]
  }
}
Пример: случай «domain_error»
json
{
  "source_refs": [
    {
      "source": "company-data",
      "ref": "violations"
    }
  ],
  "freshness": {
    "as_of": "2026-10-14T18:30:00.000Z",
    "ttl_sec": 0,
    "stale": false
  },
  "data": {
    "error": {
      "code": "not_ready",
      "message": "Реестр нарушений у компании не настроен.",
      "retryable": false
    }
  }
}

Объекты семейства ​

Объекты, из которых состоят аргументы и ответы инструментов этого семейства.

ViolationStatus ​

Статус нарушения. open — нарушение открыто; closed — закрыто; new_deadline — человек назначил новый срок, он в due_on. Статус новой строки ставит сервер, дальше его меняют люди в системе компании; агент статус не пишет. Пустой статус и значение вне словаря сервер отдаёт как open: нарушение открыто, пока человек не закрыл его и не назначил новый срок.

Значения: open, closed, new_deadline.

ViolationEntry ​

Строка реестра нарушений. Одна строка реестра нарушений правил компании: нарушение одного сотрудника или исправление нарушения. Строка исправления несёт corrects_id, а нарушение при исправлении остаётся в реестре. Строки добавляют агент и люди; статус, срок и вес ведут люди. У строки, которую завёл человек, могут быть только id, status и recorded_on. Пустое текстовое поле — человек его не заполнил; текст длиннее предела сервер обрезает. Значение, которое не проходит формат поля, — ссылку не по форме, день со временем, пустой id, вес не числом — сервер не отдаёт: поля нет, а строка остаётся. Вес — только тот, что поставил человек: оценок участника в строке нет.

ПолеОбязательноТипЗачем
idдаstringНомер строки в системе компании: на него ссылается строка исправления полем corrects_id.
recorded_onдаstring (date)Когда нарушение зафиксировано в реестре; у строки, которую человек завёл без этой даты, — день, когда строку завели.
statusдаViolationStatusЧто с нарушением сейчас: открыто, закрыто или назначен новый срок; ведут люди.
basisнетstringОснование: документ и пункт, которые нарушены.
corrects_idнетstringЕсть только у строки исправления: id строки нарушения, которое исправлено; нет поля — это строка нарушения.
due_onнетstring (date)К какому дню нарушение нужно исправить; при новом сроке — новый день.
factнетstringЧто случилось: факт словами.
keyнетstringКлюч, с которым строку записал агент; у строки, которую завёл человек, ключа может не быть.
occurred_onнетstring (date)Когда нарушение случилось; у строки исправления — когда нарушение исправили.
person_emailнетstringЧьё нарушение: почта сотрудника в нижнем регистре.
person_idнетstringЧьё нарушение: id сотрудника из norm_people_list.
person_nameнетstringКак участник назван в реестре: показать строку, не сверяясь со списком сотрудников.
sourceнетViolationSourceГде нарушение видно: вид, ссылка, встреча.
typeнетstringТип нарушения словами компании: словарь типов ведёт компания.
urlнетstring (uri)Ссылка на строку в системе компании, чтобы человек мог её открыть.
weightнетnumberВес нарушения, если его поставил человек; нет поля — вес не задан.

ViolationSource ​

Источник нарушения. Где нарушение видно: вид источника, ссылка для человека и встреча, если нарушение с ней связано.

ПолеОбязательноТипЗачем
kindдаViolationSourceKindГде нарушение видно: по виду источник показывают человеку.
meeting_idнетstringО какой встрече речь: id из norm_meetings_list, если нарушение связано со встречей.
urlнетstring (uri)Ссылка на источник для человека: протокол, встреча, письмо или карточка.

ViolationSourceKind ​

Вид источника. meeting — встреча: её запись или расшифровка; protocol — протокол встречи; calendar — событие календаря; email — письмо; record — карточка в системе компании: задача, страница, строка базы; other — источник, которого нет в словаре.

Значения: meeting, protocol, calendar, email, record, other.

NewViolationEntry ​

Новая строка реестра. Нарушение или исправление, которое агент добавляет в реестр: ключ, участник, тип, основание, факт, источник, дни нарушения и фиксации, срок. Строка исправления несёт corrects_id. Статуса, веса и id здесь нет: статус новой строки ставит сервер, вес — люди, id — система компании.

ПолеОбязательноТипЗачем
basisдаstringОснование: документ и пункт, которые нарушены, например «Правила, п. 6.35».
factдаstringЧто случилось: кто, что и когда сделал или не сделал — факт без оценки человека.
keyдаstringКлюч строки: агент строит его только из частей, которые при повторе не меняются, — день нарушения, почта участника в нижнем регистре, номер пункта, meeting_id. У строки исправления свой ключ, например из corrects_id.
occurred_onдаstring (date)Когда нарушение случилось, у строки исправления — когда нарушение исправили; не позже recorded_on.
person_emailдаstringЧьё нарушение: почта сотрудника из norm_people_list, регистр не важен.
recorded_onдаstring (date)Когда нарушение зафиксировано: день прогона агента, который его записывает.
sourceдаViolationSourceГде нарушение видно: вид, ссылка, встреча.
typeдаstringТип нарушения словами компании, из её словаря типов.
corrects_idнетstringТолько у строки исправления: id строки нарушения из norm_violations_list, которое исправлено.
due_onнетstring (date)К какому дню исправить, если срок даёт правило или поручение; нет — срок назначит человек.

ViolationEntryRef ​

Принятая запись. Запись пачки, которую сервер принял: её ключ, id строки реестра и создана ли строка этим вызовом. created: false — строка с этим ключом уже была, и вызов её не менял.

ПолеОбязательноТипЗачем
createdдаbooleanСоздана ли строка этим вызовом; false — строка с этим ключом уже была и осталась как была.
idдаstringid строки реестра за этим ключом: для corrects_id и чтобы найти строку в списке.
keyдаstringКлюч записи из входа.

RejectedRecord ​

Непринятая запись. Запись пачки, которую сервер не принял: ключ записи, код из общего словаря и пояснение. Остальные записи пачки при этом записаны.

ПолеОбязательноТипЗачем
codeдаErrorCodeПочему запись не принята: код из общего словаря, по нему видна сторона.
keyдаstringКакая запись пачки не принята: её ключ, у разбора встречи — meeting_id.
messageнетstringПояснение для разработчика.