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

В документе приводятся технические сведения о программном интерфейсе приложений (API) предоставляющем возможность регистрировать онлайн-кассы и инициировать генерацию кассовых документов посредством информационной системы (ИС) “Ferma”.
Обмен данными с онлайн-кассами происходит по протоколу HTTP с использованием зашифрованного канала (HTTPS). Данные запросов и ответов передаются в виде структуры JSON. Вне зависимости от наличия ошибок в данных, обязательным условием успешного выполнения запроса является ответ с кодом 200 согласно протоколу HTTP.
Ниже описаны запросы HTTP, которыми реализуются функции API по работе с онлайн-кассами.
На рисунке 1 показана схема запросов к ИС “Ferma”. Для получения данных по чекам и кассовым аппаратам, используйте API "Чеки и ККТ".

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

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

Здесь ключу «Data» соответствует пустое поле; ключ введен в структуру для обеспечения единообразия запросов в ИС “Ferma”; параметр «Status» – состояние обработки запроса – в данном случае имеет значение «Success» (запрос обработан успешно).
В случае неуспешности ответа (код ответа по протоколу HTTP не равен 200) данные имеют следующий обобщенный вид:

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

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

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

--- BEGIN ---
POST https://ferma.ofd.ru/api/Authorization/CreateAuthToken HTTP/1.1
Content-Length: 38
Content-Type: application/json; charset=utf-8
{"Login": "12345","Password": "56789"}
--- END ---

В данном запросе присутствуют примеры значений: передаваемое имя пользователя – «12345» и пароль – «56789»; они задаются как значения в JSON-структуре внутри запроса с ключами «Login» и «Password» соответственно. В ответ на данный запрос будет получен ответ по протоколу HTTP, который в случае успешной авторизации будет иметь код равный 200 и содержать структуру, подобную следующей (приведены примеры значений):

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

Здесь с ключом «AuthToken» – код авторизации: строка символов AuthToken, представляет собой 32-значную последовательность шестнадцатеричных цифр, используемую для повторной аутентификации, а ключ «ExpirationDateUtc» – строка, описывающая момент времени (дату и время в формате UTC), до которого будет действовать данный код авторизации. Момент времени задается в формате «ГГГГ-ММ-ДДTчч:мм:сс» ¹⁾; здесь
ГГГГ – год даты, 4 цифры,
ММ – месяц даты, 2 цифры,
ДД – день даты 2 цифры,
T – заглавная латинская буква “T”, используется как разделитель даты и времени,
чч – часы, 2 цифры,
мм – минуты, 2 цифры,
сс – секунды, 2 цифры.

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

POST https://ferma.ofd.ru/api/kkt/cloud/receipt?AuthToken=Code1

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

Вид запроса:

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

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

{
  "Request": {
    "Inn": "string",
    "Type": "string",
    "InvoiceId": "string",
    "LocalDate": "2017-01-24T14:13:24",
    "CustomerReceipt": {
      "TaxationSystem": "Common",
      "Email": "string",
      "Phone": "string",
      "PaymentType": 1,
      "KktFA": false,
      "BillAddress": "Москва, ул. Ленина, 77",
      "AutomaticDeviceNumber": "0284959493",
      "CustomUserProperty": {
        "Name": "название доп. атрибута",
        "Value": "значение доп. атрибута"
      },
      "PaymentAgentInfo": {
        "AgentType": "BANK_PAYMENT_AGENT",
      },
      "CorrectionInfo": {
        "Type": "SELF",
        "Description": "Неприменение ККТ",
        "ReceiptDate": "20.07.18",
        "ReceiptId": "123456"
      },
      "ClientInfo": {
        "Name": "Иванов Иван Иванович 9910 777777",
        "Inn": "450148839601"
      },
      "Items": [
        {
          "Label": "string",
          "Price": 0,
          "Quantity": 0,
          "Amount": 0,
          "Vat": "string",
          "MarkingCode": "000559D39E7F197241424331323334",
          "MarkingCodeStructured": {
            "Type": "MEDICINES",
            "Gtin": "77777777777777",
            "Serial": "RXWWWRRRRRRRR"
          },
          "PaymentMethod": 3,
          "OriginCountryCode": "398",
          "CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
          "PaymentType": 4,
          "PaymentAgentInfo": {
            "AgentType": "BANK_PAYMENT_AGENT",
            "TransferAgentPhone": "89061234567",
            "TransferAgentName": "наименование оператора перевода",
            "TransferAgentAddress": "адрес оператора перевода",
            "TransferAgentINN": "1234567890",
            "PaymentAgentOperation": "операция платежного агента",
            "PaymentAgentPhone": "89061234567",
            "ReceiverPhone": "89061234567",
            "SupplierInn": "012345678901",
            "SupplierName": "Иван Иванов",
            "SupplierPhone": "89061234567"
          },
        }, ...
      ],
      "PaymentItems": [
        {
          "PaymentType": 0,
          "Sum": 0.0
        }, ...
      ]
    },
    "Cashier": {
      "Name": "KASSIRNAME",
      "Inn": "991133557"
    }
  }
}

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

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

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

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

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

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

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

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

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

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

