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

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

Версия 1.91 от 14.05.2019 Открыть 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), до которого будет действовать данный код авторизации, в результате применения ключа «AuthToken».
Момент времени задается в формате «ГГГГ-ММ-ДДTчч:мм:сс» 1); здесь
ГГГГ – год даты, 4 цифры,
ММ – месяц даты, 2 цифры,
ДД – день даты 2 цифры,
T – заглавная латинская буква “T”, используется как разделитель даты и времени,
чч – часы, 2 цифры,
мм – минуты, 2 цифры,
сс – секунды, 2 цифры.

В случае проблем с авторизацией (код ответа по протоколу HTTP будет равен 403) данные будут отсутствовать, JSON-структура будет пустой (будет иметь вид «{}»). Полученный код авторизации используется в виде дополнительного параметра в запросах документов для сверки, где необходима авторизация.
Доступ к кассам по полученному ключу “AuthToken” происходит в соответствии с правами доступа, заданными для пользователя, чьи имя и пароль были использованы в процессе генерации ключа “AuthToken”. Права пользователя могут быть заданы одновременно для ЛКК нескольких юридических лиц, при этом функции описываемого здесь программного интерфейса приложений (API), связанные со сбором данных по ККТ будут возвращать данные только по тем единицам ККТ, доступ к которым разрешен согласно используемому значению ключа “AuthToken”.
Пример запроса с использованием кода авторизации:

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

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

2. Запросы к ИС на получение информации по чекам и ККТ

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

{
  "Status": "Success",
  "Data": {
    "Prop1": "Val1",
    "Prop2": "Val2",
    ...
    "PropN": "ValN"
  },
  "Elapsed": "чч:мм:сс.ддддддд"
}

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

{
  "Status": "Failed",
  "Errors": [
    "Ошибка 1",
    "Ошибка 2",
    ...
    "Ошибка N"
  ],
  "Elapsed": "чч:мм:сс.ддддддд"
}

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

2.1. Запрос информации о KKT

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

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

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

{
  "Status": "Success",
  "Data": [
    {
      "Id": "00000000-0000-0000-0000-000000000000",
      "KktRegId": "9304171212297195",
      "KktName": "Касса 1",
      "SerialNumber": "44444444444443421132",
      "FnNumber": "0666666666666660",
      "CreateDate": "2017-01-13T12:09:51",
      "PaymentDate": "2017-01-13T12:15:43",
      "CheckDate": "2017-01-13T12:12:47",
      "ActivationDate": "2017-01-13T12:15:48",
      "FirstDocumentDate": "2017-01-13T14:15:48",
      "ContractStartDate": "2017-01-13T12:12:47",
      "ContractEndDate": "2018-02-12T12:12:47",
      "LastDocOnKktDateTime": "2017-02-12T10:12:00",
      "LastDocOnOfdDateTimeUtc": "2017-02-12T07:13:10",
      "FiscalAddress": "https://ofd.ru/",
      "FiscalPlace": "https://ofd.ru/",
      "Path": "/Мои кассы/Список касс 1/",
      "KktModel": "АТОЛ 42ФС"
      "FnEndDate": "2019-10-17T12:47:57"
    },
    ...
  ]
}

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

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

Идентификатор Формат поля Назначение
Id Строка Уникальный номер ККТ (кассы)
KktRegId Строка Регистрационный номер ККТ (кассы)
KktName Строка Название кассы
SerialNumber Строка Заводской (серийный) номер ККТ (кассы)
FnNumber Строка Номер фискального накопителя
CreateDate Дата и время в формате ISO 2) Дата регистрации кассы на сайте
PaymentDate Дата и время в формате ISO Дата оплаты услуг оператора “OFD.ru”
CheckDate Дата и время в формате ISO Дата подписания КЭП (квалификационной электронной подписью)
ActivationDate Дата и время в формате ISO Дата успешной проверки регистрационного номера в ФНС
FirstDocumentDate Дата и время в формате ISO Дата и время генерации кассой первого документа
ContractStartDate Дата и время в формате ISO Дата начала действия контракта на получение услуг оператора “OFD.ru”
ContractEndDate Дата и время в формате ISO Дата окончания действия контракта на получение услуг оператора “OFD.ru”
LastDocOnKktDateTime Дата и время в формате ISO Дата и время последнего документа, сгенерированного кассой (по локальному времени кассы)
LastDocOnOfdDateTimeUtc Дата и время в формате ISO Дата и время получения последнего документа кассы в ОФД (по времени оператора “OFD.ru” в UTC)
FiscalAddress Строка Адрес установки
FiscalPlace Строка Адрес расчетов
Path Строка Иерархия расположения кассы
KktModel Строка Модель кассы (ККТ)
FnEndDate Дата и время в формате ISO Дата и время окончания работы фискального накопителя

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

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

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

