Конвертер программного интерфейса приложений (API) для «АТОЛ Онлайн»

Версия 1.11 от 07.06.2022 Открыть pdf-файл

Введение

В инструкции описан программный интерфейс приложений (API) конвертера «АТОЛ Онлайн» для облачных касс сервиса «Ferma».

1. Общая информация по API

Кодировка, используемая в запросах и ответах, – UTF-8. Запросы выполняются методами POST и GET, параметры запроса передаются в теле запроса в формата JSON методом POST, также параметры могут передаваться в строке запроса в методах GET.
Сервер отправляет ответы на запрос в формате JSON. Успешный код ответа, по протоколу HTTP равен 200.

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

В конвертере «АТОЛ Онлайн» реализован механизм многократного обращения после одной авторизации без использования механизма Cookies. Механизм реализован с помощью параметра «AuthToken». После авторизации с передачей имени и пароля система возвращает код авторизации – строку символов, параметр авторизации для многократного обращения к сервису «Ferma».

Запрос авторизации можно выполнить методом POST и методом GET.

Запрос получения значения параметра «AuthToken» методом POST имеет следующий вид:

POST https://ferma-at.ofd.ru/possystem/v1/getToken

Тело запроса передается в формате JSON.

Пример тела запроса на получение значения параметра авторизации:

{
    "login": "fermatest1",
    "pass": "Hjsf3321klsadfAA"
}

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

  • login
  • pass

Логин и пароль можно узнать в личном кабинете клиента OFD.ru в разделе «Ferma», после покупки кассы Ferma, либо у вашего менеджера.

Запрос получения значения параметра «AuthToken» методом GET имеет следующий вид:

GET https://ferma-at.ofd.ru/possystem/v1/getToken?login={Login1}&pass={Password1}

В запросе параметры login и pass передаются в строке.

В ответ на API-запрос будет получен ответ по протоколу HTTP. Успешный ответ на запрос авторизации будет иметь код равный 200 и содержать структуру в формате JSON. Пример ответа с кодом 200:

{
    "error":null,
    "token":"fj45u923j59ju42395iu9423i59243u0",
    "timestamp":"30.11.2017 17:58:53"
}

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

  • error - ошибка, если параметр пустой (null), значит запрос был успешно выполнен.
  • token - код авторизации1)
  • timestamp – Время действия токена авторизации.2)

Пример ответа с ошибкой:

{
    "error":{
        "error_id":"4475d6d8d-844d-4d05-aa8b-e3dbdf3defd5",
        "code":12,
        "text":"Неверный логин или пароль",
        "type":"system"
    },
    "timestamp":"15.02.2018 13:00:31"
}

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

  • error - массив данных, содержит информацию об ошибке:
    • error_id - уникальный идентификатор ошибки;
    • code - код ошибки;
    • text - тестовое сообщение ошибки;
    • type - тип ошибки.
  • timestamp – время и дата ошибка.

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

GET https://ferma-at.ofd.ru/possystem/v1/{group_code}/{operation}?token={Code1}

Заменяемые значения параметров:

  • Code1 – действующий код авторизации, полученный в результате запроса авторизации.
  • group_code: идентификатор группы ККТ:
    • параметр можно посмотреть в ЛКК Ferma в виджете «Реквизиты доступа»;
    • для тестовой среды параметр равен 1.

3. Создание чеков

Запрос на создание чеков с использованием конвертера «АТОЛ Онлайн»:

POST https://ferma-at.ofd.ru/possystem/v1/{group_code}/{operation}?token={Code1}

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

  • Code1 – действующий код авторизации, полученный в результате запроса авторизации.
  • group_code - идентификатор группы ККТ, параметр можно посмотреть в ЛКК Ferma в виджете «Реквизиты доступа», для тестовой среды параметр равен 1.
  • operation - тип операции фискальной операции. Типы операции:
    • sell - чек «Приход»;
    • sell_refund - чек «Возврат прихода»;
    • sell_correction - чек «Коррекция прихода»;
    • sell_refund_correction - чек «Коррекция возврата прихода»;
    • buy - чек «Расход»;
    • buy_refund - чек «Возврат расхода»;
    • buy_correction - чек «Коррекция расхода»;
    • buy_refund_correction - чек «Коррекция возврата расхода».

Тело запроса представляет собой структуру JSON, содержащую необходимые параметры и имеющую следующий обобщенный вид:

{
    "timestamp":"String"
    "external_id": "String",
    "service": {
        "callback_url": "String"
          },
    "receipt"/"correction": {
        "client": {
          "email": "String",
          "phone": "String",
          "name": "String",
          "inn": "String",
          "birthdate": "String",
          "citizenship": "String",
          "document_code": "String",
          "document_data": "String",
          "address": "String"
         },
        "company": {
          "email": "String",
          "sno": "String",
          "inn": "String",
          "payment_address": "String"
         },
        "correction_info": {
          "type": "String",
          "base_date": "String",
          "base_number": "String"
         },
        "agent_info": {
            "type": "String",
            "paying_agent": {
                "operation": "String",
                "phones": [
                    "String"
                ]
               },
            "receive_payments_operator": {
                "phones": [
                    "String"
                ]
               },
            "money_transfer_operator": {
                "phones": [
                    "String"
                ],
                "name": "String",
                "address": "String",
                "inn": "String"
               },
         }
        "supplier_info": {
            "phones": [
                    "String"
                     ]
          },
        "items": [{
            "name": "String",
            "price":  Float point,
            "quantity": Float point,
            "sum": Float point,
            "measure": "String",
            "payment_method": "String",
            "payment_object": "String",
            "nomenclature_code": "String",
            "vat": {
                "type": "String",
                "sum": Float point
                },
            "mark_quantity": {
                "numerator": Integer,
                "denominator": Integer
                },
            "mark_processing_mode": "String",
            "sectoral_item_props": [{
                "federal_id": "String",
                "date": "String",
                "number": "String",
                "value": "String"
                }],
            "mark_code": {
              "gs1m": "String"
              },
            "agent_info": {
                "type": "String",
                "paying_agent": {
                    "operation": "String",
                    "phones": [
                        "String"
                    ]
					},
                "receive_payments_operator": {
                    "phones": [
                        "String"
                    ]
                    },
                "money_transfer_operator": {
                    "phones": [
                        "String"
                    ],
                    "name": "String",
                    "address": "String",
                    "inn": "String"
		        }
             },
            "supplier_info": {
                 "phones": [
                        "String"
                    ],
                 "name": "String",
                 "inn": "String"
					},
            "user_data": null,
            "excise": Float point,
            "country_code": "String",
            "declaration_number": "String",
            "agent_info": {
              "type": "String",
              "paying_agent": {
                "operation": "String",
                "phones": [
                    "String"
                  ]
                  },
                "receive_payments_operator": {
                 "phones": [
                    "String"
                  ]
                  },
                "money_transfer_operator": {
                  "phones": [
                    "String"
                 ],
                  "name": "String",
                  "address": "String",
                  "inn": "String"
                  }
              }  ,
            "supplier_info": {
              "phones": [
                    "String"
                     ],
              "name": "String",
              "inn": "String"
                     },
              }],
        "payments": [{
                "type": Integer,
                "sum": Float point
            }],
        "vats": [{
                "type": "String",
                "sum": Float point
            }],
        "total": Float point,
        "additional_check_props": "String",
        "cashier": "String",
        "cashier_inn": "String",
        "additional_user_props": {
            "name": "String",
            "value": "String"
         },
        "operating_check_props": {
                "name": "String",
                "value": "String",
                "timestamp": "String"
                },
        "sectoral_check_props": [{
                "federal_id": "String",
                "date": "String",
                "number": "String",
                "value": "String"
                }]
     },
    "service": {
        "callback_url": "String"
     },
}

