Помогаем продавать
Войти в ЛК

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

Версия 1.19 от 23.10.2020 Открыть pdf-файл

Введение

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

1. Основные сведения о запросе и ответе

Кодировка, используемая в запросах и ответах – UTF-8. Запросы выполняются методами POST и GET, параметры запроса располагаются в структуре данных формата JSON, передаваемой в блоке данных запроса (при использовании POST), также параметры могут передаваться в строке запроса (при использовании GET). Ответы выдаются сервером в формате 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» – так же, как и в случае успешного ответа, время, затраченное системой на обработку запроса. Формат представления времени тот же.

2. Авторизация через AuthToken

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

Параметры запроса:
HTTP/1.1
Content-Length: 38
Content-Type: application/json
charset=utf-8

Вид запроса:

POST https://ofd.ru/api/Authorization/CreateAuthToken

Тело запроса представляет собой структуру JSON, содержащую:

{
    "Login": "12345","Password": "56789"
}

Приведены примеры значений: Login – «12345» и Password – «56789». Они задаются как значения в JSON-структуре внутри запроса.

Другой формат запроса, обрабатываемый ИС “Renta” - HTTP-запрос авторизации в формате URLEncoded:

Параметры запроса:
HTTP/1.1
Content-Length: 38
Content-Type: application/x-www-form-urlencoded
charset=utf-8

Вид запроса:

POST https://ofd.ru/api/Authorization/CreateAuthToken

Тело запроса представляет собой:

login=12345&password=56789

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

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

Здесь:

  • «AuthToken» – код авторизации: строка символов AuthToken, представляет собой 32-значную последовательность шестнадцатеричных цифр, используемую для повторной аутентификации;
  • «ExpirationDateUtc» – строка, описывающая момент времени (дату и время в формате UTC+3), до которого будет действовать данный код авторизации. 1)
    Момент времени задается в формате «ГГГГ-ММ-ДДTчч:мм:сс» 2):
    ГГГГ - год даты, 4 цифры,
    ММ - месяц даты, 2 цифры,
    ДД - день даты 2 цифры,
    T - заглавная латинская буква “T”, используется как разделитель даты и времени,
    чч - часы, 2 цифры,
    мм - минуты, 2 цифры,
    сс - секунды, 2 цифры.

В случае проблем с авторизацией (код ответа по протоколу HTTP будет равен 401) данные будут отсутствовать, JSON-структура будет пустой (будет иметь вид «{}»).
Полученный код авторизации используется в виде дополнительного параметра в запросах документов для сверки, где необходима авторизация 3). Пример запроса с использованием кода авторизации:

POST https://ofd.ru/api/renta/v1/inn/INN/receipts/Date1/Date2?AuthToken=Code1
  • Code1 – действующий код авторизации, полученный в результате запроса авторизации.

3. Функции интерфейса приложений

3.1. Получение списка чеков со сведениями о них за заданный период по кассе или юридическому лицу

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

GET https://ofd.ru/api/renta/v1/inn/INN1/receipts/Date1/Date2?AuthToken=Code1

или

GET https://ofd.ru/api/renta/v1/kkt/KKT1/receipts/Date1/Date2?AuthToken=Code1

Здесь:

  • INN1 – ИНН юридического лица, на которое зарегистрирована касса, по данным которой генерируется отчет – строка из 10 цифр от 0 до 9;
  • KKT1 – регистрационный номер машины (РНМ) или заводской (серийный) номер кассы – строка символов;
  • Date1 и Date2 – начальная и конечная даты периода, для которого требуется найти сведения по кассовым чекам – строка символов, содержащая дату в формате ISO YYYY-MM-DD. Разность 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. Список чеков за заданный период