GET https://ofd.ru/api/integration/v1/inn/INN/kkt/KKT/zreports?dateFrom=Date1&dateTo=Date2&AuthToken=Code1

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

{
  "Status": "Success",
  "Data": [
    {
      "Id": "fc6562fc-e8b9-4ce2-a7c1-461a02171a98",
      "Open_CDateUtc": "2016-07-26T09:28:54",
      "Close_CDateUtc": "2016-07-27T15:47:36",
      "UserInn": "7802870820",
      "KktRegNumber": "111222333",
      "FnNumber": "99990789388",
      "ShiftNumber": 1,
      "Operator": "Администратор",
      "Open_DocNumber": 2,
      "Open_DocDateTime": "2016-07-26T12:28:00",
      "Open_DocRawId": "7e66f625-2cf6-428f-bf98-be37077daf55",
      "Close_DocNumber": 9,
      "Close_DocDateTime": "2016-07-27T18:47:00",
      "Close_DocRawId": "cc3110c0-f1ca-49d1-9d3c-1f880e28957f",
      "IncomeSumm": 375420,
      "IncomeCashSumm": 0,
      "IncomeCount": 5,
      "RefundIncomeSumm": 6360,
      "RefundIncomeCashSumm": 0,
      "RefundIncomeCount": 1,
      "ExpenseSumm": 0,
      "ExpenseCount": 0,
      "RefundExpenseSumm": 0,
      "RefundExpenseCount": 0,
      "TaxTotalSumm": 0,
      "Tax10Summ": 0,
      "Tax18Summ": 0,
      "Tax110Summ": 0,
      "Tax118Summ": 0,
      "TaxNaSumm": 0,
      "Tax0Summ": 0
    },
    ...
  ]
}

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

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

Идентификатор Формат поля Назначение
Id Строка в формате UUID Идентификатор смены
Open_CDateUtc Дата и время в формате ISO Дата и время первого принятия в ИС от кассы документа отчета об открытии смены
Close_CDateUtc Дата и время в формате ISO Дата и время первого принятия в ИС от кассы документа отчета о закрытии смены
UserInn Строка, 10 или 12 цифр ИНН владельца кассы
KktRegNumber Строка Регистрационный номер кассы
FnNumber Строка Номер фискального накопителя, установленного в кассу
ShiftNumber Целое число Номер смены по данным кассы
Operator Строка Фамилия, имя, отчество оператора
Open_DocNumber Целое число Фискальный номер документа отчета об открытии смены, присвоенный кассой (уникальный в рамках текущего фискального режима)
Open_DocDateTime Дата и время в формате ISO ата и время формирования отчета об открытии смены по данным кассы
Open_DocRawId Строка в формате UUID Идентификатор документа отчета об открытии смены, полученного от кассы
Close_DocNumber Целое число Номер документа отчета о закрытии смены, присвоенный кассой (уникальный в рамках текущего фискального режима)
Close_DocDateTime Дата и время в формате ISO Дата и время формирования отчета о закрытии смены по данным кассы
Close_DocRawId Строка в формате UUID Идентификатор документа отчета об закрытии смены, полученного от кассы
IncomeSumm Целое число Сумма полученных денежных средств за смену в копейках
IncomeCashSumm Целое число Сумма полученных денежных средств за смену наличными в копейках
IncomeCount Целое число Количество чеков, выданных за смену, соответствующих получению суммы IncomeSumm
RefundIncomeSumm Целое число Сумма выданных (возвращённых) денежных средств за смену в копейках
RefundIncomeCashSumm Целое число Сумма выданных (возвращенных) денежных средств за смену наличными в копейках
RefundIncomeCount Целое число Количество чеков, выданных за смену, соответствующих возврату суммы RefundIncomeSumm
TaxTotalSumm Целое число Общая сумма удерживаемых налогов, начисленная за смену в копейках
Tax10Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10 %, начисленная за смену в копейках
Tax18Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 18 %, начисленная за смену в копейках
Tax110Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10/110, начисленная за смену, в копейках
Tax118Summ Целое число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 18/118, начисленная за смену, в копейках
TaxNaSumm Целое число Сумма по операциям, не облагаемая НДС, накопленная за смену, в копейках
Tax0Summ Целое число Сумма по операциям, облагаемая НДС по ставке 0%, накопленная за смену, в копейках

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

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

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

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