3.1. Описание параметров запроса

Таблица 3.1. Описание признака необходимости параметра в запросе

Значение Описание
1 Реквизит должен быть в составе ФД
2 Реквизит должен быть в составе ФД, в случаях указанных в приказе ФНС от 14.09.2020г. № ЕД-7-20/662@ в примечании к указанному реквизиту может не включатся в состав ФД.
3 Реквизит может не включаться в состав ФД

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

Таблица 3.2. Описание параметров запроса на пробитие фискального документа в сервисе «Ferma»

Параметр Вложенный параметр Вложенный параметр Формат значения Описание Тег Обязательность3)
external_id String Уникальный идентификатор документа. Важно! Если данный external_id известен системе, будет возвращен UUID, ранее присвоенный этому чеку, иначе чек добавится в систему с присвоением нового UUID. Если изменить external_id возможно задвоение чека 1
receipt/correction Object Кассовый чек, БСО/Кассовый чек коррекции, БСО коррекции 1
client Object Информация о покупателе 1256 2
email4) String Электронная почта покупателя 1008 2
phone5) String Телефон покупателя.
Внимание! При передачи значения телефона покупателя в парметре указывайте по маске +7ХХХХХХХХХХ. Если вы неверно укажите номер чек не будет отправлен покупателю. Если значение в параметра «phone» будет отсутствовать, чек будет направлен покупателю на указанный адрес электронной почты в параметре «email». Если в параметрах «phone» и «email» будут отсутствовать значения то чек покупателя будет отправлен на электронный адрес указанный при регистрации в сервисе «Ferma».
name String Наименование покупателя 1227 26)
inn String ИНН покупателя 1228 27)
birthdate String Дата рождения покупателя (клиента). В формате «ДД.ММ.ГГ», где ДД — день, ММ — месяц, ГГ — год. 1243 28)
citizenship String Гражданство покупателя (клиента) 1244 29)
document_code String Код вида документа, удостоверяющего личность покупателя (клиента). Описание значений представлено в разделе 3.4. 1245 210)
document_data String Данные документа, удостоверяющего личность покупателя (клиента) 1246 211)
address String Адрес покупателя (клиента) 1254 212)
company Object Информация о компании
email String Электронная почта компании 1117 2
sno String Система налогообложения: 1055 1
«osn» – общая СН;
«usn_income» – упрощенная СН (доходы);
«usn_income_outcome» – упрощенная СН (доходы минус расходы);
«envd» – единый налог на вмененный доход;
«esn» – единый сельскохозяйственный налог;
«patent» – патентная СН
inn String ИНН компании 1018 1
payment_address String Место расчета 1187 1
correction_info Object Сведения о коррекции чека 213)
type String Тип коррекции. Может принимать следующие значения: 1173 2
«self» – самостоятельная операция;
«instruction» - операция по предписанию налогового органа
об устранении выявленного нарушения законодательства РФ о применении ККТ
base_date String Дата совершения корректируемого расчета в формате: «dd.mm.yyyy». 1178 2
base_number String Номер документа основания для коррекции 1179 2
agent_info14) Object Параметр со значениями о платежном агенте. Описание параметра «agent_info» приведены в таблице 3.4 1223 2
supplier_info15) Object Информация о поставщике 216)
phones Array Телефоны поставщика 1171 2
String
name String Наименование поставщика 1225 2
inn String ИНН поставщика 1226 2
items Array Товарные позиции, приобретаемые клиентом. Параметры элементов структуры «items» приведены в таблице 3.3 1059 1
Object
payments Array Применяемые оплаты. Ограничение по количеству от 1 до 10
Object
type Integer Тип оплаты может принимать параметры: 1
«0» – наличные; 1031
«1» – безналичные; 1081
«2» – предварительная оплата (зачет аванса и/или предыдущих платежей); 1215
«3» – постоплата (кредит); 1216
«4» – иная форма оплаты (встречное предоставление); 1217
«5» – «9» – расширенные виды оплаты.
Для каждого фискального типа оплаты можно указать расширенный вид оплаты
sum Float point Сумма к оплате в рублях: 1
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков
vats Array Информация о применяемых налогах.
В параметре передаются значения сумм налога каждой позицию,
если позиции в чеке рассчитываются по различным налоговым ставкам или сумму налога рассчитанную на все позиции в чеке, если сумма налога была рассчитана по одной налоговой ставке.
3
Object
type String Тип налоговой ставки. Параметр может принимать следующие значения:
«none» – без НДС; 1105
«vat0» – НДС по ставке 0%; 1104
«vat10» – НДС чека по ставке 10%; 1103
«vat110» – НДС чека по расчетной ставке 10/110; 1107
«vat20» – НДС чека по ставке 20%; 1102
«vat120» – НДС чека по расчетной ставке 20/120. 1106
sum Float point Сумма налога в рублях: 1199 1
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков
total Float point Значение суммы чека. 1020 1
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
additional_check_props String Дополнительный реквизит чека. Максимальная длина строки – 16 символов 1192 3
cashier String ФИО кассира. Максимальная длина строки – 64 символа 1021 2
cashier_inn String ИНН кассира. 1203 3
additional_user_props Object Дополнительный реквизит пользователя 1084 3
name 17) String Наименование дополнительного реквизита пользователя. Максимальная длина строки – 64 символа 1085 3
value 18) String Значение дополнительного реквизита пользователя. Максимальная длина строки – 256 символов 1086 3
operating_check_props Object Операционный реквизит чека 1270 3
name String Идентификатор операции 1271 2
value String Данные операции 1272 2
timestamp String Дата и время операции 1273 2
sectoral_check_props Array Отраслевой реквизит чека 1261 3
Object
federal_id String Идентификатор ФОИВ (ФЕДЕРАЛЬНЫЕ ОРГАНЫ ИСПОЛНИТЕЛЬНОЙ ВЛАСТИ). Может принимать значения от 001 до 072. Описание значений представлено в разделе 3.5 1262 2
date String Дата документа основания.
Формат «ДД.ММ.ГГ», где ДД — день, ММ — месяц, ГГ — год.
1263
number String Номер документа основания 1264 2
value String Значение отраслевого реквизита 1266 2
service Object Служебный раздел 3
callback_url String URL-адрес. В параметре указывается значение URL-адреса. Если поле заполнено корректно, то после обработки документа (успешной или неуспешной фискализации в ККТ: статус «done» или «fail»), ответ будет отправлен POST запросом по URL указанному в данном поле.
Корректность заполненного поля определяется по регулярному выражению:
^http(s?)\:\/\/[0-9a-zA-Zа-яА-Я]([-.\w]*[0-9a-zA-Zа-яА-Я])*(:(0-9)*)*(\/?)([a-zA-Z0-9а-яА-Я\-\.\?\,\'\/\\\+&=%\$#_]*)?$
3
timestamp String Дата и время обработки документа внешней системы.
Дата и время представлена в формате «dd.mm.yyyy HH:MM:SS»
3

3.1.1. Описание параметров "items" ТЕГ 1059

Таблица 3.3 Параметры элементов структуры «items»

Параметр Вложенный параметр Формат значения Описание Тег Обязательность19)
name String Наименование товара. 1030 1
price Float point Цена в рублях: 1079 1
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
Максимальное значение цены – 42 949 672.95
quantity Float point Количество/вес: 1023 1
- целая часть не более 5 знаков;
- дробная часть не более 3 знаков.
Максимальное значение – 99 999.999
sum Float point Сумма в рублях: 1043 1
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
Максимальное значение – 42 949 672.95.
measure Integer Мера измерения товара, работы, услуги, платежа, выплаты, иного предмета расчета.
Значения параметра представлено в разделе 3.6.
2108 1
payment_method 20) String Способ расчёта.
Список всех значение указан в п. 3.2.
1214 1
payment_object Integer Признак предмета расчёта. Список всех значение указан в п. 3.3. 1212 1
vat Object Налог на позицию. Необходимо передать либо сумму налога на позицию, либо сумму налога на чек. Если будут переданы и сумма налога на позицию и сумма налога на чек, сервис учтет только сумму налога на чек 1
type String Тип налоговой ставки. Параметр может принимать следующие значения:
«none» – без НДС; 1105
«vat0» – НДС по ставке 0%; 1104
«vat10» – НДС чека по ставке 10%; 1103
«vat110» – НДС чека по расчетной ставке 10/110; 1107
«vat20» – НДС чека по ставке 20%; 1102
«vat120» – НДС чека по расчетной ставке 20/120. 1106
sum Float point Сумма налога позиции в рублях:
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков
1200 1
agent_info21) Object Структура, содержащая данные платежного агента. Параметры элементов структуры «agent_info» приведены в таблице 3.4 1223 2
supplier_info22) Object Информация о поставщике
phones Array Телефоны поставщика 1171 2
name String Наименование поставщика 1225 2
inn String ИНН поставщика 1226 2
user_data String Дополнительный реквизит предмета расчета 1191
excise Float point Сумма акциза в рублях 1229 223)
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков;
- значение не может быть отрицательным
country_code String Цифровой код страны происхождения товара. Если переданный код страны происхождения имеет длину меньше 3 цифр, то он дополняется справа пробелами 1230 224)
declaration_number String Номер таможенной декларации. Не более 32 символов 1231 225)
mark_quantity Object Дробное количество маркированного товара 1291 226)
numerator Integer Числитель дробной части маркированного товара 1293
denominator Integer Знаменатель дробной части маркированного товара 1294
mark_processing_mode String Товар подлежит обязательной маркировке средством идентификации. Значение должно быть равно «0» 2102 3
sectoral_item_props Array Отраслевой реквизит чека. Содержит сведения о нормативных актах. 1260 227)
Object
federal_id String Идентификатор ФОИВ (ФЕДЕРАЛЬНЫЕ ОРГАНЫ ИСПОЛНИТЕЛЬНОЙ ВЛАСТИ). Может принимать значения от 001 до 072. Описание значений представлено в разделе 3.5 1262
date String Дата нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита. Формат «ДД.ММ.ГГ», где ДД — день, ММ — месяц, ГГ — год. 1263
number String Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита 1264
value String Состав значений, определенных нормативным актом федерального органа исполнительной власти 1265
mark_code Object Сведения о товаре с обязательной маркировкой определенной товарной группы. 1163 228)
unknown String Код товара, формат не идентифицирован 1300
ean8 String Код товара в формате EAN-8 1301
ean13 String Код товара в формате EAN-13 1301
itf14 String Код товара в формате ITF-14 1303
gs1m String Код товара в формате GS1 нанесенный на товар. Товар подлежит (не подлежит) маркировке средствами идентификации 1304
1305
short String Код товара в формате короткого кода маркировки, нанесенный на товар. Товар подлежит маркировке средствами идентификации 1306
fur String Контрольно-идентификационный знак мехового изделия. Ровно 20 символов, должно соответствовать маске СС-ЦЦЦЦЦЦ-СССССССССС 1307
egais20 String Код товара в формате ЕГАИС-2.0. 1308
egais30 String Код товара в формате ЕГАИС-3.0. 1308

