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

Версия 3.4.3 от 17.09.2024

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

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

ФЗ-54

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

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

• Необходимо использовать кассу нового образца с установленным фискальным накопителем (ФН).
• Необходимо заключить договор с оператором фискальных данных (ОФД) для передачи данных с ККТ в режиме онлайн в ФНС.
• Необходимо указывать в чеке все товарные позиции: наименование, цена, кол-во, сумма, ставка НДС.
• Необходимо подключить кассу к интернету.
• Необходимо выдавать чек покупателю непосредственно в момент расчета: для интернет-платежей с использованием банковской карты отправлять чек на e-mail или телефон.
• Необходимо менять ФН в двух случаях:
  
  • по истечении его срока действия;
    
  • при заполнении памяти до истечения срока действия;
    и хранить его в течение 5-ти лет.
    
• Нет необходимости заключать договор с ЦТО на обслуживание.
• Нет необходимости предъявлять кассу инспектору ФНС, все регистрационные действия можно выполнить дистанционно в личном кабинете налогоплательщика на сайте ФНС.

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

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

Стоимость

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

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

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

• Подключиться к сервису онлайн-фискализации CloudKassir.
• Получить квалифицированную электронную подпись для работы с сайтом ФНС.
• Зарегистрироваться в личном кабинете налоговой службы: — для юридических лиц — для индивидуальных предпринимателей
• Заключить договор на онлайн-фискализацию с CloudKassir.

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

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

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

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

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

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

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

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

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

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

После создания нового сайта в личном кабинете (ЛК) CloudPayments, сайт будет находиться в тестовом режиме работы. В этом режиме все платежи и операции проходят в режиме эмуляции, и формируются тестовые чеки. Тестовые чеки создаются на демонстрационной контрольно-кассовой технике (ККТ) с отладочным фискальным накопителем, что позволяет вам проверить корректность работы системы без реальных финансовых операций.

Основные моменты

1. Тестовые чеки, включая обычные и коррекционные, пробиваются на кассах, зарегистрированных на ООО “CloudPayments”.
2. При просмотре тестовых чеков на сайтах операторов фискальных данных (ОФД), в данных чека будет фигурировать ООО “CloudPayments”.
3. Существует ограничение на количество пробиваемых тестовых чеков в сутки. Вы можете пробить до 100 чеков за 8 часов.
4. Для выдачи тестовой кассы при создании нового тестового сайта необходимо обратиться к своему менеджеру.

Для проверки работы онлайн-кассы в тестовом режиме, вы можете передать данные для онлайн-чека при оплате. Следуя этой инструкции, вы сможете убедиться, что ваша онлайн-касса функционирует корректно и готова к реальным операциям.

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":"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

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

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

Type

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

CustomerReceipt

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

Items

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

Vat

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

Method

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

Object

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

AgentData

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

PurveyorData

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

ProductCodeData

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

MarkPartQuantity

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

UnitCode

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

TaxationSystem

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

AgentSign

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

Amounts

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

UserRequisiteData

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

OperationReceiptRequisite

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

IndustryRequisiteCollection

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

Пример запроса формирования чека, ФФД 1.2

