Mark GreenEngine — входящий API программы. Руководство интегратора

Руководство описывает HTTP API, который программа Mark GreenEngine открывает на компьютере пользователя для учётной системы, кассового ПО, панели или собственного сервиса. Все поля, коды и тексты ниже взяты из кода сборки 2.2.0, а примеры ответов — из прогона этой сборки на изолированном стенде (раздел 12).

Уровни проверки, которые указаны в карточках:

• код — поведение установлено по исходному коду сборки 78ca5a8;
• стенд — запрос выполнен на настоящих сборках API выпуска 2.2.0 (GE.TrueApi.Server.dll, GE.TrueApi.Core.dll из ZIP выпуска, хэши совпали с его MANIFEST): Kestrel, сертификат, api_keys.json, роли, лимиты, менеджер токенов, учёт кег, документы CONNECT_TAP и проверка КМ — настоящие; ГИС МТ, КриптоПро, панель и центр лицензирования заменены синтетическими;
• не проверено — обмен с настоящей ГИС МТ, подписью КриптоПро и центром лицензирования в рамках этого документа не выполнялся.

Оглавление

1. Карта взаимодействий
2. Назначение и совместимость
3. Подготовка программы
4. Быстрый старт
5. Общий контракт
6. Авторизация, роли, организации и лицензия
7. Каталог методов
8. Карточки методов
9. Практические сценарии
10. Длительные операции и повторы
11. Ошибки и устранение проблем
12. Совместимость, ограничения и найденные расхождения
13. Как проверялся этот документ

0. Карта взаимодействий

Протокол входящего API — набор HTTP-маршрутов под общим префиксом /api/v1 с JSON-телами. Отдельного поля «команда» или JSON-RPC нет: операция определяется HTTP-методом и путём.

1. Назначение и совместимость

Через входящий API внешняя система может:

• узнать состояние и получить действующий токен ГИС МТ организации (для собственных запросов в True API);
• подключить кеги пива к оборудованию для розлива (документ CONNECT_TAP) и отследить результат обработки;
• вести учёт кег на кранах: список, одна кега, постановка на учёт и снятие, остатки разливного по адресам ФИАС;
• проверить коды маркировки — сведения ГИС МТ и оценку «можно ли продать».

История контракта /api/v1 по коду (новые поля и методы только добавлялись):

2. Подготовка программы

2.1. Включить API

В новой установке 2.2.0 API выключен: при сборке дистрибутива в appsettings.json записывается "Server": { "Enabled": false }. Включите одним из способов:

1. В программе: «⋯» → «Настройки» → «Входящий API» → «Принимать запросы от панели и магазинов», сохранить, перезапустить программу (настройки раздела действуют после перезапуска, в окне они помечены знаком ⟳).
2. Или в файле appsettings.Local.json рядом с MarkGreenEngine.exe (образец — appsettings.Local.example.json):

json { "Server": { "Enabled": true } }

и перезапустить программу. Значения из appsettings.Local.json перекрывают appsettings.json.

Состояние сервера видно на вкладке «API-журнал»: адрес вида https://<имя компьютера>:8443/api/v1 или причина, по которой API не запущен (например, «порт 8443 уже занят другой программой»). Если Server:Enabled = false, там написано «Server:Enabled = false в appsettings.json».

2.2. Настройки раздела Server

Переменные окружения (ASPNETCORE_URLS и т. п.) и секция Kestrel на входящий API не влияют. Активные значения видны в окне «Настройки», фактический адрес и порт — на вкладке «API-журнал».

Одновременно на одном порту может работать только одна копия программы с включённым API, даже у разных пользователей Windows. Второй копии задайте другой порт.

2.3. Сертификат и закрепление

При первом запуске API с AutoCertificate = true программа создаёт самоподписанный сертификат CN=GE-TrueAPI (RSA, SHA-256, срок 5 лет) в файле server.pfx (пароль — в server.pfx.key, зашифрован DPAPI пользователя Windows). В сертификат записываются имена localhost, имя компьютера, 127.0.0.1, ::1 и значения Server:ExtraHostNames.

Сертификат не выдан доверенным центром, поэтому клиент не может проверить цепочку обычным способом и должен проверять, что отвечает именно этот сервер:

• pin открытого ключа — sha256//<base64>; это формат curl --pinnedpubkey и CURLOPT_PINNEDPUBLICKEY;
• либо отпечаток SHA-256 сертификата — AB:CD:…;
• либо сертификат, сохранённый как доверенный файл (для 1С, examples/1c).

Pin, отпечаток, адрес API, команда брандмауэра и готовая команда curl показаны в окне «⋯» → «Сертификат и подключение API…» (также кнопка на вкладке «API-журнал»).

• Если при запуске API (запуск программы или её перезапуск) до окончания срока сертификата меньше 30 дней, программа продлевает его с тем же ключом: pin не меняется, отпечаток меняется. Во время работы срок не проверяется — если программа работает без перезапуска, сертификат может истечь. Клиенты, закрепившие отпечаток или сохранившие файл сертификата (1С), после продления должны их обновить; закрепление по pin продление переживает.
• ExtraHostNames записываются в сертификат только при его создании. Если вы добавили имя позже, удалите server.pfx и server.pfx.key и перезапустите программу. Будет создан новый ключ, pin изменится — обновите его у всех клиентов.
• Свой сертификат (AutoCertificate = false, свой PfxPath/PfxPassword) программа не продлевает, только предупреждает в журнале.

2.4. Брандмауэр и сеть

Для доступа с другого компьютера откройте порт в брандмауэре Windows (командная строка от имени администратора; та же команда с кнопкой «Копировать» есть в окне сертификата):

netsh advfirewall firewall add rule name="Mark GreenEngine 8443" dir=in action=allow protocol=TCP localport=8443

Не публикуйте порт API в интернет и не отключайте ключи ради упрощения: API даёт доступ к токенам ГИС МТ и действиям от имени организаций. Для удалённых точек используйте VPN; дополнительно ограничьте ключ адресами (allowed_ips, 5.2).

2.5. Ключи доступа

Ключи хранятся в api_keys.json рядом с MarkGreenEngine.exe и редактируются в «Настройки» → «Ключи API» (кнопки «Добавить», «Новый ключ», «Организации…»). Если файла нет, при первом открытии окна ключей он создаётся из api_keys.example.json со случайными ключами и без ограничений по адресам. Файл перечитывается автоматически через ~0,5 с после сохранения — перезапуск не нужен. Формат — 5.2.

3. Быстрый старт

Пример — на компьютере с программой (localhost) и порте 8443. В других случаях подставьте адрес из вкладки «API-журнал».

Шаг 1. Проверьте доступность (ключ не нужен). Pin возьмите из окна «Сертификат и подключение API». Команда для cmd.exe и PowerShell одинакова (в PowerShell пишите именно curl.exe, а не curl — это другая команда):

