Программный интерфейс приложений (API) для работы с ИС “Ferma”

Введение

В документе приводятся технические сведения о программном интерфейсе приложений (API) предоставляющем возможность регистрировать онлайн-кассы и инициировать генерацию кассовых документов посредством информационной системы (ИС) “Ferma”.

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

Ниже описаны запросы HTTP, которыми реализуются функции API по работе с онлайн-кассами.

1. Общий вид запроса и ответа в процессеиспользования API

Кодировка, используемая в запросах и ответах – UTF-8. Запросы выполняются методом POST, параметры запроса передаются в JSON структуре, передаваемой в блоке данных запроса.

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

{
"Status": "Success",
"Data": {}
}

Здесь ключу "Data" соответствует пустое поле; ключ введен в структуру для обеспечения единообразия запросов в ИС “Ferma”; параметр "Status" – состояние обработки запроса – в данном случае имеет значение "Success" (запрос обработан успешно).

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

{
"Status": "Failed",
"Error": {
Code: 0,
Message: "string"
}
}

Здесь ключу "Error" соответствует объект, в котором присутствуют код и сообщение об ошибке; код ошибки всегда отличен от 0; на месте строки"string" будет сообщение об ошибке, возникшей при обработке переданных данных. параметр "Status" в данном случае имеет значение "Failed" (обработка запроса не удалась).

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

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

--- BEGIN ---
POST https://ferma.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, который в случае успешной авторизации будет иметь код равный 200 и содержать структуру, подобную следующей (приведены примеры значений):

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

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

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

ГГГГ	–	год даты, 4 цифры,
ММ	–	месяц даты, 2 цифры,
ДД	–	день даты 2 цифры,
T	–	заглавная латинская буква “T”, используется как разделитель даты и времени,
чч	–	часы, 2 цифры,
мм	–	минуты, 2 цифры,
сс	–	секунды, 2 цифры.

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

POST /api/kkt/cloud/receipt?AuthToken=Code1

здесь Code1 – действующий код авторизации, полученный в результате запроса авторизации.

3. HTTP-запросы к ИС “Ferma” для работыс онлайн-кассами

3.1. Формирование кассового чека

Вид запроса: POST /api/kkt/cloud/receipt. Тело запроса представляет собой структуру JSON, содержащую необходимые параметры и имеющую следующий обобщенный вид:

{
"Request": {
"Inn": "string",
"Type": "string",
"InvoiceId": "string",
"LocalDate": "2017-01-24T14:13:24",
"CustomerReceipt": {
"TaxationSystem": "Common",
"Email": "string",
"Phone": "string",
"PaymentAgentInfo": {
"AgentType": "BANK_PAYMENT_AGENT",
"TransferAgentPhone": "89061234567",
"TransferAgentName": "наименование оператора перевода",
"TransferAgentAddress": "адрес оператора перевода",
"TransferAgentINN": "1234567890",
"PaymentAgentOperation": "операция платежного агента",
"PaymentAgentPhone": "89061234567",
"ReceiverPhone": "89061234567",
"SupplierPhone": "89061234567"
}
"CorrectionInfo": {
"Type": "SELF",
"Description": "Неприменение ККТ",
"ReceiptDate": "20.07.18",
"ReceiptId": "123456"
}
"Items": [
{
"Label": "string",
"Price": 0,
"Quantity": 0,
"Amount": 0,
"Vat": "string"
}, ...
]
}
}
}

Параметры структуры приведены в таблице 2.

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

