# A8PRO CR: инструкция интегратора

Контракт выпуска **1.1.30.0 Universal R4**, проверка исходников и идентичности артефактов: 5 ноября 2026 года. Техническое имя исполняемого файла этого выпуска — `A8prodR.exe`; публичное название продукта — **A8PRO CR**.

Эта инструкция описывает конкретный выпуск. Перед внедрением сверяйте версию программы и согласованное оборудование. Проверка документации не заменяет испытание вашего считывателя, драйвера и принимающей программы. Установщик в комплект документации не входит; получите согласованный выпуск у A8PRO.

## 1. Что подключаем

A8PRO CR работает на компьютере Windows с совместимым картридером CHIP или паспортным сканером MRZ. Принимающая программа обращается к локальному HTTP-интерфейсу и получает структурированные поля. Считывание и локальная передача результата не требуют интернета; условия активации и лицензии согласуются при поставке.

Базовый адрес: `http://localhost:9010`. Это loopback-интерфейс одного компьютера, а не публичный облачный API. Обращение с сервера 1С к localhost попадёт на сервер 1С, а не на компьютер кассира. Для установленного клиента 1С запрос выполняется на компьютере с A8PRO CR. Веб-клиент, CRM в браузере и терминальные сессии требуют отдельно согласованной архитектуры. Прямой вызов с произвольного сайта не поддерживается: сервер проверяет Host, удалённый адрес и Origin.

## 2. Подготовка и установка

1. Зафиксируйте Windows, архитектуру x86/x64, версию A8PRO CR, модель и драйвер устройства, типы документов, версию принимающей системы и место выполнения её кода.
2. Получите согласованный установщик и совместимый драйвер. Проверенная идентичность Universal R4: SHA-256 `42BA38318095FD956EA1091D8B0C1451310F4A276030690F240829D7E9F36215`. Этот хеш относится к одному пакету, а не ко всем выпускам A8PRO CR.
3. При обновлении закройте приложение через его меню в трее. Запустите установщик обычным двойным щелчком под тем пользователем Windows, который будет работать с программой. Не удаляйте предыдущую установку заранее; проверьте предложенную папку.
4. Установщик содержит необходимые компоненты .NET Framework 4.8 и Visual C++; для компонентов Windows может запросить повышение прав или перезагрузку. После запроса перезагрузки войдите под тем же пользователем и завершите установку. Не обещается поддержка любой старой ОС: фактическую конфигурацию проверяют до внедрения.
5. Проверьте лицензию и разрешённые функции CHIP/MRZ, запуск программы и отсутствие конфликта порта 9010. Автозапуск этого выпуска относится к входу пользователя Windows.
6. Для HTTP.sys необходимы корректные URLACL для точных локальных адресов `http://localhost:9010/`, `http://127.0.0.1:9010/`, `http://[::1]:9010/` и нужной учётной записи. При отказе запуска передайте диагностику администратору. Не расширяйте резервирование до `+`, `*` или Everyone и не удаляйте чужую резервацию.
7. Настройте токен, перезапустите приложение в согласованное время и проверьте `/v2/status`. Установку, перезапуск, изменение лицензии и драйверов выполняет ответственный за рабочее место.

Пакет R4 имеет ограничения приёмки: реальные старые версии Windows, физическая перезагрузка и конкретное клиентское оборудование не подтверждены проверкой этой документации. Не обновляйте рабочие места только ради совпадения с инструкцией: сначала согласуйте выпуск и пилот.

## 3. Доступ к API

Для новых интеграций используйте `/v2/` и заголовок:

```http
X-A8PRO-Token: <локальный секрет>
Accept: application/json
```

Программа читает `A8PRO_API_TOKEN` из окружения при запуске. Минимальная длина — 32 символа; используйте случайный секрет, а не пароль оператора. Непустой короткий токен приводит к ошибке запуска. Если токен отсутствует, защищённые v2-запросы не авторизуются. В режиме `A8PRO_REQUIRE_API_TOKEN=1` токен требуется и для старых маршрутов; без токена строгий режим не запускается. Его включение для существующей установки согласуйте с владельцем старой интеграции.

Токен должен быть доступен процессу A8PRO CR и локальному компоненту интегратора. Не помещайте его в URL, журнал, общий модуль с открытым исходным текстом или браузерный JavaScript. В комплекте Postman значение токена пустое. Переменные окружения — способ конфигурации, а не зашифрованное хранилище секретов.

Допускаются локальный удалённый адрес и loopback Host. Origin отсутствует либо указывает на loopback-хост с портом 9010. Удалённый доступ, обход Origin и публикация порта наружу не входят в этот контракт. Для всех операций также требуется действующая лицензия; доступ MRZ проверяется отдельно.

## 4. Маршруты

| Метод и путь | Назначение | Успех |
|---|---|---|
| `GET /v2/status` | Проверка присутствия CHIP и состояния функций | 200, объект статуса |
| `GET /v2/getInfo` | Новое чтение по действию оператора | 200, объект полей **либо** `status=waiting` |
| `GET /v2/getInfo/last` | Последний локальный результат | 200, оболочка результата; 204, если результата нет |
| `POST /v2/getInfo/ack?scanId=...` | Удалить именно принятый результат из кэша | 204 без тела |

