Перейти к основному содержимому

Фискальная система v1.2

Данный документ является описанием взаимодействия ККМ с фискальной системой КИВИ Казахстан.

Содержание​

Список изменений​

Версия 1.2 - 29.01.2026

  • Добавлен код единицы измерения в ИС ЭСФ
  • Добавлены сферы деятельности
  • Добавлена передача родительской транзакции

Список сокращений​

ТерминОписание
СФДСистема фискальных данных QIWI
ОФДОператор фискальных данных ОФД (Казактелеком, Транстелеком)
ККМКонтрольно кассовая машина
АРМАвтоматизированное рабочее место (веб портал)

Описание работы​

Прежде чем начать работу ККМ должен быть зарегистрироан в СФД.

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

ККМ должен с некоторой периодичностью (примерно раз в 5 минут) запрашивать информацию о терминале GET_KKM_INFO для актуализации информации о ККМ.

Общее описание протокола​

  • URL адрес: api.osfd.kz
  • Коммуникация осуществляется по протоколу HTTP.
  • Тело запроса и ответа должны быть в кодировке UTF-8.
  • В качестве формата обмена данными используется JSON. В случае, если какие-либо поля не обязательны, они опускаются. Также допускается, чтобы значением этих полей был null.

Формат запроса​

  • Все операции осуществляются методом POST. На все другие методы сервер будет возвращать ошибку 405 Method Not Allowed
  • В заголовке должен быть указан идентификатор ККМ QF-KKM-ID.
  • Все запросы должны быть подписаны приватным ключем терминала. Подписываться должно тело запроса. Сама подпись должна быть в формате hex и передаваться в заголовоке QF-Request-Sign.

Поддерживаемые алгоритмы подписи:

  • SHA256withRSA
  • SHA1withRSA

Пример полного запроса с заголовками и подписью​

POST / HTTP/1.1
Host: api.osfd.kz
Content-Length: 125
QF-KKM-ID: K24829
QF-Request-Sign-Alg: SHA256withRSA
QF-Request-Sign: babbb9da99411bf2440cd852ec7b4ba65d9ecb19590a51a90f183c88793ea52edf4b374d73fe0a277bb00fb6e1e2b9f811a76aea290f9cdccfcf63fd0f00f887431086f096e99694f33d62f47e66cfe5be684e3235df3e342267d03f2a0900ffa59bcc24f1bc571181a8d57d38b0c26389a786c8a9dd34ebce0a54882121d8f28efdd062931b36545a1268088bbde3c35fa530cbfd0172c768a4709dd1022201016629ce2c405e9390d4c17ca00ff07cb12cc0b29eb6727d4500fb6e47ae9f8ab7351931d1144ca5c5e4c46ae7e82b6072baba62bfe51819340ef4da14cfd63cd728c7bc4a544c9348e720dae20875bd6ffc1e030b2230b698aa4a6c570767d2

{"api_version":"1.0","client_soft":"KKM Emulator v1.0","kkm_id":"K24829","command":{"type":"GET_KKM_INFO"}}

Общая структура запроса​

{
    "api_version": "1.0",
    "kkm_id": "1234567",
    "client_request_id": "fa2cf7dd-fca3-42a8-b0bc-ebba0b945888",
    "client_soft": "Cashier 3000",
    "command": {
        "type" : "DO_COMMAND",
        "arg1" : "val1",
        "arg2" : "val2"
    }
}

REQUEST​

ПараметрТипОбязательныйОписание
api_versionstringДаВерсия протокола
kkm_idstringДаИдентификатор терминала
client_request_idstringНетИдентификатор запроса
client_softstringНетИнформация о ПО на клиенте
commandobjectДаКоманда

  • api_version - Версия состоит из двух частей. major.minor

    • major - Старшая версия протокола. Если эта версия меняется, то протокол не имеет обратной совместимости.
    • minor - Младшая версия протокола. Если эта версия меняется, то протокол имеет обратную совместимость. В этом случае поля только добавляются либо переходят в статус необязательных.

  • client_request_id - служит для сверки логов запроса и ответа от сервера. Клиент генерирует его самостоятельно и обеспечивает его уникальность.