3.1.2. Описание параметров "agent_info" ТЕГ 1223

Параметр используется если в реализации товара участвует поставщик или посредник.

Таблица 3.4 Параметры элементов структуры «agent_info»

Параметр Вложенный параметр Формат значения Описание Тег Обязательность29)
type String Тип (признак) платежного агента. Возможные значения: 1057 2
«bank_paying_agent» – банковский платежный агент.
«bank_paying_subagent» – банковский платежный субагент.
«paying_agent» - платежный агент.
«paying_subagent» – платежный субагент.
«attorney» – поверенный.
«commission_agent» - комиссионер.
«another» – другой тип агента
paying_agent Object Информация о платежной агенте
operation String Наименование операции 1044 2
phones Array Телефоны платежного агента 1073 2
String
receive_payments_operator Object Информация об операторе по приему платежей
phones Array Телефоны оператора по приему платежей 1074 2
String
money_transfer_operator Object Информация об операторе перевода
phones Array Телефон оператора перевода.
Передается только один номер телефона
1075 2
String
name String Наименование оператора перевода 1026 2
address String Адрес оператора перевода 1005 2
inn String ИНН оператора перевода 1016 2

3.1.3. Описание ответа на запрос

В ответ на POST запрос возвращается структура данных в формате JSON, содержащая уникальный идентификатор, присвоенный данному документу и статус.
Параметры элементов структуры ответа описаны в таблице 3.5.
Способы получения результатов обработки документа по уникальному идентификатору описаны в разделе 4. Пример ответа:

{
  "uuid": "2ea26f17–0884–4f08–b120–306fc096a58f",
  "timestamp": "12.04.2017 06:15:06",
  "error": null,
  "status": "wait",
}

Пример ответа с ошибкой:

{
  "timestamp": "12.04.2017 06:15:06",
  "status": "fail",
  "error": {
     "error_id": "475d6d8d-844d-4d05-aa8b-e3dbdf4defd6",
     "code": 30,
     "text": " Передан некорректный UUID : \"{0}\". Необходимо повторить запрос с корректными данными ",
     "type": "system"
   }
}

Таблица 3.5 Описание параметров ответа на запрос

Параметр Вложенный параметр Формат значения Описание
uuid Строка Уникальный идентификатор. Максимальная длина строки – 128 символов. Если документ не удалось зарегистрировать, документу не будет присвоен UUID
timestamp Дата и время Дата и время документа внешней системы в формате:
«dd.mm.yyyy HH:MM:SS»
status Строка Статус. Возможные значения:
«fail» – ошибка;
«wait» – ожидание
error Структура Описание ошибки
error_id Строка Уникальный идентификатор ошибки
code Целое число Код ошибки. Отображается только при ошибке. Если параметр присутствует, то со значением «fail» или «wait»
text Строка Текст ошибки (кодировка utf–8)
type Строка Тип источника ошибки. Возможные значения:
«wait» – ожидание;
«system» – системная ошибка;
«unknown» – неизвестная ошибка.

3.2. Значения способа расчёта (Параметр "payment_method")

  • «full_prepayment» – предоплата 100%. Полная предварительная оплата до момента передачи предмета расчета.
  • «prepayment» – предоплата. Частичная предварительная оплата до момента передачи предмета расчета.
  • «advance» – аванс.
  • «full_payment» – полный расчет. Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета.
  • «partial_payment» – частичный расчет и кредит. Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит.
  • «credit» – передача в кредит. Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит.
  • «credit_payment» – оплата кредита. Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита).

