Ferma с Checkonline

Документ описывает сценарий использования программного интерфейса приложений (API) сервиса CheckOnline для информационной системы Ferma

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

Для выполнения запросов на устройстве необходимо использовать сертификат, после чего выполнить запрос на создание чеков с использованием конвертера «Checkonline», который имеет вид:

POST https://ferma-c.ofd.ru/api/kkt/cloud/sync/receipt

Входные параметры данного запроса передаются в его теле в виде структуры данных в формате JSON. Пример запроса приведен ниже:

{
  "Requestid": "545+64",
  "Clientid": "",
  "Device": "auto",
  "DocumentType": 0,
  "Lines": [
    {
      "Qty": 1,
      "Price": 78850,
      "PayAttribute": 4,
      "Taxid": 4,
      "Description": "Услуги по перевозке пассажиров и багажа",
      "AgentModes": 64,
      "ProviderData": {
        "INN": "7707083893"
      }
    }
  ],
  "NonCash": [
    78850,
    0,
    0
  ],
  "Cash": 0,
  "TaxMode": 0,
  "PhoneOrEmail": "79878985623",
  "Place": "",
  "FullResponse": false,
  "PaymentAgentModes": 64
}

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

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

Ответ на данный запрос также содержит структуру данных в формате JSON.
Ниже приведен пример ответа, если поле FullResponse имеет значение false.
Параметры структуры ответа описаны в таблице 2.

{
    "fceerror": 0,
    "Requestid": "ac88fe9f-5885-11ea-ae38-788b1848edc8",
    "Clientid": null,
    "Device": {
        "Name": "00000003820034472769",
        "Address": "172.16.13.213:4444"
    },
    "Path": "/fr/api/v2/Complex",
    "Response": {
        "Error": 0,
        "ErrorMessages": null
    },
    "FiscalDocNumber": 62848,
    "DocNumber": 58,
    "Date": {
        "Date": {
            "Day": 27,
            "Month": 2,
            "Year": 20
        },
        "Time": {
            "Hour": 12,
            "Minute": 43,
            "Second": 57
        }
    },
    "GrandTotal": 17520,
    "FiscalSign": 1570734444,
    "DocumentType": 0,
    "QR": "t=20200227T3333&s=175.20&fn=9289000100444444&i=62888&fp=1577734888&n=1",
    "FNSerialNumber": "9289000100444444",
    "DeviceSerialNumber": "00000003820034444449",
    "DeviceRegistrationNumber": "0001729222014444",
    "FCEError": 0,
    "ErrorDescription": null,
    "Fatal": false,
    "HTTPStatus": 200
}

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

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

• не задан — для индивидуальных предпринимателей, являющихся налогоплательщиками, применяющими патентную систему налогообложения и упрощённую систему налогообложения, а также индивидуальных предпринимателей, применяющих систему налогообложения для сельскохозяйственных товаропроизводителей, систему налогообложения в виде единого налога на вменённый доход для отдельных видов деятельности при осуществлении видов предпринимательской деятельности, установленных пунктом 2 статьи 346.26 Налогового кодекса Российской Федерации, за исключением индивидуальных предпринимателей, осуществляющих торговлю подакцизными товарами, требование об обязательном включении в состав кассового чека и БСО реквизита применяется с 1 февраля 2021 года;
• 1 — полная предварительная оплата до момента передачи предмета расчёта;
• 2 — частичная предварительная оплата до момента передачи предмета расчёта;
• 3 — аванс;
• 4 — полная оплата, в том числе с учётом аванса (предварительной оплаты) в момент передачи предмета расчёта;
• 5 — частичная оплата предмета расчёта в момент его передачи с последующей оплатой в кредит;
• 6 — передача предмета расчёта без его оплаты в момент его передачи с последующей оплатой в кредит;
• 7 — оплата предмета расчёта после его передачи с оплатой в кредит (оплата кредита). Этот признак должен быть единственным в документе и документ с этим признаком может содержать только одну строку.

• Не задан — значение признака не важно
• 1 — о реализуемом товаре, за исключением подакцизного товара (наименование и иные сведения, описывающие товар);
• 2 — о реализуемом подакцизном товаре (наименование и иные сведения, описывающие товар);
• 3 — о выполняемой работе (наименование и иные сведения, описывающие работу);
• 4 — об оказываемой услуге (наименование и иные сведения, описывающие услугу);
• 5 — о приёме ставок при осуществлении деятельности по проведению азартных игр;
• 6 — о выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр;
• 7 — о приёме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приёме лотерейных ставок при осуществлении деятельности по проведению лотерей;
• 8 — о выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей;
• 9 — о предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации;
• 10 — об авансе, задатке, предоплате, кредите, взносе в счёт оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчёта;
• 11 — о вознаграждении пользователя, являющегося платёжным агентом (субагентом), банковским платёжным агентом (субагентом), комиссионером, поверенным или иным агентом;
• 12 — о предмете расчёта, состоящем из предметов, каждому из которых может быть присвоено значение от «1» до «11»;
• 13 — о предмете расчёта, не относящемуся к предметам расчёта, которым может быть присвоено значение от «1» до «12» и от «14» до «18»;
• 14 — о передаче имущественных прав;
• 15 — о внереализационном доходе;
• 16 — о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации;
• 17 — о суммах уплаченного торгового сбора;
• 18 — о курортном сборе.

