Программный интерфейс приложений (API) обслуживание касс по услуге ОФД

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

Методы доступным через стандартную процедуры получения значения параметра «AuthToken». В запросе получения кода авторизации необходимо передавать значения логина и пароль от личного кабинета партнера (ЛКП) OFD.ru. Для методов есть ограничение доступа. Доступ к методам выдается только через обращение в службу поддержки OFD.ru.

Для многократного обращения к API массового продления услуги ОФД, после одной авторизации без использования механизма Cookies реализован механизм AuthToken. После авторизации с передачей имени и пароля система возвращает код авторизации – строку символов. Код авторизации необходимый параметр в API запросах массового продления услуги ОФД. Код авторизации необходим в запросах для обращения личному кабинету (ЛК). HTTP-запрос авторизации выполняется методом POST с передачей дополнительных параметров формате JSON.

Запрос выглядит следующим образом:

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

Тело запроса:

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

В запросе необходимы значения следующих параметров:

Login – логин ЛКК OFD.ru;
Password – пароль.

На запрос будет получен ответ по протоколу HTTP. Успешный ответ на запрос авторизации будет иметь код равный 200.

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

{
    "AuthToken": "f3accdfda7574736ba94a78d00e974f4",
    "ExpirationDateUtc": "2017-01-24T14:44:21"
}

В ответе представлены следующие параметры:

«AuthToken» – ключ авторизации¹⁾;
«ExpirationDateUtc» – дата и время действия ключа аутентификации²⁾.

Если после запроса код ответа по протоколу HTTP будет равен 403, данные будут отсутствовать, вам необходимо проверить правильность введенных значений для параметров «Login», «Password».

Полученный код авторизации - это необходимый параметр для выполнения запросов в API массового продления услуги ОФД.

Получение информации по кассам и фискальным данным выполняется с помощью запросов к API массового продления услуги ОФД с использованием параметра “AuthToken”. Доступ к информации определяется в соответствии с настроенными в ЛК правами доступа к кассам и фискальным данным заданными для пользователя. Права пользователя могут быть заданы одновременно для нескольких ЛК юридических лиц. В ответах на запросы к API массового продления услуги ОФД будут приходить данные к которым разрешен доступ согласно значению ключа “AuthToken”.

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

GET https://ofd.ru/api/integration/v1/inn/{INN}/kkts?AuthToken={Code}

Параметры необходимы для выполнения запроса к API массового продления услуги ОФД:

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

2. Применение КА (оплата)

Метод используется партнерами для автоматизация оплаты касс клиентов кодами активации (далее КА) на услуги ОФД.

Чтобы применить КА необходимо передавать в метод обязательные параметры, со значениями данных своих клиентов в API-запрос.
После прохождении проверок выполняются следующие действия:

создание личного кабинета клиента (если ЛКК по ИНН клиента отсутствует);
применение кода активации на услугу ОФД.

В таблице 1 представлены параметры необходимые для выполнения запроса.

Таблица 1. Параметры для API-запроса

Параметры	Формат значения	Описание	Признак обязательности в запросе³⁾
Inn	String	ИНН идентификационный налоговый регистрационный номер (Клиента)	Да
Kpp	String	КПП идентификационный признак юридического лица (Клиента)	Нет⁴⁾
Email	String	Email клиента (Необходим для создания ЛКК в OFD.ru. Логин для входа в ЛКК)	Да
ActivationCode	String	Код активации для применения на кассах клиента	Да
Rnm	String	РНМ регистрационный номер кассы клиента	Да

В параметре «authToken» необходимо указать значение действующего кода авторизации, полученный в результате запроса авторизации.

Запрос для выполнения применения КА на кассах клиента имеет следующий вид:

POST https://ofd.ru/api/integration/partner/v1/kkt/pay?AuthToken={authToken}

{
  "Inn": "0182021620",
  "Kpp": "804845377",
  "Rnm": "09876543211234",
  "ActivationCode": "PSZ7D1Lq",
  "Email": "skala.judo@gmail.com"
}

В ответ на запрос возможны следующие вариант.

Ответ со значением «ККТ оплачена»:

{
  "IsCompleted": true,
  "IsWaiting": false
}

Ответ со значением «ККТ ожидает первый ФД»:

{
  "IsCompleted": false,
  "IsWaiting": true
}

Параметры ответа:

IsCompleted - КА примена на кассе ждет первого фискального документа (далее ФД).
IsWaiting - значение получения первого ФД.

Возможные ошибки при обработке запроса на примение КА:

ИНН не существует;
Необходимо указать КПП;
Некорректный email;
Ошибка применения, возможны следующие причины:
- Неверная связка ИНН-РНМ;
- Нельзя применить код активации на ККТ без кода партнера;
- Нельзя применить код активации на ККТ с чужим кодом партнера.

После применения КА на ИНН, если нет созданного ЛКК но есть ККТ, создается ЛКК и отправляется на email письмо параметрами (логин и пароль) входа в ЛКК. После прохождения всех проверок, КА успешно применяется и активирует услуги ОФД.

Если ККТ не была настроена на передачу фискальных данных (далее ФД) в OFD.ru, КА для кассы действует в течении 3-х суток.

Особенности и ограничения:

На кассу применяется один КА услуг ОФД, применить ещё один КА на кассу, с активной услугой ОФД невозможно.
КА для массового применения услуг ОФД закрепляется за одним партнером:
- на ККТ присваивается код партнера в соответствии с КА.
- КА чужого партнера применить на ККТ не возможно.

3.Список статусов оплаты

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

GET https://ofd.ru/api/integration/partner/v1/kkt/paystatus?AuthToken={authToken}&DateFromUtc={dateFrom}&DateToUtc={dateTo}

