Программный интерфейс приложений (API) для работы с ИС “Renta”

Описывается программный интерфейс приложений (API), предоставляющий возможность сторонним (клиентским) приложениям использовать данные из информационной системы (ИС) “Renta” для расчета арендной платы и сопутствующих операций. Взаимодействие клиентского приложения и API производится путем отправки приложением HTTP-запросов к серверу и получением ответов на них. Для отправки запросов и получения ответов используется протокол HTTPS.
Проблемы использования ИС “Renta”, которые не удалось решить самостоятельно, читая техническую и пользовательскую документацию, скорее всего, получится решить, позвонив в службу технической поддержки по телефону 8 (800) 550-99-11.

Кодировка, используемая в запросах и ответах – UTF-8. Запросы выполняются методом GET, параметры запроса передаются в URL.
Ответы выдаются сервером в формате JSON, и, в случае успешности ответа, согласно его заголовку (код ответа по протоколу HTTP равен 200), данные имеют следующий обобщенный вид:

{
  "Data": {
    "Prop1": "Val1",
    "Prop2": "Val2",
    ...
    "PropN": "ValN"
  },
  "Status": "Success",
  "Elapsed": "чч:мм:сс.ддддддд"
}

Здесь ключу «Data» соответствует структура, в которой вместо ключей «Prop1», «Prop2», … «PropN» и значений «Val1», «Val2», … «ValN» располагаются ключи передаваемых параметров с их значениями (см. описания параметров ниже; значениями параметров могут являться массивы и структуры); параметр «Status» – состояние обработки запроса, в данном случае имеет значение «Success» (запрос обработан успешно). Параметр «Elapsed» – время, затраченное системой на обработку запроса: от получения запроса системой до выдачи ответа. Формат времени – строка вида «чч:мм:сс.ддддддд», в которой
чч – часы,
мм – минуты,
сс – секунды,
ддддддд – доли секунды.
В случае неуспешности ответа (код ответа по протоколу HTTP не равен 200) данные имеют следующий обобщенный вид:

{
  "Errors": [
    "Ошибка 1",
    "Ошибка 2",
    ...
    "Ошибка N"
  ],
  "Status": "Failed",
  "Elapsed": "чч:мм:сс.ддддддд"
}

Здесь ключу «Errors» соответствует одномерный массив, в котором присутствуют строки с сообщениями об ошибках, возникших при обработке данных. На месте строк «Ошибка 1», «Ошибка 2», … «Ошибка N» перечислены сообщения об ошибках, возникших при обработке переданных данных. Параметр «Status» в данном случае имеет значение «Failed» (обработка запроса не удалась). Параметр «Elapsed» – так же, как и в случае успешного ответа, время, затраченное системой на обработку запроса; формат представления времени тот же.

Возможность множественных обращений к ИС “Renta” после одной авторизации без использования механизма Cookies реализуется с помощью механизма AuthToken: после авторизации с передачей имени и пароля система возвращает код авторизации – строку символов, которая используется, как параметр авторизации при обращении к соответствующему личному кабинету (ЛК). HTTP-запрос авторизации, передающий имя пользователя и пароль в формате JSON выглядит следующим образом:

--- BEGIN ---
POST https://ofd.ru/api/Authorization/CreateAuthToken HTTP/1.1
Content-Length: 38
Content-Type: application/json; charset=utf-8 {"Login": "12345","Password": "56789"}
--- END ---

В данном запросе присутствуют примеры значений: передаваемое имя пользователя – «12345» и пароль – «56789»; они задаются как значения в JSON-структуре внутри запроса с ключами «Login» и «Password» соответственно. Другой формат запроса, обрабатываемый ИС “Renta”: HTTP-запрос авторизации в формате URLEncoded:

--- BEGIN ---
POST https://ofd.ru/api/Authorization/CreateAuthToken HTTP/1.1
Content-Length: 26
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Login=12345&Password=56789
--- END ---

В ответ на данный запрос будет получен ответ по протоколу HTTP, который в случае успешной авторизации будет иметь код равный 200 и содержать структуру, подобную следующей (с примерами значений):

{
  "AuthToken": "f3accdfda7574736ba94a78d00e974f4",
  "ExpirationDateUtc": "2017-01-24T14:13:24"
}

