18.01.2017

Требования к разработке интеграционных приложений для подключения оборудования к мобильным приложениям

Внимание! Данные требования устарели. Актуальные требования размещены в статье.

Версия 1.2

• Изменения в стандарте
• Введение
• Общие требования к разрабатываемому интеграционному приложению
• Обязательные команды, связанные с использованием интеграционного приложения в системе
• Описание команд, специфичных для работы с подключаемым оборудованием
  • Требования к интеграционным приложениям для фискальных регистраторов
  • Требования к интеграционным приложениям для принтеров чеков
  • Требования к интеграционным приложениям для устройств ввода
  • Требования к интеграционным приложениям для платежных систем
• Подключение интеграционных приложений к конфигурации БПО

Изменения в стандарте

Введение

Для подключения оборудования к мобильной платформе "1С:Предприятие" и при последующей работе с ним используется "1С:Библиотека подключаемого оборудования для мобильных приложений". Библиотека предоставляет набор механизмов для унифицированной работы с подключаемым оборудованием. Применение данной библиотеки позволяет ускорить реализацию поддержки широкого спектра моделей подключаемого оборудования в разрабатываемых конфигурациях, а также добавить готовые функциональные блоки в уже работающие мобильные приложения.

Для подключения оборудования к "1С:Библиотека подключаемого оборудования для мобильных приложений" необходимо разработать интеграционное приложение по требованиям, описываемым в данном документе.

Требования описывают команды, используемые как конфигурацией, так и интеграционными приложениями. Библиотека подключаемого оборудования взаимодействует с интеграционными приложениями, используя описанные ниже команды, интеграционные приложения обеспечивают управление оборудованием.

Интерфейс интеграционного приложения можно условно разделить на несколько разделов:

• Первый раздел - общие требования к разрабатываемому интеграционному приложению.
• Второй раздел - системная, определяет набор служебных команд, связанных с использованием интеграционного приложения в системе: его подключение и настройку, отключение и обслуживание ошибок.
• Третий раздел - функциональная, определяет обязательный набор команд, специфичных для определенного типа подключаемого оборудования.
• Четвертый раздел - определяет действия по подключению интеграционного приложения к конфигурации "1С:Библиотека подключаемого оборудования для мобильных приложений".

1. Общие требования к разрабатываемому интеграционному приложению

Интеграционное приложение разрабатывается на языке программирования Java с использованием Android SDK. Интеграционное приложение не является пользовательским приложением, оно предназначено только для работы с программными продуктами "1С:Предприятие". Среда разработки доступна по адресу https://developer.android.com/sdk/index.html, документация - https://developer.android.com/reference/packages.html.

Технические особенности

При взаимодействии с интеграционным приложением мобильная платформа "1С:Предприятие" вызывает метод Activity.startActivityForResult(). Команда интеграционного приложения и ее данные представляют собой параметры объекта класса Intent, передаваемого в функцию startActivityForResult() и определяющего вызываемое Activity.
Более подробное описание класса Intent можно получить в документации для разработчика приложений на Android   http://developer.android.com/reference/android/content/Intent.html и инструкции по использованию Intent для запуска приложений или сервисов - http://developer.android.com/guide/components/intents-filters.html.

Команда

Наименование команды интеграционного приложения (к примеру, "GET_PARAMETERS") вместе с идентификатором пакета (например, "YourAppPackageName") формирует Action запускаемого Activity. Файл AndroidManifest.xml интеграционного приложения должен иметь элемент подобного типа для каждой команды, выполнение которой он поддерживает. Для нашего примера AndroidManifest.xml выглядит следующим образом:

<activity
    android:name="YourAppPackageName.SomeActivity"
    android:label="@string/app_name">
    <intent-filter>
        <category android:name="android.intent.category.DEFAULT"/>
        <action android:name="YourAppPackageName.GET_PARAMETERS"/>
    </intent-filter>
</activity>

Параметры команды и возвращаемое значение

Для обмена данными с мобильной платформой "1С:Предприятие" используется элемент Extras класса Intent. Получение данных осуществляется с помощью конструкции вида getIntent().getExtras(), возвращаемым значением которой является ассоциативный массив, из которого можно получить необходимые данные.

Пример:

String someString = "";
Bundle extras = getIntent().getExtras();
if(extras != null) 
    {
        someString = extras.getString("SomeStringValue");
    }