• 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 — о залоге – «ЗАЛОГ».

Внимание! Некоторые комбинации предметов расчета и систем налогообложения могут вызывать ошибку. Это связано с особенностями работ касс.

• 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 — платежи по добровольному личному страхованию

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

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

• «Не найдены данные компании с ИНН Y», где Y — значение ИНН;
• «Доступ запрещен»;
• «Ошибка создания чека: X», где X — сообщение сервера системы;
• «Превышено максимальное количество обращений», максимальное количество сообщений рассчитывается по максимальной допустимой нагрузке на кассу: один чек в 3 секунды;
• Код ошибки 1038 – длина поля ClientInfo.Name превышает максимальную длину в 256 символов;
• Код ошибки 1039 – неверно указан ИНН клиента в поле ClientInfo.Inn;
• Код ошибки 1047 – попытка пробить вендинговый чек (KktFA = true) не на кассах ФА;
• Код ошибки 1048 – попытка пробить не вендинговый чек (KktFA = false) на терминалах-ФА;
• Код ошибки 1049 – неверно указан номер автомата(AutomaticDeviceNumber). Максимальная длина 20 символов;
• Код ошибки 1050 – неверно указано место расчёта (BillAddress). Максимальная длина 255 символов;
• Код ошибки 1051 – неверное значение в поле наименования предмета расчета (Label) при указанном признаке предмета расчета (PaymentType)

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

POST https://ferma.ofd.ru/api/kkt/cloud/status

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

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

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

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

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

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

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

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

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

• запрос на чек принят ИС «Ferma»:
  • «StatusCode»: 0,
  • «StatusName»: «NEW»,
  • «StatusMessage»: «запрос на чек принят Фермой»,
• чек сформирован на кассе:
  • «StatusCode»: 1,
  • «StatusName»: «PROCESSED»,
  • «StatusMessage»: «чек сформирован на кассе»,
• чек передан в ОФД:
  • «StatusCode»: 2,
  • «StatusName»: «CONFIRMED»,
  • «StatusMessage»: «чек передан в ОФД»
• чек не передан в ОФД, нужно отправить повторно:
  • «StatusCode»: 3,
  • «StatusName»: «KKT_ERROR»

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

В случае, если чек не прошёл ФЛК при пробитие на кассе, ответ имеет следующий вид:

{
  "Status": "Success",
  "Data": {
    "StatusCode": 3,
    "StatusName": "KKT_ERROR",
    "StatusMessage": "Ошибка пробития чека на кассе",
    "Description": "[-3975] Некорректное значение параметров команды ФН",
    "ModifiedDateUtc": "2019-07-25T12:08:00",
    "ReceiptDateUtc": null,
    "Device": null
  }
}

При получении данной ошибки, необходимо повторно отправить запрос на пробитие чека.

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

