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

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

Введение

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

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

Возможность множественных обращений к ИС «Отчеты» после одной авторизации без использования механизма 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" соответственно. Другой формат запроса, обрабатываемый ИС «Отчеты»: 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-структура будет пустой (будет иметь вид «{}»). Полученный код авторизации используется в виде дополнительного параметра в запросах документов для сверки, где необходима авторизация. Пример запроса с использованием кода авторизации:

GET api/integration/v1/inn/INN1/kkts?AuthToken=Code1

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

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" – так же, как и в случае успешного ответа, время, затраченное системой на обработку запроса; формат представления времени тот же.

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

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

POST api/customer/reports

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

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

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

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

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

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

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

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

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

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

GET api/customer/reports

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

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

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

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

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

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

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

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

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

DELETE api/customer/reports/id

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

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

Параметр Тип данных Описание
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"
}

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

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

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

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

GET api/customer/reports/id

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

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

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

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

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

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

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

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

GET api/customer/reports/templates

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

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

[
{
"ReportType": "CloseShiftReport",
"DisplayName": "string",
"Description": "string",
"Fields": [
{
"Name": "string",
"DisplayField": "string",
"Optional": true
},
...
]
},
...
]
Список полей этой структуры c их описаниями представлен в таблице 10.

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

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

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

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

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

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

GET api/customer/reports/custom

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

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

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

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

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

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

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

POST api/customer/reports/custom

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

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

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

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

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

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

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

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

GET api/customer/reports/custom/id

Здесь id – идентификатор отчета, генерируемый ИС «Отчеты», имеет вид UUID.

Успешным ответом на запрос (с кодом 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 их описаниями представлен в таблице 13.

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

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

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

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

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

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

PUT api/customer/reports/custom/id

Здесь id — идентификатор отчета, генерируемый ИС «Отчеты», имеет вид UUID.

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

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

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

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

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

DELETE api/customer/reports/custom/id

Здесь id — идентификатор отчета, генерируемый ИС «Отчеты», имеет вид UUID.

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

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

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

3. История изменений

Версия 1.0

Выпущена 24 августа 2017 г.

Первая версия документа.