GET https://ofd.ru/api/integration/v1/inn/INN/zreports?dateFrom=Date1&dateTo=Date2&AuthToken=Code1

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

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

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

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

GET https://ofd.ru/api/integration/v1/inn/INN/kkt/KKT/receipts?dateFrom=Date1&dateTo=Date2&AuthToken=Code1

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

{
  "Status": "Success",
  "Data": [
    {
      "Id": "3a6e3b83-a0b0-4587-bfb3-1b7539b05cf3",
      "CDateUtc": "2016-07-26T09:32:41",
      "Tag": 0,
      "IsBso": false,
      "IsCorrection": false,
      "OperationType": "Income",
      "UserInn": "7802870820",
      "KktRegNumber": "111222333",
      "FnNumber": "99990789388",
      "DocNumber": 3,
      "DocDateTime": "2016-07-26T12:32:00",
      "DocShiftNumber": 1,
      "ReceiptNumber": 1,
      "DocRawId": "3a6e3b83-a0b0-4587-bfb3-1b7539b05cf3",
      "TotalSumm": 0,
      "CashSumm": 0,
      "ECashSumm": 0,
      "PrepaidSumm": 0,
      "CreditSumm": 0,
      "ProvisionSumm": 0,
      "TaxTotalSumm": 0,
      "Tax10Summ": 0,
      "Tax18Summ": 0,
      "Tax110Summ": 0,
      "Tax118Summ": 0,
      "Tax0Summ": 0,
      "TaxNaSumm": 0,
      "Depth": 3
    },
    ...
  ]
}

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

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

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

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

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

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

GET https://ofd.ru/api/integration/v1/inn/INN/kkt/KKT/receipts?ShiftNumber=Shift1&FnNumber=Fn1&AuthToken=Code1

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

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

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

GET https://ofd.ru/api/integration/v1/inn/INN/kkt/KKT/receipt/RawId&AuthToken=Code1

или

GET https://ofd.ru/api/integration/v1/inn/INN/kkt/KKT/zreport/ShiftNumber/receipt/DocShiftNumber&AuthToken=Code1

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

{
  "Status": "Success",
  "Data": {
    "Tag": 3,
    "User": "ООО МКАС СПб",
    "UserInn": "7802870820 ",
    "Number": 1,
    "DateTime": "2016-07-26T12:32:00",
    "ShiftNumber": 1,
    "OperationType": 1,
    "TaxationType": 1,
    "Operator": "Администратор",
    "KKT_RegNumber": "111222333",
    "FN_FactoryNumber": "99990789388",
    "Items": [
      {
        "Name": "Услуги",
        "Price": 599000,
        "Quantity": 12,
        "Total": 599000,
        "CalculationMethod": 4,
        "SubjectType": 1,
        "NDS_Rate": 1,
        "NDS_Summ": 99833,
        "Nds00_TotalSumm": 0
      },
      ...
    ],
    "Buyer_Address": "",
    "Nds18_TotalSumm": 99833,
    "Amount_Total": 599000,
    "Amount_Cash": 0,
    "Amount_ECash": 599000,
    "Document_Number": 3,
    "FiscalSign": "MQTLUGn8",
    "DecimalFiscalSign": "3393623696",
    "KKT_MachineNumber": "1",
    "InternetSign": 1,
    "Format_Version": 2,
    "Amount_Advance": 0,
    "Amount_Loan": 0,
    "Amount_Granting": 0,
    "ExtraProperty": [
      {
        "ExtraProperty_Name": "Name",
        "ExtraProperty_Value": "Value"
      },
      {
        "ExtraProperty_Name": "Name",
        "ExtraProperty_Value": "Value"
      }
    ]
  }
}

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

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

