Общая документация по интеграции с эквайринговой системой ARIASOFT 1.3.4 Help

Внешняя интеграция

Раздел предназначен для разработчиков кассовых компаний и компаний интеграторов, предоставляющий подробное руководство по использованию и интеграции решения ARIASOFT (оборудование TACTILION) с ККМ клиентов. Поддерживается работа оборудования с внешними кассами под управлением ОС Windows и ОС Linux.

Общие требования и технические условия

Операционная система одной из следующих версий:

ОС

Версия

Windows (32-х или 64-х разрядная)

8, 8.1, 10, 11

CentOS

7

Red Hat Enteprise Linux

7, 8, 9

Debian

10, 11

Ubuntu

18.04 LTS, 20.04, 22.04 LTS

Описание API

API библиотеки asapecr.dll

В библиотеке ASAPEcr реализованы функции:

  • TRPOSX_Init

  • TRPOSX_Proc

  • TRPOSX_GetRsp

  • TRPOSX_Close

  1. При запуске контрольно-кассовой машины (ККМ) необходимо произвести инициализацию библиотеки asapecr.dll. Для этого нужно вызвать функцию TRPOSX_Init(). Этот процесс включает в себя выделение необходимых ресурсов, запуск сервисов и установление соединения с POS-терминалом.

  2. Для выполнения операций следует использовать функцию TRPOSX_Proc(), которая обеспечивает корректное проведение транзакций.

  3. По завершении операции результаты можно получить с помощью функции TRPOSX_GetRsp().

  4. Когда работа с ККМ завершена, необходимо выполнить деинициализацию системы, вызвав функцию TRPOSX_Close(). Это действие освобождает все задействованные ресурсы и останавливает работу сервисов TRPOSX.

Описание функции TRPOSX_Init

int TRPOSX_Init(const char * path_to_cfg);

Пример использования функции в коде:

char TRPOSX_cfg[] = "c:/trposx/trposx.cfg"; // инициализация TRPOSX_Init TRPOSX_Init(TRPOSX_cfg);

Параметр:

  • path_to_cfg — название файла конфигурации.

Инициализация внутреннего состояния библиотеки asapecr.dll включает в себя подготовку всех необходимых функций для взаимодействия с пользователем. В процессе инициализации происходит выделение ресурсов, запуск сервисов TRPOSX и установление соединения с POS-терминалом. Этот процесс должен быть выполнен однократно при запуске контрольно-кассовой машины (ККМ).

Возвращаемые значения:

Код ошибки

Описание

0

Ошибок нет

1

Инициализация не удалась

Описание функции TRPOSX_Proc

int TRPOSX_Proc(const char * in_params, int * len_out_params, int * len_receipt);

Пример использования функции в коде:

char in_params[] = "MessageID=PUR\nECRnumber=01\nECRReceiptNumber=0000000001\nTransactionAmount=000000000100\n"; int len_out_params; int len_receipt; // заполнение входных параметров для операции Оплата if (0 == TRPOSX_Proc(in_params, &len_out_params, &len_receipt)) { ... } else { // невозможно начать операцию с TRPOSX }

Запускает операцию согласно данным из входных параметров. Вызывается каждый раз для начала операции.

Параметры:

  • in_params — указатель на список входных параметров, завершенный нулем.

  • len_out_params — адрес переменной, куда будет помещен размер выходных данных.

  • len_receipt — адрес переменной, куда будет помещен размер чека.

Возвращаемые значения:

Код ошибки

Описание

0

Ошибок нет

1

Неподдерживаемая операция

-1

Ошибка при выполнении операции

Состав полей буфера входных параметров (на который указывает in_params):

Операция

Поля буфера

1. Оплата (PUR)

MessageID, ECRnumber, TransactionAmount, Currency, MerchantNo, Token

2. Возврат (REF)

MessageID, ECRnumber, ECRReceiptNumber, TransactionAmount, Currency, MerchantNo, TrxID, Token

3. Отмена (VOI)

MessageID, ECRnumber, ECRReceiptNumber, TransactionAmount, Currency, MerchantNo, TrxID, Token

4. Сверка итогов (STL)

MessageID, ECRnumber

5. Чтение журнала (JRN)

MessageID, ECRnumber, ECRReceiptNumber, MerchantNo

6. Печать отчета (SRV)

MessageID, SRVsubfunction, ECRnumber, ECRReceiptNumber, MerchantNo

7. Аварийная отмена (EVO)

MessageID

  • Для операции Отмена в ECRReceiptNumber нужно передавать поле InvoiceNumber, полученное при проведении операции Оплата.

  • Для операции Возврат нужно заполнять в поле TrxID поле RRN, полученное при проведении операции Оплата.

  • В операциях Сверка Итогов и Печать Отчёта поле ECRReceiptNumber не является обязательным.

  • Операция Аварийная Отмена работает только для отмены последней выполненной Оплаты или последнего выполненного Возврата, без запроса дополнительных данных о номере чека. Опционально можно указать MerchantNo и TRN.

