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

Программный интерфейс приложений (API) предоставляет возможность сторонним (клиентским) приложениям запрашивать генерацию отчетов о ККТ и ее эксплуатации в информационной системе (ИС) «Отчеты». Взаимодействие клиентского приложения и API осуществляется путем отправки приложением HTTP-запросов к серверу и получением ответов в формате JSON. Для отправки запросов и получения ответов используется протокол HTTPS.

Для того, чтобы постоянно обращаться к ИС «Отчеты», реализован метод получения параметра AuthToken без использования механизма Cookies. Метод AuthToken использует логин и пароль для получения кода авторизации. Код авторизации - это параметр авторизации для обращения к личному кабинету (ЛК).
HTTP-запрос авторизации передает имя пользователя и пароль в формате JSON. Пример запроса авторизации:

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

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

В запросе параметры:
«Login» - имя пользователя ЛК OFD.ru
«Password» - пароль пользователя ЛК OFD.ru

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

{
    "AuthToken": "ed38f9e155ce4a7ab3b784606fcd40a1",
    "ExpirationDateUtc": "2021-11-12T10:55:20"
}

Параметр «AuthToken» – это код авторизации. Значение параметра AuthToken, представляет собой 32-значную последовательность шестнадцатеричных цифр и требуется для повторной аутентификации.
Параметр «ExpirationDateUtc» – это дата и время (в формате UTC) действия кода авторизации.
Параметр представлен в формате «ГГГГ-ММ-ДДTчч:мм:сс». Данный формат описан в стандарте ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Здесь используется только формат представления времени без задания смещения часовых поясов (Time Zone Offset) и интервалов.
В случае проблем с авторизацией (код ответа по протоколу HTTP будет равен 403) данные будут отсутствовать, JSON-структура будет пустой (будет иметь вид «{}»).
Полученный код авторизации используется в виде дополнительного параметра в запросах документов для сверки, где необходима авторизация.
Доступ к кассам по полученному ключу “AuthToken” происходит в соответствии с правами доступа, заданными для пользователя, чьи имя и пароль были использованы в процессе генерации ключа “AuthToken”. Права пользователя могут быть заданы одновременно для ЛКК нескольких юридических лиц, при этом функции описываемого здесь программного интерфейса приложений (API), связанные со сбором данных по ККТ будут возвращать выдаются только тем единицам ККТ, доступ к которым разрешен согласно используемому значению ключа “AuthToken”.
Пример запроса с использованием кода авторизации:

GET https://ofd.ru/api/integration/v1/inn/INN1/kkts?AuthToken=Code1

Здесь:

• INN1 – идентификационный номер налогоплательщика (ИНН) юридического лица, согласно которому производится запрос (строка из 10 цифр, от 0 до 9);
• Code1 – действующий код авторизации, полученный в результате запроса авторизации.

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

Запрос на получения идентификатора ЛКК или параметра OfdAgreementId выглядит следующим образом:

GET https://ofd.ru/api/customer/reports?&Inn={INN1}&Kpp={KPP1}&SkipPageFilter={Page}&AuthToken={Code1}

Таблица 1. Описание параметров запроса для получения параметра OfdAgreementId

Пример запроса на получение OfdAgreementId:

GET https://ofd.ru/api/customer/reports?&Inn=7841465198&Kpp=772501001&SkipPageFilter=true&AuthToken=061000bd5c234ee4b8f9fe4e143922d1

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

{
  "Status": "Success",
  "Data": {
    "OfdAgreementId": "56ddf007-76d7-4157-8e85-2d9fe0704cb4",
    "OfdAgreementLimit": 500000,
    "ConsumedLimit": 0,
    "List": [
      {
        "Id": "a0e5354a-709c-41de-ba48-63e7b7e05ee7",
        "CDateUtc": "2021-10-25T08:13:41",
        "ReportTypeName": "Отчёт по сменам",
        "ReportType": "CloseShiftReport",
        "DateFrom": "2021-10-25T00:00:00",
        "DateTo": "2021-10-25T11:12:34",
        "ExpiredDate": "2021-11-01T08:13:41",
        "KktCount": 59,
        "Status": "Processing",
        "AccountEmail": "yascher@ofd.ru",
        "AccountName": "Jhon Dow",
        "Name": "Отчёт по сменам",
        "EmailsToNotify": [
          ""
        ],
        "FileFormat": "Xlsx",
        "IsAutoReport": false,
        "AssumptiveCompleteTime": "2021-10-25T08:14:41",
        "DownloadUrl": "/api/customer/reports/a0e5354a-709c-41de-ba48-63e7b7e05ee7?OfdAgreementId=56ddf007-76d7-4157-8e85-2d9fe0704cb4",
        "DeleteUrl": "/api/customer/reports/a0e5354a-709c-41de-ba48-63e7b7e05ee7?ofdAgreementId=56ddf007-76d7-4157-8e85-2d9fe0704cb4",
        "CancelUrl": "/api/customer/reports/a0e5354a-709c-41de-ba48-63e7b7e05ee7/cancel?ofdAgreementId=56ddf007-76d7-4157-8e85-2d9fe0704cb4"
      }
    ],
    "TotalCount": 1
  },
  "Elapsed": "00:00:25.3858651"
}

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

