Сводка изменений
Версия 3.1.2 от 05.02.2021
В этом разделе отражены изменения документа, внесенные с 18.11.2020 года.
| Номер версии | Раздел | Описание | Дата изменения |
|---|---|---|---|
| 3.1.0 | API Кассы CustomerReceipt | Добавлен параметр CashierName в метод формирования кассового чека | 2020-11-18 |
| 3.1.1 | Справочники Коды ошибок | Добавлены коды ошибок при формировании онлайн чека | 2020-11-18 |
| 3.1.2 | API Кассы Запрос статуса чека | Добавлены примеры ответов на запрос статуса чека и добавлены параметры формирования чека/состав чека: AdditionalReceiptInfos и AdditionalPositionInfo | 2021-02-05 |
Онлайн-касса для интернет-расчетов
ФЗ-54
Закон 54-ФЗ "О применении контрольно-кассовой техники" с изменениями от 03.07.2016 предписывает интернет-сервисам при осуществлении расчетов с использованием электронного средства платежа (в т.ч. банковской картой) использовать контрольно-кассовую технику (ККТ) и отправлять покупателю электронный чек в момент расчета.
Основные положения закона
- Необходимо использовать кассу нового образца с установленным фискальным накопителем (ФН).
- Необходимо заключить договор с оператором фискальных данных (ОФД) для передачи данных с ККТ в режиме онлайн в ФНС.
- Необходимо указывать в чеке все товарные позиции: наименование, цена, кол-во, сумма, ставка НДС.
- Необходимо подключить кассу к интернету.
- Необходимо выдавать чек покупателю непосредственно в момент расчета: для интернет-платежей с использованием банковской карты отправлять чек на e-mail или телефон.
- Необходимо менять ФН в двух случаях:
- по истечении его срока действия;
- при заполнении памяти до истечения срока действия;
и хранить его в течение 5-ти лет.
- по истечении его срока действия;
- Нет необходимости заключать договор с ЦТО на обслуживание.
- Нет необходимости предъявлять кассу инспектору ФНС, все регистрационные действия можно выполнить дистанционно в личном кабинете налогоплательщика на сайте ФНС.
Онлайн-касса
Мы используем кассы "MicroPay-ФАС" и "MicroPay-ФС" с подключением к любому оператору фискальных данных.
Стоимость
Стоимость услуг по онлайн-фискализации и сопровождению можно узнать на сайте CloudKassir и/или уточнить у менеджера.
Порядок подключения
Для подключения услуги онлайн-фискализации необходимо:
- Подключиться к сервису онлайн-фискализации CloudKassir.
- Получить квалифицированную электронную подпись для работы с сайтом ФНС.
- Зарегистрироваться в личном кабинете налоговой службы: — для юридических лиц — для индивидуальных предпринимателей
- Заключить договор на онлайн-фискализацию с CloudKassir.
После подписания договора и оплаты счета вам будут предоставлены номер ККТ и ФН для регистрации в ФНС.
Операторы фискальных данных
В таблице ниже представлены операторы фискальных данных, с которыми могут работать интернет-кассы.
| Код | Название оператора |
|---|---|
| PeterService | ООО «ПС СТ» |
| FirstOfd | Первый ОФД |
| Taxcom | Такском |
| PlatformaOfd | Платформа ОФД |
| OfdYa | ОФД-Я |
| OfdYandex | Яндекс ОФД |
| Garantexpress | Гарант ОФД |
| OfdAstralNalog | Астрал ОФД |
| Sbis | Компания "ТЕНЗОР", ООО |
Условия успешного создания чека
- в чеке есть хотя бы одна позиция;
- во всех позициях указано наименование;
- цена и сумма позиции не отрицательная;
- общая сумма всех позиций больше нуля;
- входная строка наименования товара длиной не более 128 символов, более длинные строки будут обрезаны;
- указанная система налогообложения должна совпадать с одним из вариантов, зарегистрированных в ККТ;
- числовые значения переданы с точностью не более двух знаков после запятой;
- передан ИНН, если он требуется в документации.
Отправка покупателю онлайн-чека
На выбор покупателя кассовый чек необходимо отправить в письме на 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":"899999999", //Телефон магазина
"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 | Строка | Необязательный | Место осуществления расчёта |
| Строка | Необязательный | E-mail покупателя для отправки чека | |
| Phone | Строка | Необязательный | Телефон покупателя в формате без скобок и дефисов для отправки ссылки на чек |
| CustomerInfo | Строка | Необязательный | Покупатель, наименование организации или фамилия, имя, отчество (при наличии), серия и номер паспорта покупателя (клиента), тег ОФД 1227 |
| CustomerInn | Строка | Необязательный | ИНН покупателя, тег ОФД 1228 |
| isBso | Булевый | Необязательный | true, если чек является бланком строгой отчётности |
| AgentSign | Строка | Необязательный | Признак агента, тег ОФД 1057, см. ниже |
| CashierName | Строка | Необязательный | Имя кассира, если не передать будет использован "Сист. Администратор" |
| AdditionalReceiptInfos | Массив строк | Необязательный | Дополнительная информация общая для чека, многострочная |
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, см. ниже |
| ProductCodeData | JSON | Необязательный | Данные маркировки товара, тег ОФД 1162, см. ниже |
| AdditionalPositionInfo | Строка | Необязательный | Дополнительная информация внутри конкретной позиции чека |
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, Залог |
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 | Строка | Необязательный | Телефон поставщика, тег ОФД 1171 |
ProductCodeData
Данные маркировки товара.
| Параметр | Формат | Применение | Описание |
|---|---|---|---|
| CodeProductNomenclature | Строка | Необязательный | HEX представление штрих/бар кода маркировки целиком (Только для касс Микропэй) |
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 | Строка | Необязательный | Сумма встречным предоставлением |
Пример запроса
{
"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 представление штрих/бар кода маркировки целиком (Только для касс Микропэй)
}
},
{
"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 знака после запятой)
}
}
}
Формирование чека является асинхронной операцией, поэтому в ответ на запрос 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.ru/kkt/receipt/status/get
Параметры запроса:
| Параметр | Формат | Применение | Описание |
|---|---|---|---|
| Id | Строка | Обязательный | Идентификатор чека |
Пример запроса:
{ "Id": "Nr9eTaj" }
Пример ответа (чек успешно обработался):
{
"Model": "Processed",
"Success": true
}
Пример ответа (чек не пробился):
{
"Model": "Error",
"InnerResult": null,
"Success": true,
"Message": "Нет касс без признака БСО для организации с ИНН ..."
}
Пример ответ (чек в очереди):
{
"Model": "Queued",
"Success": true
}
Пример ответ (чек не найден):
{
"Model": "NotFound",
"Success": true
}
Получение данных чека
Метод получения детализации чека.
Адрес метода:
https://api.cloudpayments.ru/kkt/receipt/get
Параметры запроса:
| Параметр | Формат | Применение | Описание |
|---|---|---|---|
| Id | Строка | Обязательный | Идентификатор чека |
Пример запроса:
{ "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": "шт",
"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": "Nr9eTaj",
"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
}
Изменение состояния кассы
Метод ручного управления состоянием кассы. Касса может быть принудительно выключена (отправлена на техобслуживание) и включена (введена в эксплуатацию).
Адрес метода:
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"}
Получение данных кассы
Метод получения данных кассы.
Адрес метода:
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 //Для бланков строгой отчётности
}
"InnerResult": null,
"Success": true,
"Message": null
}
Уведомления
Уведомление — HTTP-запрос от системы к вашему сайту. Подобные запросы также называют callback или webhook.
Receipt
Выполняется после выдачи кассового чека.
Служит для информирования о сформированных онлайн-чеках: система отправляет запрос на адрес ТСП с информацией о чеке, а сайт должен зафиксировать информацию.
Параметры передаются в теле запроса, список представлен в следующей таблице:
| Параметр | Формат | Применение | Описание |
|---|---|---|---|
| Id | Строка | Обязательный | Уникальный идентификатор чека |
| DocumentNumber | Целое число | Обязательный | Номер чека |
| SessionNumber | Целое число | Обязательный | Номер смены |
| Number | Целое число | Обязательный | Номер чека в смене |
| FiscalSign | Строка | Обязательный | Фискальный признак документа |
| DeviceNumber | Целое число | Обязательный | Заводской номер ККТ |
| RegNumber | Строка | Обязательный | Регистрационный номер ККТ |
| FiscalNumber | Строка | Обязательный | Номер фискального накопителя |
| Inn | Число | Обязательный | ИНН |
| Type | Строка | Обязательный | Признак расчета, см. справочник |
| Ofd | Строка | Обязательный | Наименование оператора фискальных данных |
| Url | Строка | Обязательный | URL адрес с копией чека |
| QrCodeUrl | Строка | Обязательный | URL адрес с QR кодом для проверки чека в ФНС |
| TransactionId | Целое число | Необязательный | Идентификатор транзакции |
| 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 параметров (что может вызывать проблемы). Если вам необходимо проверять подлинность и целостность уведомлений, вы можете вычислить проверочное значение на своей стороне и сравнить с тем, что пришло в запросе. Совпадение подтверждает, что уведомление было отправлено от нас и пришло к вам в оригинальном виде.
При реализации проверки сообщения обратите внимание на следующие моменты:
- Для уведомлений, отправленных методом 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, могут не доставляться.
Справочники
Коды временных зон
В таблице ниже представлены коды временных зон для преобразования времени.
| Код | Название |
|---|---|
| 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 | Вносимая безналичной оплатой сумма больше суммы чека |