Здесь с ключом «AuthToken» – код авторизации: строка символов AuthToken, представляет собой 32-значную последовательность шестнадцатеричных цифр, используемую для повторной аутентификации, а ключ «ExpirationDateUtc» – строка, описывающая момент времени (дату и время в формате UTC), до которого будет действовать данный код авторизации.
Момент времени задается в формате «ГГГГ-ММ-ДДTчч:мм:сс» ¹⁾; здесь
ГГГГ – год даты, 4 цифры,
ММ – месяц даты, 2 цифры,
ДД – день даты 2 цифры,
T – заглавная латинская буква “T”, используется как разделитель даты и времени,
чч – часы, 2 цифры,
мм – минуты, 2 цифры,
сс – секунды, 2 цифры.
В случае проблем с авторизацией (код ответа по протоколу HTTP будет равен 403) данные будут отсутствовать, JSON-структура будет пустой (будет иметь вид «{}»). Полученный код авторизации используется в виде дополнительного параметра в запросах получения сведений о кассовых чеках. Пример запроса с использованием кода авторизации:

POST /api/kkt/cloud/receipt?AuthToken=Code1

здесь Code1 – действующий код авторизации, полученный в результате запроса авторизации.

Запрос на получение списка чеков за период по заданной кассе или для заданного юридического лица имеет вид:

GET https://ofd.ru/api/renta/v1/inn/INN/receipts/Date1/Date2AuthToken=Code1

или

GET https://ofd.ru/api/renta/v1/kkt/KKT/receipts/Date1/Date2AuthToken=Code1

Здесь INN – ИНН юридического лица, на которого зарегистрирована касса, по данным которой генерируется отчет – строка из 10 цифр от 0 до 9; KKT – заводской (серийный) номер кассы – строка символов; Date1 и Date2 – начальная и конечная даты периода, для которого требуется найти сведения по кассовым чекам – строка символов, содержащая дату и время в формате ISO. Разность Date2 и Date1 не должна превышать 7 дней. Code1 – действующий код авторизации, полученный в результате запроса авторизации. Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON следующего вида (вид значений показан на примерах, многоточие означает многократно повторяющуюся структуру такого же вида):

{
  "Status": "Success",
  "Data": [
    {
      "Id": "3a6e3b83-a0b0-4587-bfb3-1b7539b05cf3",
      "IsCorrection": false,
      "CDateUtc": "2016-07-26T09:32:41",
      "Tag": 0,
      "IsBso": false,
      "OperationType": "Income",
      "UserInn": "7802870820",
      "KktAddress": "142000, МО, г. Домодедово, Каширское шоссе, 63",
      "SerialNumber": "44444444444443421132",
      "KktRegNumber": "111222333",
      "FnNumber": "99990789388",
      "DocDateTime": "2016-07-26T12:32:00",
      "TotalSumm": 51360,
      "CashSumm": 51360,
      "ECashSumm": 0,
      "CreditSumm": 0,
      "PrepaidSumm": 0,
      "TaxTotalSumm": 0,
      "Tax10Summ": 0,
      "Tax18Summ": 0,
      "Tax110Summ": 0,
      "Tax118Summ": 0,
      "Tax0Summ": 0,
      "TaxNaSumm": 0,
      "Depth": 3
    }
  ]
}

Список полей этой структуры c их описаниями представлен в таблице 1. Ошибки в ответе на запрос, обрабатываемые ИС:

• InnNotFound – для текущей учетной записи не найдена организация;
• KktNotFound – для текущей учетной записи не найдена касса с заданным номером;
• InvalidTimeInterval – неверно указан временной интервал;
• TimeIntervalNotPaid – временной интервал не оплачен.

Таблица 1. Поля данных записи со списком документов (чеков)

Tax0Summ | Целое число | Сумма по операциям, облагаемая НДС по ставке 0%, накопленная за смену, в копейках |

Запрос на получение полной информации по чеку лица имеет вид:

GET https://ofd.ru/api/renta/v1/receipt/Id?AuthToken=Code1

Здесь Id – это Id чека, по которому запрашивается информация. Получить Id чека возможно с помощью запроса на получение списка чеков (см. п. 3.1). Code1 – действующий код авторизации, полученный в результате запроса авторизации. Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON следующего вида (вид значений показан на примерах, многоточие означает многократно повторяющуюся структуру такого же вида):