Запросы (функции) программного интерфейса приложений ИС «Отчеты» реализуют функции, необходимые в процессе работы ИС предприятий и организаций, использующих кассы и работающих с кассовыми документами. Большинство запросов имеет схожий формат и особенности структуры входных и выходных данных. Если входные и выходные данные будут отличаться, это будет описываться дополнительно. Обобщенно формат запроса и ответа описан ниже.
С помощью запросов программного интерфейса приложений ИС «Отчеты» можно получать отчеты о ККТ и ее функционировании как в заранее определенном виде, так и в формате, задаваемом пользователем. Кодировка в запросах и ответах – UTF 8. Ответы выдаются сервером в формате 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» – время, затраченное системой на обработку запроса;
Формат представления времени тот же.

Запрос на генерацию пользовательского отчета (на заказ отчета) имеет вид:

POST https://ofd.ru/api/customer/reports?AuthToken=Code1

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

Параметры запроса передаются списком в формате запросов команды POST. Параметры запроса приведены в таблице 3.

Таблица 3. Параметры запроса на генерацию пользовательского отчета

Успешным ответом на запрос является ответ с кодом 200, содержащий структуру данных.
Ошибки, обрабатываемые запросом, приведены в п. 3.1.2.

Пример запроса на генерацию пользовательского отчета:

POST https://ofd.ru/api/customer/reports?AuthToken=061000bd5c234ee4b8f9fe4e143922d1

{
  "OfdAgreementId": "d64249c5-61b8-4ed9-b729-9bd7cde127db",
  "CustomReportId": null,
  "Name": "Сверка",
  "DateFrom": "2021-11-01T00:00:00.000+03:00",
  "DateTo": "2021-11-02T23:59:59.000+03:00",
  "EmailsToNotify": "",
  "FfdType": 0,
  "GroupsList": [],
  "KktList": [
    "7961d10e-f36a-4cce-a8db-add93309bb9e"
  ],
  "ReportType": "ReceiptReport",
  "SelectAllKkts": false,
  "UseXlsxFile": true

}
 

Пример успешного ответа на запрос генерации пользовательского отчета:

{
    "Status": "Success",
    "Data": {
        "Id": "bddf7767-f72b-49a9-90f1-df1b74090d92",
        "CDateUtc": "2021-11-15T10:14:44",
        "ReportTypeName": "Сверка",
        "ReportType": "ReceiptReport",
        "DateFrom": "2021-11-01T00:00:00",
        "DateTo": "2021-11-02T23:59:59",
        "ExpiredDate": "2021-11-22T10:14:44",
        "KktCount": 1,
        "Status": "Todo",
        "AccountEmail": "123@gamil.ru",
        "AccountName": "Иван",
        "Name": "Сверка",
        "EmailsToNotify": [
            ""
        ],
        "FileFormat": "Xlsx",
        "IsAutoReport": false,
        "AssumptiveCompleteTime": "2021-11-15T10:15:44",
        "DownloadUrl": "/api/customer/reports/bddf7767-f72b-49a9-90f1-df1b74090d92?OfdAgreementId=d64249c5-61b8-4ed9-b729-9bd7cde127db",
        "DeleteUrl": "/api/customer/reports/bddf7767-f72b-49a9-90f1-df1b74090d92?ofdAgreementId=d64249c5-61b8-4ed9-b729-9bd7cde127db",
        "CancelUrl": "/api/customer/reports/bddf7767-f72b-49a9-90f1-df1b74090d92/cancel?ofdAgreementId=d64249c5-61b8-4ed9-b729-9bd7cde127db"
    },
    "Elapsed": "00:00:00.4870790"
}

Описание параметров ответа представлено в таблице 1.2 в разделе 1.2. Метод получения OfdAgreementId