Устройство буфера

Как это работает:

Буфер входных параметров — это строка, содержащая параметры, которые передаются в функцию для выполнения определенной операции. Параметры передаются в виде строки, где каждый параметр представлен в формате ключ=значение, и параметры разделены символом новой строки \n.

Формат строки:

  • Параметры передаются в виде строки, где каждый параметр записан в формате ключ=значение.

  • Параметры разделены символом новой строки \n.

  • Строка завершается нулевым символом \0

Пример содержимого:

  • MessageID=PUR: Идентификатор сообщения, указывающий на тип операции (например, покупка).

  • ECRnumber=01: Номер кассового аппарата.

  • ECRReceiptNumber=0000000001: Номер чека.

  • TransactionAmount=000000000100: Сумма транзакции в минимальных единицах валюты (например, в копейках для рублей).

Использование в функции:

  • TRPOSX_Proc принимает этот буфер как входной параметр.

  • len_out_params и len_receipt — это указатели на переменные, в которые функция запишет размеры выходных данных и чека соответственно.

  • Передача данных: Буфер in_params передается в функцию TRPOSX_Proc, которая обрабатывает входные параметры и выполняет операцию.

  • Обработка: Функция анализирует строку, извлекает параметры и использует их для выполнения операции.

  • Результат: Если операция успешна, функция возвращает 0, и размеры выходных данных и чека записываются в len_out_params и len_receipt.

Описание полей:

Поле

Описание

MessageID

Операция

ECRnumber

Идентификатор кассы

ECRReceiptNumber

Идентификатор транзакции (номер чека, использующийся в операции Отмена).

TransactionAmount

Сумма операции

Currency

Код валюты

SRVsubfunction

Номер отчета

InvoiceNumber

Номер чека терминальной операции

TrxID

RRN, идентификатор транзакции на стороне финансового хоста.

MerchantNo

Идентификатор продавца, по которому будут проходить операции

TRN

Уникальный номер транзакции на стороне внешнего устройства (на стороне кассы). Заполняется кассой и контролируется кассой вдальнейшем для получения информации по операции JRN в поле ECRReceiptNumber)

Token

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

  • Поле TrxID используется в запросе для операции Возврат.

  • В операциях Сверка Итогов и Печать Отчёта поле ECRReceiptNumber не является обязательным, но используется в операции Отмена для передачи номера чека оригинальной транзакции, которое было получено в ответе в поле InvoiceNumber.

  • Поле ECRReceiptNumber используется в операции Отмена для передачи номера чека оригинальной транзакции, которое было получено в ответе в поле InvoiceNumber.

  • Для Возврата нужно заполнять в поле TrxID поле RRN полученное при Оплате.

Поле

Описание

MessageID

Операция

ECRnumber

Идентификатор кассы

ECRReceiptNumber

Идентификатор транзакции

TransactionAmount

Сумма операции

Currency

Код валюты

SRVsubfunction

Номер отчета

InvoiceNumber

Номер чека терминальной операции

TrxID

Уникальный идентификатор транзакции (RRN)

MerchantNo

Идентификатор продавца, по которому будут проходить операции

Token

Уникальный идентификатор операции (данное поле формируется кассой и используется вдальнейшем для получения информации по операции в операции JRN в поле ECRReceiptNumber)

Значения MessageID для операций:

Операция

MessageID

Оплата

PUR

Возврат

REF

Отмена

VOI

Сверка итогов

STL

Чтение журнала

JRN

Печать ответа

SRV

Значения SRVsubfunction:

Вид отчета

SRVsubfunction

Соответствующие значения в десятеричной системе исчисления

Краткий с сортировкой по дате

0x0F

15

Детальный с сортировкой по эмитенту

0x0E

14

Детальный с сортировкой по дате

0x0D

13

Возвращаемые параметры:

  • Не все параметры, указанные в списке ниже, могут возвращаться после выполнения операции, так как не все являются обязательными для этого.

Параметр

Описание

Approve

Возвращает значение 'Y', если операция выполнена, 'N', если нет.

ResponseCode

Код ошибки выполнения операции на устройстве (0 - ошибок нет, если не 0, то остальные поля могут быть не заполнены!)

TransactionAmount

Сумма операции

Currency

Код валюты операции

ProcessingCode

Код ошибки выполнения операции в процессинге

Success

Дополнительное поле ответа об успешности операции, характерное только для терминалов на Android (0 - операция не выполнена). Значение нужно анализировать только при Approve = "Y' и ResponseCode = 0

