Fiscal System v1.2

This document describes the interaction between the Cash Register Machine (CRM) and the QIWI Kazakhstan fiscal system.

---

Table of Contents

• List of Abbreviations
• Change Log
• System Description
• General Protocol Description
• Command Description
  • Terminal Public Key Registration SET_KKM_PUBLIC_KEY
  • Get Terminal Information GET_KKM_INFO
  • Register Ticket Transaction REGISTER_TICKET
  • Cash Deposit DEPOSIT_MONEY
  • Cash Withdrawal WITHDRAW_MONEY
  • Shift Close CLOSE_SHIFT
• Error Codes

Change Log

Version 1.2 - 2026-01-29

• Added unit of measure code for ESF Information System
• Added activity domains
• Added parent transaction transmission

List of Abbreviations

Term	Description
FDS	QIWI Fiscal Data System
OFD	Fiscal Data Operator OFD (Kazakhtelecom, Transtelecom)
CRM	Cash Register Machine
ARM	Automated Workplace (web portal)

System Description

Before starting work, the CRM must be registered in the FDS.

After registration, it is necessary to generate a key pair and register the public key in the FDS by sending the SET_KKM_PUBLIC_KEY command. After successful key registration, the CRM can enter operational mode and perform fiscal operations.

The CRM should periodically (approximately every 5 minutes) request terminal information GET_KKM_INFO to update CRM information.

General Protocol Description

• URL address: api.osfd.kz
• Communication via HTTP protocol.
• Request and response bodies must be in UTF-8 encoding.
• Data exchange format is JSON. If any fields are not required, they are omitted. It is also allowed for the value of these fields to be null.

Request Format

• All operations are performed using the POST method. The server will return error 405 Method Not Allowed for all other methods.
• The CRM identifier QF-KKM-ID must be specified in the header.
• All requests must be signed with the terminal's private key. The request body must be signed. The signature itself must be in hex format and passed in the QF-Request-Sign header.

Supported signature algorithms:

• SHA256withRSA
• SHA1withRSA

Example of a complete request with headers and signature

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"}}

General Request Structure

{
    "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

Parameter	Type	Required	Description
api_version	string	Yes	Protocol version
kkm_id	string	Yes	Terminal identifier
client_request_id	string	No	Request identifier
client_soft	string	No	Client software information
command	object	Yes	Command

• api_version - Version consists of two parts. major.minor

  • major - Major protocol version. If this version changes, the protocol is not backward compatible.
  • minor - Minor protocol version. If this version changes, the protocol is backward compatible. In this case, fields are only added or transition to optional status. In this case, fields are only added or transition to optional status.

• client_request_id - serves to match logs of requests and responses from the server. The client generates it independently and ensures its uniqueness.

Response Format

{
    "api_version": "1.0",
    "client_request_id": "fa2cf7dd-fca3-42a8-b0bc-ebba0b945888",
    "error_code": 0,
    "error_token": "OK",
    "error_message": "Operation completed successfully",
    "result": {
        "some_property": "some_value"
    }
}

RESPONSE

Параметр	Тип	Обязательный	Описание
api_version	string	Yes	Protocol version
client_request_id	string	No	Request identifier
error_code	i32	Yes	Numeric response code
error_token	string	Yes	Symbolic error code
error_message	string	Yes	Error code description
session_id	guid	Yes	Session identifier
result	object	No	Command execution result

• client_request_id - identifier that was passed in the request.

• error_token - error token. This is a kind of literal identifier. Serves to denote possible error codes in a more understandable form for both humans and devices. A device can recognize the response either by error code or by error token.

• result - Command return value. If the command does not imply a result, the property is omitted.

Primitive Data Types Description

Type	Description	Format
i16	Signed integer	-32768 : 32767
i32	Signed integer	–2147483648 : 2147483647
i64	Signed integer	-9223372036854775808 : 9223372036854775807
money	Fixed precision number 19 with scale 2	-92233720368547758.08 : 92233720368547758.07
num_10_3	Fixed precision number 10 with scale 3	–2147483.648 : 2147483.647
string	String
bool	Boolean	true, false
datetime	Date and time	"YYYY-MM-DDThh:mm:ss"
guid	Universally unique identifier	"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
interval	Time interval	"hh:mm"
hex	Byte array	"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

• datetime - Date and time must be in the format YYYY-MM-DDThh:mm:ss. This format is compatible with ISO 8601. For example, date 24.06.2018 18:30:02 Astana time should be 2018-06-24T18:30:02.

• hex - Byte array must be transmitted in hexadecimal format, lowercase without byte separators.
  Example: "bd637b59816232bf99f183fb7b8a6a06"

• money - Value can be transmitted as text.
  Example: "12.05"

• num_10_3 - Value can be transmitted as text.
  Example: "12.345"

Common Data Types Description

Cashier Operator Information CASHIER_INFO

Parameter	Type	Required	Description
code	int	Yes	Cashier operator code
name	string	Yes	Cashier operator name

Command Description

Terminal Public Key Registration SET_KKM_PUBLIC_KEY

Request Arguments Format

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

Parameter	Type	Required	Description
kkm_pub_key	object	Yes	KKM public key

• List of supported kkm_pub_key:
  • RSA_PUBLIC_KEY

RSA Public Key RSA_PUBLIC_KEY

Parameter	Type	Required	Description
modulus	hex	Yes	Modulus
public_exponent	hex	Yes	Public exponent

Response Result Format

The command does not imply a result.

Get Terminal Information GET_KKM_INFO

Request Arguments Format

{
  "type": "GET_KKM_INFO"
}

Response Result Format

{
  "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"
  }
}

