Как подключить биометрический сканер отпечатков пальцев ZKTeco ZK4500 к 1С 7.7?

Интеграция современного биометрического оборудования с устаревшими платформами автоматизации часто вызывает у разработчиков множество вопросов. В нашей практике мы регулярно сталкиваемся с задачами сопряжения торгового оборудования и систем контроля управления доступом (СКУД) со старыми конфигурациями на платформе 1С:Предприятие 7.7. Одним из наиболее популярных и доступных USB-сканеров на рынке является модель ZKTeco ZK4500. В этой статье мы подробно разберем, как подключить данное устройство к 1С 7.7, проанализируем типовые ошибки разработчиков и рассмотрим готовые варианты реализации кода.

Выясняем причины: почему не работают стандартные DLL и утилита Dynwrapx?

При попытке подключить сканер напрямую через внешние библиотеки (например, libzkfpcsharp.dll) с использованием универсального загрузчика Dynwrapx программисты часто сталкиваются с системной ошибкой «Функция не найдена». Выясним, почему это происходит:

1. Разрядность платформы (Bitness): Платформа 1С 7.7 является строго 32-битным (x86) приложением. Любая внешняя библиотека, загружаемая в адресное пространство процесса 1С, также обязана быть 32-битной. Если установленный в системе драйвер или обертка SDK скомпилированы под 64-битную архитектуру, 1С не сможет их инициализировать.
2. Проблема зависимостей (Dependencies): Файл libzkfpcsharp.dll не является самостоятельной низкоуровневой библиотекой, а представляет собой всего лишь обертку (C#-wrapper). Для ее успешной работы в системе должны присутствовать основные C++ библиотеки ядра SDK (например, libzkfp.dll). Если эти файлы отсутствуют в системной директории Windows (SysWOW64 для 64-битных ОС) или в рабочем каталоге базы данных, инициализация вызовет ошибку.
3. Соглашение о вызовах: Динамический вызов через Dynwrapx требует строгого соответствия соглашениям о вызове функций (обычно __stdcall для Windows API). Функции внутри .NET-сборок экспортируются иначе, что делает их прямую интеграцию через врапперы невозможной.

Для решения этой проблемы мы рассмотрим два наиболее эффективных и проверенных метода интеграции сканера ZKTeco ZK4500 с 1С 7.7.

Способ №1. Использование официального ActiveX-компонента ZKFPEngX (Рекомендуемый способ)

Компания ZKTeco бесплатно предоставляет разработчикам комплект ZKFinger SDK. В его состав входит готовый к использованию элемент управления ActiveX — библиотека ZKFPEngX.dll (в некоторых версиях SDK она представлена как файл biokey.ocx). Использование этого компонента позволяет обойтись без создания собственных внешних компонент и программировать логику работы оборудования напрямую в среде 1С.

Рассмотрим по шагам процесс установки и настройки ActiveX-компонента:

1. Регистрация библиотеки в операционной системе. Скопируйте файл ZKFPEngX.dll и сопутствующие библиотеки ядра SDK в системную папку (для 64-разрядных Windows это папка C:\Windows\SysWOW64). Откройте командную строку от имени Администратора и выполните следующую команду: regsvr32 C:\Windows\SysWOW64\ZKFPEngX.dll
2. Обход ограничений 1С 7.7 по обработке событий. Поскольку сканирование отпечатка пальца — процесс асинхронный (пользователь может приложить палец к сенсору в любой момент), конфигурация должна уметь перехватывать внешние события устройства. В отличие от версии 1С 8.x, в 1С 7.7 мы не можем динамически подписаться на события объекта, созданного через функцию СоздатьОбъект().

   Решение: Разместим элемент ActiveX непосредственно на форме нашей обработки или документа. Для этого откройте форму в Конфигураторе 1С 7.7, выберите пункт меню «Вставить объект» (Insert Control) и найдите в списке зарегистрированных элементов «ZKFPEngX Control». Задайте созданному элементу понятный идентификатор, например: ЭлементСканер.

Теперь проанализируем программный код, который необходимо разместить в модуле нашей формы для инициализации сенсора:

// Процедура инициализации оборудования при открытии формы
Процедура ПриОткрытии()
    Попытка
        // Указываем индекс активного сенсора (0 - если подключен один сканер)
        ЭлементСканер.SensorIndex = 0;
        
        // Запускаем биометрический движок
        РезультатИнициализации = ЭлементСканер.InitEngine();
        
        Если РезультатИнициализации = 0 Тогда
            Сообщить("Биометрический сканер ZK4500 успешно инициализирован.");
        ИначеЕсли РезультатИнициализации = 1 Тогда
            Предупреждение("Ошибка: Не удалось загрузить драйверы сканера отпечатков!");
        ИначеЕсли РезультатИнициализации = 2 Тогда
            Предупреждение("Ошибка: Сканер отпечатков пальцев не подключен к USB!");
        Иначе
            Предупреждение("Неизвестная ошибка инициализации устройства. Код: " + РезультатИнициализации);
        КонецЕсли;
    Исключение
        Предупреждение("Критическая ошибка: Компонент ZKFPEngXControl не зарегистрирован на этом компьютере!");
    КонецПопытки;
КонецПроцедуры

После успешной инициализации нам нужно настроить обработку событий. Когда пользователь прикладывает палец к сканеру, ActiveX генерирует событие OnCapture. В модуле формы 1С 7.7 мы перехватываем его с помощью предопределенной процедуры, которая формируется по шаблону: [ИмяЭлемента]_[ИмяСобытия].

// Обработчик события успешного сканирования отпечатка пальца
Процедура ЭлементСканер_OnCapture(РезультатСчитывания, ШаблонОтпечатка)
    Если РезультатСчитывания = 0 Тогда
        // Считывание прошло успешно. ШаблонОтпечатка содержит двоичные данные.
        // Переведем двоичные данные шаблона в строковое представление для удобства работы в 1С
        СтрокаШаблона = "";
        ЭлементСканер.GetTemplateAsString(ШаблонОтпечатка, СтрокаШаблона);
        
        // Вызываем функцию верификации или авторизации пользователя
        АвторизоватьСотрудникаПоШаблону(СтрокаШаблона);
    Иначе
        Сообщить("Ошибка считывания биометрических данных. Пожалуйста, повторите попытку.");
    КонецЕсли;
КонецПроцедуры

Способ №2. Создание собственной внешней компоненты на C#/.NET

Если специфика вашей конфигурации не позволяет размещать ActiveX-элементы на формах диалогов (например, если требуется фоновое сканирование в глобальном модуле или работа в фоновых процессах), оптимальным решением станет написание собственной внешней компоненты (ВК) по стандарту COM на C# с использованием платформы .NET.

Рассмотрим структуру простейшего класса-обертки на C# для взаимодействия с 1С 7.7:

using System;
using System.Runtime.InteropServices;

namespace ZK4500_1C_Bridge
{
    // Уникальные GUID для регистрации COM-класса и интерфейса
    [Guid("A1B2C3D4-E5F6-7A8B-9C0D-1E2F3A4B5C6D")]
    [InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
    [ComVisible(true)]
    public interface IZKConnector
    {
        int InitDevice();
        string CaptureFingerprint();
    }

    [Guid("F1E2D3C4-B5A6-9788-7766-554433221100")]
    [ClassInterface(ClassInterfaceType.None)]
    [ComVisible(true)]
    public class ZKConnector : IZKConnector
    {
        // Внутренние методы взаимодействия с libzkfp.dll через DllImport
        [DllImport("libzkfp.dll")]
        private static extern int zkfperr_Init();

        public int InitDevice()
        {
            // Логика инициализации библиотеки и датчика
            return zkfperr_Init();
        }

        public string CaptureFingerprint()
        {
            // Логика получения шаблона и преобразования в Base64-строку
            byte[] templateBuffer = new byte[2048];
            // ... Код получения отпечатка из устройства ...
            return Convert.ToBase64String(templateBuffer);
        }
    }
}

При компиляции данной сборки крайне важно соблюдать следующие правила настройки проекта:

1. Установите целевую платформу компиляции строго в положение x86. Платформа 1С 7.7 не сможет взаимодействовать со сборками AnyCPU, если операционная система запустит их в 64-битном режиме.
2. Включите флаг "Register for COM interop" в свойствах проекта Visual Studio на вкладке "Build" или зарегистрируйте готовую сборку вручную через утилиту regasm.exe:
   Скопировать код

   
   C:\Windows\Microsoft.NET\Framework\v4.0.30319\regasm.exe ZK4500_1C_Bridge.dll /codebase /tlb
   

В коде 1С 7.7 работа с такой компонентой будет выглядеть классическим образом:

// Пример работы с самописной ВК на C#
Процедура ПодключитьСборку()
    Попытка
        Компонента = СоздатьОбъект("ZK4500_1C_Bridge.ZKConnector");
        Если Компонента.InitDevice() = 0 Тогда
            Сообщить("Собственная компонента успешно подключена!");
        КонецЕсли;
    Исключение
        Сообщить("Не удалось запустить COM-объект компоненты.");
    КонецПопытки;
КонецПроцедуры

Организация хранения и сравнения отпечатков пальцев в базе данных 1С 7.7

Рассмотрим подробнее, как организовать хранение биометрической информации и осуществлять быстрый поиск сотрудников в справочнике базы данных 1С 7.7.

1. Хранение шаблонов в справочнике:
Биометрический шаблон представляет собой массив байт, который с помощью метода GetTemplateAsString() преобразуется в текстовую Base64-строку фиксированной длины (обычно от 1 до 4 КБ в зависимости от версии алгоритма). Для хранения этой информации в 1С 7.7 идеально подходит справочник "Сотрудники". Создайте в нем новый реквизит (например, БиометрическийШаблон) со следующими свойствами:

• Тип: Строка
• Длина: Неограниченная (это позволит хранить длинные Base64-строки без риска усечения данных).

2. Процедура регистрации нового сотрудника (Enrollment):
При регистрации пользователя в системе рекомендуется сделать несколько сканирований (обычно 3 прикладывания пальца) для формирования эталонного шаблона. ActiveX-компонент ZKFPEngX умеет автоматически объединять эти сканы в единый качественный шаблон при помощи встроенного механизма слияния.

3. Процедура сравнения (Верификация 1:1 и 1:N):
Для авторизации сотрудника нам нужно сравнить вновь полученный отпечаток с базой данных. Передавать биометрические данные на сторонние веб-сервисы не требуется — все операции сравнения выполняются локально и мгновенно силами самой библиотеки ZKFPEngX.

Разберем пример кода поиска сотрудника по его отпечатку (алгоритм сравнения "один ко многим"):

// Функция поиска сотрудника в базе данных по текущему скану отпечатка
Функция НайтиСотрудникаПоОтпечатку(ТекущийШаблонСтрокой)
    СпрСотрудники = СоздатьОбъект("Справочник.Сотрудники");
    СпрСотрудники.ВыбратьЭлементы();
    
    Пока СпрСотрудники.ПолучитьЭлемент() = 1 Цикл
        ШаблонИзБазы = СпрСотрудники.БиометрическийШаблон;
        
        Если ПустаяСтрока(ШаблонИзБазы) = 1 Тогда
            Продолжить; // Пропускаем сотрудников без зарегистрированных отпечатков
        КонецЕсли;
        
        // Метод Verifying From String сравнивает два текстовых шаблона биометрии
        // Возвращает True (Истина/1), если степень совпадения выше установленного порога
        Если ЭлементСканер.VerifyingFromString(ШаблонИзБазы, ТекущийШаблонСтрокой) = 1 Тогда
            // Сотрудник успешно идентифицирован!
            Возврат СпрСотрудники.ТекущийЭлемент();
        КонецЕсли;
    КонецЦикла;
    
    Возврат ПолучитьПустоеЗначение("Справочник.Сотрудники");
КонецФункции

Использование встроенного метода сравнения VerifyingFromString гарантирует высочайшую скорость работы, так как математический расчет сходства векторов отпечатков реализован разработчиками ZKTeco на уровне оптимизированного под x86 машинного кода библиотеки C++, работающей внутри ActiveX.