Таблица 3.3.

Запрос реестра кассовых чеков включает в себя 2 метода: При использовании этого метода в ответе возвращается информация о серверном времени обработки чека. Смотри таблицу 4.2.

POST https://ferma.ofd.ru/api/kkt/cloud/list

И

При использовании этого метода в ответе возвращается информация о времени пробитии чека на кассе (время кассы). Смотри таблицу 4.2.

POST https://ferma.ofd.ru/api/kkt/cloud/list2

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

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

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

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

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

{
  "Status": "Success",
  "Data": [
    {
      "ReceiptId": "e0d2212f-4e85-475a-8e6e-c533f233e1d9",
      "StatusCode": 1,
      "StatusName": "Чек сформирован на кассе",
      "StatusMessage": "PROCESSED",
      "ModifiedDateUtc": "2017-01-24T14:13:24",
      "ReceiptDateUtc": "2019-11-22T14:36:21",
      "InvoiceID": "50000249010",
      "Receipt": {
        "cashboxInfoHolder": {
          "DeviceId": 6045,
          "RNM": "0000000116046792",
          "ZN": "00107701223456",
          "FN": "9999078900011688",
          "FDN": "0000003397",
          "FPD": "2106376249"
        },
        "Inn": "3245001416",
        "Type": "Income",
        "InvoiceId": "A795769D-C27F-44D7-AAF0-D050A6880D21",
        "CustomerReceipt": {
          "TaxationSystem": "Common",
          "Email": "azudin@sol2b.com",
          "Phone": "+7(495)988-78-77",
          "PaymentType": 10,
          "PaymentAgentInfo": {
            "AgentType": "BANK_PAYMENT_AGENT",
          },
          "CorrectionInfo": {
            "Type": "SELF",
            "Description": "Неприменение ККТ",
            "ReceiptDate": "20.07.18",
            "ReceiptId": "123456"
          },
          "ClientInfo": {
            "Name": "Иванов Иван Иванович 9910 777777",
            "Inn": "450148839601"
          },
          "Items": [
            {
              "Label": "Товар",
              "Price": 100,
              "Quantity": 1,
              "Amount": 100,
              "Vat": "Vat20",
              "MarkingCode": "E2800000000000000019",
              "MarkingCodeStructured": null,
              "PaymentMethod": 0,
              "PaymentType": 0,
              "OriginCountryCode": null,
              "CustomsDeclarationNumber": null,
              "PaymentAgentInfo": {
                "AgentType": "BANK_PAYMENT_AGENT",
                "TransferAgentPhone": "89061234567",
                "TransferAgentName": "наименование оператора перевода",
                "TransferAgentAddress": "адрес оператора перевода",
                "TransferAgentINN": "1234567890",
                "PaymentAgentOperation": "операция платежного агента",
                "PaymentAgentPhone": "89061234567",
                "ReceiverPhone": "89061234567",
                "SupplierInn": "012345678901",
                "SupplierName": "Иван Иванов",
                "SupplierPhone": "89061234567"
              }
            }
          ],
          "PaymentItems": [
            {
              "PaymentType": 0,
              "Sum": 0.0
            }, ...
          ]
          "CustomUserProperty": null
        }
      }
    }
  ]
}

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

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

В случае, если чек не прошёл ФЛК при пробитие на кассе, ответ имеет следующий вид:

{
  "Status": "Success",
  "Data": {
    "StatusCode": 3,
    "StatusName": "KKT_ERROR",
    "StatusMessage": "Ошибка пробития чека на кассе",
    "Description": "[-3975] Некорректное значение параметров команды ФН",
    "ModifiedDateUtc": "2019-07-25T12:08:00",
    "ReceiptDateUtc": null,
    "Device": null
  }
}

При получении данной ошибки, необходимо повторно отправить запрос на пробитие чека.

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

Таблица 4.2

Вид запроса:

GET https://ferma.ofd.ru/api/kkt/cloud/stats/fn/aggregates?dateFrom=Date1&dateTo=Date2&AuthToken=Code1

