KassaLite RPC protocol

RPC (Remote Procedures Call) - удаленный вызов процедур по HTTP

Описание

Программный интерфейс (API) системы ClassCard работает через протокол HTTP POST. В параметрах запроса указывается название функции и ее параметры. По умолчанию используется кодировка UTF-8. Строка запроса выглядит примерно так:

http://server.ru:8888/api?function=Login&login=8006248383&passw=4444

Параметры запроса могут стоять в любом порядке. Некоторые параметры функций являются обязательными, они отмечены подчеркиванием. Часть функций требуют пропуск (token) - это кодовая строка, получаемая при успешной авторизации. Ответ отправляется в формате XML, например:

<response><error>Auth failed</error></response>

Табличные значения

Числа с десятичной точкой: с точкой
Даты:

Таблица:

<table> <item> <id>1</id> <name>Иван</name> <date>344542.43464</date> <summa>321.78</summa> </item> <item> <id>2</id> <name>Михаил</name> <date>344546.43344</date> <summa>123.45</summa> </item> </table>

Общие параметры для всех запросов

function - имя вызываемой функции
format - формат ответа. По умолчанию format=xml. Можно получить ответ в формате JSON, для этого нужно указать параметр format=json
encoding - кодировка данных в запросе и в ответе. По умолчанию encoding=utf-8

Список функций

Авторизация

Login( login, passw )

Авторизует пользователя в системе, возвращает пропуск (token) или ошибку авторизации.

Параметры:

name - учетное имя пользователя
passw - пароль

CheckToken( token, url )

Проверка токена и URL отправителя. Если URL не указан, то проверяется только токен. Если токен действителен, то возвращается идентификатор пользователя - владельца токена, логин и время логина.

Проверка URL используется при кросс-доменной авторизации, для предотвращения авторизации с неизвестных хостов.

Параметры:

token - токен пользователя, полученный при авторизации в функции Login
url - строка URL обратного вызова, при кросс-доменной авторизации

GetAccountByMifare( token, mifare_id )

Возвращает данные пользователя по MifareID карты. Вызывается после считывания карты для отображения данных на экране. Исторически была заточена под школы, отсюда названия некоторых параметров.

Параметры:

token - токен пользователя, полученный при авторизации в функции Login
mifare_id - MifareID прочитанной карты, например 40B399DE

Возвращает таблицу:

id - код абонента
mifare_id - MifareID карты
internal_card_id - внутренний номер карты (не используется)
balance - остаток денег на счету карты
day_limit - дневной лимит расходов по карте
available_sum - доступная для расходования сумма (с учетом возвратов и предыдущих покупок)
discount_available - сумма скидки (отображается если не равна нулю)
fam - фамилия
im - имя
otch - отчество
account_type - название должности абонента
class_id - код подразделения
class_num - название подразделения
class_liter - название подразделения
in_school - признак присутствия
photo_md5 - MD5 хеш фотографии абонента (не используется)

GetUserPhoto( token, user_id, mifare_id )

Вызывается сразу после запроса GetAccountByMifare(). Возвращает фотографию пользователя. Нужно указать user_id или mifare_id пользователя. Фотография возвращается в бинарном виде.

MakePurchase( token, mifare_id, sum1, sum2 )

Операция упрощенной продажи. Указываются только общие суммы по двум отделам. Суммы указываются даже если они равны нулю.

Параметры:

token - токен пользователя, полученный при авторизации в функции Login
mifare_id - MifareID карты абонента
sum1 - сумма по первому отделу
sum2 - сумма по второму отделу

Возвращает:

doc_id - код операции

MakePurchaseGoods( token, mifare_id, summa, doc_body )

Операция продажи товаров. Таблица товаров передается в параметре doc_body формата:

id,goods_id,name,amount,sum,dept@ id - код (не используется) goods_id - код товара name - название товара (без запятых) amount - количество sum - сумма dept - номер отдела @ - конец строки Может быть несколько таких записей подряд, разделенных символом "@"

Возвращает:

doc_id - код операции

GetRefundSum( token, account_id )

Запрос доступных сумм возвратов по отделам, отправляется после запроса GetAccountByMifare() в режиме «Возврат».

