Сводка изменений

Версия 3.3.8 от 15.06.2023

В этом разделе отражены изменения документа, внесенные с 15.06.2023 года.

Онлайн-касса для интернет-расчетов

Условия успешного создания чека

• в чеке есть хотя бы одна позиция;
• во всех позициях указано наименование;
• цена и сумма позиции не отрицательная;
• общая сумма всех позиций больше нуля;
• входная строка наименования товара длиной не более 128 символов, более длинные строки будут обрезаны;
• указанная система налогообложения должна совпадать с одним из вариантов, зарегистрированных в ККТ;
• числовые значения переданы с точностью не более двух знаков после запятой;
• передан ИНН, если он требуется в документации.

Отправка покупателю онлайн-чека

На выбор покупателя кассовый чек необходимо отправить в письме на e-mail адрес или в СМС (Viber/WhatsApp/Telegram) сообщении на номер телефона. При формировании корректного запроса на отправку чека, при условии передачи e-mail адреса или номера телефона покупателя, или при самостоятельном создании чека из личного кабинета — все необходимые реквизиты система передает в уведомлении Receipt.

Момент отправки чека

Чек должен быть отправлен покупателю в момент расчета. Для одностадийных платежей чек формируется сразу же после прохождения оплаты, для двустадийных (c холдированием) — при подтверждении операции.

API Кассы

API для касcы — программный интерфейс системы для взаимодействия с онлайн-кассой.

Интерфейс работает по адресу api.cloudpayments.kz и поддерживает функции для фискализации кассы, а также формирования и выдачи кассовых чеков.

Архитектура

API использует REST архитектуру. Параметры передаются методом POST в формате JSON, кодировке UTF-8 с обязательным указанием заголовка Content-Type: application/json.

Ответ система выдает в JSON формате, который как минимум включает в себя два параметра: Success и Message:

{ "Success": false, "Message": "Invalid Amount value" }

Первый параметр указывает на результат выполнения запроса – успешно или нет, второй может содержать дополнительную информацию.

Аутентификация запросов

Для аутентификации запроса используется HTTP Basic Auth — отправка логина и пароля в заголовке HTTP-запроса. В качестве логина используется Public ID, в качестве пароля — API Secret. Оба этих значения можно получить в личном кабинете.

Идемпотентность API

Идемпотентность — свойство API при повторном запросе выдавать тот же результат, что на первичный без повторной обработки. Это значит, что вы можете отправить несколько запросов к системе с одинаковым идентификатором, при этом обработан будет только один запрос, а все ответы будут идентичными. Таким образом реализуется защита от сетевых ошибок, которые приводят к созданию дублированных записей и действий.

Для включения идемпотентности необходимо в запросе к API передавать заголовок с ключом X-Request-ID, содержащий уникальный идентификатор. Формирование идентификатора запроса остается на вашей стороне — это может быть guid, комбинация из номера заказа, даты и суммы или любое другое значение на ваше усмотрение.

Каждый новый запрос, который необходимо обработать, должен включать новое значение X-Request-ID. Обработанный результат хранится в системе в течение 1 часа.

Формирование кассового чека

Метод формирования кассового чека.

Адрес метода:
https://api.cloudpayments.kz/kkt/receipt

Параметры запроса:

При указании e-mail адреса или номера телефона плательщика, система автоматически отправит письмо с чеком или сообщение со ссылкой на чек. Вы также можете не указывать контакты, а самостоятельно отправлять покупателю чек в электронной форме с указанием фискальных реквизитов, полученных в уведомлении Receipt.

Type

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

CustomerReceipt

Параметры формирования чека/состав чека.
Объект CustomerReceipt также может быть передан в параметре Data с вызовом виджета, либо в любом другом платёжном методе CloudPayments (например, оплата по криптограмме, по токену, подтверждении оплаты, возвратах денежных средств, изменений подписки и др.) для формирования чека прихода при успешном платеже.

Items

Параметры услуг/товарных позиций в чеке.

Vat

Значения ставки НДС.

Method

Признак способа расчета.

Object

Признак предмета расчета.

ProductCodeData

Данные маркировки товара.

TaxationSystem

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

Amounts

Общая сумма платежа или возврата. Должна содержать в себе, как минимум, один из следующих параметров.

Пример запроса

