Программный интерфейс приложений (API) заказа и оплаты услуги Ferma®
Введение
Обмен данными происходит по протоколу HTTP с использованием зашифрованного канала (HTTPS). Данные запросов и ответов передаются в виде структуры JSON-схем.
Для авторизации в методах API используется авторизационный токен, представляющий собой строку UUID, которая должна быть передана в запросе в виде AuthToken={Code}.
| Параметр | Формат | Описание |
|---|---|---|
| Code | uuid | Код авторизации: строка символов, представляет собой 32-значную последовательность шестнадцатеричных цифр. Срок действия – 1 год. |
Чтобы получить токен, напишите нам.
Вне зависимости от наличия ошибок в данных, обязательным условием успешного выполнения запроса является ответ с кодом 200 согласно протоколу HTTP.
В документации описаны HTTP-запросы создания личного кабинета клиента (ЛКК), создания заказа и формирования ссылок для оплаты, бронирования требуемого количества касс с выбранными типами тарифов и типами фискальных накопителей.
Заказ и оплата услуги Ferma®
1.1. Метод создания ЛКК с одним пользователем
Для того, чтобы перейти к удаленной оплате услуг и регистрации кассы, партнеру необходимо выполнить запрос на создание личного кабинета клиента с одним пользователем.После создания ЛКК клиенту на E-mail приходит письмо, в котором содержится ссылка для перехода и создания логина и пароля личного кабинета.
{POST} /api/integration/partner/v1/PartnerCreateClientCabinet?AuthToken={Code}
Параметры запроса
| Параметр | Формат | Описание |
|---|---|---|
| Inn | String | ИНН клиента. Длина 10-12 цифр |
| Kpp | String | КПП клиента |
| CompanyName | String | Наименование организации |
| String | Адрес электронной почты клиента | |
| Name | String | Имя пользователя с логином из поля Email. Параметр необязательный |
| Phone | String | Контактный телефон. Параметр необязательный |
Пример запроса
{
"Inn": "String",
"Kpp": "String",
"CompanyName": "String",
"Email": "String",
"Name": "String",
"Phone": "String",
}
Параметры ответа
| Параметр | Формат | Описание |
|---|---|---|
| OfdAgreementId | String | Идентификатор юридического лица клиента, прикрепленного к ЛК OFD.ru |
Пример ответа
{
"OfdAgreementId": "String"
}
Возможные ошибки
| HTTP код | Код ошибки | Описание ошибки | Причина ошибки |
|---|---|---|---|
| 500 | 1 | Неизвестная ошибка | Пользователь или ЛКК с таким Email уже |
| 400 | 1007 | Некорректный ИНН | ЛКК для такого ИНН/КПП уже существует |
1.2. Бронирование касс и передача запроса на формирование ссылки на оплату для нового клиента
Для создания заказа партнер указывает требуемое количество касс, тип тарифа и тип фискального накопителя (общие для всех касс в одном заказе).
Эти данные содержатся в одном заказе и привязываются к идентификатору заказа OrderID.
{POST} /api/integration/partner/v1/PartnerBookingKkt?AuthToken={Code}
Параметры запроса
| Параметр | Формат | Описание | |
|---|---|---|---|
| OfdAgreementId | String | Идентификатор юридического лица клиента, прикрепленного к ЛК OFD.ru | |
| quantity | Integer | Количество касс по выбранным tariffType и fnType | |
| tariffType | String | Тип тарифа на кассе. Возможные значения: | |
| Urgent1M | Количества месяцев | ||
| Urgent6M | |||
| Urgent12M | |||
| Urgent13M | |||
| Urgent15M | |||
| Urgent18M | |||
| Receipt399 | Количества чеков | ||
| Receipt699 | |||
| Receipt999 | |||
| fnType | String | Тип фискального накопителя, установленного в кассу. Возможные значения: | |
| Fn15 | ФН15 | ||
| Fn36 | ФН36 | ||
| PaymentType | String | Способ оплаты заказа | |
Доступными способами оплаты заказа (поля PaymentType) являются:
- Bill - выставление счета;
- CreditCard - оплата картой;
- SBP - оплата по СБП.
Пример запроса
{
"OfdAgreementId": "String",
"quantity": "Integer",
"tariffType": "String",
"fnType": "String",
"PaymentType": "String"
}
Параметры ответа
| Параметр | Формат | Описание |
|---|---|---|
| OfdAgreementId | String | Ссылка на оплату заказа. Возможные значения в зависимости от выбранного PaymentType в заказе |
| OrderID | String | Идентификатор заказа |
Доступными результатами ответа в значении поля OfdAgreementId являются:
- QR-код в формате Base64;
- Ссылка на оплату по карте;
- Ссылка на счет в формате PDF.
Пример ответа
{
"OrderReceiptUrl": "String",
"OrderID": "String"
}
1.3. Запрос статуса заказа
Партнер может получить статус заказа посредством запроса статуса бронирования.
{GET} /api/integration/partner/v1/kkt/GetStatus?AuthToken={Code}
Параметры запроса
| Параметр | Формат | Описание | |
|---|---|---|---|
| OrderID | String | Идентификатор заказа | |
Пример запроса
{
"OrderID": "String"
}
Параметры ответа
| Параметр | Формат | Описание |
|---|---|---|
| Status | Integer | Статус заказа |
| DueDate | String | Дата, до которой на бронировании оплачен тариф, в формате UTC+0 «dd.mm.yyyy HH:MM:SS». |
Доступными результатами ответа в значении поля Status являются:
- 1 – Оплачен;
- 2 – Ожидает оплату;
- 3 – Просрочен.
Параметр DueDate отображается в ответе только в случае значения статуса 1 – Оплачен.
Пример ответа
{
"Status": "Integer",
"DueDate": "String"
}
История изменений
Версия 1.00 от 21.03.2024
Первая публикуемая версия документа.
Версия 1.01 от 27.03.2024
В пункте Введение добавлено описание параметра AuthToken={Code}.
В пункте 1.1. добавлено описание возможных ошибок запроса, обновлено описание параметра Name.
В пункте 1.2. обновлено описание значений типов тарифов и способов оплаты заказа.
Версия 1.02 от 08.04.2024
Обновлено описание параметра OfdReceiptUrl в ответе на запрос 1.2. Бронирование касс и передача запроса на формирование ссылки на оплату для нового клиента.