Здесь Date1 и Date2 – начальная и конечная даты периода, за который будет получен список ККТ, которые обрабатывали ФД – строка символов, содержащая дату и время в формате ISO. Code1 – действующий код авторизации, полученный в результате запроса авторизации.

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

{
  "Status": "Success",
  "Data": [
    {
      "fn": "9280440300111111",
      "firstReceiptDate": "2019-07-16",
      "lastReceiptDate": "2019-07-16"
    },
    {
      "fn": "9280440300222222",
      "firstReceiptDate": "2019-07-16",
      "lastReceiptDate": "2019-07-16"
    },
    ...
  ]
}

Вид запроса:

POST https://ferma.ofd.ru/api/edo/VERSION/drafts/draft/add&AuthToken=Code1

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

{
  "to": "2PS-00631566061106315010010016107897",
  "docType": 7,
  "content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNv...",
  "fileName": "my_file.txt"
  "isSignRequested": false
}

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

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

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": {
    "data": [
      {
        "errorCode": [
          {
            "code": 11,
            "desc": "Некорректный XML файл"
          }
        ],
        "data": {
          "draftId": 808,
          "fromOrgId": "859",
          "fromOrgName": "Общество с ограниченной ответственностью ПРОДУКТЫ 24",
          "toOrgId": "859",
          "toOrgName": "Общество с ограниченной ответственностью ПРОДУКТЫ 24",
          "edoIdFrom": "2PS-00783908888003511154340097777777",
          "edoIdTo": "2PS-00783908888003511154340097777777",
          "docTypeId": 8,
          "docTypeName": "УПД",
          "innFrom": "7839088000",
          "innTo": "7839088000",
          "kppFrom": "351744444",
          "kppTo": "351744444",
          "content": null,
          "xmlBody": null,
          "fileName": "ON_SCHFDOPPR_2PS-00784446519907841010010013609999_2PS-00783908888003517444340099992397_20190725_7b7000bb-f4b1-40ac-9efe-55b6f1166b22.xml",
          "docName": "Счет-фактура и документ об отгрузке товаров (выполнении работ), передаче имущественных прав (документ об оказании услуг)",
          "docNumber": "1ССФПРОФД19/19757   ",
          "docDate": "25.07.2019 00:00:00",
          "sumAll": 35000,
          "sumNds": 5833.33,
          "statusId": 0,
          "statusName": "Не готов",
          "nds": true,
          "signRequested": false,
          "updated": "26.08.2019 16:52:25"
        }
      }
    ]
  }
}

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

Таблица 5.2.

Вид запроса:

GET https://ferma.ofd.ru/api/edo/VERSION/drafts?pageIndex=Pageindex&pageRecords=Pagerecords&sortKey=Key1&sortDirection=Dir1&docTypeId=Doctypeid&from=Datetime1&to=Datetime2&orgNameTo=Orgnameto&orgInnTo=Orginnto&status=Status&AuthToken=Code1

