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

Содержание

• Список сокращений
• Описание работы
• Общее описание протокола
• Описание команд
  • Регистрация публичного ключа терминала SET_KKM_PUBLIC_KEY
  • Получение информации о терминале GET_KKM_INFO
  • Регистрация чековой транзакции REGISTER_TICKET
  • Взнос наличных DEPOSIT_MONEY
  • Изъятие наличных WITHDRAW_MONEY
  • Закрытие смены CLOSE_SHIFT
• Коды ошибок

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

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

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

После регистрации необходимо сгенерировать ключевую пару и зарегистрировать публичный ключ в СФД отправив команду 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_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

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

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

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

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

• 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

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

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

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

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

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

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

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

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

Получение информации о терминале 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"
    }
}
   

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

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

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

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

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

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

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

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

Регистрация чековой транзакции 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"
        },
        {
            "type": "STORNO_COMMODITY",
            "section_code": "Секция 1",
            "name": "Пицца с грибами - отмена",
            "quantity": "2.000",
            "price": "200.00",
            "total": "400.00"
        },
        {
            "type": "COMMODITY",
            "section_code": "Секция 1",
            "name": "Пицца с сыром",
            "quantity": "1.000",
            "price": "200.00",
            "total": "200.00"
        },
        {
            "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": "Иванов"
    }
}

• Список поддерживаемых типов items:
  • COMMODITY
  • STORNO_COMMODITY
  • DISCOUNT
  • STORNO_DISCOUNT
  • MARKUP
  • STORNO_MARKUP
• Список поддерживаемых типов total_modifier:
  • DISCOUNT
  • MARKUP
• taxes - налог с определенным процентом должен встречаться не более одного раза.

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

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

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

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

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

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

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

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

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

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

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

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

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

Типы операций (TICKET_OPERATION_TYPE_ENUM)

Типы налогооблажения (TAXATION_TYPE_ENUM)

Типы налогов (TAX_TYPE_ENUM)

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

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

Если платеж был офлайн, то 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"
}

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

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

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

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

{
    "type": "DEPOSIT_MONEY",
    "client_txn_id": "603dc6a3-ab05-49d0-9059-ed3599b2fae7",
    "client_txn_date": "2018-05-03T16:27:30",
    "amount": "2345.00"
}

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

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

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

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

{
   "type": "CLOSE_SHIFT",
   "shift_number": 5,
   "cashier": {
        "code": 12,
        "name": "Иванов"
   }
}

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

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

Коды ошибок

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

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

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

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