Ferma® с АТОЛ Онлайн

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

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

В конвертере «АТОЛ Онлайн» реализован механизм многократного обращения после одной авторизации без использования механизма 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), значит запрос был успешно выполнен. Параметр не является обязательным в успешных ответах (code 200) конвертера API для «АТОЛ Онлайн», параметр может присутствовать в успешных ответах (code 200).
  
• token - код авторизации¹⁾
  
• timestamp – Время действия токена авторизации (по стандарту UTC).²⁾
  

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

{
    "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 – время и дата ошибки (по стандарту UTC).

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

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

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

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

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

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"
         },
        "device_number": "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.2.

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

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

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

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

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

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

• 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 — о реализуемом товаре, подлежащем маркировке средством идентификации, имеющем код маркировки, за исключением подакцизного товара — «ТМ» или может не печататься.

Параметр «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, «Документ, удостоверяющий личность лица, не имеющего действительного документа, удостоверяющего личность, на период рассмотрения заявления о признании гражданином Российской Федерации или о приеме в гражданство Российской Федерации»).

Параметр «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 - Федеральное агентство по делам национальностей

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

В API Ferma® можно создать чек без ограничения на число товаров.
Если запрос на формирование кассового чека превышает порог в 20 000 символов (~ = 200 товаров), то Ferma® делит запрос на несколько чеков, которые могут быть выбиты на разных кассах клиента.

Для включения механики обратитесь в поддержку OFD.ru.

Внимание!
Все позиции должны иметь одинаковое значение «payment_object» (тип оплаты).
Параметр «agent_info» (информации об агенте) передавать только в параметре «items», в составе товарной позиции.

Чек с большим количеством позиций формируется методом "possystem". Описание параметров запроса формирование кассового представлено в разделе "3.1. Описание параметров запроса"

Вид запроса:

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

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

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

{
	"receipt": {
		"client": {
			"email": "@gmail.com"
		},
		"company": {
			"sno": "osn",
			"inn": "4501037489",
			"payment_address": "Интернет магазин"
		},
		"items": [

			{
				"name": "НАПИТОК НЕМОЛОКО 0,2Л ОВСЯНЫЙ КЛАССИЧЕСКИЙ ОБОГАЩ ВИТАМИН И МИНЕРАЛ ВЕЩ Т/П",
				"price": 300.0,
				"quantity": 1,
				"sum": 300.0,
				"vat": {
					"type": "vat10",
					"sum": 30.0
				},
				"payment_method": "full_payment",
				"payment_object": "1"
			},
			{
				"name": "НАПИТОК НЕМОЛОКО 0,2Л ОВСЯНЫЙ КЛАССИЧЕСКИЙ ОБОГАЩ ВИТАМИН И МИНЕРАЛ ВЕЩ Т/П",
				"price": 300.0,
				"quantity": 1,
				"sum": 300.0,
				"vat": {
					"type": "vat10",
					"sum": 30.0
				},
				"payment_method": "full_payment",
				"payment_object": "1"
			},
			{
				"name": "НАПИТОК НЕМОЛОКО 0,2Л ОВСЯНЫЙ КЛАССИЧЕСКИЙ ОБОГАЩ ВИТАМИН И МИНЕРАЛ ВЕЩ Т/П",
				"price": 300.0,
				"quantity": 1,
				"sum": 300.0,
				"vat": {
					"type": "vat10",
					"sum": 30.0
				},
				"payment_method": "full_payment",
				"payment_object": "1"
			},
			{
				"name": "НАПИТОК НЕМОЛОКО 0,2Л ОВСЯНЫЙ КЛАССИЧЕСКИЙ ОБОГАЩ ВИТАМИН И МИНЕРАЛ ВЕЩ Т/П",
				"price": 300.0,
				"quantity": 1,
				"sum": 300.0,
				"vat": {
					"type": "vat10",
					"sum": 30.0
				},
				"payment_method": "full_payment",
				"payment_object": "1"
			},
			...
			{
				"name": "НАПИТОК НЕМОЛОКО 0,2Л ОВСЯНЫЙ КЛАССИЧЕСКИЙ ОБОГАЩ ВИТАМИН И МИНЕРАЛ ВЕЩ Т/П",
				"price": 300.0,
				"quantity": 1,
				"sum": 300.0,
				"vat": {
					"type": "vat10",
					"sum": 30.0
				},
				"payment_method": "full_payment",
				"payment_object": "1"
			},
			{
				"name": "НАПИТОК НЕМОЛОКО 0,2Л ОВСЯНЫЙ КЛАССИЧЕСКИЙ ОБОГАЩ ВИТАМИН И МИНЕРАЛ ВЕЩ Т/П",
				"price": 300.0,
				"quantity": 1,
				"sum": 300.0,
				"vat": {
					"type": "vat10",
					"sum": 30.0
				},
				"payment_method": "full_payment",
				"payment_object": "1"
			},
			{
				"name": "НАПИТОК НЕМОЛОКО 0,2Л ОВСЯНЫЙ КЛАССИЧЕСКИЙ ОБОГАЩ ВИТАМИН И МИНЕРАЛ ВЕЩ Т/П",
				"price": 300.0,
				"quantity": 1,
				"sum": 300.0,
				"vat": {
					"type": "vat10",
					"sum": 30.0
				},
				"payment_method": "full_payment",
				"payment_object": "1"
			}
		],
		"payments": [
			{
				"type": 1,
				"sum": 54000.0
			}
		]
	},
	"timestamp": "23.03.2023 16:00:05",
	"external_id": "8eb0dd81-8588-4c37-b293-2c544547243654a115454ab7cb6"
}