Возврат данных в мобильную платформу "1С:Предприятие" осуществляется как результат работы вызванного Activity. В случае успешного завершения работы в интеграционном приложении необходимо вызвать функцию setResult, передав ей в качестве первого параметра константу RESULT_OK , а в качестве второго – элемент класса Intent, содержащего заполненный массив Extras.

Пример:

Intent resultIntent = new Intent();
resultIntent.putExtra("SomeStringValue", "Hello from external activity");
setResult(RESULT_OK, resultIntent);

Если же во время работы интеграционного приложения возникла ошибка и команда не может быть обработана корректно, в качестве первого параметра функции setResult необходимо передать RESULT_CANCELED. Именно от этого зависит возвращаемое значение команды: при RESULT_OK - Истина, при RESULT_CANCELED – Ложь.

Преобразования типов

При передаче параметра в интеграционное приложение "1С:Предприятие" производит преобразование типов:

• Строка –> string
• Булево –> boolean
• Число –> double
• НавигационнаяСсылка –> string
• Картинка –> Bitmap

При передаче параметра из интеграционного приложения в "1С:Предприятие" также производится преобразование типов:

• byte –> Число
• char –> Строка
• double –> Число
• float –> Число
• int –> Число
• long –> Число
• short –> Число
• boolean –> Число
• string –> Строка
• Uri –> Строка
• Bitmap –> Картинка

2. Обязательные команды, связанные с использованием интеграционного приложения в системе

Данный раздел содержит список обязательных команд, связанных с использованием интеграционного приложения в системе – его подключение и получение списка настраиваемых параметров.

Интеграционное приложение поддерживает два основных этапа работы с оборудованием в конфигурации:

• Подключение и настройка интеграционного приложения.
• Использование оборудования пользователем в процессе работы.

Регистрация и настройка оборудования

При настройке оборудования в приложении БПО выполняются следующие действия:

1. Получение версии интеграционного приложения командой "GET_VERSION".
2. Получения доступных параметров для настройки интеграционного приложения командой "GET_PARAMETERS".
3. Построение формы настройки интеграционного приложения на основании списка доступных параметров, описанных в структуре TableParameters.
4. Сохранение параметров настройки интеграционного приложения в базе данных конфигурации.

Использование интеграционного приложения в процессе работы

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

1. При вызове любой команды (кроме "GET_LAST_ERROR") интеграционного приложения в нее передается полный список сохраненных параметров, полученных командой "GET_PARAMETERS".
2. Любая команда возвращает значение логического типа. Если интеграционное приложение успешно выполнило операцию на оборудовании, возвращается Истина, иначе - Ложь.
3. В случае неуспешного выполнения команды следующей вызывается команда "GET_LAST_ERROR", возвращающая текстовое описание ошибки.
4. Подключение оборудования осуществляется с помощью команды "OPEN". При вызове этой команды интеграционное приложение производит необходимые операции по инициализации и подготовке оборудования к работе.
5. Далее происходит последовательный вызов команд интеграционного приложения, специфичных для определенного типа оборудования.
6. Отключение устройства происходит командой "CLOSE". При вызове этой команды интеграционное приложение производит необходимые операции по завершению работы с устройством и освобождению использованных ресурсов.

* - Версия требований – версия текущего документа (Версии 1.00 соответствует число 1000. Текущей версии 1.2 соответствует число 1002).

Описание структуры TableParameters

Текст в формате XML содержит описание всех параметров интеграционного приложения и описание визуального интерфейса настройки интеграционного приложения.
Необходимые для работы параметры могут быть структурированы для вывода на форму - распределены по закладкам и группам на закладке. Закладки и группы могут иметь наименования, которые отобразятся на форме. Для параметров могут быть заданы определенные значения, которые сформируют выпадающий список для выбора.

Пример XML описывающего параметры интеграционного приложения:

<?xml version="1.0" encoding="UTF-8" ?>
<Settings>
    <Page Caption="Параметры"> 
        <Group Caption="Параметры подключения">
            <Parameter Name="Model" Caption="Модель"/> 
            <Parameter Name="Port" Caption="Порт" TypeValue="Number" DefaultValue="0">
                <ChoiceList>
                     <Item Value="0">Клавиатура</Item>
                     <Item Value="1">COM1</Item>
                     <Item Value="2">COM2</Item>
                </ChoiceList>
            </Parameter>
            <Parameter Name="Parity" Caption="Четность" TypeValue="Number" DefaultValue="True"/>
            <Parameter Name="Speed" Caption="Скорость" TypeValue="Number" FieldFormat="" DefaultValue="1"/>
        </Group>
    </Page>
</Settings>