Ключ	Формат значения	Описание
Request	структура	Параметры запросы на формирование кассового документа
Inn	строка	ИНН лица, от имени которого генерируется кассовый документ (чек)
Type	строка	Тип формируемого документа (чек), см. п. 3.1.2
InvoiceId	строка	Идентификатор счета, на основании которого генерируется чек
LocalDate	строка, описывающая момент времени (дату и время)	Локальная дата и время чека
CustomerReceipt	структура	Содержимое клиентского чека
TaxationSystem	строка	Система налогообложения
Email	строка	Адрес электронной почты клиента
Phone	строка	Контактный телефон клиента
PaymentAgentInfo	структура	Структура, содержащая данные платежного агента
AgentType	строка	Тип (признак) платежного агента тег 1057, возможные значения: BANK_PAYMENT_AGENT — банковский платежный агент; BANK_PAYMENT_SUBAGENT — банковский платежный субагент; PAYMENT_SUBAGENT — платежный субагент CONFIDANT — поверенный; COMMISSIONER — комиссионер; AGENT — агент
TransferAgentPhone	строка	Номер телефона платежногоагента, тег
TransferAgentName	строка	Имя агента
TransferAgentAddress	строка	Адрес агента
TransferAgentINN	строка	ИНН агента
PaymentAgentOperation	строка	Операция платежного агента
PaymentAgentPhone	строка	Телефон платежного агента
ReceiverPhone	строка	Телефон потребителя
SupplierPhone	строка	Телефон поставщика
CorrectionInfo	структура	Структура, описывающая информацию по чеку коррекции. Внимание! Структура присутствует в данных только в случае генерации чека коррекции. Для генерации обычного чека данная структура не нужна.
Type	строка	Тип коррекции:
Description	строка	Описание коррекции и причин коррекции
ReceiptDate	строка	Дата коррекции в формате "ДД.ММ.ГГ", здесь ДД — день, ММ — месяц, ГГ — год.
ReceiptId	строка	Идентификатор чека, к которому применяется чек коррекции
Items	массив структур	Товарные позиции, приобретаемые клиентом
Label	строка	Название товарной позиции
Price	число с точкой	Цена товарной позиции, в рублях
Quantity	число с точкой	Количество товара в товарной позиции
Amount	число с точкой	Общая стоимость товара в товарной позиции в рублях
Vat	строка	Вид вычисляемого НДС см. п. 3.1.1

Все вышеуказанные поля являются необходимыми, за исключением полей Email и Phone, здесь необходимым является наличие хотя бы одного из них.

В случае успеха ответ имеет следующий вид:

{
"Status": "Success",
"Data": {
"ReceiptId": "string"
}
}

Параметры структуры «Data» приведены в таблице 3.

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

Ключ	Формат значения	Описание
ReceiptId	строка, содержащая UUID	Идентификатор чека для дальнейшего запроса состояния

3.1.1. Возможные значения вида вычисляемого НДС (поле “Vat”)

• "Vat10" — налог на добавленную стоимость (НДС) 10%;
• "Vat18" — НДС 18%;
• "Vat20" — НДС 20%;
• "Vat0" — НДС 0%;
• "VatNo" — НДС не облагается;
• "CalculatedVat10110" — вычисленный НДС 10% от 110% суммы;
• "CalculatedVat18118" — вычисленный НДС 18% от 118% суммы;
• "CalculatedVat20120" — вычисленный НДС 20% от 120% суммы.

3.1.2. Типы формируемых чеков

• "Income" — получение денежных средств от покупателя;
• "IncomeReturn" — возврат денежных средств, полученных от покупателя;
• "IncomePrepayment" — авансовый платеж от покупателя;
• "IncomeReturnPrepayment" — возврат аванса;
• "IncomeCorrection" — чек коррекции;
• "Expense" — выдача денежных средств покупателю;
• "ExpenseReturn" — возврат денежных средств, выданных покупателю.

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

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

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

3.1.4. Условия успешного формирования чека

Сформированный чек будет считаться корректным, если он соответствует следующим условиям:

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

3.1.5. Возможные ошибки

• «Не найдены данные компании с ИНН Y», где Y — значение ИНН;
• «Доступ запрещен»;
• «Ошибка создания чека: X», где X — сообщение сервера системы;
• «Превышено максимальное количество обращений», максимальное количество сообщений рассчитывается по максимальной допустимой нагрузке на кассу: один чек в 3 секунды.

3.2. Проверка статуса кассового чека

Важно! Информация о статусе имеет срок годности (сутки), после которого перестает быть доступна. После истечения этого срока, при попытке запроса статуса вернется ошибка «Чек не найден». Это означает, что информация по данному чеку удалена из оперативной памяти для освобождения ресурсов, но она остается доступна при помощи запроса реестра кассовых чеков (3.3).