• KKTReport — Отчет по подключенным ККТ;
• CloseShiftReport — Отчет по закрытым сменам;
• ReceiptReport — Сверка (список чеков);
• FiscalDocumentReport — Список фискальных документов;
• RentReport — Отчет арендатора;
• EReceiptReport — Статистика отправки электронных чеков;
• OpenShift24Report — Список касс со сменами, открытыми более 24 часов;
• ManagerKktReport — Список всех касс;
• MyKktReport — Отчёт-мониторинг;
• FnScheduleReport — График смены ФН.

• DateFromGreaterThanDateTo — Конечная дата больше начальной, ошибка в задании диапазона дат;
• OfdAgreementNotFound — Личный кабинет, к которому происходит обращение, не найден;
• AccessDenied — Доступ заблокирован;
• ReportSizeError — Запрошен отчет на слишком большое количество записей;
• LimitExhausted — Исчерпан лимит свободного дискового пространства пользователя личным кабинетом клиента;
• InternalError — Внутренняя ошибка ИС «Отчеты».

Запрос на получение списка отчетов (сгенерированных и генерирующихся) для текущего пользователя имеет вид:

GET https://ofd.ru/api/customer/reports?AuthToken=Code1

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

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

{
  "OfdAgreementLimit": 500000,
  "ConsumedLimit": 0,
  "List": [
    {
      "Id": "1577b8bc-a384-4f1d-ad00-b0c2440601ef",
      "CDateUtc": "2018-07-12T12:28:06",
      "ReportType": "CloseShiftReport",
      "DateFrom": "2018-07-12T00:00:00",
      "DateTo": "2018-08-12T23:59:59",
      "ExpiredDate": "2018-07-19T12:28:06",
      "KktCount": 8,
      "ReportSize": 8,
      "Status": "Done",
      "AccountEmail": ofdtester1@ofd.ru
    },
    ...
    ],
    " TotalCount ": 9
}

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

Таблица 4. Параметры запроса списка отчетов

• Todo — Отчет ожидает генерации;
• Done — Отчет готов;
• Deleted — Отчет удален;
• Processing — Отчет генерируется;
• Error — Генерация отчета совершена с ошибкой.

• OfdAgreementNotFound — Личный кабинет, к которому происходит обращение, не найден;
• AccessDenied — Доступ заблокирован;
• InternalError — Внутренняя ошибка ИС «Отчеты».

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

DELETE https://ofd.ru/api/customer/reports/id?AuthToken=Code1

Здесь:
id – идентификатор отчета, генерируемый ИС «Отчеты», который имеет вид UUID;
Code1 – действующий код авторизации, полученный в результате запроса авторизации.

Параметры запроса передаются списком в формате запросов команды DELETE.
Параметры запроса приведены в таблице 5.

Таблица 5. Параметры запроса на удаление файла отчета

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

{
  "Id": "3ec32d28-d851-4ada-9ae3-d4ef5d05d9a1",
  "CDateUtc": "2018-07-16T14:35:24",
  "ReportType": "CloseShiftReport",
  "DateFrom": "2018-07-16T00:00:00",
  "DateTo": "2018-07-16T23:59:59",
  "ExpiredDate": "2018-07-23T14:35:24",
  "KktCount": 61,
  "ReportSize": 8,
  "Status": "Deleted",
  "AccountEmail": "ofdtest1@ofd.ru"
}

• OfdAgreementNotFound — Личный кабинет, к которому происходит обращение, не найден;
• AccessDenied — Доступ заблокирован;
• ReportNotFound — Удаляемый документ не найден;
• InternalError — Внутренняя ошибка ИС «Отчеты».

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

GET https://ofd.ru/api/customer/reports/id?AuthToken=Code1

Здесь:
id – Идентификатор отчета, генерируемый ИС «Отчеты» (имеет вид UUID);
Параметры запроса передаются списком в команде GET следом за строкой; строка от параметров отделена символом “?”, между группами «параметр — значение» используется разделитель “&”, между параметром и значением используется разделитель “=”;
Code1 – Действующий код авторизации, полученный в результате запроса авторизации.
Параметры запроса приведены в таблице 6.

Таблица 6. Параметры запроса файла отчета

Успешным ответом на запрос (с кодом HTTP равным 200) является ответ, содержащий файл запрошенного отчета.
Ошибки, обрабатываемые запросом, приведены в п. 5.1.1.

• ReportNotDone — Отчет не сгенерирован или не существует;
• InternalError — Внутренняя ошибка ИС «Отчеты».

