Версия документа 27A, Прошивка iKKM 1024,1224,1324 и выше.

1. Введение

При работе с API iKKM нужно придерживаться немного других правил чем при традиционной интеграции с ФР регистраторами по COM порту. В старых ФР процесс обмена данными состоит из 5-6 шагов: опрос состояния, открытие чека, передача суммы,получения статуса итд.

В iKKM по причине использования web сервера весь процесс обмена данными состоит из формирования и передачи одного запроса. Однако при возникновении ситуации когда софт POS системы постоянно требует опроса каких либо параметров, в iKKM предусмотрены все необходимые функции (см глава Дополнительные возможности)

2. Запуск API

Работа в режиме web-api доступна при подключении iKKM по LAN или WiFi. Перед началом работы необходимо включить web-api в Главное меню - Фискальный Регистратор - ФР режим, затем Авторизуйтесь , выберите налог по умолчанию , и нажмите на кнопку Включить web кассу Все действия подробно описаны в руководстве пользователя iKKM, а также можно узнать много в базе знаний. Если у вас возникли вопросы откройте тикет в службе поддержки

* Для iKKM самообслуживания API сервер запускается автоматически при включении.

3. Протокол работы

Отправка данных осуществляется по протоколу HTTP/1.1. Порт TCP всегда 8080, допустимы методы POST или GET (лишь в нескольких случаях используется только POST). Используйте наиболее подходящий для вас метод.

Стандартный таймаут запроса 10 секунд. При закрытии смены до 90 секунд. Количество обращений не чаще чем одно в секунду.

Передаваемые параметры чувствительны к регистру символов. Предусмотрены два типа данных строковый и числовой

Строковые данные (String)

Используйте кодировку Utf-8. Поддерживается английски, русский и казахский алфавиты.

Числа (Int, Float)

Максимально допустимое числового значения - 20 миллионов. Передаваемые числа могут быть целыми или с десятичной дробью, разделитель . (точка) при передачи более 2-х знаков (сотых) произойдет округление.

Проверить включено или нет округление можно в отчете /apicheck/getInfo

4. Web-API ключ

Для авторизации во всех запросах передается параметр key состоящий из 8 чисел. После любой успешной операции c БД или фискальной памятью iKKM, web-api ключ изменяется, новый ключ приходит в виде ответа. При следующем запросе нужно использовать новый ключ.

Если в запросе web-api ключ не соответствует текущему, iKKM вернет ошибку. Исключение составляет только метод регистрации /api/sale|buy|... в случае передачи предыдущего ключа, iKKM повторит ответ: вернет новый ключ, распечатает дубликат чека, но регистрация не будет продублирована.

Узнать актуальный web-api ключ можно на экране iKKM перед запуском фискального регистратора; считать с дисплея iKKM QR-код, или удаленно зайти под администратором в веб-управление (на первой странице).

5. Кассовые операции

5.1 Регистрация

Регистрация - главная операция iKKM, регистрация влияет на БД и фискальную память iKKM. Метод вызывается /api/..., передаются следующие параметры:

sale | buy ... тип регистрации
cash | bank ... оплата
tax налог (необязательно)
print печать (необязательно)
itemdata табличная часть для ОФД (необязательно)

Типы регистрации

Удачная продажа на 800 тенге, получено 1000, сдача 200

GET /api/?key=12345678&sale=800&cash=1000 HTTP/1.1
  Response: 200 (text/plain)
  Description: 123 #Номер чека при удачной операции
  Body: 87654321

Ошибочное выполнение запроса

GET /api/?key=12345678&sale=800&cash=200 HTTP/1.1
  Response: 400 (text/plain)
  Description: cash-lq-sale #Наличность меньше суммы чека
  Body: -10

Основных торговых операций всего четыре:

sale- продажа
buy - покупка
saleReturn - возврат продажи
buyReturn - возврат покупки

В запросе указывается только один вид регистрации. Значение параметра итоговая сумма операции, например: /api/?sale=660...

Оплата

Удачный пример смешанной оплаты по чеку

GET /api/?key=12345678&sale=800&cash=500&bank=400 HTTP/1.1
  Response: 200 (text/plain)
  Description: 124
  Body: 87654321

Ошибка оплаты чека

GET /api/?key=12345678&sale=800&cash=2000&bank=800 HTTP/1.1
  Response: 400 (text/plain)
  Description: no-cache-hq-sale #Чек оплачен безналом, наличность запрещена
  Body: -13

Возможные виды оплат:

cash- получено наличности
bank - оплата банковской картой
tara - прием тары
credit - оплата в кредит.

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

Выбор налога [устарело]

