NAV
Example

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

Версия 3.4.3 от 17.09.2024

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

Номер версии Раздел Описание Дата изменения
3.4.3 API Кассы Добавлен новый метод Проверка кода маркировки 2024-09-17
3.4.2 API Кассы Формирование кассового чека В блоке CustomerReceipt для поля CashierName изменена логика передачи значения. Новая логика в описании к полю 2024-08-01
3.4.1 API Кассы Формирование кассового чека
MarkPartQuantity
Справочники Коды ошибок
Добавлен новый пример запроса с дробным числом маркируемого товара
Добавлено описание заполнения полей блока MarkPartQuantity
Добавлены коды ошибок
2024-06-18
3.4.0 API Кассы Фискализация кассы
API Кассы Запрос статуса чека
API Кассы Запрос статуса чека коррекции
Для поля MerchantPhone - введена обязательность и изменен формат на: +79999999999
Для поля Model изменен ответ статуса: Queued
Для поля Model изменен ответ статуса: Queued
2024-06-03
3.3.9 API Кассы Добавлен новый метод Предупреждения по кассам 2024-05-08
3.3.8 API Кассы Изменение состояния кассы
API Кассы Получение данных кассы
Расширен пример ответа, добавлено описание кодов предупреждений 2024-05-07
3.3.7 API Кассы Чек коррекции Добавлены методы формирования чека коррекции для ФФД 1.2 2022-06-10
3.3.6 API Кассы Параметры услуг/товарных позиций Добавлен UnitCode - Мера количества предмета расчета. ффд 1.2 2022-04-12
3.3.5 API Кассы Признак предмета расчета Добавлены параметры в Признак предмета расчета 2022-04-07
3.3.4 Справочники Коды ошибок Добавлены коды ошибок при формировании онлайн чека 2022-04-06
3.3.3 API Кассы Чек коррекции Добавлен AdditionalReceiptRequisite в метод формирования чека коррекции (тег 1192) 2022-03-31
3.3.2 API Кассы CustomerReceipt Добавлен параметры для ффд 1.2 2022-03-21
3.3.1 API Кассы CustomerReceipt Добавлен параметры AdditionalReceiptInfos и AdditionalReceiptRequisite 2021-12-16
3.3.0 Общая информация о закрывающих документах Добавлена информация и FAQ для партнеров 2021-09-29
3.2.0 API Кассы Чек коррекции Добавлены методы формирования, запроса статуса и получение данных чека коррекции 2021-08-18
3.1.3 Справочники Коды ошибок Добавлены коды ошибок при формировании онлайн чека и коды предупреждений 2021-03-22
3.1.2 API Кассы Запрос статуса чека Добавлены примеры ответов на запрос статуса чека и добавлены параметры формирования чека/состав чека: AdditionalReceiptInfos и AdditionalPositionInfo 2021-02-05
3.1.1 Справочники Коды ошибок Добавлены коды ошибок при формировании онлайн чека 2020-11-18
3.1.0 API Кассы CustomerReceipt Добавлен параметр CashierName в метод формирования кассового чека 2020-11-18

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

ФЗ-54

Закон 54-ФЗ "О применении контрольно-кассовой техники" с изменениями от 03.07.2016 предписывает интернет-сервисам при осуществлении расчетов с использованием электронного средства платежа (в т.ч. банковской картой) использовать контрольно-кассовую технику (ККТ) и отправлять покупателю электронный чек в момент расчета.

Основные положения закона

Онлайн-касса

Мы используем кассы "MicroPay-ФАС" и "MicroPay-ФС" с подключением к любому оператору фискальных данных.

cash_registers

Стоимость

Стоимость услуг по онлайн-фискализации и сопровождению можно узнать на сайте CloudKassir и/или уточнить у менеджера.

Порядок подключения

Для подключения услуги онлайн-фискализации необходимо:

После подписания договора и оплаты счета вам будут предоставлены номер ККТ и ФН для регистрации в ФНС.

Операторы фискальных данных

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

Код Название оператора
Element ОФД Группа Элемент
PeterService ООО «ПЕТЕР-СЕРВИС Спецтехнологии»
FirstOfd Первый ОФД
Taxcom Такском
PlatformaOfd Платформа ОФД
OfdYa ОФД-Я
OfdYandex Яндекс ОФД
Garantexpress Гарант ОФД
OfdAstralNalog Астрал ОФД
Sbis ООО «Компания «ТЕНЗОР»
Esphere КОРУС ОФД
Kontur Контур.ОФД
Magnit ОФД АО «Тандер»
InitPro ИнитПро ОФД
KonturNtt ОФД Контур НТТ
KazakhTelecom ОФД - АО «Казахтелеком»

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

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

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

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

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

Тестирование онлайн-чека

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

API Кассы

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

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

Архитектура

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 часа.

Тестовый метод

Для проверки взаимодействия с API можно вызвать тестовый метод.

Адрес метода:
https://api.cloudpayments.ru/test

Параметры запроса:
Отсутствуют.

Пример ответа:
В ответ метод возвращает статус запроса.

{"Success":true,"Message":"bd6353c3-0ed6-4a65-946f-083664bf8dbd"}

Фискализация кассы

Метод перевода интернет-кассы в фискальный режим работы (первичная регистрация).

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

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

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

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

{
   "Inn":"7708806062",                      //ИНН
   "DeviceNumber":"00000000000000000001",   //заводской номер кассы
   "FiscalNumber":"9999078900005430",       //номер ФН
   "RegNumber":"0000000004030311",          //регистрационный номер кассы
   "Url":"www.cloudpayments.ru",            //ваш адрес сайта
   "Ofd":"PeterService",                    //ОФД
   "TaxationSystem":[0],                    //системы налогообложения
   "MerchantEmail":"my@mail.ru",            //Email магазина
   "MerchantPhone":"+79999999999",             //Телефон магазина в формате "+79999999999"
   "IsBso":false,                           //БСО
}

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

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

{"Success":true,"Message":"Fiscal data queued"}

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

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

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

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

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

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

Type

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

Тип Признак расчета Описание
Income Приход Выдается при получении средств от покупателя (клиента)
IncomeReturn Возврат прихода Выдается при возврате покупателю (клиенту) средств, полученных от него
Expense Расход Выдается при выдаче средств покупателю (клиенту)
ExpenseReturn Возврат расхода Выдается при получении средств от покупателя (клиента), выданных ему

CustomerReceipt

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