3. Описание команд, специфичных для работы с подключаемым оборудованием

3.1. Требования к интеграционным приложениям для фискальных регистраторов

При работе с фискальными регистраторами (принтерами чеков для ЕНВД) поддерживаются операции:

• Печать чеков внесения/выемки денежных средств
• Построчная и пакетная печать чеков ККМ
• Печать отчетов за смену с гашением (Z-отчет) и без гашения (X-отчет)
• Открытие денежного ящика

Алгоритм построчной печати чека ККМ

Выполнение команд построчной печати чеков на ФР осуществляется по следующему алгоритму:

1. Открытие чека;
2. Печать фискальных строк / нефискальных строк / штрихкода;
3. Закрытие чека.

Открытие чека - Открытие чека происходит командой  "OPEN_CHECK".
Команда открывает на ФР необходимый тип чека согласно параметру CheckType. Команда возвращает номер открытого чека (CheckNumber) и номер текущей отрытой фискальной смены (SessionNumber).
Если ранее был открыт чек, повторный вызов должен автоматически аннулировать ранее открытый чек.

Печать фискальных строк - Печать фискальных строк осуществляется командой "PRINT_FISCAL_STRING". Печатается на чековой ленте фискальная строка с переданными реквизитами.
При печати фискальной строки рассчитываются скидки. Если рассчитанное по формуле "Цена*Количество – Сумма по строке" значение отлично от 0, то в чеке печатается абсолютное значение скидки в денежном выражении. Если значение скидки меньше нуля, вместо слова "Скидка" выводится слово "Наценка".
Для длинных фискальных строк необходимо делать перенос на следующую строку.

Печать нефискальных строк - Печать нефискальных строк осуществляется командой "PRINT_NONFISCAL_STRING". Выводится произвольная текстовую строка на чековой ленте.
Для длинных нефискальных строк перенос не предусмотрен: строки обрезаются до максимально возможной длины строки печатающего устройства.

Печать штрихкода - Печать штрихкода осуществляется командой "PRINT_BARCODE". Осуществляется печать штрихкода в открытом чеке, если это позволяет сделать модель устройства.

Закрытие чека - Для завершения печати чека происходит закрытие чека командой "CLOSE_CHECK".
При открытом фискальном чеке происходит печать итогов и расчет сумм оплаты. Расчет по чеку может может производиться несколькими видами оплат - наличные и 3 вида безналичной оплаты.
Сумма всех видов оплат должна быть больше суммы открытого чека. Если сумма внесенных наличных денег превышает сумму открытого чека - происходит расчет сдачи.

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

Алгоритм пакетной печати чека ККМ

Алгоритм пакетной печати чека отличается от построчной печати тем, что все те же команды, которые используются при построчной печати, передаются единым пакетом.
Последовательность команд их параметры описываются с помощью XML определенного типа - CheckCommandsPackage.
Пакетная печать осуществляется командой "PRINT_CHECK".

Описание структуры CheckCommandsPackage

Текст в формате XML содержит описание передаваемого для печати чека.

Пример XML описывающего чека для печати:

<?xml version="1.0" encoding="UTF-8" ?>
<Check>
   <Parameters CheckType="1"/>
   <Positions> 
      <FiscalString Name="Товарная позиция 1" Quantity="1.5" Price="100.0" Amount="150.0" Department="1" Tax="18.0"/> 
      <FiscalString Name="Товарная позиция 2" Quantity="2.0" Price="100.0" Amount="200.0" Department="1" Tax="18.0"/> 
      <NonFiscalString TextString="Тестовая нефискальная строка"/> 
      <Barcode BarcodeType="EAN13" Barcode="290000143180"/> 
   </Positions>
   <Payments Cash="300.0" NonCashType1="50.0" NonCashType2="0.0" NonCashType3="0.0"/>
</Check>

3.2. Требования к интеграционным приложениям для принтеров чеков

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

• Печать текстовых чеков;
• Открытие денежного ящика.

При подключении устройства командой "OPEN" интеграционное приложение устанавливает режим печати, настраивает кодировку принтера чеков или производит другие необходимые действия по инициализации печати на устройстве.

Алгоритм построчной печати чека

Выполнение команд построчной печати чеков осуществляется по следующему алгоритму:

1. Открытие документа;
2. Печать текстовых строк / печать штрихкода;
3. Закрытие документа.

Открытие документа - Открытие текстового чека происходит командой  "OPEN_DOCUMENT".