3.3. Значения признака предмета расчёта (Параметр "payment_object")

  • 1 — о реализуемом товаре, за исключением подакцизного товара (наименование и иные сведения, описывающие товар) – «ТОВАР» или «Т»;
  • 2 — о реализуемом подакцизном товаре (наименование и иные сведения, описывающие товар) – «ПОДАКЦИЗНЫЙ ТОВАР» или «АТ»;
  • 3 — о выполняемой работе (наименование и иные сведения, описывающие работу) – «РАБОТА» или «Р»;
  • 4 — об оказываемой услуге (наименование и иные сведения, описывающие услугу) – «УСЛУГА» или «У» или может не печататься;
  • 5 — о приеме ставок при осуществлении деятельности по проведению азартных игр – «СТАВКА АЗАРТНОЙ ИГРЫ» или «СТАВКА ИГРЫ» или «СА»;
  • 6 — о выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр – «ВЫИГРЫШ АЗАРТНОЙ ИГРЫ» или «ВЫИГРЫШ АИ» или «ВА»;
  • 7 — о приеме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приеме лотерейных ставок при осуществлении деятельности по проведению лотерей – «ЛОТЕРЕЙНЫЙ БИЛЕТ» или «СТАВКА ЛОТЕРЕИ» или «СЛ»;
  • 8 — о выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей – «ВЫИГРЫШ ЛОТЕРЕИ» или «ВЫИГРЫШ ЛОТЕРЕИ» или «ВЛ»;
  • 9 — о предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации – «ПРЕДОСТАВЛЕНИЕ РИД» или «РИД» (в ред. Приказа ФНС России от 22.10.2018 N ММВ-7-20/605@) (см. текст в предыдущей редакции);
  • 10 — об авансе, задатке, предоплате, кредите, взносе в счет оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчета – «ПЛАТЕЖ» или «П», «ВЫПЛАТА» или «В»;
  • 11 — о вознаграждении пользователя, являющегося платежным агентом (субагентом), банковским платежным агентом (субагентом), комиссионером, поверенным или иным агентом – «АГЕНТСКОЕ ВОЗНАГРАЖДЕНИЕ» или «АВ»;
  • 12 — о предмете расчета, состоящем из предметов, каждому из которых может быть присвоено значение от «1» до «11» – «СОСТАВНОЙ ПРЕДМЕТ РАСЧЕТА» или «СПР»;
  • 13 — о предмете расчета, не относящемуся к предметам расчета, которым может быть присвоено значение от «1» до «12» и от «14» до «18» – «ИНОЙ ПРЕДМЕТ РАСЧЕТА» или «ИПР»;
  • 14 — о передаче имущественных прав – «ИМУЩЕСТВЕННОЕ ПРАВО»;
  • 15 — о внереализационным доходе – «ВНЕРЕАЛИЗАЦИОННЫЙ ДОХОД» или может не печататься;
  • 16 — о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации – «СТРАХОВЫЕ ВЗНОСЫ»;
  • 17 — о суммах уплаченного торгового сбора – «ТОРГОВЫЙ СБОР»;
  • 18 — о курортном сборе – «КУРОРТНЫЙ СБОР»;
  • 19 — о залоге – «ЗАЛОГ»;
  • 20 — о суммах произведенных расходов в соответствии со статьей 346.16 Налогового кодекса Российской Федерации, уменьшающих доход;
  • 21 — о страховых взносах на обязательное пенсионное страхование, уплачиваемых ИП, не производящими выплаты и иные вознаграждения физическим лицам — «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ ПЕНСИОННОЕ СТРАХОВАНИЕ ИП» или «ВЗНОСЫ НА ОПС ИП» или может не печататься;
  • 22 — о страховых взносах на обязательное пенсионное страхование, уплачиваемых организациями и ИП, производящими выплаты и иные вознаграждения физическим лицам — «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ ПЕНСИОННОЕ СТРАХОВАНИЕ» или «ВЗНОСЫ НА ОПС» или может не печататься;
  • 23 — о страховых взносах на обязательное медицинское страхование, уплачиваемых ИП, не производящими выплаты и иные вознаграждения физическим лицам — «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ МЕДИЦИНСКОЕ СТРАХОВАНИЕ ИП» или «ВЗНОСЫ НА ОМС ИП» или может не печататься;
  • 24 — о страховых взносах на обязательное медицинское страхование, уплачиваемые организациями и ИП, производящими выплаты и иные вознаграждения физическим лицам — «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ МЕДИЦИНСКОЕ СТРАХОВАНИЕ» или «ВЗНОСЫ НА ОМС» или может не печататься;
  • 25 — о страховых взносах на обязательное социальное страхование на случай временной нетрудоспособности и в связи с материнством, на обязательное социальное страхование от несчастных случаев на производстве и профессиональных заболеваний — «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ СОЦИАЛЬНОЕ СТРАХОВАНИЕ» или «ВЗНОСЫ НА ОСС» или может не печататься;
  • 26 — о приеме и выплате денежных средств при осуществлении казино и залами игровых автоматов расчетов с использованием обменных знаков игорного заведения — «ПЛАТЕЖ КАЗИНО» или «ПК» или может не печататься;
  • 27 — о выдаче денежных средств банковским платежным агентом — «ВЫДАЧА ДЕНЕЖНЫХ СРЕДСТВ» или «ВЫДАЧА ДС» или может не печататься;
  • 30 — о реализуемом подакцизном товаре, подлежащем маркировке средством идентификации, не имеющем кода маркировки — «АТНМ» или может не печататься;
  • 31 — о реализуемом подакцизном товаре, подлежащем маркировке средством идентификации, имеющем код маркировки — «АТМ» или может не печататься;
  • 32 — о реализуемом товаре, подлежащем маркировке средством идентификации, не имеющем кода маркировки, за исключением подакцизного товара — «ТНМ» или может не печататься;
  • 33 — о реализуемом товаре, подлежащем маркировке средством идентификации, имеющем код маркировки, за исключением подакцизного товара — «ТМ» или может не печататься.

3.4. Значения параметра документа удостоверяющего личность (Параметр "document_code")

Параметр «document_code» может принимать следующие значения:

  • RF_ID(21, «Паспорт гражданина Российской Федерации»);
  • RF_ID_ETC(22, «Паспорт гражданина Российской Федерации, дипломатический паспорт, служебный паспорт, удостоверяющие личность гражданина Российской Федерации за пределами Российской Федерации;»);
  • TEMP_RF_ID(26, «Временное удостоверение личности гражданина Российской Федерации, выдаваемое на период оформления паспорта гражданина Российской Федерации»);
  • BIRTH_RF_ID(27, «Свидетельство о рождении гражданина Российской Федерации (для граждан Российской Федерации в возрасте до 14 лет)»);
  • OTHER_RF_ID(28, «Иные документы, признаваемые документами, удостоверяющими личность гражданина Российской Федерации в соответствии с законодательством Российской Федерации»);
  • FOREIGN_ID(31, «Паспорт иностранного гражданина»);
  • FOREIGN_ID_OTHER(32, «Иные документы, признаваемые документами, удостоверяющими личность иностранного гражданина в соответствии с законодательством Российской Федерации и международным договором Российской Федерации»);
  • ID_FOREIGN_STATELESS(33, «Документ, выданный иностранным государством и признаваемый в соответствии с международным договором Российской Федерации в качестве документа, удостоверяющего личность лица без гражданства.»);
  • RESIDENCE_PERMIT(34, «Вид на жительство (для лиц без гражданства)»);
  • TEMP_RESIDENCE_PERMIT(35, «Разрешение на временное проживание (для лиц без гражданства)»);
  • STATELESS_REVIEW_ID(36, «Свидетельство о рассмотрении ходатайства о признании лица без гражданства беженцем на территории Российской Федерации по существу»);
  • REFUGEE_ID(37, «Удостоверение беженца»);
  • OTHER_ID(38, «Иные документы, признаваемые документами, удостоверяющими личность лиц без гражданства в соответствии с законодательством Российской Федерации и международным договором Российской Федерации»);
  • STATELESS_REVIEW_RF_ID(40, «Документ, удостоверяющий личность лица, не имеющего действительного документа, удостоверяющего личность, на период рассмотрения заявления о признании гражданином Российской Федерации или о приеме в гражданство Российской Федерации»).