Формат ответа​

{
    "api_version": "1.0",
    "client_request_id": "fa2cf7dd-fca3-42a8-b0bc-ebba0b945888",
    "error_code": 0,
    "error_token": "OK",
    "error_message": "Операция выполнена успешно",
    "result": {
        "some_property": "some_value"
    }
}

RESPONSE​

ПараметрТипОбязательныйОписание
api_versionstringДаВерсия протокола
client_request_idstringНетИдентификтор запроса
error_codei32ДаЦифровой код ответа
error_tokenstringДаСимвольный код ошибки
error_messagestringДаОписание кода ошибки
session_idguidДаИдентификатор сессии
resultobjectНетРезультат выполения команды

  • client_request_id - идентификатор который был передан в запросе.

  • error_token - токен ошибки. Это своеобразный литеральный идентификатор. Служит для обозначения возможных кодов ошибки в более понятном виде как для человека так и для устройства. Утройство может распозновать ответ как по коду ошибки так и по токену ошибки.

  • result - Возвращаемое значение комманды. Если команда не подразумевает результат, то свойство опускается.

Описание примитивных типов данных​

ТипОписаниеФормат
i16Целочисленный со знаком-32768 : 32767
i32Целочисленный со знаком–2147483648 : 2147483647
i64Целочисленный со знаком-9223372036854775808 : 9223372036854775807
moneyЧисло с фикс. точностью 19 и масштабом 2-92233720368547758.08 : 92233720368547758.07
num_10_3Число с фикс. точностью 10 и масштабом 3–2147483.648 : 2147483.647
stringСтроковый
boolБулевыйtrue, false
datetimeДата и время"YYYY-MM-DDThh:mm:ss"
guidУниверсальный уникальный идентификатор"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
intervalВременной интервал"hh:mm"
hexМассив байт"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

  • datetime - Дата и время должны быть в формате YYYY-MM-DDThh:mm:ss. Данный формат совместим с ISO 8601. Например дата 24.06.2018 18:30:02 по времени Астаны должна быть 2018-06-24T18:30:02.

  • hex - Массив байт должен передаваться в шеснадцетиричном формате, нижнего регистра без разделителей байт.
    Например: "bd637b59816232bf99f183fb7b8a6a06"

  • money - Значение может передаваться в виде текстового значения.
    Например: "12.05"

  • num_10_3 - Значение может передваться в виде текстового значения.
    Например: "12.345"

Описание общих типов данных​

Информация об операторе-кассире CASHIER_INFO​

ПараметрТипОбязательныйОписание
codeintДаКод оператора-кассира
namestringДаИмя оператора-кассира

Описание команд​

Регистрация публичного ключа терминала SET_KKM_PUBLIC_KEY​

Формат аргументов запроса​

{
    "type": "SET_KKM_PUBLIC_KEY",
    "kkm_pub_key": {
        "type": "RSA_PUBLIC_KEY",
        "modulus": "00aa18aba43b50deef38598faf87d2ab634e4571c130a9bca7b878267414faab8b471bd8965f5c9fc",
        "public_exponent": "010001"
    }
}

ПараметрТипОбязательныйОписание
kkm_pub_keyobjectДаПубличный ключ ккм
  • Список поддерживаемых типов kkm_pub_key:
    • RSA_PUBLIC_KEY

Публичный ключ RSA RSA_PUBLIC_KEY​

ПараметрТипОбязательныйОписание
modulushexДаМодуль
public_exponenthexДаОткрытая экспонента

Формат результата ответа​

Команда не подразумевает результат.

Получение информации о терминале GET_KKM_INFO​

Формат аргументов запроса​

{
    "type": "GET_KKM_INFO"
}

Формат результата ответа​