Идентификатор Формат поля Назначение
Tag Целое число Численный признак вида документа:
3 – чек,
31 – чек коррекции,
4 – бланк строгой отчетности,
41 – бланк строгой отчетности коррекции
User Строка Полное имя или название владельца кассы
UserInn Строка, 10 или 12 цифр ИНН владельца кассы
Number Целое число Номер документа внутри смены
DateTime Дата и время в формате ISO Дата и время формирования документа (чека)
ShiftNumber Целое число Номер смены (по данным кассы), в которую был сформирован документ
OperationType Строка Тип операции:
«Income» – приход,
«Expence» – расход,
«Refund income» – возврат прихода,
«Refund expence» – возврат расхода.
TaxationType Целое число Тип налогообложения смотри п.п.2.6.1
Operator Строка Должность, фамилия, имя, отчество (фамилия и инициалы) оператора
KKT_RegNumber Строка Регистрационный номера кассы
FN_FactoryNumber Строка Номер фискального накопителя, установленного в кассу
Items Массив структур Список товарных позиций в чеке
Name Строка Название товарной позиции в чеке
Price Целое число Цена в копейках за единицу измерения товарной позиции
Quantity Целое число Количество единиц товарной позиции
Total Целое число Стоимость товарной позиции в копейках
CalculationMethod Целое число Признак способа расчета
SubjectType Целое число Признак предмета расчета
NDS_Rate Целое число Ставка НДС принимает значения:
1 - НДС 18%;
2 - НДС 10%;
3 - НДС 18/118;
4 - НДС 10/110;
5 - НДС 0%;
6 - НДС не облагается.
NDS_Summ Целое число Общая сумма НДС в копейках
Buyer_Address Строка Адрес покупателя (используется службами доставки)
Nds18_TotalSumm Целое число Общая сумма НДС по чеку в копейках
Amount_Total Целое число Общая сумма по чеку в копейках
Amount_Cash Целое число Сумма наличными по чеку в копейках
Amount_ECash Целое число Сумма, оплаченная картой, в копейках
Document_Number Целое число Фискальный номер документа
FiscalSign Строка Фискальный признак документа
DecimalFiscalSign Строка Фискальный признак документа
KKT_MachineNumber Строка Заводской номер автоматического устройства для расчетов
InternetSign Целое число Признак осуществления расчетов только в сети «Интернет», в которой отсутствует устройство для печати фискальных документов в составе ККТ
Format_Version Целое число Номер версии формата фискальных документов
Amount_Advance Целое число Сумма предоплаты
Amount_Loan Целое число Сумма постоплаты
Amount_Granting Целое число Сумма встречным предоставлением
ExtraProperty Массив структур Список дополнительных свойств чека
ExtraProperty_Name Строка Название (идентификатор) свойства
ExtraProperty_Value Строка Значение свойства

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

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

2.6.1. Возможные значения типа налогообложения (поле “TaxationType”)

  • «Common» или «0» — общая система налогообложения;
  • «SimpleIn» или «1» — упрощенная система налогообложения (доход);
  • «SimpleInOut» или «2» — упрощенная система налогообложения (доход минус расход);
  • «Unified» или «3» — единый налог на вмененный доход;
  • «UnifiedAgricultural» или «4» — единый сельскохозяйственный налог;
  • «Patent» или «5» — патентная система налогообложения.

Внимание! Возможные (корректные) значения типа налогообложения ограничиваются значениями, отмеченными, как разрешенные при регистрации кассы. Для того, чтобы изменить список допустимых типов налогообложения, необходимо произвести перерегистрацию кассы.

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

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

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

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

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