{
  "inn": "7708806062", //ИНН
  "invoiceId": "invoiceId", //номер заказа, необязательный
  "accountId": "accountId", //идентификатор пользователя, необязательный
  "Type": 0, //признак расчета
  "customerReceipt": { //состав чека
    "email": "email@email.ru", //тег-1008 e-mail покупателя, если нужно отправить письмо с чеком
    "phone": "+79999999999", //тег-1008 телефон покупателя в любом формате, если нужно отправить сообщение со ссылкой на чек
    "calculationPlace": "от 1 до 256", //тег-1187 место осуществления расчёта
    "items": [ //товарные позициии 
      {
        "label": "от 1 до 124", //тег-1030 наименование товара или услуги
        "price": 100, //тег-1079 цена
        "quantity": 1, //тег-1023 количество
        "amount": 100, //тег-1043 сумма
        "vat": 0, //тег-1199 ставка НДС
        "method": 0, // тег-1214 признак способа расчета - признак способа расчета
        "object": 0, // тег-1212 признак предмета расчета - признак предмета товара, работы, услуги, платежа, выплаты, иного предмета расчета
        "unitCode": 0, // тег-2108 мера количества предмета расчета (ФФД 1.2)
        "agentSign": 0, //тег-1222 признак агента по предмету расчета
        "agentData": { //тег-1223 данные агента
          "agentOperationName": "agentOperationName", //тег-1044 наименование операции банковского платежного агента или банковского платежного субагента
          "paymentAgentPhone": "+79999999999", //тег-1073 телефон платежного агента
          "paymentReceiverOperatorPhone": "+79999999999", //тег-1074 телефон оператора по приему платежей
          "transferOperatorPhone": "+79999999999", //тег-1075 телефон оператора перевода
          "transferOperatorName": "transferOperatorName", //тег-1026 наименование оператора перевода, тег ОФД 1026
          "transferOperatorAddress": "transferOperatorAddress", //тег-1005 адрес оператора перевода
          "transferOperatorInn": "1234567890" //тег-1016 ИНН оператора перевода
        },
        "purveyorData": { //тег-1224 данные поставщика платежного агента 
          "phone": "+79999999999", //тег-1171 телефон поставщика
          "name": "name", //тег-1225 наименование поставщика
          "inn": "1234567890" //тег-1226 ИНН поставщика
        },
        "excise": 100, //тег-1229 сумма акциза
        "countryOriginCode": "156", //тег-1230 цифровой код страны происхождения товара в соответствии с Общероссийским классификатором стран мира, 3 символа 
        "customsDeclarationNumber": "10714040/140917/0090376", // тег-1231 регистрационный номер таможенной декларации, 32 символа
        "additionalPositionInfo": "additionalPositionInfo", //дополнительная информация внутри конкретной позиции чека
        "saleObjectData": "1 до 64", //тег-1191 дополнительный реквизит предмета расчета
        "industryRequisiteCollection": [ //тег-1260 отраслевой реквизит предмета расчета
          {
            "code": "020", //тег-1262 идентификатор ФОИВ
            "documentDate": "2018-12-14T00:00:00", //тег-1263 дата документа основания
            "documentNumber": "1556", //тег-1264 номер документа основания
            "requisiteValue": "tm=mdlp&sid=00000000128602&dn=&dd=&ps=" //тег-1265 значение отраслевого реквизита
          }
        ],
        "markPartQuantity": { //тег-1291 дробное количество маркированного товара
          "numerator": 2, //тег-1293 числитель
          "denominator": 4 //тег-1294 знаменатель
        },
        "rawMarkCode": "010462930887704421DzkcYt2\u001d8005177000\u001d93dGVz" //тег-2000 код маркировки
      }
    ],
    "taxationSystem": 0, //тег-1055 система налогообложения; необязательный, если у вас одна система налогообложения
    "amounts": { //общая сумма платежа или возврата
      "electronic": 60, //тег-1081 сумма оплаты электронными деньгами
      "cash": 10, //тег-1031 сумма оплаты наличными
      "advancePayment": 10, //тег-1215 сумма из предоплаты (зачетом аванса) (2 знака после запятой)
      "credit": 10, //тег-1216 сумма постоплатой (в кредит) (2 знака после запятой)
      "provision": 10 //тег-1217 сумма оплаты встречным предоставлением (сертификаты, др. мат.ценности) (2 знака после запятой)
    }, 
    "isBso": false, //чек является бланком строгой отчётности
    "customerInfo": "customerInfo", //тег-1227 Покупатель наименование организации или фамилия, имя, отчество (при наличии), серия и номер паспорта покупателя (клиента)
    "customerInn": "123456789012", //тег-1228 ИНН покупателя 
    "customerBirthday": "2025-02-26T12:26:45.020Z", //тег-1243 дата рождения покупателя (клиента)
    "customerStateCode": "RUS", //тег-1244 гражданство
    "customerDocType": "21", //тег-1245 код вида документа, удостоверяющего личность
    "customerDoc": "customerDoc", //тег-1246 данные документа, удостоверяющего личность
    "customerPlace": "customerPlace", //тег-1254 адрес покупателя (клиента)
    "cashierName": "CashierName", //тег-1021 имя кассира
    "cashierInn": "123456789012", //тег-1203 ИНН кассира
    "additionalReceiptInfos": [ //дополнительная информация общая для чека, многострочная
      "additionalReceiptInfos"
    ],
    "userRequisiteData": { //тег-1084 дополнительный реквизит пользователя
      "requisiteKey": "1 до 64", //тег-1085 наименование дополнительного реквизита пользователя
      "requisiteValue": "1 до 256" //тег-1086 значение дополнительного реквизита пользователя
    },
    "additionalReceiptRequisite": "1 до 16", //тег-1192 дополнительный реквизит чека
    "operationReceiptRequisite": { //тег-1270 операционный реквизит чека
      "operationIdentifier": 0, //тег-1271 идентификатор операции
      "operationDate": "2025-02-26T12:26:45.020Z", //тег-1273 дата, время операции
      "operationData": "1 до 64" //тег-1272 данные операции
    }
  }
}

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

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

{
    "Success": true,
    "Message": "Queued",
    "Warning": null,
    "WarningCodes": null,
    "Model": {
        "Id": "17b6899c89af4486b954ba584af8c4ae",
        "ErrorCode": 0,
        "ReceiptLocalUrl": "https://receipts.ru/17b6899c89af4486b954ba584af8c4ae"
    }
}

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