{
    "kkm": {
        "kkm_id": "123456",
        "kkm_serial_number": "345234",
        "kkm_kgd_id": "123456789012",
        "timezone": "06:00",
        "is_ready": true,
    },
    "organization": {
        "title": "ТОО Касса 24/7",
        "address": "Жубанова 42",
        "iinbin": "123456789012",
    },
    "position": {
        "title": "Торговая точка 1",
        "address": "Муканова 23",
    },
    "taxation": {
        "taxation_type": "USN",
        "taxes":[
            {
                "tax_type": "NDS",
                "tax_rate_percent": "18.000"
            }

        ]
    },
    "cash_amount": "1240.00",
    "last_shift": {
        "shift_number": 123,
        "open_date": "2019-03-13T23:44:00",
        "is_closed": true,
        "expiry_date": "2019-03-14T23:44:00",
        "close_date": "2019-03-13T22:44:00"
    }
}
ПараметрТипОбязательныйОписание
kkmKKM_INFOДаИнформация о ккм
organisationORGANISATION_INFOДаИнформация об организации
positionPOSITION_INFOДаИнформация о позиции продажи
cash_amountmoneyДаКоличество наличных в кассе
taxationTAXATION_INFOНетИнформация о привязанном налогоблажении
last_shiftLAST_SHIFT_INFOНетИнформация о последней смене

Информация о последней смене LAST_SHIFT_INFO​

ПараметрТипОбязательныйОписание
shift_numberi32ДаНомер смены
open_datedatetimeДаДата открытия смены
is_closedboolДаЗакрыта ли смена
expiry_datedatetimeДаДата истечения смены, если смена закрыта
close_datedatetimeНетДата закрытия смены, если смена закрыта

Информация о ккм KKM_INFO​

ПараметрТипОбязательныйОписание
kkm_idstringДаИдентификатор ККМ в СФД
kkm_serial_numberi32ДаЗаводской номер ККМ
kkm_kgd_idstringДаКод ККМ КГД
timezoneintervalДаЧасовой пояс к которому привязан ККМ
is_readyboolДаГотов ли терминал к работе

  • is_ready - Если стутус false то ККМ должен приостановить свою работу. Это может быть в следующих случаях:

    • ККМ находится в стадии постановки на учёт
    • ККМ находится в стадии снятия с учёта
    • ККМ находится в режиме программирования
    • Запрет на проведение платежей со стороны ОФД
    • Выполнение фискальных операций со стороны АРМа

Информация об организации ORGANIZATION_INFO​

ПараметрТипОбязательныйОписание
iinbinstringДаИИН / БИН
titlestringНетНазвание организации
addressstringНетАдрес организации

Информация о точке продажи POSITION_INFO​

ПараметрТипОбязательныйОписание
titlestringНетНазвание торговой точки
addressstringНетАдрес торговой точки

Информация о налогоблажении TAXATION_INFO​

ПараметрТипОбязательныйОписание
taxation_typeTAXATION_TYPE_ENUMДаТип налогоблажения
taxesTAX_INFO[]НетИнформация о налогах

Информация о налоге TAX_INFO​

ПараметрТипОбязательныйОписание
tax_typeTAX_TYPE_ENUMДаТип налога
tax_rate_percentnum_10_3ДаПроцент налога

Регистрация чековой транзакции REGISTER_TICKET​

Формат аргументов запроса​

