Программный интерфейс приложений (API) обслуживания касс ИС «OFD.RU» для партнеров

В документе приводятся технические сведения о программном интерфейсе приложений (API), предоставляющем возможность сторонним (клиентским) веб-приложениям выполнять регистрацию контрольно-кассовой техники (KKT) с помощью асинхронных HTTP-запросов к ИС «OFD.RU».

Обмен данными происходит по протоколу HTTP с использованием зашифрованного канала (HTTPS). Данные запросов и ответов передаются в виде структуры JSON. Вне зависимости от наличия ошибок в данных, обязательным условием успешного выполнения запроса является ответ с кодом 200 согласно протоколу HTTP.

Для получения токена авторизации, который будет использоваться для выполнения запросов, пользователю необходимо обратиться в раздел «Настройки» в Личном кабинете партнера.

Далее пользователь переходит на вкладку «API для партнеров» и попадает в блок генерации ключей доступа к использованию API 2.0.

• Ключ доступа к API 2.0 (API KEY) предоставляется на личный кабинет организации (уникальную пару ИНН и КПП);
• Блокировка ключа доступа в интерфейсе личного кабинета партнера в случае компрометации;
• Срок действия ключа доступа — неограничен;
• Право на выделение ключа доступа есть у пользователей с полными правами администратора в ЛКП.

Сгенерированный ключ появляется на вкладке «API для партнеров» в блоке «Ваши ключи доступа».

Созданный ключ доступа будет иметь указания данных о датах создания и последней активности, статусе ключа и типе доступа, которое будет использоваться в запросах API 2.0.

Используемое обозначение параметра ключа доступа в запросах — AuthToken={Code}

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

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

• Code — действующий код авторизации, полученный при авторизации.

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

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

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

{
 "Inn": string,
 "Kpp": string,
 "Rnm": string,
 "ActivationCode": string,
 "Email": string
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для получения списка статусов оплат используется метод «GET».

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

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

Заменяемые параметры:

• {Code} — токен, возвращенный в результате авторизации (см. пп. 1. Авторизация).
• {dateFrom} — начальная дата поиска.
• {dateTo} — конечная дата поиска.

Пример успешного ответа на запрос имеет следующий вид (приведены примеры значений):

{
  "Data": [
    {
      "DateUtc": datetime,
      "Inn": string,
      "Rnm": string,
      "ActivationCode": string,
      "Status": string,
      "ActivationDateUtc": datetime
    }
  ],
  "Success": true
}

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

Таблица 2. Поля структуры ответа на запрос статусов оплат

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

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

• Code — значение действующего кода авторизации, полученного в ЛКК;
• inn — ИНН партнера.

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

{
    "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. Описание параметров ответа на запрос

Для того, чтобы перейти к удаленной оплате услуг и регистрации кассы, партнеру необходимо выполнить запрос на создание личного кабинета клиента с одним пользователем. После создания ЛКК клиенту на E-mail приходит письмо, в котором содержится ссылка для перехода и создания логина и пароля личного кабинета.

POST https://ofd.ru/api/integration/partner/v2/PartnerCreateClientCabinet?AuthToken={Code}

Code — значение действующего кода авторизации, полученного в ЛКК;

Пример запроса:

{
  "Inn": "String",
  "Kpp": "String",
  "CompanyName": "String",
  "Email": "String",
  "Name": "String",
  "Phone": "String",
}

Описание параметров запроса для создания ЛКК представлено в таблице 4.

Таблица 4. Параметры запроса на создание ЛКК

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

{
  "OfdAgreementId": "String"
}

Описание параметра ответа:

• OfdAgreementId — Идентификатор юридического лица клиента, прикрепленного к ЛК OFD.ru.

Возможные ошибки представлены в таблице 5.

Таблица 5. Возможные ошибки в ответе на запрос

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

Эти данные содержатся в одном заказе и привязываются к идентификатору заказа OrderID.

POST https://pre.ofd.ru/api/integration/partner/v2/PartnerBookingKkt?AuthToken={Code}

Пример запроса

{
  "OfdAgreementId": "String",
  "quantity": "Integer",
  "tariffType": "String",
  "fnType": "String",
  "PaymentType": "String"
}

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

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

Пример ответа

{
  "OrderID": "String"
  "OrderReceiptUrl": "String",
}

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

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

Партнер может получить статус заказа посредством запроса статуса бронирования:

GET https://ofd.ru/api/integration/partner/v2/kkt/GetStatus?AuthToken={Code}&OrderID={orderid}

Параметры запроса:

• Code — код полученный во время авторизации;
• orderid — идентификатор заказа

Пример ответа на запрос

{
  "Status": "Integer",
  "DueDate": "String"
}

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

Таблица 8. Поля структуры ответа на запрос статуса заказа

Версия 1.0
Выпущена 20 Февраля 2025 г.
Первая регистрируемая версия документа.