Идентификатор Формат поля Назначение
Id Строка в формате UUID Уникальный номер фискального документа в ИС, используется в запросе подробной информации по чеку, как RawId
IsCorrection Логическая переменная Имеет значение true, если чек или бланк строгой отчетности (БСО) является документом коррекции, иначе – false
CDateUtc Дата и время в формате ISO Дата и время приема документа в ИС
Tag Целое число Численный признак вида документа:
3 – чек,
31 – чек коррекции,
4 – бланк строгой отчетности,
41 – бланк строгой отчетности коррекции
IsBso Логическая переменная Имеет значение true, если документ является БСО, иначе (если документ является чеком) – false
OperationType Строка Тип операции:
«Income» – приход,
«Expense» – расход,
«Refund income» – возврат прихода,
«Refund expense» – возврат расхода.
KktAddress Строка Место установки кассы
SerialNumber Строка Заводской номер кассы
KktRegNumber Строка Регистрационный номер кассы
FnNumber Строка Номер фискального накопителя, установленного в кассу
DocNumber Целое число Фискальный номер документа
DocDateTime Дата и время в формате ISO Дата и время формирования документа по данным кассы
DocShiftNumber Целое число Номер смены (по данным кассы), в которую был сформирован документ
ReceiptNumber Целое число Номер документа в смене (по данным кассы)
TotalSumm Целое число Общая сумма по чеку в копейках
CashSumm Целое число Сумма наличными по чеку в копейках
ECashSumm Целое число Сумма электронного платежа по чеку в копейках
CreditSumm Целое число Кредит в копейках
PrepaidSumm Целое число Аванс в копейках
TaxTotalSumm Целое число Общая сумма удерживаемых налогов, начисленная за смену в копейках
Tax10Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10 %, начисленная за смену, в копейках
Tax18Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 18 %, начисленная за смену, в копейках
Tax110Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10/110, начисленная за смену, в копейках
Tax118Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 18/118, начисленная за смену, в копейках
TaxNaSumm Целое число Сумма по операциям, не облагаемая НДС, накопленная за смену, в копейках
Tax0Summ Целое число Сумма по операциям, облагаемая НДС по ставке 0%, накопленная за смену, в копейках
Depth Целое число Количество товарных позиций в чеке

3.2. Получение полной информации по чеку

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

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. Информация по чеку

Идентификатор Вложенные поля Формат поля Назначение
Id Строка в формате UUID Уникальный номер фискального документа в ИС
IsCorrection Логическая переменная Имеет значение true, если чек или бланк строгой отчетности (БСО) является документом коррекции, иначе – false
IsBso Логическая переменная Имеет значение true, если документ является БСО, иначе (если документ является чеком) – false
OperationType Строка Тип операции:
«Income» – приход;
«Expense» – расход;
«Refund income» – возврат прихода;
«Refund expense» – возврат расхода.
UserInn Строка ИНН юридического лица
UserName Строка Название юридического лица
KktAddress Строка Место установки кассы
SerialNumber Строка Заводской номер кассы
kktRegNumber Строка Регистрационный номер кассы
FnNumber Строка Номер фискального накопителя, установленного в кассу
Items Структура Информация о проданном товаре
Name Строка Название товара по чеку
CustomName Строка Название товара из кастомного справочника пользователя, если справочник был загружен пользователем
Price Целое число Цена с НДС
Quantity Целое число Количество товара в товарной позиции
Total Целое число Стоимость товарной позиции в копейках
CalculationMethod Целое число Признак способа расчета
SubjectType Целое число Признак предмета расчета
NDS_Rate Целое число Ставка НДС принимает значения:
1 - НДС 18%;
2 - НДС 10%;
3 - НДС 18/118;
4 - НДС 10/110;
5 - НДС 0%;
6 - НДС не облагается.
NDS_Summ Целое число Общая сумма НДС в копейках
DocDateTime Дата и время в формате ISO Дата и время формирования документа по данным кассы
TotalSumm Целое число Общая сумма по чеку в копейках
CashSumm Целое число Сумма по чеку (БСО) наличными в копейках
ECashSumm Целое число Сумма по чеку (БСО) электронными в копейках
CreditSumm Целое число Сумма по чеку (БСО) постоплатами (кредитами)
PrepaidSumm Целое число Сумма по чеку (БСО) предоплатами (авансами)
TaxTotalSumm Целое число Общая сумма удерживаемых налогов, начисленная за смену в копейках
Tax10Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10 %, начисленная за смену, в копейках
Tax18Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 18 %, начисленная за смену, в копейках

3.3. Получение сведений о юридических лицах, подключивших свои кассы к ИС “Renta”

Запрос на получение списка юридических лицах, подключивших свои кассы к ИС “Renta” имеет вид:

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. Сведения о юридических лицах

Идентификатор Формат поля Назначение
UserInn Строка ИНН юридического лица, подключившего свои кассы в текущем ЛК “Renta”
UserKpp Строка КПП юридического лица, подключившего свои кассы в текущем ЛК “Renta”
UserName Строка Название юридического лица или имя ИП, подключившего свои кассы в текущем ЛК “Renta”
KktRegistered Целое число Количество касс зарегистрированных у данного юридического лица
KktOnline Целое число Количество касс зарегистрированных у данного юридического лица, работающих в текущий момент