tax - Необязательный параметр, используется для выбора налога указанного не по умолчанию. Значение параметра - код налога (число, см. получение справочника налогов)

Табличная часть чека

iKKM может заполнять табличную часть чека следующим образом:

Пример параметра itemdata

[{
    "name": "Чай",
    "price": "200",
    "qty": "2",
    "sum": "400"
}, {
    "name": "Стейк",
    "price": "6000",
    "qty": "2",
    "excise": "12345ABCDF",
    "sum": "12000"
}, {
    "name": "Coffee",
    "price": "2000",
    "qty": "3",
    "measure": "112", # литры
    "taxid": "2", # код налога из справочника
    "sum": "6000",
},{
    "name": " скидка 10% ",
    "discount": "1240" #если скидка, поля price|qty|sum не указываются
}]

Автоматически в виде одной строки, например Продажа 1x100=100 тг
Печатать табличную часть чека из параметра print
Из структурированного JSON поля itemdata (так же происходит отправка этих данных в ОФД)

itemdata - служит для печати и передачи табличной части чека на сервер ОФД. Метод передачи только POST, кодировка UTF-8. Формат данных JSON. Максимальное количество позиций в одном чеке 100. В случае превышения, будут распечатаны все позиции, но на сервер ОФД будет отправлена одна позиция с названием типа регистрации, например: Продажа 1x100=100 тг. Если вместе с itemdata также передан параметр print, он будет распечатан в первую очередь.

name - наименование товара или услуг (String)
price - цена (Int, Float)
qty - кол-во (Int, Float)
taxid - код налога (Int, см. получение справочника налогов)
excise - маркировка (String) при указании маркировки qty = 1
discount - сумма скидки, если скидка, поля price|qty|sum не указываются (Int, Float)
measure - код единицы измерения в ИС ЭСФ (String), если не указывать данный параметр, по умолчанию равен 796

print - необязательный параметр, для печати табличной части чека или рекламы. Метод передачи запроса только POST, кодировка UTF-8. Количество строк не ограничено, разделение строки \n.

Допустимы следующие размеры строк:

Внутренний принтер: 24 символа нормальный шрифт, 32 маленький, 19 крупный.
LAN/USB принтер: 42 символа для 80мм и 30 символов для 57мм бумаги, размер шрифта не предусмотрен при печати на внешнем принтере.

footer - дополнительный необязательный параметр, служит для печати рекламного текста в конце чека, метод только POST. В данном параметре можно печатать штрих-коды, формат описан в printHeader). Чтобы отрезать футер от основного чека на внешнем принтере, добавьте параметр cutfooter=true

5.2 Ответы

TCP дамп ответа (200 - удачно, 164 - номер чека, 29852781 - новый ключ )

HTTP/1.1 200 164
Content-Length: 8
Content-Type: text/html; charset=UTF-8
Date: 2017-02-15 15:00

29852781

