{
  "openapi": "3.0.3",
  "info": {
    "title": "Reestr — партнёрский API",
    "version": "1.0.0",
    "description": "Программный доступ к данным о юридических лицах Кыргызской Республики.\n\nОдин вызов: полное досье компании по ИНН. Доступ по ключу в заголовке `X-Api-Key`, расходует месячную квоту тарифа — списывается только ответ, который принёс данные.\n\nОписание содержит ровно этот вызов: внутренние и административные интерфейсы Реестра в него не входят и партнёрам не предоставляются.\n\n**Про даты.** Все отметки времени приходят строкой вида `2019-04-12T00:00:00` — без буквы `Z` и без смещения часового пояса, поэтому у них НЕ проставлен `format: date-time`: строгий разбор по RFC 3339 такую строку не принимает, а нестрогий подставил бы часовой пояс машины клиента и сдвинул дату. Отметки времени («когда проверяли») — по UTC; регистрационные даты календарные, время у них нулевое и смысла не несёт.\n\n**Поля без данных.** `riskScore` сейчас приходит пустым по любой компании (расчёт оценки риска отключён), `isRegisteredSupplier` — замороженный снимок неизвестной давности. Оба поля остаются в ответе, но выводов по ним делать нельзя, подробности — в их описаниях.\n\nВопросы по подключению: info@reestr.kg",
    "contact": {
      "name": "Поддержка Реестра",
      "email": "info@reestr.kg"
    }
  },
  "servers": [
    {
      "url": "https://api.reestr.kg",
      "description": "Рабочий сервер"
    }
  ],
  "tags": [
    {
      "name": "Партнёрский API",
      "description": "Полное досье компании по ИНН. Требуется ключ, расходует квоту."
    }
  ],
  "security": [],
  "paths": {
    "/partner/v1/companies/{tin}": {
      "get": {
        "tags": [
          "Партнёрский API"
        ],
        "summary": "Полное досье компании по ИНН",
        "description": "Возвращает карточку компании целиком: регистрационные сведения, учредителей, контакты и реквизиты, отметки о запретах, банкротстве и задолженности, санкционные совпадения.\n\nКвоту расходует только ответ, который принёс данные (`200`). Отказы — неверный ИНН, компания не найдена, проблемы с ключом, подпиской или скоростным лимитом — квоту не списывают.\n\nПоле `riskScore` в ответе есть, но сейчас всегда пустое: расчёт оценки риска отключён.",
        "operationId": "getPartnerCompany",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tin",
            "in": "path",
            "required": true,
            "description": "ИНН компании — от 3 до 14 цифр. Короткие идентификаторы встречаются у старых и ликвидированных компаний.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{3,14}$",
              "example": "01234567890123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Досье найдено",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyDossier"
                }
              }
            }
          },
          "400": {
            "description": "ИНН не соответствует форме (код `InvalidTin`). Квоту не расходует.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "InvalidTin",
                  "message": "ИНН должен содержать от 3 до 14 цифр."
                }
              }
            }
          },
          "401": {
            "description": "Нет заголовка `X-Api-Key`, либо ключ недействителен или отозван (код `InvalidApiKey`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "InvalidApiKey",
                  "message": "API-ключ недействителен или отозван."
                }
              }
            }
          },
          "403": {
            "description": "Подписка не даёт доступа к API или истекла (`ApiSubscriptionExpired`); аккаунт временно заморожен (`AccountTemporarilyFrozen`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ApiSubscriptionExpired",
                  "message": "Активная подписка не даёт доступа к партнёрскому API."
                }
              }
            }
          },
          "404": {
            "description": "Компании с таким ИНН нет в реестре (код `CompanyNotFound`). Квоту не расходует.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "CompanyNotFound",
                  "message": "Компания с указанным ИНН не найдена в реестре."
                }
              }
            }
          },
          "429": {
            "description": "Превышен скоростной лимит (`RateLimitExceeded`, заголовок `Retry-After: 60`) либо исчерпана месячная квота (`QuotaExceeded`, в теле — `used` и `quota`).\n\nКод `RateLimitExceeded` отдают ДВА разных лимита, и по телу ответа они неразличимы:\n\n1. Тарифный лимит запросов в минуту по вашему ключу.\n2. Общий лимит на IP-адрес, с которого пришёл запрос — 120 запросов в минуту по умолчанию, независимо от тарифа. Он проверяется ДО ключа, поэтому срабатывает и тогда, когда с ключом и подпиской всё в порядке. Такое возможно, если запросы уходят через общий внешний адрес (офисный шлюз, общий NAT, облачный прокси) и лимит расходуете не только вы; лимит на адрес настраивается — напишите в поддержку.",
            "headers": {
              "Retry-After": {
                "description": "Через сколько секунд повторить запрос. Присылается при `RateLimitExceeded`.",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuotaError"
                },
                "example": {
                  "code": "QuotaExceeded",
                  "message": "Месячная квота партнёрского API исчерпана.",
                  "used": 1000,
                  "quota": 1000
                }
              }
            }
          },
          "500": {
            "description": "Непредвиденный сбой. В отличие от остальных отказов, приходит С ПУСТЫМ ТЕЛОМ: единого обработчика исключений у сервиса нет, и до формата `{ code, message }` такой ответ не доходит. Разбирайте тело только после проверки, что оно непустое. Квоту не расходует. Предвиденный сбой инфраструктуры — это `503`, у него тело есть."
          },
          "503": {
            "description": "Временный сбой на стороне Реестра (код `TemporarilyUnavailable`). Заголовок `Retry-After: 5` — запрос стоит повторить. Квоту не расходует: списание происходит только в момент отдачи досье и до этого ответа не доходит.",
            "headers": {
              "Retry-After": {
                "description": "Через сколько секунд повторить запрос.",
                "schema": {
                  "type": "integer",
                  "example": 5
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "TemporarilyUnavailable",
                  "message": "Сервис временно недоступен, повторите запрос"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "Партнёрский ключ вида `rk_…`. Выпускается в личном кабинете (раздел «Профиль → API») и показывается один раз. Активный ключ у аккаунта один: выпуск нового сразу отзывает предыдущий."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Единый формат ошибки. Ориентируйтесь на машиночитаемое поле `code`; `message` предназначено человеку и может меняться.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Машиночитаемый код ошибки.",
            "example": "CompanyNotFound"
          },
          "message": {
            "type": "string",
            "description": "Пояснение на русском языке.",
            "example": "Компания с указанным ИНН не найдена в реестре."
          }
        }
      },
      "QuotaError": {
        "type": "object",
        "description": "Ошибка исчерпания месячной квоты — то же тело, что и у прочих ошибок, плюс счётчики.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "QuotaExceeded"
          },
          "message": {
            "type": "string"
          },
          "used": {
            "type": "integer",
            "description": "Сколько запросов израсходовано в текущем месяце."
          },
          "quota": {
            "type": "integer",
            "description": "Месячная квота тарифа."
          }
        }
      },
      "Founder": {
        "type": "object",
        "description": "Учредитель компании: физическое лицо либо организация. Организации разделены по виду — обычная компания, госорган, иностранная компания, некоммерческая организация.",
        "required": [
          "name",
          "type"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "ФИО физлица или наименование организации. У безымянного узла графа приходит заглушка `(без ИНН)` — имени учредителя в источнике не было, поле при этом непустое."
          },
          "type": {
            "type": "string",
            "description": "Тип учредителя. Перечень открытый: разбирайте значение как строку с запасным вариантом, а не жёсткой проверкой на известные варианты — иначе клиент упадёт на первой же компании с учредителем-госорганом.",
            "enum": [
              "person",
              "company",
              "state",
              "foreign",
              "ngo"
            ],
            "x-enum-descriptions": {
              "person": "Физическое лицо.",
              "company": "Юридическое лицо — обычная компания.",
              "state": "Государственный орган или орган местного самоуправления.",
              "foreign": "Иностранная компания.",
              "ngo": "Некоммерческая организация: фонд, кооператив, профсоюз, общественное объединение."
            }
          },
          "tin": {
            "type": "string",
            "nullable": true,
            "description": "ИНН учредителя-юрлица, чья карточка есть в реестре; null — у физлица и у организации без разрешённой карточки (в том числе у типов state, foreign, ngo)."
          }
        }
      },
      "CompanyLicenseDetail": {
        "type": "object",
        "description": "Поле реестра, которого нет в общей части лицензии: подпись и значение дословно из источника. Набор полей зависит от реестра — например, у иностранных строительных лицензий это государство-эмитент и реестр признания.",
        "required": [
          "label",
          "value"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "Подпись поля на русском языке.",
            "example": "Государство, выдавшее лицензию"
          },
          "value": {
            "type": "string",
            "description": "Значение строкой дословно из источника.",
            "example": "Республика Казахстан"
          }
        }
      },
      "CompanyLicense": {
        "type": "object",
        "description": "Лицензия или разрешение компании из любого реестра, который мы загружаем. Вид реестра назван полем kind, ограничения приходят этим же списком со статусом Restricted. Записи, пропавшие из источника, наружу не отдаются.",
        "required": [
          "kind",
          "authority",
          "status",
          "matchedBy"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "Construction"
            ],
            "description": "Вид реестра. Перечень будет пополняться по мере подключения новых реестров — обрабатывайте незнакомое значение как «прочая лицензия», а не как ошибку.",
            "example": "Construction"
          },
          "authority": {
            "type": "string",
            "description": "Кто выдал лицензию (ведёт реестр), коротко.",
            "example": "Минстрой"
          },
          "category": {
            "type": "string",
            "nullable": true,
            "description": "Деление внутри реестра, как его называет источник. У строительных лицензий это раздел реестра: Level1–Level4 — уровень ответственности, Foreign — реестр лицензий иностранных государств. null — у записи такого деления нет (например, у ограничения: источник не говорит, лицензию какого уровня приостановили).",
            "example": "Level3"
          },
          "series": {
            "type": "string",
            "nullable": true,
            "description": "Серия лицензии. У строительных третья буква — регион выдачи (Ц — Бишкек, О — Ош, Ж — Джалал-Абад, И — Иссык-Куль, Ч — Чуй, Б — Баткен, Н — Нарын, Т — Талас). null — источник серию не публикует (иностранные лицензии, ограничения).",
            "example": "КРЦ-2"
          },
          "number": {
            "type": "string",
            "nullable": true,
            "description": "Номер лицензии как в реестре; null — источник номер не публикует.",
            "example": "012899/18"
          },
          "activity": {
            "type": "string",
            "nullable": true,
            "description": "Вид деятельности по лицензии дословно из источника; null — источник вид деятельности не печатает (так у строительных уровней 1–4).",
            "example": "СМР"
          },
          "issuedOnRaw": {
            "type": "string",
            "nullable": true,
            "description": "Дата выдачи (у ограничения — дата решения) строкой ДОСЛОВНО из реестра — показывать нужно именно её. Источники заполняют даты небрежно: встречается «1899-12-30» (так табличный редактор показывает пустую дату) и невозможные годы. Мы такие значения не подменяем и не прячем.",
            "example": "2025-06-19"
          },
          "issuedOn": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Та же дата, разобранная в дату, либо null, если значение источника нечитаемо или заведомо невозможно. Годится для сортировки и отбора по периоду; для показа берите issuedOnRaw.",
            "example": "2025-06-19T00:00:00"
          },
          "validUntilRaw": {
            "type": "string",
            "nullable": true,
            "description": "Срок действия (у ограничения — срок ограничения) строкой дословно из источника, включая свободный текст вроде «бессрочно»; null — источник срок не публикует (так у действующих строительных лицензий).",
            "example": "2026-02-18"
          },
          "validUntil": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Тот же срок, разобранный в дату, либо null, если значение нечитаемо или это свободный текст. Для показа берите validUntilRaw.",
            "example": "2026-02-18T00:00:00"
          },
          "status": {
            "type": "string",
            "enum": [
              "Active",
              "Restricted"
            ],
            "description": "Active — запись есть в реестре, ограничений по ней источник не публикует. Restricted — есть приостановка, аннулирование или решение суда; дословная формулировка в statusNote. Статусов намеренно два: формулировки запретов у источников не унифицированы, и раскладывать их по видам значило бы угадывать за источник.",
            "example": "Active"
          },
          "statusNote": {
            "type": "string",
            "nullable": true,
            "description": "Формулировка ограничения дословно из источника («Приостановить действие лицензии», ссылка на решение суда). null — у записи нет ограничения либо источник оставил ячейку пустой.",
            "example": "Приостановить действие лицензии"
          },
          "matchedBy": {
            "type": "string",
            "enum": [
              "Tin",
              "Name"
            ],
            "description": "Чем запись привязана к компании: Tin — источник публикует ИНН лицензиата; Name — ИНН в источнике нет, привязка сделана сверкой наименований и только при однозначном совпадении. ВНИМАНИЕ: запись с Name — повод проверить вручную, а не готовый вывод.",
            "example": "Tin"
          },
          "details": {
            "type": "array",
            "description": "Поля, которых нет в общей части: подпись и значение дословно из источника, в порядке показа. Пустой список — таких полей у записи нет.",
            "items": {
              "$ref": "#/components/schemas/CompanyLicenseDetail"
            }
          }
        }
      },
      "SanctionMatch": {
        "type": "object",
        "description": "Подтверждённое совпадение компании, её руководителя или учредителя с записью санкционного либо дебарментного списка. Спорные и отклонённые совпадения наружу не отдаются.",
        "required": [
          "source",
          "listedName",
          "subjectType",
          "matchedSubject",
          "confidence",
          "sourceCount",
          "subjectKey",
          "isActive"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "Источник списка человекочитаемо.",
            "example": "Госфинразведка КР (национальный список)"
          },
          "listedName": {
            "type": "string",
            "description": "Наименование субъекта в списке, дословно из источника."
          },
          "listingBasis": {
            "type": "string",
            "nullable": true,
            "description": "Основание включения в список, если источник его указывает."
          },
          "subjectType": {
            "type": "string",
            "description": "Тип субъекта записи в списке.",
            "enum": [
              "person",
              "entity",
              "unknown"
            ]
          },
          "matchedSubject": {
            "type": "string",
            "description": "Чьё имя в компании совпало со списком.",
            "enum": [
              "company",
              "director",
              "founder"
            ]
          },
          "confidence": {
            "type": "integer",
            "description": "Уверенность совпадения, 0–100.",
            "minimum": 0,
            "maximum": 100
          },
          "sourceCount": {
            "type": "integer",
            "description": "Сколько независимых источников подтверждают субъект."
          },
          "subjectKey": {
            "type": "string",
            "description": "Ключ субъекта: нормализованное имя записи. У совпадений с одним и тем же фигурантом он одинаков — по нему записи об одном субъекте из разных списков склеиваются в одну.",
            "example": "kejdzhi impeks"
          },
          "isActive": {
            "type": "boolean",
            "description": "Действует ли санкция сейчас. false — субъект снят с санкций, совпадение историческое."
          },
          "delistedDate": {
            "type": "string",
            "example": "2019-04-12T00:00:00",
            "nullable": true,
            "description": "Дата снятия с санкций, если совпадение историческое."
          }
        }
      },
      "RiskFactor": {
        "type": "object",
        "description": "Один признак, учитываемый в оценке риска. СХЕМА НЕ ИСПОЛЬЗУЕТСЯ, пока расчёт оценки риска отключён: объект `RiskScore`, внутри которого живут признаки, сейчас не строится ни для одной компании (см. `CompanyDossier.riskScore`). Описание сохранено, чтобы контракт не менялся, когда расчёт вернут.",
        "required": [
          "code",
          "description",
          "score",
          "maxScore",
          "isTriggered"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Код признака. Перечень кодов не зафиксирован: пока расчёт отключён, ни один код наружу не отдаётся, и примера здесь намеренно нет — выдуманный пример читался бы как обещание конкретного признака."
          },
          "description": {
            "type": "string",
            "description": "Пояснение на русском языке."
          },
          "score": {
            "type": "integer",
            "description": "Начисленный балл; 0, если признак не сработал."
          },
          "maxScore": {
            "type": "integer",
            "description": "Максимально возможный балл этого признака."
          },
          "isTriggered": {
            "type": "boolean",
            "description": "Сработал ли признак."
          }
        }
      },
      "RiskScore": {
        "type": "object",
        "description": "Оценка риска компании. СХЕМА НЕ ИСПОЛЬЗУЕТСЯ: расчёт отключён, и поле `CompanyDossier.riskScore` сейчас приходит пустым по любой компании. Описание формы сохранено, чтобы контракт не менялся, когда расчёт вернут; строить логику на этих полях пока нельзя.",
        "required": [
          "totalScore",
          "level",
          "factors"
        ],
        "properties": {
          "totalScore": {
            "type": "integer",
            "description": "Итоговый балл: 0 — минимальный риск, 100 — максимальный.",
            "minimum": 0,
            "maximum": 100
          },
          "level": {
            "type": "integer",
            "description": "Уровень риска числом: 0 — низкий, 1 — средний, 2 — высокий, 3 — критический.",
            "enum": [
              0,
              1,
              2,
              3
            ]
          },
          "factors": {
            "type": "array",
            "description": "Разбор по признакам: какие сработали и на сколько баллов.",
            "items": {
              "$ref": "#/components/schemas/RiskFactor"
            }
          }
        }
      },
      "DataFreshness": {
        "type": "object",
        "description": "Когда мы последний раз обращались к источникам по этой компании и есть ли сохранённые документы. Позволяет отличить «источник ещё не запрашивали» от «проверили, данных нет». Объект в ответе есть всегда; пустыми бывают только отдельные даты внутри него.",
        "required": [
          "hasExtractPdf",
          "hasCertificatePdf"
        ],
        "properties": {
          "profileCheckedAt": {
            "type": "string",
            "example": "2026-08-25T04:11:07",
            "nullable": true,
            "description": "Последняя сверка регистрационного профиля; null — компанию ещё ни разу не сверяли."
          },
          "taxCheckedAt": {
            "type": "string",
            "example": "2026-08-25T04:11:07",
            "nullable": true,
            "description": "Последнее обращение к налоговым источникам."
          },
          "documentsCheckedAt": {
            "type": "string",
            "example": "2026-08-25T04:11:07",
            "nullable": true,
            "description": "Последняя загрузка PDF-документов."
          },
          "hasExtractPdf": {
            "type": "boolean",
            "description": "Есть ли сохранённая выписка в PDF."
          },
          "hasCertificatePdf": {
            "type": "boolean",
            "description": "Есть ли сохранённое свидетельство в PDF."
          }
        }
      },
      "CompanyDossier": {
        "type": "object",
        "description": "Полное досье компании — ответ партнёрского API. Поле, по которому данных нет, приходит со значением null, а список — пустым; это не ошибка, а неравномерная заполненность реестров.",
        "required": [
          "tin"
        ],
        "properties": {
          "tin": {
            "type": "string",
            "description": "ИНН компании."
          },
          "recordId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Идентификатор записи в реестре Минюста."
          },
          "registrationNumber": {
            "type": "string",
            "nullable": true,
            "description": "Регистрационный номер."
          },
          "statNo": {
            "type": "string",
            "nullable": true,
            "description": "Код ОКПО."
          },
          "fullNameRu": {
            "type": "string",
            "nullable": true,
            "description": "Полное наименование на русском языке."
          },
          "shortNameRu": {
            "type": "string",
            "nullable": true,
            "description": "Сокращённое наименование на русском языке."
          },
          "fullNameKy": {
            "type": "string",
            "nullable": true,
            "description": "Полное наименование на кыргызском языке."
          },
          "fullNameEn": {
            "type": "string",
            "nullable": true,
            "description": "Полное наименование на английском языке."
          },
          "directorName": {
            "type": "string",
            "nullable": true,
            "description": "ФИО руководителя."
          },
          "orderDate": {
            "type": "string",
            "example": "2019-04-12T00:00:00",
            "nullable": true,
            "description": "Дата приказа Минюста."
          },
          "primaryRegistrationDate": {
            "type": "string",
            "example": "2019-04-12T00:00:00",
            "nullable": true,
            "description": "Дата первичной регистрации."
          },
          "reRegistrationDate": {
            "type": "string",
            "example": "2019-04-12T00:00:00",
            "nullable": true,
            "description": "Дата перерегистрации."
          },
          "liquidationDate": {
            "type": "string",
            "example": "2019-04-12T00:00:00",
            "nullable": true,
            "description": "Дата прекращения деятельности; null — компания не ликвидирована."
          },
          "registrationType": {
            "type": "string",
            "nullable": true,
            "description": "Тип последнего регистрационного действия: «Регистрация» или «Перерегистрация». Не путать со state."
          },
          "state": {
            "type": "string",
            "nullable": true,
            "description": "Текущий статус компании.",
            "example": "REGISTERED"
          },
          "denyReregistration": {
            "type": "boolean",
            "description": "Установлен запрет на перерегистрацию."
          },
          "denyElimination": {
            "type": "boolean",
            "description": "Установлен запрет на ликвидацию."
          },
          "denyNotification": {
            "type": "boolean",
            "description": "Установлен запрет на выдачу извещений."
          },
          "legalForm": {
            "type": "string",
            "nullable": true,
            "description": "Организационно-правовая форма."
          },
          "ownershipForm": {
            "type": "string",
            "nullable": true,
            "description": "Форма собственности."
          },
          "hasForeignCapital": {
            "type": "boolean",
            "description": "Есть ли иностранное участие в капитале."
          },
          "mainActivity": {
            "type": "string",
            "nullable": true,
            "description": "Основной вид деятельности текстом."
          },
          "okedCode": {
            "type": "string",
            "nullable": true,
            "description": "Код вида деятельности (ОКЭД)."
          },
          "regionCode": {
            "type": "string",
            "nullable": true,
            "description": "Код региона, вычислен из юридического адреса; null — адрес не распознан."
          },
          "okedSection": {
            "type": "string",
            "nullable": true,
            "description": "Буква раздела ОКЭД (A–U); null — код не распознан."
          },
          "bankruptcyStatus": {
            "type": "string",
            "nullable": true,
            "description": "Статус из реестра банкротств; null — компании там нет."
          },
          "hasDebt": {
            "type": "boolean",
            "description": "Числится ли за компанией налоговая задолженность."
          },
          "sanctions": {
            "type": "array",
            "description": "Подтверждённые санкционные совпадения; пустой список — совпадений нет.",
            "items": {
              "$ref": "#/components/schemas/SanctionMatch"
            }
          },
          "licenses": {
            "type": "array",
            "description": "Лицензии и разрешения компании из всех реестров, которые мы загружаем, одним списком: вид реестра назван в самой записи (поле kind), поэтому новый реестр не добавляет в ответ новых полей. Ограничения (приостановки, аннулирования) лежат здесь же — со статусом Restricted. Пустой список — ни в одном реестре компания не значится. Записи, пропавшие из источника, сюда не попадают.",
            "items": {
              "$ref": "#/components/schemas/CompanyLicense"
            }
          },
          "lastCheckedAt": {
            "type": "string",
            "example": "2026-08-25T04:11:07",
            "nullable": true,
            "description": "Дата последней сверки данных с реестром; null — компанию ещё ни разу не сверяли."
          },
          "freshness": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DataFreshness"
              }
            ],
            "description": "Признаки сбора по этой компании. Объект приходит ВСЕГДА, даже если по компании ещё ничего не собирали: в этом случае пустыми будут отдельные даты внутри него. Проверять на null сам объект не нужно — проверяйте его поля."
          },
          "riskScore": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RiskScore"
              }
            ],
            "nullable": true,
            "description": "Оценка риска. СЕЙЧАС ВСЕГДА null: расчёт оценки риска отключён, и пустое значение приходит по любой компании. Поле оставлено в ответе, чтобы контракт не менялся, когда расчёт вернут; форма объекта описана в схеме RiskScore. Строить логику на этом поле нельзя."
          },
          "location": {
            "nullable": true,
            "description": "Точка юридического адреса на карте. ВСЕГДА null: партнёрам она не отдаётся (решение владельца 2026-09-13). Поле есть в ответе, чтобы контракт не менялся; строить логику на нём нельзя."
          },
          "constructionObjects": {
            "type": "array",
            "description": "Стройки из реестра объектов Минстроя. ВСЕГДА пустой список: партнёрам они не отдаются (решение владельца 2026-09-13). Поле оставлено ради стабильности контракта; строить логику на нём нельзя.",
            "items": {}
          },
          "founders": {
            "type": "array",
            "description": "Учредители компании; пустой список — сведений нет.",
            "items": {
              "$ref": "#/components/schemas/Founder"
            }
          },
          "actualAddress": {
            "type": "string",
            "nullable": true,
            "description": "Фактический адрес."
          },
          "workPhone": {
            "type": "string",
            "nullable": true,
            "description": "Рабочий телефон."
          },
          "email": {
            "type": "string",
            "nullable": true,
            "description": "Электронная почта."
          },
          "bankName": {
            "type": "string",
            "nullable": true,
            "description": "Наименование банка."
          },
          "accountNumber": {
            "type": "string",
            "nullable": true,
            "description": "Расчётный счёт."
          },
          "bic": {
            "type": "string",
            "nullable": true,
            "description": "БИК банка."
          },
          "isRegisteredSupplier": {
            "type": "boolean",
            "description": "Был ли признак «зарегистрирована поставщиком на портале госзакупок» на момент последнего сбора. ЗАМОРОЖЕННЫЙ СНИМОК, а не текущее состояние: сборщик, который заполнял это поле, снят, новые записи не появляются и старые не обновляются. Возраст значения по конкретной компании неизвестен — как источник сведений о госзакупках поле использовать нельзя."
          },
          "taxAuthorityCode": {
            "type": "string",
            "nullable": true,
            "description": "Код налогового органа (УГНС)."
          },
          "taxAuthorityShortName": {
            "type": "string",
            "nullable": true,
            "description": "Краткое наименование налогового органа."
          },
          "taxAuthorityFullName": {
            "type": "string",
            "nullable": true,
            "description": "Полное наименование налогового органа."
          }
        }
      }
    }
  }
}