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

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

Введение

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

1. Авторизация

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

Для того, чтобы постоянно обращаться к ИС «Отчеты», реализован метод получения параметра 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 – действующий код авторизации, полученный в результате запроса авторизации.

1.2. Метод получения OfdAgreementId

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

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


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

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

Заменяемые значения Описание Обязательность
INN1 Идентификационный номер налогоплательщика (ИНН) юридического лица Да
KPP1 Идентификационный номер, дополняющий ИНН юридического лица. Да
Page Может иметь следующие значения:
- true (отключает постраничный вывод)
- false (включает постраничный вывод)
Нет
Code1 Действующий код авторизации, полученный в результате запроса авторизации Да

Пример запроса на получение 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

Параметр Вложенный параметр Вложенный параметр Формат значения Описание
Status Сообщения о статусе запроса
Data Структура Данные о запросах на отчеты
OfdAgreementId Строка Идентификатор ЛКК
OfdAgreementLimit Целое число Максимальное количество запросов на отчёты
ConsumedLimit Целое число Израсходованное количество запросов на отчёты
List Массив [Структура] Массив структур данных по сгенерированным отчетам
Id Строка Идентификатор отчета
CDateUtc Дата и время в формате ISO Дата генерации отчета
ReportTypeName Строка Тип отчета, см. п. 3.1.1.
DateFrom Дата и время в формате ISO Начальная дата отчета
DateTo Дата и время в формате ISO Конечная дата отчета
ExpiredDate Дата и время в формате ISO Дата и время автоматического удаления отчета системой из списка
KktCount Целое число Количество касс
Status Строка Статус отчета, см. п. 3.2.1
AccountEmail Строка Адрес электронной почты пользователя ЛКК
AccountName Строка Имя пользователя ЛКК
Name Строка Название отчета
EmailsToNotify Массив В параметре перечислены адреса электронной почты для уведомления о генерации отчета
FileFormat Строка Формат файла сгенерированного отчета
IsAutoReport Логическая переменная Признак автоматически генерируемого отчета.
Возможные значения:
- true;
- false.
AssumptiveCompleteTime Дата и время в формате ISO Предположительное время формирования отчета (если отчет ещё не сгенерирован)
DownloadUrl Строка URL-адрес доступа к сгенерированному отчету для метода GET
DeleteUrl Строка URL-адрес удаления сгенерированного отчета для метода DELETE
CancelUrl Строка URL-адрес отмены сгенерированного отчета. Если отчет ещё не сгенерирован, то его возможно отменить методом GET
TotalCount Целое число Общее количество отчетов
Elapsed Дата и время в формате ISO Время, затраченное системой на обработку запроса

2. Виды запросов ИС «Отчеты»

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

3. Запрос отчетов

3.1. Запрос на генерацию пользовательского отчета

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

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

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

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

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

Параметр Тип данных Описание
ofdAgreementId Строка в формате UUID Идентификатор ЛКК, в котором производится запрос
DateFrom Дата и время в формате ISO Начальная дата периода генерации отчета
DateTo Дата и время в формате ISO Конечная дата периода генерации отчета
KktList Массив Список касс, по которым генерируется отчет
GroupsList Массив Список папок с записями ККТ, по которым генерируется отчет (учитывается содержимое всех вложенных папок)
SelectAllKkts Логическая переменная Признак выбора для генерации отчета всех ККТ текущего ЛКК
CustomReportId Строка в формате UUID Идентификатор пользовательского шаблона (задается, если запрошен отчет на основе пользовательского шаблона)
UseXlsxFile Логическая переменная Признак «Использовать для отчета файл типа XSLX»
ReportType Строка Тип отчета, (если не задан CustomReportId), см. п. 3.1.1.
KktStatus Строка Состояние касс, по которым генерируется отчет (в данной версии не используется)
SearchString Строка Строка фильтрации списка касс (в данной версии не используется)
EmailsToNotify Строка Признак «Оповестить об окончании генерации отчета по почте». В параметре вы можете перечислить адреса электронной почты для уведомления о генерации отчета. Адреса электронной почты указываются через символ «;»

Успешным ответом на запрос является ответ с кодом 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

3.1.1. Возможные типы отчетов

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

3.1.2. Возможные ошибки

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

3.2. Загрузка списка отчетов

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

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. Параметры запроса списка отчетов