3.5. Значения параметра идентификатора федеральных органов исполнительной власти (Параметр "federal_id")

Параметр «federal_id» может принимать следующие значения:

  • 001 - Министерство внутренних дел Российской Федерации
  • 002 - Министерство Российской Федерации по делам гражданской обороны, чрезвычайным ситуациям и ликвидации последствий стихийных бедствий
  • 003 - Министерство иностранных дел Российской Федерации
  • 004 - Федеральное агентство по делам Содружества Независимых Государств, соотечественников, проживающих за рубежом, и по международному гуманитарному сотрудничеству
  • 005 - Министерство обороны Российской Федерации
  • 006 - Федеральная служба по военно-техническому сотрудничеству
  • 007 - Федеральная служба по техническому и экспортному контролю
  • 008 - Министерство юстиции Российской Федерации
  • 009 - Федеральная служба исполнения наказаний
  • 010 - Федеральная служба судебных приставов
  • 011 - Государственная фельдъегерская служба Российской Федерации(федеральная служба)
  • 012 - Служба внешней разведки Российской Федерации (федеральная служба)
  • 013 - Федеральная служба безопасности Российской Федерации (федеральная служба)
  • 014 - Федеральная служба войск национальной гвардии Российской Федерации (федеральная служба)
  • 015 - Федеральная служба охраны Российской Федерации (федеральная служба)
  • 016 - Федеральная служба по финансовому мониторингу (федеральная служба)
  • 017 - Федеральное архивное агентство (федеральное агентство)
  • 018 - Главное управление специальных программ Президента Российской Федерации (федеральное агентство)
  • 019 - Управление делами Президента Российской Федерации (федеральное агентство)
  • 020 - Министерство здравоохранения Российской Федерации
  • 021 - Федеральная служба по надзору в сфере здравоохранения
  • 022 - Министерство культуры Российской Федерации
  • 023 - Министерство науки и высшего образования Российской Федерации
  • 024 - Министерство природных ресурсов и экологии Российской Федерации
  • 025 - Федеральная служба по гидрометеорологии и мониторингу окружающей среды
  • 026 - Федеральная служба по надзору в сфере природопользования
  • 027 - Федеральное агентство водных ресурсов
  • 028 - Федеральное агентство лесного хозяйства
  • 029 - Федеральное агентство по недропользованию
  • 030 - Министерство промышленности и торговли Российской Федерации
  • 031 - Федеральное агентство по техническому регулированию и метрологии
  • 032 - Министерство просвещения Российской Федерации
  • 033 - Министерство Российской Федерации по развитию Дальнего Востока и Арктики
  • 034 - Министерство сельского хозяйства Российской Федерации
  • 035 - Федеральная служба по ветеринарному и фитосанитарному надзору
  • 036 - Федеральное агентство по рыболовству
  • 037 - Министерство спорта Российской Федерации
  • 038 - Министерство строительства и жилищно-коммунального хозяйства Российской Федерации
  • 039 - Министерство транспорта Российской Федерации
  • 040 - Федеральная служба по надзору в сфере транспорта
  • 041 - Федеральное агентство воздушного транспорта
  • 042 - Федеральное дорожное агентство
  • 043 - Федеральное агентство железнодорожного транспорта
  • 044 - Федеральное агентство морского и речного транспорта
  • 045 - Министерство труда и социальной защиты Российской Федерации
  • 046 - Федеральная служба по труду и занятости
  • 047 - Министерство финансов Российской Федераци
  • 048 - Федеральная налоговая служба
  • 049 - Федеральная пробирная палата (федеральная служба)
  • 050 - Федеральная служба по регулированию алкогольного рынка
  • 051 - Федеральная таможенная служба
  • 052 - Федеральное казначейство (федеральная служба)
  • 053 - Федеральное агентство по управлению государственным имуществом
  • 054 - Министерство цифрового развития, связи и массовых коммуникаций Российской Федерации
  • 055 - Федеральная служба по надзору в сфере связи, информационных технологий и массовых коммуникаций
  • 056 - Федеральное агентство по печати и массовым коммуникациям
  • 057 - Федеральное агентство связи
  • 058 - Министерство экономического развития Российской Федерации
  • 059 - Федеральная служба по аккредитации
  • 060 - Федеральная служба государственной статистики
  • 061 - Федеральная служба по интеллектуальной собственности
  • 062 - Федеральное агентство по туризму
  • 063 - Министерство энергетики Российской Федерации
  • 064 - Федеральная антимонопольная служба
  • 065 - Федеральная служба государственной регистрации, кадастра и картографии
  • 066 - Федеральная служба по надзору в сфере защиты прав потребителей и благополучия человека
  • 067 - Федеральная служба по надзору в сфере образования и науки
  • 068 - Федеральная служба по экологическому, технологическому и атомному надзору
  • 069 - Федеральное агентство по государственным резервам
  • 070 - Федеральное медико-биологическое агентство
  • 071 - Федеральное агентство по делам молодежи
  • 072 - Федеральное агентство по делам национальностей

3.6. Значения параметра мера измерения товара (Параметр "measure")

  • 0 - Применяется для предметов расчета, которые могут быть реализованы поштучно или единицами
  • 10 - Грамм
  • 11 - Килограмм
  • 12 - Тонна
  • 20 - Сантиметр
  • 21 - Дециметр
  • 22 - Метр
  • 30 - Квадратный сантиметр
  • 31 - Квадратный дециметр
  • 32 - Квадратный метр
  • 40 - Миллилитр
  • 41 - Литр
  • 42 - Кубический метр
  • 50 - Киловатт час
  • 51 - Гигакалория
  • 70 - Сутки (день)
  • 71 - Час
  • 72 - Минута
  • 73 - Секунда
  • 80 - Килобайт
  • 81 - Мегабайт
  • 82 - Гигабайт
  • 83 - Терабайт
  • 255 - Применяется при использовании иных единиц измерения

3.7. Примеры чеков

Пример простого чека:

{
  "external_id": "17052922154475616",
  "receipt": {
    "client": {
      "email": "test@test.ru"
    },
    "company": {
      "email": "test@test.ru",
      "sno": "osn",
      "inn": "1234567891",
      "payment_address": "http://magazin.ru/"
    },
    "items": [
      {
        "name": "колбаса Клинский Брауншвейгская с/к в/с ",
        "price": 1000,
        "quantity": 0.3,
        "sum": 300,
        "measure: 11,
        "payment_method": "full_payment",
        "payment_object": 1,
        "vat": {
          "type": "vat20"
        }
      },
      {
        "name": "яйцо Окское куриное С0 белое",
        "price": 100,
        "quantity": 1,
        "sum": 100,
        "measure": 0,
        "payment_method": "full_payment",
        "payment_object": 1,
        "vat": {
          "type": "vat10"
        }
      }
    ],
    "payments": [
      {
        "type": 1,
        "sum": 400
      }
    ],
    "vats": [
      {
        "type": "vat20",
        "sum": 60.00
      },
      {
        "type": "vat10",
        "sum": 10.00
      }
    ],
    "total": 400
  },
  "service": {
    "callback_url": "http://testtest"
  },
  "timestamp": "22.09.21 13:45:00"
}