Вид запроса: POST /api/kkt/cloud/status. Тело запроса представляет собой структуру JSON, содержащую необходимые параметры и имеющую следующий обобщенный вид:

{
"Request": {
"ReceiptId": "string"
}
}

Параметры структуры приведены в таблице 3.

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

Ключ	Формат значения	Описание
Request	структура	Параметры запроса статуса кассового документа
ReceiptId	строка	Идентификатор чека, полученный из запроса на формирование кассового документа

В случае успеха ответ имеет следующий вид:

{
"Status": "Success",
"Data": {
"StatusCode": 1,
"StatusName": "PROCESSED",
"StatusMessage": "Чек сформирован на кассе",
"ModifiedDateUtc": "2017-01-24T14:13:24",
"ReceiptDateUtc": "2017-01-24T14:13:24",
"Device": {
"DeviceId": "string",
"RNM": "string",
"ZN": "string",
"FN": "string",
"FDN": "string",
"FDP": "string",
}
}
}

Параметры структур Data и Device приведены соответственно в таблицах 3.1 и 3.2.

Таблица 3.1 Параметры структуры данных информации о кассовом чеке

Ключ	Формат значения	Описание
StatusCode	Число	Код статуса
StatusName	строка	Название статуса
StatusMessage	строка	Необязательный параметр, содержащий дополнительную информацию о текущем состоянии, может отсутствовать
ModifiedDateUtc	строка, описывающая момент времени (дату и время в формате UTC)	Дата и время последнего обновления информации о чеке
ReceiptDateUtc	строка, описывающая момент времени (дату и время в формате UTC)	Дата и время, указанные в чеке
Device	структура	Информация об устройстве (ККТ), на котором была произведена операция

Возможные значения:

• запрос на чек принят ИС «Ferma»:

"StatusCode": 0,
"StatusName": "NEW",
"StatusMessage": "запрос на чек принят Фермой",

• чек сформирован на кассе:

"StatusCode": 1,
"StatusName": "PROCESSED",
"StatusMessage": "чек сформирован на кассе",

• чек передан в ОФД:

"StatusCode": 2,
"StatusName": "CONFIRMED",
"StatusMessage": "чек передан в ОФД"
Таблица 3.2 Параметры структуры данных информации о ККТ

Ключ	Формат значения	Описание
DeviceId	строка	Сервисный идентификатор устройства, на котором генерируется кассовый документ (чек)
RNM	строка	Регистрационный номер кассы
ZN	строка	Заводской номер кассы
FN	строка	Номер фискального накопителя, установленного в кассу
FDN	строка	Номер фискального документа
FPN	строка	Фискальный признак документа

3.3. Запрос реестра кассовых чеков

Вид запроса: POST /api/kkt/cloud/list. Тело запроса представляет собой структуру JSON, содержащую необходимые параметры и имеющую следующий обобщенный вид:

{
"Request": {
"ReceiptId": "e0d2212f-4e85-475a-8e6e-c533f233e1d9",
"StartDateUtc": "2017-01-24T14:13:24",
"EndDateUtc": "2017-01-24T14:13:24",
"StartDateLocal": "2017-01-24T14:13:24",
"EndDateLocal": "2017-01-24T14:13:24"
}
}

В случае наличия не пустого параметра "ReceiptId" остальные могут отсутствовать; в случае наличия не пустых параметров "StartDateUtc" и "EndDateUtc" остальные могут отсутствовать; в случае наличия не пустых параметров "StartDateLocal" и "EndDateLocal" остальные могут отсутствовать. Параметры структуры приведены в таблице 4.

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

Ключ	Формат значения	Описание
Request	структура	Параметры запроса статуса кассового документа
ReceiptId	строка в формате UUID	Идентификатор чека, полученный из запроса на формирование кассового документа
StartDateUtc	строка, описывающая момент времени (дату и время в формате UTC)	Дата и время начала интервала
EndDateUtc	строка, описывающая момент времени (дату и время в формате UTC)	Дата и время окончания интервала
StartDateLocal	строка, описывающая момент времени (дату и время)	Локальная дата и время начала интервала
EndDateLocal	строка, описывающая момент времени (дату и время)	Локальная дата и время окончания интервала