Здесь Pageindex - номер запрашиваемой страницы списка документов в виде десятичного целого числа. Pagerecords - количество записей на странице в виде десятичного целого числа. Key1 - столбец для сортировки. Dir1 - определяет порядок сортировки. Возможные значения: asc — восходящая (прямой порядок) и desc — нисходящая (обратный порядок). Doctypeid - уникальный идентификационный номер типа документа. Datetime1 и Datetime2 – начальное и конечное время и даты периода в формате ISO, за который будет получен список черновиков. Orgnameto - наименование организации получателя документа. Orginnto - ИНН получателя документа. Status - статус готовности отправки черновика. Code1 – действующий код авторизации, полученный в результате запроса авторизации.

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

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": {
    "data": [
      {
        "errorCode": [
          {
            "code": 11,
            "desc": "Некорректный XML файл"
          }
        ],
        "data": {
          "draftId": 808,
          "fromOrgId": "859",
          "fromOrgName": "Общество с ограниченной ответственностью ПРОДУКТЫ 24",
          "toOrgId": "859",
          "toOrgName": "Общество с ограниченной ответственностью ПРОДУКТЫ 24",
          "edoIdFrom": "2PS-00783908888003511154340097777777",
          "edoIdTo": "2PS-00783908888003511154340097777777",
          "docTypeId": 8,
          "docTypeName": "УПД",
          "innFrom": "7839088000",
          "innTo": "7839088000",
          "kppFrom": "351744444",
          "kppTo": "351744444",
          "content": null,
          "xmlBody": null,
          "fileName": "ON_SCHFDOPPR_2PS-00784446519907841010010013609999_2PS-00783908888003517444340099992397_20190725_7b7000bb-f4b1-40ac-9efe-55b6f1166b22.xml",
          "docName": "Счет-фактура и документ об отгрузке товаров (выполнении работ), передаче имущественных прав (документ об оказании услуг)",
          "docNumber": "1ССФПРОФД19/19757   ",
          "docDate": "25.07.2019 00:00:00",
          "sumAll": 35000,
          "sumNds": 5833.33,
          "statusId": 0,
          "statusName": "Не готов",
          "nds": true,
          "signRequested": false,
          "updated": "26.08.2019 16:52:25"
        },
        ...
      }
    ],
    "pageInfo": {
      "pageIndex": 1,
      "pageRecords": 1000,
      "pageCount": 1,
      "sortKey": null,
      "sortDirection": "desc"
    }
  }
}

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

Вид запроса:

GET https://ferma.ofd.ru/api/edo/VERSION/drafts/draft?draftId=Draftid&AuthToken=Code1

Здесь Draftid – идентификатор черновика. Получить его можно при добавлении черновика, смотри п. 3.5. Code1 – действующий код авторизации, полученный в результате запроса авторизации.

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

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": {
    "data": [
      {
        "errorCode": [
          {
            "code": 11,
            "desc": "Некорректный XML файл"
          }
        ],
        "data": {
          "draftId": 808,
          "fromOrgId": "859",
          "fromOrgName": "Общество с ограниченной ответственностью ПРОДУКТЫ 24",
          "toOrgId": "859",
          "toOrgName": "Общество с ограниченной ответственностью ПРОДУКТЫ 24",
          "edoIdFrom": "2PS-00783908888003511154340097777777",
          "edoIdTo": "2PS-00783908888003511154340097777777",
          "docTypeId": 8,
          "docTypeName": "УПД",
          "innFrom": "7839088000",
          "innTo": "7839088000",
          "kppFrom": "351744444",
          "kppTo": "351744444",
          "content": null,
          "xmlBody": null,
          "fileName": "ON_SCHFDOPPR_2PS-00784446519907841010010013609999_2PS-00783908888003517444340099992397_20190725_7b7000bb-f4b1-40ac-9efe-55b6f1166b22.xml",
          "docName": "Счет-фактура и документ об отгрузке товаров (выполнении работ), передаче имущественных прав (документ об оказании услуг)",
          "docNumber": "1ССФПРОФД19/19757   ",
          "docDate": "25.07.2019 00:00:00",
          "sumAll": 35000,
          "sumNds": 5833.33,
          "statusId": 0,
          "statusName": "Не готов",
          "nds": true,
          "signRequested": false,
          "updated": "26.08.2019 16:52:25"
        }
      }
    ]
  }
}

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

Таблица 7.

Вид запроса:

POST https://ferma.ofd.ru/api/edo/VERSION/drafts/remove&AuthToken=Code1

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

{
  "draftId": "2604"
}

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

Пример успешного ответа на запрос описан в п. 3.7, при этом параметр «message» имеет значение «OK», а «result» имеет значение «null».

Вид запроса:

GET https://ferma.ofd.ru/api/edo/VERSION/drafts/download?draft=ID1&downloadType=Type1&AuthToken=Code1