Ответ в формате JSON (http://адрес/v2/метод..)

{ "body" : "-1", "result" : "400", "resultText" : "incorrect-web-api-key" }

Ответ возвращается в текстовом формате, только число. Если ответ положительное число длиной 8, запрос выполнен удачно и вы получили новый web-api ключ. Если отрицательное - смотрите коды ошибок.

При возникновении ошибок, код HTTP статуса (HTTP status code) будет 400, а описание (HTTP status description) будет содержать короткую причину возникновения ошибки, например: bank-param-error.

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

Eсли вам не удобно читать http body, header, responce. Вы можете получить ответ в JSON формате. Для того чтобы iKKM отвечал всегда в JSON формате, подставьте в путь всех запросов v2, например http://ikkm.local:8080/v2/apicheck/?key=12345678

5.3 Прочие кассовые операции

Снятие наличности

GET /apiwithdraw/?key=12345678&cash=200 HTTP/1.1
  Response: 200 (text/plain)
  Description: 126
  Body: 12345678

Внесение наличности

GET /apideposit/?key=12345678&cash=2000 HTTP/1.1
  Response: 200 (text/plain)
  Description: 127
  Body: 12345678

Печать X-Отчета

GET /apixreport/?key=12345678 HTTP/1.1
  Response: 200 (text/plain)
  Description: x-report-started
  Body: 0

Закрытие смены и печать Z-Отчета

GET /apizreport/?key=12345678 HTTP/1.1
  Response: 200 (text/plain)
  Description: z-report-started
  Body: 0

Внос / снятие наличности

Для снятия наличности из кассы выполните запрос: /apiwithdraw/?cash=[сумма]
Для вноса наличности выполните запрос: /apideposit/?cash=[сумма]

Значение параметра cash только положительное число.

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

Для корректной кассовой дисциплины мы рекомендуем использовать непосредственно интерфейс iKKM для снятия наличности и закрытия смены.

Однако вы можете при необходимости провести все операции через web-api. Ключ web-api не изменится в результате данной операции.

Закрытие смены и печать Z отчета: /apizreport
Печать X отчета: /apixreport

Получение ответов не предусмотрено, вы всегда можете получить данные любой смены и операции выполнив запросы по получению отчетов или на сайте ОФД.

6 Банковские операции

6.1 Запуск операции

Запуск оплаты по карте банка

GET /apibank/?key=12345678&message=purchase&amount=1500&trackdocument=345 HTTP/1.1
  Response: 200 (text/plain)
  Description: bank-is-opened
  Body: 0

Для запуска банковского приложения выполните метод /apibank/..., передаются следующие параметры:

amount cумма платежа
message тип операции
trackdocument номер операции, требуется для получения результата (необязательно)

Возможные типы операций message:

purchase- покупка
refund - возврат
reversal - отмена
reconciliation - закрытие цикла

Параметр trackdocument число, любое удобное для вас уникальное значение от 1 до 999.999.999, iKKM не проверяет уникальность данного параметра.

При удачном запуске банковского приложения придет ответ 0. При обращении к iKKM во время оплаты, ответ будет -2. Ключ web-api не изменится в результате данной операции.

Опции при оплате картой:

bankSlot Вы можете указать банковский слот, от 1 до 9. (по умолчанию 1-й банк)
showSlotMenu true - Показать список банков на терминале, false - Сразу перейти в интерфейс оплаты карты (по умолчанию true - показывать список)
customerSlip печать чека для покупателя, возможные значения: true, false, ask (по умолчанию)-спросить на терминале требуется ли чек.
bankRef референс номер оригинальной транзаshowSloкции, используется при операциях Refund и Reversal.

Использование опций не обязательно.

6.2 Получение результатов

Запрос результата оплаты

EMV операция `/dump/bank/[номер-операции]/trackdocument`
{
    "foundTransactions": "1",
    "totalAmount": "200.00",  
    "transactionResult": "success",
    "details": [{  # массив
        "AID": "VISA CREDIT", 
        "PAN": "1234 XXXX XXXX 1234",
        "amount": "100.00",
        "bankslot": "1",
        "currency": "398",
        "dateTime": "22-11-2017 17:19:55",
        "operationType": "purchase", 
        "refnum": "100000000013",
        "authcode": "12345678", 
        "responce": "00",
        "result": "success", # success | fail
        "traceNumber": "60"
    }],
}


QR оплата `/dump/qrbank/[номер-операции]/trackdocument`
{
    "foundTransactions": "1",
    "totalAmount": "5000",
    "transactionResult": "success",
    "details": [
        {
            "amount": "5000",
            "bankqr": "kaspiqr",
            "dateTime": "14-01-2021 21:31:31",
            "operationType": "purchase",
            "paymentid": "58",
            "qrtoken": "9784766091812243283999827934089209253028",
            "result": "success"
        },...
    ]
}

Получить результат можно выполнив запрос: "/dump/bank/[номер-операции]/trackdocument

foundTransactions количество найденных транзакций
totalAmount общая сумма удачных транзакций
transactionResult результат операции success | fail
details список всех транзакций (массив) :
1. AID платежная система
2. PAN номер карты
3. amount сумма
4. bankslot банковский слот
5. cardHolderName владелец карты
6. currency код валюты
7. dateTime дата и время (yyyy-MM-dd hh:mm:ss)
8. operationType тип операции purchase | refund | reversal
9. refnum reference number (от банка-эквайринга)
10. authcode авторизационный код (от банка-эмитента)
11. responce код ответа банка
12. result результат операции success | fail
13. traceNumber номер документа для банка

Если вы используете оплату по QR-коду, для проверки результата QR-платежа используйте следующий запрос /dump/qrbank/[номер-операции]/trackdocument. Если у вас настроены слоты EMV и QR, и при этом вы явно не указываете bankSlot, единственным способом проверить результат операции является поочередная проверка /dump/bank/... затем /dump/qrbank/.

6.3 Смены в банке

Детальная информация /dump/bank/batches

{
    "batches": [
        {
            "bankid": 1,
            "batch": 12,
            "status": "opened" | "expired"
        }
    ]
}

Получить результат можно выполнив запрос: /dump/bank/batches

bankid банковский слот
batch номер смены в банке
status состояние смены opened | expired

7. Проверка состояния

Для получения состояния iKKM используйте запрос /apicheck, Положительный ответ 0 - iKKM готов к работе. Код HTTP статуса будет 200, описание будет содержать номер последнего закрытого чека, если номер чека 0 (ноль) это означает что это новый iKKM.

Запрашивать состояние iKKM перед каждой регистрацией не нужно, так как любой метод регистрации проводит все проверки самостоятельно.

7.1 Дополнительные возможности apicheck

Детальная информация getInfo

{
  "applicationVersion": 122404, # версия приложения, целое число
  "batteryCapacityPerc": "80", # заряд батареи (если есть)
  "cashWeHave": "102878.00", # наличности в кассе
  "cashierID": "166", # ID текущего кассира
  "cashierName": "default", # имя кассира
  "currentShiftID": "45", # номер текущей рабочей смены
  "currentShiftStatus": "closed", # состояние смены (opened | closed)
  "databaseSizeKb": "654", # размер базы данных в кб
  "defaultApiTaxID": "1", # ID налога по умолчанию
  "factorySerialNumber": "000117184200028", # заводской номер iKKM
  "lastClosedChequeId": "864", # последний закрытый номер чека
  "messagesQueSize": "0", # очередь не отправленных сообщений в налоговую
  "ofdSysId": "127", # ОФД регистрационный номер (логин) *
  "ofdProtoVer": "202", # версия протокола ОФД
  "printingMode": "internal", # режим печати внешний или внутренний принтер
  "roudingRule": "yes", # использовать округление
  "shiftOpenedMinutes": 120, # Время в минутах с момента открытия смены *
  "statusOFD": "online", # статус ОФД offline | online *
  "offlineSeconds": "0", # время в секундах с момента наступления ОФД offline *
  "terminalDateTime": "26-11-2020 02:18:48", # текущее время на терминале
  "totalFlashUsedMb": "78", # всего использовано флеш памяти
  "totalRamUsedMb": "70" # свободно памяти
}

Для печати последнего чека используйте запрос /apicheck/printLastDocument
Для получения детальной информации об iKKM в формате JSON, используйте запрос /apicheck/getInfo?key=12345678
Рекомендуем запрашивать упрощенную версию отчета /apicheck/getInfo?show=minimum&key=12345678 В этом случае будет возвращено: номер последнего чека, текущий номер смены и статус, налог по-умолчанию, код и имя кассира.

8. Режим принтера

123456789012345678901234567890
Brick quiz whangs jumpy veldt 
fox!
--cut--
съешь ещё этих мягких францу-
зских булок, да выпей чаю.
--line--
Жылқының еті жесең-тісіне 
кіреді, жемесең-үсіңе кіреді.  
--cut--
--open-cash--

Для печати нужно передать параметр print содержащий текст на /apiprint. Передача запроса только POST, кодировка UTF-8. Разделители строк: \n. Допустимы следующие размеры строк:

Внутренний принтер: 24 символа нормальный шрифт, 32 маленький, 19 крупный.
LAN/USB принтер: 42 символа для 80мм бумаги и 30 символов для 57мм бумаги. Размер шрифта не предусмотрен при печати на внешнем принтере.

Если вы используете внешний принтер, доступны следующие команды:

--cut-- для отрезки бумаги
--line-- для печати горизонтальной линии
--open-cash-- для открытия денежного ящика подключенного к внешнему принтеру.

Печать логотипа в этом методе не предусмотрена.

9. Справочники и отчеты

Для удобной интеграции iKKM c вашим приложением предусмотрена выгрузка данных в JSON формате

9.1 Справочники

Справочник Товары

[{
    "uid": 11, # внутренний и уникальный код товара
    "code1": 888, # уникальный код товара
    "code2": "008123563127", # штрих-код
    "name": "Кофе", # наименование товара
    "price1": 77,  # розничная цена 
    "itemtax1": 2, # код налога (см справочник налоги)
    "itemtype": 0, # тип
    "measure": 0, # измерение
    "catalogid": 16 # код каталога (см справочник каталог)
},...
}]