Параметр Формат Применение Описание
Items JSON Обязательный Содержимое позиций чека, см. ниже. Действует ограничение на максимальное количество позиций в чеке (100 штук). Если их больше - пробьется несколько чеков максимум по 100 позиций в каждом.
TaxationSystem Строка Обязательный Система налогообложения (необязательный, если у вас одна система налогообложения), см. ниже
Amounts JSON Обязательный Общая сумма платежа или возврата, см. ниже
CalculationPlace Строка Необязательный Место осуществления расчёта
Email Строка Необязательный E-mail покупателя для отправки чека
Phone Строка Необязательный Телефон покупателя в формате без скобок и дефисов для отправки ссылки на чек
CustomerInfo Строка Необязательный Покупатель, наименование организации или фамилия, имя, отчество (при наличии), серия и номер паспорта покупателя (клиента), тег ОФД 1227
CustomerInn Строка Необязательный ИНН покупателя, тег ОФД 1228
isBso Булевый Необязательный true, если чек является бланком строгой отчётности
AgentSign Строка Необязательный Признак агента, тег ОФД 1057, см. ниже
CashierName Строка Необязательный Имя кассира, если не передать будет использовано значение (если заполнено) указанное в настройке кассира в ЛК
AdditionalReceiptInfos Массив строк Необязательный Дополнительная информация общая для чека, многострочная
AdditionalReceiptRequisite Строка Необязательный Дополнительный реквизит чека (тег 1192)
CustomerBirthday Строка Необязательный Дата рождения покупателя (клиента), тег ОФД 1243 (ффд 1.2)
CustomerStateCode Строка Необязательный Гражданство, тег ОФД 1244 (ффд 1.2)
CustomerDocType Строка Необязательный Код вида документа, удостоверяющего личность, тег ОФД 1245 (ффд 1.2)
CustomerDoc Строка Необязательный Данные документа, удостоверяющего личность, тег ОФД 1246 (ффд 1.2)
CustomerPlace Строка Необязательный Адрес покупателя (клиента), тег ОФД 1254 (ффд 1.2)
UserRequisiteData JSON Необязательный Дополнительный реквизит пользователя, тег ОФД 1084, см. ниже
OperationReceiptRequisite JSON Необязательный Операционный реквизит чека, тег ОФД 1270, (ффд 1.2) см. ниже
IndustryRequisiteCollection Массив объектов Необязательный Отраслевой реквизит чека, тег ОФД 1261 (ффд 1.2)

Items

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

Параметр Формат Применение Описание
Label Строка Обязательный Наименование товара или услуги
Price Строка Обязательный Цена за единицу товара/услуги
Quantity Строка Обязательный Количество
Vat Строка Обязательный Ставка НДС услуги/товара
Amount Строка Обязательный Price * Quantity c учетом скидки
Method Строка Необязательный Способ расчёта, см. ниже
Object Строка Необязательный Предмет расчёта, см. ниже
MeasurementUnit Строка Необязательный Единица измерения.
Excise Строка Необязательный Сумма акциза
CountryOriginCode Строка Необязательный Код страны происхождения товара в соответствии с Общероссийским классификатором стран мира 3 символа, тег ОФД 1230
CustomsDeclarationNumber Строка Необязательный Регистрационный номер таможенной декларации 32 символа, тег ОФД 1231
AgentSign Строка Необязательный Признак агента, тег ОФД 1222, см. ниже
AgentData JSON Необязательный Данные агента, тег ОФД 1223, см. ниже
PurveyorData JSON Необязательный Данные поставщика платежного агента, тег ОФД 1224, см. ниже
AdditionalPositionInfo Строка Необязательный Дополнительная информация внутри конкретной позиции чека
SaleObjectData Строка Необязательный Дополнительный реквизит предмета расчета, тег ОФД 1191
IndustryRequisiteCollection Массив объектов Необязательный Отраслевой реквизит предмета расчета, тег ОФД 1260 (ффд 1.2)
ProductCodeData JSON Необязательный Данные маркировки товара, тег ОФД 1162, см. ниже (ффд 1.05)
MarkPartQuantity JSON Необязательный Дробное количество маркированного товара, тег ОФД 1291 (ффд 1.2) см. ниже
RawMarkCode Строка Необязательный Код маркировки, тег ОФД 2000 (ффд 1.2)
GroupSeparator Строка Необязательный Разделитель GS (ффд 1.2)
UnitCode Строка Необязательный Мера количества предмета расчета, тег ОФД 2108, см. ниже (ффд 1.2). Заменяет MeasurementUnit.
Vat

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

Код Описание
null или не указано НДС не облагается
0 НДС 0%
10 НДС 10%
20 НДС 20%
110 Расчетный НДС 10/110
120 Расчетный НДС 20/120
12 НДС 12% (только для онлайн-касс в Казахстане)
Method

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

Код Описание
0 Unknown, неизвестный способ расчета
1 FullPrepayment, предоплата 100%
2 PartialPrepayment, предоплата
3 AdvancePay, аванс
4 FullPay, полный расчёт
5 PartialPayAndCredit, частичный расчёт и кредит
6 Credit, передача в кредит
7 CreditPayment, оплата кредита
Object

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

Код Описание
0 Unknown, неизвестный предмет оплаты
1 Commodity, товар
2 ExcisedCommodity, подакцизный товар
3 Job, работа
4 Service, услуга
5 GamblingBet, ставка азартной игры
6 GamblingWin, выигрыш азартной игры
7 LotteryTicket, лотерейный билет
8 LotteryWin, выигрыш лотереи
9 RidAccess, предоставление РИД
10 Payment, платеж
11 AgentReward, агентское вознаграждение
12 Composite, Выплата
13 Another, иной предмет расчета
14 PropertyLaw, Имущественное право
15 NonOperatingIncome, Внереализационный доход
16 InsuranceContributions, Страховые взносы
17 TradeFee, Торговый сбор
18 ResortFee, Курортный сбор
19 CautionMoney, Залог
20 ExpensesIncurred, Расход
21 ContributionsOnIp, Взносы на обязательное пенсионное страхование ИП
22 ContributionsSimple, Взносы на обязательное пенсионное страхование
23 ContributionsMedical, Взносы на обязательное медицинское страхование ИП
24 ContributionsMedicalSimple, Взносы на обязательное медицинское страхование
25 ContributionsSocial, Взносы на обязательное социальное страхование
26 CasinoPayment, Платеж казино
27 CashWithdrawal, Выдача денежных средств (ффд 1.2)
30 Atnm, АТНМ (ффд 1.2)
31 Atm, АТМ (ффд 1.2)
32 Tnm, ТНМ (ффд 1.2)
33 Tm, ТМ (ффд 1.2)
AgentData