{
    "type": "REGISTER_TICKET",
    "client_txn_id": "d108a81b-1a0e-4b7b-824e-a25bd64b21a4",
    "client_txn_date": "2018-05-03T16:27:30",
    "is_offline": false,
    "operation_type" : "SELL",
    "total": "180.00",
    "items": [
        {
            "type": "COMMODITY",
            "section_code": "Секция 1",
            "name": "Пицца с грибами",
            "quantity": "2.000",
            "price": "200.00",
            "total": "400.00",
            "measure_unit_code": "642"
        },
        {
            "type": "STORNO_COMMODITY",
            "section_code": "Секция 1",
            "name": "Пицца с грибами - отмена",
            "quantity": "2.000",
            "price": "200.00",
            "total": "400.00",
            "measure_unit_code": "642"
        },
        {
            "type": "COMMODITY",
            "section_code": "Секция 1",
            "name": "Пицца с сыром",
            "quantity": "1.000",
            "price": "200.00",
            "total": "200.00",
            "measure_unit_code": "642"
        },
        {
            "type": "MARKUP",
            "name": "Наценка",
            "total": "20.00"
        },
    ],

    "total_modifier": {
        "type": "DISCOUNT",
        "name": "Общая скидка",
        "total": "40.00"
    },

    "taxes" : [
        {
            "tax_type": "NDS",
            "taxation_type": "USN",
            "tax_rate_percent": "18.000",
            "total": "27.46",
            "is_included_in_total": true
        },
        {
            "tax_type": "NDS",
            "taxation_type": "USN",
            "tax_rate_percent": "10.000",
            "total": "13.86",
            "is_included_in_total": true
        },
    ],

    "payments": {
        "cash": {
            "amount": "180.00",
            "taken": "1000.00",
            "change": "820.00"
        }
    },
    "cashier": {
        "code": 12,
        "name": "Иванов"
    },
    "customer": {
       "iinbin": "123456789012"
    }
}

ПараметрТипОбязательныйОписание
client_txn_idguidДаИдентификатор транзакции присваиваемый клиентом
client_parent_txn_idguidДа (при отмене)Идентификатор родительской транзакции. Только при SELL_RETURN либо BUY_RETURN
client_txn_datedatetimeДаДата транзакции на момент операции
is_offlineboolДаРежим офлайн или онлайн (был распечатан чек или нет)
operation_typeTICKET_OPERATION_TYPE_ENUMДаТип операций
totalmoneyДаИтоговая сумма чековой транзакции
itemsobject[]ДаСписок товаров / услуг
total_modifierobjectНетОбщая скидка или наценка
taxesTAX[]НетНалог на чек (отсутствует если налоги укзаны в элементах)
paymentPAYMENT_INFOДаИнформация о платеже
cashierCASHIER_INFOНетИнформация об операторе-кассире
customerCUSTOMER_INFOНетИнформация о покупателе
domainDOMAIN_INFOНетИнформация о сфере деятельности

  • Список поддерживаемых типов items:

    • COMMODITY
    • STORNO_COMMODITY
    • DISCOUNT
    • STORNO_DISCOUNT
    • MARKUP
    • STORNO_MARKUP

  • Список поддерживаемых типов total_modifier:

    • DISCOUNT
    • MARKUP

  • taxes - налог с определенным процентом должен встречаться не более одного раза.

Также если указано поле taxes в чеке, то в отдельных элементах items/taxes оно должно отсутствовать.

  • Список поддерживаемых типов domain:
    • TRADING_DOMAIN
    • SERVICES_DOMAIN
    • TAXI_DOMAIN
    • PARKING_DOMAIN
    • HOTELS_DOMAIN
    • GASOIL_DOMAIN

Информация о товаре услуге COMMODITY​

ПараметрТипОбязательныйОписание
section_codestringДаКод секции или отдела
namestringДаНаименование
quantitynum_10_3ДаКоличество
pricemoneyДаЦена
totalmoneyДаИтоговая сумма
taxesTAX[]НетСписок налогов (отсутствует если есть в чеке)
excise_stampstringНетНомер акцизной марки
measure_unit_codestringНетКод единицы измерения в ИС ЭСФ

Информация о сторно товара / услуги STORNO_COMMODITY​

ПараметрТипОбязательныйОписание
section_codestringДаКод секции или отдела
namestringДаНаименование
quantitynum_10_3ДаКоличество
pricemoneyДаЦена
totalmoneyДаИтоговая сумма
taxesTAX[]НетСписок налогов (отсутствует если есть в чеке)
excise_stampstringНетНомер акцизной марки
measure_unit_codestringНетКод единицы измерения в ИС ЭСФ

Информация о скидке DISCOUNT​

ПараметрТипОбязательныйОписание
namestringДаНаименование
totalmoneyДаИтоговая сумма
taxesTAX[]НетСписок налогов (отсутствует если есть в чеке)

Информация о сторно скидки STORNO_DISCOUNT​