Справочник Товары /dump/table/items

uid внутренний и уникальный код товара
code1 уникальный код товара
code2 штрих-код
name наименование товара
price1 розничная цена
itemtax1 код налога (см справочник налоги)
itemtype тип продукта | услуги
measure вид измерения
catalogid код каталога (см справочник каталог)

Справочник Каталог

{   "1": "Кухня",
    "2": "Бар",
    ... }

Справочник Каталог /dump/table/catalog

Внутренний код
Название папки

Справочник Налоги

version 1
{   "1": "НДС",
    "2": "Без НДС",
...}
version 2
[
    {
        "id": "1",
        "taxcode": "100",
        "taxname": "НДС",
        "taxpercent": "12%",
        "taxtype": "101"
    }
]

Справочник Налоги

Версия 1 /dump/table/taxes

Внутренний код
Наименование налога

При редактировании налога, например % ставки, автоматически изменится и код налога, поэтому жестко привязывать ID налога в вашей программе не следует.

Версия 2 /dump/table/taxes

Код налога
Код налога в ОФД
Название налога
Процент
ОФД Тип налога

Справочник Кассиры

version 1
{   "100": "Алия Кассир",
    "201": "Наташа Старший Кассир",
...}

version 2
[{
    "id": "1",
    "name": "admin",
    "role": "Администратор"
}],...