Данные агента, Тег ОФД 1223.

Параметр Формат Применение Описание
AgentOperationName Строка Обязательно, если AgentSign (1222) = 0, 1 Наименование операции банковского платежного агента или банковского платежного субагента, тег ОФД 1044
PaymentAgentPhone Строка Обязательно, если AgentSign (1222) = 0, 1, 2, 3 Телефон платежного агента, тег ОФД 1073
PaymentReceiverOperatorPhone Строка Обязательно, если AgentSign (1222) = 2, 3 Телефон оператора по приему платежей, тег ОФД 1074
TransferOperatorPhone Строка Обязательно, если AgentSign (1222) = 0, 1 Телефон оператора перевода, тег ОФД 1075
TransferOperatorName Строка Обязательно, если AgentSign (1222) = 0, 1 Наименование оператора перевода, тег ОФД 1026
TransferOperatorAddress Строка Обязательно, если AgentSign (1222) = 0, 1 Адрес оператора перевода, тег ОФД 1005
TransferOperatorInn Строка Обязательно, если AgentSign (1222) = 0, 1 ИНН оператора перевода, тег ОФД 1016
PurveyorData

Данные поставщика платежного агента, Тег ОФД 1224.

Параметр Формат Применение Описание
Name Строка Обязательный Наименование поставщика, тег ОФД 1225
Inn Строка Обязательный ИНН поставщика, тег ОФД 1226
Phone Строка Обязательный, если AgentSign равен одному из значений [0, 1, 2, 3]
Необязательный, если AgentSign не задан или равен одному из значений [4, 5, 6]
Телефон поставщика, тег ОФД 1171
ProductCodeData

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

Параметр Формат Применение Описание
CodeProductNomenclature Строка Необязательный HEX представление штрих/бар кода маркировки целиком (Только для касс Микропэй и БФР-112ФС)
MarkPartQuantity

Дробное количество маркированного товара

Параметр Формат Применение Описание
Numerator Число Обязательный Числитель, тег ОФД 1293
Denominator Число Обязательный Знаменатель, тег ОФД 1294
UnitCode

Мера количества предмета расчета

Код Описание
0 Unit, шт. или ед
10 Gram, Грамм
11 Kilogram, Килограмм
12 Ton, Тонна
20 Centimetre, Сантиметр
21 Decimetre, Дециметр
22 Metre, Метр
30 SquareCentimetre, Квадратный сантиметр
31 SquareDecimetre, Квадратный сантиметр
32 SquareMetre, Квадратный метр
40 Milliliter, Миллилитр
41 Litre, Литр
42 CubicMeter, Кубический метр
50 KilowattHour, Киловатт час
51 Gigacalorie, Гигакалория
70 Day, Сутки (день)
71 Hour, Час
72 Minute, Минута
73 Second, Секунда
80 Kilobyte, Килобайт
81 Megabyte, Мегабайт
82 Gigabyte, Гигабайт
83 Terabyte, Терабайт
255 None, Иная система измерения

TaxationSystem

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

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

AgentSign

Признак агента, Тег ОФД 1057, 1222.
Для корректного формирования при указаннии признака агента необходимо:
В каждой товарной позиции указывать данные агента (AgentData, Тег 1223) и данные поставщика (PurveyorData, Тег 1224).

Код Описание
0 "Банковский платежный агент", Оказание услуг пользователем, являющимся банковским платежным агентом
1 "Банковский платежный субагент", Оказание услуг пользователем, являющимся банковским платежным субагентом
2 "Платежный агент", Оказание услуг пользователем, являющимся платежным агентом
3 "Платежный субагент", Оказание услуг пользователем, являющимся платежным субагентом
4 "Поверенный", Оказание услуг пользователем, являющимся поверенным
5 "Комиссионер", Оказание услуг пользователем, являющимся комиссионером
6 "Агент", Оказание услуг пользователем, являющимся агентом и не являющимся банковским платежным агентом (субагентом), платежным агентом (субагентом), поверенным, комиссионером

Amounts

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

Параметр Формат Применение Описание
Electronic Строка Необязательный Сумма оплаты электронными деньгами
AdvancePayment Строка Необязательный Сумма предоплаты
Credit Строка Необязательный Сумма постоплатой
Provision Строка Необязательный Сумма встречным предоставлением

UserRequisiteData

Дополнительный реквизит пользователя

Параметр Формат Применение Описание
RequisiteKey Строка Обязательный Наименование дополнительного реквизита пользователя, тег ОФД 1085
RequisiteValue Строка Обязательный Значение дополнительного реквизита пользователя, тег ОФД 1086

OperationReceiptRequisite

Операционный реквизит чека

Параметр Формат Применение Описание
OperationIdentifier Число Обязательный Идентификатор операции, тег ОФД 1271
OperationDate Строка Обязательный Дата, время операции, тег ОФД 1273
OperationData Строка Обязательный Данные операции, тег ОФД 1272

IndustryRequisiteCollection

Отраслевой реквизит чека

Параметр Формат Применение Описание
Code Строка Обязательный Идентификатор ФОИВ, тег ОФД 1262
DocumentDate Строка Обязательный Дата документа основания, тег ОФД 1263
DocumentNumber Строка Обязательный Номер документа основания, тег ОФД 1264
RequisiteValue Строка Обязательный Значение отраслевого реквизита, тег ОФД 1265

Пример запроса без дробного числа маркируемого товара

