Операции
Запросы на создание чековых операций отличаются от прочих запросов. Подробнее о формате запросов прочитайте в описании Общих требований и соглашений.
Автономный режим работы
Автономный режим работы предоставляется только тем клиентам, у которых есть лицензия нац. банка на подобный режим.
При автономной работе для операций продажи, покупки, возврата товара, возврата покупки добавляется поле ReceiptDate, предназначенное для обозначения времени пробития чека. Поле должно присутствовать в теле запроса, если он автономный (в теле запроса присутствует поле AFP). В случае ненулевого поля AFP и отсутствия поля ReceiptDate возвращается ошибка 400: Автономный запрос должен содержать дату создания чека ReceiptDate.
AFP должен быть в формате uint32: неотрицательное целое число от 0 до 4 294 967 295.
Должна сохраняться очередность операций. Дата текущей операции не должна быть ранее предыдущей, в противном случае вернется ошибка 400: Нарушена очередность операций.
Формат поля даты должен быть в формате RFC3339, который может быть прочитан пэкеджом time golang.
Операция продажи
Чековая операция. Принимает Uid в заголовке запроса и возвращает новый в заголовке ответа.
Ожидает в теле запроса предчек со списком позиций и данными о внесенных суммах. Возвращает измененные счетчики балансов, изображение с чеком и номер чека.
POST /kkms/:IdKkm/salesДанные на вход:
{
"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 | Время пробития чека при автономном режиме работы |
Возвращает данные:
{
"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 |
Получение списка единиц измерения
GET/kkms/:IdKkm/units{
"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/NonCach должно быть положительным | ||
| 403 | Forbidden: Доступ к указанному ресурсу закрыт. | Проверить IdKkm кассы, выбрать IdKkm кассы | |
| 403 | Forbidden: касса заблокирована | Связаться с тех. поддержкой | Если касса была заблокирована из-за проблем отправки данных в ОФД |
| 423 | Смена просрочена | Закрыть текущую смену и открыть смену заново | Смена длится 24 часа |
| 452 | Некорректный Uid | Запросить новый Uid | |
| 500 | Internal Server Error | Обратиться в тех. поддержку |
Блок-схема
Служебный приход
Чековая операция. Принимает Uid в заголовке запроса и возвращает новый в заголовке ответа.
Ожидает в теле запроса сумму наличных средств, которые нужно внести в кассу. Возвращает измененные счетчики балансов, изображение с чеком и номер чека.
Приход можно осуществить в автономном режиме, если у клиента есть лицензия нац. банка на такой режим. При автономном режиме работы в тело запроса добавляется поле Date. Если поле есть, то операция автономная, и если поля нет, то обычная.
POST /kkms/:IdKkm/incomesДанные на вход:
{
"Amount": 100
"Date": "2020-12-20T06:34:46+00:00"
}Описание переменных
| Название переменной | Тип переменной | Описание переменной |
| Amount | int | Сумма наличных |
| Date | string | Дата при автономном режиме работы |
Возвращает данные:
{
"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. Если поле есть, то операция автономная, и если поля нет, то обычная.
POST /kkms/:IdKkm/expensesДанные на вход:
{
"Amount": 100
"Date": "2020-12-20T06:34:46+00:00"
}Описание переменных
| Название переменной | Тип переменной | Описание переменной |
| Amount | int | Сумма наличных |
| Date | string | Дата при автономном режиме работы |
Возвращает данные:
{
"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 в заголовке запроса и возвращает новый в заголовке ответа.
Ожидает в теле запроса предчек со списком покупаемых товаров или услуг, которые нужно оплатить из кассы. Возвращает измененные счетчики балансов, изображение с чеком и номер чека.
POST /kkms/:IdKkm/purchasesДанные на вход:
{
"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 | Время пробития чека при автономном режиме работы |
Возвращает данные:
{
"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 | позиция была сторнирована (отменена) |
Получение списка единиц измерения
GET/kkms/:IdKkm/units{
"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 в заголовке запроса и возвращает новый в заголовке ответа.
Ожидает в теле запроса предчек со списком позиций, на которые нужно оформить возврат. Возвращает измененные счетчики балансов, изображение с чеком и номер чека.
POST /kkms/:IdKkm/refundsДанные на вход:
{
"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 | Время пробития чека при автономном режиме работы |
Возвращает данные:
{
"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 | Количество товара |
Получение списка единиц измерения
GET/kkms/:IdKkm/units{
"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 в заголовĸе запроса и возвращает новый в заголовĸе ответа. Ожидает в теле запроса предчеĸ со списĸом позиций, на ĸоторые нужно оформить возврат. Возвращает измененные счетчиĸи балансов, изображение с чеĸом и номер чеĸа.
POST /kkms/:IdKkm/purchase_refundsДанные на вход:
{
"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"
}Возвращает данные:
{
"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 | Время пробития чека при автономном режиме работы |
Получение списка единиц измерения
GET/kkms/:IdKkm/units{
"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 | Цена позиции |
Получить данные об операции
GET /operations/:IdDocumentВозвращает данные:
{
"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: касса заблокирована | Связаться с тех. поддержкой | Если касса была заблокирована из-за проблем отправки данных в ОФД |
Блок-схема
Получить дубликат чека
GET /www/document/:IdDocumentВозвращает данные:
{
"Status": 200,
"Message": "OK",
"Data": {
"Reciept": "123RECEIPT123"
}
}Описание переменных
| Название переменной | Тип переменной | Описание переменной |
| Receiptstring | string | Картинка с чеком в base64 |
Ошибки
| Status | Message | Способ устранения | Примечание |
| 401 | Unauthorized: token is expired by 2h36m46s | Получить новый токен | |
| 500 | Internal Server Error | Обратиться в тех. поддержку |
Блок-схема
Получить данные по QR чека
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-параметр итого |
Возвращает данные:
{
"Status": 200,
"Message": "OK",
"Data": {
"Reciept": "123RECEIPT123"
}
}Описание переменных
| Название переменной | Тип переменной | Описание переменной |
|---|---|---|
| Receipt | string | Картинка с чеком в base64 |
Ошибки
| Status | Message | Способ устранения | Примечание |
|---|---|---|---|
| 401 | Unauthorized: token is expired by 2h36m46s | Получить новый токен | |
| 500 | Internal Server Error | Обратиться в тех. поддержку |
Блок-схема