Справочник Кассиры

Версия 1 /dump/table/cashiers

Код кассира (совпадает с ОФД)
Имя кассира

Версия 2 /dump/table/cashiers/v2

id пользователя
имя пользователя
роль пользователя

9.2 Отчеты

Данные методы доступны пользователям Старший Кассир или Администратор. Все методы начинаются с /dump

Отчет по всем сменам

[{
    "id": 12, # Номер смены
    "opened": 0, # 1 - смена открыта, 0 - смена закрыта
    "openDate": "2016-01-18 20:41:06”, # дата открытия смены
    "closeDate": "2016-01-19 17:21:46", # дата закрытия смены
    "cashierId": 166, # код кассира
    "sale": 5210, # сумма всех продаж на начало смены
    "buy": 100, # сумма всех покупок на начало смены
    "saleReturn": 803, # сумма всех возвратов продаж на начало смены
    "buyReturn": 50 # сумма всех возвратов покупок на начало смены
},…
}]

Отчет по всем сменам /dump/table/shifts Возвращает все смены кроме архивных

id Номер смены
opened Статус смены: 1 - открыта, 0 - закрыта
openDate дата открытия смены (yyyy-MM-dd hh:mm:ss)
closeDate дата закрытия смены (yyyy-MM-dd hh:mm:ss)
cashierId код кассира
sale сумма всех продаж на начало смены
buy сумма всех покупок на начало смены
saleReturn всех возвратов продаж на начало смены
buyReturn сумма всех возвратов покупок на начало смены

Отчет по чекам

[{
    "chequeId": 244, # номер чека
    "chequeDate": "2016-01-18 20:41:08”, # дата открытия чека
    "chequeType": "1", # 0 - продажа, 1 - покупка, 2 - возврат продажи, 3 - возврат покупки
    "chequeSales": [{
        "id": 878, # код продажи
        "itemCode": "1001", # код товара (может быть пустой)
        "qty": 1, # количество (может быть Double)
        "price": 23, # цена за единицу
        "saleSum": 23, # сумма продажи
        "taxId": 2 # код налога
                 },…
             ],
…
}]

Отчет по чекам /dump/table/shifts/[номер-смены]/cheques

chequeId номер чека
chequeDate дата открытия чека
chequeType тип чека 0 - продажа, 1 - покупка, 2 - возврат продажи, 3 - возврат
chequeSales Табличная часть чека :
1. id код продажи
2. itemCode код товара (может быть пустой)
3. qty количество (может быть Double)
4. price цена за единицу
5. saleSum сумма продажи
6. taxId код налога

Используйте /salescheques вместо /cheques в конце запроса, для получения плоской структуры

Отчет по продажам

[{
    "id": 878, #  код продажи
    "chequeId": 244, # номер чека, сортировка результата по этому полю
    "itemCode": "1001",# код товара (может быть пустой)
    "qty": 2, # количество (может быть Double даже при включенном округлении сумм)
    "price": 30, # цена за единицу
    "saleSum": 60, # сумма продажи
    "taxId": 2  # код налога
},….]

Отчет по продажам /dump/table/shifts/[номер-смены]/sales

id код продажи
chequeId номер чека, сортировка результата по этому полю
itemCode код товара (может быть пустой)
qty количество (может быть Double даже при включенном округлении сумм)
price цена за единицу
saleSum сумма продажи
taxId код налога

Отчет по смене (z/x-отчет)