{
    "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, //ставка НДС
                "method": 0, // тег-1214 признак способа расчета - признак способа расчета
                "object": 0, // тег-1212 признак предмета расчета - признак предмета товара, работы, услуги, платежа, выплаты, иного предмета расчета
                "measurementUnit": "шт" //единица измерения
            },
            {
                "label": "Наименование товара 2", //наименование товара или услуги
                "price": 200.00, //цена
                "quantity": 2.00, //количество
                "amount": 300.00, //сумма со скидкой 25%
                "vat": 10, //ставка НДС
                "method": 0, // тег-1214 признак способа расчета - признак способа расчета
                "object": 0, // тег-1212 признак предмета расчета - признак предмета товара, работы, услуги, платежа, выплаты, иного предмета расчета
                "measurementUnit": "шт", //единица измерения
                "excise": 0.01, // тег-1229 сумма акциза
                "countryOriginCode": "156", // тег-1230 цифровой код страны происхождения товара в соответствии с Общероссийским классификатором стран мира 3 симв. 
                "customsDeclarationNumber": "54180656/1345865/3435625/23", // тег-1231 регистрационный номер таможенной декларации 32 симв.
                "ProductCodeData": //данные маркировки товара {
                    "CodeProductNomenclature": "3031303239303030303033343....a78495a4f6672754744773d3d" //HEX представление штрих/бар кода маркировки целиком (Только для касс Микропэй и БФР-112ФС)
                },
                "rawMarkCode": "010460043993125621JgXJ5.T\u001d8005112000\u001d930001\u001d923zbrLA==\u001d24014276281",
                "groupSeparator": "\u001d"
            },
            {
                "label": "Наименование товара 3", //наименование товара или услуги
                "price": 300.00, //цена
                "quantity": 3.00, //количество
                "amount": 900.00, //сумма
                "vat": 20, //ставка НДС
                "method": 0, // тег-1214 признак способа расчета - признак способа расчета
                "object": 0, // тег-1212 признак предмета расчета - признак предмета товара, работы, услуги, платежа, выплаты, иного предмета расчета
                "measurementUnit": "шт", //единица измерения
                "AgentSign": 6, //признак агента, тег ОФД 1222
                "AgentData": //данные агента, тег офд 1223 {
                    "AgentOperationName": null, // наименование операции банковского платежного агента или банковского платежного субагента, тег ОФД 1044
                    "PaymentAgentPhone": null, // телефон платежного агента, тег ОФД 1073
                    "PaymentReceiverOperatorPhone": null, // телефон оператора по приему платежей, тег ОФД 1074
                    "TransferOperatorPhone": null, // телефон оператора перевода, тег ОФД 1075
                    "TransferOperatorName": null, // наименование оператора перевода, тег ОФД 1026
                    "TransferOperatorAddress": null, // адрес оператора перевода, тег ОФД 1005
                    "TransferOperatorInn": null // ИНН оператора перевода, тег ОФД 1016
                },
                "PurveyorData": //данные поставщика платежного агента,  тег ОФД 1224 {
                    "Phone": "+74951234567", // телефон поставщика, тег ОФД 1171
                    "Name": "ООО Ромашка", // наименование поставщика, тег ОФД 1225
                    "Inn": "1234567890" // ИНН поставщика, тег ОФД 1226
                }
            }
        ],
        "calculationPlace": "www.my.ru", //Место осуществления расчёта
        "taxationSystem": 0, //система налогообложения; необязательный, если у вас одна система налогообложения
        "email": "user@example.com", //e-mail покупателя, если нужно отправить письмо с чеком
        "phone": "", //телефон покупателя в любом формате, если нужно отправить сообщение со ссылкой на чек
        "customerInfo": "", // тег-1227 Покупатель наименование организации или фамилия, имя, отчество (при наличии), серия и номер паспорта покупателя (клиента)
        "customerInn": "7708806063", // тег-1228 ИНН покупателя 
        "isBso": false, //чек является бланком строгой отчётности
        "AgentSign": null, //признак агента, тег ОФД 1057
        "amounts": {
            "electronic": 1300.00, // Сумма оплаты электронными деньгами
            "advancePayment": 0.00, // Сумма из предоплаты (зачетом аванса) (2 знака после запятой)
            "credit": 0.00, // Сумма постоплатой(в кредит) (2 знака после запятой)
            "provision": 0.00 // Сумма оплаты встречным предоставлением (сертификаты, др. мат.ценности) (2 знака после запятой)
        },
        "customerBirthday": "1992-12-26",
        "customerStateCode": "443",
        "customerDocType": "04",
        "customerDoc": "Some doc value",
        "customerPlace": "Kazan city",
        "userRequisiteData": {
            "requisiteKey": "key string",
            "requisiteValue": "value string"
        },
        "operationReceiptRequisite": {
            "operationIdentifier": 7,
            "operationDate": "2022-03-21",
            "operationData": "some data"
        },
        "industryRequisiteCollection": [
            {
                "code": "012",
                "documentDate": "2022-03-21T11:29:26.714Z",
                "documentNumber": "doc number value",
                "requisiteValue": "requisite value"
            }
        ]
    }
}

Пример запроса с дробным числом маркируемого товара

{
    "Inn": "7708806062",
    "CustomerReceipt": {
        "Items": [
            {
                "label": "Чек с маркировкой",
                "price": 777.00,
                "quantity": 1.00,
                "amount": 777.00,
                "UnitCode": 0,
                "MarkPartQuantity": {
                    "Numerator": 2,
                    "Denominator": 4
                },
                "RawMarkCode": "0104600286103035215opOBpkv4n9iD\u001d93Y7JW",
                "GroupSeparator": "\u001d"
            }
        ]
    }
}

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

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

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

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

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

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

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

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

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

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

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

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

Параметр Формат Применение Описание
Id Строка Обязательный Идентификатор чека

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

{ "Id": "4c335bb5ee56455f916db6e95c0d196e" }

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

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

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

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

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

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

Пример ответ (чек в очереди, но не может быть пробит по указанной причине):

{
    "Model": "Queued",
    "InnerResult": null,
    "Warnings": [
        {
            "Code": 1,
            "Description": "Есть касса (кассы) с неотправляющимися в ОФД документами"
        }
    ],
    "Success": true,
    "Message": null
}

Описание кодов из блока Warnings:

Код Описание
1 Есть касса (кассы) с неотправляющимися в ОФД документами
2 Есть касса (кассы) с заполненным ФН

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

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

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

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

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

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

Параметр Формат Применение Описание
Id Строка Обязательный Идентификатор чека

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

{ "Id": "4c335bb5ee56455f916db6e95c0d196e" }

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

{
    "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": "шт",
                "AgentData": null,
                "PurveyorData": null
            },
            {
                "Label": "Товар 2",
                "Price": 220,
                "Quantity": 2.5,
                "Amount": 550,
                "Department": null,
                "Vat": 10,
                "EAN13": null,
                "AgentSign": 2,
                "Method": 0,
                "Object": 0,
                "MeasurementUnit": null,
                "AgentData": {
                    "PayingAgentOperation": null,
                    "PayingAgentPhone": null,
                    "ReceivePaymentsOperatorPhone": null,
                    "MoneyTransferOperatorPhone": null,
                    "MoneyTransferOperatorName": null,
                    "MoneyTransferOperatorAddress": null,
                    "MoneyTransferOperatorVATIN": null
                },
                "PurveyorData": null
            },
            {
                "Label": "Товар 3",
                "Price": 150,
                "Quantity": 5,
                "Amount": 600,
                "Department": null,
                "Vat": 20,
                "EAN13": null,
                "AgentSign": null,
                "Method": 0,
                "Object": 0,
                "MeasurementUnit": null,
                "AgentData": null,
                "PurveyorData": null
            }
        ],
        "TaxationSystem": 2,
        "Amounts": null,
        "IsBso": false,
        "AdditionalData": {
            "Id": "4c335bb5ee56455f916db6e95c0d196e",
            "AccountId": "user@example.com"
            "Amount": 1150,
            "CalculationPlace": "www.my.ru",
            "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.ru/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
}