3.4. Получение сведений о кассах юридических лиц, подключенных к ИС “Renta”

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

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",
      "AvailableReports": [
          "KktWorkingTime",
          "KktOperations",
          "KktReceipts",
          "NomenclatureSales"
      ]
    }
  ]
}

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

В ответе на запрос также могут быть сведения об ошибке:

  • InnNotFound – для текущей учетной записи не найдена организация с заданным ИНН.

Таблица 4. Сведения о кассах юридических лиц

Идентификатор Формат поля Назначение
UserInn Строка ИНН юридического лица, зарегистрированного в текущем ЛК “Renta”
UserKpp Строка КПП юридического лица, зарегистрированного в текущем ЛК “Renta”
UserName Строка Название юридического лица или имя ИП, зарегистрированного в текущем ЛК “Renta”
KktAddress Строка Адрес установки кассы
KktPlace Строка Зарегистрированное название места установки кассы
KktSerialNumber Строка Заводской номер кассы
KktRegNumber Строка Регистрационный номер кассы
FnNumber Строка Номер фискального накопителя кассы
AvailableReports Структура Доступные отчеты4):
KktWorkingTime - Время работы касс;
KktOperations - Операции по кассам (приход/возврат);
KktReceipts - Чеки (сверка);
NomenclatureSales - Продажи по номенклатуре;
KktOracleReceipts - Чеки (сверка) из Оракл;
UnaccountedRevenue - Неучтенная выручка;
KktMonitoring - Мониторинг передачи данных;
RentaForTenantReport - Отчет для арендатора Renta;
RentaCloseShiftReport - Отчет по сменам для клиентов Renta (арендодателей)

3.5. Подключение касс к ИС “Renta”

Запрос на подключение касс к ИС «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. Информация о кассах, для их подключения к ЛК “Renta”

Идентификатор Формат поля Назначение
UserInn Строка ИНН юридического лица, зарегистрированного в текущем ЛК “Renta”
UserKpp Строка КПП юридического лица, зарегистрированного в текущем ЛК “Renta”
UserOgrn Строка ОГРН юридического лица, зарегистрированного в текущем ЛК “Renta”
UserEmail Строка Адрес электронной почты для регистрации ЛКК, либо дополнительного пользователя существующего ЛКК
KktList Массив структур Список записей о регистрируемых кассах
KktNumber Строка Заводской номер кассы
FnNumber Строка Номер фискального накопителя кассы
KktRegNumber Строка Регистрационный номер кассы
KktAddress Строка Адрес установки кассы
KktPlace Строка Зарегистрированное название места установки кассы
CurrentOfdInn Строка ИНН оператора фискальных данных, обслуживающего кассу в настоящее время