В случае успеха ответ имеет следующий вид:

{
"Status": "Success",
"Data": [
{
"ReceiptId": "e0d2212f-4e85-475a-8e6e-c533f233e1d9",
"StatusCode": 1,
"StatusName": "Чек сформирован на кассе",
"StatusMessage": "PROCESSED",
"ModifiedDateUtc": "2017-01-24T14:13:24",
"InvoiceID": "50000249010"
}, ...
]
}

Параметры структуры элементов массива «Data» приведены в таблице 4.1.

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

Ключ	Формат значения	Описание
ReceiptId	строка	Идентификатор чека, полученный из запроса на формирование кассового документа
StatusCode	Число	Код статуса
SatusName	строка	Название статуса
SatusMessage	строка	Необязательный параметр, содержащий дополнительную информацию о текущем состоянии, может отсутсвовать
ModifiedDateUtc	строка, описывающая момент времени (дату и время в формате UTC)	Дата и время последнего обновления информации о чеке
InvoiceID	строка	Идентификатор (номер) счета, связанного с кассовым документом (Идентификатор чека со стороны клиента)

4. Коды ошибок

HTTP Код	Код ошибки	Описание ошибки
401	1001	Клиент не авторизован
500	1002	Непредвиденная ошибка
400	1003	Некорректный формат запроса
404	1004	Объект не найден
500	1	Неизвестная ошибка
500	2	Неверный логин, пароль
500	3	Нет свободных касс
500	4	Нет авторизации
400	1005	Объект Request пустой
400	1006	Объект CustomerReceipt пустой
400	1007	Некорректный ИНН
400	1008	Некорректный тип формируемого чека (Type)
400	1009	Некорректный идентификатор счета (InvoiceId)
400	1010	Некорректный тип налогообложения (TaxationSystem)
400	1011	Некорректно заполнены контакты (Email, Phone)
400	1012	Некорректный адрес электронной почты
400	1013	Некорректный номер телефона
400	1014	Некорректно заполнены позиции (Items)
400	1015	Цена и общая стоимость не должны быть отрицательными
400	1016	Количество товаров в позиции не должно быть отрицательным
400	1017	Некорректно заполнен НДС позиции (Vat)
400	1018	Общая сумма позиций должна быть неотрицательной
400	1019	Идентификатор счета уже существует (InvoiceId, ReceiptId)
400	1020	Превышено максимальное количество обращений
400	1021	Неверно указан телефон платежного агента
400	1022	Неверно указан телефон поставщика
400	1023	Неверно указан телефон оператора перевода
400	1024	Неверно указан ИНН оператора перевода
400	1025	Неверно указан признак платежного агента
400	1026	Длина поля PaymentAgentInfo.TransferAgentName превышает максимальную длину в 64 символа
400	1027	Длина поля PaymentAgentInfo.TransferAgentAddress превышает максимальную длину в 256 символов
400	1028	Длина поля PaymentAgentInfo.PaymentAgentOperation превышает максимальную длину в 24 символа
400	1029	Нет касс соответствующих переданному типу платёжного агента
400	1030	Не указано описание коррекции (CorrectionInfo.Description)
400	1031	Некорректный формат даты совершения корректируемого расчёта
400	1032	Неверно указан тип коррекции (CorrectionInfo.Type)

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

Версия 2.0

Выпущена 24 августа 2018 г.

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

Версия 2.1

Выпущена 14 ноября 2018 г.

• исправлены ошибки по тексту предыдущей версии документа;
• добавлена информация о новым значениях констант типов НДС.

Версия 2.2

Выпущена 17 января 2019 г.

• исправлена ошибка в тексте предыдущей версии документа: замена строки «FPD» на «FDP» в примерах структур данных.

Версия 2.3

Добавлена 28 января 2019 г.

• добавлена информация в соответствии с изменениями в структуре данных CustomerReceipts.