{   "shiftState": "closed",            # статус смены закрыта или открыта
    "dateOpen": "2016-07-18 20:03",    # время открытия смены 
    "dateClose": "2016-07-18 20:03",   # время закрытия смены (если смена закрыта)  
    "fiscalDataOnShiftOpen": {         # фискальные данные на начало смены
        "sale": 218861420.47,          # сумма всех продаж
        "buy": 529.70,                 # сумма всех  покупок
        "saleReturn": 19999600.00,     # сумма всех  возвратов продаж
        "buyReturn": 0.00 },           # сумма всех  возвратов покупок

    "totalSaleCheques": 1200,          # количество всех чеков продаж
    "saleDetails": {"sum": 1000.00, "cheques": 12 }, # сумма продаж за смену
    "totalBuyCheques": 1007,           # информация по покупкам
    "buyDetails": {"sum": 0.00,"cheques": 0 },
    "totalSaleReturnCheques": 1000,    # информация по возвратам продаж
    "saleReturnDetails": {"sum": 0.00,"cheques": 0 },
    "totalBuyReturnCheques": 947,      # информация по возвратам покупок
    "buyRetDetails": {"sum": 0.00,"cheques": 0},

    "cashOutDocCount": 1,              # количество документов снятий наличности
    "cashOutTotal": 100.00,            # снято наличности
    "cashInDocCount": 0,               # количество документов вноса наличности
    "cashInTotal": 0.00,               # внесено наличности
    "cashWeHave": 1108.00,             # наличности в кассе
    "revenue": 0.00,                   # доход
    "fiscalData": {                    # текущие фискальные данные
        "sales": 218867407.47,
        "buy": 529.70,
        "saleReturn": 19999600.00,
        "buyReturn": 0.00 }
}

...
    #Отчет по смене + налоги (.../reportwithtax)
    "taxes": {
        "sale": [{
            "taxId": 5,
            "turnover": 815.00,
            "taxDetails": [{
                "taxId": 5,
                "isIncluded": "true",
                "taxPercent": 12,
                "amount": 87.32
            }]
        }]...
    }

Отчет по смене (z/x-отчет) /dump/table/shifts/[номер-смены]/report

Если смена в архиве, будет возвращены только фискальные данные и значение isArhived=true

shiftState статус смены закрыта или открыта (closed | opened)
dateOpen время открытия смены (yyyy-MM-dd hh:mm:ss)
dateClose время закрытия смены (если смена закрыта)
fiscalDataOnShiftOpen фискальные данные на начало смены
- sale сумма всех продаж
- buy сумма всех покупок
- saleReturn сумма всех возвратов продаж
- buyReturn сумма всех возвратов покупок
totalSaleCheques количество всех чеков продаж
saleDetails продаж за смену
- sum сумма
- cheques количество чеков
totalBuyCheques количество всех чеков покупок
buyDetails покупок за смену
- sum сумма
- cheques количество чеков
totalSaleReturnCheques количество всех чеков по возвратам продаж
saleReturnDetails возвратов продаж за смену
- sum сумма
- cheques количество чеков
totalBuyReturnCheques количество всех чеков по возвратам покупок
buyRetDetails возвратов покупок за смену
- sum сумма
- cheques количество чеков
cashOutDocCount количество документов снятий наличности
cashOutTotal снято наличности
cashInDocCount количество документов вноса наличности
cashInTotal внесено наличности
cashWeHave наличности в кассе
revenue доход
fiscalData текущие фискальные данные, не зависят от выбранной смены (актуальны если вы указали ID последней смены)
- sale сумма всех продаж
- buy сумма всех покупок
- saleReturn сумма всех возвратов продаж
- buyReturn сумма всех возвратов покупок

Для включения в отчет налогов, используйте /reportwithtax вместо /report в конце запроса.

taxes налоги
- sale вид операции
  1. taxId код налога
  2. turnover оборот по налогу
  3. taxDetails детали налога
    - taxId код налога
    - isIncluded включен в сумму (bool)
    - taxPercent процент
    - amount сумма налога
- buy вид операции ...

Получение состояния чека

{
    "docid": "247", #  номер чека
    "createDate": "2016-01-20 18:10:43", # дата создания
    "submitDate": "2016-01-20 18:11:12", # дата отправки
    "status": 1, #  0 - не отправлен в ОФД, 1 - отправлен
    "onlineCode": "020223112" #  онлайн номер чека (может быть пустым)
}

Получение состояния чека [/dump/transaction/ключ-запрашиваемого-чека]

Пример: /dump/transaction/11112222?key=33334444 где: 11112222 - ключ с которым проводили документ, 33334444 - текущий верный ключ

docid номер чека
createDate дата создания (yyyy-MM-dd hh:mm:ss)
submitDate дата отправки (yyyy-MM-dd hh:mm:ss)
status статус 0 - не отправлен в ОФД, 1 - отправлен
onlineCode онлайн номер чека (может быть пустым)

10. Управление

10.1 Сессионные переменные

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

Гудок

Иногда требуется привлечь внимание кассира, используйте запрос: /apicheck/?beep=true

Быстрый Z-отчет

