API касса

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

Интерфейс работает по адресу https://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. Оба этих значения можно получить в личном кабинете.

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


Идемпотентность 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 Массив значений Обязательный Одно или несколько значний системы налогообложения, см. справочник

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

{
   "Inn":"7708806062",                      //ИНН
   "DeviceNumber":"00000000000000000001",   //заводской номер кассы
   "FiscalNumber":"9999078900005430",       //номер ФН
   "RegNumber":"0000000004030311",          //регистрационный номер кассы
   "Url":"www.cloudpayments.ru",            //ваш адрес сайта
   "Ofd":"PeterService",                    //ОФД
   "TaxationSystem":[0],                    //системы налогообложения
}

 

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

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

 

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

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

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

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

 

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

{
	"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": "шт" //единица измерения
			}, {
				"label": "Наименование товара 3", //наименование товара
				"price": 300.00, //цена
				"quantity": 3.00, //количество
				"amount": 900.00, //сумма
				"vat": 18, //ставка НДС
                "method": 0, // тег-1214 признак способа расчета - признак способа расчета
			    "object": 0, // тег-1212 признак предмета расчета - признак предмета товара, работы, услуги, платежа, выплаты, иного предмета расчета
                "measurementUnit": "шт" //единица измерения
			}
		],
        "taxationSystem": 0, //система налогообложения; необязательный, если у вас одна система налогообложения
		"email": "user@example.com", //e-mail покупателя, если нужно отправить письмо с чеком
		"phone": "", //телефон покупателя в любом формате, если нужно отправить сообщение со ссылкой на чек
		"amounts":
	    {
		    "electronic": 9.00, // Сумма оплаты электронными деньгами
		    "advancePayment": 0.00, // Сумма из предоплаты (зачетом аванса) (2 знака после запятой)
		    "credit": 0.00, // Сумма постоплатой(в кредит) (2 знака после запятой)
		    "provision": 0.00 // Сумма оплаты встречным предоставлением (сертификаты, др. мат.ценности) (2 знака после запятой)
	    }
	}
}

 

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

{"Success":true,"Message":"Queued", Model:{Id:"M83loSk"}}

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

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

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

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

 

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

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

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

Способы расчета:

  • 0 — Unknown, неизвестный способ расчета (значение по умолчанию. в электронной форме чека не отображается )
  • 1 — FullPrepayment, Предоплата 100%
  • 2 — PartialPrepayment, Предоплата
  • 3 — AdvancePay, Аванс
  • 4 — FullPay, Полный расчёт
  • 5 — PartialPayAndCredit, Частичный расчёт и кредит
  • 6 — Credit, Передача в кредит
  • 7 — CreditPayment, Оплата кредита

Предметы расчета:

  • 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, Иной предмет расчета

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

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

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

 

Касса может быть принудительно выключена (отправлена на техобслуживание) и включена (введена в эксплуатацию). Для ручного управления состоянием кассы необходимо отправить запрос по адресу 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/receipt/status/get с передачей единственного параметра:

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

 

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

{ "Id": "Nr9eTaj" }

 

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

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

 

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

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

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

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

{ "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": "шт",
                "Code": "1322",
                "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,
                "Code": 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": 18,
                "EAN13": null,
                "AgentSign": null,
                "Method": 0,
                "Object": 0,
                "MeasurementUnit": null,
                "Code": null,
                "AgentData": null,
                "PurveyorData": null
            }
        ],
        "TaxationSystem": 2,
        "Amounts": null
    },
    "InnerResult": null,
    "Success": true,
    "Message": null
}