Parameter	Type	Required	Description
kkm	KKM_INFO	Yes	KKM information
organisation	ORGANISATION_INFO	Yes	Organization information
position	POSITION_INFO	Yes	Sales position information
cash_amount	money	Yes	Amount of cash in the cash register
taxation	TAXATION_INFO	No	Information about linked taxation
last_shift	LAST_SHIFT_INFO	No	Information about the last shift

Last Shift Information LAST_SHIFT_INFO

Parameter	Type	Required	Description
shift_number	i32	Yes	Shift number
open_date	datetime	Yes	Shift opening date
is_closed	bool	Yes	Whether the shift is closed
expiry_date	datetime	Yes	Shift expiry date, if the shift is closed
close_date	datetime	No	Shift closing date, if the shift is closed

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

Parameter	Type	Required	Description
kkm_id	string	Yes	ККМ identifier in SFD
kkm_serial_number	i32	Yes	ККМ factory number
kkm_kgd_id	string	Yes	ККМ KGD code
timezone	interval	Yes	Timezone to which the KKM is bound
is_ready	bool	Yes	Whether the terminal is ready for work

• is_ready - If status is false then the CRM must suspend its operation. This can be in the following cases:

  • ККМ is in the registration stage
  • ККМ is in the deregistration stage
  • ККМ is in programming mode
  • Payment prohibition from the OFD side
  • Fiscal operations being performed from the ARM side

Organization Information ORGANIZATION_INFO

Parameter	Type	Required	Description
iinbin	string	Yes	IIN/BIN
title	string	No	Organization name
address	string	No	Organization address

Sales Point Information POSITION_INFO

Parameter	Type	Required	Description
title	string	No	Sales point name
address	string	No	Sales point address

Taxation Information TAXATION_INFO

Parameter	Type	Required	Description
taxation_type	TAXATION_TYPE_ENUM	Yes	Taxation type
taxes	TAX_INFO[]	No	Tax information

Tax Information TAX_INFO

Parameter	Type	Required	Description
tax_type	TAX_TYPE_ENUM	Yes	Tax type
tax_rate_percent	num_10_3	Yes	Tax percentage

Register Ticket Transaction REGISTER_TICKET

Request Arguments Format

{
  "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"
  }
}

Parameter	Type	Required	Description
client_txn_id	guid	Yes	Transaction identifier assigned by the client
client_parent_txn_id	guid	Yes (при отмене)	Parent transaction identifier. Only for SELL_RETURN or BUY_RETURN
client_txn_date	datetime	Yes	Transaction date at the time of operation
is_offline	bool	Yes	Offline or online mode (whether receipt was printed or not)
operation_type	TICKET_OPERATION_TYPE_ENUM	Yes	Operation type
total	money	Yes	Total amount of ticket transaction
items	object[]	Yes	List of goods/services
total_modifier	object	No	General discount or markup
taxes	TAX[]	No	Tax on receipt (absent if taxes are specified in elements)
payment	PAYMENT_INFO	Да	Payment information
cashier	CASHIER_INFO	No	Cashier operator information
customer	CUSTOMER_INFO	No	Customer information
domain	DOMAIN_INFO	No	Activity domain information

