6 бизнес-инструментов от Kassa24 для успешного предпринимателя

Операции

Запросы на создание чековых операций отличаются от прочих запросов. Подробнее о формате запросов прочитайте в описании Общих требований и соглашений.

Автономный режим работы

Автономный режим работы предоставляется только тем клиентам, у которых есть лицензия нац. банка на подобный режим.

При автономной работе для операций продажи, покупки, возврата товара, возврата покупки добавляется поле ReceiptDate, предназначенное для обозначения времени пробития чека. Поле должно присутствовать в теле запроса, если он автономный (в теле запроса присутствует поле AFP). В случае ненулевого поля AFP и отсутствия поля ReceiptDate возвращается ошибка 400: Автономный запрос должен содержать дату создания чека ReceiptDate.

AFP должен быть в формате uint32: неотрицательное целое число от 0 до 4 294 967 295.

Должна сохраняться очередность операций. Дата текущей операции не должна быть ранее предыдущей, в противном случае вернется ошибка 400: Нарушена очередность операций.

Формат поля даты должен быть в формате RFC3339, который может быть прочитан пэкеджом time golang.

Операция продажи

Чековая операция. Принимает Uid в заголовке запроса и возвращает новый в заголовке ответа.

Ожидает в теле запроса предчек со списком позиций и данными о внесенных суммах. Возвращает измененные счетчики балансов, изображение с чеком и номер чека.

1
POST /kkms/:IdKkm/sales

Данные на вход:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "IdDomain": 1,
  "Cash": 100,
  "NonCash": 0,
  "Positions": [
    {
        "Name": "Вода",
        "IdSection": 2,
        "Price": 10,
        "Markup": 0,
        "Discount": 0,
        "Qty": 10,
        "idUnit": 1,
        "Storno": false
    }
  ],
  "Total": 100,
  "GenerateCheck": true
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
IdDomain	int	Идентификатор вида деятельности
Cash	int	Сумма оплаты наличными
NonCash	int	Сумма оплаты безналом
Positions	object	Список позиций товаров или услуг
Name	string	Наименование позиции
IdSection	int	Идентификатор секции
Price	int	Цена позиции
Markup	int	Сумма наценки
Discount	int	Сумма скидки
Qty	float	Количество товара
idUnit	int	Единица измерения товара
Storno	bool	Позиция была сторнирована (отменена)
Total	float	Итоговая сумма
Amount	int
GenerateCheck	bool	Генерация чека
AFP	int	Идентификатор наличия/отсутствия автономного режима работы
ReceiptDate	string	Время пробития чека при автономном режиме работы

Возвращает данные:

1
2
3
4
5
6
7
8
9
10
11
{
  "Status": 200,
  "Message": "OK",
  "Data": {
    "Balances": [ object ],
    "FiscalNumber": 1836733025,
    "AutonomousNumber": 0,
    "IdDocument": 1234567,    
    "Reciept": "123RECEIPT123"
  }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Balances	object	Актуальные данные по балансам кассы (см. /kkms/:IdKk/balances)
FiscalNumber	int	Фискальный признак
AutonomousNumber	int	Автономный номер
IdDocument	int	Номер чека
Receipt	string	Картинка с чеком в base64

Получение списка единиц измерения

1
GET/kkms/:IdKkm/units

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "Status": 200,
  "Message": "OK",
  "Data": [
    {
      "Id": 1,
      "Code": 796,
      "NameRU": "штука",
      "NameKAZ": "дана",
      "ShortName": "шт"
    }
  ]
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
id	int	Идентификатор единицы измерения
Code	int	Идентификатор в справочнике информационной системы электронных счетов-фактур
NameRU	string	Название единицы измерения на русском языке
NameKAZ	string	Название единицы измерения на казахском языке
ShortName	string	Сокращенное название единицы измерения

Ошибки

Status	Message	Способ устранения	Примечание
400	Некорректный запрос. Поле IdSection не должно быть пустым
401	Unauthorized: token is expired by 2h36m46s	Получить новый токен
402	Полученная сумма меньше стоимости
402	402: сумма операции не может быть равна нулю
402	Некорректный запрос. Поле Cash/NonCash должно быть положительным
403	Forbidden: Доступ к указанному ресурсу закрыт.	Проверить IdKkm кассы, выбрать IdKkm кассы
403	Forbidden: касса заблокирована	Связаться с тех. поддержкой	Если касса была заблокирована из-за проблем отправки данных в ОФД
423	Смена просрочена	Закрыть текущую смену и открыть смену заново	Смена длится 24 часа
452	Некорректный Uid	Запросить новый Uid
500	Internal Server Error	Обратиться в тех. поддержку

Блок-схема

Служебный приход

Чековая операция. Принимает Uid в заголовке запроса и возвращает новый в заголовке ответа.

Ожидает в теле запроса сумму наличных средств, которые нужно внести в кассу. Возвращает измененные счетчики балансов, изображение с чеком и номер чека.

Приход можно осуществить в автономном режиме, если у клиента есть лицензия нац. банка на такой режим. При автономном режиме работы в тело запроса добавляется поле Date. Если поле есть, то операция автономная, и если поля нет, то обычная.

1
POST /kkms/:IdKkm/incomes

Данные на вход:

1
2
3
4
{ 
  "Amount": 100
   "Date": "2020-12-20T06:34:46+00:00"
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Amount	int	Сумма наличных
Date	string	Дата при автономном режиме работы

Возвращает данные:

1
2
3
4
5
6
7
8
9
{
  "Status": 200,
  "Message": "OK",
  "Data": {
    "Balances": [ object ],
    "IdDocument": 1234568,    
    "Reciept": "123RECEIPT123"
  }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Balances	object	Актуальные данные по балансам кассы (см. /kkms/:IdKk/balances)
IdDocument	int	Номер чека
Receipt	string	Картинка с чеком в base64

Ошибки

Status	Message	Способ устранения	Примечание
400	Некорректный запрос. Поле Amount не должно быть пустым
401	Unauthorized: token is expired by 2h36m46s	Получить новый токен
402	402: сумма операции не может быть равна нулю
403	Forbidden: Доступ к указанному ресурсу закрыт.	Проверить IdKkm кассы, выбрать IdKkm кассы
403	Forbidden: касса заблокирована	Связаться с тех. поддержкой	Если касса была заблокирована из-за проблем отправки данных в ОФД
423	Смена просрочена	Закрыть текущую смену и открыть смену заново	Смена длится 24 часа
452	Некорректный Uid	Запросить новый Uid
500	Internal Server Error	Обратиться в тех. поддержку

Блок-схема

Служебный расход

Чековая операция. Принимает Uid в заголовке запроса и возвращает новый в заголовке ответа.

Расход или инкассация. Ожидает в теле запроса сумму наличных средств, которые нужно забрать из кассы. Возвращает измененные счетчики балансов, изображение с чеком и номер чека.

Сумма не может быть больше счетчика баланса наличных в кассе.

Расход можно осуществить в автономном режиме, если у клиента есть лицензия нац. банка на такой режим. При автономном режиме работы в тело запроса добавляется поле Date. Если поле есть, то операция автономная, и если поля нет, то обычная.

1
POST /kkms/:IdKkm/expenses

Данные на вход:

1
2
3
4
{ 
  "Amount": 100
   "Date": "2020-12-20T06:34:46+00:00"
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Amount	int	Сумма наличных
Date	string	Дата при автономном режиме работы

Возвращает данные:

1
2
3
4
5
6
7
8
9
{
  "Status": 200,
  "Message": "OK",
  "Data": {
    "Balances": [ object ],
    "IdDocument": 1234569,    
    "Reciept": "123RECEIPT123"
  }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Balances	object	Актуальные данные по балансам кассы (см. /kkms/:IdKk/balances)
IdDocument	int	Номер чека
Receipt	string	Картинка с чеком в base64

Ошибки

Status	Message	Способ устранения	Примечание
400	Некорректный запрос. Поле Amount не должно быть отрицательным
401	Unauthorized: token is expired by 2h36m46s	Получить новый токен
402	402: сумма операции не может быть равна нулю
402	Сумма операции превышает баланс кассы
403	Forbidden: Доступ к указанному ресурсу закрыт.	Проверить IdKkm кассы, выбрать IdKkm кассы
403	Forbidden: касса заблокирована	Связаться с тех. поддержкой	Если касса была заблокирована из-за проблем отправки данных в ОФД
423	Смена просрочена	Закрыть текущую смену и открыть смену заново	Смена длится 24 часа
452	Некорректный Uid	Запросить новый Uid
500	Internal Server Error	Обратиться в тех. поддержку

Блок-схема

Операция покупки

Чековая операция. Принимает Uid в заголовке запроса и возвращает новый в заголовке ответа.

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

1
POST /kkms/:IdKkm/purchases

Данные на вход:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "IdDomain": 1,
  "Cash": 100,
  "Positions": [
    {
        "Name": "Хлебушек",
        "IdSection": 1,
        "Price": 200,
        "Qty": 1,
        "idUnit":1,
        "Storno": false
    }
               ],
  "Total": 100,
  "Amount": 0,
  "GenerateCheck": true
  "AFP": 1,
  "ReceiptDate": "2006-01-02T15:04:05+06:00"
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
IdDomain	int	Идентификатор вида деятельности
Cash	int	Сумма оплаты наличными
Positions	object	Список позиций товаров или услуг
Name	string	Наименование позиции
IdSection	int	Идентификатор отдела (секции)
Price	int	Цена позиции
Qty	float	Количество товара
Storno	bool	Позиция была сторнирована (отменена)
Total	float	Итоговая сумма
idUnit	int	Единица измерения товара
Amount	int	Сумма
GenerateCheck	bool	Генерация чека
AFP	int	Идентификатор наличия/отсутствия автономного режима работы
ReceiptDate	string	Время пробития чека при автономном режиме работы

Возвращает данные:

1
2
3
4
5
6
7
8
9
10
11
{
  "Status": 200,
  "Message": "OK",
  "Data": {
    "Balances": [ object ],
    "FiscalNumber": 1836733025,
    "AutonomousNumber": 0,
    "IdDocument": 1234570,    
    "Reciept": "123RECEIPT123"
  }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Balances	object	Актуальные данные по балансам кассы (см. /kkms/:IdKk/balances)
FiscalNumber	int	Фискальный признак
AutonomousNumber	int	Автономный номер
IdDocument	int	Номер чека
Receipt	string	Картинка с чеком в base64
Price	int	Цена позиции
Qty	float	Количество товара
Storno	bool	Позиция была сторнирована (отменена)

Получение списка единиц измерения

1
GET/kkms/:IdKkm/units

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "Status": 200,
  "Message": "OK",
  "Data": [
    {
      "Id": 1,
      "Code": 796,
      "NameRU": "штука",
      "NameKAZ": "дана",
      "ShortName": "шт"
    }
  ]
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
id	int	Идентификатор единицы измерения
Code	int	Идентификатор в справочнике информационной системы электронных счетов-фактур
NameRU	string	Название единицы измерения на русском языке
NameKAZ	string	Название единицы измерения на казахском языке
ShortName	string	Сокращенное название единицы измерения
Price	int	Цена позиции

Ошибки

Status	Message	Способ устранения	Примечание
400	Некорректный запрос. Поле IdSection не должно быть пустым
400	Некорректный запрос. Поле Cash/NonCash должно быть положительным
401	Unauthorized: token is expired by 2h36m46s	Получить новый токен
402	402: сумма операции не может быть равна нулю
402	Полученная сумма меньше стоимости
403	Forbidden: Доступ к указанному ресурсу закрыт.	Проверить IdKkm кассы, выбрать IdKkm кассы
403	Forbidden: касса заблокирована	Связаться с тех. поддержкой	Если касса была заблокирована из-за проблем отправки данных в ОФД
423	Смена просрочена	Закрыть текущую смену и открыть смену заново	Смена длится 24 часа
452	Некорректный Uid	Запросить новый Uid
500	Internal Server Error	Обратиться в тех. поддержку

Блок-схема

Операция возврата товара

Чековая операция. Принимает Uid в заголовке запроса и возвращает новый в заголовке ответа.

Ожидает в теле запроса предчек со списком позиций, на которые нужно оформить возврат. Возвращает измененные счетчики балансов, изображение с чеком и номер чека.

1
POST /kkms/:IdKkm/refunds

Данные на вход:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "IdDomain": 1,
  "Cash": 100,
  "Positions": [
    {
        "Name": "Хлебушек",
        "IdSection": 1,
        "Price": 200,
        "Qty": 1,
        "idUnit":1,
        "Storno": false
    }
  ],
  "Total": 100,
  "Amount": 0,
  "GenerateCheck": true
    }
   "AFP": 1,
   "ReceiptDate": "2006-01-02T15:04:05+06:00"

Описание переменных

Название переменной	Тип переменной	Описание переменной
IdDomain	int	Идентификатор вида деятельности
Cash	int	Сумма оплаты наличными
Positions	object	Список позиций товаров или услуг
Name	string	Наименование позиции
IdSection	int	Идентификатор отдела (секции)
Price	int	Цена позиции
Qty	float	Количество товара
Storno	bool	Позиция была сторнирована (отменена)
Total	float	Итоговая сумма
idUnit	int	Единица измерения товара
Amount	int	Сумма
GenerateCheck	bool	Генерация чека
AFP	int	Идентификатор наличия/отсутствия автономного режима работы
ReceiptDate	string	Время пробития чека при автономном режиме работы

Возвращает данные:

1
2
3
4
5
6
7
8
9
10
11
{
  "Status": 200,
  "Message": "OK",
  "Data": {
    "Balances": [ object ],
    "FiscalNumber": 1836733025,
    "AutonomousNumber": 0,
    "IdDocument": 1234571,    
    "Reciept": "123RECEIPT123"
  }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Balances	object	Актуальные данные по балансам кассы (см. /kkms/:IdKk/balances)
FiscalNumber	int	Фискальный признак
AutonomousNumber	int	Автономный номер
IdDocument	int	Номер чека
Receipt	string	Картинка с чеком в base64
Price	int	Цена позиции
Qty	float	Количество товара

Получение списка единиц измерения

1
GET/kkms/:IdKkm/units

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "Status": 200,
  "Message": "OK",
  "Data": [
    {
      "Id": 1,
      "Code": 796,
      "NameRU": "штука",
      "NameKAZ": "дана",
      "ShortName": "шт"
    }
  ]
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
id	int	Идентификатор единицы измерения
Code	int	Идентификатор в справочнике информационной системы электронных счетов-фактур
NameRU	string	Название единицы измерения на русском языке
NameKAZ	string	Название единицы измерения на казахском языке
ShortName	string	Сокращенное название единицы измерения

Ошибки

Status	Message	Способ устранения	Примечание
400	Некорректный запрос. Поле IdSection не должно быть пустым
400	Некорректный запрос. Поле Cash/NonCash должно быть положительным
401	Unauthorized: token is expired by 2h36m46s	Получить новый токен
402	402: сумма операции не может быть равна нулю
402	Полученная сумма меньше стоимости
403	Forbidden: Доступ к указанному ресурсу закрыт.	Проверить IdKkm кассы, выбрать IdKkm кассы
403	Forbidden: касса заблокирована	Связаться с тех. поддержкой	Если касса была заблокирована из-за проблем отправки данных в ОФД
423	Смена просрочена	Закрыть текущую смену и открыть смену заново	Смена длится 24 часа
452	Некорректный Uid	Запросить новый Uid
500	Internal Server Error	Обратиться в тех. поддержку

Блок-схема

Операция возврата покупки

Чеĸовая операция. Принимает Uid в заголовĸе запроса и возвращает новый в заголовĸе ответа. Ожидает в теле запроса предчеĸ со списĸом позиций, на ĸоторые нужно оформить возврат. Возвращает измененные счетчиĸи балансов, изображение с чеĸом и номер чеĸа.

1
POST /kkms/:IdKkm/purchase_refunds

Данные на вход:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
 "IdDomain": 1,
"Cash": 1000,
"NonCash": 0,
"Positions": [
 {
 "Name": "Универсальный товар",
"IdSection": 56954,
 "Price": 1000,
"Markup": 0,
"Discount": 0,
"Qty": 1,”
"idUnit":1,
“Storno": false
 }
 ],
 "Total": 1000,
 "Amount": 0,
 "GenerateCheck": true
 "AFP": 1,
 "ReceiptDate": "2006-01-02T15:04:05+06:00"
 }

Возвращает данные:

1
2
3
4
5
6
7
8
9
10
11
{
 "Status": 200,
 "Message": "OK",
 "Data": {
 "Balances": [ object ],
 "FiscalNumber": 1102294106,
 "AutonomousNumber": 0,
 "IdDocument": 1234567,
 "Reciept": "123RECEIPT123"
 }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
IdDomain	int	Идентификатор вида деятельности
Cash	int	Сумма оплаты наличными
NonCash	int	Внесенная сумма безналичными
Positions	object	Список позиций товаров или услуг
Name	string	Наименование позиции
IdSection	int	Идентификатор отдела (секции)
Price	int	Цена позиции
Markup	int	Наценка на товар или услугу
Discount	int	Скидка на товар или услугу
Qty	float	Количество товара
Storno	bool	Позиция была сторнирована (отменена)
Total	float	Итоговая сумма
idUnit	int	Единица измерения товара
Amount	int	Сумма
GenerateCheck	bool	Генерация чека
AFP	int	Идентификатор наличия/отсутствия автономного режима работы
ReceiptDate	string	Время пробития чека при автономном режиме работы

Получение списка единиц измерения

1
GET/kkms/:IdKkm/units

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "Status": 200,
  "Message": "OK",
  "Data": [
    {
      "Id": 1,
      "Code": 796,
      "NameRU": "штука",
      "NameKAZ": "дана",
      "ShortName": "шт"
    }
  ]
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
id	int	Идентификатор единицы измерения
Code	int	Идентификатор в справочнике информационной системы электронных счетов-фактур
NameRU	string	Название единицы измерения на русском языке
NameKAZ	string	Название единицы измерения на казахском языке
ShortName	string	Сокращенное название единицы измерения
IdSection	int	Идентификатор отдела (секции)
Price	int	Цена позиции

Получить данные об операции

1
GET /operations/:IdDocument

Возвращает данные:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "Status": 200,
  "Message": "OK",
  "Data": {
    "Document": {
      "AutonomousNumber": 0,
      "Cash": 5000,
      "Change": 0,
      "Checksum": "123CHECKSUM123",
      "Coins": 0,
      "DateDocument": "2020-06-05T06:55:34.2447169Z",
      "Domain": {
        "Id": 1,
        "Name": "DOMAIN_TRADING"
      },
      "FiscalNumber": 0,
      "Id": 170460,
      "IdCompany": 20,
      "IdDomain": 1,
      "IdKkm": 34,
      "IdShift": 7327,
      "IdUser": 1032,
      "KKM": { object },
      "NonCash": 0,
      "NumberDoc": "2034159134013424",
      "TypeDocument": {
        "Id": 3,
        "Name": "Служебный расход"
      },
      "User": {
        "Id": 1032,
        "IdShift": 13327,
        "Lock": false,
        "Name": "first cashier",
        "PhoneLogin": "77078385387"
      },
      "Value": 5000
    },
    "Reciept": "123RECEIPT123"
  }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Document	object	объект с информацией о документе
AutonomousNumber	int	Автономный фискальный признак
Cash	int	Сумма наличными
Change	int	Сумма сдачи
Checksum	string	Хэш с контрольной суммой
Coins	int	Копейки
DateDocument	string	Дата документа
Domain	object	Вид деятельности
Id	int	Идентификатор вида деятельности
Name	string	Название идентификатора вида деятельности
FiscalNumber	int	Фискальный признак
Id	int	Идентификатор документа
IdCompany	int	Идентификатор компании
IdDomain	int	Идентификатор вида деятельности
IdKkm	int	Идентификатор ККМ
IdShift	int	Идентификатор смены
IdUser	int	Идентификатор пользователя (кассира)
KKM	object	Данные о ККМ, включая вложенный документ о юр. лице (см. GET /kkms/:IdKkm)
NonCash	int	Сумма безналичными
NumberDoc	string	Номер документа (чека)
TypeDocument	object	Тип документа
Id	int	Идентификатор типа документа
Name	string	Название идентификатора типа документа
User	object	Документ с данными о пользователе
Id	int	Идентификатор пользователя
IdShift	int	Идентификатор смены открытой или последней открытой смены
Lock	bool	Признак блокировки сменой
Name	string	Имя пользователя
PhoneLogin	string	Номер пользователя
Value	int	Сумма документа
Receipt	string	Картинка с чеком в base64

Ошибки

Status	Message	Способ устранения	Примечание
400	Bad request		Если идентификатор операции некорректный
401	Unauthorized: token is expired by 2h36m46s	Получить новый токен
403	Вы не имеете доступ к указанному объекту		Если документ был создан в другой компании, в которой пользователь не зарегистрирован
500	Internal Server Error	Обратиться в тех. поддержку
402	Полученная сумма меньше стоимости
403	Forbidden: Доступ к указанному ресурсу закрыт.	Проверить IdKkm кассы, выбрать IdKkm кассы
403	Forbidden: касса заблокирована	Связаться с тех. поддержкой	Если касса была заблокирована из-за проблем отправки данных в ОФД

Блок-схема

Получить дубликат чека

1
GET /www/document/:IdDocument

Возвращает данные:

1
2
3
4
5
6
7
{
  "Status": 200,
  "Message": "OK",
  "Data": {
    "Reciept": "123RECEIPT123"
  }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Receiptstring	string	Картинка с чеком в base64

Ошибки

Status	Message	Способ устранения	Примечание
401	Unauthorized: token is expired by 2h36m46s	Получить новый токен
500	Internal Server Error	Обратиться в тех. поддержку

Блок-схема

Получить данные по QR чека

1
GET /receipt?datetime=2020-07-14T09:06&znm=54321&fn=85619944&total=50.00

Описание querystring параметров

Название переменной	Тип переменной	Описание переменной
datetime	ISO 8601 date(YYYY-MM-DDThh:mm:ss)	Обязательный. querystring-параметр дата и время покупки
znm	int	Обязательный. querystring-параметр заводской номер машины (ЗНМ) кассы
fn	int	Обязательный. querystring-параметр фискальный признак
total	int	Обязательный. querystring-параметр итого

Возвращает данные:

1
2
3
4
5
6
7
{
  "Status": 200,
  "Message": "OK",
  "Data": {
    "Reciept": "123RECEIPT123"
  }
}

Описание переменных

Название переменной	Тип переменной	Описание переменной
Receipt	string	Картинка с чеком в base64