Методы - 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 Сумма платежа в рублях

🔗Agent v2

Параметр Тип Описание Тег
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"
    }
}

🧩ReceiptBatch v2

🚀 Оптимально подходит для фискализации больших объемов

Метод для формирование пачки фискальных чеков.

метод может принять не более 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"
    }
}

🧩CorrectionBatch v2

🚀 Оптимально подходит для фискализации больших объемов

Метод для формирование пачки фискальных чеков коррекции.

метод может принять не более 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
    }
}

status v2

Код Описание
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-запросы с чеком

Как использовать? 📔