{
  "Status": "Success",
  "Data": {
    "Id": "3a6e3b83-a0b0-4587-bfb3-1b7539b05",
    "IsCorrection": false,
    "IsBso": false,
    "OperationType": "Income",
    "UserInn": "0123456789",
    "UserName": "ООО \"Компания и КО\"",
    "KktAddress": "105064,г.Москва,ул.Московская,д.111",
    "SerialNumber": "01234560087654321",
    "kktRegNumber": "0000123456789012",
    "FnNumber": "4321000100012345",
    "Items": [
      {
        "Name": "Брюки Размер-38-34",
        "CustomName": "Брюки Размер-38-34",
        "Price": 349500,
        "Quantity": 1,
        "Total": 349500,
        "CalculationMethod": 4,
        "SubjectType": 1,
        "NDS_Rate": 1,
        "NDS_Summ": 58250
      }
    ],
    "DocDateTime": "2016-07-26T09:32:41",
    "TotalSumm": 349500,
    "CashSumm": 0,
    "ECashSumm": 349500,
    "CreditSumm": 0,
    "PrepaidSumm": 0,
    "TaxTotalSumm": 58250,
    "Tax10Summ": 0,
    "Tax18Summ": 58250
  },
}

Список полей этой структуры c их описаниями представлен в таблице 2. Ошибки в ответе на запрос, обрабатываемые ИС:

• DataNotFound – не верно указан ID чека.

Таблица 2. Поля данных записи со списком документов (чеков)

Запрос на получение списка за период по заданной кассе или для заданного юридического лица имеет вид:

GET https://ofd.ru/api/renta/v1/legal-entities

Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON следующего вида (вид значений показан на примерах, многоточие означает многократно повторяющуюся структуру такого же вида):

{
  "Status": "Success",
  "Data": [
    {
      "UserInn": "7802870820",
      "UserKpp": "780901001",
      "UserName": "ООО \"НАДЕЖДА\"",
      "KktRergistered": 20,
      "KktOnline": 14
    }
  ]
}

Список полей этой структуры c их описаниями представлен в таблице 3.

Таблица 3. Поля данных записи со списком юридических лиц

Запрос на получение списка за период по заданной кассе или для заданного юридического лица имеет вид:

GET https://ofd.ru/api/renta/v1/kkts/INN

Здесь INN — ИНН зарегистрированного юридического лица, по данным которого требуется получить список касс; данный параметр может отсутствовать, и тогда запрос будет выглядеть так:

GET https://ofd.ru/api/renta/v1/kkts

Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON следующего вида (вид значений показан на примерах, многоточие означает многократно повторяющуюся структуру такого же вида):

{
  "Status": "Success",
  "Data": [
    {
      "UserInn": "7802870820",
      "UserKpp": "780901001",
      "UserName": "ООО \"НАДЕЖДА\"",
      "KktAdress": "МО, г. Домодедово, Каширское шоссе, 68",
      "KktPlace": "Торговый зал № 2",
      "KktSerialNumber": "111222333444",
      "KktRegNumber": "111222333",
      "FnNumber": "99990789388"
    }
  ]
}

Список полей этой структуры c их описаниями представлен в таблице 4. В ответе на запрос, обрабатываемые ИС также могут быть сведения об ошибке InnNotFound – для текущей учетной записи не найдена организация с заданным ИНН.

Таблица 4. Поля данных записи со списком юридических лиц

Запрос на подключение касс к ИС «Renta» строится на основе метода POST протокола HTTP: в качестве входных параметров передается структура JSON, вид которой представлен ниже на примере. По вызову функции будет произведено одно из следующих действий:

• если ИНН заданного юридического лица соответствуют адресу электронной почты, на который зарегистрирован его ЛКК, либо адресу электронной почты доверенного лица в данном ЛКК, то происходит добавление в данный ЛКК касс из структуры данных, переданной по запросу (для этого в списке ЛКК создается новая папка с именем «Тестдрайв - n - x», где вместо “n” подставлено значение идентификатора пользователя, переданного в структуре, а вместо “x” подставлено значение текущей даты в формате ISO); кассы становятся доступными пользователю; если же кассы из переданной структуры уже были зарегистрированы в ЛКК на тот же ИНН, но были недоступны заданному пользователю, то они становятся ему доступными, при этом все данные касс сохраняются без изменений;
• если ИНН заданного юридического лица не соответствуют адресу электронной почты, на который зарегистрирован его ЛКК, либо адресу электронной почты доверенного лица в данном ЛКК, то происходит добавление в данный ЛКК пользователя с заданным адресом электронной почты в качестве доверенного лица с правами доступа только к той папке, в которой находятся кассы, добавленные по запросу; если же кассы из переданной структуры уже были зарегистрированы в ЛКК, то они становятся доступными пользователю, при этом все их данные сохраняются без изменений;
• если ИНН и КПП юридического лица отсутствует в базе данных ИС «Renta», то создается ЛКК, в котором пользователь с заданным адресом электронной почты становится ответственным лицом; в ЛКК добавляются кассы из переданного списка без создания папки и становятся доступными зарегистрированному пользователю.

