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

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

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

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

Здесь:

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

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

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

Здесь:

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

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

Параметры запроса:
HTTP/1.1
Content-Length: 38
Content-Type: application/json
charset=utf-8

Вид запроса:

POST https://ferma.ofd.ru/api/Authorization/CreateAuthToken

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

{
    "Login": "12345","Password": "56789"
}

В данном запросе присутствуют примеры значений: Login – «12345» и Password – «56789». Они задаются как значения в JSON-структуре внутри запроса.
Их можно получить в личном кабинете клиента в разделе «Ferma», после покупки кассы Ferma, либо у вашего менеджера.

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

{
    "Status": "Success",
    "Data": {
        "AuthToken": "f3accdfda7574736ba94a78d00e974f4",
        "ExpirationDateUtc": "2017-01-24T14:44:21"
    }
}

Здесь:

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

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

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

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

Внимание. Сервис Ferma является асинхронным, отправка чека методом “Receipt” и успешное получение идентификатора транзакции не является финальным завершением операции пробития чека. Для завершения операции необходимо настроить корректную обработку Callback ответов и настроить получение данных по чеку через методы “Status”, “list”, “list2”.

Вид запроса:

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

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

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

{
    "Request": {
        "Inn": "0123456789",
        "Type": "Income",
        "InvoiceId": "15975364820",
        "LocalDate": "2020-01-24T14:13:24",
        "CallbackUrl": "http://testcallbackurl:12345",
        "CustomerReceipt": {
            "TaxationSystem": "Common",
            "Email": "example@mail.ru",
            "Phone": "+79000000000",
            "PaymentType": 1,
            "KktFA": true,
            "AutomatNumber": "123456",
            "BillAddress": "Москва, ул. Ленина, 77",
            "CustomUserProperty": {
                "Name": "название доп. атрибута",
                "Value": "значение доп. атрибута"
            },
            "PaymentAgentInfo": {
                "AgentType": "BANK_PAYMENT_AGENT",
                "TransferAgentPhone": "+79000000001",
                "TransferAgentName": "наименование оператора перевода",
                "TransferAgentAddress": "адрес оператора перевода",
                "TransferAgentINN": "1234567890",
                "PaymentAgentOperation": "операция платежного агента",
                "PaymentAgentPhone": "+79000000002",
                "ReceiverPhone": "+79000000003",
                "SupplierInn": "012345678901",
                "SupplierName": "Иван Иванов",
                "SupplierPhone": "+79000000004"
            },
            "CorrectionInfo": {
                "Type": "SELF",
                "Description": "Неприменение ККТ",
                "ReceiptDate": "20.07.18",
                "ReceiptId": "123456"
            {
            "ClientInfo": {
                "Name": "Иванов Иван Иванович",
                "Inn": "450148839601",
                "Birthday": "05-01-1985",
                "Citizenship": "003",
                "IdDocType": "RF_ID",
                "IdDocData": "4705 493567",
                "Address": "г.Москва, Гороховский переулок д.7 кв 56"
            },
            "IndustryRequisite": {
                "FoivId": "001",
                "DocDate": "06-08-2021",
                "DocNumber": "123/43",
                "Value": "Ид1=Знач1&Ид2=Знач2&Ид3=Знач3"
            },
            "OperationRequisite": {
                "Id": "0",
                "Details": "Данные операции",
                "DateTime" : "06-08-2021 10:05:20"
            }
          }
            "Items": [
                {
                    "Label": "Мороженое",
                    "Price": 5,
                    "Quantity": 50,
                    "Amount": 250,
                    "Vat": "Vat0",
                    "MarkingCodeData": {
                      "Type": "GS1M",
                      "Code": "1234",
                      "PlannedStatus": "PRODUCT_STATUS_NOT_CHANGED",
                      "Fractional": {
                        "Numerator": 1,
                        "Denominator": 10
                        }
                      },
                    "Measure": "PIECE"
                 },
                    "PaymentMethod": 3,
                    "AdditionalRequisite": "TAG_1191"
                    "OriginCountryCode": "398",
                    "CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
                    "PaymentType": 4,
                    "PaymentAgentInfo": {
                        "AgentType": "BANK_PAYMENT_AGENT",
                        "TransferAgentPhone": "+79000000001",
                        "TransferAgentName": "наименование оператора перевода",
                        "TransferAgentAddress": "адрес оператора перевода",
                        "TransferAgentINN": "1234567890",
                        "PaymentAgentOperation": "операция платежного агента",
                        "PaymentAgentPhone": "+79000000002",
                        "ReceiverPhone": "+79000000003",
                        "SupplierInn": "012345678901",
                        "SupplierName": "Иван Иванов",
                        "SupplierPhone": "+79000000004"
                    },
                },
                ...
            ],
            "PaymentItems": [
                {
                    "PaymentType": 0,
                    "Sum": 0.0
                },
                ...
            ],
            "AdditionalReceiptProp": "1234567890"
        },
        "Cashier": {
            "Name": "Фёдорова Нина Тихомирова",
            "Inn": "991133557"
        }
    }
}