• 0 — Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платёжным агентом;
• 1 — Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платёжным субагентом;
• 2 — Оказание услуг покупателю (клиенту) пользователем, являющимся платёжным агентом;
• 3 — Оказание услуг покупателю (клиенту) пользователем, являющимся платёжным субагентом;
• 4 — Осуществление расчёта с покупателем (клиентом) пользователем, являющимся поверенным;
• 5 — Осуществление расчёта с покупателем (клиентом) пользователем, являющимся комиссионером;
• 6 — Осуществление расчёта с покупателем (клиентом) пользователем, являющимся агентом и не являющимся банковским платёжным агентом (субагентом), платёжным агентом (субагентом), поверенным, комиссионером.

• 1 — доход от долевого участия в других организациях;
• 2 — доход в виде курсовой разницы, образующейся вследствие отклонения курса продажи (покупки) иностранной валюты от официального курса;
• 3 — доход в виде подлежащих уплате должником штрафов, пеней и (или) иных санкций за нарушение договорных обязательств;
• 4 — доход от сдачи имущества (включая земельные участки) в аренду (субаренду);
• 5 — доход от предоставления в пользование прав на результаты интеллектуальной деятельности;
• 6 — доход в виде процентов, полученных по договорам займа и другим долговым обязательствам;
• 7 — доход в виде сумм восстановленных резервов;
• 8 — доход в виде безвозмездно полученного имущества (работ, услуг) или имущественных прав;
• 9 — доход в виде дохода, распределяемого в пользу налогоплательщика при его участии в простом товариществе;
• 10 — доход в виде дохода прошлых лет, выявленного в отчетном (налоговом) периоде;
• 11 — доход в виде положительной курсовой разницы;
• 12 — доход в виде основных средств и нематериальных активов, безвозмездно полученных атомными станциями;
• 13 — доход в виде стоимости полученных материалов при ликвидации выводимых из эксплуатации основных средств;
• 14 — доход в виде использованных не по целевому назначению имущества, работ, услуг;
• 15 — доход в виде использованных не по целевому назначению средств, предназначенных для формирования резервов по обеспечению безопасности производств;
• 16 — доход в виде сумм, на которые уменьшен уставной (складочный) капитал (фонд) организации;
• 17 — доход в виде сумм возврата от некоммерческой организации ранее уплаченных взносов (вкладов);
• 18 — доход в виде сумм кредиторской задолженности, списанной в связи с истечением срока исковой давности или по другим основаниям;
• 19 — доход в виде доходов, полученных от операций с производными финансовыми инструментами;
• 20 — доход в виде стоимости излишков материально-производственных запасов и прочего имущества, которые выявлены в результате инвентаризации;
• 21 — доход в виде стоимости продукции СМИ и книжной продукции, подлежащей замене при возврате либо при списании;
• 22 — доход в виде сумм корректировки прибыли налогоплательщика;
• 23 — доход в виде возвращенного денежного эквивалента недвижимого имущества и (или) ценных бумаг, переданных на пополнение целевого капитала некоммерческой организации;
• 24 — доход в виде разницы между суммой налоговых вычетов из сумм акциза и указанных сумм акциза;
• 25 — доход в виде прибыли контролируемой иностранной компании;
• 26 — взносы на ОПС;
• 27 — взносы на ОСС в связи с нетрудоспособностью;
• 28 — взносы на ОМС;
• 29 — взносы на ОСС от несчастных случаев;
• 30 — пособие по временной нетрудоспособности;
• 31 — платежи по добровольному личному страхованию.

• 0 — банковский платёжный агент;
• 1 — банковский платёжный субагент;
• 2 — платёжный агент;
• 3 — платёжный субагент;
• 4 — поверенный;
• 5 — комиссионер;
• 6 — агент, но не являющийся банковским платёжным агентом (субагентом), платёжным агентом (субагентом), поверенным, комиссионером.

• 0 или «Income» — получение денежных средств от покупателя;
• 1 или «IncomeReturn» — возврат денежных средств, полученных от покупателя;
• 2 или «IncomePrepayment» — авансовый платеж от покупателя;
• 3 или «IncomeReturnPrepayment» — возврат аванса;
• 4 или «IncomeCorrection» — чек коррекции/приход;
• 5 или «BuyCorrection» — чек коррекции/расход;
• 6 или «Expense» — выдача денежных средств покупателю;
• 7 или «ExpenseReturn» — возврат денежных средств, выданных покупателю.

При ошибках, возникающих при работе сервиса, возвращается ошибка HTTP с номером 500.

Таблица 3. Ошибки сервиса

• Ошибка при преобразовании строковых данных из кодировки UTF-8 в кодировку Windows-1251.
• Значение реквизита «признак способа расчёта» отличается от перечисленных в п.п. 2.2. или не соответствует условиям изложенным там же.
• Код налога выходит за пределы диапазона 1…6.
• Параметр TaxMode имеет более одного установленного бита, причём этот бит должен быть один из тех, которые были указаны при регистрации.
• Строка содержит символы, недопустимые в кодировке CP866.
• Пустое наименование товарной позиции.

Во время исполнения команды в устройстве произошёл сбой, который возможно перевёл устройство в состояние фатальной ошибки.

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

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

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

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

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

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

Для того чтобы пробить чеки на кассе Ferma, которая находится в ЛКК, используйте данные:
Авторизация осуществляется по сертификату.

Чтобы получить сертификат, необходимо зайти в свой ЛКК.

Зайти в раздел Сервис Ferma

Здесь на странице найти Реквизиты доступа

В реквизитах доступа нажать следующую кнопку

Рабочий сертификат будет скачан на устройство

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

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

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

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

Версия 1.3
Выпущена 20 октября 2020 г.
Изменен продуктовый URL на ferma-c.ofd.ru

Версия 1.4
Выпущена 29 октября 2020 г.
Добавлена ссылка на сертификат для тестового доступа.

Версия 1.5
Выпущена 20 декабря 2021 г.
Исправлены мелкие недочеты