Причина долгого закрытия Z-Отчета (~ 40 секунд) состоит в необходимости временной задержки между снятием наличности из кассы и непосредственно закрытием смены. Если у вас снятие наличности происходит раздельно с закрытием смены, используйте быстрые таймеры Z-Отчета.

/apicheck/?timersFast=true - включить быстрый отчет (5-10 секунд)
/apicheck/?timersNormal=true - вернутся в нормальное состояние.

Работа с внешним LAN принтером

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

/apicheck/?keepLanPrinter=true - включить функцию поддержания связи
/apicheck/?closeLanPrinter=true - вернутся в нормальное состояние.

Переключение принтера

Если вам требуется переключится к примеру с LAN на внутренний принтер можно использовать данные запросы:

/apicheck/?getPrintMode=true - узнать какой сейчас принтер используется
/apicheck/?setPrintMode=[вид-принтера] - переключится на нужный принтер

Виды принтеров:

lan-printer
internal-printer
usb-printer

Управление отправкой в ОФД

Вы можете включить пакетную передачу сообщений в ОФД, используйте запрос: /apicheck/?ofdPacketMode=true

В случае если iKKM настроен на пакетную передачу сообщений в ОФД, используйте запрос: /apicheck/?pushTheQue=true для отправки сообщений, самостоятельно iKKM не будет отправлять сообщения.

Для возврата в нормальный режим используйте запрос: /apicheck/?ofdNormalMode=true

Отключить Web-Управление

Помимо API, в iKKM присутствует полноценный интерфейс по управлению и просмотру состояния устройства. Для отключения этого интерфейса используйте запрос: /apicheck/?disableWebMgmt=true

Ограничить доступ по IP

После отправки параметра /apicheck/?lockhost=true все последующие запросы от других хостов будут отклонены. Данная настройка действует до перезагрузки iKKM. В начале работы кассира, рекомендуем включать данную опцию для улучшения безопасности.

Запретить выходить из режима API на iKKM

Для запрета выхода из режима API с самого терминала /apicheck/?uilock=true . Данная настройка действует до перезагрузки iKKM. В начале работы кассира, рекомендуем включать данную опцию для улучшения безопасности.

Печать отчетов на виртуальном принтере в SQL

После отправки /apicheck/?reportsVirtualPrint=true Z-отчет/Банковская реконсиляция печатаются на виртуальном принтере в SQL базу, отчеты всегда можно посмотреть в WEB управлении iKKM (Первая страница - Журнал)

Дополнительный текст в чеке

Установить печать рекламного текста (как и другие переменные) можно в одном запросе, в самом начале работы ПО кассира.

Для того чтобы установить рекламный текст для печати в шапке чека, используйте '/apicheck', параметр printHeader, метод только POST. После выполнения запроса, переданный текст будет печататься на всех чеках до перезагрузки iKKM. Чтобы убрать рекламный текст отправьте тот же параметр: printHeader со значением clear.

Печать штрих-кода в чеке

Пример текста с печатью штрих-кода

Реклама * Реклама * Реклама *
--barcodeEAN13-7501031311309--
Вы можете печатать несколько
штрих-кодов в одном тексте
--barcode128-TESTCODE123--
продолжение текста...

Допустимы следующие команды для печати штрих-кода в тексте:

EAN13 --barcodeEAN13-[штрих-код 13 цифр]--
EAN8 --barcodeEAN8-[штрих-код 8 цифр]--
CODE128 --barcode128-[штрих-код 1-13 символов]--

В CODE128 разрешены символы: a-zA-Z0-9 !#$%&'()*+,-.:;<=>?@^~

QR код --qrcode-[текст 10-512 символов]--

В QR-code разрешены символы: a-zA-Z0-9 !#$%&'()*+,-.:;<=>?@^~/ \n

Открыть интерфейс Киоска

Для открытия интерфейса выбора услуг или товаров киоска, используйте /apikiosk

10.2 Системные функции

Для удаленного управления можно использовать следующие методы:

/apimanage/?doUpdate=true проверить и выполнить обновление прошивки
/apimanage/?doReboot=true перезагрузить iKKM
/dump/rawlog получить журнал ошибок

11. Коды ошибок

11.1 Все ошибки

TCP дамп ошибки (Не верный web-api ключ)

HTTP/1.1 400 incorrect-web-api-key
Content-Length: 2
Content-Type: text/html; charset=UTF-8
Date: 2017-02-15 15:00

-1