Запрос списка шаблонов базовых отчетов с указанием их структуры имеет вид:

GET https://ofd.ru/api/customer/reports/templates?AuthToken=Code1

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

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

[
  {
    "ReportType": "CloseShiftReport",
    "DisplayName": "string",
    "Description": "string",
    "Fields": [
      {
        "Name": "string",
        "DisplayField": "string",
        "Optional": true
      },
      ...
    ]
  },
  ...
]

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

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

• InternalError — Внутренняя ошибка ИС «Отчеты».

Запрос на получение списка сгенерированных отчетов для текущего пользователя имеет вид:

GET https://ofd.ru/api/customer/reports/custom?AuthToken=Code1

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

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

[
  {
    "Name": "string",
    "BaseReportType": "All",
    "CustomFields": [
      "string",..
    ],
    "Id": "00000000-0000-0000-0000-000000000000",
    "CDateUtc": "2001-09-11T08:46:26.0000000",
    "UDateUtc": "2001-09-11T08:46:26.0000000"
  },
  ...
]

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

Таблица 8. Поля данных списка шаблонов отчетов, созданных пользователем

• AccessDenied — Доступ заблокирован;
• InternalError — Внутренняя ошибка ИС «Отчеты».

Запрос на сохранение модифицированного шаблона отчета для текущего пользователя имеет вид:

POST https://ofd.ru/api/customer/reports/custom?AuthToken=Code1

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

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

Таблица 9. Параметры запроса на сохранение шаблона с внесенными изменениями

Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON содержащая только поле «Status» с указанием значения «Elapsed».

• AccessDenied — Доступ заблокирован;
• InternalError — Внутренняя ошибка ИС «Отчеты».

Запрос для текущего пользователя шаблона отчета по заданному идентификатору шаблона имеет вид:

GET https://ofd.ru/api/customer/reports/custom/id?AuthToken=Code1

Здесь:
id – Идентификатор отчета, генерируемый ИС «Отчеты» (имеет вид UUID);
Code1 – действующий код авторизации, полученный в результате запроса авторизации.
Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON следующего вида (приведены примеры значений):

{
  "Name": "string",
  "BaseReportType": "All",
  "CustomFields": [
    "string",..
  ],
  "Id": "00000000-0000-0000-0000-000000000000",
  "CDateUtc": "2001-09-11T08:46:26.0000000",
  "UDateUtc": "2001-09-11T08:46:26.0000000"
}

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

Таблица 10. Поля данных шаблона пользовательского отчета

• InternalError — Внутренняя ошибка ИС «Отчеты».

Запрос на сохранение шаблона отчета по заданному идентификатору шаблона для текущего пользователя имеет вид:

PUT https://ofd.ru/api/customer/reports/custom/id?AuthToken=Code1

Здесь:
id – идентификатор отчета, генерируемый ИС «Отчеты» (имеет вид UUID).
Code1 – действующий код авторизации, полученный в результате запроса авторизации.
Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON, содержащая только «Status», имеющее значение «Success», и «Elapsed».

• AccessDenied — Доступ заблокирован;
• InternalError — Внутренняя ошибка ИС «Отчеты».

Запрос на удаление шаблона отчета для текущего пользователя по заданному идентификатору шаблона имеет вид:

DELETE https://ofd.ru/api/customer/reports/custom/id?AuthToken=Code1

Здесь id – идентификатор отчета, генерируемый ИС «Отчеты» (имеет вид UUID).
Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON, содержащая только поле «Status», имеющее значение «Success», и «Elapsed».

• AccessDenied — Доступ заблокирован;
• InternalError — Внутренняя ошибка ИС «Отчеты».

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

Версия 1.1
Выпущена 12 сентября 2018 г.
В раздел 1 («Авторизация через AuthToken») добавлена информация о разграничении прав доступа к ККТ в зависимости от заданных прав для учетной записи.

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

Версия 1.3
Выпущена 15 ноября 2021 г.

• Добавлен новый «1.2. Метод получения OfdAgreementId»
• Добавлен пример запроса на генерацию пользовательского отчета в разделе «3.1. Запрос на генерацию пользовательского отчета»
• Добавлен пример ответа на запрос генерации пользовательского отчета в разделе «3.1. Запрос на генерацию пользовательского отчета»
• Дополнено описание параметра EmailsToNotify в таблице 3.1
• В параметре «ReportType» исправлена опечатка в значениях

Устранены мелкие недочеты по всему объему документа.