Пример чека коррекции:

{
  "external_id": "1705222292215225475616",
  "correction": {
    "client": {
      "email": "kkt@kkt.ru"
    },
    "company": {
      "email": "test@ofd.ru",
      "sno": "osn",
      "inn": "1234567891",
      "payment_address": "http://magazin.ru/"
    },
    "items": [
      {
        "name": "колбаса Клинский Брауншвейгская с/к в/с ",
        "price": 1000,
        "quantity": 0.3,
        "sum": 300,
        "measure": 11,
        "payment_method": "full_payment",
        "payment_object": 1,
        "vat": {
          "type": "vat20"
        }
      },
      {
        "name": "яйцо Окское куриное С0 белое",
        "price": 100,
        "quantity": 1,
        "sum": 100,
        "measure": 0,
        "payment_method": "full_payment",
        "payment_object": 1,
        "vat": {
          "type": "vat10"
        }
      }
    ],
     "correction_info": {
        "type": "self",
        "base_date": "01.01.2021",
        "base_number": "123",
        "base_name": "Pip"
     },
    "payments": [
      {
        "type": 1,
        "sum": 400
      }
    ],
    "vats": [
      {
        "type": "vat20",
        "sum": 60.00
      },
      {
        "type": "vat10",
        "sum": 10.00
      }
    ],
    "total": 400
  },
  "service": {
    "callback_url": "http://testtest"
  },
  "timestamp": "22.09.21 13:45:00"
}

Пример чека коррекции с ФПД:

{
  "external_id": "1705222292215225475616",
  "correction": {
    "client": {
      "email": "kkt@kkt.ru"
    },
    "company": {
      "email": "test@ofd.ru",
      "sno": "osn",
      "inn": "1234567891",
      "payment_address": "http://magazin.ru/"
    },
    "items": [
      {
        "name": "колбаса Клинский Брауншвейгская с/к в/с ",
        "price": 1000,
        "quantity": 0.3,
        "sum": 300,
        "measure": 11,
        "payment_method": "full_payment",
        "payment_object": "commodity",
        "vat": {
          "type": "vat20"
        }
      },
      {
        "name": "яйцо Окское куриное С0 белое",
        "price": 100,
        "quantity": 1,
        "sum": 100,
        "measure": 0,
        "payment_method": "full_payment",
        "payment_object": "commodity",
        "vat": {
          "type": "vat10"
        }
      }
    ],
     "correction_info": {
        "type": "self",
        "base_date": "01.01.2021",
        "base_number": "123",
        "base_name": "Pip"
     },
    "payments": [
      {
        "type": 1,
        "sum": 400
      }
    ],
    "vats": [
      {
        "type": "vat20",
        "sum": 60.00
      },
      {
        "type": "vat10",
        "sum": 10.00
      }
    ],
    "total": 400
  },
  "additional_check_props": "4444444",
  "service": {
    "callback_url": "http://testtest"
  },
  "timestamp": "22.09.21 13:45:00"
}

Пример чека коррекции с платежным агентом:

{
  "external_id": "qswdcfvb-345678-rtghnm-56789_test11123",
  "receipt": {
    "client": {
      "email": "kamarip214@falkyz.com",
      "phone" : "+79771080684"
    },
    "company": {
      "email": "chek@romashka.ru",
      "sno": "osn",
      "inn": "1234567891",
      "payment_address": "http://magazin.ru/"
    },
    "items": [
      {
        "name": "колбаса Клинский Брауншвейгская с/к в/с ",
        "price": 1000,
        "quantity": 0.3,
        "sum": 300,
        "measure": 11,
        "payment_method": "full_payment",
        "payment_object": 1,
        "vat": {
          "type": "vat20"
        },
        "agent_info": {
          "type": "another",
          "paying_agent": {
            "operation": "Операция 1",
            "phones": ["+79998887766"]
            },
          "receive_payments_operator": {
            "phones": ["+79998887766"]
            },
          "money_transfer_operator": {
            "phones": ["+79998887766"],
            "name": "Оператор перевода",
            "address": "г. Москва, ул. Складочная д.3",
            "inn": "8634330204"
            }
            },
        "supplier_info": {
          "phones": ["+79998887766"],
          "name": "Название поставщика",
          "inn": "287381373424"
        }
       },
      {
        "name": "яйцо Окское куриное С0 белое",
        "price": 100,
        "quantity": 1,
        "sum": 100,
        "measure": 0,
        "payment_method": "full_payment",
        "payment_object": 1,
        "vat": {
          "type": "vat10"
        },
        "agent_info": {
          "type": "another",
          "paying_agent": {
            "operation": "Операция 1",
            "phones": ["+79998887766"]
            },
          "receive_payments_operator": {
            "phones": ["+79998887766"]
            },
          "money_transfer_operator": {
            "phones": ["+79998887766"],
            "name": "Оператор перевода",
            "address": "г. Москва, ул. Складочная д.3",
            "inn": "8634330204"
            }
            },
        "supplier_info": {
          "phones": ["+79998887766"],
          "name": "Название поставщика",
          "inn": "287381373424"
        }
      }
    ],
    "payments": [
      {
        "type": 0,
        "sum": 400
      }
    ],
    "vats": [
      {
        "type": "vat20",
        "sum": 60.00
      },
      {
        "type": "vat10",
        "sum": 10.00
      }
    ],
    "total": 400
  },
  "service": {
    "callback_url": "http://testtest"
  }
}

4. Получение результата обработки документа

Результат обработки документа может быть получен двумя способами. Если поле «callback_url» было заполнено, то после обработки документа (успешной или неуспешной фискализации в ККТ), ответ будет отправлен POST запросом по URI указанному в данном поле. Если в течение 300 секунд ответ не поступил, необходимо запросить статус обработки документа с помощью метода GET. Результат обработки документа одинаков для всех способов получения и приведен в таблице 3 и 4.

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

GET https://ferma-at.ofd.ru/possystem/v1/{group_code}/report/{uuid}token={Code1}

Заменяемые значения:

  • Code1 – действующий код авторизации, полученный в результате запроса авторизации.
  • group_code: идентификатор группы ККТ:
    • параметр можно посмотреть в ЛКК Ferma в виджете «Реквизиты доступа»;
    • для тестовой среды параметр равен 1.
  • uuid: уникальный идентификатор, присвоенный документу после выполнения запроса на регистрацию.

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

{
    "error": null,
    "timestatmp": "31.03.2020 13:32:25",
    "uuid": "0099caf8-2c9c-4888-a289-b8ac879cdd91",
    "status": "done",
    "payload": {
        "total": 1598,
        "ofd_inn": "7709364545",
        "fns_site": "www.nalog.ru",
        "fn_number": "1110000100231111",
        "ecr_registration_number": "0000111118041111",
        "shift_number": 23,
        "receipt_datetime": "12.04.2017 20:16:00",
        "fiscal_receipt_number": 6,
        "fiscal_document_number": 133,
        "fiscal_document_attribute": 3449555955
        "ofd_receipt_url": "https://check.ofd.ru/"
    },
    "group_code": " MyCompany_MyShop",
    "daemon_code": "prod–agent–1",
    "device_code": "KSR13.00–1–11",
    "external_id": "TRF10601_1",
    "callback_url": ""
 }

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

