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>

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

  • Числа с десятичной точкой: с точкой
  • Даты:
    • целая часть - число дней с 30 декабря 1899
    • дробная - доля суток (1/24 - 1 час, 1/24/60 - 1 минута, итд..)

Таблица:

idnamedatesumma
1Иван344542.43464321.78
2Михаил344546.43344123.45
<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 - описание параметра
Comments