Маршруты без `/v2` существуют для прежних интеграций. Не переключайтесь на них автоматически при 401/403. Диагностический `/getInfo/debug/mrz` не предназначен для обычного заполнения карточек и в примеры не включён.

### Проверка состояния

```json
{"reader":true,"card":false,"presenceError":false,"autoMode":false,"mrzEnabled":true,"autoModeSample":"before_status_probe","autoCompletedCount":0,"lastAutoCompletedUtc":null}
```

Это условный пример. `reader` и `card` описывают CHIP-проверку; `reader=false` не доказывает отсутствия MRZ-сканера. `mrzEnabled` означает разрешение функции, а не успешное аппаратное чтение. В этом выпуске ответ содержит `autoMode=false` во время проверки; не используйте это поле как единственный показатель готовности. `/status` занимает общий канал устройства и может вернуть 429, поэтому не вызывайте его параллельно с чтением в частом цикле.

### Новое чтение

`GET /v2/getInfo` сначала проверяет CHIP. При наличии карты пытается прочитать её; ошибка CHIP не означает автоматический переход к MRZ. Если карты нет и MRZ разрешён, используется MRZ. Отдельного параметра принудительного выбора источника здесь нет.

Бюджет чтения — 10 секунд; задайте клиентский тайм-аут с запасом, например 15 секунд. Это предел ожидания данного запроса, а не обещание скорости устройства. После тайм-аута устройство может ещё завершать работу, поэтому последующий запрос может вернуть 429. Не запускайте параллельные чтения и не перезапускайте приложение автоматически.

Ожидание документа — тоже HTTP 200:

```json
{"status":"waiting","message":"Поднесите документ к считывателю"}
```

Если MRZ недоступен по функции, возможен HTTP 200:

```json
{"status":"waiting","mrzEnabled":false,"message":"Поднесите удостоверение к считывателю CHIP"}
```

Успешное чтение возвращает непосредственно поля, **без** оболочки `data` и **без** `status=ready`. Не считайте любой HTTP 200 успешным чтением. Сохраните служебные заголовки вместе с результатом:

```http
X-A8PRO-Scan-Id: 11111111111111111111111111111111
X-A8PRO-Scan-Source: chip
X-A8PRO-Scanned-At: 2026-11-05T08:00:00.0000000Z
```

Идентификатор генерируется для каждого успешного чтения. Пример данных — полностью вымышленный, не документ для проверки личности:

```json
{"docType":"","docnum":"TEST-ONLY","lname":"ПРИМЕР","fname":"ТЕСТ","sname":"","mrzfn":"TEST","mrzln":"EXAMPLE","bdate":"01.01.1990","citizen":"","iin":"","issuecountry":"","issuer":"","valid_from":"01.01.2025","valid_to":"01.01.2030","sex":"","bplace":"","nation":"","photo":"","sig_photo":""}
```

## 5. Поля результата

Все перечисленные поля — строки. Возможны пустые значения. ИИН и номер документа нельзя преобразовывать в число. Не перезаписывайте уже проверенные данные пустыми полями.

| Поле | Назначение |
|---|---|
| `docType` | Тип документа; трактовку значения согласуйте для нужных документов |
| `docnum` | Номер документа |
| `lname`, `fname`, `sname` | Фамилия, имя, отчество |
| `mrzln`, `mrzfn` | Фамилия и имя из MRZ, обычно латиницей |
| `bdate` | Дата рождения |
| `citizen` | Гражданство |
| `iin` | ИИН, если доступен |
| `issuecountry` | Страна выдачи |
| `issuer` | Кем выдан документ |
| `valid_from`, `valid_to` | Даты выдачи и окончания действия |
| `sex` | Пол; исходное значение требует сопоставления с вашей системой |
| `bplace` | Место рождения |
| `nation` | Национальность |
| `photo`, `sig_photo` | В проверенных CHIP/MRZ-присваиваниях этого выпуска пустые строки; изображение не обещается |

Даты обычно `ДД.ММ.ГГГГ`; валидируйте календарную дату, пустые и неожиданные значения. Источники имеют разный набор данных. В MRZ-ветке `issuer`, `bplace`, `nation` не заполняются; остальные поля также не гарантированы для каждого документа. Имена ключей отличаются от QRScan (`docnum` против `document_number`, `issuer` против `issuing_authority`). Не используйте одно сопоставление без адаптера.

## 6. Получение, сохранение и очистка

1. Сериализуйте операции чтения на рабочем месте. Один сеанс приложения содержит один слот последнего результата, а не очередь и не разделение по пользователям/токенам.
2. По кнопке оператора вызовите `/v2/getInfo`. При `waiting` покажите ожидание; при ошибке — понятную причину.
3. При успехе запомните `scanId` из заголовка, источник, время и данные. Покажите поля оператору, разрешите исправление.
4. Надёжно сохраните нужные данные в вашей системе. Повтор сохранения того же `scanId` не должен создавать дубль операции.
5. После подтверждённого сохранения вызовите `POST /v2/getInfo/ack?scanId=<тот же идентификатор>`. Тело не требуется. 204 означает, что этот результат удалён из локального слота.