В методе используются следующие параметры описанные в таблице 2.

Таблица 2. Описание параметров API-запросов

Параметр	Формат значения	Описание	Признак обязательности в запросе⁵⁾
AuthToken	String	Значение действующего кода авторизации, полученный в результате запроса авторизации.	Да
DateFromUtc	String	Дата и время начала поиска	Да
DateToUtc	String	Дата и время конца поиска	Да

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

{
    "Data": [
        {
            "DateUtc": "2022-10-24T19:07:35",
            "Inn": "616111397436",
            "Rnm": "12345678901234",
            "ActivationCode": "LSZ7D1LD",
            "Status": "WaitingActivation"
        }
    ],
    "Success": true
}

Описание параметров ответа представлено в таблице 3.

Таблица 3. Описание параметров ответа на API-запрос

Параметр	Вложенный параметр	Формат значения	Описание
Data		Array	Массив данных со списком касс с примененным КА
		Object	Структура данных по кассе с примененным КА
	DateUtc	String	Дата и время отправки запроса
	Inn	String	ИНН клиента
	Rnm	String	Регистрационный номер кассы (РНМ) клиента
	ActivationCode	String	код активации услуг ОФД
	Status	String	Статус КА. В параметре могут быть следующие значения:
			Undefined - Не определено
			WaitingActivation - Ожидание активации ККТ
			Payed - ККТ оплачена
			Cancelled - Отмена
	ActivationDateUtc	String	Дата и время применения кода
Success		Boolean	Статус выполнения запроса

4. Получение списка касс клиентов

Метод получения списка касс клиентов имеет следующий вид:

GET https://ofd.ru/api/integration/partner/v1/inn/{inn}/kkts?AuthToken={authToken}

В методе используются следующие параметры описанные в таблице 2.

Таблица 2. Описание параметров API-запросов

Параметр	Формат значения	Описание	Признак обязательности в запросе⁶⁾
AuthToken	String	Значение действующего кода авторизации, полученный в результате запроса авторизации.	Да
inn	String	ИНН партнера	Да

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

{
    "Data": [
        {
            "Id": "60854103-3e26-49d5-942b-07c34f7b9446",
            "KktRegId": "0005792715046206",
            "SerialNumber": "00105703738735",
            "FnNumber": "9960440301038465",
            "CreateDate": "2021-09-01T15:43:28",
            "LastDocOnKktDateTime": "2021-12-13T16:34:00",
            "LastDocOnOfdDateTimeUtc": "2021-12-13T13:37:03",
            "FiscalAddress": "Москва, Ленинская Слобода, 19",
            "FiscalPlace": "ofd.ru",
            "KktModel": "АТОЛ 25Ф",
            "FnEndDate": "2022-11-25T15:43:57",
            "ContractStartDateUtc": "2021-09-01T00:00:00"
        }
    ],
    "Success": true
}

Описание параметров ответа представлено в таблице 3.

Таблица 3. Описание параметров ответа на API-запрос

Параметр	Вложенный параметр	Формат значения	Описание
Data		Array	Массив данных со списком касс клиентов партнера
		Object	Структура данных по кассе
	Id	String	Идентификатор кассы
	KktRegId	String	РНМ - регистрационный номер кассы
	SerialNumber	String	Заводской номер кассы
	FnNumber	String	Заводской номер фискального накопителя
	CreateDate	String	Дата регистрации кассы в личном кабинете клиента
	LastDocOnKktDateTime	String	Дата и время⁷⁾ последнего документа, сгенерированного кассой
	LastDocOnOfdDateTimeUtc	String	Дата и время⁸⁾ получения последнего документа кассы в ОФД
	FiscalAddress	String	Адрес установки кассы
	FiscalPlace	String	Место расчетов
	KktModel	String	Модель кассы (ККТ)
	FnEndDate	String	Дата и время⁹⁾ окончания работы фискального накопителя
	Tariff	String	Тарифный план:
			«Red»
			«Yellow»
			«Green»
			«Blue»
			«Orange»
	LastBuyDateUtc	String	Оплата услуги ОФД
	ContractStartDateUtc	String	Дата и время¹⁰⁾ начало предоставления услуги ОФД
	ContractEndDateUtc	String	Дата и время¹¹⁾ окончания предоставления услуги ОФД
Success		Boolean	Статус выполнения запроса

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

Версия 1.00
Выпущена 28.отктября.2022 г.
Первая версия документа.

Версия 1.01
Выпущена 22 февраля 2023 г.
Добавлено описание запрос на получение списка касс клиентов, привязанных к партнёрскому аккаунту.

¹⁾

Значение параметра «AuthToken» представлено в строковом виде, представляет собой 32-значную последовательность шестнадцатеричных цифр, используется в запросах к API массового продления услуги ОФД

²⁾ , ⁸⁾

Значение параметра «ExpirationDateUtc» представлено в строковом виде в формате даты и времени (UTC+3, МОСКОВСКОЕ ВРЕМЯ).
Время представлено в формате «ГГГГ-ММ-ДДTчч:мм:сс». Формат даты и времени соответствует международному стандарту ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601).
Формат представления времени выводится без смещения часовых поясов (Time Zone Offset) и интервалов. Формат даты и времени имеет следующую структуру:
ГГГГ - год;
ММ - месяц;
ДД - день;
T - используется как разделитель даты и времени;
чч - часы;
мм - минуты;
сс - секунды.

³⁾ , ⁵⁾ , ⁶⁾

Да/Нет

⁴⁾

Если его нет

⁷⁾ , ⁹⁾ , ¹⁰⁾ , ¹¹⁾

Дата и время в формате стандарта ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Здесь используется только формат представления времени без задания смещения часовых поясов (Time Zone Offset) и интервалов.