Параметр Вложенный параметр Формат значения Описание
error String Сообщение об ошибке. В случае успешного ответа имеет значение null
timestamp String30) Дата и время документа из ФН
uuid String Уникальный идентификатор. Максимальная длина строки – 128 символов. Если документ не удалось зарегистрировать, документу не будет присвоен UUID
status String Статус. Возможные значения:
«done» – готово;
«fail» – ошибка;
«wait» – ожидание
payload Object Реквизиты фискализации документа
total Float point Итоговая сумма документа в рублях с заданным в CMS округлением:
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
При регистрации в ККТ происходит расчёт фактической суммы
ofd_inn String ИНН ОФД, через которого был зарегистрирован чек
fns_site String Адрес сайта ФНС
fn_number String Номер ФН
ecr_registration_number String Регистрационный номер ККТ
shift_number Integer Номер смены
receipt_datetime String31) Дата и время документа внешней системы в формате
«dd.mm.yyyy HH:MM:SS»
fiscal_receipt_number Integer Номер чека в смене
fiscal_document_number Integer Фискальный номер документа
fiscal_document_attribute Integer Фискальный признак документа
ofd_receipt_url String URL для просмотра чека на сайте ОФД
group_code String Идентификатор группы ККТ
daemon_code String Наименование сервера
device_code String Код ККТ
external_id String Идентификатор документа внешней системы, уникальный среди всех документов, отправленных в данную группу ККТ
callback_url String URL, на который необходимо ответить после обработки документа

В случае ошибки ответ имеет следующий вид:

{
    "error": {
        "error_id": "474d4d4d-444d-4d44-aa4b-e3dbdf4defd3",
        "code": 34,
        "text": "Состояние чека не найдено. Попробуйте позднее",
        "type": "system"
    },
    "status": "wait",
    "timestamp": "12.04.2017 18:58:38",
    "callback_url": ""
}

Таблица 4.2 Параметры структуры ответа при получении ошибки на запрос результата обработки документов

Параметр Вложенный параметр Формат значения Описание
error Object Описание ошибки
error_id String Уникальный идентификатор ошибки
code Integer Код ошибки. Отображается только при ошибке. Если параметр присутствует, то со значением «fail» или «wait»
text String Текст ошибки (кодировка utf–8)
type String Тип источника ошибки. Возможные значения:
«system» – системная ошибка;
«unknown» – неизвестная ошибка
status String Статус. Возможные значения:
«done» – готово;
«fail» – ошибка;
«wait» – ожидание
receipt_datetime String32) Дата и время документа внешней системы в формате
«dd.mm.yyyy HH:MM:SS»
callback_url String URL, на который необходимо ответить после обработки документа

5. Описание ошибок

Таблица 5.1. Ошибка и описание ошибки

Сообщение об ошибки Код ошибки Описание ошибки
CASHBOX_NOT_FISCALIZED 1070 Касса не фискализирована. По кассе Ferma не завершена регистрация в ФНС
CASHBOX_REQUIRES_REGISTRATION_COMPLETION 1071 По кассе требуется завершение регистрации. По кассе Ferma регистрация в ФНС не завершена
CASHBOX_TO_ARCHIVING 1072 Касса подготавливается к архивации. Необходима замена фискального накопителя
CASHBOX_ARCHIVED 1073 Касса заархивирована. Необходима замена фискального накопителя
CASHBOX_REREGISTRATION_REQUIRED 1074 По кассе требуется перерегистрации. По кассе Ferma перерегистрация в ФНС не завершена
CASHBOX_REQUIRES_REREGISTRATION_COMPLETION 1076 По кассе требуется завершение перерегистрации. По кассе Ferma перерегистрация в ФНС не завершена
CASHBOX_REMOVED_FROM_BALANCING 1075 Касса убрана из балансировки. По кассе проводятся временные технические работы
CASHBOX_REQUIRES_ERASURE 1077 Касса требует обнуления. По кассе проводятся временные технические работы
CASHBOX_FIRMWARE_UPDATE_IN_PROGRESS 1078 Проводится прошивка кассы. По кассе проводятся временные технические работы
CASHBOX_WITHDRAWN_FOR_NONPAYMENT 1079 Касса выведена за неуплату. Не оплачена касса Ferma
CASHBOX_STATE_UNKNOWN 1080 Нет касс Ferma в статусе 'Готова к работе'

6. Порядок тестирования

6.1. Описание

Раздел описывает способ тестирования программного интерфейса приложений (API) сервиса «АТОЛ Онлайн» для информационной системы «Ferma» с пробитием чеков и возможностью их просмотра. Для тестирования используется демонстрационный личный кабинет клиента (ЛКК), а также кассовый аппарат с установленным тестовым фискальным накопитель (ФН МГМ), который подключен к тестовой информационной системе Ferma. Все запросы, описанные в инструкции, собраны в коллекцию для Postman. Вы можете скачать коллекцию и убедиться в работоспособности всех методов. Коллекция поможет вам настроить сервис под ваши задачи.

6.2. Тестовое API сервиса «АТОЛ Онлайн» для информационной системы «Ferma»

Для того чтобы пробить чеки на тестовой кассе Ferma, которая находится в демо ЛКК, используйте данные:
Домен1) - ferma-test-at.ofd.ru

Логин - fermatest2

Пароль - Go2999483Mb

group_code - 1

Логин и пароль используются в API-запросе для получения кода авторизации (AuthToken). group_code используется в API-запросе для доступа к кассам и формированию запросов на создание чеков.

6.3. Вход в демо ЛКК

Чтобы войти в демо личный кабинет клиента для дальнейшего просмотра чеков, нужно выполнить следующие действия:

  1. Переходим по ссылке;
  2. Автоматически подставленные данные в полях «Электронная почта» и «Пароль» удаляем.
  3. Вводим данные:
    1. электронная почта: fermatest1@ofd.ru
    2. пароль: 1231
  4. Нажимаем кнопку «Войти»;
  5. Вы оказались в демо личном кабинете.

6.4. Как посмотреть чеки

После того как вошли в демо ЛКК, для просмотра пробитых чеков на кассе, нужно:

  1. перейти в раздел «Кассы»;
  2. здесь находится единственная касса;
  3. нажимаем на её РНМ;
  4. на следующей странице переходим на вкладку «Фискальные документы»;
  5. в таблице «Все документы» находим нужный чек, для этого можно воспользоваться фильтрами, которые располагаются над таблицей;
  6. напротив нужного чека нажать на значок .

7. Мониторинг услуги Ferma и ФН

Метод получения информации о ККТ и ФН предназначен для получения актуальной информации об арендованной клиентом контрольно-кассовой технике в сервисе Ferma и состоянии фискальных накопителей посредством API.

Метод позволяет получить следующую информацию: • регистрационных данных о ККТ и ФН; • о текущем состоянии ФН (процент наполненности, количество документов в ФН, срок замены ФН); • о текущем статусе ККТ в сервисе Ferma для осуществления необходимых действий со стороны клиента в Личном кабинете клиента.

Запрос на получение данных мониторинга услуги Ferma и ФН выглядит следующим образом:

GET https://ferma-at.ofd.ru/possystem/v1/stats/cashboxes/extended?token=Code1&deviceId=deviceId&rnm=rnm&zn=zn&fn=fn

Здесь:

  • Code1 (обязательное поле) – действующий код авторизации, полученный в результате запроса авторизации.;
  • deviceId (необязательное поле) - cервисный идентификатор устройства, на котором генерируется кассовый документ (чек);
  • rnm (необязательное поле) - регистрационный номер кассы;
  • zn (необязательное поле) - серийный номер ККТ;
  • fn (необязательное поле) - номер ФН;