Проверка кода маркировки

Для использования метода API, проверяющего маркировку товара в Системе цифровой маркировки товаров Честный знак, нужно задать настройки “Разрешительный режим“ через ЛК мерчанта в разделе “Чеки и кассы“.

Метод для проверки кода маркировки.

Адрес метода:
https://api.cloudpayments.ru/kkt/validate-mark-code

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

Параметр Формат Применение Описание
Inn Строка Обязательный ИНН организации или индивидуального предпринимателя — пользователя кассы
MarkCode Строка Обязательный Код маркировки

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

{
    "Inn": "7708806062",
    "MarkCode": "010460043993125621JgXJ5.T\u001d8005112000\u001d930001\u001d923zbrLA==\u001d24014276281" 
}

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

Параметр Формат Применение Описание
Success Булевый Обязательный Флаг успешности запроса в ГИС МТ (получен ли ответ от ГИС МТ)
IsValid Булевый Обязательный Флаг валидности КМ (заполняется и используется при "Success": true)
Message Строка Обязательный В случае, если "IsValid": false - будет заполнена причина отказа
В случае, если "IsValid": true - null
IndustryRequisite JSON Обязательный Отраслевой реквизит предмета расчета, тег ОФД 1260
IndustryRequisite.Code Строка Обязательный Идентификатор ФОИВ, тег ОФД 1262
IndustryRequisite.DocumentDate yyyy-MM-dd HH:mm:ss Обязательный Дата документа основания, тег ОФД 1263
IndustryRequisite.DocumentNumber Строка Обязательный Номер документа основания, тег ОФД 1264
IndustryRequisite.RequisiteValue Строка Обязательный Значение отраслевого реквизита, тег ОФД 1265

Пример ответа: товар валидный:

{
    "Success": true,
    "IsValid": true,
    "Message": null,
    "IndustryRequisite": {
        "Code": "030",
        "DocumentDate": "2023-11-21T00:00:00",
        "DocumentNumber": "1944",
        "RequisiteValue": "UUID=5325c6f5-6269-4374-b95f-becbe580a039&Time=1725279151445"
    }
}

Пример ответа: товар невалидный:

{
    "Success": true,
    "IsValid": false,
    "Message": "Истек срок годности товара",
    "IndustryRequisite": null
}

Пример ответа: терминал не имеет доступа к ИНН:

{"Success":false,"Message":"Терминал {PublicId} не имеет доступа к ИНН {Inn}"}

Формирование чека коррекции

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

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

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

Параметр Формат Применение Описание
CorrectionReceiptData JSON Обязательный Состав чека см. ниже

CorrectionReceiptData

Параметры формирования чека/состав чека.

Параметр Формат Применение Описание
OrganizationInn Строка Обязательный ИНН организации
VatRate Строка Обязательный Ставка НДС, см. ниже (необязательный для ФФД 1.2)
TaxationSystem Строка Обязательный Система налогообложения, см. выше
DeviceNumber Строка Обязательный Номер ККТ
CorrectionReceiptType Строка Обязательный Признак расчета коррекции, см. ниже
CauseCorrection JSON Обязательный Основание для коррекции, см. ниже
Amounts JSON Обязательный Общая сумма платежа или возврата, см. выше
Items JSON Необязательный Содержимое позиций чека, см. выше. (обязательный для ФФД 1.2)
IndustryRequisites Массив объектов Необязательный Отраслевой реквизит чека, тег ОФД 1261 см. выше (ффд 1.2)
UserRequisiteData JSON Необязательный Дополнительный реквизит пользователя, тег ОФД 1084, см. выше
OperationReceiptRequisite JSON Необязательный Операционный реквизит чека, тег ОФД 1270, (ффд 1.2) см. выше
CustomerInfo Строка Необязательный Покупатель, наименование организации или фамилия, имя, отчество (при наличии), серия и номер паспорта покупателя (клиента), тег ОФД 1227
CustomerInn Строка Необязательный ИНН покупателя, тег ОФД 1228
CustomerBirthday Строка Необязательный Дата рождения покупателя (клиента), тег ОФД 1243 (ффд 1.2)
CustomerStateCode Строка Необязательный Гражданство, тег ОФД 1244 (ффд 1.2)
CustomerDocType Строка Необязательный Код вида документа, удостоверяющего личность, тег ОФД 1245 (ффд 1.2)
CustomerDoc Строка Необязательный Данные документа, удостоверяющего личность, тег ОФД 1246 (ффд 1.2)
CustomerPlace Строка Необязательный Адрес покупателя (клиента), тег ОФД 1254 (ффд 1.2)
CustomerContactAddress Строка Необязательный Email или телефон покупателя, тег ОФД 1008
CashierName Строка Необязательный Имя кассира
CashierInn Строка Необязательный ИНН кассира
PaymentPlace Строка Необязательный Место использования ККТ (сайт)
PaymentAddress Строка Необязательный Адрес использования ККТ
CorrectionType Строка Необязательный Тип коррекции, см. ниже
AdditionalReceiptRequisite Строка Необязательный Дополнительный реквизит чека (тег 1192)

CauseCorrection

Основание для коррекции

Параметр Формат Применение Описание
CorrectionDate Строка Обязательный Дата документа основания для коррекции
CorrectionNumber Строка Обязательный Номер документа основания для коррекции

VatRate

Код Ставка НДС
1 20
2 10
3 20/120
4 10/110
5 0
6 Без НДС

CorrectionType

Код Тип коррекции
0 Самостоятельно
1 По предписанию

CorrectionReceiptType

Код Признак расчета коррекции
1 Корректировка прихода
2 Возврат прихода
3 Корректировка расхода
4 Возврат расхода

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