ПараметрТипОбязательныйОписание
namestringДаНаименование
totalmoneyДаИтоговая сумма
taxesTAX[]НетСписок налогов (отсутствует если есть в чеке)

Информация о наценке MARKUP​

ПараметрТипОбязательныйОписание
namestringДаНаименование
totalmoneyДаИтоговая сумма
taxesTAX[]НетСписок налогов (отсутствует если есть в чеке)

Информация о сторно наценки STORNO_MARKUP​

ПараметрТипОбязательныйОписание
namestringДаНаименование
totalmoneyДаИтоговая сумма
taxesTAX[]НетСписок налогов (отсутствует если есть в чеке)

Информация о налоге TAX​

ПараметрТипОбязательныйОписание
tax_typeTAX_TYPE_ENUMДаТип налога
taxation_typeTAXATION_TYPE_ENUMДаТип налогоблажения
tax_rate_percentnum_10_3ДаЗначение налога в процентах
totalmoneyДаЗначение налога в деньгах
is_included_in_totalboolДаЗаложен ли налог в сумму

Информация о платеже PAYMENT​

ПараметрТипОбязательныйОписание
cashCASH_PAYMENTНетИнфо об оплате наличными
cardCARD_PAYMENTНетИнфо об оплате картой
creditCREDIT_PAYMENTНетИнфо об оплате в кредит
tareTARE_PAYMENTНетИнфо об оплате тарой

Информация о наличном платеже CASH_PAYMENT​

ПараметрТипОбязательныйОписание
amountmoneyДаСумма для оплаты наличными
takenmoneyДаПринято наличными
changemoneyДаСдача

Информация о платеже картой CARD_PAYMENT​

ПараметрТипОбязательныйОписание
amountmoneyДаСумма для оплаты наличными

Информация о платеже кредитом CREDIT_PAYMENT​

ПараметрТипОбязательныйОписание
amountmoneyДаСумма для оплаты наличными

Информация о платеже тарой TARE_PAYMENT​

ПараметрТипОбязательныйОписание
amountmoneyДаСумма для оплаты наличными

Информация о покупателе CUSTOMER_INFO​

ПараметрТипОбязательныйОписание
iinbinstringНетИИН / БИН покупателя
phonestringНетТелефон покупателя
emailstringНетE-mail покупателя
Типы операций (TICKET_OPERATION_TYPE_ENUM)​
ЗначениеОписание
BUYПокупка
BUY_RETURNВозврат покупки
SELLПродажа
SELL_RETURNВозврат продажи
Типы налогооблажения (TAXATION_TYPE_ENUM)​
ЗначениеОписание
USNУСН
OSNОСН
PEASANT_AND_FARMНалоговый режим для крестьянских и фермерских хозяйств
SMALL_BUSINESS_PATENTНалоговый режим для малых предприятий на основе патента
Типы налогов (TAX_TYPE_ENUM)​
ЗначениеОписание
NDSНДС

Торговая сфера TRADING_DOMAIN​

Не содержит полей.

Сфера услуг SERVICES_DOMAIN​

ПараметрТипОбязательныйОписание
account_numberstringДа

Сфера обеспечения нефтепродуктами GASOIL_DOMAIN​

ПараметрТипОбязательныйОписание
card_numberstringНет
correction_numberstringНет
correction_summoneyНет

Отели и рестораны HOTELS_DOMAIN​

Не содержит полей.

Такси TAXI_DOMAIN​

ПараметрТипОбязательныйОписание
car_numberstringДа
is_orderboolДа
current_feemoneyДа

Стоянки PARKING_DOMAIN​

ПараметрТипОбязательныйОписание
begin_timedatetimeДа
end_timedatetimeДа

Формат аргументов ответа​

{
    "is_offline": false,
    "ofd_ticket_number": "AS2304342",
    "ofd_ticket_qr_code": "687474703a2f2f636f6e73756d65722e746573742d6f6f66642e6b7a3f693d3131393635373238373126663d36373839383031323334353626733d302e3026743d323032303035313854313831383137",
    "offline_ticket_number": 123453,
    "shift_number": 22,
    "shift_document_number": 11
}