{
    "Inn": "7708806062", //ИНН
    "InvoiceId": "1234567", // Номер заказа, необязательный
    "AccountId": "user@example.com", // Идентификатор пользователя, необязательный
    "Type": "Income", // Признак расчета
    "CustomerReceipt": {
        "Items": // Товарные позициии [
            {
                "label": "Наименование товара 1", // Наименование товара или услуги
                "price": 100.00, // Цена
                "quantity": 1.00, // Количество
                "amount": 100.00, // Сумма
                "vat": 0, // Ставка НДС
                "measurementUnit": "шт" // Единица измерения
            },
            {
                "label": "Наименование товара 2", // Наименование товара или услуги
                "price": 200.00, // Цена
                "quantity": 2.00, // Количество
                "amount": 300.00, // Сумма со скидкой 25%
                "vat": 10, // Ставка НДС
                "measurementUnit": "шт" // Единица измерения
            },
            {
                "label": "Наименование товара 3", //наименование товара или услуги
                "price": 300.00, // Цена
                "quantity": 3.00, // Количество
                "amount": 900.00, // Сумма
                "vat": 20, // Ставка НДС
                "measurementUnit": "шт" // Единица измерения
            }
        ],
        "calculationPlace": "www.my.kz", //Место осуществления расчёта
        "taxationSystem": 0, // Система налогообложения; необязательный, если у вас одна система налогообложения
        "email": "user@example.com", // e-mail покупателя, если нужно отправить письмо с чеком
        "phone": "", // Телефон покупателя в любом формате, если нужно отправить сообщение со ссылкой на чек
        "isBso": false, // Чек является бланком строгой отчётности
        "amounts": {
            "electronic": 1300.00, // Сумма оплаты электронными деньгами
            "advancePayment": 0.00, // Сумма из предоплаты (зачетом аванса) (2 знака после запятой)
            "credit": 0.00, // Сумма постоплатой(в кредит) (2 знака после запятой)
            "provision": 0.00 // Сумма оплаты встречным предоставлением (сертификаты, др. мат.ценности) (2 знака после запятой)
            "cash": 0.00 // Сумма оплаты наличными деньгами (2 знака после запятой)
        },    
    }
}

Формирование чека является асинхронной операцией, поэтому в ответ на запрос API система сообщает, что чек поставлен в очередь и будет обработан кассой в течение нескольких секунд. Для получения результата операции, вы можете включить Receipt уведомление в личном кабинете. При постановке чека в очередь, ему присваивается уникальный идентификатор.

Пример ответа: запрос принят успешно:

{
    "Model": {
        "Id": "QSnuAqV",
        "ErrorCode": 0
    },
    "InnerResult": null,
    "Success": true,
    "Message": "Queued",
    "Warning": null
}

Пример ответа: запрос принят успешно (но имеется сообщение требующее внимания):

{
    "Model": {
        "Id": "FrBuAok",
        "ErrorCode": 0
    },
    "InnerResult": null,
    "Success": true,
    "Message": "Queued",
    "Warning": "01801810008658: Буфер ФН переполнен - Необходима замена ФН"
}

Пример ответа: некорректный запрос:

{
    "Model": {
        "ErrorCode": -1
    },
    "InnerResult": null,
    "Success": false,
    "Message": "Компания с ИНН 7777777777 не найдена"
}

В случае ошибки в поле Model возвращается объект с полем ErrorCode (см. справочник)

Запрос статуса чека

Метод получения статуса чека.

Адрес метода:
https://api.cloudpayments.kz/kkt/receipt/status/get

Параметры запроса:

Пример запроса:

{ "Id": "Nr9eTaj" }

Пример ответа (чек успешно обработался):

{
   "Model": "Processed",
   "Success": true
}

Пример ответа (чек не пробился):

{
   "Model": "Error",
   "InnerResult": null,
   "Success": true,
   "Message": "Нет касс без признака БСО для организации с ИНН ..."
}

Пример ответ (чек в очереди):

{
   "Model": "Queued",
   "Success": true
}

Пример ответ (чек не найден):

{
   "Model": "NotFound",
   "Success": true
}

Получение данных чека

Метод получения детализации чека.

Адрес метода:
https://api.cloudpayments.kz/kkt/receipt/get

Параметры запроса:

Пример запроса:

{ "Id": "Nr9eTaj" }

Пример ответа:

{
    "Model": {
        "Email": "user@example.com",
        "Phone": null,
        "Items": [
            {
                "Label": "Товар 1",
                "Price": 100,
                "Quantity": 1,
                "Amount": 100,
                "Department": null,
                "Vat": 0,
                "EAN13": null,
                "AgentSign": null,
                "Method": 6,
                "Object": 3,
                "MeasurementUnit": "шт"
            },
            {
                "Label": "Товар 2",
                "Price": 220,
                "Quantity": 2.5,
                "Amount": 550,
                "Department": null,
                "Vat": 10,
                "EAN13": null,
                "AgentSign": 2,
                "Method": 0,
                "Object": 0,
                "MeasurementUnit": null
            },
            {
                "Label": "Товар 3",
                "Price": 150,
                "Quantity": 5,
                "Amount": 600,
                "Department": null,
                "Vat": 20,
                "EAN13": null,
                "AgentSign": null,
                "Method": 0,
                "Object": 0,
                "MeasurementUnit": null
            }
        ],
        "TaxationSystem": 2,
        "Amounts": null,
        "IsBso": false,
        "AdditionalData": {
            "Id": "Nr9eTaj",
            "AccountId": "user@example.com"
            "Amount": 1150,
            "CalculationPlace": "www.my.kz",
            "CashierName": "test",
            "DateTime": "2018-11-14T16:19:33",
            "DeviceNumber": "00000000000000000001",
            "DocumentNumber": "1323",
            "FiscalNumber": "9999078900005430",
            "FiscalSign": "13223",
            "InvoiceId": "1322223",
            "Ofd": "Первый ОФД",
            "OfdReceiptUrl": "http://url.com/adress",
            "OrganizationInn": "7708806062",
            "QrCodeUrl": "https://qr.cloudpayments.kz/receipt?q=t%3d20181205T185000%26s%3d99.00%26fn%3d9999078900005430%26i%3d157347%26fp%3d1016954666%26n%3d1",
            "RegNumber": "322223",
            "SenderEmail": "sender@email.com",
            "SessionCheckNumber": "12223",
            "SessionNumber": "1",
            "SettlePlace": "117342, Москва, ул. Бутлерова, 17Б",
            "TransactionId": 14442,
            "Type": "Income",
        }
    },
    "InnerResult": null,
    "Success": true,
    "Message": null
}

Уведомления

Уведомление — HTTP-запрос от системы к вашему сайту. Подобные запросы также называют callback или webhook.

Receipt

Выполняется после выдачи кассового чека.

Служит для информирования о сформированных онлайн-чеках: система отправляет запрос на адрес ТСП с информацией о чеке, а сайт должен зафиксировать информацию.

Параметры передаются в теле запроса, список представлен в следующей таблице:

В ответ на запрос система ожидает получить ответ в JSON формате с обязательным параметром code:

{"code":0}

Код определяет результат обработки сервером ТСП уведомления о чеке и может принимать единственное значение:

Принцип работы и проверка уведомлений

Параметры передаются методом POST или GET в теле запроса в формате «ключ=значение».

Уведомление receipt содержит 2 HTTP-заголовка X-Content-HMAC и Content-HMAC, в котором находится проверочное значение запроса, вычисленное с помощью алгоритма HMAC. Отличие между ними только в том, что первый генерируется из URL decoded (или не encoded) параметров, а второй генерируется из URL encoded параметров (что может вызывать проблемы). Если вам необходимо проверять подлинность и целостность уведомлений, вы можете вычислить проверочное значение на своей стороне и сравнить с тем, что пришло в запросе. Совпадение подтверждает, что уведомление было отправлено от нас и пришло к вам в оригинальном виде.

При реализации проверки сообщения обратите внимание на следующие моменты:

• Для уведомлений, отправленных методом POST, сообщением является тело запроса. Для GET — строка параметров;
• Хэш вычисляется функцией SHA256;
  
• В качестве ключа используется API Secret, который можно получить в личном кабинете;
  
• Вычисленное значение передается в кодировке base64.

Примеры вычисления HMAC на разных языках программирования.

Адреса, с которых система отправляет уведомления — 130.193.70.192 и 185.98.85.109. Добавлены новые подсети адресов - 91.142.84.0/27, 87.251.91.160/27 и 185.98.81.0/28.

Для вас это означает что:

• Если вы не используете Receipt уведомления, то делать ничего не нужно.

• Если вы используете это уведомление, то нужно проверить, какие протоколы шифрования https поддерживает ваш сервер. Если ваш сервер поддерживает только SSL3, то нужно обновить его минимум до TLS11. Ещё лучше — до TLS13. В крайнем случае вы можете перевести уведомления на http-протокол.

Более подробно, как отказаться от SSL3. После 8 июня https-уведомления на сервера, поддерживающие только SSL3, могут не доставляться.

Справочники

Коды временных зон

В таблице ниже представлены коды временных зон для преобразования времени.

Тип уведомления

В таблице ниже представлены тип уведомления.

Коды ошибок

В таблице ниже представлены коды ошибок при формировании онлайн-чека.

Коды предупреждений

В таблице ниже представлены возможные коды предупреждений при попытке формирования чека, которые могут блокировать пробитие чека (в этом случае в ответе присутствует поле Warning с рекомендацией решения проблемы)