Параметры:

token - токен пользователя, полученный при авторизации в функции Login
account_id - код абонента

Возвращает:

l_sum_dept_1 - сумма по отделу 1
l_sum_dept_2 - сумма по отделу 2

MakeRefund( token, mifare_id, sum1, sum2 )

Операция возврата, указываются суммы возврата по первому и второму отделу.

Параметры:

token - токен пользователя, полученный при авторизации в функции Login
mifare_id - MifareID карты абонента
sum1 - сумма возврата по отделу 1
sum2 - сумма возврата по отделу 2

Возвращает:

doc_id - код операции

GetReportX( token )

Запрос данных для X-отчета по продажам

Возвращает таблицу:

department_id - номер отдела продаж
sum_total - сумма продаж
body_cnt - число продаж
r_department_id - номер отдела возвратов
r_sum_total - сумма возвратов
r_body_cnt - число возвратов

GetReportZ( token )

Закрытие смены, отчет по смене (Z-отчет)

Возвращает таблицу:

department_id - номер отдела продаж
sum_total - сумма продаж
body_cnt - число продаж
r_department_id - номер отдела возвратов
r_sum_total - сумма возвратов
r_body_cnt - число возвратов

GetVendReportX( token )

Запрос данных для X-отчета по продажам торгового автомата (раздатчика)

Возвращает таблицу:

department_id - номер отдела продаж
sum_total - сумма продаж
body_cnt - число продаж

GetVendReportZ( token )

Закрытие смены, отчет по смене (Z-отчет) для торгового автомата

Возвращает таблицу:

department_id - номер отдела продаж
sum_total - сумма продаж
body_cnt - число продаж

GetMeals( token )

Запрос видов комплексного питания (завтраки, обеды). Выполняется при начале работы если включен модуль «Групповые заказы».

Возвращает таблицу:

id - код трапезы
meal_name - название трапезы
meal_type_id - код типа трапезы (1-завтрак, 2-обед, 3-полдник)
price - цена трапезы

GetScoList( token )

Запрос таблицы заказов комплексного питания по классам/подразделениям. При отображении заказы группируются по классам/подразделениям и по трапезам.

Возвращает таблицу:

id - код
meal_id - код трапезы
result_price - сумма заказа
account_id - код абонента
class_num - название подразделения
class_liter - название подразделения
start_time - время начала трапезы по расписанию

GetGoodsList( token )

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

GetLocalGoodsList( token )

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

Возвращает таблицу:

good_id - код товара
portion_name - название товара
price - цена товара
plu_code - PLU-код товара
key_code - код клавиши
ask_amount - запрос количества (1-запрашивать)
department_id - номер отдела

SetLocalGoodsItem( token, id, goods_id, name, price, plu_code, key_code, ask_amount, department_id )

Изменение товара буфета. Выполняется при изменении любого реквизита товара. Из-за особенности реализации в школьной базе, при изменении названия кассирка сперва удаляет товар командой DeleteLocalGoodsItem()

Параметры:

token - токен пользователя, полученный при авторизации в функции Login
id - код товара
goods_id - код неизменяемого товара (не используется)
name - название товара, включая единицу измерения (без запятых!)
price - цена товара
plu_code - PLU-код товара
key_code - код клавиши
ask_amount - запрос количества (1-запрашивать)
department_id - номер отдела

DeleteLocalGoodsItem( token, id, goods_id, name )

Удаление товара по коду или названию.

Параметры:

token - токен пользователя, полученный при авторизации в функции Login
id - код товара
goods_id - код неизменяемого товара (не используется)
name - название товара, включая единицу измерения (без запятых!)

GetSchoolParams( token )

Запрос таблицы параметров. Выполняется при начале работы для получения реквизитов для печати чеков. Необязательно, можно использовать параметры в конфиге. Названия параметров:

ENTPR_NAME - название организации
ENTPR_INN - ИНН организации
ENTPR_INDEX - почтовый индекс
ENTPR_CITY - город
ENTPR_ADDR - адрес

Возвращает таблицу:

param_name - название параметра
param_value - значение параметра
param_comment - описание параметра