{
  "correctionReceiptData": {
    "organizationInn": "7708806062",
    "cashierName": "Сист. администратор",
    "cashierInn": "7708806062",
    "deviceNumber": "01801810008669",
    "paymentPlace": "test_place.com",
    "paymentAddress": "117342, Москва, ул. Бутлерова, 17Б",
    "vatRate": 1,
    "taxationSystem": 1,
    "correctionType": 1,
    "correctionReceiptType": 1,
    "causeCorrection": {
      "correctionDate": "2021-07-27",
      "correctionNumber": "б//н"
    },
    "amounts": {
      "electronic": 150,
      "cash": 0,
      "advancePayment": 0,
      "credit": 0,
      "provision": 0
    }
  }
}

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

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

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

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

Параметр Формат Применение Описание
Id Строка Обязательный Идентификатор чека

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

{ "Id": "4c335bb5ee56455f916db6e95c0d196e" }

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

{
   "Model": "Processed",
   "InnerResult": null,
   "Success": true,
   "Message": null
}

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

{
   "Model": "Error",
   "InnerResult": null,
   "Success": true,
   "Message": "Описание ошибки"
}

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

{
   "Model": "Queued",
   "InnerResult": null,
   "Success": true,
   "Message": null
}

Пример ответ (чек в очереди, но не может быть пробит по указанной причине):

{
    "Model": "Queued",
    "InnerResult": null,
    "Warnings": [
        {
            "Code": 1,
            "Description": "Есть касса (кассы) с неотправляющимися в ОФД документами"
        }
    ],
    "Success": true,
    "Message": null
}

Описание кодов из блока Warnings:

Код Описание
1 Есть касса (кассы) с неотправляющимися в ОФД документами
2 Есть касса (кассы) с заполненным ФН

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

{
   "Model": "NotFound",
   "InnerResult": null,
   "Success": true,
   "Message": null
}

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

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

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

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

{
    "Id": "4c335bb5ee56455f916db6e95c0d196e" 
}

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

{
    "Model": {
        "Status": "Processed",
        "ErrorCode": null,
        "ErrorMessage": null,
        "Amounts": {
            "Electronic": 150.0,
            "Cash": 0.0,
            "AdvancePayment": 0.0,
            "Credit": 0.0,
            "Provision": 0.0,
            "Sum": 150.0
        },
        "Items": [],
        "TaxationSystem": 1,
        "CorrectionType": 1,
        "CorrectionReceiptType": 1,
        "VatRate": 1,
        "CorrectionDate": "2021-07-26T21:00:00Z",
        "CorrectionNumber": "б//н",
        "Id": "4c335bb5ee56455f916db6e95c0d196e",
        "Amount": 150.0,
        "PaymentPlace": "test_place.com",
        "PaymentAddress": "117342, Москва, ул. Бутлерова, 17Б",
        "CashierName": "Сист. администратор",
        "DeviceNumber": "01801810008669",
        "DocumentNumber": "602",
        "FiscalNumber": "9999078902009571",
        "FiscalSign": "2451182224",
        "OfdName": "ООО «ПЕТЕР-СЕРВИС Спецтехнологии»",
        "OfdInn": "7841465198",
        "OfdReceiptUrl": null,
        "OrganizationInn": "7708806062",
        "RegNumber": "0000000480013321",
        "SessionCheckNumber": "3",
        "SessionNumber": "13"
    },
    "InnerResult": null,
    "Success": true,
    "Message": null
}

Изменение состояния кассы

Метод ручного управления состоянием кассы. Касса может быть принудительно выключена (отправлена на техобслуживание) и включена (введена в эксплуатацию).

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

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

Параметр Формат Применение Описание
Inn Строка Обязательный ИНН организации или индивидуального предпринимателя — пользователя кассы
DeviceNumber Строка Обязательный Заводской номер кассы
FiscalNumber Строка Обязательный Номер фискального накопителя
OnMaintenance Булевый Обязательный Флаг, указывающий, нужно ли помещать кассу на техобслуживание

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

{
   "Inn":"7708806062",                      //ИНН
   "DeviceNumber":"00000000000000000001",   //заводской номер кассы
   "FiscalNumber":"9999078900005430",       //номер ФН
   "OnMaintenance":true          //признак техобслуживания
}

Пример ответа: статус кассы изменился:

{"Success":true,"Message":"Kkt status was changed"}

Пример ответа: касса уже включена:

{"Success":true,"Message":"Kkm is already turned on"}

Пример ответа: касса уже на обслуживании:

{"Success":true,"Message":"Kkm is already on maintenance"}

Пример ответа: не удается установить онлайн статус, т.к. у kkm есть специальный код причины технического обслуживания:

{"Success":false,"Message":"Cannot set online status, kkm has specific Maintenance reason code"}

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

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

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

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

Параметр Формат Применение Описание
DeviceNumber Строка Обязательный Заводской номер кассы
FiscalNumber Строка Обязательный Номер фискального накопителя

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

{
   "DeviceNumber": "00000000000000000001",   //заводской номер кассы
   "FiscalNumber": "9999078900005430",       //номер ФН
}

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

{
"Model": {
        "Inn": "7708806062", //ИНН
        "DeviceNumber": "01801810008669",  //Заводской номер кассы
        "RegNumber": "0000000370021655", //Регистрационный номер ККМ
        "FiscalNumber": "9999078902005454", //Номер ФН
        "Status": 1, //Статус 1-онлайн, 2-оффлайн, 3-ошибка
        "Fiscal": true, //ККМ фискализирована
        "OfdName": "ОФД Группа Элемент", //ОФД
        "SettlePlace": "117342, Москва, ул. Бутлерова, 17Б", //место нахождения (установки) ккм
        "CalculationPlace": "www.my.ru", //Место осуществления расчёта
        "KkmModelName": "MicroPay-ФАС", //Название модели кассового аппарата
        "FiscalDateEnd": "2022-02-18T00:00:00+03:00", //Дата окончания фискального накопителя
        "FirmwareVersion": "MP 087", //Версия прошивки кассы
        "IsBso": false, //Для бланков строгой отчётности
        "OfdQueueDocsCount": 0, //количество документов не отправленных в ОФД
        "FnOccupancy": 0.0, //заполненность ФН, где 1 - ФН заполнен
        "Warnings": [ //массив с предупреждениями по кассам
            {
             "Code": 2, //код предупреждения
             "Description": "Переполнение очереди отправки в ОФД", //описание предупреждения
             "ResolveAction": "Требуется продлить услуги ОФД" //инструкция для решения проблемы
            }
        ],
        "IsReceiptProcessingBlocked": true //ккт не может бить чеки
    }
    "InnerResult": null,
    "Success": true,
    "Message": null
}

Описание кодов предупреждений:

Код ошибки Описание предупреждения Инструкция для решения проблемы
1 Срок действия фискального накопителя истек Требуется замена ФН
2 Переполнение очереди отправки в ОФД Требуется продлить услуги ОФД
3 ФН заполнен Требуется замена ФН
4 Ошибка кассы Обратитесь к администратору

Предупреждения по кассам

Метод получения предупреждений по всем кассам мерчанта.

Адрес метода:
https://api.cloudpayments.ru/kkt/merchant-devices-warnings

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

Запрос без параметров.

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

{
    "Model": [
        {
            "DeviceNumber": "888888888888888", //номер ккт
            "Warnings": [] //массив предупреждений
        },
        {
            "DeviceNumber": "999999999999999", //номер ккт
            "Warnings": [ //массив предупреждений
                {
                    "Code": 2, //код предупреждения
                    "Description": "Переполнение очереди отправки в ОФД", //описание предупреждения
                    "ResolveAction": "Требуется продлить услуги ОФД" //инструкция для решения проблемы
                },
                {
                    "Code": 4, //код предупреждения
                    "Description": "Ошибка кассы", //описание предупреждения
                    "ResolveAction": "Обратитесь к администратору" //инструкция для решения проблемы
                }
            ]
        }
    ],
    "InnerResult": null,
    "Success": true,
    "Message": null
} 

Пример ответа: нет предупреждений:

{
    "DeviceNumber": "888888888888888", //номер ккт
    "Warnings": [] //массив пустой, значит предупреждений по кассе нет
}

Описание кодов предупреждений:

Код ошибки Описание предупреждения Инструкция для решения проблемы
1 Срок действия фискального накопителя истек Требуется замена ФН
2 Переполнение очереди отправки в ОФД Требуется продлить услуги ОФД
3 ФН заполнен Требуется замена ФН
4 Ошибка кассы Обратитесь к администратору

Уведомления

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

Receipt

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

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

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

Параметр Формат Применение Описание
Id Строка Обязательный Уникальный идентификатор чека
DocumentNumber Целое число Обязательный Номер чека
SessionNumber Целое число Обязательный Номер смены
Number Целое число Обязательный Номер чека в смене
FiscalSign Строка Обязательный Фискальный признак документа
DeviceNumber Целое число Обязательный Заводской номер ККТ
RegNumber Строка Обязательный Регистрационный номер ККТ
FiscalNumber Строка Обязательный Номер фискального накопителя
Inn Число Обязательный ИНН
Type Строка Обязательный Признак расчета, см. справочник
Ofd Строка Обязательный Наименование оператора фискальных данных
Url Строка Обязательный URL адрес с копией чека
QrCodeUrl Строка Обязательный URL адрес с QR кодом для проверки чека в ФНС
TransactionId Long Необязательный Идентификатор транзакции
Amount Число Обязательный Сумма чека
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время выдачи чека во временной зоне UTC
InvoiceId Строка Необязательный Номер заказа
AccountId Строка Необязательный Идентификатор пользователя
Receipt JSON Обязательный Состав чека
CalculationPlace Строка Необязательный Место осуществления расчетов
CashierName Строка Необязательный Имя кассира
SettlePlace Строка Необязательный место нахождения (установки) ккм

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

{"code":0}

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

Код Значение
0 Чек зарегистрирован

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

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

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

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

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

Адреса, с которых система отправляет уведомления — 185.98.81.0/28, 87.251.91.160/27, 46.46.175.96/27, 46.46.168.160/27, 162.55.174.97/32 и 91.216.178.243/32.

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

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




Справочники

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

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

Код Название
HST (UTC-10:00) Гавайи
AKST (UTC-09:00) Аляска
PST (UTC-08:00) Тихоокеанское время (США и Канада)
MST (UTC-07:00) Горное время (США и Канада)
CST (UTC-06:00) Центральное время (США и Канада)
EST (UTC-05:00) Восточное время (США и Канада)
AST (UTC-04:00) Атлантическое время (Канада)
BRT (UTC-03:00) Бразилия
UTC (UTC) Время в формате UTC
GMT (UTC) Дублин, Лиссабон, Лондон, Эдинбург
CET (UTC+01:00) Амстердам, Берлин, Берн, Вена, Рим, Стокгольм
CET (UTC+01:00) Белград, Братислава, Будапешт, Любляна, Прага
CET (UTC+01:00) Брюссель, Копенгаген, Мадрид, Париж
CET (UTC+01:00) Варшава, Загреб, Сараево, Скопье
EET (UTC+02:00) Афины, Бухарест
EET (UTC+02:00) Вильнюс, Киев, Рига, София, Таллин, Хельсинки
EET (UTC+02:00) Восточная Европа
EET (UTC+02:00) Калининград (RTZ 1)
MSK (UTC+03:00) Волгоград, Москва, Санкт-Петербург (RTZ 2)
MSK (UTC+03:00) Минск
AZT (UTC+04:00) Баку
AMT (UTC+04:00) Ереван
SAMT (UTC+04:00) Ижевск, Самара (RTZ 3)
GET (UTC+04:00) Тбилиси
TJT (UTC+05:00) Ашхабад, Ташкент
YEKT (UTC+05:00) Екатеринбург (RTZ 4)
ALMT (UTC+06:00) Астана, Алматы
NOVT (UTC+06:00) Новосибирск (RTZ 5)
KRAT (UTC+07:00) Красноярск (RTZ 6)
HKT (UTC+08:00) Гонконг, Пекин, Урумчи, Чунцин
IRKT (UTC+08:00) Иркутск (RTZ 7)
SGT (UTC+08:00) Куала-Лумпур, Сингапур
ULAT (UTC+08:00) Улан-Батор
YAKT (UTC+09:00) Якутск (RTZ 8)
VLAT (UTC+10:00) Владивосток, Магадан (RTZ 9)
SAKT (UTC+11:00) Чокурдах (RTZ 10)
ANAT (UTC+12:00) Анадырь, Петропавловск-Камчатский (RTZ 11)

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

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

Код Название
Receipt Receipt

Коды ошибок

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

