Методы - abr-tech/smorodina_kkt_api GitHub Wiki
🧩Test
Метод для проверки API запросов.
🖌Параметры запроса
В этот метод можно передать любые параметры, все переданные данные попадут в объект result.requestData в JSON ответ
📥Пример запроса
POST -> /kktgate/api/Test
{
"hi": "Привет касса"
}
📤Пример ответа
{
"ok": true,
"code": 0,
"message": "OK",
"time": "0.104 ms",
"version": 2,
"result": {
"request": {
"hi": "Привет касса"
}
}
}
🧩Receipt
Метод для формирование фискального чека (добавляет чек в очередь на обработку). После вызова метода через несколько секунд организация получит нотификацию с данными чека
!! ОБРАЩАЕМ ВНИМАНИЕ !! Начиная с версии
v2
сервис не будет возвращать ошибку если данные в чеке заполнены не корректно! Ошибки формирования чека теперь доступны в сервисе ReceiptInfo. Если чек содержит ошибки и не был фискализирован, создать чек с таким-же идентификатором уже не получится!
🖌Параметры запроса
Параметр | Тип | Описание | Тег |
---|---|---|---|
appId | string | ID приложения (из договора) | - |
appSecret | string | Пароль приложения (из договора) | - |
id | string | Уникальный идентификатор чека в системе | - |
inn | string | ИНН Организации | - |
customerContact | string | Почта покупателя | 1008 |
taxationSystem | int• | Система налогообложения (см. Системы налогообложения) | 1055 |
type | int• | Признак расчета (см. Признаки расчета) | 1054 |
positions | [🔗positions] | Список товаров/услуг | 1059 |
payments | [🔗payments] | Список платежей | - |
agentv2 |
{🔗agent}?• | Данные по агенту | - |
attributesv2 |
{any}? | Структура с дополнительными атрибутами (не отправляется в ОФД) | - |
🔗Position
Параметр | Тип | Описание | Тег |
---|---|---|---|
text | string | Наименование товара (128 символов ограничение) | 1030 |
quantity | float | Колличество | 1023 |
price | float | Стоимость товара/услуги | 1079 |
tax | int• | Ставки НДС | 1199 |
paymentMethodType | int• | Признак способа расчета | - |
paymentSubjectType | int• | Признак предмета расчета | 1212 |
nomenclatureCode | base64? | Номекулатура (до 32 байт) | 1162 |
supplierNamev2 |
string? | Наименование поставщика | 1225 |
supplierINNv2 |
string? | ИНН поставщика | 1226 |
supplierPhoneNumbersv2 |
[string]? | Телефон поставщика | 1171 |
Внимание тег 1225 (supplierName) имеет ограничение 239 символов в которые входят телефоны поставщика тег 1171 (supplierPhoneNumbers) Например, если передано { supplierPhoneNumbers: ["+74955555555"] } то длина supplierName будет ровна 239 - (supplierPhoneNumbers[0].length + 4) = 223
🔗Payment
Параметр | Тип | Описание |
---|---|---|
type | int• | Тип оплаты: |
amount | float | Сумма платежа в рублях |
v2
🔗Agent Параметр | Тип | Описание | Тег |
---|---|---|---|
agentType | int(1-127) | Признак агента (Битовое значение) | 1057 |
paymentAgentOperation | string? | Телефон платежного агента | 1044 |
paymentAgentPhoneNumbers | [string]? | Телефон платежного агента | 1073 |
paymentOperatorName | string? | Наименование оператора перевода | 1026 |
paymentOperatorAddress | string? | Адрес оператора перевода | 1005 |
paymentOperatorINN | string? | ИНН оператора перевода (10-12 знаков) | 1016 |
paymentOperatorPhoneNumbers | [string]? | Телефон оператора по приему платежей | 1074 |
paymentTransferOperatorPhoneNumbers | [string]? | Телефон оператора перевода | 1075 |
Кассовый чек (БСО) может содержать реквизиты «признак агента» (тег 1057), только если отчет о регистрации и (или) текущий отчет о перерегистрации содержит реквизит «признак агента» (тег 1057), имеющий значение, идентичное значению реквизита «признак агента» (тег 1057) кассового чека.
📥Пример запроса
POST -> /kktgate/api/Receipt
{
"appId":"28c2126d-0a6e-4b4c-b937-0c08d3e41f51",
"appSecret":"00ga0lgf4cft",
"inn":"7725713770",
"id":"12345",
"customerContact":"[email protected]",
"taxationSystem": 0,
"type": 1,
"positions": [
{
"text": "Билет в кино",
"quantity": 1,
"price": 700.00,
"tax": 1,
"paymentMethodType": 4,
"paymentSubjectType": 4,
"nomenclatureCode": "MTIzNDU2Nzg5MA=="
}
],
"payments": [
{
"type": 2,
"amount": 700.00
}
],
"attributes": {
"test1": "12345",
},
}
📤Пример ответа
{
"ok": true,
"code": 0,
"message": "Added in queue",
"time": "0.142 ms",
"version": 2,
"result": {
"id": "12345"
}
}
v2
🧩ReceiptBatch 🚀 Оптимально подходит для фискализации больших объемов
Метод для формирование пачки фискальных чеков.
метод может принять не более 1000 чеков в 1 запросе
🖌Параметры запроса
Аналогично методу Receipt за исключением параметров чека, их необходимо передать в параметр batch массивом см. пример
📥Пример запроса
POST -> /kktgate/api/v2/ReceiptBatch
{
"appId": "28c2126d-0a6e-4b4c-b937-0c08d3e41f51",
"appSecret": "00ga0lgf4cft",
"inn": "7725713770",
"batch": [
{
"id": "12345",
"test": "qwerty"
},
{
"id": "123456",
"customerContact": "[email protected]",
"taxationSystem": 0,
"type": 1,
"positions": [
{
"text": "Билет в кино",
"quantity": 1,
"price": 700.00,
"tax": 1,
"paymentMethodType": 4,
"paymentSubjectType": 4,
"nomenclatureCode": "MTIzNDU2Nzg5MA=="
}
],
"payments": [
{
"type": 2,
"amount": 700.00
}
]
}
]
}
📤Пример ответа
{
"ok": true,
"code": 0,
"message": "OK",
"time": "753.101 ms",
"version": 2,
"result": [{
"id": "12345",
"code": 1,
"message": "Параметр customerContact должен быть заполнен"
}{
"id": "123456",
"code": 0,
"message": "OK"
}]
}
🧩ReceiptSync
🚦Внимание! данный метод предназначен только для точечной печати, для получения высокой производительности печати больших объемов используйте методы ReceiptBatch или Receipt🚦
Время ответа зависит от количества ККТ, если у вас 1 ККТ необходимо отправлять запросы ReceiptSync синхронно! То есть после получения ответа от пред идущего запроса.
Метод для формирование фискального чека в синхронном режиме. Метод возвращает данные чека после ответа от ОФД
После вызова метода нотификация не будет отправлена!
🖌Параметры запроса
Аналогично методу Receipt
📥Пример запроса
POST -> /kktgate/api/ReceiptSync
{
"appId": "28c2126d-0a6e-4b4c-b937-0c08d3e41f51",
"appSecret": "00ga0lgf4cft",
"inn": "7725713770",
"id": "12345",
"customerContact": "[email protected]",
"taxationSystem": 0,
"type": 1,
"positions": [
{
"text": "Билет в кино",
"quantity": 1,
"price": 700.00,
"tax": 1,
"paymentMethodType": 4,
"paymentSubjectType": 4,
"nomenclatureCode": "MTIzNDU2Nzg5MA=="
}
],
"payments": [
{
"type": 2,
"amount": 700.00
}
]
}
📤Пример ответа
{
"ok": true,
"code": 0,
"message": "OK",
"time": "642.410 ms",
"version": 2,
"result": {
"id": "0133ce16b64ee4ae8e766d7b5b9d3f360d3d",
"deviceSN": "1400000000000052",
"deviceRN": "0000000400054952",
"fsNumber": "9999078900001341",
"ofdName": "ООО \"Ярус\" (\"ОФД-Я\")",
"ofdWebsite": "www.ofd-ya.ru",
"ofdinn": "7728699517",
"fnsWebsite": "www.nalog.ru",
"companyINN": "7725713770",
"companyName": "ООО \"Кинопортал\"",
"documentNumber": 4110,
"shiftNumber": 2961,
"documentIndex": 2667,
"processedAt": "2018-08-17T10:19:00",
"content": {
"type": 1,
"positions": [
{
"quantity": 1,
"price": 700.00,
"tax": 1,
"text": "Билет в кино",
"paymentMethodType": 4,
"paymentSubjectType": 4
}
],
"checkClose": {
"payments": [
{
"type": 2,
"amount": 700.00
}
],
"taxationSystem": 0
},
"customerContact": "[email protected]"
},
"change": 0,
"fp": "364831178"
},
}
}
🧩Correction
Метод для формирование фискального чека коррекции (добавляет чек в очередь на обработку). После вызова метода через несколько секунд организация получит нотификацию с данными чека
!! ОБРАЩАЕМ ВНИМАНИЕ !! Начиная с версии
v2
сервис не будет возвращать ошибку если данные в чеке заполнены не корректно! Ошибки формирования чека теперь доступны в сервисе ReceiptInfo. Если чек содержит ошибки и не был фискализирован, создать чек с таким-же идентификатором уже не получится!
🖌Параметры запроса
Параметр | Тип | Описание |
---|---|---|
appId | string | ID приложения (из договора) |
appSecret | string | Пароль приложения (из договора) |
id | string | Уникальный идентификатор чека в системе |
inn | string | ИНН Организации |
content | {🔗content} | Параметры чека коррекции |
attributesv2 |
{any}? | Структура с дополнительными атрибутами (не отправляется в ОФД) |
🔗Content
Параметр | Тип | Описание |
---|---|---|
type | number | Признак расчета (только приход либо расхд) |
correctionType | number | Тип коррекции |
description | string | Описание коррекции |
causeDocumentDate | string | Дата совершения корректируемого расчета |
causeDocumentNumber | string | Номер корректируемого документа |
taxationSystem | number | Системы налогооблажения |
totalSum | number | Сумма расчета, указанного в чеке (БСО) |
cashSum | number? | Сумма по чеку наличными |
eCashSum | number? | Сумма по чеку электронными |
prepaymentSum | number? | Сумма по чеку предоплатой (зачет аванса и (или) предыдущих платежей) |
postpaymentSum | number? | Сумма по чеку постоплатой (кредит) |
otherPaymentTypeSum | number? | Сумма по чеку встречным предоставлением |
tax1Sum | number? | Сумма НДС чека по ставке 20% |
tax2Sum | number? | Сумма НДС чека по ставке 10% |
tax3Sum | number? | Сумма расчета по чеку с НДС по ставке 0% |
tax4Sum | number? | Сумма расчета по чеку без НДС |
tax5Sum | number? | Сумма НДС чека по расч. ставке 20/120 |
tax6Sum | number? | Сумма НДС чека по расч. ставке 10/110 |
settlementAddress | string? | Адрес расчетов |
settlementPlace | string? | Место расчетов |
📥Пример запроса
POST -> /kktgate/api/Correction
{
"appId": "ca53738c-c443-466e-9ff3-329ffb46bc65",
"appSecret": "0ktnzfeerwi",
"id": "12345",
"inn": "7725713770",
"content": {
"correctionType": 1,
"type": 1,
"description": "Не хочу но надо",
"causeDocumentDate": "2017-08-10T00:00:00",
"causeDocumentNumber": "ФЗ-54",
"totalSum": 17.25,
"cashSum": 1.23,
"eCashSum": 2.34,
"prepaymentSum": 5.67,
"postpaymentSum": 4.56,
"otherPaymentTypeSum": 3.45,
"tax1Sum": 1.34,
"tax2Sum": 2.34,
"tax3Sum": 3.34,
"tax4Sum": 4.34,
"tax5Sum": 5.34,
"tax6Sum": 6.34,
"taxationSystem": 1
}
}
📤Пример ответа
{
"ok": true,
"code": 0,
"message": "Added in queue",
"time": "0.204 ms",
"version": 2,
"result": {
"session": "d87dd67e-a04c-4149-9c14-b67b658d4ffa",
"receipt_id": "cjkxnyco601lc0800uzmzt57n"
}
}
v2
🧩CorrectionBatch 🚀 Оптимально подходит для фискализации больших объемов
Метод для формирование пачки фискальных чеков коррекции.
метод может принять не более 1000 чеков в 1 запросе
🖌Параметры запроса
Аналогично методу Correction за исключением параметров чека, их необходимо передать в параметр batch массивом см. пример
📥Пример запроса
POST -> /kktgate/api/v2/CorrectionBatch
{
"appId": "28c2126d-0a6e-4b4c-b937-0c08d3e41f51",
"appSecret": "00ga0lgf4cft",
"inn": "7725713770",
"batch": [
{
"id": "12345",
"test": "qwerty"
},
{
"id": "123456",
"content": {
"correctionType": 1,
"type": 1,
"description": "Не хочу но надо",
"causeDocumentDate": "2017-08-10T00:00:00",
"causeDocumentNumber": "ФЗ-54",
"totalSum": 17.25,
"cashSum": 1.23,
"eCashSum": 2.34,
"prepaymentSum": 5.67,
"postpaymentSum": 4.56,
"otherPaymentTypeSum": 3.45,
"tax1Sum": 1.34,
"tax2Sum": 2.34,
"tax3Sum": 3.34,
"tax4Sum": 4.34,
"tax5Sum": 5.34,
"tax6Sum": 6.34,
"taxationSystem": 1
}
}
]
}
📤Пример ответа
{
"ok": true,
"code": 0,
"message": "OK",
"time": "864,112 ms",
"version": 2,
"result": [{
"id": "12345",
"code": 1,
"message": "Параметр content должен быть заполнен"
}{
"id": "123456",
"code": 0,
"message": "OK"
}]
}
🧩CorrectionSync
🚦Внимание! данный метод предназначен только для точечной печати, для получения высокой производительности печати больших объемов используйте методы CorrectionBatch или Correction🚦
Время ответа зависит от количества ККТ, если у вас 1 ККТ необходимо отправлять запросы ReceiptSync синхронно! То есть после получения ответа от пред идущего запроса.
Метод для формирование фискального чека коррекции в синхронном режиме. Метод возвращает данные чека после ответа от ОФД
🖌Параметры запроса
Аналогично методу Correction
📥Пример запроса
POST -> /kktgate/api/CorrectionSync
{
"appId": "ca53738c-c443-466e-9ff3-329ffb46bc65",
"appSecret": "0ktnzfeerwi",
"id": "12345",
"inn": "7725713770",
"content": {
"correctionType": 1,
"type": 1,
"description": "Не хочу но надо",
"causeDocumentDate": "2017-08-10T00:00:00",
"causeDocumentNumber": "ФЗ-54",
"totalSum": 17.25,
"cashSum": 1.23,
"eCashSum": 2.34,
"prepaymentSum": 5.67,
"postpaymentSum": 4.56,
"otherPaymentTypeSum": 3.45,
"tax1Sum": 1.34,
"tax2Sum": 2.34,
"tax3Sum": 3.34,
"tax4Sum": 4.34,
"tax5Sum": 5.34,
"tax6Sum": 6.34,
"taxationSystem": 1
}
}
📤Пример ответа
{
"ok": true,
"code": 0,
"message": "OK",
"time": "420.103 ms",
"version": 2,
"result": {
"id": "12345",
"deviceSN": "1400000000000052",
"deviceRN": "0000000400054952",
"fsNumber": "9999078900001341",
"ofdName": "ООО \"Ярус\" (\"ОФД-Я\")",
"ofdWebsite": "www.ofd-ya.ru",
"ofdinn": "7728699517",
"fnsWebsite": "www.nalog.ru",
"companyINN": "7725713770",
"companyName": "ООО \"Кинопортал\"",
"documentNumber": 166,
"shiftNumber": 8893,
"documentIndex": 9606,
"processedAt": "2018-12-21T13:52:00",
"content": {
"correctionType": 1,
"type": 1,
"description": "Не хочу но надо",
"causeDocumentDate": "2017-08-10T00:00:00",
"causeDocumentNumber": "ФЗ-54",
"totalSum": 17.25,
"cashSum": 1.23,
"eCashSum": 2.34,
"prepaymentSum": 5.67,
"postpaymentSum": 4.56,
"otherPaymentTypeSum": 3.45,
"tax1Sum": 1.34,
"tax2Sum": 2.34,
"tax3Sum": 3.34,
"tax4Sum": 4.34,
"tax5Sum": 5.34,
"tax6Sum": 6.34,
"taxationSystem": 1
},
"change": 0,
"fp": "998143741"
}
}
🧩ReceiptInfo
Метод возвращает результат фискализации чека по его идентификатору
🖌Параметры запроса
Параметр | Тип | Описание |
---|---|---|
appId | string | ID приложения (из договора) |
appSecret | string | Пароль приложения (из договора) |
inn | string | ИНН Организации |
receiptId | string | Уникальный идентификатор чека в системе |
📥Пример запроса
POST -> /kktgate/api/ReceiptInfo
{
"appId":"28c2126d-0a6e-4b4c-b937-0c08d3e41f51",
"appSecret":"00ga0lgf4cft",
"receiptId":"12345",
"inn":"7725713770"
}
📤Пример ответа
{
"ok": true,
"code": 0,
"message": "OK",
"time": "0.669 ms",
"version": 2,
"result": {
"order": {
"id": "12345",
"inn": "7806080903",
"group": "Main",
"key": "7725713770",
"content": {
"type": 1,
"positions": [
{
"quantity": 1,
"price": 700,
"tax": 1,
"text": "Билет в кино",
"paymentMethodType": 4,
"paymentSubjectType": 4,
"nomenclatureCode": "MTIzNDU2Nzg5MA=="
}
],
"checkClose": {
"taxationSystem": 0,
"payments": [
{
"type": 2,
"amount": 700
}
]
},
"customerContact": "[email protected]"
}
},
"receipt": {
"id": "0133ce16b64ee4ae8e766d7b5b9d3f360d3d",
"deviceSN": "1400000000000052",
"deviceRN": "0000000400054952",
"fsNumber": "9999078900001341",
"ofdName": "ООО \"Ярус\" (\"ОФД-Я\")",
"ofdWebsite": "www.ofd-ya.ru",
"ofdinn": "7728699517",
"fnsWebsite": "www.nalog.ru",
"companyINN": "7725713770",
"companyName": "ООО \"Кинопортал\"",
"documentNumber": 4110,
"shiftNumber": 2961,
"documentIndex": 2667,
"processedAt": "2018-08-17T10:19:00",
"content": {
"type": 1,
"positions": [
{
"quantity": 1,
"price": 700.00,
"tax": 1,
"text": "Билет в кино",
"paymentMethodType": 4,
"paymentSubjectType": 4
}
],
"checkClose": {
"payments": [
{
"type": 2,
"amount": 700.00
}
],
"taxationSystem": 0
},
"customerContact": "[email protected]"
},
"change": 0,
"fp": "364831178"
},
"dt_create": "2018-08-17T13:10:18.410Z",
"status": 2,
"attributes": {
"test1": "12345",
},
"error": null
}
}
v2
status Код | Описание |
---|---|
0 | Чек добавлен в систему ожидает постановки в очередь |
1 | Чек отправлен на фискализацию |
2 | Чек успешно фискализирован |
3 | Чек ожидает свободной кассы, очередь переполнена! |
4 | Чек с ошибкой (фискализация не будет выполнена) (см. поле error) |
5 | Ошибка кассы (попытка фискализации будет выполнена повторно) (см. поле error) |
🧩GetNotifications
Метод для получение архивных нотификаций.
POST -> /kktgate/api/GetNotifications
{
"appId":"28c2126d-0a6e-4b4c-b937-0c08d3e41f51",
"appSecret":"00ga0lgf4cft",
}
📤Пример ответа
{
"ok": true,
"code": 0,
"message": "OK",
"time": "0.402 ms",
"version": 2,
"result": 10
}
Нотификации
Нотификации – это уведомления приложения о успешной обработке чека. В уведомлении передается номер чека и сам чек.
Нотификации по http(s)
Система может уведомлять организацию об успешной обработке чека. Для этого в настройках приложения необходимо указать URL для уведомлений, на который будет отправляться POST-запросы с чеком