• List of supported items types:

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

• List of supported total_modifier types:

  • DISCOUNT
  • MARKUP

• taxes - tax with a specific percentage should appear no more than once.

Also, if the taxes field is specified in the receipt, then it should be absent in individual items/taxes elements.

• List of supported domain types:
  • TRADING_DOMAIN
  • SERVICES_DOMAIN
  • TAXI_DOMAIN
  • PARKING_DOMAIN
  • HOTELS_DOMAIN
  • GASOIL_DOMAIN

Product/Service Information COMMODITY

Parameter	Type	Required	Description
section_code	string	Yes	Section or department code
name	string	Yes	Name
quantity	num_10_3	Yes	Quantity
price	money	Yes	Price
total	money	Yes	Total amount
taxes	TAX[]	No	List of taxes (absent if present in receipt)
excise_stamp	string	No	Excise stamp number
measure_unit_code	string	No	Unit of measure code for ESF Information System

Product/Service Storno Information STORNO_COMMODITY

Parameter	Type	Required	Description
section_code	string	Yes	Section or department code
name	string	Yes	Name
quantity	num_10_3	Yes	Quantity
price	money	Yes	Price
total	money	Yes	Total amount
taxes	TAX[]	No	List of taxes (absent if present in receipt)
excise_stamp	string	No	Excise stamp number
measure_unit_code	string	No	Unit of measure code for ESF Information System

Discount Information DISCOUNT

Parameter	Type	Required	Description
name	string	Yes	Name
total	money	Yes	Total amount
taxes	TAX[]	No	List of taxes (absent if present in receipt)

Discount Storno Information STORNO_DISCOUNT

Parameter	Type	Required	Description
name	string	Yes	Name
total	money	Yes	Total amount
taxes	TAX[]	No	List of taxes (absent if present in receipt)

Markup Information MARKUP

Parameter	Type	Required	Description
name	string	Yes	Name
total	money	Yes	Total amount
taxes	TAX[]	No	List of taxes (absent if present in receipt)

Markup Storno Information STORNO_MARKUP

Parameter	Type	Required	Description
name	string	Yes	Name
total	money	Yes	Total amount
taxes	TAX[]	No	List of taxes (absent if present in receipt)

Tax Information TAX

Parameter	Type	Required	Description
tax_type	TAX_TYPE_ENUM	Yes	Tax type
taxation_type	TAXATION_TYPE_ENUM	Yes	Taxation type
tax_rate_percent	num_10_3	Yes	Tax value in percentage
total	money	Yes	Tax value in money
is_included_in_total	bool	Yes	Whether tax is included in the amount

Payment Information PAYMENT

Parameter	Type	Required	Description
cash	CASH_PAYMENT	No	Cash payment information
card	CARD_PAYMENT	No	Card payment information
credit	CREDIT_PAYMENT	No	Credit payment information
tare	TARE_PAYMENT	No	Tare payment information

Cash Payment Information CASH_PAYMENT

Parameter	Type	Required	Description
amount	money	Yes	Amount for cash payment
taken	money	Yes	Taken in cash
change	money	Yes	Change

Card Payment Information CARD_PAYMENT

Parameter	Type	Required	Description
amount	money	Yes	Amount for card payment

Credit Payment Information CREDIT_PAYMENT

Parameter	Type	Required	Description
amount	money	Yes	Amount for credit payment

Tare Payment Information TARE_PAYMENT

Parameter	Type	Required	Description
amount	money	Yes	Amount for tare payment

Customer Information CUSTOMER_INFO

Parameter	Type	Required	Description
iinbin	string	No	Customer IIN/BIN
phone	string	No	Customer phone
email	string	No	Customer email

Operation Types (TICKET_OPERATION_TYPE_ENUM)

Значение	Description
BUY	Purchase
BUY_RETURN	Purchase return
SELL	Sale
SELL_RETURN	Sale return

Taxation Types (TAXATION_TYPE_ENUM)