`GET /v2/getInfo/last` возвращает `{"scanId":"...","scannedAt":"...","source":"chip","data":{...}}`. Получение не очищает результат. Срок доступности — 2 минуты от чтения; истечение проверяется при обращении к `/last`. Новый успешный скан заменяет предыдущий, остановка сервера очищает кэш. Это не обещание таймерного стирания памяти ровно через 2 минуты.

Не подставляйте `/last` в новую карточку без проверки уже известного `scanId`: там может быть предыдущий клиент. Если ответ нового чтения потерян и `scanId` неизвестен, автоматическое восстановление по `/last` не позволяет доказать принадлежность результата текущему запросу. Нужен контролируемый сценарий повторного чтения с оператором.

`/getInfo` не идемпотентен: повтор запускает новое чтение. Повтор ACK после успешного удаления возвращает 404, а не 204; 404 также возможен при отсутствии или замене результата. Не трактуйте любой 404 как подтверждённый успех и не удаляйте вместо него новый чужой `scanId`. Если данные уже сохранены, не создавайте повторную бизнес-операцию из-за ошибки очистки.

## 7. Ошибки

| HTTP / status | Действие |
|---|---|
| 200 + `waiting` | Ожидание документа/CHIP; это не готовые поля |
| 204 | Пустой ответ: `/last` ничего не содержит или ACK выполнен |
| 401, тело может быть пустым | Проверить токен и окружение процесса; не переходить на старый API |
| 403 + `license_required` | Проверить лицензию и разрешённые функции |
| 403 без JSON | Проверить локальный адрес, Host и Origin |
| 404 | Неизвестный маршрут либо отсутствующий/неподходящий `scanId` при ACK |
| 405 | Неверный HTTP-метод; ACK требует POST |
| 429, возможно `busy` | Канал занят. Выждать, не запускать параллельное чтение; тело может быть пустым |
| 503 + `reader_timeout` | Истёк бюджет чтения; операция устройства может ещё завершаться |
| 503 + `reader_initialization_timeout` | Не завершилась инициализация устройства |
| 503 + `chip_presence_error`, `chip_error`, `mrz_error` | Проверить устройство/документ; повтор только в контролируемом сценарии |
| 503, возможно пустое тело | Сервер останавливается или перегружен |
| 500 + `reader_error` | Внутренняя ошибка; сохранить техническую диагностику без персональных данных |

Сначала проверяйте код HTTP и наличие тела, затем JSON. Не пытайтесь разобрать пустой 204 как JSON. Сообщения HTTP.sys могут отличаться от ответов приложения.

## 8. Примеры для интегратора

- `openapi.json` — контракт четырёх рабочих маршрутов v2.
- `postman.json` — ручные запросы с пустым токеном; ACK запускается только после явного подтверждения сохранения. Не запускайте всю коллекцию подряд.
- `A8PRO_CR_1C.bsl` — функции установленного клиента 1С на Windows: HTTP, разбор JSON, различение ожидания, получение scanId и отдельный ACK. Это шаблон, не готовая обработка EPF. Не запускайте его на сервере 1С или в веб-клиенте без изменения архитектуры.
- `examples/*.json` — вымышленные ответы для разработки интерфейса без документов клиентов.

Пример 1С не записывает справочники и не отправляет ACK автоматически. Реализуйте сохранение и бизнес-правила в вашей конфигурации; проверьте модуль в её синтакс-контроле и тестовой базе. Синхронный запрос может блокировать интерфейс на время чтения; для промышленного интерфейса предусмотрите ожидание и подходящий вашей версии 1С способ асинхронной работы. [Официальное описание HTTP-взаимодействия 1С](https://v8.1c.ru/platforma/rabota-s-http-i-ftp/).

## 9. Приёмка подключения

- Проверить версию и хеш пакета, пользователя Windows, драйвер, лицензию и токен.
- Проверить CHIP и MRZ отдельно на согласованных документах, пустые поля, даты, кириллицу и латиницу.
- Проверить ожидание, отсутствие документа, отключение устройства, 401/403 и занятый канал.
- Проверить тайм-аут без параллельного повторного чтения, потерю ответа и защиту от предыдущего клиента.
- Проверить сохранение до ACK, повтор сохранения того же scanId без дубля, ACK 204 и повтор ACK 404.
- Проверить замену результата новым чтением, срок `/last`, работу нескольких клиентских окон с сериализацией.
- Проверить отсутствие токенов и данных документов в журнале, правила доступа и хранения в принимающей программе.
- Зафиксировать фактические результаты в `ACCEPTANCE.md` перед распространением на рабочие места.

Материалы: https://a8pro.kz/solutions/cardreader/api?lang=ru