Код Описание
-1 Неизвестная ошибка
2 Отсутствует ККТ для фискализации транзакции для данной организации
3 Переданная система налогообложения не установлена ни в одной кассе для данной организации
4 Переданы не все необходимые данные агента
5 Отсутствует ИНН поставщика или телефон поставщика при агентском расчете
6 Оформление услуг не разрешено при регистрации ККТ или телефон покупателя передан в неверном формате
7 Неверный формат ИНН поставщика
8 Ресурс хранения документов исчерпан (ФН переполнен)
9 Ошибка агентских данных
10 Не зашифрованные персональные данные
11 Не передан ИНН
12 Отсутствует информация о товарах/услугах
13 Сумма по всем способам оплаты меньше итога чека
14 Вносимая безналичной оплатой сумма больше суммы чека
15 Нет подходящей ККМ для данной организации
16 Нет касс с подходящим терминалом
17 Нет касс с признаком БСО
18 Нет касс без признака БСО
19 Нет касс поддерживающих наличный рассчет
20 Нет касс с агентским признаком
21 Нет касс с поддержкой тега - Дополнительный реквизит пользователя
22 Превышен лимит тестовых чеков за день
23 Неверный формат цены/суммы - не более двух знаков после точки
24 Неверный формат email
25 Нет оплаченных ККМ для обработки чека
26 Не переданы необходимые данные
27 Некорректные данные

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

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

Код Описание
1 Ошибка криптопроцессора
2 Срок действия фискального накопителя истек
3 Переполнение очереди отправки в ОФД
4 Буфер ФН переполнен
5 Ошибка кассы

Общая информация о закрывающих документах:

  1. Все закрывающие документы, согласно действующему законодательству РФ, выставляются на ежемесячной основе. Мы предоставляем документы по форме УПД и датируем их последним числом месяца, в котором были оказаны услуги.
  2. Сканы закрывающих документов за текущий месяц становятся доступны для просмотра в Личном кабинете не позднее 5-го рабочего дня следующего месяца.
  3. Мы можем отправлять оригиналы закрывающих документов и актов сверки посредством ЭДО.
  4. Партнёрам, с которыми у нас настроен ЭДО, мы автоматически отправляем посредством ЭДО оригиналы закрывающих документов за прошедший месяц не позднее 5-го рабочего дня следующего месяца.
  5. Любые открытые вопросы к нам про закрывающие документы / акты сверки можно адресовать на адрес accounting@cloudpayments.ru c указанием
    • наименования и ИНН Вашей организации,
    • периода (за который нужны документы/ информация)
    • с пометкой «Клаудкассир».

FAQ

Как получить оригиналы закрывающих документов?

Способ 1 – посредством ЭДО

1. Вы уже работаете с ЭДО

1.1. Если Вы уже получали от нас закрывающие документы по ЭДО:

1.2. Если ранее Вы не получали от нас закрывающие документы по ЭДО

2. Вы планируете начать работу с ЭДО

Способ 2 – на бумаге по почте

Как я могу получить акт сверки состояния расчётов?

Напишите нам письмо на адрес accounting@cloudpayments.ru

На какую сумму выставляется закрывающий документ в случае, если услуга оказывалась не полный календарный месяц (первый/ последний месяц сотрудничества)?

Документ выставляется на сумму, равную стоимости услуг за полный календарный месяц (см. п. 5.5 и 5.6 Договора (оферты) об информационно-технологическом взаимодействии с целью обработки фискальных данных оферты).

Почему сумма закрывающих документов не соответствует сумме моей оплаты?

В первый месяц оказания услуг (месяц, в котором фискализирована касса) закрывающие документы предоставляются на
* резерв кассы на 1 год,
* фискальный накопитель,
* аренду кассы за первый месяц действия пакета.
Остаток аванса будет на ежемесячной основе закрываться УПД на аренду кассы в течение всех оставшихся месяцев действия пакета.

Пример:

Я оплатил 12.05.2021 пакет на сумму 48 990р. одним платежом, включающим:
* резерв кассы на 1 год (01.05.2021 – 30.04.2022) на сумму 6 000р.,
* фискальный накопитель на 3 года на сумму 12 990р.,
* аренду кассы на 1 год (01.05.2021 – 30.04.2021) на сумму 30 000р.
Допустим, касса была фискализирована в мае 2021, тогда первый месяц оказания услуг – это май 2021 года. За май 2021 года будут выставлены УПД на резерв кассы (6 000р.), фискальный накопитель (12 990р.) и аренду кассы за май 2021 (2 500р.) на общую сумму 21 490р. За июнь 2021 и последующие 10 месяцев (по апрель 2022 включительно) будут выставлены УПД на сумму 2 500р. каждый на аренду кассы за соответствующий месяц.

Как узнать информацию про состав счёта, который я получил от ООО «Клаудкассир»?

Этот вопрос нужно адресовать менеджеру, ведущему Ваш пакет (бухгалтерия ООО «Клаудкассир» не владеет информацией о выставляемых партнёрам счетах).

Я ошибочно сделал оплату в адрес ООО «Клаудкассир», как я могу вернуть свои деньги?

Напишите заявление на возврат, воспользовавшись прилагаемым шаблоном, и направьте его на адрес accounting@cloudpayments.ru. Деньги будут возвращены в течение 3 рабочих дней с даты подтверждения возврата со стороны нашей бухгалтерии.

За меня заплатила другая организация / ИП – как сделать зачёт оплаты третьего лица в счёт моего договора?

Напишите заявление на зачёт, воспользовавшись прилагаемым шаблоном, и направьте его на адрес kassa@cloudkassir.ru

Как досрочно расторгнуть договор с ООО «Клаудкассир» и вернуть оставшиеся на балансе деньги?

  1. Напишите заявление на расторжение договора, воспользовавшись прилагаемым шаблоном, и направьте его на адрес kassa@cloudkassir.ru.
  2. Дождитесь получения от нашей бухгалтерии информации об остатке денежных средств на Вашем балансе на последнее число месяца, в котором будет расторгнут договор, вместе с закрывающими документами за последний месяц действия договора и акта сверки на последний день месяца действия договора,
  3. Подпишите со своей стороны и направьте нам наши экземпляры всех закрывающих документов, выставленных в Ваш адрес за весь период нашего сотрудничества, а также акта сверки на последний день месяца действия договора, если они не были ранее возвращены нам,
  4. Пришлите нам на адрес accounting@cloudpayments.ru заявление на возврат денежных средств, воспользовавшись прилагаемым шаблоном.

Деньги будут возвращены в течение 3 рабочих дней с даты подтверждения возврата со стороны нашей бухгалтерии (после того, как будут выполнены все условия, указанные в пп. 1 – 4 выше).

В моих закрывающих документах допущена ошибка (в адресе / наименовании) либо я подозреваю, что мне выставили закрывающий документ с неверной суммой?

Напишите нам запрос на адрес accounting@cloudpayments.ru. Мы разберёмся в ситуации и исправим ошибку, если мы её действительно допустили. В случае необходимости корректировки суммы исходного документа, корректирующий документ будет составлен текущей датой.