ответ	описание
[больше нуля]	данные приняты, возвращает новый web-api ключ * успех, сохранить web-api ключ для следующей операции
0	устройство готово к работе, можно провести регистрацию
-1	неверный web-api ключ, настроить новый ключ на iKKM
-2	происходит регистрация или банковская операция, повторите запрос позже
-3	смена превысила 24 часа, необходимо закрыть смену
-4	оффлайн период более 72 часов, решить проблему связи и разблокировать ккм
-5	низкий заряд батареи ккм
-6	принтер не готов, проверить бумагу
-7	ошибка запроса, проверьте передаваемые параметры
-8	ошибка метода
-9	ошибка значений параметров передавать только цифры (кроме параметра print)
-10	сумма cash (bank, tara, credit) меньше sale (buy…), проверьте логику работы с API
-11	смена открыта другим кассиром, закрыть смену
-12	значение cash меньше чем расчетная итоговая сумма, может возникнуть если налог насчитывается поверх суммы
-13	банк или тара или кредит больше чем итоговая сумма (или чек уже оплачен наличностью) проверьте логику работы с API
-14	ошибка налога, указанный налог не найден
-15	нет наличности в кассе (возврат продажи, покупка), проверьте передаваемые параметры
-16	операцию может проводить только старший кассир, проверить пользователя
-17	ошибка обработки JSON запроса в itemdata, проверьте логику работы с API
-18	отклонен IP адрес хоста с которого выполнен запрос
-19	требуется обновление, версия ikkm меньше чем требуется. см параметр requiredversion
-20	ошибка при работе c API по Bluetooth / USB, детали смотреть поле resultText
-21	невозможно запустить режим киоска, проверьте настройки
-100	…-199 ккм заблокирован ОФД. см документацию ОФД (отнять100)
-99	ошибка iKKM "смотрите журнал событий на iKKM в меню состояние устройства"
нет ответа	ккм не работает, проверьте сеть, включен ли режим web-api, итд

11.2 Короткие описания

Данные ошибки можно прочитать в HTTP заголовке, поле HTTP status description

HTTP status description	HTTP Body	описание
no-web-api-key-provided	-7	Не передан web-api ключ
incorrect-web-api-key	-1	Не верный web-api ключ
ikkm-is-blocked	-100	ОФД заблокировал iKKM
check-external-printer	-6	Нет связи с внешним принтером
check-printer-or-batt	-6	Нет бумаги или низкий заряд батареи
sale-param-error	-9	Ошибка передачи параметра
buy-param-error	-9	Ошибка передачи параметра
saleRet-param-error	-9	Ошибка передачи параметра
buyRet-param-error	-9	Ошибка передачи параметра
check-all-params	-7	Проверьте все параметры
payment-params-missed	-7	Параметры оплаты отсутствуют
cache-param-error	-7	Ошибка передачи параметра
bank-param-error	-7	Ошибка передачи параметра
tara-param-error	-7	Ошибка передачи параметра
credit-param-error	-7	Ошибка передачи параметра
cache-not-in-range	-7	Параметр за пределами значений
bank-not-in-range	-7	Параметр за пределами значений
tara-not-in-range	-7	Параметр за пределами значений
credit-not-in-range	-7	Параметр за пределами значений
sale-lq-one	-7	Значение меньше 1
sale-hq-20mil	-7	Значение больше 20000000
cash-lq-sale	-10	Наличность меньше суммы чека
bank-hq-sale	-10	Значение меньше 1
tara-hq-sale	-10	Значение меньше 1
credit-hq-sale	-10	Значение меньше 1
bank-tara-credit-hq-sale	-13	Оплата безналом больше чем сумма чека
no-cache-hq-sale	-13	Чек оплачен безналом, наличность запрещена
no-mixed-payment-allowed	-13	Смешанный вид оплаты выключен в настройках
change-not-allowed	-13	Сдача запрещена в данной операции
tax-invlid-num	-14	Неправильный код налога
tax-not-found	-14	Код налога не найден
cash-lq-tax	-12	Сумма чека (с налогом) больше принятой оплаты
no-cash-in-pos	-15	Нет наличности в кассе
internal-error	-99	Внутренняя ошибка кассы (повреждена БД)
wrong-cashier	-11	Смену открыл другой кассир
shift-gt-24h	-3	Смена отрыта более 24 часов
no-last-document	-7	Нет последнего документа
print-lines-parse-error	-7	Ошибка парсинга параметра print
only-master-cashier	-16	Операцию может провести только старший кассир
payment-params-missed	-7	Пропущены параметры (см внос/снятие наличности)
cache-param-error	-9	Ошибка передачи параметра
cache-not-in-range	-9	Параметр за пределами значений
shift-gt-7days	-3	Смена открыта более 7 дней
incorrect-method	-8	Неправильно указан метод
unknown-error	-99	Неизвестная ошибка