Здесь ID1 - идентификатор загружаемого черновика. Получить его можно при добавлении черновика, смотри п. 3.5. Type1 - Тип загрузки черновика. Возможны варианты: CURRENT – загрузка только текущего документа с заданным идентификатором; PDF – в формате PDF. Code1 – действующий код авторизации, полученный в результате запроса авторизации.

Вид запроса:

GET https://ferma.ofd.ru/api/edo/VERSION/drafts/show-pdf?draftId=ID1&AuthToken=Code1

Здесь ID1 - идентификатор черновика документа, на основе которого по запросу генерируется документ в формате PDF. Получить его можно при добавлении черновика, смотри п. 3.5. Code1 – действующий код авторизации, полученный в результате запроса авторизации.

В ответ на данный запрос начинается загрузка файла в двоичном виде. В заголовках ответа (response headers) указывается имя загружаемого файла.

Версия 2.0
Выпущена 24 августа 2018 г.
Первая регистрируемая версия документа.

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

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

Версия 2.2
Выпущена 17 января 2019 г.
Исправлена ошибка в тексте предыдущей версии документа: замена строки «FPD» на «FDP» в примерах структур данных.

Версия 2.3
Добавлена 28 января 2019 г.
Добавлена информация в соответствии с изменениями в структуре данных CustomerReceipts.

Версия 2.6
Добавлена 04 апреля 2019 г.

• исправлена ошибка в тексте предыдущей версии документа: замена в таблице 3.2 «FPN» на «FDP»;
• исправлена ошибка в тексте предыдущей версии документа: удаление лишней запятой в строке ответа при запросе кассового чека.

Версия 2.7
Добавлена 28 мая 2019 г.

• добавлена новая структура данных CustomUserProperty и параметры в структуру данных;
• признаки предмета расчета были перенесены из таблицы 2 в п. 3.4.1.

Версия 2.8
Добавлена 19 июня 2019 г.

• добавлена новая структура данных ClientInfo и параметры в структуру данных;
• добавлены возможные ошибки «Код ошибки 1038» и «Код ошибки 1039».

Версия 2.9
Добавлена 21 июня 2019 г.

• добавлено новое значение BuyCorrection — чек коррекции/расход для параметра «Type»;
• добавлен новый параметр PaymentType в массив структур Items.

Версия 2.10
Добавлена 08 июля 2019 г.

• у параметра MarkingCode было изменено значение с строка на структуру;
• были добавлены параметры Type, Gtin, Serial в структуру MarkingCode.

Версия 2.11
Добавлена 15 июля 2019 г.

• наименование структуры MarkingCode было изменено на MarkingCodeStructured;
• был добавлен параметры MarkingCode, который имеет значения «Строка»;
• в формирование кассового чека были добавлены параметры OriginCountryCode и CustomsDeclarationNumber.

Версия 2.12
Добавлена 16 июля 2019 г.
Добавлен метод для получения списка ККТ, которые обрабатывали ФД в определенный период

Версия 2.13
Добавлена 17 июля 2019 г.
В формирование кассового чека добавлены теги: 1171, 1225, 1226

Версия 2.14
Добавлена 25 июля 2019 г.
В метода «Проверка статуса кассового чека» и «Запрос реестра кассовых чеков» добавлена ошибка, если чек не прошёл ФЛК при пробитие на кассе

Версия 2.15
Добавлена 03 сентября 2019 г.
Добавлены методы для работы с черновиками

Версия 2.16
Добавлена 12 ноября 2019 г.
Добавлена схема запросов к ИС «Ferma»; Добавлено описание логики работы параметра PaymentType для всего чека при запросе на формирование кассового чека.

Версия 2.17
Добавлена 26 ноября 2019 г.
Добавлен метод list2; Добавлена структура Cashier при формировании чека; Актуализирован ответ при запросе реестра кассовых чеков.

Версия 2.18
Добавлена 10 января 2020 г.
Добавлено условие, как правильно нужно заполнять параметр Label в API-запросе; Добавлена ошибка 1051, которая возникает при неверно заполненном параметре Label.