ErrorReason

Ошибка обработки транзакции на устройстве, характерное только для терминалов на Android (0 - ошибок нет).

MerchantNo

Идентификатор продавца, по которому проходила операция

TerminalID

Номер терминала

POSEntryMode

Способ ввода карты

PAN

Маскированный PAN карты

AuthorizationID

Код авторизации

RRN

RRN операции

CardHash

Хэш карты

Date и Time

Оригинальные дата и время совершения операции на хосте

OrigTRN

Уникальный номер оригинальной транзакции со стороны внешнего устройства. Используется для операции Чтение журнала(JRN), как идентификатор транзакции, которую надо получить.

  • Взаимодействия на стороне ПО с маскировкой PAN нет, PAN карты маскируется на стороне сервера и обычно выглядит как "************8371".

  • Поле TRN добавляется в ответ от устройства (туда записывается RRN).

Параметр

Описание

Approve

Возвращает значение 'Y', если операция выполнена, 'N', если нет.

ResponseCode

Код ошибки выполнения операции на устройстве (0 - ошибок нет, если не 0, то остальные поля могут быть не заполнены!)

TransactionAmount

Сумма операции

Currency

Код валюты операции

ProcessingCode

Код ошибки выполнения операции в процессинге

Success

Дополнительное поле ответа об успешности операции, характерное только для терминалов на Android (0 - операция не выполнена). Значение нужно анализировать только при Approve = "Y' и ResponseCode = 0

ErrorReason

Ошибка обработки транзакции на устройстве, характерное только для терминалов на Android (0 - ошибок нет).

MerchantNo

Идентификатор продавца, по которому проходила операция

InvoiceNumber

Номер чека терминальной операции

TerminalID

Номер терминала

POSEntryMode

Способ ввода карты

PAN

Маскированный PAN карты

AuthorizationID

Код авторизации

RRN

RRN операции

CardHash

Хэш карты

Date и Time

Оригинальные дата и время совершения операции на хосте

  • Взаимодействия на стороне ПО с маскировкой PAN нет, PAN карты маскируется на стороне сервера и обычно выглядит как "************8371".

  • Поле TRN добавляется в ответ от устройства (туда записывается RRN).

Описание функции TRPOSX_GetRsp

int TRPOSX_GetRsp(char * out_params, char * receipt);

Пример использования функции в коде:

char *out_params = (char*) malloc(len_out_params); char *receipt = (len_receipt ? (char*) malloc(len_receipt) : NULL); if ( 0 == TRPOSX_GetRsp(out_params, receipt)) { if (NULL != out_params) { // обработка результата операции } if (NULL != receipt) { // обработка данных квитанции } } else { // не удается получить результат } free(out_params); free(receipt);

Вызывается после завершения операции для получения результатов.

Параметры:

  • out_params — указатель на буфер для выходных параметров. ККМ должна выделить память размером len_out_params под этот буфер.

  • receipt — указатель на буфер для чека. ККМ должна выделить память размером len_receipt под этот буфер.

Возвращаемые значения:

Код ошибки

Описание

0

Ошибок нет

1

Ошибка при выполнении функции

Описание функции TRPOSX_Close

int TRPOSX_Close(void);

Вызывается при завершении работы ККМ. При этом происходит освобождение ресурсов, остановка сервисов TRPOSX, разрыв связи с POS-терминалом.

Код ошибки

Описание

0

Ошибок нет

1

Ошибка при выполнении функции

Пример работы с библиотекой

#include <stdio> #include <stddef.h> #include <malloc.h> extern int TRPOSX_Init(char * path_to_cfg); extern int TRPOSX_Proc(char * in_params, int * len_out_params, int * len_receipt); extern int TRPOSX_GetRsp(char * out_params, char * receipt); extern int TRPOSX_Close(void); int main() { char TRPOSX_cfg[] = "c:/trposx/trposx.cfg"; // инициализация TRPOSX_Init TRPOSX_Init(TRPOSX_cfg); char in_params[] = "MessageID=PUR\nECRnumber=01\nECRReceiptNumber=0000000001\nTransactionAmount=000000000100\n"; int len_out_params; int len_receipt; // заполнение входных параметров для операции покупки if (0 == TRPOSX_Proc(in_params, &len_out_params, &len_receipt)) { // выделите память для выходных параметров char *out_params = (char*) malloc(len_out_params); char *receipt = (len_receipt ? (char*) malloc(len_receipt) : NULL); if ( 0 == TRPOSX_GetRsp(out_params, receipt)) { if (NULL != out_params) { // обработка результата операции } if (NULL != receipt) { // обработка данных квитанции } } else { // не удается получить результат } free(out_params); free(receipt); } else { // невозможно начать операцию с TRPOSX } // закрытие TRPOSX TRPOSX_Close(); return 0; }

Описание Эмулятора

Эмулятор кассы

Актуальная версия эмулятора передается совместно с кассовой библиотекой ASAPEcr файл «pyecr.py».

В папке присутвуют следующие файлы:

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

  • input – файл с данными для тестовой операции (для скрипта pyecr)

  • setup – файл с настройками формируемый при регистрации и настройке драйвера 1С AsapecrAT. Допускается ручная корректировка для использования с pyecr

Для работы эмулятора нужна 32 разрядная версия python 3. Можно использовать python-3.4.3.

Для работы кассовой библиотеки нужен распространяемый компонент Visual Studio 2012 (VC++ 11.0) Update 4 (ver 11.0.61030.0).

Для работы эмулятора нужна библиотека "asapecr.dll" и файлы необходимые для её работы (setup.txt и сертификаты). Параметры операции указываются в «input.txt».

Примеры ответов на операции

Пример информации в чеке после выполнения одной из операций:

check.png

Операция "Оплата"

Входные параметры

Результат и возвращаемые параметры

MessageID=PUR
ECRnumber=01
ECRReceiptNumber=1000000001
TransactionAmount=11100
Currency=643
Token=1234567890
MerchantNo=NADEKS9999

Approve=Y
AuthorizationID=745468
Currency=643
Date=1812
ECRReceiptNumber=1000000001
ECRnumber=01
ErrorReason=3
InvoiceNumber=000002463686
MerchantNo=NADEKS9999
MessageID=PUR
PAN=************3428
POSEntryMode=7
ProcessingCode=000
RRN=000002463686
ResponseCode=00
SRVsubfunction=
Success=1
TerminalID=NADEKS9999
Time=1809
TransactionAmount=11100
TrxID=000002463686

Операция "Возврат"

Входные параметры

Результат и возвращаемые параметры

MessageID=REF
ECRnumber=01
ECRReceiptNumber=1000000001
TransactionAmount=11100
Currency=643
Token=1234567890
MerchantNo=NADEKS9999
TrxID=000002463686

Approve=Y
AuthorizationID=257489
Currency=643
Date=1812
ECRReceiptNumber=1000000001
ECRnumber=01
ErrorReason=3
InvoiceNumber=1000000001
MerchantNo=NADEKS9999
MessageID=REF
PAN=************3428
POSEntryMode=7
ProcessingCode=000
RRN=1000000001
ResponseCode=00
SRVsubfunction=
Success=1
TRN=1234567890
TerminalID=NADEKS9999
Time=1820
TransactionAmount=11100
TrxID=1000000001

Операция "Отмена"

Входные параметры

Результат и возвращаемые параметры

MessageID=VOI
ECRnumber=01
ECRReceiptNumber=1000000001
TransactionAmount=11100
Currency=643
Token=1234567890
MerchantNo=NADEKS9999
TrxID=000038256232

Approve=Y
Currency=643
ECRReceiptNumber=6
ECRnumber=01
ErrorReason=3
InvoiceNumber=000066924028
MerchantNo=NADEKS9999
MessageID=VOI
ProcessingCode=000
ResponseCode=00
SRVsubfunction=
Success=1
TRN=1234567890
TerminalID=NADEKS9999
TransactionAmount=11100
TrxID=000066924028

Операция "Сверка итогов"

Входные параметры

Результат и возвращаемые параметры

MessageID=STL
ECRnumber=01

Approve=Y
ECRnumber=01
ErrorReason=3
MerchantNo=NADEKS9999
MessageID=STL
ProcessingCode=000
ResponseCode=00
SRVsubfunction=
Success=1

Операция "Чтеные журнала"

Входные параметры

Результат и возвращаемые параметры

Операция "Печать отчета"

Входные параметры

Результат и возвращаемые параметры

MessageID=SRV
SRVsubfunction=0E
ECRnumber=01
ECRReceiptNumber=0000001951

Approve=Y
ECRReceiptNumber=0000001951
ECRnumber=01
ErrorReason=3
MessageID=SRV
ResponseCode=00
SRVsubfunction=0E
Success=1

Ссылка на актуальный дистрибутив DEMO библиотеки, драйвера 1С и эмулятора:

ASAPEcr 0.43 1.0.36 - Ссылка

Архив содержит файлы библиотек, предназначенные под разные операционные системы:

Наименование файла

ОС

asapecr.dll

Windows 32

asapecr_x64.dll

Windows 64

asapecr.so

Linux 64

Полезные ссылки:

Инструкция G201 - Ссылка

Инструкция по 1С и ASAP - Ссылка

Ссылки на инструкции ИКР

Last modified: 27 December 2025
Внутренняя интеграцияИнструкции ИКР