Успешным ответом на запрос (с кодом 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. Ответ на запрос на подключение касс к ЛК “Renta”

Идентификатор Формат поля Назначение
UserInn Строка ИНН юридического лица, зарегистрированного в текущем ЛК “Renta”
UserKpp Строка КПП юридического лица, зарегистрированного в текущем ЛК “Renta”
UserEmail Строка Адрес электронной почты для регистрации ЛКК, либо дополнительного пользователя существующего ЛКК
UserOgrn Строка ОГРН юридического лица, зарегистрированного в текущем ЛК “Renta”
KktList Массив структур Список записей о регистрируемых кассах
KktNumber Строка Заводской номер кассы
FnNumber Строка Номер фискального накопителя кассы
KktRegNumber Строка Регистрационный номер кассы
KktAddress Строка Адрес установки кассы
KktPlace Строка Зарегистрированное название места установки кассы
CurrentOfdInn Строка ИНН оператора фискальных данных, обслуживающего кассу в настоящее время
Errors Массив структур Список записей о регистрируемых кассах
ErrorCode Строка Код ошибки
ErrorMessage Строка Сообщение об ошибке

Таблица 7. Коды ошибок

Код ошибки Сообщение об ошибке Назначение
1 InnKppIncorrect Неверно задан ИНН или КПП
2 AuthorizationError Ошибка авторизации
3 KktBelongAnotherInn ККТ принадлежит другому ИНН
4 RnFnIncorrect Неверный формат РН или ФН
5 OfdInnUnknown Неизвестный ИНН оператора фискальных данных

3.6. Отключение касс от ИС “Renta”

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

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

Вид запроса:

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”

Идентификатор Формат поля Назначение
UserInn Строка ИНН юридического лица торгового центра, от которого требуется отключить кассу
KktRegNumber Строка Регистрационный номер отключаемой кассы
KktOffDate Строка Дата и время отключения кассы

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

Таблица 9. Коды ошибок

Код ошибки Сообщение об ошибке Назначение
1 InnKppIncorrect Неверно задан ИНН или КПП
2 AuthorizationError Ошибка авторизации
3 KktBelongAnotherInn Ошибка привязки ККТ к ЛК “Renta”
4 RnFnIncorrect Неверный формат РН или ФН
5 OfdInnUnknown Неизвестный ИНН оператора фискальных данных
6 WrongDate Некорректно заданная дата

3.7. Отчёт по номенклатуре

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

GET https://ofd.ru/api/renta/v3/report/nomenclatures?inn=INN1&inn=INN2&DateStart=Date1&DateEnd=Date2&AuthToken=Code1

Здесь:

  • INN1 и INN2 – ИНН юридического лица, на которого зарегистрирована касса, по данным которой генерируется отчёт – строка из 10 цифр от 0 до 9. Для получения отчёта по нескольким компаниям, достаточно перечислить в URL запроса несколько ИНН, как показано в примере API-запроса;
  • Date1 и Date2 – начальная и конечная даты периода, для которого требуется найти сведения по кассовым чекам – строка символов, содержащая дату в формате ISO YYYY-MM-DD. Разность Date2 и Date1 не должна превышать 7 дней;
  • Code1 – действующий код авторизации, полученный в результате запроса авторизации.

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

{
    "Data": [
        {
            "Inn": "590500806738",
            "Address": "614000, г Пермь, Баумана, 24, корп/стр: а, офис/кв: 20",
            "ProductGroup": "Apparel",
            "ProductCategory": "PANTS",
            "Nomenclature": ">4150006/>5 брюки o1. culotte pants (36) шт",
            "SalesCount": 1,
            "IncomeSum": 6922,
            "IncomeCount": 1,
            "ReturnedSum": 0,
            "ReturnedCount": 0,
            "AvgNomenclatureCount": 1
        },
        {
            "Inn": "027814131865",
            "Address": "450000, г Уфа, Менделеева, 148, корп/стр: 3, офис/кв: 9",
            "ProductGroup": "Underwear",
            "ProductCategory": "UNDERWEAR",
            "Nomenclature": "3-PACK TRUNK XO GIFT BOX CTN S (Артикул: >901833153; Код цвета: >405; Размер: XL)",
            "SalesCount": 1,
            "IncomeSum": 4770,
            "IncomeCount": 1,
            "ReturnedSum": 0,
            "ReturnedCount": 0,
            "AvgNomenclatureCount": 2
        },
        ...
    ]
}

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

Таблица 10. Ответ на запрос отчета по номенклатуре

Идентификатор Формат поля Назначение
Inn Строка ИНН организации
Address Строка Юридический адрес компании
ProductGroup Строка Наименование группы товаров, в которой находится товар
ProductCategory Строка Категория товара
Nomenclature Строка Наименование товара
SalesCount Целое число Количество продаж
IncomeSum Целое число Сумма прихода
IncomeCount Целое число Количество чеков на выручку
ReturnedSum Целое число Сумма возврата
ReturnedCount Целое число Количество чеков на возврат
AvgNomenclatureCount Целое число Среднее количество номенклатуры в чеке

Термины и определения, применяемые в пользовательской документации программных продуктов оператора “OFD.ru”

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

Версия 1.17
Выпущена 03 апреля 2020 г.
Добавлен метод получения отчёта по номенклатуре

Версия 1.18
Выпущена 24 сентября 2020 г.
Устранены мелкие недочеты по всему объему документа.

Версия 1.19
Выпущена 23 октября 2020 г.

  • Исправлена ошибка в описании метода 3.1 Получение списка чеков со сведениями о них за заданный период по кассе или юридическому лицу;
  • Добавлена информация по доступным отчетам в методе 3.4. Получение сведений о кассах юридических лиц, подключенных к ИС “Renta”;
  • Устранены мелкие недочеты по всему объему документа.
1)
Время, которое токен будет активен - 24 часа.
2)
Данный формат описан в стандарте ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Здесь используется только формат представления времени без задания смещения часовых поясов (Time Zone Offset) и интервалов.
3)
Далее в запросах параметр кода авторизации не указывается
4)
Представлен полный список возможных отчетов
5)
Взято из https://ru.wikipedia.org/wiki/Контрольно-кассовая_машина#В_Российской_Федерации