Параметр Тэг из документа «Приложении 2 к приказу ФНС России от 21 марта 2017 г. № ММВ-7-20/229@» («Формат фискальных документов») Описание
inn 1018 ИНН владельца кассы, на которого она зарегистрирована
kktregnumber 1037 Регистрационный номер ККТ
fnnumber 1041 Номер фискального накопителя
docnumber 1040 Номер фискального документа
decsign 1077 Фискальный признак документа

3. Запросы к ИС на получение информации о папках и кассах с ошибками

Помимо функций управления кассами и получения информации о кассах и чеках в ИС имеется возможность обработки запросов программного интерфейса на получение информации об организации касс в структуру папок, а также о кассах, имеющих проблемы: неисправных, неоплаченных, отключенных по каким-либо другим причинам и т. д.; ниже описываются такие запросы.

3.1. Запрос на получение структуры папок с ККТ

Запрос на получение списка папок с ККТ, находящихся в корневом либо в явно заданном каталоге текущего ЛКК, имеет следующий вид:

GET api/integration/v1/kktgroup/list

или

GET api/integration/v1/kktgroup/list?groupId=Id1

здесь Id1 — идентификатор папки, список дочерних папок которой запрашивается; если параметр отсутствует, в ответе на запрос возвращается список папок корневого каталога касс текущей учетной записи. Если пользователь, данные аутентификации которого (например, значение AuthToken) используются при выполнении запросов, является доверенным лицом (дополнительным пользователем), то список папок содержит только те папки, к которым у данного пользователя имеется доступ в соответствии с предоставленными правами.
Ответ на запрос имеет типовую структуру, описанную в разделе 2. Структура данных имеет формат JSON следующего вида (приведены примеры значений):

{
  "Status": "Success",
  "Data": [
    {
      ″AgreementId″: ″1afff828-7ac1-41aa-8282-210c9ffb3df7″,
      ″Groups″: [
        {
          ″Id″: ″26beff999-d454-44aa-8ada-cdc1rf8942fd″,
          ″Name″: ″Все кассы″,
          ″Path″: ″/Все кассы/″,
          ″Level″: 1
        }
      ]
    }
  ],
}

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

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

Идентификатор Формат поля Назначение
AgreementId Строка в формате UUID Идентификатор личного кабинета, для которого генерируется список каталогов 3)
Groups Массив структур Массив записей с информацией о папках, в которых содержатся кассы
Id Строка в формате UUID Идентификатор папки в ИС «Чеки и ККТ»
Name Строка Имя папки
Path Строка Путь к папке
Level Целое число Уровень вложенности папки (1 для корневого каталога, 2 для содержимого папки в корневом каталоге, 3 — для содержимого папки в папке корневого каталога и т. п.

3.2. Запрос на получение информации о кассах с ошибками

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

GET api/integration/v1/kkt/problem/list

или

GET api/integration/v1/kkt/problem/list/KKT1

здесь KKT1 — регистрационный номер кассы.
Ответ на запрос имеет типовую структуру, описанную в разд. 2, идентификатору «Data» соответствует массив структур; структура имеет следующий вид (приведены примеры значений):

{
  "Id": "00000000-0000-0000-0000-000000000000",
  "KktName": "string",
  "KktModel": "string",
  "KktRegId": "string",
  "SerialNumber": "string",
  "FnNumber": "string",
  "CreateDate": "2001-09-11T08:46:26.0000000",
  "PaymentDate": "2001-09-11T08:46:26.0000000",
  "CheckDate": "2001-09-11T08:46:26.0000000",
  "ActivationDate": "2001-09-11T08:46:26.0000000",
  "ContractStartDate": "2001-09-11T08:46:26.0000000",
  "ContractEndDate": "2001-09-111T08:46:26.0000000",
  "FirstDocumentDate": "2001-09-11T08:46:26.0000000",
  "LastDocumentDate": "2001-09-11T08:46:26.0000000",
  "FiscalAddress": "string",
  "FiscalPlace": "string",
  "GroupId": "00000000-0000-0000-0000-000000000000",
  "Path": "string",
  "Status": "string",
  "StatusMessage": "string"
}

Список полей этой структуры c их описаниями представлен в таблице 7. Если запрос произведен с указанием регистрационного номера кассы (KKT1), то массив в ответе будет состоять из одной записи.

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

Идентификатор Формат поля Назначение
Id Строка в формате UUID Идентификатор ККТ
KktName Строка Название ККТ
KktModel Строка Модель ККТ
KktRegId Строка Регистрационный номер ККТ
SerialNumber Строка Заводской номер ККТ
FnNumber Строка Номер фискального накопителя ККТ
CreateDate Строка, содержащая дату Дата и время внесения информации о ККТ
PaymentDate Строка, содержащая дату Дата и время последнего платежа за обслуживание данного ККТ
CheckDate Строка, содержащая дату
ActivationDate Строка, содержащая дату Дата и время активации ККТ
ContractStartDate Строка, содержащая дату Дата и время начала действия контракта по предоставлению услуг ОФД для данного ККТ
ContractEndDate Строка, содержащая дату Дата и время окончания контракта по предоставлению услуг ОФД для данного ККТ
FirstDocumentDate Строка, содержащая дату Дата и время генерации кассой первого фискального документа
LastDocumentDate Строка, содержащая дату Дата и время генерации кассой последнего фискального документа
FiscalAddress Строка Адрес установки кассы
FiscalPlace Строка Место установки кассы
GroupId Строка в формате UUID Идентификатор папки, в которой находится касса в ЛКК
Path Строка Путь к папке, в которой находится касса в ЛКК
Status Строка Статус кассы (обозначение)
StatusMessage Строка Статус кассы (полное название)

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

Версия 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) для работы с ИС «Отчеты»

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