{
    "Model": {
        "Id": "4c335bb5ee56455f916db6e95c0d196e",
        "ErrorCode": 0,
        "ReceiptLocalUrl": "https://receipts.ru/17b6899c89af4486b954ba584af8c4ae"
    },
    "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": "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:

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

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

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

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

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

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

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

{ "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": "7708806062",
    "MarkCode": "010460043993125621JgXJ5.T\u001d8005112000\u001d930001\u001d923zbrLA==\u001d24014276281" 
}

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

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

{
    "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/validate-mark-codes

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

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

{
  "Inn": "7708806062",
  "MarkCodes": [
    "010462930887704421DzkcYt2\u001d8005177000\u001d93dGVz", // ОК
    "0104670540176099215NNcM\u001d93dGVz", // выведен из оборота
  ]
}

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

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

{
  "Success": true, // Флаг успешности запроса в ГИС МТ (получен ли ответ от ГИС МТ)
  "Message": null, // Причина неуспешного запроса в ГИС МТ
  "Results": [
        {
            "MarkCode":"010462930887704421DzkcYt2800517700093dGVz",
            "IsValid": true,
            "Message": null,
            "IndustryRequisite": {
                "Code": "030",
                "DocumentDate": "2023-11-21T00:00:00",
                "DocumentNumber": "1944",
                "RequisiteValue": "UUID=d3e758f9-246e-41a0-ad15-8e95a8a61b61&Time=1732706841407"
            }
        },
        {
            "MarkCode":"0104670540176099215NNcM93dGVz",
            "IsValid": false,
            "Message": "КМ выведен из оборота",
            "IndustryRequisite": null
        }
    ]
}

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

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

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

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

CorrectionReceiptData

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

CauseCorrection

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

VatRate

CorrectionType

CorrectionReceiptType

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

{
    "correctionReceiptData": {
        "cashierName": "Сист. Администратор",
        "organizationInn": "7708806062",
        "paymentPlace": "paymentPlace",
        "customerContactAddress": "+79000000000",
        "paymentAddress": "site.com",
        "taxationSystem": "0",
        "correctionType": 0,
        "correctionReceiptType": 2,
        "isBso": true,
        "causeCorrection": {
            "correctionNumber": null,
            "correctionDate": "2024-12-31"
        },
        "items": [
            {
                "label": "Пример товара 1",
                "quantity": 1,
                "price": 100,
                "amount": 100,
                "vat": 20,
                "object": 1,
                "method": 4
            }
        ],
        "amounts": {
            "electronic": 100,
            "cash": 0,
            "advancePayment": 0,
            "credit": 0,
            "provision": 0
        }
    }
}

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

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

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

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

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

{ "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:

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

{
   "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":"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": "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
}

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

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

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

Адрес метода:
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": [] //массив пустой, значит предупреждений по кассе нет
}

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

Уведомления

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

Receipt

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

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

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

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

{"code":0}

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

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

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

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

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

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

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

Адреса, с которых система отправляет уведомления — 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.

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

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

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

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

Справочники

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

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

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

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

Коды ошибок

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

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

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

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

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

FAQ

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

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

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

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

• дождитесь 6-го рабочего дня месяца и проверьте в Вашей системе ЭДО поступление от нас закрывающего документа за прошлый месяц.
  
• если Вы не получили от нас документы по ЭДО, напишите нам запрос на accounting@cloudpayments.ru
  

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

• если у Вас есть такая возможность, пришлите нам приглашение на ЭДО/сделайте настройку роуминга через Вашего оператора ЭДО (мы работаем через Контур.Диадок, наш идентификатор участника ЭДО - 2BM-7725364512-772501001-201706290838186103839)
  
• обязательно напишите нам запрос на accounting@cloudpayments.ru с указанием наименования Вашего оператора ЭДО (по возможности дополнительно уточните Ваш номер идентификатора участника ЭДО) и дождитесь ответа от нашего бухгалтера.
  
• после настройки ЭДО мы вышлем Вам закрывающие документы посредством ЭДО
  

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

• Подключите этот сервис через любого оператора ЭДО (для ускорения работы с нами рекомендуем выбрать Контур.Диадок).
• Следуйте инструкции из п. 1.2 выше.

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

• напишите нам не ранее 6-го рабочего дня месяца, следующего за месяцем оказания услуг, письмо на accounting@cloudpayments.ru с просьбой предоставить оригиналы закрывающих документов на бумаге и с указанием Вашего полного почтового адреса.
• дождитесь получения от нас оригиналов бумажных документов, верните нам наши экземпляры закрывающих документов на адрес 115162, Москва, ул. Шухова, д.14, стр.11, помещение 309.
• повторяйте эту процедуру ежемесячно в течение всего периода действия договорных отношений.
• в случае досрочного расторжения договорных отношений для возврата остатка Вашего аванса будьте готовы оперативно предоставить нам в оригиналах все недостающие у нас экземпляры бумажных документов за весь период нашего сотрудничества.

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

Напишите нам письмо на адрес 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. Мы разберёмся в ситуации и исправим ошибку, если мы её действительно допустили. В случае необходимости корректировки суммы исходного документа, корректирующий документ будет составлен текущей датой.