Печать текстовых строк - Печать текстовых строк осуществляется командой "PRINT_STRING". Выводится произвольная текстовая строка на чековой ленте.
Для длинных нефискальных строк перенос не предусмотрен: строки обрезаются до максимально возможной длины строки печатающего устройства.

Печать штрихкода - Печать штрихкода осуществляется командой "PRINT_BARCODE". Осуществляется печать штрихкода в открытом документе, если это позволяет сделать модель устройства.

Закрытие чека - Закрытие документа осуществляется командой "CLOSE_DOCUMENT". В случае необходимости посылается команда отрезчику, и если это позволяет сделать модель устройства.

В рамках одного документа должна быть предусмотрена возможность печати текстовых строк и штрихкода.

Алгоритм пакетной печати документа

Алгоритм пакетной печати документа отличается от построчной печати тем, что все те же команды, которые используется при построчной печати, передаются единым пакетом.
Последовательность команд и их параметры описываются с помощью XML определенного типа - DocumentCommandsPackage.
Пакетная печать осуществляется командой "PRINT_DOCUMENT".

Описание структуры DocumentCommandsPackage

Текст в формате XML содержит описание передаваемого для печати документа.

Пример XML описывающего чека для печати:

<?xml version="1.0" encoding="UTF-8" ?>
<Document>
   <Positions> 
      <NonFiscalString TextString="Тестовая нефискальная строка"/> 
      <Barcode BarcodeType="EAN13" Barcode="290000143180"/> 
   </Positions>
</Document>

3.3. Требования к интеграционным приложениям для устройств ввода

Данные устройства реализуют функцию считывания закодированной различными способами информации и передачи ее в "1С:Предприятие".
К данным устройствам можно отнести сканеры штрихкода, считыватели магнитных карт.

3.4. Требования к интеграционным приложениям для платежных систем

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

• Оплата картой
• Отмена платежа по карте
• Возврат платежа по карте
• Получение итогов дня по картам

ВНИМАНИЕ: По требованиям безопасности полный номер карты не предоставляется, предоставляется маскированный номер карты (часть цифр номера карты заменено звездочками).

Оплата картой

При необходимости оплатить покупку платежной картой система вызывает команду "PAYMENT", передавая во входных параметрах сумму к оплате для списания с карты и номер чека по которому происходит покупка.
Интеграционное приложение возвращает результат выполнения команды, код RRN, маскированный номер карты, код авторизации и текст слип-чека.
Текст слип чека печатается на подключенном печатающем устройстве (ФР или Принтер чеков) или передается покупателю средствами мобильного решения (email или sms).

Возврат платежа по карте

При возврате платежа система вызывает команду "RETURN_PAYMENT", передавая во входном параметре сумму к возврату на карту, номер карты по которой происходила оплата, номер чека по которому происходит операция, код RRN операции по которой совершается возврат, и код авторизации. Интеграционное приложение в ответ возвращает результат выполнения функции, а в выходные параметры записывает код RRN, код авторизации.
Текст слип чека печатает на подключенном печатающем устройстве (ФР или Принтер чеков) или передается покупателю средствами мобильного решения (email или sms).

Отмена платежа по карте

Если происходит отмена платежа, то система вызывает команду "CANCEL_PAYMENT", передавая во входных параметрах сумму, которая была указана для списания с карты, номер карты по которой происходила оплата, номер чека по которому происходит операция, код RRN операции по которой совершается отмена, и код авторизации. Интеграционное приложение в ответ возвращает результат выполнения функции.

Получение итогов дня по картам

Для получения текста отчета система вызывает команду "SETTLEMENT". Интеграционное приложение возвращает результат выполнения функции и текст отчета.

4. Подключение интеграционных приложений к конфигурации БПО

Для подключения интеграционных приложений к конфигурации БПО необходимо установить интеграционное приложение на устройство и зарегистрировать его в приложении "1С:Библиотека подключаемого оборудования для мобильных приложений".

Для этого необходимо в главном меню приложения выбрать раздел "Подключаемое оборудование" и в отрывшемся окне нажать кнопку "Драйверы оборудования". При этом открывается список доступных драйверов. С помощью кнопки "Создать" необходимо создать новый элемент справочника драйверов: выбрать необходимый тип оборудования, ввести наименование, ввести в поле "Идентификатор объекта" значение идентификатора пакета интеграционного приложения  (см. раздел 1 "Общие требования к разрабатываемому интеграционному приложению"). Нажать "Записать и закрыть". После этого вернуться в раздел "Подключаемое оборудование" и создать новую запись в справочнике подключаемого оборудования для данного экземпляра.