Вид запроса:

POST https://ofd.ru/api/Renta/v1/addKkt/

Параметры содержатся в блоке данных в формате JSON, передаваемом по запросу в ИС. Структура блока данных (с примерами значений):

{
  "UserInn": "7802870820",
  "UserKpp": "780901001",
  "UserOgrn": "3210987654321",
  "UserEmail": "user@site.com",
  "KktList": [
    {
      "KktNumber": "111222333",
      "FnNumber": "99990789388",
      "KktRegNumber": "9999000087654321",
      "KktAddress": "МО, г. Домодедово, Каширское шоссе, 68",
      "KktPlace": "Торговый зал № 2",
      "CurrentOfdInn": "7802811111"
    },
    {
      "KktNumber": "111222444",
      "FnNumber": "99990789747",
      "KktRegNumber": "9999000012345678",
      "KktAddress": "МО, г. Домодедово, Каширское шоссе, 68",
      "KktPlace": "Торговый зал № 4",
      "CurrentOfdInn": "7802811111"
    }
  ]
}

Список полей этой структуры c их описаниями представлен в таблице 5. В ответе на запрос, обрабатываемые ИС также могут быть сведения об ошибке InnNotFound – для текущей учетной записи не найдена организация с заданным ИНН.

Таблица 5. Поля данных записи со списком юридических лиц

Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON вида, аналогичного структуре, передаваемой (вид значений показан на примерах, многоточие означает многократно повторяющуюся структуру такого же вида):

{
  "UserInn": "7802870820",
  "UserKpp": "780901001",
  "UserOgrn": "3210987654321",
  "UserEmail": "user@site.com",
  "KktList": [
    {
      "KktNumber": "111222333",
      "FnNumber": "99990789388",
      "KktRegNumber": "9999000087654321",
      "KktAddress": "МО, г. Домодедово, Каширское шоссе, 68",
      "KktPlace": "Торговый зал № 2",
      "CurrentOfdInn": "7802811111"
    },
    {
      "KktNumber": "111222444",
      "FnNumber": "99990789747",
      "KktRegNumber": "9999000012345678",
      "KktAddress": "МО, г. Домодедово, Каширское шоссе, 68",
      "KktPlace": "Торговый зал № 4",
      "CurrentOfdInn": "7802811111"
    }
  ],
  "Errors": [
    {
      "ErrorCode": "1",
      "ErrorMessage": "INN_KPP_incorrect"
    },
    {
      "ErrorCode": "5",
      "ErrorMessage": "RN_FN_incorrect"
    }
  ]
}

Список полей этой структуры c их описаниями представлен в таблице 6. В ответе на запрос, обрабатываемые ИС также могут быть сведения об ошибках, приведенные в таблице 7.

Таблица 6. Поля данных записи со списком юридических лиц

Таблица 7. Коды ошибок и сообщения об ошибках, возвращаемые

Запрос на отключение касс от ИС “Renta” строится на основе метода POST протокола HTTP; в качестве входных параметров передается следующие сведения:

• ИНН торгового центра, использующего ИС “Renta”, для работы с которой кассы используют технологию “Proxy OFD”,
• РНМ кассы, которую следует отключить,
• Дата и время отключения кассы.

Вид запроса:

POST https://ofd.ru/api/Renta/v1/removeKkt/INN/NUM/Date1

Здесь INN — ИНН торгового центра, использующего ИС “Renta”, NUM — РНМ кассы, отключаемой от ИС, Date1 — дата, когда произойдёт отключение кассы. Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON следующего вида (с примерами значений):

{
  "UserInn": "7802870820",
  "KktRegNumber": "9999000087654321",
  "KktOffDate": "2018-06-30"
}

Список полей этой структуры c их описаниями представлен в таблице 8.

Таблица 8. Поля структуры ответа на запрос на отключение касс от ИС “Renta”

Коды ошибок, возвращаемых в ответ на данный запрос перечислены в таблице 9:

Таблица 9. Коды ошибок и сообщения об ошибках, возвращаемые функцией отключения касс от ИС “Renta”