curl.exe --insecure --pinnedpubkey "sha256//<pin из окна программы>" https://localhost:8443/api/v1/health

Ожидаемый ответ (version — версия и commit вашей сборки, environment — среда ГИС МТ из настройки TrueApi:Environment):

{
  "status": "ok",
  "version": "2.2.0+78ca5a874c6e8094da14024f2094857960bdcd54",
  "uptime_seconds": 0,
  "environment": "prod"
}

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

Шаг 2. Получите ключ. В «Настройки» → «Ключи API» добавьте ключ, выберите роль (panel — все методы, retail — чтение кег и проверка кодов) и организации. Сохраните значение ключа в файл, а не в командную строку: файл mge-api-key.txt с одной строкой

X-Api-Key: <значение ключа>

и закройте к нему доступ другим пользователям (icacls mge-api-key.txt /inheritance:r /grant:r "%USERNAME%:R").

Шаг 3. Первый запрос с ключом — список организаций и состояние их токенов (роль panel). -H @файл читает заголовок из файла, значение ключа не попадает в командную строку и историю:

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt https://localhost:8443/api/v1/tokens

[
  {
    "client": "ООО «Пример»",
    "inn": "0100000001",
    "enabled": true,
    "status": "active",
    "expire_date": "2026-11-01T19:00:00+00:00",
    "next_rotation": "2026-11-01T18:00:00+00:00"
  },
  {
    "client": "ИП Образцов О. О.",
    "inn": "010000000001",
    "enabled": true,
    "status": "active",
    "expire_date": "2026-11-01T19:00:00+00:00",
    "next_rotation": "2026-11-01T18:00:00+00:00"
  },
  {
    "client": "ООО «Без права»",
    "inn": "0100000003",
    "enabled": true,
    "status": "not_received",
    "next_rotation": "2026-11-01T09:00:00+00:00"
  },
  {
    "client": "ООО «Нет связи»",
    "inn": "0100000004",
    "enabled": true,
    "status": "error",
    "next_rotation": "2026-11-01T09:01:00+00:00",
    "last_error": "ГИС МТ: сервис временно недоступен (HTTP 503)"
  },
  {
    "client": "ООО «Отключено»",
    "inn": "0100000005",
    "enabled": false,
    "status": "disabled",
    "next_rotation": "2026-11-01T09:00:00+00:00"
  },
  {
    "client": "ООО «Нет сертификата»",
    "inn": "0100000006",
    "enabled": true,
    "status": "cert_error",
    "last_error": "Сертификат с серийным номером STAND06 не найден в хранилище «Личное»"
  }
]

Значение client из этого ответа — имя организации, которое передаётся в остальные методы.

Шаг 4. Типичные причины неуспеха.

Готовые сценарии на PowerShell и 1С — api/examples.

4. Общий контракт

4.1. Транспорт

4.2. JSON

• Имена полей — snake_case (client, connect_date, uuid_token).
• Имена полей в теле запроса сверяются без учёта регистра, но camelCase не распознаётся: connectDate вместо connect_date молча игнорируется, и программа подставляет значение по умолчанию. Неизвестные поля игнорируются без ошибки (сценарий connect-camelcase в отчёте проверки).
• Поле со значением null в ответе не выводится — кроме полей, где это оговорено в карточке (cis в /codes/check, sale_allowed, fias_id и литры в /kegs/rests/fias). Отсутствие поля и null в ответе означают одно и то же — «значения нет».
• Перечисления (status, outcome, sale_status …) — строки в snake_case. Числа вместо строк не принимаются.
• ИНН, КПП, GTIN, коды маркировки, идентификаторы документов — всегда строки. Не преобразуйте их в числа: потеряете ведущие нули ("010000000001").
• Кириллица в ответах не экранируется. Управляющие символы экранируются: символ GS в коде маркировки приходит как \u001D.
• Ответ на некорректный JSON: 400 validation_failed, message «Некорректный JSON в теле запроса», details — путь к полю («Некорректное значение поля $.codes[0].connect_date») или «Тело запроса не является корректным JSON-объектом».

4.3. Даты, время, количества

4.4. Коды маркировки в запросе

Методы кег (/kegs*, connect, track) приводят код к виду КИ «01» + GTIN (14 цифр) + «21» + серийный номер (1–20 символов ASCII с кодами 33–122, то есть печатные символы, кроме {, |, }, ~) и отбрасывают криптохвост. Принимаются:

• префиксы сканера ]C1, ]d2, ]Q3, ведущий символ FNC1/GS;
• разделитель GS как символ \u001d (в JSON), или текстом <GS>, \x1d, \u001d;
• скобочная запись (01)…(21)…(91)…(92)…;
• код кеги пива без разделителя — ровно 31 символ, где после КИ (25 символов) идут «93» и 4 символа проверки.

/codes/check разбирает шире: дополнительно русскую раскладку сканера, КИТУ (18 цифр, 00+18, (00)+18) и прочие коды ГИС МТ из 18–74 печатных символов.

Код в пути (/kegs/{cis}) кодируйте целиком как компонент URL (encodeURIComponent, Uri.EscapeDataString, КодироватьСтроку(…, СпособКодированияСтроки.КодировкаURL)): / → %2F, GS → %1D, % → %25, ? → %3F, # → %23, + → %2B. Код в query (/codes/check?cis=) кодируется так же: незакодированный + превратится в пробел. Коды со спецсимволами удобнее передавать в теле POST.

4.5. Формат ошибки

Любой ответ с кодом 4xx/5xx, кроме оборванных соединений, — объект:

{
  "error": "validation_failed",
  "message": "Ошибка проверки данных",
  "details": [
    "Некорректный код маркировки: «12345» (проверьте раскладку клавиатуры сканера: латиница, без CapsLock)",
    "Для юрлица обязателен КПП торговой точки (9 цифр, в 5-6 позиции допустимы буквы A-Z по формату ФНС)",
    "Для юрлица ФИАС не указывается",
    "КИ 010460000000001021FoR0001: дата подключения 05.11.2026 позже сегодняшней"
  ]
}

Клиент закрыл соединение до ответа — в журнале программы запрос записывается с кодом 499; клиент ответа не получает.

4.6. Лимиты частоты

Окно — фиксированная минута (не скользящая), очереди нет: лишний запрос сразу получает 429.

Когда с адреса набралось 30 неудачных попыток, до конца минуты, отсчитанной от первой из них, адрес получает 429 на любой запрос (начиная с 31-го), даже с верным ключом. Такие отказы не пишутся в журнал запросов, в журнал программы — одно предупреждение. GET /health эта блокировка не затрагивает.

{
  "error": "rate_limited",
  "message": "Превышен лимит запросов, повторите позже"
}

Заголовок Retry-After — целое число секунд до конца окна (в примере 60).