Таблица 3.1. Значения атрибута «Обязательность»

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

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

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

Таблица 3.4. Параметры элементов структуры «Items» ТЕГ 1059

Таблица 3.5. Параметры элементов структуры «MarkingCodeData» ТЕГ 1163

Внимание! Тег 1224 не передается в составе кассового чека, передаются только теги из его состава, а именно тег 1225 и 1171. Теги передаются в составе тега 1223.

Таблица 3.6. Структура, содержащая данные платежного агента ТЕГ 1223

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

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

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

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

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

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

• «Income» — получение денежных средств от покупателя;
• «IncomeReturn» — возврат денежных средств, полученных от покупателя;
• «IncomePrepayment» — авансовый платеж от покупателя;
• «IncomeReturnPrepayment» — возврат аванса;
• «IncomeCorrection» — чек коррекции/приход;
• «BuyCorrection» — чек коррекции/расход;
• «IncomeReturnCorrection» - чек коррекции/Возврат прихода;
• «ExpenseReturnCorrection» - чек коррекции/Возврат расхода;
• «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 — о залоге – «ЗАЛОГ».

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

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

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

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

Касса ФА используется:

• Вендинговый аппарат - применяется для платежных терминалов, почтоматов и других;
• Транспортные компании - при совершении расчетов за проезд в автоматизированном режиме(через валидатор) или при совершении расчетов через терминал кондуктора.

Чек получения денежных средств с информацией о клиенте:

{
    "Inn": "2465165753",
    "Type": "Income",
    "InvoiceId": "1",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "SimpleIn",
        "Email": "example@yandex.ru",
        "Phone": "+79000000000",
        "AutomaticDeviceNumber": null,
        "PaymentType": 1,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo": {
             "Name": "Иванов Иван Иванович",
             "Inn": "5645645319"
        },
        "Items": [
            {
                "Label": "Апартамент A005 с 21.08 по 25.08",
                "Price": 7600.0,
                "Quantity": 1.0,
                "Amount": 7600.0,
                "Vat": "VatNo",
                "MarkingCodeStructured": null,
                "MarkingCode": null,
                "PaymentMethod": 3,
                "PaymentType": 4,
                "OriginCountryCode": "643",
                "CustomsDeclarationNumber": null,
                "PaymentAgentInfo": null
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

Чек коррекции/приход:

{
    "Inn": "0123456789",
    "Type": "IncomeCorrection",
    "InvoiceId": "test2_874427356",
    "LocalDate": "2019-08-15T07:24:06",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": null,
        "CorrectionInfo": {
            "Type": "SELF",
            "Description": "l",
            "ReceiptDate": "15.08.19",
            "ReceiptId": "_"
        },
        "Items": [
            {
                "Label": "Расходы",
                "Price": 1,
                "Quantity": 1,
                "Amount": 1,
                "Vat": "CalculatedVat20120",
                "PaymentMethod": 4,
                "PaymentType": 4
            }
        ]
    }
}

Простой чек получения денежных средств:

{
    "Inn": "0123456789",
    "Type": "Income",
    "InvoiceId": "6f000fee-bbac-4444-bda1-e9ce9999fcc7",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@ya.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "Items": [
            {
                "Label": "Оплата услуг по страхованию.",
                "Price": 5328.53,
                "Quantity": 1.0,
                "Amount": 5328.53,
                "Vat": "VatNo",
                "MarkingCode": null,
                "PaymentMethod": 0
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

Простой чек получения денежных средств с таможенной информацией:

{
    "Inn": "284691370",
    "Type": "Income",
    "InvoiceId": "6f110fee-bbac-7777-bda1-e9555996fcc4",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo" : null,
        "Items": [
            {
                "Label": "Таблетки от кашля иностранные",
                "Price": 10.00,
                "Quantity": 1.0,
                "Amount": 10.00,
                "Vat": "VatNo",
                "MarkingCode": null,
                "PaymentMethod": 0,
                "OriginCountryCode": "398",
                "CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
                "PaymentType": 10
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

Простой чек получения денежных средств с разными признаками предмета расчета (PaymentType):

{
    "Inn": "5319782640",
    "Type": "Income",
    "InvoiceId": "6f110fee-bbac-4446-bda1-e9ce2996fcc3",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo" : null,
        "Items": [
            {
                "Label": "Оплата услуг по страхованию.",
                "Price": 10.00,
                "Quantity": 1.0,
                "Amount": 10.00,
                "Vat": "VatNo",
                "MarkingCode": null,
                "PaymentMethod": 0,
                "PaymentType": 10
            },
            {
                "Label": "Услуга по страхованию.",
                "Price": 100.00,
                "Quantity": 1.0,
                "Amount": 100.00,
                "Vat": "Vat20",
                "MarkingCode": null,
                "PaymentMethod": 0,
                "PaymentType": 3
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

Простой чек получения денежных средств с разными поставщиками (Supplier):

{
    "Inn": "5645648283",
    "Type": "Income",
    "InvoiceId": "6f000fee-bbac-4444-bda1-e9111111fcc8",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@yandex.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo": null,
        "Items": [
            {
                "Label": "Таблетки от кашля иностранные",
                "Price": 10.00,
                "Quantity": 1.0,
                "Amount": 10.00,
                "Vat": "VatNo",
                "MarkingCode": null,
                "PaymentMethod": 0,
                "OriginCountryCode": "398",
                "CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
                "PaymentType": 10,
                "PaymentAgentInfo": {
                    "AgentType": "PAYMENT_SUBAGENT",
                    "TransferAgentPhone": "+79000000002",
                    "TransferAgentName": "ГУП ВЦКП \"Жилищное хозяйство\"",
                    "TransferAgentAddress": "190031, Санкт-Петербург,Наб. р. Фонтанки, 105",
                    "TransferAgentINN": "7984798465",
                    "PaymentAgentOperation": "Оплата по лицевому счету",
                    "PaymentAgentPhone": "+79000000003",
                    "ReceiverPhone": "",
                    "SupplierInn": "1739818379",
                    "SupplierName": "Купец Иванов",
                    "SupplierPhone": "+79000000004"
                }
            },
            {
                "Label": "Таблетки от жадности иностранные",
                "Price": 10.00,
                "Quantity": 1.0,
                "Amount": 10.00,
                "Vat": "VatNo",
                "MarkingCode": null,
                "PaymentMethod": 0,
                "OriginCountryCode": "398",
                "CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
                "PaymentType": 10,
                "PaymentAgentInfo": {
                    "AgentType": "PAYMENT_SUBAGENT",
                    "TransferAgentPhone": "+79000000002",
                    "TransferAgentName": "ГУП ВЦКП \"Жилищное хозяйство\"",
                    "TransferAgentAddress": "190031, Санкт-Петербург,Наб. р. Фонтанки, 105",
                    "TransferAgentINN": "7984798465",
                    "PaymentAgentOperation": "Оплата по лицевому счету",
                    "PaymentAgentPhone": "+79000000003",
                    "ReceiverPhone": "",
                    "SupplierInn": "2839172837",
                    "SupplierName": "ООО Медсерв и Ко",
                    "SupplierPhone": "+79000000005"
                }
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

Простой чек получения денежных средств с кодом маркировки (MarkingCodeStructured):

{
    "Inn": "089137465",
    "Type": "Income",
    "InvoiceId": "6f550fee-bbac-4445-bda1-e5111556fcc5",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@yahoo.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo" : null,
        "Items": [
            {
                "Label": "Таблетки от кашля",
                "Price": 10.00,
                "Quantity": 1.0,
                "Amount": 10.00,
                "Vat": "VatNo",
                "MarkingCodeStructured": {
                    "Type": "MEDICINES",
                    "Gtin": "05995327115555",
                    "Serial": "RXFMY9PH7ZZZZ"
                },
                "PaymentMethod": 0,
                "PaymentType": 10
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

Простой чек получения денежных средств с кодом маркировки (MarkingCode) вид 2:

{
    "Inn": "0258469137",
    "Type": "Income",
    "InvoiceId": "6f290fee-bbac-1111-bda1-e1111116fcc1",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo" : null,
        "Items": [
            {
                "Label": "Таблетки от кашля",
                "Price": 10.00,
                "Quantity": 1.0,
                "Amount": 10.00,
                "Vat": "VatNo",
                "MarkingCode": "0003574EA75F63675258464D5939504837435A5057",
                "PaymentMethod": 0,
                "PaymentType": 10
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

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

{
    "Inn": "4613794639",
    "Type": "Income",
    "InvoiceId": "1",
    "LocalDate": "2019-08-15T17:27:52",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@yahoo.ru",
        "PaymentType": 0,
        "CustomUserProperty": null,
        "PaymentAgentInfo": {
            "AgentType": "BANK_PAYMENT_SUBAGENT",
            "TransferAgentPhone": "+79000000001",
            "TransferAgentName": "ПАО Сбербанк",
            "TransferAgentAddress": "г. Екатеринбург, ул.Московская 11",
            "TransferAgentINN": "1346976431",
            "PaymentAgentOperation": "Оплата по лицевому счету",
            "PaymentAgentPhone": "+79000000002"
        },
        "Items": [
            {
                "Label": "Услуги ЖКХ по л/с 4340119233",
                "Price": 889.00,
                "Quantity": 1.0,
                "Amount": 889.00,
                "Vat": "VatNo",
                "PaymentMethod": 4,
                "PaymentType": 4
            }
        ],
        "PaymentItems": [
            {
                "PaymentType": 1,
                "Sum": 889.00
            }
        ]
    }
}

Простой чек получения денежных средств с данными поставщика:

{
    "Inn": "1739284652",
    "Type": "Income",
    "InvoiceId": "6f330fee-bbac-6661-bda1-e8111886fcc8",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": {
            "AgentType": "PAYMENT_SUBAGENT",
            "TransferAgentPhone": "+79000000002",
            "TransferAgentName": "ГУП ВЦКП \"Жилищное хозяйство\"",
            "TransferAgentAddress": "190031, Санкт-Петербург,Наб. р. Фонтанки, 105",
            "TransferAgentINN": "5456232189",
            "PaymentAgentOperation": "Оплата по лицевому счету",
            "PaymentAgentPhone": "+79000000003",
            "ReceiverPhone": "",
            "SupplierInn": "7898654512",
            "SupplierName": "АО РЦ Урала",
            "SupplierPhone": "+79000000004"
        },
        "CorrectionInfo": null,
        "ClientInfo" : null,
        "Items": [
            {
                "Label": "Таблетки от кашля иностранные",
                "Price": 10.00,
                "Quantity": 1.0,
                "Amount": 10.00,
                "Vat": "VatNo",
                "MarkingCode": null,
                "PaymentMethod": 0,
                "OriginCountryCode": "398",
                "CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
                "PaymentType": 10
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

Простой чек с дополнительным реквизитом чека (БСО) (AdditionalReceiptProp):

{
    "Inn": "1739284652",
    "Type": "Income",
    "InvoiceId": "6f222fee-bbac-4444-bda1-e9ce2442fcc6",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46222",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo" : {
            "Name": "Тестов Тест Тестович",
            "Inn": "7898654512125"
        },
        "Items": [
            {
                "Label": "Оплата услуг по страхованию.",
                "Price": 5328.53,
                "Quantity": 1.0,
                "Amount": 5328.53,
                "Vat": "VatNo",
                "MarkingCode": null,
                "PaymentMethod": 0
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null,
        "AdditionalReceiptProp": "1234567890"
    }
}

Чек коррекции с отсутствующими товарными позициями (Items):

{
    "Inn": "1739284652",
    "Type": "IncomeCorrection",
    "InvoiceId": "2f222fee-bbac-4444-bda9-e9ce9999fcc9",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": {
            "Type": "SELF",
            "Description": "Коррекция",
            "ReceiptDate": "12.06.2019",
            "ReceiptId": "123"
        },
        "ClientInfo": null,
        "Items": null,
        "PaymentItems": [
            {
                "PaymentType": 1,
                "Sum": 150.00
            }
        ],
        "Vat": "Vat20",
        "CustomUserProperty": null
    }
}

Чек коррекции при наличии товарных позиций (Items) и видом вычисляемого НДС (Vat):

{
    "Inn": "1739284652",
    "Type": "BuyCorrection",
    "InvoiceId": "2f222fee-bbac-4444-bda9-e9ce9999fcc9",
    "CallbackUrl": "http://testcallbackurl:12345",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": {
            "Type": "INSTRUCTION",
            "Description": "Коррекция",
            "ReceiptDate": "12.06.2019",
            "ReceiptId": "123"
        },
        "ClientInfo": null,
        "Items": [
            {
                "Label": "Оплата услуг по страхованию.",
                "Price": 150,
                "Quantity": 1.0,
                "Amount": 150,
                "Vat": "Vat10",
                "MarkingCode": null,
                "PaymentMethod": 0
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

Чек коррекции, на ошибочный сформированный чек:

{
    "Request":{
    "Inn": "781148191912",
    "Type": "IncomeCorrection",
    "InvoiceId": "ffb7fc5e-fe96-4f8f-900c-e88d8c8ef027",
    "CustomerReceipt": {
      "TaxationSystem": "SimpleIn",
      "Email": null,
      "Phone": null,
      "InstallmentPlace": null,
      "InstallmentAddress": null,
      "BillAddress": null,
      "KktFA": false,
      "AutomatNumber": null,
      "PaymentType": 4,
      "PaymentAgentInfo": null,
      "CorrectionInfo": {
        "Type": "SELF",
        "Description": "Ошибочный чек",
        "ReceiptDate": "17.01.21",
        "ReceiptId": "3144062149"
    },
    "ClientInfo": null,
    "Items": [
      {
        "Label": "Отмена оплаты подписки",
        "Price": 2000,
        "Quantity": 1,
        "Amount": 2000,
        "Vat": "VatNo",
        "MarkingCodeStructured": null,
        "MarkingCode": null,
        "PaymentMethod": 0,
        "MeasurementUnit": null,
        "PaymentType": 0,
        "OriginCountryCode": null,
        "CustomsDeclarationNumber": null,
        "PaymentAgentInfo": null,
        "UserProperty1080": null
      }
    ],
    "PaymentItems": null,
    "Vat": null,
    "CustomUserProperty": null,
    "AdditionalReceiptProp": 3144062149
  }
}}

Формирование кода маркировки в HEX формате требуется для версии ФФД 1.1. Для формирования код маркировки в HEX формате для передачи в API Ferma в параметре MarkingCode реализуйте следующий алгоритм:

1. Из кода в формате Data Matrix считывается код Data Matrix и получается его значение: Пример == 010463003407001221SxMGorvNuq6Wk, где значение имеет следующую структуру:
   
   • 01 – префикс для GTIN;
   • 04630034070012 - GTIN 14 (символов);
   • 21 – Префикс для SERIAL;
   • SxMGorvNuq6Wk - SERIAL 13 (символов).
2. Из полученного значения Data Matrix берется значение GTIN, конвертируется из десятичной системы счисления (СС) в шестнадцатеричную (HEX) и получается новое значение GTIN:0436038939FC.
   
3. Из полученного значения Data Matrix берется значение SERIAL, конвертируется из ASCII в шестнадцатеричную СС (HEX) и получается новое значение SERIAL: 53784D476F72764E757136576B.
   
4. К двум полученным значениям, добавляется префикс товарной группы для формата Data Matrix со следующим значением – «444D».
   
5. Итоговое значение тега 1162, для передачи по API («MarkingCode») формируется в следующем порядке «444D» + GTIN + SERIAL и получается новое значение кода маркировки для печати в API Ferma:«444D0436038939FC53784D476F72764E757136576B».

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

Вид запроса:

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

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

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

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

{
    "Request": {
        "InvoiceId": "string"
    }
}

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

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

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

{
    "Status": "Success",
    "Data": {
        "StatusCode": 1,
        "StatusName": "PROCESSED",
        "StatusMessage": "Чек сформирован на кассе",
        "ModifiedDateUtc": "2020-09-15T17:37:00",
        "ReceiptDateUtc": "2020-09-15T17:37:00",
        "ModifiedDateTimeIso": "2020-09-15T17:37+03:00[Europe/Moscow]",
        "ReceiptDateTimeIso": "2020-09-15T17:37+03:00[Europe/Moscow]",
        "Device": {
            "DeviceId": "string",
            "RNM": "string",
            "ZN": "string",
            "FN": "string",
            "FDN": "string",
            "FPD": "string"
            "ShiftNumber": null,
            "ReceiptNumInShift": 1,
            "DeviceType": null,
            "OfdReceiptUrl": "string"
        }
    }
}

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

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

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

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

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

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

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

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

При получении значений «StatusCode»: 0,1,3, следует совершить следующие действия:

• При получении значения «StatusCode»: 0 транзакция выполняется, необходимо повторить запрос до получения статуса 1, 2 или 3. Если значение возвращается и не было открыто ни одной смены в течение суток, то требуется обратиться в техническую поддержку «OFD.ru»;
• При получении значения «StatusCode»: 1 сделайте повторный запрос до получения статуса 1, 2 или 3;
• При получении значения «StatusCode»: 3 необходимо исправить транзакцию и повторно направить транзакцию с изменением значением «InvoiceId».

При получении ошибки необходимо проверить введенные данные и исправить их в соответствии с сообщением системы. После чего повторно выполнить запрос на транзакцию. Список всех возможных ошибок представлен здесь. Если самостоятельно не удается разобраться с проблемой, то обратитесь техническую поддержку «OFD.ru».

Запрос реестра кассовых чеков включает в себя 2 метода:

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

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

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

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

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

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

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

{
    "Request": {
        "ReceiptId": "e0d1122f-4e88-777a-8e8e-c333f333e4d4",
        "StartDateUtc": "2020-01-24T14:13:24",
        "EndDateUtc": "2020-01-24T14:13:24",
        "StartDateLocal": "2020-01-24T14:13:24",
        "EndDateLocal": "2020-01-24T14:13:24"
    }
}

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

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

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

{
    "Status": "Success",
    "Data": [
        {
            "ReceiptId": "44ff3d74-7414-4f71-ac5e-80242914be8a",
            "StatusCode": 2,
            "StatusName": "Чек передан в ОФД",
            "StatusMessage": "CONFIRMED",
            "ModifiedDateUtc": "2020-09-15T17:37:52",
            "ReceiptDateUtc": "2020-09-15T17:37:52",
            "ModifiedDateTimeIso": "2020-09-15T17:37:52+03:00[Europe/Moscow]",
            "ReceiptDateTimeIso": "2020-09-15T17:37:52.437+03:00[Europe/Moscow]",
            "InvoiceId": "a011y93242ab11623abdd",
            "Receipt": {
                "cashboxInfoHolder": {
                    "checkNumInShift": "2",
                    "shiftNum": "15",
                    "totalSum": 4000,
                    "DeviceId": 6608,
                    "RNM": "0000000001017018",
                    "ZN": "00107601637967",
                    "FN": "9999078902005984",
                    "FDN": "0000000208",
                    "FPD": "3649802185"
                },
                "Inn": "3245001416",
                "Type": "Income",
                "InvoiceId": "a011y93242ab11623abdd",
                "CustomerReceipt": {
                    "TaxationSystem": "0",
                    "Email": "dbaigozin@oooinex.ru",
                    "Phone": null,
                    "BillAddress": "Тестируем маркировку табака",
                    "KktFA": true,
                    "PaymentType": 4,
                    "PaymentAgentInfo": null,
                    "CorrectionInfo": null,
                    "ClientInfo": null,
                    "Items": [
                        {
                            "Label": "Табак с кодом маркировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": {
                                "markingCodeHex": "000346BD0CD0DC7152585757575252525252525252",
                                "codeCorrect": true,
                                "gtinHex": "46BD0CD0DC71",
                                "serialHex": "52585757575252525252525252",
                                "typeHex": "0003",
                                "Gtin": "77777777777777",
                                "Serial": "RXWWWRRRRRRRR",
                                "Type": "MEDICINES"
                            },
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        },
                        {
                            "Label": "Табак с кодом маркировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": {
                                "markingCodeHex": "000346BD0CD0DC7152585757575252525252525253",
                                "codeCorrect": true,
                                "gtinHex": "46BD0CD0DC71",
                                "serialHex": "52585757575252525252525253",
                                "typeHex": "0003",
                                "Gtin": "77777777777777",
                                "Serial": "RXWWWRRRRRRRS",
                                "Type": "MEDICINES"
                            },
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        },
                        {
                            "Label": "Табак с кодом ма12154215ркировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": {
                                "markingCodeHex": "000300000000000752585757575252525252525252",
                                "codeCorrect": true,
                                "gtinHex": "000000000007",
                                "serialHex": "52585757575252525252525252",
                                "typeHex": "0003",
                                "Gtin": "7",
                                "Serial": "RXWWWRRRRRRRR",
                                "Type": "MEDICINES"
                            },
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        },
                        {
                            "Label": "Табак с кодом марк2222ировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": null,
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        }
                    ],
                    "PaymentItems": [
                        {
                            "PaymentType": 1,
                            "Sum": 4000.0
                        }
                    ],
                    "Vat": null,
                    "CustomUserProperty": null,
                    "AdditionalReceiptProp": null
                },
                "Cashier": {}
            }
        }
        ...
    ]
}

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

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

Таблица 3.13. Параметры структуры содержимого кассового чека

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

В зависимости от того, какие параметры были переданы при формировании чека, некоторые элементы могут отсутствовать или иметь значение «null».

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

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

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

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

При получении ошибки необходимо проверить введенные данные и исправить их в соответствии с сообщением системы. После чего повторно отправить запрос на пробитие чека. Список всех возможных ошибок представлен здесь. Если самостоятельно не удается разобраться с проблемой, то обратитесь к вашему менеджеру, либо в нашу техподдержку.

Вид запроса:

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-17"
        },
        {
            "fn": "9280440300222222",
            "firstReceiptDate": "2019-07-16",
            "lastReceiptDate": "2019-07-17"
        },
        ...
    ]
}

Вид запроса:

GET https://ferma.ofd.ru/api/kkt/cloud/stats/receipts/extended?AuthToken=Code1&dateFromIncl=dateFromIncl&dateToIncl=dateToIncl&receiptId=receiptId&zn=zn&fn=fn

Здесь:

• Code1 – действующий код авторизации, полученный в результате запроса авторизации.
• dateFromIncl (обязательное поле) - нижняя граница даты по москве включая. Формат yyyy-MM-dd;
• dateToIncl (обязательное поле) - верхняя граница даты по москве включая. Формат yyyy-MM-dd;
• receiptId (необязательное поле) - ид чека;
• zn (необязательное поле) - серийный номер ККТ;
• fn (необязательное поле) - номер ФН;

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

{
    "Status": "Success",
    "Data": {
        "Receipts": [
            {
                "Id": "XXXXXXXX-XXXXX-XXXX-XXXXX-XXXXXXXXXXXX",
                "Tag": 3,
                "TotalSumm": 1000,
                "CashSumm": 0,
                "ECashSumm": 1000,
                "Nds00_TotalSumm": 0,
                "NdsNA_TotalSumm": 0,
                "PrepaidSumm": 0,
                "ProvisionSumm": 0,
                "DocDateTime": "2020-11-05 00:00:00Z",
                "OperationType": "Income",
                "DocNumber": XXXXXXXX,
                "KktRegNumber": "XXXXXXXX",
                "FnNumber": "XXXXXXXX",
                "DocShiftNumber": XXXXXXXX,
                "ReceiptNumber": "XXXXXXXX",
                "DecimalFiscalSign": "XXXXXXXX",
                "CDateUt": "2020-11-05 00:01:47Z",
                "Items": [
                    {
                        "Name": "XXXXXXXX",
                        "Quantity": 1,
                        "Total": 1000,
                        "CalculationMethod": 3,
                        "SubjectType": "0A",
                        "Nds10_TotalSumm": 0,
                        "Nds18_TotalSumm": 0,
                        "Barcode": null,
                        "NdsCalculated10": 0,
                        "NdsCalculated18": 167
                    }
                ]
            },

   ......

            {
                "Id": "XXXXXXXX-XXXXX-XXXX-XXXXX-XXXXXXXXXXXX",
                "Tag": 3,
                "TotalSumm": 10000,
                "CashSumm": 0,
                "ECashSumm": 10000,
                "Nds00_TotalSumm": 0,
                "NdsNA_TotalSumm": 0,
                "PrepaidSumm": 0,
                "ProvisionSumm": 0,
                "DocDateTime": "2020-11-05 00:00:00Z",
                "OperationType": "Income",
                "DocNumber": XXXXXXXX,
                "KktRegNumber": "XXXXXXXX",
                "FnNumber": "XXXXXXXX",
                "DocShiftNumber": XXXXXXXX,
                "ReceiptNumber": "XXXXXXXX",
                "DecimalFiscalSign": "XXXXXXXX",
                "CDateUt": "2020-11-05 00:00:16Z",
                "Items": [
                    {
                        "Name": "XXXXXXXX",
                        "Quantity": 1,
                        "Total": 10000,
                        "CalculationMethod": 3,
                        "SubjectType": "0A",
                        "Nds10_TotalSumm": 0,
                        "Nds18_TotalSumm": 0,
                        "Barcode": null,
                        "NdsCalculated10": 0,
                        "NdsCalculated18": 1667
                    }
                ]
            }
        ]
    }
}

Вид запроса:

GET https://ferma.ofd.ru/api/kkt/cloud/stats/cashboxes/extended?AuthToken=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"
        },
        .....
    ]
}

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

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

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

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

Таблица 4.1. Код и описания ошибок

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

Для того чтобы пробить чеки на тестовой кассе Ferma, используйте домен ⁴³⁾ ferma-test.ofd.ru, для кассы версии ФФД 1.05 и 1.1 используйте следующие данные:

• Логин - fermatest1;
• Пароль - Hjsf3321klsadfAA;

для кассы версии ФФД 1.2:

• Логин - fermatest2;

• Пароль - Go2999483Mb.

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

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

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

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

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

Версия 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 Возможные значения признака предмета расчета (поля «PaymentType»).

Версия 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».

Версия 2.19
Добавлена 27 января 2020 г.
Исключен из API-запроса на формирование кассового чека параметр «AutomaticDeviceNumber».

Версия 2.20
Добавлена 18 февраля 2020 г.
Добавлены примеры API-запросов на формирование кассового чека.

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

Версия 2.22
Выпущена 13 апреля 2020 г.

• Добавлен параметр «AdditionalReceiptProp» в структуру «CustomerReceipt» в API-запрос на формирование кассового чека;
• Обновлено описание параметра «Vat» в составе массива структур «Items», теперь данный параметр обязателен в чеке коррекции при наличии товарных позиций в чеке;
• Добавлены ошибки «INVALID_ADDITIONAL_RECEIPT_PROPERTY», «EMPTY_CORRECTION_INFO», «INVALID_CORRECTION_RECEIPT» в список возможных ошибок при формировании кассового чека;
• Добавлены примеры простого чека с дополнительным реквизитом чека (БСО) (AdditionalReceiptProp), чека коррекции с отсутствующими товарными позициями (Items) и чека коррекции при наличии товарных позиций (Items) и видом вычисляемого НДС (Vat) в раздел «Примеры формируемых чеков».

Версия 2.23
Выпущена 16 июнь 2020 г.
В список возможных ошибок при формировании кассового чека добавлена ошибка 1055.

Версия 2.24
Выпущена 27 августа 2020 г.

• В структуру метода «STATUS» добавлен параметр «InvoiceId»;
• В список возможных ошибок при формировании кассового чека добавлена ошибка 1057.

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

• В формирование кассового чека добавлены теги: 1005, 1008, 1012, 1016, 1020, 1021, 1023, 1026, 1044, 1055, 1073, 1074, 1075, 1079, 1081, 1173, 1177, 1203, 1214, 1223;
• Добавлен параметр PAYMENT_AGENT;
• Добавлены сноски для разных условий заполнения агентских параметров.

Версия 2.26
Выпущена 09 сентября 2020 г.
В список возможных ошибок при формировании кассового чека добавлена ошибка 1058.

Версия 2.27
Выпущена 14 сентября 2020 г.
Добавлено уточнение по формату времени UTC.

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

• Устранены мелкие недочеты по всему объему документа;
• Исправлен код ошибки при проблеме с авторизацией.

Версия 2.29
Выпущена 17 сентября 2020 г.
В методах status и list добавлены параметры ModifiedDateTimeIso и ReceiptDateTimeIso с датой в формате ISO.

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

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

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

• Переработаны таблицы для большей наглядности информации о вложенных полях в структурах;
• Удалены блоки по работе с черновиками ЭДО;
• В таблицу 3.1 добавлены новые параметры ShiftNumber, ReceiptNumInShift, DeviceType, OfdReceiptUrl;
• Исправлена ошибка в пункте 3.4, запрос возвращается серийные номера ФН, а не ККТ, как было указано;
• Добавлены описания параметров cashboxInfoHolder.checkNumInShift, cashboxInfoHolder.shiftNum, cashboxInfoHolder.totalSum, cashboxInfoHolder.cashboxType, MarkingCodeStructured.markingCodeHex, MarkingCodeStructured.codeCorrect, MarkingCodeStructured.gtinHex, MarkingCodeStructured.serialHex, MarkingCodeStructured.typeHex.

Версия 2.32
Выпущена 06 ноября 2020 г.
Добавлен раздел 3.5

Версия 2.33
Выпущена 30 ноября 2020 г.

• Добавлен параметр AutomatNumber(тег 1036) для касс ФА;
• В таблицу 4 добавлены новые коды ошибок.

Версия 2.34
Выпущена 09 февраля 2021 г.

• Добавлены дополнительные тип чеков коррекции для касс Эфир Pro IncomeReturnCorrection, ExpenseReturnCorrection;
• Добавлена ошибка 1064, возникающая при пробитии доп типов чеков коррекции на кассах Атол42ФС

Версия 2.35
Выпущена 09 февраля 2021 г.

• Добавлены дополнительные тип чеков коррекции для касс Эфир Pro IncomeReturnCorrection, ExpenseReturnCorrection;
• Добавлена ошибка 1064, возникающая при пробитии доп типов чеков коррекции на кассах Атол42ФС

Версия 2.36
Выпущена 10 февраля 2021 г.
Исправлено описание тега 1179 в таблице 1.1 Параметры элементов структуры «CustomerReceipt»

Версия 2.37
Выпущена 12 февраля 2021 г.
Убраны параметры InstallmentPlace, InstallmentAddress

Версия 2.38
Выпущена 30 апреля 2021 г.
Добавлено описание метода 3.6. Запрос информации для мониторинга услуги Ferma и ФН.
Добавлено описание параметров метода 3.6. Запрос информации для мониторинга услуги Ferma и ФН.

Версия 2.39
Выпущена 17 мая 2021 г.
Добавлено описание передачи скидки/надбавки для параметра Amount

Версия 2.40
Выпущена 07 июля 2021 г.

• Удален раздел 3.1.5. Возможные значения наименования предмета расчета (Поле «Label»);
• Добавлен раздел 3.1.12. Формирование кода маркировки в HEX формате API Ferma;
• В Таблицу 3.2. добавлена информация по параметр CallbackUrl;
• В Таблицу 3.2. Параметры структуры запроса на формирование кассового чека добавлена информация по параметру CallbackUrl;
• В Таблицу 3.5. Параметры элементов структуры «Items» ТЕГ 1059 обновлена информация по параметру MarkingCodeStructured;
• В Таблицу 3.5. Параметры элементов структуры «Items» ТЕГ 1059 обновлена информация по параметру Label;
• В разделе 3.1. Добавлена Таблица 3.1. Значения атрибута «Обязательность»
• В разделе 3.1. Добавлена Таблица 3.4. Примечания
• В разделе 3.1.1. Добавлена Таблица 3.5. Параметры элементов структуры «Items» ТЕГ 1059;
• В разделе 3.1.1. Добавлена Таблица 3.6. Примечания;
• В разделе 3.1.2. Добавлена Таблица 3.7. Структура, содержащая данные платежного агента ТЕГ 1223;
• В разделе 3.1.2. Добавлена Таблица 3.8. Примечания;
• В разделе 3.1.11. Примеры формируемых чеков добавлен пример чека коррекции на ошибочный сформированный чек.
• В таблицах добавлены колонки «Обяз.» и Примечание
• Изменена структура документа;
• Добавлено содержание;
• Изменена схема;
• Изменен порядок нумерации таблиц;
• Устранены мелкие недочеты по всему объему документа.

Версия 2.41
Выпущена 09 августа 2021 г.

• Обновлена структура запроса;
• Обновлена информация по параметрам запроса в таблице 3.3.;
• Добавлена таблица 3.5. Параметры элементов структуры «MarkingCodeData» ТЕГ 1163;
• В разделе 3.1. удалена Таблица 3.4. Примечания;
• В разделе 3.1.1. удалена Таблица 3.6. Примечания;
• В разделе 3.1.2. удалена Таблица 3.8. Примечания;
• Таблица 4.1. Код и описания ошибок дополнена возможными ошибками.