Значение	Description
USN	УСН
OSN	ОСН
PEASANT_AND_FARM	Tax regime for peasant and farm households
SMALL_BUSINESS_PATENT	Tax regime for small enterprises based on patent

Tax Types (TAX_TYPE_ENUM)

Значение	Description
NDS	НДС

Trading Domain TRADING_DOMAIN

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

Services Domain SERVICES_DOMAIN

Parameter	Type	Required	Description
account_number	string	Yes

Gas/Oil Supply Domain GASOIL_DOMAIN

Parameter	Type	Required	Description
card_number	string	No
correction_number	string	No
correction_sum	money	No

Hotels and Restaurants Domain HOTELS_DOMAIN

Contains no fields.

Taxi Domain TAXI_DOMAIN

Parameter	Type	Required	Description
car_number	string	Yes
is_order	bool	Yes
current_fee	money	Yes

Parking Domain PARKING_DOMAIN

Parameter	Type	Required	Description
begin_time	datetime	Yes
end_time	datetime	Yes

Response Arguments Format

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

Parameter	Type	Required	Description
ofd_ticket_number	string	No	Receipt number received from OFD
ofd_ticket_qr_code	hex	No	QR code received from OFD
offline_ticket_number	i32	Yes	Autonomous receipt number
is_offline	bool	Yes	Whether receipt was online or offline
shift_number	i32	Yes	Shift number
shift_document_number	i32	Yes	Document number in shift

If the payment was offline, then is_offline: true, but ofd_ticket_number and ofd_ticket_qr_code will be absent.

Cash Withdrawal WITHDRAW_MONEY

Request Arguments Format

{
  "type": "WITHDRAW_MONEY",
  "client_txn_id": "5d8b06e4-0560-4dcd-8162-8bb23f5ee258",
  "client_txn_date": "2018-05-03T16:27:30",
  "amount": "2345.00"
}

Parameter	Type	Required	Description
client_txn_id	guid	Yes	Client transaction identifier
client_txn_date	timestamp	Yes	Transaction date
amount	money	Yes	Amount of money

Response Arguments Format

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

Parameter	Type	Required	Description
shift_number	i32	Yes	Shift number
shift_document_number	i32	Yes	Document number in shift

Cash Deposit DEPOSIT_MONEY

Request Arguments Format

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

Parameter	Type	Required	Description
client_txn_id	guid	Yes	Client transaction identifier
client_txn_date	timestamp	Yes	Transaction date
amount	money	Yes	Amount of money

Response Arguments Format

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

Parameter	Type	Required	Description
shift_number	i32	Yes	Shift number
shift_document_number	i32	Yes	Document number in shift

Shift Close CLOSE_SHIFT

Request Arguments Format

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

Parameter	Type	Required	Description
shift_number	i32	Yes	Shift number
cashier	CASHIER_INFO	No	Cashier operator information

shift_number - should be the last open shift

The command does not imply a result.

Error Codes

Successful Operation 0

Code	Token	Description
0	OK	Operation completed successfully.

Request Format Errors 1xx

Code	Token	Description
100	FMT_ERR	Invalid request format.

Domain Errors 2xx

Code	Token	Description
200	DMN_ERR	Currently impossible to perform this operation in the current terminal state or with current parameters.
201	DMN_ERR_AUTH_FAILED	Invalid terminal identifier or signature.
202	DMN_ERR_KKM_NOT_FOUND	ККМ not found.
203	DMN_ERR_NOT_ENOUGH_CASH	Insufficient cash to perform the operation.
204	DMN_ERR_KKM_BLOCKED	Terminal is blocked. Any operations are prohibited.
205	DMN_ERR_KKM_BLOCKED_BY_OFD	Terminal is blocked on the OFD side. Fiscal operations are prohibited.
206	DMN_ERR_KKM_BLOCKED_BY_OFD_ERROR	Terminal is blocked because there is an error in data transmission to OFD. Manual intervention is required.
207	DMN_ERR_SHIFT_NOT_FOUND	Shift not found.
208	DMN_ERR_INVALID_TICKET	Receipt is incorrectly formed.

Server Errors 3xx

Code	Token	Description
300	SRV_ERR	Server-side error. In this case, the request should be sent later.