ПараметрТипОбязательныйОписание
ofd_ticket_numberstringНетНомер чека полученый от ОФД
ofd_ticket_qr_codehexНетQR код, полученный от ОФД
offline_ticket_numberi32ДаАвтономный номер чека
is_offlineboolДаЧек был онлайн или офлайн
shift_numberi32ДаНомер смены
shift_document_numberi32ДаНомер документа в смене

Если платеж был офлайн, то is_offline: true, а ofd_ticket_number и ofd_ticket_qr_code будут отсутствовать.

Изъятие наличных WITHDRAW_MONEY​

Формат аргументов запроса​

{
    "type": "WITHDRAW_MONEY",
    "client_txn_id": "5d8b06e4-0560-4dcd-8162-8bb23f5ee258",
    "client_txn_date": "2018-05-03T16:27:30",
    "amount": "2345.00"
}
ПараметрТипОбязательныйОписание
client_txn_idguidДаИдентификатор транзакции клиента
client_txn_datetimestampДаДата транзакции
amountmoneyДаКоличество денег

Формат аргументов ответа​

{
    "shift_number": 22,
    "shift_document_number": 11
}

ПараметрТипОбязательныйОписание
shift_numberi32ДаНомер смены
shift_document_numberi32ДаНомер документа в смене

Взнос наличных DEPOSIT_MONEY​

Формат аргументов запроса​

{
    "type": "DEPOSIT_MONEY",
    "client_txn_id": "603dc6a3-ab05-49d0-9059-ed3599b2fae7",
    "client_txn_date": "2018-05-03T16:27:30",
    "amount": "2345.00"
}
ПараметрТипОбязательныйОписание
client_txn_idguidДаИдентификатор транзакции клиента
client_txn_datetimestampДаДата транзакции
amountmoneyДаКоличество денег

Формат аргументов ответа​

{
    "shift_number": 22,
    "shift_document_number": 11
}

ПараметрТипОбязательныйОписание
shift_numberi32ДаНомер смены
shift_document_numberi32ДаНомер документа в смене

Закрытие смены CLOSE_SHIFT​

Формат аргументов запроса​

{
   "type": "CLOSE_SHIFT",
   "shift_number": 5,
   "cashier": {
        "code": 12,
        "name": "Иванов"
   }
}
ПараметрТипОбязательныйОписание
shift_numberi32ДаНомер смены
cashierCASHIER_INFOНетИнформация об операторе-кассире

shift_number - должен быть последней открытой сменой

Команда не подразумевает результат.

Коды ошибок​

Успешное завершение операции 0​

КодТокенОписание
0OKОперация выполнена успешно.

Ошибки формата запроса 1xx​

КодТокенОписание
100FMT_ERRНеверный формат запроса.

Ошибки предметной области 2xx​

КодТокенОписание
200DMN_ERRВ данный момент невозможно выполнить данную операцию в текущем состоянии терминала либо с текущими параметрами.
201DMN_ERR_AUTH_FAILEDНеверный идентификатор терминала или подпись.
202DMN_ERR_KKM_NOT_FOUNDНе найден ККМ.
203DMN_ERR_NOT_ENOUGH_CASHНедостаточно наличных для выполнения операции.
204DMN_ERR_KKM_BLOCKEDТерминал заблокирован. Любые операции запрещены
205DMN_ERR_KKM_BLOCKED_BY_OFDТерминал заблокирован на стороне ОФД. Фискальные операции запрещены.
206DMN_ERR_KKM_BLOCKED_BY_OFD_ERRORТерминал заблокирован т.к. имеентся ошибка при передаче данных в ОФД. Требуется ручное вмешательство.
207DMN_ERR_SHIFT_NOT_FOUNDНе найдена смена.
208DMN_ERR_INVALID_TICKETЧек неправильно сформирован.

Ошибки сервера 3xx​

КодТокенОписание
300SRV_ERRОшибка на стороне сервера. В данном случае необходимо отправить запрос позже.