4.7. Журнал

Программа хранит последние 500 запросов (время, имя ключа, IP, метод, путь без query-строки, код ответа, длительность) — вкладка «API-журнал», и пишет их в файл logs/api-ГГГГММДД.log. Значения ключей, токены, query-строки и тела запросов в журнал не попадают. Имя организации из пути (/kegs/{cis} содержит только код) не записывается; query-строка с client не пишется.

5. Авторизация, роли, организации и лицензия

5.1. Какие ключи бывают — не путайте

5.2. Файл api_keys.json

Массив объектов (допускаются комментарии // и завершающие запятые):

[
  { "name": "accounting", "key": "<случайная строка от 32 символов>", "role": "panel", "clients": ["*"], "allowed_ips": ["192.168.10.5"] },
  { "name": "shop-1", "key": "<случайная строка от 32 символов>", "role": "retail", "clients": ["ИП Образцов О. О."] }
]

Некорректный элемент пропускается (ошибка — в журнале программы, значение ключа в ошибку не попадает); остальные ключи действуют. Если файл целиком не разобран, остаются прежние ключи. Если файла нет — все запросы, кроме /health, получают 401.

Сервер хранит только SHA-256 ключа и сравнивает его за постоянное время. Отзыв ключа — удалить элемент или сменить key и сохранить файл: изменение действует через ~0,5 с.

5.3. Роли и организации

Порядок проверок: блокировка адреса за неудачные попытки (429) → ключ (401) → адрес из allowed_ips (403) → лимит ключа (429) → роль метода (403 «Метод доступен только ключам с ролью panel») → разбор параметров и тела (400) → организация (403 «Нет доступа к организации …», 404) → проверки данных метода (400) → лицензия организации (403 license_denied, только у методов, которые обращаются в ГИС МТ). Поэтому, например, POST /kegs/connect с ошибками в данных для организации без права получит 400, а не 403 license_denied: лицензия проверяется непосредственно перед обращением в ГИС МТ.

Параметр client — имя организации, как оно задано в профиле программы (поле client в GET /tokens), сравнивается без учёта регистра. ИНН вместо имени не принимается. Методы, которые читают данные нескольких организаций (GET /kegs, GET /kegs/rests/fias, GET /tokens), без client возвращают только организации, доступные ключу. Данные организаций, к которым у ключа нет доступа, в ответах скрыты: кега или документ такой организации даёт 404, как будто их нет. Исключение — POST /kegs/track (11.3, Д-2).

5.4. Лицензия (LicenseGate) и несколько организаций

С версии 2.2.0 каждая операция, которая обращается в ГИС МТ от имени организации, разрешается программой только при действующем праве этой организации — его выдаёт центр лицензирования по ключу подключения программы. Право — у каждой организации (ИНН) своё. Один ключ подключения и одна подписка аккаунта не означают права для всех организаций копии: у организации без пробного периода или оплаты операции запрещены, даже если у соседней организации всё оплачено.

Ответ license_denied: message — причина по-русски, details[0] — код причины программы, details[1] — код причины центра (может быть пустой строкой):

{
  "error": "license_denied",
  "message": "Нет действующего права организации (ЮЛ ИНН 0100000003): нет пробного периода или оплаты. Операция: запрос в ГИС МТ / ЭДО Лайт.",
  "details": [
    "RightDenied",
    "no_subscription"
  ]
}

Коды центра в details[1]: no_subscription (нет пробного периода или оплаты), expired, subscription_blocked, organization_unverified (организация не подтверждена УКЭП в кабинете), organization_archived, not_in_account (организация не добавлена в аккаунт), license_required, license_invalid, license_revoked, account_blocked, install_disabled, installation_key_mismatch, installation_revoked; может прийти и новый код — показывайте message.

Ответ license_denied — окончательный для этой минуты: повторять запрос имеет смысл только после устранения причины (для NotRequested и KeyChanged — через минуту). Недоступность центра сама по себе не запрещает операции: решает последний проверенный ответ центра и его сроки (до 72 часов без связи).

Серверная настройка центра licensing.enforce_api к этому механизму программы не относится: она управляет проверкой на стороне сайта для старых копий программы. По последнему известному состоянию (отчёт MGE-WEB-007B, 01.11.2026) она выключена; на работу LicenseGate программы 2.2.0 это не влияет.

6. Каталог методов

Все пути — от /api/v1. «Роль» — минимальная роль: метод с ролью retail доступен и ключам panel.

Других маршрутов в 2.2.0 нет: нет списка документов, нет методов ЭДО, ЕГАИС и чеков. Алиасов и устаревших маршрутов нет. Машиночитаемый реестр — api/api-methods.json, формальная схема — api/openapi.yaml.

7. Карточки методов

Примеры запросов показаны для curl.exe с файлом заголовка ключа из раздела 3; <pin> — pin из окна программы. Все организации, ИНН, коды и токены в примерах вымышлены. Ответы — дословно из прогона на стенде (раздел 12), включая порядок полей.

7.1. GET /health — проверка доступности

Ответ 200

curl.exe --insecure --pinnedpubkey "sha256//<pin>" https://localhost:8443/api/v1/health

{
  "status": "ok",
  "version": "2.2.0+78ca5a874c6e8094da14024f2094857960bdcd54",
  "uptime_seconds": 0,
  "environment": "prod"
}

Ошибки: 429 rate_limited — превышен лимит с адреса. Если программа не запущена или API выключен — нет TCP-соединения.

7.2. GET /tokens — организации и состояние токенов

Ответ 200 — массив в порядке профилей программы:

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt https://localhost:8443/api/v1/tokens

[
  {
    "client": "ООО «Пример»",
    "inn": "0100000001",
    "enabled": true,
    "status": "active",
    "expire_date": "2026-11-01T19:00:00+00:00",
    "next_rotation": "2026-11-01T18:00:00+00:00"
  },
  {
    "client": "ИП Образцов О. О.",
    "inn": "010000000001",
    "enabled": true,
    "status": "active",
    "expire_date": "2026-11-01T19:00:00+00:00",
    "next_rotation": "2026-11-01T18:00:00+00:00"
  },
  {
    "client": "ООО «Без права»",
    "inn": "0100000003",
    "enabled": true,
    "status": "not_received",
    "next_rotation": "2026-11-01T09:00:00+00:00"
  },
  {
    "client": "ООО «Нет связи»",
    "inn": "0100000004",
    "enabled": true,
    "status": "error",
    "next_rotation": "2026-11-01T09:01:00+00:00",
    "last_error": "ГИС МТ: сервис временно недоступен (HTTP 503)"
  },
  {
    "client": "ООО «Отключено»",
    "inn": "0100000005",
    "enabled": false,
    "status": "disabled",
    "next_rotation": "2026-11-01T09:00:00+00:00"
  },
  {
    "client": "ООО «Нет сертификата»",
    "inn": "0100000006",
    "enabled": true,
    "status": "cert_error",
    "last_error": "Сертификат с серийным номером STAND06 не найден в хранилище «Личное»"
  }
]

Ошибки: 401, 403 forbidden (ключ retail — «Метод доступен только ключам с ролью panel»), 429.

{
  "error": "forbidden",
  "message": "Метод доступен только ключам с ролью panel"
}

7.3. GET /tokens/current — действующий токен организации

Параметры

Ответ 200

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt "https://localhost:8443/api/v1/tokens/current?client=%D0%9E%D0%9E%D0%9E%20%C2%AB%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80%C2%BB"

(client=ООО «Пример» в URL-кодировке.)

{
  "client": "ООО «Пример»",
  "uuid_token": "00000000-0000-4000-a000-000000000001",
  "expire_date": "2026-11-01T19:00:00+00:00",
  "status": "active"
}

Ошибки

{
  "error": "token_unavailable",
  "message": "ГИС МТ: сервис временно недоступен (HTTP 503)"
}

{
  "error": "signing_failed",
  "message": "Сертификат с серийным номером STAND06 не найден в хранилище «Личное»"
}

7.4. POST /tokens/rotate — перевыпустить токен

Параметры, ответ и ошибки — как у 7.3. Если ГИС МТ ответила без токена — 503 token_unavailable «ГИС МТ не вернула токен».

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt -X POST "https://localhost:8443/api/v1/tokens/rotate?client=%D0%9E%D0%9E%D0%9E%20%C2%AB%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80%C2%BB"

{
  "client": "ООО «Пример»",
  "uuid_token": "00000000-0000-4000-a000-000000000001",
  "expire_date": "2026-11-01T19:00:00+00:00",
  "status": "active"
}

7.5. POST /kegs/connect — подключить кеги к оборудованию (CONNECT_TAP)

Параметры (тело)

Тип организации определяется по ИНН: 10 цифр — юрлицо (нужен КПП), 12 — ИП (нужен ФИАС). Пустая строка в kpp/fias_id равнозначна отсутствию поля: берётся значение по умолчанию из профиля.

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt -H "Content-Type: application/json" --data-binary @connect.json https://localhost:8443/api/v1/kegs/connect

connect.json (UTF-8):

{
  "client": "ООО «Пример»",
  "codes": [
    {
      "cis": "010460000000001021NeW0001",
      "connect_date": "2026-11-01",
      "expiration_date": "2026-12-31"
    }
  ]
}

Ответ 202 Accepted, заголовок Location: /api/v1/documents/<doc_id>:

{
  "doc_id": "00000000-0000-4000-9000-000000000001",
  "status": "IN_PROGRESS",
  "codes": [
    {
      "cis": "010460000000001021NeW0001",
      "connect_date": "2026-11-01",
      "expiration_date": "2026-12-31"
    }
  ]
}

Ошибки

{
  "error": "validation_failed",
  "message": "Ошибка проверки данных",
  "details": [
    "КИ 010460000000001021NeW0001: уже отправлен в документе 00000000-0000-4000-9000-000000000001, ожидается результат"
  ]
}

{
  "error": "validation_failed",
  "message": "Ошибка проверки данных",
  "details": [
    "Сертификат с серийным номером STAND06 не найден в хранилище «Личное»"
  ]
}

{
  "error": "license_denied",
  "message": "Нет действующего права организации (ЮЛ ИНН 0100000003): нет пробного периода или оплаты. Операция: запрос в ГИС МТ / ЭДО Лайт.",
  "details": [
    "RightDenied",
    "no_subscription"
  ]
}

{
  "error": "validation_failed",
  "message": "Некорректный JSON в теле запроса",
  "details": [
    "Некорректное значение поля $.codes[0].connect_date"
  ]
}

7.6. GET /documents/{doc_id} — статус документа CONNECT_TAP

Параметры: doc_id в пути — значение из ответа connect.

Ответ 200

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt https://localhost:8443/api/v1/documents/00000000-0000-4000-9000-000000000001

Сразу после отправки:

{
  "doc_id": "00000000-0000-4000-9000-000000000001",
  "client": "ООО «Пример»",
  "status": "IN_PROGRESS",
  "status_text": "Проверяется",
  "errors": [],
  "codes": [
    {
      "cis": "010460000000001021NeW0001",
      "connect_date": "2026-11-01",
      "expiration_date": "2026-12-31"
    }
  ],
  "submitted_at": "2026-11-01T09:00:00+00:00"
}

После обработки:

{
  "doc_id": "00000000-0000-4000-9000-000000000001",
  "client": "ООО «Пример»",
  "status": "CHECKED_OK",
  "status_text": "Обработан",
  "errors": [],
  "codes": [
    {
      "cis": "010460000000001021NeW0001",
      "connect_date": "2026-11-01",
      "expiration_date": "2026-12-31"
    }
  ],
  "submitted_at": "2026-11-01T09:00:00+00:00",
  "completed_at": "2026-11-01T09:00:10+00:00"
}

Ошибки: 404 not_found — документ не найден, удалён после 7 суток или принадлежит организации, недоступной ключу.

{
  "error": "not_found",
  "message": "Документ 00000000-0000-4000-9000-999999999999 не найден"
}

7.7. GET /kegs — кеги на учёте

Параметры: query client — необязателен. Организация с таким именем может и не существовать: тогда ответ — пустой массив.

Ответ 200 — массив объектов «кега» (поле last_info здесь не выводится):

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt https://localhost:8443/api/v1/kegs

[
  {
    "cis": "010460000000001021AbC1234",
    "client": "ООО «Пример»",
    "product_name": "Пиво светлое фильтрованное, кега 30 л",
    "gtin": "04600000000010",
    "connect_date": "2026-10-28",
    "expiration_date": "2026-12-31",
    "expiration_from_document": true,
    "inner_unit_count": 30000,
    "sold_unit_count": 12500,
    "rest": 17500,
    "rest_percent": 58,
    "status": "INTRODUCED",
    "status_ex": "CONNECT_TAP",
    "source": "connect_tap",
    "doc_id": "00000000-0000-4000-9000-000000000100",
    "updated_at": "2026-11-01T09:00:00+00:00"
  },
  {
    "cis": "010460000000001021AbC1235",
    "client": "ООО «Пример»",
    "product_name": "Пиво светлое фильтрованное, кега 30 л",
    "gtin": "04600000000010",
    "connect_date": "2026-10-30",
    "expiration_date": "2027-01-31",
    "expiration_from_document": false,
    "inner_unit_count": 30000,
    "sold_unit_count": 0,
    "rest": 30000,
    "rest_percent": 100,
    "status": "INTRODUCED",
    "status_ex": "CONNECT_TAP",
    "source": "api",
    "updated_at": "2026-11-01T09:00:00+00:00"
  },
  {
    "cis": "010460000000002721Ip00001",
    "client": "ИП Образцов О. О.",
    "product_name": "Пиво тёмное, кега 50 л",
    "gtin": "04600000000027",
    "connect_date": "2026-10-25",
    "expiration_date": "2027-01-31",
    "expiration_from_document": false,
    "inner_unit_count": 50000,
    "sold_unit_count": 10000,
    "rest": 40000,
    "rest_percent": 80,
    "status": "INTRODUCED",
    "status_ex": "CONNECT_TAP",
    "source": "connect_tap",
    "doc_id": "00000000-0000-4000-9000-000000000101",
    "updated_at": "2026-11-01T09:00:00+00:00"
  },
  {
    "cis": "010460000000003421Ip00002",
    "client": "ИП Образцов О. О.",
    "product_name": "Сидр, кега 20 л",
    "gtin": "04600000000034",
    "connect_date": "2026-10-29",
    "expiration_date": "2027-01-31",
    "expiration_from_document": false,
    "status": "INTRODUCED",
    "status_ex": "CONNECT_TAP",
    "source": "connect_tap",
    "doc_id": "00000000-0000-4000-9000-000000000102",
    "updated_at": "2026-11-01T09:00:00+00:00"
  }
]

Ошибки: 403 forbidden — указана организация, недоступная ключу.

{
  "error": "forbidden",
  "message": "Нет доступа к организации «ООО «Пример»»"
}

7.8. GET /kegs/{cis} — одна кега или сведения ГИС МТ о коде

Параметры

Логика ответа:

1. Код на учёте у организации, доступной ключу → объект «кега» (7.7) плюс last_info — последний ответ ГИС МТ cisInfo без изменений (поля и регистр — как у ГИС МТ, например requestedCis, partialSaleInfo). client игнорируется.
2. Код не на учёте и нет client → 404 «КИ не на учёте; укажите client для запроса в ГИС МТ».
3. Код не на учёте, есть client → живой запрос в ГИС МТ; ответ — объект {cis, client, tracked: false, last_info}.

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt https://localhost:8443/api/v1/kegs/010460000000001021AbC1234

{
  "cis": "010460000000001021AbC1234",
  "client": "ООО «Пример»",
  "product_name": "Пиво светлое фильтрованное, кега 30 л",
  "gtin": "04600000000010",
  "connect_date": "2026-10-28",
  "expiration_date": "2026-12-31",
  "expiration_from_document": true,
  "inner_unit_count": 30000,
  "sold_unit_count": 12500,
  "rest": 17500,
  "rest_percent": 58,
  "status": "INTRODUCED",
  "status_ex": "CONNECT_TAP",
  "source": "connect_tap",
  "doc_id": "00000000-0000-4000-9000-000000000100",
  "updated_at": "2026-11-01T09:00:00+00:00",
  "last_info": {
    "cis": "010460000000001021AbC1234",
    "requestedCis": "010460000000001021AbC1234",
    "gtin": "04600000000010",
    "productName": "Пиво светлое фильтрованное, кега 30 л",
    "status": "INTRODUCED",
    "ownerInn": "0100000001",
    "ownerName": "ООО «Пример»",
    "productGroup": "beer",
    "packageType": "UNIT",
    "producerInn": "0100000008",
    "producerName": "ООО «Пивоварня»",
    "emissionDate": "2026-10-01T09:00:00.000Z",
    "introducedDate": "2026-10-03T09:00:00.000Z",
    "productionDate": "2026-10-02T00:00:00.000Z",
    "expirationDate": "2027-01-31T00:00:00.000Z",
    "statusEx": "CONNECT_TAP",
    "connectDate": "2026-10-28T09:00:00.000Z",
    "partialSaleInfo": {
      "innerUnitCount": 30000,
      "soldUnitCount": 12500,
      "rest": 17500
    }
  }
}

Живой запрос кода не на учёте:

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt "https://localhost:8443/api/v1/kegs/010460000000001021FoR0001?client=%D0%9E%D0%9E%D0%9E%20%C2%AB%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80%C2%BB"

{
  "cis": "010460000000001021FoR0001",
  "client": "ООО «Пример»",
  "tracked": false,
  "last_info": {
    "cis": "010460000000001021FoR0001",
    "requestedCis": "010460000000001021FoR0001",
    "gtin": "04600000000010",
    "productName": "Пиво светлое фильтрованное, кега 30 л",
    "status": "INTRODUCED",
    "ownerInn": "0100000009",
    "ownerName": "ООО «Другая организация»",
    "productGroup": "beer",
    "packageType": "UNIT",
    "producerInn": "0100000008",
    "producerName": "ООО «Пивоварня»",
    "emissionDate": "2026-10-01T09:00:00.000Z",
    "introducedDate": "2026-10-03T09:00:00.000Z",
    "productionDate": "2026-10-02T00:00:00.000Z",
    "expirationDate": "2027-01-31T00:00:00.000Z",
    "statusEx": "CONNECT_TAP",
    "connectDate": "2026-10-20T09:00:00.000Z",
    "partialSaleInfo": {
      "innerUnitCount": 30000,
      "soldUnitCount": 1000,
      "rest": 29000
    }
  }
}

Ошибки

Если ГИС МТ на неизвестный код отвечает элементом с cisInfo и ошибкой «не найден» (так этот ответ смоделирован в тестах программы и на стенде), ответ — 200 с почти пустым last_info (только requestedCis, cis), а не 404: признак «не найден» теряется (11.3, Д-3). Если элемент приходит без cisInfo, ответ — 502 gis_error с текстом ГИС МТ. Какую форму возвращает рабочая ГИС МТ, в этой проверке не установлено. Проверяйте наличие status в last_info или используйте /codes/check.

{
  "cis": "010460000000001021ZzZ9999",
  "client": "ООО «Пример»",
  "tracked": false,
  "last_info": {
    "requestedCis": "010460000000001021ZzZ9999",
    "cis": "010460000000001021ZzZ9999"
  }
}

{
  "error": "validation_failed",
  "message": "Некорректный код маркировки: «12345» (проверьте раскладку клавиатуры сканера: латиница, без CapsLock)"
}

7.9. GET /kegs/rests/fias — остатки разливного по адресам ФИАС

Параметры

Учитываются только кеги со статусом подключения CONNECT_TAP. Адрес известен для кег, подключённых через программу с ФИАС (это ИП); у юрлиц адрес не передаётся, их кеги — в группе fias_id: null.

Ответ 200

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt https://localhost:8443/api/v1/kegs/rests/fias

{
  "generated_at": "2026-11-01T12:00:00+03:00",
  "totals": {
    "kegs": 4,
    "rest_liters": 87.5,
    "volume_liters": 110
  },
  "addresses": [
    {
      "fias_id": "00000000-0000-4000-8000-000000000001",
      "clients": [
        "ИП Образцов О. О."
      ],
      "kegs": 2,
      "rest_liters": 40,
      "volume_liters": 50,
      "products": [
        {
          "gtin": "04600000000027",
          "product_name": "Пиво тёмное, кега 50 л",
          "kegs": 1,
          "rest_liters": 40,
          "volume_liters": 50,
          "rest_unknown": 0,
          "volume_unknown": 0,
          "items": [
            {
              "cis": "010460000000002721Ip00001",
              "client": "ИП Образцов О. О.",
              "rest_liters": 40,
              "volume_liters": 50,
              "connect_date": "2026-10-25",
              "expiration_date": "2027-01-31",
              "updated_at": "2026-11-01T09:00:00+00:00"
            }
          ]
        },
        {
          "gtin": "04600000000034",
          "product_name": "Сидр, кега 20 л",
          "kegs": 1,
          "rest_liters": 0,
          "volume_liters": 0,
          "rest_unknown": 1,
          "volume_unknown": 1,
          "items": [
            {
              "cis": "010460000000003421Ip00002",
              "client": "ИП Образцов О. О.",
              "rest_liters": null,
              "volume_liters": null,
              "connect_date": "2026-10-29",
              "expiration_date": "2027-01-31",
              "updated_at": "2026-11-01T09:00:00+00:00"
            }
          ]
        }
      ]
    },
    {
      "fias_id": null,
      "clients": [
        "ООО «Пример»"
      ],
      "kegs": 2,
      "rest_liters": 47.5,
      "volume_liters": 60,
      "products": [
        {
          "gtin": "04600000000010",
          "product_name": "Пиво светлое фильтрованное, кега 30 л",
          "kegs": 2,
          "rest_liters": 47.5,
          "volume_liters": 60,
          "rest_unknown": 0,
          "volume_unknown": 0,
          "items": [
            {
              "cis": "010460000000001021AbC1234",
              "client": "ООО «Пример»",
              "kpp": "010001001",
              "rest_liters": 17.5,
              "volume_liters": 30,
              "connect_date": "2026-10-28",
              "expiration_date": "2026-12-31",
              "updated_at": "2026-11-01T09:00:00+00:00"
            },
            {
              "cis": "010460000000001021AbC1235",
              "client": "ООО «Пример»",
              "rest_liters": 30,
              "volume_liters": 30,
              "connect_date": "2026-10-30",
              "expiration_date": "2027-01-31",
              "updated_at": "2026-11-01T09:00:00+00:00"
            }
          ]
        }
      ]
    }
  ]
}

Без детализации, только кеги без адреса:

{
  "generated_at": "2026-11-01T12:00:00+03:00",
  "totals": {
    "kegs": 2,
    "rest_liters": 47.5,
    "volume_liters": 60
  },
  "addresses": [
    {
      "fias_id": null,
      "clients": [
        "ООО «Пример»"
      ],
      "kegs": 2,
      "rest_liters": 47.5,
      "volume_liters": 60,
      "products": [
        {
          "gtin": "04600000000010",
          "product_name": "Пиво светлое фильтрованное, кега 30 л",
          "kegs": 2,
          "rest_liters": 47.5,
          "volume_liters": 60,
          "rest_unknown": 0,
          "volume_unknown": 0
        }
      ]
    }
  ]
}

Ошибки: 400 — fias_id не GUID и не none, details не логическое; 403 — client недоступен ключу.

{
  "error": "validation_failed",
  "message": "Параметр fias_id должен быть GUID ФИАС или none"
}

7.10. POST /kegs/track — поставить кеги на учёт

Параметры (тело)

Ответ 200 — массив результатов в порядке codes:

{
  "client": "ООО «Пример»",
  "codes": [
    {
      "cis": "010460000000001021RcV0001",
      "expiration_date": "2027-01-15"
    },
    {
      "cis": "010460000000001021InT0001"
    },
    {
      "cis": "12345"
    },
    {
      "cis": "010460000000001021RcV0001"
    },
    {
      "cis": "010460000000001021AbC1234"
    }
  ]
}

[
  {
    "input": "010460000000001021RcV0001",
    "cis": "010460000000001021RcV0001",
    "outcome": "added",
    "message": "Поставлен на учёт"
  },
  {
    "input": "010460000000001021InT0001",
    "cis": "010460000000001021InT0001",
    "outcome": "not_connected",
    "message": "КИ не подключён к оборудованию (статус INTRODUCED)"
  },
  {
    "input": "12345",
    "outcome": "invalid",
    "message": "Некорректный код маркировки: «12345» (проверьте раскладку клавиатуры сканера: латиница, без CapsLock)"
  },
  {
    "input": "010460000000001021RcV0001",
    "cis": "010460000000001021RcV0001",
    "outcome": "already_tracked",
    "message": "Повтор в списке"
  },
  {
    "input": "010460000000001021AbC1234",
    "cis": "010460000000001021AbC1234",
    "outcome": "already_tracked",
    "message": "Уже на учёте («ООО «Пример»»)"
  }
]

Ошибки запроса целиком: 400 — нет client, пустой codes, некорректный JSON; 403 — нет доступа к организации; 404 — организация не настроена; 502 gis_error — сбой запроса сведений в ГИС МТ. Отказ лицензии, ошибка токена и ошибка подписи не дают 4xx/5xx: все ещё не стоящие на учёте коды получают failed.

[
  {
    "input": "010460000000001021NeW0003",
    "cis": "010460000000001021NeW0003",
    "outcome": "failed",
    "message": "Нет действующего права организации (ЮЛ ИНН 0100000003): нет пробного периода или оплаты. Операция: запрос в ГИС МТ / ЭДО Лайт."
  }
]

7.11. DELETE /kegs/{cis} — снять кегу с учёта

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt -X DELETE https://localhost:8443/api/v1/kegs/010460000000001021AbC1235

{
  "cis": "010460000000001021AbC1235",
  "removed": true
}

Ошибки: 400 — код не распознан; 404 — не на учёте.

{
  "error": "not_found",
  "message": "КИ 010460000000001021AbC1235 не на учёте"
}

7.12. GET /codes/check — проверка кода маркировки

Параметры

Если код принадлежит другой нашей организации, доступной ключу, он дополнительно запрашивается её токеном (часть сведений ГИС МТ отдаёт только владельцу); checked_as — чей ответ использован.

Ответ 200 (код не найден — тоже 200):

Оценка по gis_info — резервная: она не проверяет криптоподпись и не равна ответу разрешительного режима. Для продажи в розницу настройте ключ разрешительного режима в профиле организации.

curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt "https://localhost:8443/api/v1/codes/check?cis=010460000000001021AbC1234&client=%D0%9E%D0%9E%D0%9E%20%C2%AB%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80%C2%BB"

{
  "input": "010460000000001021AbC1234",
  "cis": "010460000000001021AbC1234",
  "found": true,
  "outcome": "ours",
  "owner_inn": "0100000001",
  "owner_name": "ООО «Пример»",
  "ours": true,
  "our_client": "ООО «Пример»",
  "status": "INTRODUCED",
  "status_ex": "CONNECT_TAP",
  "status_text": "В обороте · Подключена к оборудованию",
  "product_group": "beer",
  "product_group_name": "Пиво и слабоалкогольные напитки",
  "package_type": "UNIT",
  "gtin": "04600000000010",
  "product_name": "Пиво светлое фильтрованное, кега 30 л",
  "producer_inn": "0100000008",
  "producer_name": "ООО «Пивоварня»",
  "emission_date": "2026-10-01",
  "introduced_date": "2026-10-03",
  "production_date": "2026-10-02",
  "expiration_date": "2027-01-31",
  "connect_date": "2026-10-28",
  "volume_liters": 30,
  "rest_liters": 17.5,
  "tracked": true,
  "checked_as": "ООО «Пример»",
  "sale_allowed": true,
  "sale_status": "allowed",
  "sale_reasons": [],
  "sale_source": "gis_info",
  "sale_note": "разрешительный режим не настроен"
}

Код с криптохвостом (GS — %1D), организация по умолчанию:

{
  "input": "0104600000000041215Kq7mT2\u001d93Qw7z",
  "cis": "0104600000000041215Kq7mT2",
  "found": true,
  "outcome": "foreign",
  "owner_inn": "0100000009",
  "owner_name": "ООО «Другая организация»",
  "ours": false,
  "status": "INTRODUCED",
  "status_text": "В обороте",
  "product_group": "beer",
  "product_group_name": "Пиво и слабоалкогольные напитки",
  "package_type": "UNIT",
  "gtin": "04600000000041",
  "product_name": "Пиво светлое, бутылка 0,5 л",
  "producer_inn": "0100000008",
  "producer_name": "ООО «Пивоварня»",
  "emission_date": "2026-09-01",
  "introduced_date": "2026-09-03",
  "production_date": "2026-09-02",
  "expiration_date": "2027-03-01",
  "tracked": false,
  "checked_as": "ООО «Пример»",
  "sale_allowed": false,
  "sale_status": "forbidden",
  "sale_reasons": [
    "владелец кода — другая организация (ООО «Другая организация»)"
  ],
  "sale_source": "gis_info",
  "sale_note": "разрешительный режим не настроен"
}

Ошибки

{
  "error": "token_unavailable",
  "message": "Не удалось получить токен ГИС МТ «ООО «Нет связи»»: ГИС МТ: сервис временно недоступен (HTTP 503)"
}

7.13. POST /codes/check — проверка списка кодов

Ответ 200 — массив объектов из 7.12 в порядке codes. Некорректный код — элемент с outcome: "invalid", cis: null и error (не 400 на весь запрос).

{
  "client": "ООО «Пример»",
  "codes": [
    "010460000000001021AbC1234",
    "0104600000000041215Kq7mT2\u001d93Qw7z",
    "12345",
    "046000000000000019"
  ]
}

[
  {
    "input": "010460000000001021AbC1234",
    "cis": "010460000000001021AbC1234",
    "found": true,
    "outcome": "ours",
    "owner_inn": "0100000001",
    "owner_name": "ООО «Пример»",
    "ours": true,
    "our_client": "ООО «Пример»",
    "status": "INTRODUCED",
    "status_ex": "CONNECT_TAP",
    "status_text": "В обороте · Подключена к оборудованию",
    "product_group": "beer",
    "product_group_name": "Пиво и слабоалкогольные напитки",
    "package_type": "UNIT",
    "gtin": "04600000000010",
    "product_name": "Пиво светлое фильтрованное, кега 30 л",
    "producer_inn": "0100000008",
    "producer_name": "ООО «Пивоварня»",
    "emission_date": "2026-10-01",
    "introduced_date": "2026-10-03",
    "production_date": "2026-10-02",
    "expiration_date": "2027-01-31",
    "connect_date": "2026-10-28",
    "volume_liters": 30,
    "rest_liters": 17.5,
    "tracked": true,
    "checked_as": "ООО «Пример»",
    "sale_allowed": true,
    "sale_status": "allowed",
    "sale_reasons": [],
    "sale_source": "gis_info",
    "sale_note": "разрешительный режим не настроен"
  },
  {
    "input": "0104600000000041215Kq7mT2\u001d93Qw7z",
    "cis": "0104600000000041215Kq7mT2",
    "found": true,
    "outcome": "foreign",
    "owner_inn": "0100000009",
    "owner_name": "ООО «Другая организация»",
    "ours": false,
    "status": "INTRODUCED",
    "status_text": "В обороте",
    "product_group": "beer",
    "product_group_name": "Пиво и слабоалкогольные напитки",
    "package_type": "UNIT",
    "gtin": "04600000000041",
    "product_name": "Пиво светлое, бутылка 0,5 л",
    "producer_inn": "0100000008",
    "producer_name": "ООО «Пивоварня»",
    "emission_date": "2026-09-01",
    "introduced_date": "2026-09-03",
    "production_date": "2026-09-02",
    "expiration_date": "2027-03-01",
    "tracked": false,
    "checked_as": "ООО «Пример»",
    "sale_allowed": false,
    "sale_status": "forbidden",
    "sale_reasons": [
      "владелец кода — другая организация (ООО «Другая организация»)"
    ],
    "sale_source": "gis_info",
    "sale_note": "разрешительный режим не настроен"
  },
  {
    "input": "12345",
    "cis": null,
    "found": false,
    "outcome": "invalid",
    "error": "Некорректный код маркировки: «12345» (проверьте, что отсканирован код маркировки, а не штрихкод товара)",
    "ours": false,
    "tracked": false,
    "sale_allowed": null,
    "sale_status": "unknown",
    "sale_reasons": [],
    "sale_note": "некорректный код маркировки"
  },
  {
    "input": "046000000000000019",
    "cis": "046000000000000019",
    "found": false,
    "outcome": "not_found",
    "error": "КИ не найден",
    "ours": false,
    "tracked": false,
    "checked_as": "ООО «Пример»",
    "sale_allowed": null,
    "sale_status": "unknown",
    "sale_reasons": [],
    "sale_note": "транспортная упаковка (КИТУ) в розницу не продаётся — проверяются коды товаров"
  }
]

Ошибки: 400 — пустой список или больше 1000 кодов, некорректный JSON; остальные — как у GET.

{
  "error": "validation_failed",
  "message": "Не указано ни одного кода маркировки"
}

8. Практические сценарии

Готовые скрипты — api/examples: PowerShell (MarkGreenEngineApi.psm1, сценарии 01-…–03-…), 1С 8.3 (МаркГринЭнджинAPI.bsl), cURL, коллекция .http.

8.1. Первый запрос и выбор организации

1. GET /health — программа доступна, версия 2.2.0 или новее.
2. GET /tokens с ключом panel — список организаций; сохраните точное значение client нужной организации. Ключу retail этот метод недоступен: имя организации ему сообщает администратор (оно же — в GET /kegs, поле client).
3. Дальше передавайте client во все методы. Имя меняется при переименовании профиля в программе — обрабатывайте 404 not_found «Профиль … не найден» как сигнал перечитать список.

8.2. Проверка кода перед продажей (касса, учётная система)

1. Отсканированный код передайте как есть (с криптохвостом) в POST /codes/check с client — организацией-продавцом.
2. sale_allowed: true — продажа разрешена по оценке программы; false — показать sale_reasons; null — оценки нет (sale_note).
3. Проверьте sale_source: для решения о продаже нужен permissive_mode.
4. Ответ 403 license_denied или 503 token_unavailable — программа не может проверить код. Решение о продаже в этом случае принимает ваша система по своим правилам; API не возвращает «разрешено» без проверки.

8.3. Подключить кегу и дождаться результата

1. POST /kegs/connect → 202, doc_id, заголовок Location.
2. Опрашивайте GET /documents/{doc_id} не чаще раза в 5 с первые 2 минуты, затем раз в минуту, пока не появится completed_at.
3. CHECKED_OK — кега на учёте: GET /kegs/{cis} покажет source: "connect_tap", status_ex: "CONNECT_TAP".
4. CHECKED_NOT_OK / PARSE_ERROR / PROCESSING_ERROR — причины в errors; исправьте и отправьте новый connect (повтор разрешён: код больше не «в обработке»).
5. UNKNOWN — проверьте код живым запросом GET /kegs/{cis}?client=…: status_ex: "CONNECT_TAP" в last_info значит, что подключение прошло; тогда поставьте кегу на учёт POST /kegs/track.

8.4. Остатки для учётной системы

GET /kegs/rests/fias?details=false по расписанию (не чаще раза в минуту — данные обновляются программой раз в 15 минут) — итоги по адресам и товарам. Для сверки по кегам — details=true или GET /kegs.

8.5. Неверные параметры, нет права, нет связи

9. Длительные операции и повторы

9.1. Общие правила

Ответы 429 содержат Retry-After — ждите не меньше. Для 502/503 используйте нарастающую паузу. Для 400, 401, 403, 404 повтор без изменения запроса бесполезен.

9.2. Ответ на POST /kegs/connect потерян

Ключа идемпотентности и метода «список документов» в 2.2.0 нет. Исход восстанавливается так:

1. Повторите тот же запрос.
2. 202 — первый запрос не дошёл до отправки; это первая отправка.
3. 400, в details — «КИ …: уже отправлен в документе , ожидается результат»: первый документ отправлен; возьмите doc_id из текста и переходите к шагу 2 сценария 8.3.
4. 400 «КИ …: уже подключён (на учёте у «…»)» — первый документ уже обработан успешно.
5. Защита держится, только пока документ не окончательный. Если первый документ успел завершиться, повтор создаст новый подписанный документ:
6. после CHECKED_NOT_OK, PARSE_ERROR, PROCESSING_ERROR, CANCELLED это допустимо — прежний не подключил кегу;
7. после UNKNOWN исход прежнего документа не известен, и он мог пройти. Не повторяйте connect после UNKNOWN: сначала проверьте код живым запросом (сценарий 8.3, шаг 5);
8. защита «уже подключён» действует, только пока кега стоит на учёте программы: после DELETE /kegs/{cis} или автоматического снятия повтор будет отправлен.

Защита работает внутри одной копии программы и не распространяется на другую копию или на подключение в личном кабинете ГИС МТ. Если программа аварийно завершилась ровно между отправкой и сохранением документа, повтор отправит документ ещё раз; ГИС МТ отклонит подключение уже подключённой кеги — результат увидите в errors.

10. Ошибки и устранение проблем

11. Совместимость, ограничения и найденные расхождения

11.1. Ограничения текущей реализации

• API работает только пока запущена программа на этом компьютере; кластеризации и очереди запросов нет.
• Нет ключа идемпотентности и списка документов CONNECT_TAP (9.2).
• Нет пагинации и фильтров в GET /kegs и GET /tokens.
• Нет методов ЭДО, ЕГАИС, чеков, управления профилями и ключами.
• HEAD поддерживается только у /health; неподдерживаемый метод — 404, не 405.
• Секрет передаётся только заголовком X-Api-Key; передача ключа в URL не поддерживается (и не нужна).
• Ответ conflict (409) объявлен, но не используется.

11.2. Исправления относительно прежней документации

Прежняя редакция этого файла, комментарии api_keys.example.json и страница сайта /docs/api расходились с кодом 2.2.0:

11.3. Расхождения реализации, требующие отдельной задачи

Поведение API в рамках этой задачи не менялось; ниже — что найдено и как учитывать до исправления.

12. Как проверялся этот документ

• Инвентаризация — по регистрации маршрутов ApiApp.MapEndpoints, HealthEndpoints, TokenEndpoints, KegEndpoints, CodeEndpoints (commit 78ca5a8): 14 регистраций (13 методов + HEAD /health) и обработчик неизвестных путей. Скрипт api/tools/check_docs.py сверяет реестр с кодом, OpenAPI и этим документом.
• Стенд — tools/GE.TrueApi.ApiDocStand: настоящие GE.TrueApi.Server.dll (SHA-256 40d3120d…adf35) и GE.TrueApi.Core.dll (c02f531b…dbe1) из ZIP выпуска 2.2.0 — те же, что в MANIFEST; часы остановлены на 2026-11-01T09:00:00Z. 75 сценариев api/tools/run_cases.py, все прошли; ответы — api/verification/stand-cases.json. Все JSON-примеры этого документа подставлены из этого файла и сверяются с ним.
• Примеры api/tools/verify_examples.py на том же стенде: коллекция .http (14 запросов), examples.cmd (curl.exe Windows 8.13.0 и curl 8.18.0), examples.sh, сценарии PowerShell 5.1 — без ошибок; протокол api/verification/examples-run.txt.
• Существующие тесты tests/GE.TrueApi.Server.Tests на 87eed57: 228 из 228.
• Не проверено: обмен с настоящей ГИС МТ и разрешительным режимом, подпись КриптоПро, центр лицензирования, работа по сети между компьютерами, примеры 1С на платформе 1С (платформы нет в среде проверки). Подробно — api/verification-report.md.

Собрано из docs/api.md скриптом docs/api/tools/build_html.py.