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

Введение

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

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

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

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

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

Здесь с ключом "AuthToken" – код авторизации: строка символов AuthToken, представляет собой 32-значную последовательность шестнадцатеричных цифр, используемую для повторной аутентификации, а ключ "ExpirationDateUtc" – строка, описывающая момент времени (дату и время в формате UTC), до которого будет действовать данный код авторизации.

Момент времени задается в формате "ГГГГ-ММ-ДДTчч:мм:сс"; здесь

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

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

2. Виды запросов ИС «Чеки и ККТ»

Запросы (функции) программного интерфейса приложений ИС «Чеки и ККТ» реализуют функции, необходимые в процессе работы различных ИС, использующих кассы и работающих с кассовыми документами. Большинство запросов имеет схожий формат и особенности структуры входных и выходных данных, если входные и выходные данные будут отличаться, это будет описываться дополнительно. Обобщенно формат запроса и ответа описан ниже.

С помощью запросов программного интерфейса приложений ИС «Чеки и ККТ» можно получать информацию о чеках и ККТ. Кодировка, в запросах и ответах – UTF-8. Ответы выдаются сервером в формате JSON, и, в случае успешности ответа, согласно его заголовку (код ответа по протоколу HTTP равен 200), данные имеют следующий обобщенный вид:

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

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

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

2.1. Запрос списка зарегистрированной KKT

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

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

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

Таблица 1. Поля данных записи с информацией о ККТ

Ошибка в ответе на запрос, обрабатываемая ИС: InnNotFound – для текущей учетной записи не найдено юридическое лицо по заданному ИНН.

2.2. Запрос списка отчетов по смене для заданной кассы за заданный период

Запрос на получение списка отчетов по смене (z-отчетов) по заданной кассе за заданный период имеет вид:

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

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

Таблица 2. Поля данных записи с информацией о ККТ

Ошибки в ответе на запрос, обрабатываемые ИС:

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

2.3. Запрос списка отчетов по смене для всей ККТ за заданный период

Запрос на получение списка отчетов по смене (z-отчетов) для всей ККТ, зарегистрированной на определенного владельца, за заданный период имеет вид:

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

Ошибки в ответе на запрос, обрабатываемые ИС:

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

2.4. Список чеков за период по заданной кассе

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

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

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

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

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

2.5. Список чеков за смену по заданной кассе

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

Здесь INN – ИНН юридического лица, на которого зарегистрирована касса, по данным которой генерируется отчет – строка из 10 цифр от 0 до 9; KKT – заводской (серийный) номер кассы – строка символов; Shift1 – номер смены, по которой требуется сгенерировать отчет и Fn1 – номер фискального накопителя, установленного в кассу. Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON, аналогичная структуре, приведенной в п. 2.1.4. Описание полей структуры см. в Таблице 3, описание ошибок, см. в п. 2.1.4.

2.6. Подробная информация по чеку

Запрос на получение подробной информации по конкретному чеку может быть получен двумя способами: по уникальному номеру фискального документа, либо по порядковому номеру смены и номеру документа в смене.

или

здесь INN – ИНН юридического лица, на которого зарегистрирована касса, по данным которой генерируется отчет – строка из 10 цифр от 0 до 9; KKT – заводской (серийный) номер кассы – строка символов; RawId – уникальный номер фискального документа в ИС «Чеки и ККТ» (строка в формате UUID); ShiftNumber – номер смены, в течение которой был сгенерирован документ, DocShiftNumber – номер документа внутри смены.

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

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

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

Ошибки в ответе на запрос, обрабатываемые ИС:

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

2.7. Прямая ссылка на электронный чек

Прямая ссылка на электронный чек имеет следующий вид:

{Домен}/rec/{inn}/{kktregnumber}/{fnnumber}/{docnumber}/{decsign}

Ниже, в таблице 5 приведен список параметров.

Таблица 5. Параметры ссылки на электронный чек

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

Версия 1.3

Выпущена 11 октября 2017 г.

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

Версия 1.31

Выпущена 26 января 2018 г.

1. Добавлены дополнительные поля в структуры данных смены и чека.
2. Устранены мелкие недочеты по всему объему документа.

Версия 1.32

Выпущена 7 февраля 2018 г.

1. Добавлена дополнительная форма запроса подробной информации
   по чеку.
2. Устранены мелкие недочеты по всему объему документа.

Версия 1.33

Выпущена 15 марта 2018 г.

Добавлена дополнительная форма запроса данных смены и чека.

Версия 1.34

Выпущена 24 мая 2018 г.

Добавлены дополнительные поля в запросе данных чека.

Версия 1.4

Выпущена 16 июля 2018 г.

1. Изменено название документа на «Программный интерфейс приложений (API) интеграции ИС пользователей с АИС “OFD.ru”»
2. Изменен стиль оформления документа, обновлен логотип кампании.
3. Добавлены функции работы с пользовательскими отчетами.
4. Введена новая структура разделов, функции поделены на группы.
5. Устранены фактические ошибки в существующих описаниях вызовов API.

Версия 1.5

Выпущена 24.08.2018

1. Изменено название документа на «Программный интерфейс приложений (API) для работы с ИС «Чеки и ККТ»
2. Подраздел «Работа с пользовательскими отчетами» выделен в документ «Программный интерфейс приложений (API) для работы с ИС «Отчеты»