Аутентификация — установление достоверности подключения пользователя с заданным идентификатором с целью предотвращения использования данного идентификатора другими пользователями.
Баланс — сумма денег, перечисленная оператору “OFD.ru”, не израсходованная на получение услуг оператора “OFD.RU” и доступная для их оплаты. Значение баланса отображается в интерфейсе ЛКК.
Заводской номер кассы — номер, идентифицирующий определенную кассу, присвоенный ей на заводе-изготовителе после ее изготовления и контроля, перед её реализацией (продажей, передачей, и т. п.).
Идентификация — указание информационной системе, какой именно пользователь с ней взаимодействует.
Касса — аппаратно-программное средство для автоматизации кассовых операций, учета и регистрации перемещений денежных средств и материальных ценностей, генерации и печати кассовых документов; касса также может иметь (имеет) возможность передачи данных о кассовых операциях и сопутствующих им данных в налоговые органы (таких, как ФНС) посредством операторов фискальных данных (таких, как “OFD.RU”). Также кассу можно определить, как «инструмент контроля со стороны государства за налично-денежным оборотом, полнотой и своевременностью оприходования предприятиями наличной выручки» ²⁾.
Контрольно-кассовая техника — множество касс, множество разновидностей касс; здесь также данный термин может употребляться в значении «касса» (см. «Касса»).
Номер фискального накопителя — последовательность десятичных цифр, идентифицирующая определенный фискальный накопитель, присвоенная ему на заводе-изготовителе после его изготовления и контроля, перед его реализацией (продажей, передачей и т. п.).
Профиль пользователя — совокупность данных о пользователе ИС.
Рабочее поле — область окна браузера, в которой отображается текущий раздел данных, заданный закладками или пунктами меню пользователя. Имеет наибольший размер относительно других частей страницы.
Регистрационный номер кассы — последовательность символов, идентифицирующая кассу в ФНС в процессе обработки отчетных данных кассы. Присваивается в процессе регистрации кассы.
Учетная запись — совокупность данных, связанных с определенным пользователем ИС. Включает в себя также данные идентификации и аутентификации. Доступ к учетной записи может получить только пользователь, прошедший процедуру идентификации и аутентификации.
Фискальный накопитель — аппаратно-программное средство, с энергонезависимым запоминающим устройством, подключающееся к кассе и предназначенное для сбора и хранения сгенерированных кассой документов для последующей передачи для хранения в ФНС. Для возможности использования кассы фискальный накопитель должен быть обязательно установлен в кассу. После окончания периода эксплуатации фискального накопителя (см. Фискальный режим) он хранится у налогоплательщика в течение 5 лет.

БД — база данных;
ЕГРЮЛ — единый государственный реестр юридических лиц;
ИНН — идентификационный номер налогоплательщика;
ИС — информационная система;
ККТ — контрольно-кассовая техника;
ЛКК — личный кабинет клиента;
ЛКП — личный кабинет партнера;
НДС — налог на добавленную стоимость;
ОГРН — основной государственный регистрационный номер;
ОФД — оператор фискальных данных;
РН (РНМ) — регистрационный номер (в данном случае — регистрационный номер кассы);
ФД — фискальный документ;
ФН — фискальный накопитель.

Версия 1.0
Выпущена 20 февраля 2018 г.
Первая версия документа.

Версия 1.1
Выпущена 27 апреля 2018 г.

• Изменен формат данных JSON-ответа функции получения сведений о кассовых чеках за заданный период по кассе или юридическому лицу.
• Для оформления документа использован новый шаблон

Версия 1.11
Выпущена 22 мая 2018 г.
Добавлены функции «Получение сведений о юридических лицах, подключивших свои кассы к ИС “Renta”» и «Получение сведений о кассах юридических лиц, подключенных к ИС “Renta”».

Версия 1.12
Выпущена 06 июня 2018 г.
Добавлены функции «Подключение касс к услуге ИС “Renta”» и «Отключение касс от услуги ИС “Renta”».

Версия 1.13
Выпущена 21 августа 2018 г.
Исправлены ошибки в описаниях входных параметрах функций.

Версия 1.14
Выпущена 21 августа 2018 г.
Изменено название документа на «Программный интерфейс приложений (API) для работы с ИС “Renta”»

Версия 1.15
Выпущена 19 сентября 2018 г.
Добавлен входной параметр к функции подключения касс к ИС “Renta”

Версия 1.16
Выпущена 23 апреля 2019 г.
Добавлен метод получения полной информации по чеку