В ответ Ferma® вернет массив чеков:

{
    "uuid": null,
    "split_receipt_data": [
        {
            "uuid": "889b277c-be8c-4544-b84c-8f7b24462ebc"
        },
        {
            "uuid": "a86153df-494e-425f-9d36-47e9adc1926a"
        },
        {
            "uuid": "bc6d7ba2-c2b1-49ed-b9f5-cfa118e97163"
        },
        {
            "uuid": "866eb0ec-bf11-415f-b05e-4c8282b5c0db"
        }
    ],
    "status": "wait",
    "error": null,
    "timestamp": "05.04.2023 12:47:16"
}

Проверка статуса чека выполняется по присвоенным «uuid» в ответе. Описание метода проверки статуса кассового чека представлено в разделе "4. Проверка статуса кассового чека".

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

{
  "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"
  }
}

Результат обработки документа может быть получен двумя способами. Если поле «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",
    "external_id": "TRF10601_1",
    "callback_url": ""
 }

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

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

{
    "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 Параметры структуры ответа при получении ошибки на запрос результата обработки документов

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

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

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

Логин - fermatest2

Пароль - Go2999483Mb

group_code - 1

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

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

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

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

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

Метод получения информации о ККТ и ФН предназначен для получения актуальной информации об арендованной клиентом контрольно-кассовой технике в сервисе 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 (необязательное поле) - сервисный идентификатор устройства, на котором генерируется кассовый документ (чек);
• 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® и ФН

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

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

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

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

Версия 1.2
Выпущена 25 июня 2020 г.
В описание к параметру timestamp (по стандарту UTC), который присутствует при получении кода авторизации (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.13
Выпущена 16 июня 2023 г.

• В параметре «receipt_datetime» добавлена информация про формат даты и времени

Версия 1.14
Выпущена 22 декабря 2023 г.

• В разделе 3.1 добавлен параметр device_number

Версия 1.15
Выпущена 24 января 2024 г.

• Удалено описание параметра device_code

Версия 1.16
Выпущена 6 мая 2024 г.

• Для параметров timestamp добавлено уточнение формата и стандарта (по стандарту UTC).

Версия 1.17
Выпущена 26 июля 2024 г.

• В разделах 3.1. и 3.1.1. добавлены правила применения параметров vat и vats для прямых чеков и чеков коррекции.