API кассы

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


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

Архитектура

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


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

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

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

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


Если в запросе не передан заголовок с данными аутентификации или переданы неверные данные, система вернет HTTP статус 401 – Unauthorized.

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

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


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


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

Система сохраняет только успешные результаты запросов.

Тестовый метод [идемпотентный]

Для проверки взаимодействия с API можно вызвать тестовый метод по адресу https://api.cloudpayments.ru/test без передачи параметров. В ответ метод возвращает статус запроса.

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

Фискализация кассы [идемпотентный метод]

Для перевода интернет-кассы в фискальный режим работы (первичная регистрация) необходимо отправить запрос по адресу https://api.cloudpayments.ru/kkt/fiscalize с передачей следующих параметров:

Параметр Формат Применение Описание
Inn Строка Обязательный ИНН организации или индивидуального предпринимателя — пользователя кассы
DeviceNumber Строка Обязательный Заводской номер кассы
FiscalNumber Строка Обязательный Номер фискального накопителя
RegNumber Строка Обязательный Регистрационный номер кассы
Url Строка Обязательный Адрес сайта (сайтов) — место расчетов
Ofd Строка Обязательный Оператор фискальный данных, см. справочник
TaxationSystem Массив значений Обязательный Одно или несколько значний системы налогообложения, см. справочник

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

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

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

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

Формирование кассового чека [идемпотентный метод]

Для формирования кассового чека необходимо отправить запрос по адресу https://api.cloudpayments.ru/kkt/receipt с передачей следующих параметров:

Параметр Формат Применение Описание
Inn Строка Обязательный ИНН вашей организации или ИП, на который зарегистрирована касса
Type Строка Обязательный Признак расчета, см. справочник
CustomerReceipt JSON Обязательный Состав чека
InvoiceId Строка Необязательный Номер заказа в вашей системе
AccountId Строка Необязательный Идентификатор пользователя в вашей системе

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

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

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

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

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

  • null или не указано — НДС не облагается
  • 18 — НДС 18%
  • 10 — НДС 10%
  • 0 — НДС 0%
  • 110 — расчетный НДС 10/110
  • 118 — расчетный НДС 18.118

При указании ставки НДС будьте внимательны: "НДС 0%" и "НДС не облагается" — это не равнозначные варианты.


Варианты системы налогообложения:

  • 0 — Общая система налогообложения
  • 1 — Упрощенная система налогообложения (Доход)
  • 2 — Упрощенная система налогообложения (Доход минус Расход)
  • 3 — Единый налог на вмененный доход
  • 4 — Единый сельскохозяйственный налог
  • 5 — Патентная система налогообложения

При не указании системы налогообложения чек формируется с первой указанной при фискализации.


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

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