Онлайн-касса для интернет-расчетов
Версия 3.0 от 15.03.2019
ФЗ-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 | Обязательный | Содержимое позиций чека, см. ниже |
| TaxationSystem | Строка | Обязательный | Система налогооблажения (необязательный, если у вас одна система налогообложения), см. ниже |
| CalculationPlace | Строка | Необязательный | Место осуществления расчёта |
| Строка | Необязательный | E-mail покупателя для отправки чека | |
| Phone | Строка | Необязательный | Телефон покупателя в любом формате для отправки ссылки на чек |
| CustomerInfo | Строка | Необязательный | Покупатель наименование организации или фамилия, имя, отчество (при наличии), серия и номер паспорта покупателя (клиента), тег ОФД 1227 |
| CustomerInn | Строка | Необязательный | ИНН покупателя, тег ОФД 1228 |
| isBso | Булевый | Необязательный | true, если чек является бланком строгой отчётност |
| AgentSign | Строка | Необязательный | Признак агента, тег ОФД 1057, см. ниже |
| Amounts | JSON | Обязательный | Общая сумма платежа или возврата, см. ниже |
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, см. ниже |
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, иной предмет расчета |
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.
| Параметр | Формат | Применение | Описание |
|---|---|---|---|
| Phone | Строка | Обязательный | Телефон поставщика, тег ОФД 1171 |
| Name | Строка | Обязательный | Наименование поставщика, тег ОФД 1225 |
| Inn | Строка | Обязательный | ИНН поставщик, тег ОФД 1226 |
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"
}
Пример ответа: некорректный запрос:
{
"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
}
Получение данных чека
Метод получения детализации чека.
Адрес метода:
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", //номер ФН
}
Пример ответа:
{
"Inn":"7708806062", //ИНН
"DeviceNumber": "00000000000000000001", //заводской номер кассы
"FiscalNumber": "9999078900005430", //номер ФН
"RegNumber": "0000000004030311", //Регистрационный номер ККМ
"Status": "Online", //Статус
"Fiscal": true, //ККМ фискализирована
"OfdName": "Первый ОФД", //ОФД
"SettlePlace": "117342, Москва, ул. Бутлерова, 17Б", //место нахождения (установки) ккм
"CalculationPlace": "www.my.ru", //Место осуществления расчёта
"KkmModelName": "Терминал ФА", //Название модели кассового аппарата
"FiscalDateEnd": "2021-01-01T00:00:00.000+000", //Дата окончания фискального накопителя
"FirmwareVersion": "14.1.2", //Версия прошивки кассы
"IsBso": false, //Для бланков строгой отчётности
}
Уведомления
Уведомление — 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 | Чек зарегистрирован |
Kkt
Выполняется после перевода кассы в фискальный режим и содержит данные отчета о регистрации. Использование данного уведомления имеет смысл, если у вас десятки или сотни касс. Для остальных случаев, проще получать необходимую информацию через личный кабинет.
Параметры передаются в теле запроса, список представлен в следующей таблице:
| Параметр | Формат | Применение | Описание |
|---|---|---|---|
| Inn | Строка | Обязательный | ИНН организации или ИП — пользователя кассы |
| DeviceNumber | Строка | Обязательный | Заводской номер кассы |
| FiscalNumber | Строка | Обязательный | Номер фискального накопителя |
| RegNumber | Строка | Обязательный | Регистрационный номер кассы |
| Status | Строка | Обязательный | Текущий статус: Fiscalized |
| DocumentNumber | Строка | Обязательный | Номер фискального документа |
| FiscalSign | Строка | Обязательный | Фискальный признак документа |
| Date | Дата/время | Обязательный | Дата и время регистрации в формате yyyy-MM-dd HH:mm:ss |
В ответ на запрос система ожидает получить ответ в JSON формате с обязательным параметром code:
{"code":0}
Код определяет результат обработки сервером ТСП уведомления и может принимать единственное значение:
| Код | Значение |
|---|---|
| 0 | Статус зарегистрирован |
Принцип работы и проверка уведомлений
Параметры передаются методом POST или GET в теле запроса в формате «ключ=значение».
Все виды уведомлений — receipt и kkt содержат HTTP заголовок Content-HMAC в котором находится проверочное значение запроса, вычисленное с помощью алгоритма HMAC. Если вам необходимо проверять подлинность и целостность уведомлений, вы можете вычислить проверочное значение на своей стороне и сравнить с тем, что пришло в запросе. Совпадение подтверждает, что уведомление было отправлено от нас и пришло к вам в оригинальном виде.
При реализации проверки сообщения, обратите внимания на следующие моменты:
- Для уведомлений, отправленных методом POST, сообщением является тело запроса. Для GET — строка параметров;
- Хэш вычисляется функцией SHA256;
- В качестве ключа используется API Secret, который можно получить в личном кабинете;
- Вычисленное значение передается в кодировке base64.
Примеры вычисления HMAC на разных языках программирования.
Адреса, с которых система отправляет уведомления — это 130.193.70.192 и 185.98.85.109.
Справочники
Коды временных зон
В таблице ниже представлены коды временных зон для преобразования времени.
| Код | Название |
|---|---|
| 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 |
| Kkt | Kkt |
Коды ошибок
В таблице ниже представлены коды ошибок при формировании онлайн чека.
| Код | Описание |
|---|---|
| -1 | Неизвестная ошибка |
| 2 | Отсутсвует ККТ для фискализации транзакции для данной организации |
| 3 | Переданная система налогообложения не установлена ни в одной кассе для данной организации |
| 4 | Переданы не все необходимые данные агента |
| 5 | Отсутствует ИНН поставщика или телефон поставщика при агентском расчете |
| 6 | Оформление услуг не разрешено при регистрации ККТ или телефон покупателя передан в неверном формате |
| 7 | Неверный формат ИНН поставщика |
| 8 | Ресурс хранения документов исчерпан (ФН переполнен) |