Параметр Тип данных Описание
OfdAgreementLimit Целое число Максимальное количество отчетов, которое пользователь может запросить
ConsumedLimit Целое число Израсходованное количество отчетов
List Массив структур Массив структур данных по сгенерированным и генерируемым отчетам
Id Строка в формате UUID Идентификатор отчета
CDateUtc Дата и время в формате ISO Дата генерации отчета
ReportType Строка Тип отчета, см. п. 3.1.1.
DateFrom Дата и время в формате ISO Начальная дата отчета
DateTo Дата и время в формате ISO Конечная дата отчета
ExpiredDate Дата и время в формате ISO Дата и время, когда отчет будет автоматически удален системой из списка
KktCount Целое число Количество касс
ReportSize Целое число Размер отчета (в килобайтах)
Status Строка Статус отчета, см. п. 3.2.1
AccountEmail Строка Адрес электронной почты, использующийся в учетной записи
TotalCount Целое число Общее количество отчетов

3.2.1. Возможные статусы отчета

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

3.2.2. Возможные ошибки

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

4. Удаление файла сгенерированного пользовательского отчета

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

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

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

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

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

Параметр Тип данных Описание
Id Строка в формате UUID Идентификатор отчета (то же значение, что и в запросе)
command.ofdAgreementId Строка в формате UUID Идентификатор ЛКК, в котором производится запрос
command.id Строка в формате UUID Идентификатор отчета (то же значение, что и в запросе)

Успешным ответом на запрос (с кодом 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"
}

4.1. Возможные ошибки

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

5. Отчеты и структуры

5.1. Загрузка отчета по ID (в формате GUID)

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

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

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

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

Параметр Тип данных Описание
id Строка в формате UUID Идентификатор отчета (то же значение, что и в запросе)
ofdAgreementId Строка в формате UUID Идентификатор ЛКК, в котором производится запрос

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

5.1.1. Возможные ошибки

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

5.2. Загрузка списка типов базовых отчетов и их структур

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

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. Поля данных записи с описанием типов базовых отчетов и их структуры

Идентификатор Формат поля Назначение
ReportType Строка Тип отчета, см. п. 3.1.1.
DisplayName Строка Имя отчета, выводимое в документ или в окно интерфейса
Description Строка Краткое описание отчета
Fields Структура Структура с описанием полей
Name Строка Имя (идентификатор) поля
DisplayField Строка Имя поля, выводимое в документ или в окно интерфейса
Optional Логическая переменная Признак «дополнительное поле»

5.2.1. Возможные ошибки

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

6. Шаблоны

6.1. Загрузка списка шаблонов отчетов, созданных пользователем

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

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. Поля данных списка шаблонов отчетов, созданных пользователем

Идентификатор Формат поля Назначение
Name Строка Название шаблона пользовательского отчета
BaseReportType Строка Тип отчета, на основе которого построен шаблон
CustomFields Массив строк Идентификаторы полей, выбранных пользователем
Id Строка в формате UUID Идентификатор шаблона
CDateUtc Дата и время в формате ISO Дата и время создания шаблона
UDateUtc Дата и время в формате ISO Дата и время последнего изменения шаблона

6.1.1. Возможные ошибки

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

6.2. Сохранение модифицированного шаблона

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

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

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

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

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

Параметр Тип данных Описание
Name Строка Название шаблона пользовательского отчета
Fields Массив строк Сохраняемые измененные идентификаторы полей
BaseReportType Строка Тип отчета, на основе которого построен шаблон
Description Строка Описание шаблона пользовательского отчета

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

6.2.1. Возможные ошибки

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

6.3. Загрузка шаблона пользовательского отчета по идентификатору

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

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. Поля данных шаблона пользовательского отчета

Идентификатор Формат поля Назначение
Name Строка Название шаблона пользовательского отчета
BaseReportType Строка Тип отчета, на основе которого построен шаблон
CustomFields Массив строк Идентификаторы полей, выбранных пользователем
Id Строка в формате UUID Идентификатор шаблона
CDateUtc Дата и время в формате ISO Дата и время создания шаблона
UDateUtc Дата и время в формате ISO Дата и время последнего изменения шаблона

6.3.1 Возможные ошибки

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

6.4. Сохранение шаблона пользовательского отчета по идентификатору

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

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

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

6.4.1. Возможные ошибки

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

6.5. Удаление шаблона пользовательского отчета по идентификатору

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

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

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

6.5.1. Возможные ошибки

  • 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» исправлена опечатка в значениях

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