Успешным ответом на запрос возвращается структура данных JSON следующего вида (вид значений показан на примерах, многоточие означает многократно повторяющуюся структуру такого же вида):

{
    "Status": "Success",
    "Data": [
        {
            "deviceId": 12135,
            "fn": "9280440300750000",
            "zn": "9944254000",
            "rnm": "0004939230052000",
            "kktModel": "Эфир Pro ФС",
            "kktState": "Готова к работе",
            "tariffType": "Стоимость за 1 месяц",
            "tariffEndDate": "2021-01-03",
            "tariffChecksCnt": null,
            "fnName": "Шифровальное (криптографическое) средство защиты фискальных данных фискальный накопитель «ФН-1.1» исполнение Ав15-2",
            "fnModelName": "FN15",
            "checksCnt": 66,
            "fnVolumePercent": 0.03,
            "projectedFnReplaceDate": "2022-03-19",
            "projectedFnFilledDate": "2022-03-19",
            "fnLastChangeDate": "2021-07-09"
        },
        .....
    ]
}

Параметры структуры ответа с ошибкой приведены в таблице 5.

Таблица 5. Параметры структуры ответа метода для мониторинга состояния услуги Ferma и ФН

Параметр Формат значения Описание
deviceId Строка Сервисный идентификатор устройства, на котором генерируется кассовый документ (чек)
fn Строка Номер фискального накопителя, установленного в кассу
zn Строка Заводской номер кассы
rnm Строка Регистрационный номер кассы
kktModel Строка Наименование модели кассы
kktState Строка Статус кассы в ИС «Ferma»
tariffType Строка Тип тарифа на кассе
tariffEndDate Строка Дата окончания оплаченного периода по тарифу
tariffChecksCnt Строка Число доступных для пробития чеков на почековом типе тарифа
fnName Строка Наименование модели фискального накопителя установленного в кассу
fnModelName Строка Тип фискального накопителя установленного в кассу
checksCnt Строка Число пробитых чеков в фискальном накопителе
fnVolumePercent Строка Процент заполнения памяти фискального накопителя
projectedFnReplaceDate Строка Прогнозируемая дата замены по сроку окончания фискального накопителя
projectedFnFilledDate Строка Прогнозируемая дата замены по наполнению памяти фискального накопителя
fnLastChangeDate Строка Дата последней замены фискального накопителя

7.1. Возможные значения статуса кассы в ИС «Ferma» (поле “kktState”)

  • «Готова к работе» - касса принимает фискальные документы в штатном режиме;
  • «Не фискализирована» — касса выделена клиенту и на кассе не сформирован отчет о регистрации, касса не формирует чеки;
  • «Требуется завершение фискализации» - на кассе клиента сформирован отчет о регистрации, требуется выведения кассы в работу в Личном Кабинете клиента, касса не формирует чеки;
  • «Заменен ФН» - фискальный накопитель заменен на кассе, касса не формирует чеки;
  • «К архивации» - на кассе требуется замена фискального накопителя, касса не формирует чеки;
  • «Требуется завершение перерегистрации» - касса выведена из балансировки, на кассе сформирован Отчет о перерегистрации и требуется завершить перерегистрацию в Личном кабинете клиента, касса не формирует чеки;
  • «ФН на хранении» - фискальный накопитель переведен в хранение;
  • «Заканчивается срок обслуживания» - до остановки обслуживания кассы Ferma осталось менее 15 дней, касса принимает фискальные документы в штатном режиме;
  • «Проводится прошивка» - на кассе осуществляются плановые технические работы, касса не формирует чеки

7.2. Возможные значения типа тарифа в ИС «Ferma» (поле “tariffType”)

  • «Стоимость за 1 месяц» - тарификация осуществляется за 1 календарный месяц;
  • «Стоимость за 12 месяцев» - тарификация осуществляется за 12 календарных месяцев;
  • «Стоимость за 1 чек» - тарификация осуществляется по количеству пробитых чеков

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

Версия 1.0
Выпущена 27 марта 2020 г.
Первая регистрируемая версия документа.

Версия 1.1
Выпущена 7 апреля 2020 г.
Добавлен раздел описывающий порядок тестирования.

Версия 1.2
Выпущена 25 июня 2020 г.
В описание к параметру timestamp, который присутствует при получении кода авторизации (token), добавлена информация о том, сколько времени токен доступен для использования.

Версия 1.3
Выпущена 8 сентября 2020 г.
Добавлена информация откуда берется параметр group_code.

Версия 1.4
Выпущена 9 сентября 2020 г.
В блок 5.4. Тестовое API Ferma добавлена информация по параметру group_code.

Версия 1.5
Выпущена 18 сентября 2020 г.
Исправлен url для доступа.

Версия 1.6
Выпущена 21 сентября 2020 г.

  • Переработан блок 5. Порядок тестирования
  • Устранены мелкие недочеты по всему объему документа.

Версия 1.7
Выпущена 24 сентября 2020 г.
Исправлена ошибка в регулярном выражении.

Версия 1.8
Выпущена 08 октября 2020 г.

  • Переработаны таблицы для большей наглядности информации о вложенных полях в структурах;
  • Изменены описания параметров external_id в таблице 1, error в таблице 3

Версия 1.9
Выпущена 30 апреля 2021 г.

  • Добавлено описание метода 6 Мониторинг услуги Ferma и ФН.
  • Добавлено описание параметров метода 6 Мониторинг услуги Ferma и ФН.

Версия 1.10
Выпущена 14 апреля 2021 г.

  • Добавлен новый раздел 3.6
  • Добавлено описание по новым тегам birthdate, citizenship, document_code, document_data, address, operating_check_props, sectoral_check_props, measure, mark_quantity, mark_processing_mode, sectoral_item_props, mark_code

Версия 1.11
Выпущена 07 июня 2022 г.

  • Переструктурирован документ
  • Добавлены разделы с описанием значений:
    • Параметра «payment_object»
    • Параметра «document_code»
    • Параметра «federal_id»
    • Параметра «measure»
  • Добавлено описание двух новых чеков:
    • sell_refund_correction чек «Коррекция возврата прихода»
    • buy_refund_correction чек «Коррекция возврата расхода»

Версия 1.12
Выпущена 10 июня 2022 г.

  • Добавлен пример чека с платежным агентом
1)
строка символов, представляет собой 32-значную последовательность шестнадцатеричных цифр
2)
Временя задается в формате «ДД-ММ-ГГГГ чч:мм:сс»
3) , 19) , 29)
Признак обязательности параметра в запросе
4) , 5)
В запросе обязательно должно быть заполнено хотя бы одно из полей: email или phone. Если заполнены оба поля, ОФД отправит электронный чек только на email
6) , 7) , 8) , 9) , 10) , 11) , 12)
Если расчеты осуществляются между организациями
13)
Используется в составе чека коррекции
14) , 21)
Параметр обязателен, если передан «supplier_info».
15) , 22)
Поле обязательно, если передан «agent_info».
16)
Если пробивает чек поставщик товара
17)
Если передан объект «additional_user_props», в нём обязательно должно быть передано поле «name».
18)
Если передан объект «additional_user_props», в нём обязательно должно быть передано поле «value».
20)
Если признак не передан, по умолчанию используется значение «full_prepayment»
23)
Необходим для реализации подакцизного товара
24) , 25)
Необходим для реализации экспортных товаров
26)
Необходим для пробития маркированного товара со значением «0» в параметре «measure»
27) , 28)
Если товар подлежит обязательно маркировки
30) , 31) , 32)
Дата и время