Версия 1.7
Выпущена 17.10.2018
Добавлен раздел «Запросы к ИС на получение информации о папках и кассах с ошибками» (раздел 3); в разделе находится описание двух функций.

Версия 1.8
Выпущена 14.11.2018
Исправлены ошибки в описании структуры ответа на запрос списка касс: уточнен состав полей и их назначение (поле CheckDate вместо SignDate и добавление поля FirstDocumentDate).

Версия 1.9
Выпущена 10.04.2019

  1. Визуально поправлен текст, исправлены ошибки в тексте и запросах;
  2. В раздел 1 («Авторизация через AuthToken») добавлена информация о разграничении прав доступа к ККТ в зависимости от заданных прав для учетной записи;
  3. Во всех примерах API-запросов был добавлен домен и, где необходимо, параметр AuthToken;
  4. Исправлен пример запроса имеющий обобщенный вид в разделе 2 на актуальный;
  5. В примере запроса списка зарегистрированных KKT добавлены параметры NSerialNumber, KKTSerialNumber, KKTRegNumber;
  6. В примере ответа на запрос списка зарегистрированных KKT добавлены параметры Id, CheckDate, FirstDocumentDate, Path, KktModel, FnEndDate;
  7. В примере ответа на запрос списка отчетов по смене для заданной кассы за заданный период добавлены параметры Id, Open_CDateUtc, Open_DocRawId, Close_DocRawId, IncomeCashSumm, RefundIncomeCashSumm;
  8. В примере ответа на запрос cписка чеков за период по заданной кассе добавлены параметры IsCorrection, DocRawId, PrepaidSumm;
  9. В примере ответа на запрос подробной информации по чеку добавлены параметры Total, CalculationMethod, SubjectType, NDS_Rate, NDS_Summ, DecimalFiscalSign, KKT_MachineNumber, InternetSign, Format_Version, Amount_Advance, Amount_Loan, Amount_Granting;
  10. В таблицы с описанием полей были добавлены виды документов и типы операций;
  11. Добавлены типы налогообложений.

Версия 1.91
Выпущена 14 мая 2019 г.
В ответ на запрос информации о ККТ был добавлен параметр с название кассы.

1) , 2)
Данный формат описан в стандарте ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Здесь используется только формат представления времени без задания смещения часовых поясов (Time Zone Offset) и интервалов.
3)
Если определено несколько личных кабинетов для одной учетной записи (один и тот же человек зарегистрировал в OFD.ru несколько юридических лиц, или один и тот же работник головной компании имеет доступ к учетным записям нескольких филиалов), то массив структур содержит несколько записей с различными ″AgreementId″, если же учетной записи соответствует один ЛКК, то есть, одно юридическое лицо, массив будет состоять из одного элемента.