Ferma®

Версия 2.66 от 27.06.2024 Открыть pdf-файл EN RU

Введение

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

Рисунок 1. Схема запросов к ИС Ferma®

1. Общий вид запроса и ответа в процессе использования API

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

Внимание! В заголовке запроса требуется указание:

Content-Type: application/json

Ответы выдаются сервером в формате 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» будет сообщение об ошибке, возникшей при обработке переданных данных.

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

Чтобы неоднократно обращаться к сервису Ferma® необходим ключ аутентификации. Получить ключ аутентификации вы можете с помощью запроса методом POST. В запросе вы передаете параметры авторизации в сервисе Ferma®.

В теле запроса передаются следующие параметры:

  • Login;
  • Password.

Значения параметров можно получить в личном кабинете клиента в разделе Ferma®, после покупки услуг сервиса Ferma® или узнать у вашего менеджера.

Вид запроса:

POST https://ferma.ofd.ru/api/Authorization/CreateAuthToken
Content-Type: application/json

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

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

Успешный запрос получения ключа аутентификации будет иметь код равный 200.

Пример успешного ответа на запрос получения ключа аутентификации:

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

В ответе представлены следующие параметры:

  • «AuthToken» – ключ аутентификации1);
  • «ExpirationDateUtc» – дата и время действия ключа аутентификации2).

Полученный ключ аутентификации необходим в запросах сервиса Ferma®.

Пример запроса с использованием ключа аутентификации:

POST https://ferma.ofd.ru/api/kkt/cloud/receipt?AuthToken={Code1}
Content-Type: application/json
  • Code1 – действующий ключ аутентификации

3. HTTP-запросы к ИС Ferma® для работы с онлайн-кассами

В разделе представлена общая JSON-схема, описание параметров, а также описана работа с API сервисом Ferma®.

Внимание. Сервис Ferma® является асинхронным, отправка чека методом “Receipt” и успешное получение идентификатора транзакции не является финальным завершением операции пробития чека. Для завершения операции необходимо настроить корректную обработку Callback ответов и настроить получение данных по чеку через методы "Status", "list", "list2". Если в параметре «CallbackUrl» было заполнено значение с URL-адресом, то после отправки запроса на пробитие чека на кассе (успешное или неуспешное), будет отправлен ответ методом POST на URL-адрес, указанный в параметре «CallbackUrl». Описание параметров ответа на значение «CallbackUrl» представлено в разделе 3.9. Если в течение 300 секунд ответ не поступил, вам необходимо выполнить запрос проверки статуса кассового чека.

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

В разделе представлена общая JSON-схема запроса на формирование фискальных документов для пробития на кассе Ferma®, а также представлено описание всех параметров запроса. В разделе есть примеры JSON-схем для запроса на пробитие фискальных документов в кассе Ferma®.

На схеме представлены все параметры для работы с API.

Для корректной настройки вашей информационной системы с API Ferma® воспользуйтесь примерами JSON-схем. Примеры JSON-схем представлены в разделе 3.2.5.

Общая JSON-схема:

{ 
    "Request":    
      {
        "Inn": "string",
        "Type": "string",
        "InvoiceId": "string",
        "McCheckRetryPeriodSec": "integer",
        "CallbackUrl": "string",
        "CustomerReceipt": 
          {
            "CheckMcMode": "string",
            "TaxationSystem": "string",
            "Email": "string",
            "Phone": "string",
            "PaymentType": integer,
            "KktFA": boolean,
            "AutomatNumber": "string",
            "BillAddress": "string",
            "CustomUserProperty":  
              {
                "Name": "string",
                "Value": "string"
              },
            "PaymentAgentInfo": 
              {
                "AgentType": "string",
                "TransferAgentPhone": "string",
                "TransferAgentName": "string",
                "TransferAgentAddress": "string",
                "TransferAgentINN": "string",
                "PaymentAgentOperation": "string",
                "PaymentAgentPhone": "string",
                "ReceiverPhone": "string",
                "SupplierInn": "string",
                "SupplierName": "string",
                "SupplierPhone": "string"
              },
            "CorrectionInfo": 
              {
                "Type": "string",
                "Description": "string",
                "ReceiptDate": "string",
                "ReceiptId": "string"
              },
            "ClientInfo": 
              { 
                "Name": "string",
                "Inn": "string",
                "Birthday": "string",
                "Citizenship": "string",
                "IdDocType": "string",
                "IdDocData": "string",
                "Address": "string"
              },
            "IndustryRequisite":  
              {
                "FoivId": "string",
                "DocDate": "string",
                "DocNumber": "string",
                "Value": "string"
              },
            "OperationRequisite":  
              { 
                "Id": "string",
                "Details": "string",
                "DateTime": "string"
              },
            "Items":  
               [ 
                 {
                   "Label": "string", 
                   "Price": floating point, 
                   "Quantity": floating point, 
                   "Amount": floating point, 
                   "Vat": "string", 
                   "Excise": floating point, 
                   "Measure": "string", 
                   "PaymentMethod": integer,
                   "IndustryRequisite": 
                     {
                       "FoivId": "string",
                       "DocDate": "string",
                       "DocNumber": "string",
                       "Value": "string"
                     }, 
                   "AdditionalRequisite": "string", 
                   "OriginCountryCode": "string", 
                   "CustomsDeclarationNumber": "string", 
                   "PaymentType": integer, 
                   "MarkingCodeData":  
                     { 
                       "Type": "string", 
                       "Code": "string", 
                       "PlannedStatus": "string", 
                       "Fractional": 
                         { 
                           "Numerator": integer, 
                           "Denominator": integer 
                         } 
                     }, 
                   "PaymentAgentInfo": 
                     { 
                       "AgentType": "string", 
                       "TransferAgentPhone": "string", 
                       "TransferAgentName": "string", 
                       "TransferAgentAddress": "string", 
                       "TransferAgentINN": "string", 
                       "PaymentAgentOperation": "string", 
                       "PaymentAgentPhone": "string", 
                       "ReceiverPhone": "string", 
                       "SupplierInn": "string", 
                       "SupplierName": "string", 
                       "SupplierPhone": "string" 
                     } 
                 } 
               ],
            "PaymentItems":  
              [ 
                {
                  "PaymentType": integer, 
                  "Sum": floating point 
                } 
              ], 
            "AdditionalReceiptProp":   
          },            
        "Cashier":
          {
            "Name": "string",
            "Inn": "string"
          }
      }
}

В таблицах представлены параметры, их вид и формат значений, описание значений, а также признак необходимости в запросе.

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

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

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

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

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

Параметр Вложенный параметр Формат значения Описание Тег 3) Обязательность4)
Inn Строка ИНН вашей компании 1018 1
Type Строка Тип формируемого фискального документа (чек).
Тип может принимать следующие значения:
1054 1
– «Income» — получение денежных средств от покупателя;
– «IncomeReturn» — возврат денежных средств, полученных от покупателя;
– «IncomePrepayment» — авансовый платеж от покупателя;
– «IncomeReturnPrepayment» — возврат аванса;
– «IncomeCorrection» — чек коррекции/приход;
– «BuyCorrection» — чек коррекции/расход;
– «IncomeReturnCorrection» - чек коррекции/Возврат прихода;
– «ExpenseReturnCorrection» - чек коррекции/Возврат расхода;
– «Expense» — выдача денежных средств покупателю;
– «ExpenseReturn» — возврат денежных средств, выданных покупателю.
InvoiceId Строка Идентификатор, присвоенный вашей информационной системой в запросе на формирование кассового чека.
Использование идентификатора предотвращает формирование дублей чеков
Важно! Изменяйте идентификатор для перепробития неуспешных чеков в Ferma® («StatusCode»: 3)
McCheckRetryPeriodSec Число Параметр повтора проверки КМ в честном знаке.
Параметр может принимать значение не больше числа 1800, также значение должно быть положительным (строго больше 0). Подробно описано в разделе 3.3.2.
CallbackUrl Строка URL-адрес. В параметре указывается значение URL-адреса. Если поле заполнено корректно, то после обработки документа (успешной или неуспешной фискализации в ККТ: статус «CONFIRMED» или «KKT_ERROR»), ответ будет отправлен POST запросом по URL указанному в данном поле. Корректность заполненного поля определяется по регулярному выражению:^http(s?)\:\/\/[0-9a-zA-Zа-яА-Я]([-.\w]*[0-9a-zA-Zа-яА-Я])*(:(0-9)*)*(\/?)([a-zA-Z0-9а-яА-Я\-\.\?\,\'\/\\\+&=%\$#_]*)?$\\.
Описание параметров ответа на значение «CallbackUrl» представлено в разделе 3.9.
CustomerReceipt Структура Содержимое клиентского чека. Параметры элементов структуры CustomerReceipt приведены в таблице 3.3.
Cashier 5) Структура Информация о кассире
Name Строка ФИО кассира 1021 2
Inn Строка ИНН кассира 1203 3


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

Параметр Вложенный параметр Формат значения Описание Тег 6) Обязательность7)
CheckMcMode Строка Параметр проверки кода маркировки
Параметр в запросе не обязательный. Перед пробитием чека касса автоматически проверит код маркировки.
Если вы в запросе не указали параметр CheckMcMode, чек пробьётся при любом результате проверки кода маркировки в ЦРПТ.

Если вы передали одно из следующих значений:
- IGNORE_ANY_ERRORS - вне зависимости от результата проверки, устанавливается по умолчанию, чек пробьётся
- REQUIRE_NO_M_MINUS - касса пробивает чек, если результат проверки КМ в ЦРПТ не равен значению [М-]. Если результат проверки кода окажется равен значению [М-] - касса чек не пробивает
TaxationSystem Строка Система налогообложения.
Внимание! Список применения значений систем налогообложения формируется на этапе регистрации кассы. Чтобы изменить список допустимых значений, необходимо выполнить перерегистрацию кассы.
Параметр определения системы налогообложения может принимать следующие значения:
1055 1
– «Common» или «0» — общая система налогообложения;
– «SimpleIn» или «1» — упрощенная система налогообложения (доход);
– «SimpleInOut» или «2» — упрощенная система налогообложения (доход минус расход);
– «Unified» или «3» — единый налог на вмененный доход;
– «UnifiedAgricultural» или «4» — единый сельскохозяйственный налог;
– «Patent» или «5» — патентная система налогообложения.
Email 8) Строка Адрес электронной почты клиента 1008 2
Phone 9) Строка Контактный телефон клиента 1008 2
PaymentType Число Признак предмета расчета для всего чека.
Важно! Если в данном поле значение клиентом не указано, то используется значение по умолчанию, которое устанавливается по умолчанию при заведении учетной записи в информационной системе Ferma®.
Список возможных значений перечислен в п. 3.1.4.
1212 1
KktFA Логическое выражение Если используется касса ФА в сервисе Ferma® необходимо установить значение true. Если используется касса ФС необходимо установить значение false.
Касса ФА может применятся для :
– вендингового аппарата, при совершении расчетов за товары или услуги;
– совершения расчетов за проезд в автоматизированном режиме (через валидатор) или совершения расчетов через терминал кондуктора.
AutomatNumber Строка Номер автоматического устройства 1036 2
BillAddress Строка Место осуществления расчетов 1187 1
CustomUserProperty Структура Дополнительный реквизит пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты 1084 3
Name Строка Наименование дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты 1085 3
Value Строка Значение дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты 1086 3
PaymentAgentInfo 10) Структура Структура, содержит данные платежного агента.
Важно!
Для касс с ФФД 1.2 параметр должен передаваться только в отдельные позиции и не может быть передан в структуре всего чека.
Для касс с ФФД 1.05-1.1 параметр может передаваться как на отдельные позиции, так и в структуре всего чека.
1223 2
AgentType 11) Строка Тип (признак) платежного агента. Возможные значения: 1057 3
BANK_PAYMENT_AGENT — банковский платежный агент;
BANK_PAYMENT_SUBAGENT — банковский платежный субагент;
PAYMENT_AGENT — платежный агент;
PAYMENT_SUBAGENT — платежный субагент;
CONFIDANT — поверенный;
COMMISSIONER — комиссионер;
AGENT — агент.
TransferAgentPhone 12) Строка Телефон оператора по переводу денежных средств 1075 3
TransferAgentName 13) Строка Имя агента 1026 2
TransferAgentAddress 14) Строка Адрес агента 1005 2
TransferAgentINN 15) Строка ИНН агента 1016 2
PaymentAgentOperation 16) Строка Операция платежного агента 1044 2
PaymentAgentPhone 17) Строка Телефон платежного агента 1073 2
ReceiverPhone 18) Строка Телефон потребителя 1074 3
SupplierInn 19) Строка ИНН поставщика 1226 2
SupplierName 20) Строка Наименование поставщика 1225 2
SupplierPhone 21) Строка Телефон поставщика 1171 3
CorrectionInfo Структура Структура, описывает информацию по чеку коррекции.
Внимание! Структура присутствует в данных только в случае генерации чека коррекции. Для генерации обычного чека данная структура не нужна.
1174 1
Description Строка Описание коррекции и причин коррекции 1
Type Строка Тип коррекции:
SELF — коррекция производится самостоятельно;
INSTRUCTION — коррекция производится по предписанию
1173 3
ReceiptDate Строка Дата пробития чека, к которому применяется чек коррекции. В формате «ДД.ММ.ГГ», где ДД — день, ММ — месяц, ГГ — год. 1178 3
ReceiptId Строка Номер предписания налогового органа 1179 3
ClientInfo Структура Данные о покупателе 1256 2
Name Строка ФИО или наименование организации, если клиент юр. лицо. Не более 256 символов в поле 1227 2
Inn Строка ИНН покупателя. Длина 10-12 цифр 1228 2
Birthday Строка Дата рождения покупателя (клиента). В формате «ДД.ММ.ГГ», где ДД — день, ММ — месяц, ГГ — год. 1243 2
Citizenship Строка Гражданство покупателя (клиента) 1244 3
IdDocType Строка Код вида документа, удостоверяющего личность покупателя (клиента).
Описание значений представлено в разделе 3.1.3.
1245 2
IdDocData Строка Данные документа, удостоверяющего личность покупателя (клиента) 1246 2
Address Строка Адрес покупателя (клиента) 1254 3
IndustryRequisite Структура Отраслевой реквизит чека 1261 2
FoivId Строка Идентификатор ФОИВ (ФЕДЕРАЛЬНЫЕ ОРГАНЫ ИСПОЛНИТЕЛЬНОЙ ВЛАСТИ). Может принимать значения от 001 до 072. Описание значений представлено в разделе 3.1.5. 1262 3
DocDate Строка Дата документа основания. Формат «ДД.ММ.ГГГГ», где ДД — день, ММ — месяц, ГГГГ — год. 1263 3
DocNumber Строка Номер документа основания 1264 3
Value Строка Значение отраслевого реквизита 1265 3
OperationRequisite Структура Операционный реквизит чека 1270 2
Id Строка Идентификатор операции 1271 2
Details Строка Данные операции 1272 2
DateTime Строка Дата и время задается в формате unix timestamp 1273 2
Items Структура Товарные позиции, приобретаемые клиентом. Параметры элементов структуры Items приведены в таблице 3.4. 1059 1
PaymentItems Структура Суммы по типам оплат
PaymentType Число Тип оплаты:
0 – наличными; 1031 1
1 – безналичными; 1081 1
2 – предварительная оплата (аванс); 1215 1
3 – предварительная оплата (кредит); 1216 1
4 – иная форма оплаты. 1217 1
Sum Число с точкой Сумма по типу, в рублях 1020 1
AdditionalReceiptProp Строка Дополнительный реквизит чека (БСО). Применяется в составе кассового чека (БСО). Максимальная длина - 16 символов. 1192 3

3.1.1. Описание параметров «Items» ТЕГ 1059


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

Параметр Вложенный параметр Формат значения Описание Тег 22) Обязательность23)
Label Строка Передаются значения в текстовом виде. Здесь могу присутствовать описание товара или описание услуги
Параметр всегда требуется в запросе на формирование фискального документа.
1030 2
Price Число с точкой Цена товарной позиции в рублях. 1079 2
Quantity Число с точкой Количество товара в товарной позиции 1023 2
Amount Число с точкой Общая стоимость товара в товарной позиции в рублях. Правила округления для стоимости товара зависят от типа кассы. В кассах типа Эфир Pro ФС и Эфир Pro ФА стоимость округляется по математическим правилам округления.
Результат умножения значений параметров «Price» и «Quantity» должно быть равно значению параметра «Amount»
1043 1
Excise Число с точкой Сумма акциза с учетом копеек. Участвует в запросе, если предмет расчета признается объектом налогообложения акцизами 1229 2
Vat Строка Вид вычисляемого НДС.
Обязательное поле для чеков коррекции, если Items не равен NULL.
Параметр может принимать следующие значения:
1199 2
- «VatNo» — налог на добавленную стоимость без НДС;
- «Vat10» — налог на добавленную стоимость (НДС) 10%;
- «Vat20» — НДС 20% 24);
- «Vat0» — НДС 0%;
- «CalculatedVat10110» — вычисленный НДС 10% от 110% суммы;
- «CalculatedVat20120» — вычисленный НДС 20% от 120% суммы25).
MarkingCodeData Структура Код маркировки товарной позиции. Передается структура. Структура содержит информацию о маркировке товарных позиций. Структура описана в таблице 3.5. 1163 2
Measure Строка Тег содержит единицы измерения количества предмета расчета и может принимать значения описанные в разделе 3.1.6. Параметр является обязательным для ФФД 1.2. 2108 1
PaymentMethod Число Признак способа расчета: 1214 1
- 1 — предоплата 100%;
- 2 — предоплата;
- 3 — аванс;
- 4 — полный расчет;
- 5 — частичный расчет;
- 6 — передача в кредит;
- 7 — оплата в кредит.
IndustryItemRequisite Структура Отраслевой реквизит чека. Содержит сведения о нормативных актах 1260 2
FoivId Строка Идентификатор ФОИВ (ФЕДЕРАЛЬНЫЕ ОРГАНЫ ИСПОЛНИТЕЛЬНОЙ ВЛАСТИ). Может принимать значения от 001 до 072. Описание значений представлено в разделе 3.1.5. 1262 3
DocDate Строка Дата документа основания. Формат «ДД.ММ.ГГГГ», где ДД — день, ММ — месяц, ГГГГ — год. 1263 3
DocNumber Строка Номер документа основания 1264 3
Value Строка Значение отраслевого реквизита 1265 3
AdditionalRequisite Строка Дополнительный реквизит предмета расчета (Максимальная длина 64 символов) 1191 2
OriginCountryCode Строка Код страны происхождения товара. Не более 3 цифр. 26) 1230 2
CustomsDeclarationNumber Строка Номер таможенной декларации. Не более 32 символов 1231 2
PaymentType Число Признак предмета расчета для конкретной позиции в чеке. Если значение отсутствует, берется значение для всего чека. Возможные значения перечислены в п. 3.1.4. 1212 1
PaymentAgentInfo 27) Структура Структура данных платежного агента приведены в таблице 3.6. 1223 2

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

Параметр Вложенный параметр Формат значения Описание Тег 28) Обязательность29)
Type Строка Формат КМ
Может принимать следующие значения:
- UNKNOWN_PRODUCT_CODE 1300
- EAN8 — значение кода маркировки в формате EAN-8 1301
- EAN13 — значение кода маркировки в формате EAN-13 1302
- ITF14 — значение кода маркировки в формате ITF-14 1303
- GS1 — значение кода маркировки в формате GS1 1304
- GS1M — значение кода маркировки в формате GS1.M 1305
- SHORT_MC — значение кода маркировки в формате КМК (Короткий код маркировки) 1306
- FUR — Контрольно-идентификационный знак мехового изделия 1307
- EGAIS20 — значение кода маркировки в формате ЕГАИС-2.0. 1308
- EGAIS30 — значение кода маркировки в формате ЕГАИС-3.0. 1309
- KTF1 — Определяется ФНС России 1320
- KTF2 — Определяется ФНС России 1321
- KTF3 — Определяется ФНС России 1322
- KTF4 — Определяется ФНС России 1323
- KTF5 — Определяется ФНС России 1324
- KTF6 — Определяется ФНС России 1325
Code Строка Код маркировки.
В параметре передается значение, полученное сканером штрих-кода
PlannedStatus Строка Если в параметре «PlannedStatus» значение не было задано, то по умолчанию ставится значение «PIECE_PRODUCT_INCOME» (штучный товар).
Планируемый статус товара с КМ может принимать следующие значения:
2003 3
- PIECE_PRODUCT_INCOME — Штучный товар, подлежащий обязательной маркировке средством идентификации, реализован;
- MEASURED_PRODUCT_INCOME — Мерный товар, подлежащий обязательной маркировке средством идентификации, в стадии реализации;
- PIECE_PRODUCT_RETURN — Штучный товар, подлежащий обязательной маркировке средством идентификации, возвращен;
- MEASURED_PRODUCT_RETURN — Часть товара, подлежащего обязательной маркировке средством идентификации, возвращена;
- PRODUCT_STATUS_NOT_CHANGED — Статус товара, подлежащего обязательной маркировке средством идентификации, не изменился.
Fractional Структура Тег содержит дробное количество маркированного товара. 129130) 231)
Numerator Число Числитель (значение должно быть строго меньше значения тега 1294) 1293 1
Denominator Число Знаменатель 1294 1

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

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

Для касс с ФФД 1.2 параметр должен передаваться только в отдельные позиции и не может быть передан в структуре всего чека.
Для касс с ФФД 1.05-1.1 параметр может передаваться как на отдельные позиции, так и в структуре всего чека.

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

Параметр Вложенный параметр Формат значения Описание Тег 32) Обязательность33)
PaymentAgentInfo 34) Структура Структура, содержащая данные платежного агента 1223
AgentType 35) Строка Тип (признак) платежного агента. Возможные значения: 1222 1
BANK_PAYMENT_AGENT — банковский платежный агент;
BANK_PAYMENT_SUBAGENT — банковский платежный субагент;
PAYMENT_AGENT — платежный агент;
PAYMENT_SUBAGENT — платежный субагент;
CONFIDANT — поверенный;
COMMISSIONER — комиссионер;
AGENT — агент.
TransferAgentPhone 36) Строка Телефон оператора по переводу денежных средств 1075 3
TransferAgentName 37) Строка Имя агента 1026 2
TransferAgentAddress 38) Строка Адрес агента 1005 2
TransferAgentINN 39) Строка ИНН агента 1016 2
PaymentAgentOperation 40) Строка Операция платежного агента 1044 2
PaymentAgentPhone 41) Строка Телефон платежного агента 1073 2
ReceiverPhone 42) Строка Телефон оператора по приему платежей 1074 3
SupplierInn 43) Строка ИНН поставщика 1226 2
SupplierName 44) Строка Наименование поставщика 1225 2
SupplierPhone 45) Строка Телефон поставщика 1171 3

Таблица 3.7. Состав параметров ТЕГ 1223 в зависимости от типа платежного агента

Параметр/AgentType BANK_PAYMENT_AGENT BANK_PAYMENT_SUBAGENT PAYMENT_AGENT PAYMENT_SUBAGENT CONFIDANT COMMISSIONER AGENT
TransferAgentPhone 1 1 0 0 0 0 0
TransferAgentName 1 1 0 0 0 0 0
TransferAgentAddress 1 1 0 0 0 0 0
TransferAgentINN 1 1 0 0 0 0 0
PaymentAgentOperation 1 1 0 0 0 0 0
PaymentAgentPhone 1 1 1 1 0 0 0
ReceiverPhone 0 0 1 1 0 0 0
SupplierInn 1 1 1 1 1 1 1
SupplierName 1 1 1 1 1 1 1
SupplierPhone 1 1 1 1 0 0 0

3.1.3. Возможные значения параметра "IdDocType"

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

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

3.1.4. Возможные значения признака предмета расчета (параметра "PaymentType")

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

Внимание!

  • Некоторые комбинации предметов расчета и систем налогообложения могут вызывать ошибку. Это связано с особенностями касс.
  • Для обработки процедур и чеков с кодом маркировки могут применяться следующие значения признака предмета расчета (параметра «PaymentType»):
    • 30 — о реализуемом подакцизном товаре, подлежащем маркировке средством идентификации, не имеющем кода маркировки — «АТНМ» или может не печататься;
    • 31 — о реализуемом подакцизном товаре, подлежащем маркировке средством идентификации, имеющем код маркировки — «АТМ» или может не печататься;
    • 32 — о реализуемом товаре, подлежащем маркировке средством идентификации, не имеющем кода маркировки, за исключением подакцизного товара — «ТНМ» или может не печататься;
    • 33 — о реализуемом товаре, подлежащем маркировке средством идентификации, имеющем код маркировки, за исключением подакцизного товара — «ТМ» или может не печататься.

3.1.5. Возможные значения параметра "FoivId"

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

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

3.1.6. Возможные значения параметра "Measure"

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

  • «PIECE» — Применяется для предметов расчета, которые могут быть реализованы поштучно или единицами
  • «GRAM» — Грамм
  • «KILOGRAM» — Килограмм
  • «TON» — Тонна
  • «CENTIMETER» — Сантиметр
  • «DECIMETER» — Дециметр
  • «METER» — Метр
  • «SQUARE_CENTIMETER» — Квадратный сантиметр
  • «SQUARE_DECIMETER» — Квадратный дециметр
  • «SQUARE_METER» — Квадратный метр
  • «MILLILITER» — Миллилитр
  • «LITER» — Литр
  • «CUBIC_METER» — Кубический метр
  • «KILOWATT_HOUR» — Киловатт час
  • «GIGACALORIE» — Гигакалория
  • «DAY» — Сутки (день)
  • «HOUR» — Час
  • «MINUTE» — Минута
  • «SECOND» — Секунда
  • «KILOBYTE» — Килобайт
  • «MEGABYTE» — Мегабайт
  • «GIGABYTE» — Гигабайт
  • «TERABYTE» — Терабайт
  • «OTHER» — Применяется при использовании иных единиц измерения

Внимание! Параметр Measure в структуре Items является обязательным для ФФД 1.2. По умолчанию (если параметр Measure не был передан в теле запроса для ФФД 1.2) присваивается значение PIECE.

3.2. Формирование фискальных документов

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

Значение параметра Email заполняется по умолчанию (на основе данных организации/пользователя личного кабинета) в случае, если параметр передан некорректно или не передан в запросе.

Вы можете воспользоваться примерами JSON-схем, для запроса на формирование фискального документа, в разделе 3.2.6.

Успешный ответ запроса имеет следующий вид:


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

ReceiptId является уникальным идентификатором, присвоенным сервисом Ferma®.

3.2.1. Запрос на формирование фискальных документов

Запрос на формирование фискального документа выполняется методом POST.

Запрос имеет следующий вид:

POST https://ferma.ofd.ru/api/kkt/cloud/receipt?AuthToken={Code1}
Content-Type: application/json

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

Приведен пример запроса на формирование простого чека

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

{
  "Request": 
   {
    "Inn": "0123456789",
    "Type": "Income",
    "InvoiceId": "6f000fee-bbac-4444-bda1-e9ce9999fcc7",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@ya.ru",
        "Phone": "+79000000001",
        "PaymentType": 4,
        "Items": [
            {
                "Label": "Оплата услуг по страхованию.",
                "Price": 5328.53,
                "Quantity": 1.0,
                "Amount": 5328.53,
                "Vat": "VatNo",
                "MarkingCode": null,
                "PaymentMethod": 0,
                "Measure": "PIECE"
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
   } 
 }

Пример успешного ответа:

{
    "Status": "Success",
    "Data": {
        "ReceiptId": "655bf554-a003-47a1-b558-e861ffca2b76"
    }
}

3.2.2. Условия успешного формирования чека

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

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

3.2.3. Возможные ошибки

  • «Не найдены данные компании с ИНН 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 – некорректно заполнен чек коррекции.

3.2.4. Формирование кассового чека с большим количеством позиций

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

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

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

Вид запроса:

POST https://ferma.ofd.ru/api/kkt/cloud/receipt?AuthToken=Code1
Content-Type: application/json
  • Code1 – действующий код авторизации, полученный в результате запроса авторизации.

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

{
  "Request": {
    "Inn": "7718221538",
    "Type": "Income",
    "InvoiceId": "229244shfjhfkidu144",
    "CustomerReceipt": {
      "TaxationSystem": 0,
      "Email": "scijkinkjcvnskl@gmail.ru",
      "PaymentType": 1,
      "KktFA": false,
      "PaymentAgentInfo": {
        "AgentType": "AGENT",
        "TransferAgentINN": "5047063929"
      },
      "Items": [
        {
          "Label": "Наколенник эластичный \"Серебряный верблюд\", 4 размер",
          "Price": 259.57,
          "Quantity": 2.0,
          "Amount": 519.14,
          "Vat": "VatNo",
          "PaymentMethod": 4,
          "PaymentType": 1,
          "PaymentAgentInfo": {
            "AgentType": "AGENT",
            "SupplierInn": "7718221538",
            "SupplierName": "ООО «Фитосила»",
            "SupplierPhone": "+74959613411"
          }
        },
        {
          "Label": "Налокотник эластичный \"Серебряный верблюд\", 1 размер",
          "Price": 218.37,
          "Quantity": 1.0,
          "Amount": 218.37,
          "Vat": "VatNo",
          "PaymentMethod": 4,
          "PaymentType": 1,
          "PaymentAgentInfo": {
            "AgentType": "AGENT",
            "SupplierInn": "7718221538",
            "SupplierName": "ООО «Фитосила»",
            "SupplierPhone": "+74959613411"
          }
        },
        {
          "Label": "Носки из шерсти альпака, р. 25",
          "Price": 191.47,
          "Quantity": 1.0,
          "Amount": 191.47,
          "Vat": "VatNo",
          "PaymentMethod": 4,
          "PaymentType": 1,
          "PaymentAgentInfo": {
            "AgentType": "AGENT",
            "SupplierInn": "7718221538",
            "SupplierName": "ООО «Фитосила»",
            "SupplierPhone": "+74959613411"
          }
        },
        ...........
        }
      ],
      "PaymentItems": null
	  }
    },
    "Cashier": {}
  }

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

{
    "Status": "Success",
    "DataList": [
        {
            "ReceiptId": "400dcca2-d15b-48ff-9ec5-71eb6c04c741"
        },
        {
            "ReceiptId": "40651553-d8ad-49eb-9376-af37ac8ca74f"
        },
        {
            "ReceiptId": "e0276498-17bf-4b69-98af-31b50a998e09"
        },
        {
            "ReceiptId": "c6188fcd-b744-4409-b276-b50c8372e5e9"
        },
        {
            "ReceiptId": "1223f1d7-2771-4dac-a067-9c400327a767"
        }
    ]
}

При проверке статуса чека по параметру «InvoiceId» возвращается массив чеков со статусами пробития на кассах Ferma®. Проверка статуса чека по параметру «ReceiptId» возвращает статус одного чека из списка. Описание метода проверки статуса кассового чека представлено в разделе "3.4. Проверка статуса кассового чека"

Пример проверки статуса чека по параметру «InvoiceId»:

{
    "Status": "Success",
    "DataList": [
        {
            "StatusCode": 2,
            "StatusName": "CONFIRMED",
            "StatusMessage": "Чек передан в ОФД",
            "ModifiedDateUtc": "2021-11-18T15:51:09",
            "ReceiptDateUtc": "2021-11-18T15:51:09",
            "ModifiedDateTimeIso": "2021-11-18T15:51:09+03:00[Europe/Moscow]",
            "ReceiptDateTimeIso": "2021-11-18T15:51:09+03:00[Europe/Moscow]",
            "ReceiptId": "9528b5ac-5197-4f70-b7d7-1a57bfa78d7c",
            "Device": {
                "DeviceId": 7405,
                "RNM": "0000000010053286",
                "ZN": "9985857579",
                "FN": "9999078902001735",
                "FDN": "78224",
                "FPD": "1599519205",
                "ShiftNumber": null,
                "ReceiptNumInShift": 289,
                "DeviceType": "Эфир Pro ФС",
                "OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78224/1599519205"
            }
        },
        {
            "StatusCode": 2,
            "StatusName": "CONFIRMED",
            "StatusMessage": "Чек передан в ОФД",
            "ModifiedDateUtc": "2021-11-18T15:51:19",
            "ReceiptDateUtc": "2021-11-18T15:51:19",
            "ModifiedDateTimeIso": "2021-11-18T15:51:19+03:00[Europe/Moscow]",
            "ReceiptDateTimeIso": "2021-11-18T15:51:19+03:00[Europe/Moscow]",
            "ReceiptId": "ed748298-8450-4563-8564-ba5660bb2e30",
            "Device": {
                "DeviceId": 7405,
                "RNM": "0000000010053286",
                "ZN": "9985857579",
                "FN": "9999078902001735",
                "FDN": "78227",
                "FPD": "2919427768",
                "ShiftNumber": null,
                "ReceiptNumInShift": 292,
                "DeviceType": "Эфир Pro ФС",
                "OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78227/2919427768"
            }
        },
        {
            "StatusCode": 2,
            "StatusName": "CONFIRMED",
            "StatusMessage": "Чек передан в ОФД",
            "ModifiedDateUtc": "2021-11-18T15:51:15",
            "ReceiptDateUtc": "2021-11-18T15:51:15",
            "ModifiedDateTimeIso": "2021-11-18T15:51:15+03:00[Europe/Moscow]",
            "ReceiptDateTimeIso": "2021-11-18T15:51:15+03:00[Europe/Moscow]",
            "ReceiptId": "c54fc696-c36c-4039-8f75-bf0bbf6167a2",
            "Device": {
                "DeviceId": 7405,
                "RNM": "0000000010053286",
                "ZN": "9985857579",
                "FN": "9999078902001735",
                "FDN": "78226",
                "FPD": "3192423269",
                "ShiftNumber": null,
                "ReceiptNumInShift": 291,
                "DeviceType": "Эфир Pro ФС",
                "OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78226/3192423269"
            }
        },
        {
            "StatusCode": 2,
            "StatusName": "CONFIRMED",
            "StatusMessage": "Чек передан в ОФД",
            "ModifiedDateUtc": "2021-11-18T15:51:22",
            "ReceiptDateUtc": "2021-11-18T15:51:22",
            "ModifiedDateTimeIso": "2021-11-18T15:51:22+03:00[Europe/Moscow]",
            "ReceiptDateTimeIso": "2021-11-18T15:51:22+03:00[Europe/Moscow]",
            "ReceiptId": "aa6e916c-2e9e-4fa4-94d4-8b8dd92c636a",
            "Device": {
                "DeviceId": 7405,
                "RNM": "0000000010053286",
                "ZN": "9985857579",
                "FN": "9999078902001735",
                "FDN": "78228",
                "FPD": "3629293526",
                "ShiftNumber": null,
                "ReceiptNumInShift": 293,
                "DeviceType": "Эфир Pro ФС",
                "OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78228/3629293526"
            }
        },
        {
            "StatusCode": 2,
            "StatusName": "CONFIRMED",
            "StatusMessage": "Чек передан в ОФД",
            "ModifiedDateUtc": "2021-11-18T15:51:05",
            "ReceiptDateUtc": "2021-11-18T15:51:05",
            "ModifiedDateTimeIso": "2021-11-18T15:51:05+03:00[Europe/Moscow]",
            "ReceiptDateTimeIso": "2021-11-18T15:51:05+03:00[Europe/Moscow]",
            "ReceiptId": "ea0aa3ab-47de-4fae-b360-72ee28320dcc",
            "Device": {
                "DeviceId": 7405,
                "RNM": "0000000010053286",
                "ZN": "9985857579",
                "FN": "9999078902001735",
                "FDN": "78223",
                "FPD": "678189693",
                "ShiftNumber": null,
                "ReceiptNumInShift": 288,
                "DeviceType": "Эфир Pro ФС",
                "OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/78223/678189693"
            }
        }
    ]
}

3.2.5. Примеры формируемых чеков

Внимание! Параметр Measure в структуре Items является обязательным для ФФД 1.2. По умолчанию (если параметр Measure не был передан в теле запроса для ФФД 1.2) присваивается значение PIECE.

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

{
  "Request": {
    "Inn": "2465165753",
    "Type": "Income",
    "InvoiceId": "qyqg3456789_u12",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "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,
                "Measure": "PIECE",
                "PaymentType": 4,
                "OriginCountryCode": "643",
                "CustomsDeclarationNumber": null,
                "PaymentAgentInfo": null
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

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

{
  "Request": {
    "Inn": "0123456789",
    "Type": "IncomeCorrection",
    "InvoiceId": "test2_8744273567_u12",    
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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,
                "Measure": "PIECE",
                "PaymentType": 4
            }
        ]
    }
  }
}

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

{
  "Request": {
    "Inn": "0123456789",
    "Type": "Income",
    "InvoiceId": "6f000fee-bbac-4444-bda1-8888_u22",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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,
                "Measure": "PIECE"
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

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

{
  "Request": {
    "Inn": "0123456789",
    "Type": "Income",
    "InvoiceId": "6f110fee-bbac-7777-bda1-e9555996fcc7_1",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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,
                "Measure": "PIECE",
                "OriginCountryCode": "398",
                "CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
                "PaymentType": 10
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

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

{
  "Request": {
    "Inn": "5319782640",
    "Type": "Income",
    "InvoiceId": "6f110fee-bbac-4446-bda1-e9ce2996fcc0_12",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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,
                "Measure": "PIECE",
                "PaymentType": 10
            },
            {
                "Label": "Услуга по страхованию.",
                "Price": 100.00,
                "Quantity": 1.0,
                "Amount": 100.00,
                "Vat": "Vat20",
                "MarkingCode": null,
                "PaymentMethod": 0,
                "Measure": "PIECE",
                "PaymentType": 3
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

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

{
  "Request": {
    "Inn": "5645648283",
    "Type": "Income",
    "InvoiceId": "6f000fee-bbac-4444-bda1-e9111111fcc0_u1",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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,
                "Measure": "PIECE",
                "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,
                "Measure": "PIECE",
                "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):

{
  "Request": {
    "Inn": "5319782640",
    "Type": "Income",
    "InvoiceId": "6f550fee-bbac-4445-bda1-e5111556fcc5_u12",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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,
                "Measure": "PIECE",
                "PaymentType": 32
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

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

{
  "Request": {
    "Inn": "0258469137",
    "Type": "Income",
    "InvoiceId": "6f290fee-bbac-1111-bda1-e1111116fcc4_u1",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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": "444D0436038939FC53784D476F72764E757136576B",
                "PaymentMethod": 0,
                "Measure": "PIECE",
                "PaymentType": 32
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

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

{
  "Request": {
    "Inn": "4613794639",
    "Type": "Income",
    "InvoiceId": "1256_u1",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@yahoo.ru",
        "PaymentType": 0,
        "CustomUserProperty": null,
        "PaymentAgentInfo": {
            "AgentType": "AGENT",
            "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,
                "Measure": "PIECE",
                "PaymentType": 4
            }
        ],
        "PaymentItems": [
            {
                "PaymentType": 1,
                "Sum": 889.00
            }
        ]
    }
  }
}

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

{
  "Request": {
    "Inn": "1739284652",
    "Type": "Income",
    "InvoiceId": "6f330fee-bbac-6661-bda1-e8111886fcc8_u12",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": {
            "AgentType": "AGENT",
            "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,
                "Measure": "PIECE",
                "OriginCountryCode": "398",
                "CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
                "PaymentType": 10
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

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

{
  "Request": {
    "Inn": "1739284652",
    "Type": "Income",
    "InvoiceId": "6f222fee-bbac-4444-bda1-e9ce2442fc",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "AutomaticDeviceNumber": "46222",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo": {
            "Name": "Тестов Тест Тестович",
            "Inn": "123456789102"
        },
        "Items": [
            {
                "Label": "Оплата услуг по страхованию.",
                "Price": 5328.53,
                "Quantity": 1.0,
                "Amount": 5328.53,
                "Vat": "VatNo",
                "MarkingCode": null,
                "PaymentMethod": 0,
                "Measure": "PIECE"
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null,
        "AdditionalReceiptProp": "1234567890"
    }
  }
}

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

{
  "Request": {
    "Inn": "1739284652",
    "Type": "BuyCorrection",
    "InvoiceId": "2f222fee-bbac-4444-bda9-e9ce99996",
    "CallbackUrl":"https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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,
                "Measure": "PIECE"
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

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

{
  "Request": {
    "Inn": "781148191912",
    "Type": "IncomeCorrection",
    "InvoiceId": "ffb7fc5e-fe96-4f8f-900c-e88d8c27",
    "CallbackUrl":"https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
      "TaxationSystem": "Common",
      "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,
        "Measure": "PIECE",
        "PaymentType": 0,
        "OriginCountryCode": null,
        "CustomsDeclarationNumber": null,
        "PaymentAgentInfo": null,
        "UserProperty1080": null
      }
    ],
    "PaymentItems": null,
    "Vat": null,
    "CustomUserProperty": null,
    "AdditionalReceiptProp": 3144062149
    }
  }
}

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

{
  "Request": {
    "Inn": "0258469137",
    "Type": "Income",
    "InvoiceId": "6f290fee-bbac-111-bda1-e1131",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo": null,
        "Items": [
              {
          "Label": "Тестовый товар",
          "Price": 50.0,
          "Quantity": 1.0,
          "Amount": 50.0,
          "Vat": "CalculatedVat20120",
          "PaymentMethod": 3,
          "Measure": "PIECE",
          "OriginCountryCode": 46,
          "CustomsDeclarationNumber": 4567896,
          "IndustryItemRequisite": {
            "FoivId": "046",
            "DocDate": "01.01.2021",
            "DocNumber": "123",
            "Value": "456"
          },
          "MarkingCodeData": {
            "Code": "00000046210654mT/hXgcAAPidGVz",
            "Type": "UNKNOWN_PRODUCT_CODE",
            "PlannedStatus": "PRODUCT_STATUS_NOT_CHANGED", 
            "Fractional": { 
             "Numerator": 1, 
             "Denominator": 10             
             }
          },
          "PaymentType": 31
         }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

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

{
  "Request": {
    "Inn": "0123456789",
    "Type": "Income",
    "InvoiceId": "6f000fee-bbac-4444-bda1-e9ce9999f676",
    "CallbackUrl":"https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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",
                "Excise": 50.47,
                "MarkingCode": null,
                "PaymentMethod": 0,
                "Measure": "PIECE"
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

Чек коррекции с отсутствующими товарными позициями (Items) Применим только для ФФД 1.02:

{
  "Request": {
    "Inn": "1739284652",
    "Type": "IncomeCorrection",
    "InvoiceId": "2f222fee-bbac-4444-bda9-e9ce9999fcc2_U21",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "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": [
              {
          "Label": "Тестовый товар",
          "Price": 50.0,
          "Quantity": 1.0,
          "Amount": 50.0,
          "Vat": "CalculatedVat20120",
          "PaymentMethod": 3,
          "PaymentType": 0,
          "Measure": "PIECE"
         }
        ],
        "PaymentItems": [
            {
                "PaymentType": 1,
                "Sum": 150.00
            }
        ],
        "Vat": "Vat20",
        "CustomUserProperty": null
    }
  }
}

Простой чек аванса:

{
  "Request": {
    "Inn": "0258469137",
    "Type": "IncomePrepayment",
    "InvoiceId": "6f2966789fee-bb23ac-111-b555a1-e1138881",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "PaymentType": 1,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo": null,
        "Items": [
              {
          "Label": "Тестовый товар",
          "Price": 50.0,
          "Quantity": 1.0,
          "Amount": 50.0,
          "Vat": "CalculatedVat20120",
          "PaymentMethod": 3,
          "PaymentType": 0,
          "Measure": "PIECE"
         }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

Простой чек зачет аванса:

{
  "Request": {
    "Inn": "0258469137",
    "Type": "Income",
    "InvoiceId": "6f2966789fee-bb23ac-111-b555a1-e1138881",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "PaymentType": 1,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo": null,
        "Items": [
              {
          "Label": "Тестовый товар",
          "Price": 50.0,
          "Quantity": 1.0,
          "Amount": 50.0,
          "Vat": "CalculatedVat20120",
          "PaymentMethod": 4,
          "PaymentType": 0,
          "Measure": "PIECE"
         }
        ],
        "PaymentItems": [{
                "PaymentType": 2,
                "Sum": 50
            }]
        "CustomUserProperty": null
    }
  }
}

3.3. Описание работы с КМ в API Ferma®

Клиентам подключенной услуги Ferma® доступны кассы, со следующими форматами ФФД:

  • 1.1;
  • 1.2.

С 6 августа 2021 года ФНС России введен новый формат фискальных документов — ФФД 1.2. Подробнее о формате ФФД 1.2 вы можете узнать в приказе ФНС от 14.09.2020г. № ЕД-7-20/662@.
Клиенты Ferma®, реализующие товары с обязательной маркировкой или собирающиеся начать их продавать, должны до 1 февраля 2022 года перейти на новый формат фискальных данных при передаче чеков.

Мы рекомендуем не откладывать доработки вашей системы и подготовиться к переходу заранее.
После уведомления о переходе касс Ferma® на ФФД 1.2 вам необходимо передавать значения кода маркировки в соответствии с ФФД 1.2.

В API Ferma® код маркировки возможно передать в следующих версиях ФФД 1.1, 1.2.

В версии ФФД 1.1 значение кода маркировки передается в параметрах «MarkingCode», «MarkingCodeStructured», в составе параметра «Items» (Тег 1059).
В версии ФФД 1.2 значение кода маркировки передается в параметре «MarkingCodeData», в составе параметра «Items» (Тег 1059).

Если при формировании чека в параметре «MarkingCodeData» во вложенном параметре Type не поставили значение, то по умолчанию ставится значение «UNKNOWN_PRODUCT_CODE»

3.3.1. Передача кода маркировки в ФФД 1.2 в API Ferma®

Код маркировки товара передается в чеке в составе параметра Items (тег 1059). Для передачи кода маркировки в соответствии с ФФД 1.2 в кассах Ferma® разработан параметр «MarkingCodeData».

В сервисе Ferma® при передаче значения товара с КМ и признаком дробной реализации, обязательно передается в теле запроса на пробитие чека параметр «Fractional». Значение параметра Numerator должно быть строго меньше значения Denominator и оба значения не должны равняться нулю. Если КМ персональный, параметр Fractional не передается.

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

{
  "Status": "Failed",
   "Data": {
     "ValidationErrors": [
      {
        "FieldName": "receipt.customerReceipt.receiptItems[0].markingCodeData.fractionalMc",
        "Description": "В случае, если реализовывается маркированный товар поштучно, а код маркировки есть только на пачку, числитель (Numerator) должен быть строго меньше знаменателя (Denominator), а также числитель и знаменатель не могут быть равны 0"
      }
    ]
  },
  "Error": {
    "Code": 1085,
    "Message": "Запрос содержит ошибки"
  }
}

Выбор значения параметра Type зависит от формата кода маркировки. Описание форматов кодов маркировки представлено в приказе ФНС от 14.09.2020г. № ЕД-7-20/662@. Считанный сканером код маркировки передается в параметре «Code».

Параметр проверки кода маркировки «CheckMcMode» не обязательный в запросе на формирование фискального документа . Перед пробитием чека касса автоматически проверит код маркировки.
Если вы в запросе не указали параметр CheckMcMode, чек пробьётся при любом результате проверки кода маркировки в ЦРПТ.
Если вы передали одно из следующих значений:

  • IGNORE_ANY_ERRORS - вне зависимости от результата проверки, устанавливается по умолчанию, чек пробьётся;
  • REQUIRE_NO_M_MINUS - касса пробивает чек, если результат проверки КМ в ЦРПТ не равен значению М-. В случае если результат проверки кода окажется равен значению М- касса чек не пробивает

Если вы не смогли определить формат кода маркировки, в параметре «Type» указываете значение «UNKNOWN_PRODUCT_CODE». Касса автоматически проверит в ЦРПТ код маркировки и определит формат.

Внимание! В сервисе Ferma® по значению формата КМ определяется требование проверки КМ в честном знаке. Если в параметре «Type» будет задано значение формат КМ с признаком «Не требуется», касса не отправит значение КМ на проверку в честный знак. В таблице 3.8 представлен список форматов КМ с признаком требования проверки КМ в честном знаке.

Таблица 3.8. Список форматов КМ с признаком требования проверки КМ в честном знаке

Значение формата КМ Признак требования проверки в честном знаке
UNKNOWN_PRODUCT_CODE Требуется
EAN8 — значение кода маркировки в формате EAN-8 Не требуется
EAN13 — значение кода маркировки в формате EAN-13 Не требуется
ITF14 — значение кода маркировки в формате ITF-14 Не требуется
GS1 — значение кода маркировки в формате GS1 Не требуется
GS1M — значение кода маркировки в формате GS1.M Требуется
SHORT_MC — значение кода маркировки в формате КМК (Короткий код маркировки) Требуется
FUR — Контрольно-идентификационный знак мехового изделия Не требуется
EGAIS20 — значение кода маркировки в формате ЕГАИС-2.0. Не требуется
EGAIS30 — значение кода маркировки в формате ЕГАИС-3.0. Не требуется
KTF1 — Определяется ФНС России Не требуется
KTF2 — Определяется ФНС России Не требуется
KTF3 — Определяется ФНС России Не требуется
KTF4 — Определяется ФНС России Не требуется
KTF5 — Определяется ФНС России Не требуется
KTF6 — Определяется ФНС России Не требуется

Параметр «MarkingCodeData» содержит в своем составе параметры, описанные в таблице 3.9.

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

Параметр Вложенный параметр Формат значения Описание Тег 46) Обязательность47)
Type Строка Формат КМ
Может принимать следующие значения:
- UNKNOWN_PRODUCT_CODE 1300
- EAN8 — значение кода маркировки в формате EAN-8 1301
- EAN13 — значение кода маркировки в формате EAN-13 1302
- ITF14 — значение кода маркировки в формате ITF-14 1303
- GS1 — значение кода маркировки в формате GS1 1304
- GS1M — значение кода маркировки в формате GS1.M 1305
- SHORT_MC — значение кода маркировки в формате КМК (Короткий код маркировки) 1306
- FUR — Контрольно-идентификационный знак мехового изделия 1307
- EGAIS20 — значение кода маркировки в формате ЕГАИС-2.0. 1308
- EGAIS30 — значение кода маркировки в формате ЕГАИС-3.0. 1309
- KTF1 — Определяется ФНС России 1320
- KTF2 — Определяется ФНС России 1321
- KTF3 — Определяется ФНС России 1322
- KTF4 — Определяется ФНС России 1323
- KTF5 — Определяется ФНС России 1324
- KTF6 — Определяется ФНС России 1325
Code Строка Код маркировки.
Не имеет ограничений по количеству символов
PlannedStatus Строка Если в параметре «PlannedStatus» значение не было задано, то по умолчанию ставится значение «PIECE_PRODUCT_INCOME» (штучный товар).
Планируемый статус товара с КМ может принимать следующие значения:
2003 3
- PIECE_PRODUCT_INCOME — Штучный товар, подлежащий обязательной маркировке средством идентификации, реализован;
- MEASURED_PRODUCT_INCOME — Мерный товар, подлежащий обязательной маркировке средством идентификации, в стадии реализации;
- PIECE_PRODUCT_RETURN — Штучный товар, подлежащий обязательной маркировке средством идентификации, возвращен;
- MEASURED_PRODUCT_RETURN — Часть товара, подлежащего обязательной маркировке средством идентификации, возвращена;
- PRODUCT_STATUS_NOT_CHANGED — Статус товара, подлежащего обязательной маркировке средством идентификации, не изменился.
Fractional Структура Тег содержит дробное количество маркированного товара. 129148) 249)
Numerator Число Числитель (значение должно быть строго меньше значения тега 1294) 1293 1
Denominator Число Знаменатель 1294 1

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

{
  "Request": {
    "Inn": "0258469137",
    "Type": "Income",
    "InvoiceId": "6f290fee-bbac-111-bda1-e1131",
    "CallbackUrl": "https://webhook.site/0c01f3ef-597e-43d8-8463-4c1b942d3ea2",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo": null,
        "Items": [
              {
          "Label": "Тестотвый товар",
          "Price": 50.0,
          "Quantity": 1.0,
          "Amount": 50.0,
          "Vat": "CalculatedVat20120",
          "PaymentMethod": 3,
          "Measure": "PIECE",
          "OriginCountryCode": 46,
          "CustomsDeclarationNumber": 4567896,
          "IndustryItemRequisite": {
            "FoivId": "046",
            "DocDate": "01.01.2021",
            "DocNumber": "123",
            "Value": "456"
          },
          "MarkingCodeData": {
            "Code": "00000046210654mT/hXgcAAPidGVz",
            "Type": "UNKNOWN_PRODUCT_CODE",
            "PlannedStatus": "PRODUCT_STATUS_NOT_CHANGED", 
            "Fractional": { 
             "Numerator": 1, 
             "Denominator": 10             
             }
          },
          "PaymentType": 0
         }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
  }
}

3.3.2. Описание работы параметра повторной проверки КМ в API Ferma®

При выполнении запросов на пробитие чека в API Ferma®, вы можете установить время ожидания получения положительного результата проверки КМ. После истечения времени ожидания, облачная касса пробьет чек с первым успешным результатом проверки КМ в честном знаке.

Параметр установки времени ожидания получения положительного результата проверки КМ, является опциональным.

Текущее ограничение значения параметра - полчаса. Значения параметра задается в секундах. В параметре может передаваться значение не больше 1800 секунд, также значение должно быть положительным (строго больше 0). Если вы указали значение больше 1800 секунд, то при выполнении запроса на формирование фискального документа, вам будет выведена ошибка с кодом 1085 и сообщение о превышении допустимого значения.

Пример запроса:


{
  "Request": {
    "Inn": "7841465198",
    "Type": "Income",
    "InvoiceId": "sdf21111q1111",
    "McCheckRetryPeriodSec": 600,
    "CustomerReceipt": {
      "TaxationSystem": "Common",
      "Email": "pegov@test.ru",
      "KktFA": false,
      "PaymentType": 1,
      "Items": [
        {
          "Label": "Товар с КМ",
          "Price": 50.0,
          "Quantity": 1.0,
          "Amount": 50.0,
          "Vat": "CalculatedVat20120",
          "PaymentMethod": 3,
          "Measure": "PIECE",
          "MarkingCodeData": {
            "Code": "\u00E8010460780959133121e/Fw:xeo47NK2\u001D91F010\u001D92Afwuf6d3c9oszbRy/Vb+hRU|1wokz/8UOthdpBYw9A0=",
            "Type": "GS1M",
            "Fractional": {
              "Numerator": "1",
              "Denominator": "2"
            }
          },
          "PaymentType": 0
        }
      ]
    }
  }
}

Сообщение о превышении допустимого значения:


{
    "Status": "Failed",
    "Data": {
        "ValidationErrors": [
            {
                "FieldName": "receipt.mcCheckRetryPeriodSec",
                "Description": "Допустимый период проверки КМ не должен превышать полчаса в секундах (1800 сек)"
            }
        ]
    },
    "Error": {
        "Code": 1085,
        "Message": "Запрос содержит ошибки"
    }
}

3.4. Проверка статуса кассового чека

Важно! Информация о статусе кассового чека хранится в оперативной памяти сервиса Ferma® всего сутки. После истечения суток при повторном запросе статуса кассового чека в ответ будет выведена ошибка «Чек не найден». После истечения суток информацию о статусе кассового чека можно получить в запроса реестра кассовых чеков.

Вид запроса:

POST https://ferma.ofd.ru/api/kkt/cloud/status?AuthToken={Code1}
Content-Type: application/json

Вы можете проверить статус чека после следующим параметрам:

  • ReceiptId - идентификатор, присвоенный сервисом Ferma®
  • InvoiceId - идентификатор, сформированный вашей информационной системой

Тело запроса представляет собой структуру JSON и имеет следующий вид для запроса по параметру «ReceiptId»:

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

Тело запроса представляет собой структуру JSON и имеет следующий вид для запроса по параметру «InvoiceId»:

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

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

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

Параметр Вложенные поля Формат значения Описание
Request Структура Параметры запроса статуса кассового документа
ReceiptId Строка Идентификатор, присвоенный сервисом Ferma®
InvoiceId Строка Идентификатор, присвоенный вашей информационной системой в запросе на формирование кассового чека.

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

{
    "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.11.

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

Параметр Вложенные поля Формат значения Описание
StatusCode Число Код статуса
StatusName Строка Название статуса
StatusMessage Строка Необязательный параметр, содержащий дополнительную информацию о текущем состоянии, может отсутствовать
ModifiedDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время, указанные в чеке по московскому времени
ModifiedDateTimeIso Строка, описывающая момент времени (дату и время в формате ISO) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateTimeIso Строка, описывающая момент времени (дату и время в формате ISO) Дата и время, указанные в чеке по московскому времени
Device Структура Информация об устройстве (ККТ), на котором была произведена операция
DeviceId Строка Сервисный идентификатор устройства, на котором генерируется кассовый документ (чек)
RNM Строка Регистрационный номер кассы
ZN Строка Заводской номер кассы
FN Строка Номер фискального накопителя, установленного в кассу
FDN Строка Номер фискального документа
FPD Строка Фискальный признак документа
ShiftNumber Число Номер смены
ReceiptNumInShift Число Номер чека в смене
DeviceType Строка Модель кассы, на которой пробит чек
OfdReceiptUrl Строка Ссылка на чек

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

  • запрос на чек принят ИС 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.12.

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

Параметр Формат значения Описание
StatusCode Число Код ошибки
StatusName Строка Название ошибки
StatusMessage Строка Описание ошибки
Description Строка Детальное описание ошибки
ModifiedDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время, указанные в чеке по московскому времени
ModifiedDateTimeIso Строка, описывающая момент времени (дату и время в формате ISO) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateTimeIso Строка, описывающая момент времени (дату и время в формате ISO) Дата и время, указанные в чеке по московскому времени
Device Структура Информация об устройстве (ККТ), на котором была произведена операция


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

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


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

3.5. Запрос реестра кассовых чеков

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

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

POST https://ferma.ofd.ru/api/kkt/cloud/list?AuthToken={Code1}
Content-Type: application/json

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

POST https://ferma.ofd.ru/api/kkt/cloud/list2?AuthToken={Code1}
Content-Type: application/json

Тело запроса представляет собой структуру 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.13.

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

Параметр Формат значения Описание Обязателен в запросе
ReceiptId Строка в формате UUID Идентификатор чека, присвоенный сервисом Ferma® Нет
StartDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время начала интервала по московскому времени Нет
EndDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время окончания интервала по московскому времени Нет
StartDateLocal Строка, описывающая момент времени (дату и время) Локальная дата и время начала интервала Да
EndDateLocal Строка, описывающая момент времени (дату и время) Локальная дата и время окончания интервала Да

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

{
    "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": {
                                "Gtin": "77777777777777",
                                "Serial": "RXWWWRRRRRRRR",
                                "Type": "MEDICINES"
                            },
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "Measure": "PIECE",
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        },
                        {
                            "Label": "Табак с кодом маркировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": {
                                "Gtin": "77777777777777",
                                "Serial": "RXWWWRRRRRRRS",
                                "Type": "MEDICINES"
                            },
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "Measure": "PIECE",
                            "PaymentType": 4,
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        },
                        {
                            "Label": "Табак с кодом ма12154215ркировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": {
                                "Gtin": "7",
                                "Serial": "RXWWWRRRRRRRR",
                                "Type": "MEDICINES"
                            },
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "Measure": "PIECE",
                            "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,
                            "Measure": "PIECE",
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        }
                    ],
                    "PaymentItems": [
                        {
                            "PaymentType": 1,
                            "Sum": 4000.0
                        }
                    ],
                    "Vat": null,
                    "CustomUserProperty": null,
                    "AdditionalReceiptProp": null
                },
                "Cashier": {}
            }
        }
        ...
    ]
}

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

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

Параметр Формат значения Описание
ReceiptId Строка Идентификатор чека, присвоенный сервисом Ferma®
StatusCode Число Код статуса
StatusName Строка Название статуса
StatusMessage Строка Необязательный параметр, содержащий дополнительную информацию о текущем состоянии. Может отсутствовать
ModifiedDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время, указанные в чеке по московскому времени. При использовании метода list - возвращается серверное время обработки чека, при использовании list2 - возвращает время пробития чека на кассе (время кассы)
ModifiedDateTimeIso Строка, описывающая момент времени (дату и время в формате ISO) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateTimeIso Строка, описывающая момент времени (дату и время в формате ISO) Дата и время, указанные в чеке по московскому времени. При использовании метода list - возвращается серверное время обработки чека, при использовании list2 - возвращает время пробития чека на кассе (время кассы)
InvoiceId Строка Идентификатор, присвоенный вашей информационной системой в запросе на формирование кассового чека.
Receipt Структура Содержимое клиентского чека. Параметры элементов структуры «Receipt» приведены в таблице 3.15.

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

Параметр Вложенные поля Вложенные поля Формат значения Описание
cashboxInfoHolder Структура Информация о кассовом аппарате
checkNumInShift Число Номер чека в смене
shiftNum Число Номер смены
totalSum Число Общая сумма по чеку
cashboxType Число Тип кассы, на которой был сгенерирован чек
DeviceId Число Сервисный идентификатор устройства, на котором был сгенерирован чек
RNM Строка Регистрационный номер кассы
ZN Строка Заводской номер кассы
FN Строка Номер фискального накопителя
FDN Строка Номер фискального документа
FPD Строка Фискальный признак документа
Inn Строка ИНН лица, от имени которого был сгенерирован кассовый документ (чек)
Type Строка Тип формируемого фискального документа (чек).
Тип может принимать следующие значения:
– «Income» — получение денежных средств от покупателя;
– «IncomeReturn» — возврат денежных средств, полученных от покупателя;
– «IncomePrepayment» — авансовый платеж от покупателя;
– «IncomeReturnPrepayment» — возврат аванса;
– «IncomeCorrection» — чек коррекции/приход;
– «BuyCorrection» — чек коррекции/расход;
– «IncomeReturnCorrection» - чек коррекции/Возврат прихода;
– «ExpenseReturnCorrection» - чек коррекции/Возврат расхода;
– «Expense» — выдача денежных средств покупателю;
– «ExpenseReturn» — возврат денежных средств, выданных покупателю.
InvoiceId Строка Идентификатор, присвоенный вашей информационной системой в запросе на формирование кассового чека.
CustomerReceipt Структура Содержимое клиентского чека
TaxationSystem Строка Система налогообложения.
Внимание! Список применения значений систем налогообложения формируется на этапе регистрации кассы. Чтобы изменить список допустимых значений, необходимо выполнить перерегистрацию кассы.
Параметр определения системы налогообложения может принимать следующие значения:
– «Common» или «0» — общая система налогообложения;
– «SimpleIn» или «1» — упрощенная система налогообложения (доход);
– «SimpleInOut» или «2» — упрощенная система налогообложения (доход минус расход);
– «Unified» или «3» — единый налог на вмененный доход;
– «UnifiedAgricultural» или «4» — единый сельскохозяйственный налог;
– «Patent» или «5» — патентная система налогообложения.
Email Строка Адрес электронной почты клиента
Phone Строка Контактный телефон клиента
BillAddress Строка Место осуществления расчетов
KktFA Логическое выражение Если используется касса ФА в сервисе Ferma® необходимо установить значение true. Если используется касса ФС необходимо установить значение false.
Касса ФА может применятся для :
– вендингового аппарата, при совершении расчетов за товары или услуги;
– совершения расчетов за проезд в автоматизированном режиме (через валидатор) или совершения расчетов через терминал кондуктора
PaymentType Число Признак предмета расчета для всего чека. Список возможных значений перечислен в п. 3.1.4.
PaymentAgentInfo Структура Структура, содержащая данные платежного агента
AgentType 50) Строка Тип (признак) платежного агента. Возможные значения:
BANK_PAYMENT_AGENT — банковский платежный агент;
BANK_PAYMENT_SUBAGENT — банковский платежный субагент;
PAYMENT_AGENT — платежный агент;
PAYMENT_SUBAGENT — платежный субагент;
CONFIDANT — поверенный;
COMMISSIONER — комиссионер;
AGENT — агент.
CorrectionInfo Структура Структура, описывающая информацию по чеку коррекции
Type Строка Тип коррекции:
SELF — коррекция производится самостоятельно;
INSTRUCTION — коррекция производится по предписанию.
Description Строка Описание коррекции и причин коррекции
ReceiptDate Строка Дата пробития чека, к которому был применен чек коррекции. В формате «ДД.ММ.ГГ», где ДД — день, ММ — месяц, ГГ — год.
ReceiptId Строка Номер предписания налогового органа
ClientInfo Структура Данные о покупателе
Name Строка ФИО и паспортные данные покупателя или наименование организации, если клиент юр. лицо. Не более 256 символов в поле
Inn Строка ИНН покупателя. Длина 10-12 цифр
Items Структура Товарные позиции, приобретенные клиентом. Параметры элементов структуры Items приведены в таблице 3.16.
PaymentItems Структура Суммы по типам оплат
PaymentType Число Тип оплаты:
0 – наличными;
1 – безналичными;
2 – предварительная оплата (аванс);
3 – предварительная оплата (кредит);
4 – иная форма оплаты.
Sum Число с точкой Сумма по типу, в рублях
Vat Строка Вид вычисляемого НДС.
Обязательное поле для чеков коррекции, если Items не равен NULL.
Параметр может принимать следующие значения:
- «VatNo» — налог на добавленную стоимость без НДС;
- «Vat10» — налог на добавленную стоимость (НДС) 10%;
- «Vat20» — НДС 20% 51);
- «Vat0» — НДС 0%;
- «CalculatedVat10110» — вычисленный НДС 10% от 110% суммы;
- «CalculatedVat20120» — вычисленный НДС 20% от 120% суммы52).
CustomUserProperty Структура Дополнительный реквизит пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты
Name Строка Наименование дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты
Value Строка Значение дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты
AdditionalReceiptProp
Cashier Структура Информация о кассире
Name Строка ФИО кассира
Inn Строка ИНН кассира

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

Параметр Вложенные поля Формат значения Описание
Label Строка Наименование предмета расчета
Price Число с точкой Цена товарной позиции в рублях
Quantity Число с точкой Количество товара в товарной позиции
Amount Число с точкой Общая стоимость товара в товарной позиции в рублях
Vat Строка Вид вычисляемого НДС.
Обязательное поле для чеков коррекции, если Items не равен NULL.
Параметр может принимать следующие значения:
- «VatNo» — налог на добавленную стоимость без НДС;
- «Vat10» — налог на добавленную стоимость (НДС) 10%;
- «Vat20» — НДС 20% 53);
- «Vat0» — НДС 0%;
- «CalculatedVat10110» — вычисленный НДС 10% от 110% суммы;
- «CalculatedVat20120» — вычисленный НДС 20% от 120% суммы54).
MarkingCode Строка Код маркировки товарной позиции. Передается Hex55) представление кода маркировки.
Является аналогом «MarkingCodeStructured». При использовании данного параметра нельзя использовать «MarkingCodeStructured»
MarkingCodeStructured Структура Код маркировки товарной позиции. Передается структура, содержащая информацию о маркировке товарных позиций.
Является аналогом «MarkingCode». При использовании данного параметра нельзя использовать «MarkingCode»
Type Строка Тип товарной позиции. Возможные значения:
MEDICINES;
TOBACCO;
SHOES;
UNIFIED - универсальная товарная группа (код 444D).
Gtin Строка Идентификационный номер GTIN (артикул) товара
Serial Строка Серийный номер товара
PaymentMethod Число Признак способа расчета:
- 1 — предоплата 100%;
- 2 — предоплата;
- 3 — аванс;
- 4 — полный расчет;
- 5 — частичный расчет;
- 6 — передача в кредит;
- 7 — оплата в кредит.
PaymentType Число Признак предмета расчета для конкретной позиции в чеке. Если значение отсутствует берется значение для всего чека. Возможные значения перечислены в п. 3.1.4.
OriginCountryCode Число Код страны происхождения товара. Не более 3 цифр. 56)
CustomsDeclarationNumber Строка Номер таможенной декларации. Не более 32 символов
PaymentAgentInfo Структура Структура, содержащая данные платежного агента
AgentType 57) Строка Тип (признак) платежного агента. Возможные значения:
BANK_PAYMENT_AGENT — банковский платежный агент;
BANK_PAYMENT_SUBAGENT — банковский платежный субагент;
PAYMENT_AGENT — платежный агент;
PAYMENT_SUBAGENT — платежный субагент;
CONFIDANT — поверенный;
COMMISSIONER — комиссионер;
AGENT — агент.
TransferAgentPhone Строка Телефон оператора по переводу денежных средств
TransferAgentName Строка Имя агента
TransferAgentAddress Строка Адрес агента
TransferAgentINN Строка ИНН агента
PaymentAgentOperation Строка Операция платежного агента
PaymentAgentPhone Строка Телефон платежного агента
ReceiverPhone Строка Телефон потребителя
SupplierInn Строка ИНН поставщика
SupplierName Строка Наименование поставщика
SupplierPhone Строка Телефон поставщика

В зависимости от того, какие параметры были переданы при формировании чека, некоторые элементы могут отсутствовать или иметь значение «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.17.

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

Параметр Формат значения Описание
StatusCode Число Код ошибки
StatusName Строка Название ошибки
StatusMessage Строка Описание ошибки
Description Строка Детальное описание ошибки
ModifiedDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateUtc Строка, описывающая момент времени (дату и время в формате UTC+3) Дата и время, указанные в чеке по московскому времени
ModifiedDateTimeIso Строка, описывающая момент времени (дату и время в формате ISO) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateTimeIso Строка, описывающая момент времени (дату и время в формате ISO) Дата и время, указанные в чеке по московскому времени
Device Структура Информация об устройстве (ККТ), на котором была произведена операция

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

3.6. Запрос списка ФН, которые обрабатывали ФД в определенный период

Вид запроса:

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"
        },
        ...
    ]
}

3.7. Запрос реестра кассовых чеков с детальной информацией по чеку

Вид запроса:

GET https://ferma.ofd.ru/api/kkt/cloud/stats/receipts/extended?AuthToken={Code1}&dateFrom={dateFrom}&dateTo={dateTo}&receiptId={receiptId}&zn={zn}&fn={fn}

Здесь:

  • Code1 – действующий ключ аутентификации, полученный в ответе на запрос получения ключа аутентификации.
  • dateFrom (обязательное поле) - нижняя граница даты и времени по Москве (МСК). Формат YYYY-MM-DD hh24:mi:ss«Z» (учитываются секунды входного параметра);
  • dateTo (обязательное поле) - верхняя граница даты и времени по Москве (МСК). Формат YYYY-MM-DD hh24:mi:ss«Z» (учитываются секунды входного параметра);
  • 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,
                        "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,
                        "Barcode": null,
                        "NdsCalculated10": 0,
                        "NdsCalculated18": 1667
                    }
                ]
            }
        ]
    }
}
enlightened
Параметр CalculationMethod, который присутствует в структуре Items в ответах, передает те значения,
которые были заданы в параметре PaymentMethod
структуры «Items» ТЕГ 1059.
Причина - наследование названия из API "Чеки и ККТ".

3.8. Запрос информации для мониторинга услуги Ferma® и ФН

Вид запроса:

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.18. Параметры структуры ответа метода для мониторинга состояния услуги Ferma® и ФН

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

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

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

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

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

3.9. Описание коллбэк ответа

Параметр «CallbackUrl» передается в составе запроса для пробития чека на кассе Ferma®. Параметр принимает url/ip адрес клиента-обработчика callback. После пробития чека на кассе («StatusCode»: 2/3), ответ будет отправлен методом POST на url/ip-адрес указанный в параметре «CallbackUrl».
Если в течение 300 секунд ответ не поступил, вам необходимо выполнить запрос проверки статуса кассового чека.

Для корректной работы параметра «CallbackUrl» в настройках вашей информационной системы необходимо добавить в доверительный список следующие IP-адреса:

  • 94.143.160.0/2458);
  • 94.143.161.0/2459);
  • 185.15.172.16/2960).

Приведен пример ответа, отправленный на указанный URL-адрес в параметре «CallbackUrl»:

{
	"Status": "Success",
	"Data": {
		"StatusCode": 2,
		"StatusName": "CONFIRMED",
		"StatusMessage": "Чек передан в ОФД",
		"ModifiedDateUtc": "2022-02-09T10:36:38",
		"ReceiptDateUtc": "2022-02-09T10:36:38",
		"ModifiedDateTimeIso": "2022-02-09T10:36:38+03:00[Europe/Moscow]",
		"ReceiptDateTimeIso": "2022-02-09T10:36:38+03:00[Europe/Moscow]",
		"ReceiptId": "47975e7d-ebb4-4906-83e2-e4244f56ecca",
		"InvoiceId": "7899we45453477798989363776e55",
		"Device": {
			"DeviceId": 7405,
			"RNM": "0000000010053286",
			"ZN": "9985857579",
			"FN": "9999078902001735",
			"FDN": "121453",
			"FPD": "1298875598",
			"ShiftNumber": null,
			"ReceiptNumInShift": 524,
			"DeviceType": "Эфир Pro ФС",
			"OfdReceiptUrl": "https://check-demo.ofd.ru/rec/9999078902001735/121453/1298875598"
		}
	}
}

Таблица 3.19. Описание параметров ответа на значение параметра «CallbackUrl»

Параметр Вложенный параметр Формат значения Описание
Status Строка Состояние обработки запроса
Data Структура Данные пробитого чека
StatusCode Число Код статуса.
- 0 - запрос на чек принят ИС Ferma®;
- 1 - чек сформирован на кассе;
- 2 - чек передан в ОФД;
- 3 - чек не передан в ОФД, нужно отправить повторно
StatusName Строка Название статуса.
Имеет следующие значения:
- «NEW» - запрос на чек принят ИС Ferma®
- «PROCESSED» - чек сформирован на кассе
- «CONFIRMED» - чек передан в ОФД
- «KKT_ERROR» - чек не передан в ОФД, нужно отправить повторно
StatusMessage Строка Параметр содержит дополнительную информацию о текущем состоянии.
Имеет следующие значения:
- «запрос на чек принят Фермой» запрос на чек принят ИС Ferma®
- «чек сформирован на кассе» - чек сформирован на кассе
- «чек передан в ОФД» - чек передан в ОФД
ModifiedDateUtc Строка61) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateUtc Строка62) Дата и время, указанные в чеке по московскому времени
ModifiedDateTimeIso Строка63) Дата и время последнего обновления информации о чеке по московскому времени
ReceiptDateTimeIso Строка64) Дата и время, указанные в чеке по московскому времени
ReceiptId Строка Идентификатор чека, присвоенный сервисом Ferma®
InvoiceId Строка Идентификатор чека присвоенный вашей информационной системой в запросе на формирование кассового чека.
Device Структура Информация об устройстве (ККТ), на котором была произведена операция
DeviceId Число Сервисный идентификатор устройства, на котором генерируется кассовый документ (чек)
RNM Строка Регистрационный номер кассы
ZN Строка Заводской номер кассы
FN Строка Номер фискального накопителя, установленного в кассу
FDN Строка Номер фискального документа
FPD Строка Фискальный признак документа
ShiftNumber Число Номер смены
ReceiptNumInShift Число Номер чека в смене
DeviceType Строка Модель кассы, на которой пробит чек
OfdReceiptUrl Строка Ссылка на чек

3.10. Описание запроса на получение информации об очереди

Запрос на получение информации об очереди чеков на пробитие в кассах Ferma® выполняется методом GET

Запрос на получение информации об очереди чеков имеет следующий вид:

GET https://ferma.ofd.ru/api/kkt/cloud/stats/receipts/queue/length?AuthToken={Code1}

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

Успешный ответ:

{
    "Status": "Success",
    "Data": {
        "Length": 0,
        "UpdateTime": "2022-11-09T15:44:48Z"
    }
}
параметр Вложенный параметр Формат значения Описание
Status Логическое выражение Результат выполнения запроса
Data Структура Информация об очереди чеков
Length Число Количество чеков в очереди на пробитие
UpdateTime Строка Дата и время информации об очереди на пробитие в кассы Ferma®

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

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

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

HTTP Код Код ошибки Описание ошибки
401 1001 Клиент не авторизован
500 1002 Непредвиденная ошибка
400 1003 Некорректный формат запроса
404 1004 Объект не найден
500 1 Неизвестная ошибка
500 2 Неверный логин, пароль
500 3 Нет свободных касс
500 4 Нет авторизации
400 1005 Объект Request пустой
400 1006 Объект CustomerReceipt пустой
400 1007 Некорректный ИНН
400 1008 Некорректный тип формируемого чека (Type)
400 1009 Некорректный идентификатор счета (InvoiceId)
400 1010 Некорректный тип налогообложения (TaxationSystem)
400 1011 Некорректно заполнены контакты (Email, Phone)
400 1012 Некорректный адрес электронной почты
400 1013 Некорректный номер телефона
400 1014 Некорректно заполнены позиции (Items)
400 1015 Цена и общая стоимость не должны быть отрицательными
400 1016 Количество товаров в позиции не должно быть отрицательным
400 1017 Некорректно заполнен НДС позиции (Vat)
400 1018 Общая сумма позиций должна быть неотрицательной
400 1019 Идентификатор счета уже существует (InvoiceId, ReceiptId)
400 1020 Превышено максимальное количество обращений
400 1021 Неверно указан телефон платежного агента
400 1022 Неверно указан телефон поставщика
400 1023 Неверно указан телефон оператора перевода
400 1024 Неверно указан ИНН оператора перевода
400 1025 Неверно указан признак платежного агента
400 1026 Длина поля PaymentAgentInfo.TransferAgentName превышает максимальную длину в 64 символа
400 1027 Длина поля PaymentAgentInfo.TransferAgentAddress превышает максимальную длину в 256 символов
400 1028 Длина поля PaymentAgentInfo.PaymentAgentOperation превышает максимальную длину в 24 символа
400 1029 Нет касс, соответствующих переданному типу платёжного агента
400 1030 Не указано описание коррекции (CorrectionInfo.Description)
400 1031 Некорректный формат даты совершения корректируемого расчёта
400 1032 Неверно указан тип коррекции (CorrectionInfo.Type)
400 1049 Неверно указан номер автомата (AutomatNumber). Максимальная длина 20 символов
400 1056 Идентификатор чека задан неверно или отсутствует
400 1058 Чек коррекции содержит больше одной позиции
400 1063 Указан номер автомата (AutomatNumber) совместно с флагом KktFA = false
400 1064 Чек коррекции содержит некорректный признак расчета (тег 1054)
400 1065 Некорректно заполнены ставки НДС. Указано более 1-ого типа ставки на чек
400 1066 Неверная длина тега 1191 (дополнительный реквизит предмета расчета). Максимальная длина 64 символов
400 1067 Наименование предмета расчета (Items.Label) не должно быть пустым или превышать длину в 128 символов
400 1068 Неверно указан номер предписания налогового органа для чека коррекции (тег 1179). Номер предписания не может быть пустым. Максимальная длина 32 символа.
400 1069 Количество кодов маркировки превышает допустимое количество (128) в рамках одного чека
400 1070 Отсутствует касса с ФФД 1.2 для пробития чека с этими данными
400 1071 Отсутствует касса с ФФД ниже 1.2 для пробития чека с данными по кодам маркировке в MarkingCode/MarkingCodeStructured
400 1085 Ошибка значений входных параметров для пробития на кассе Ferma®

В таблице 4.2. перечислены сообщения об ошибках и описания сообщений, полученных в ответе на запрос.

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

Сообщение об ошибке Код ошибки Описание ошибки
CASHBOX_NOT_FISCALIZED 1070 Касса не фискализирована. Перейдите в личный кабинет OFD.ru и завершите регистрацию кассы разделе Ferma®
CASHBOX_REQUIRES_REGISTRATION_COMPLETION 1071 По кассе требуется завершение регистрации в ФНС. По кассе Ferma® регистрация в ФНС не завершена. Перейдите в личный кабинет OFD.ru, завершите регистрацию кассы разделе Ferma®
CASHBOX_TO_ARCHIVING 1072 Касса подготавливается к архивации. Необходима замена фискального накопителя. Перейдите в личный кабинет OFD.ru, проверьте наличие предоплаченных фискальных документов
CASHBOX_ARCHIVED 1073 Касса заархивирована. Необходима замена фискального накопителя. Перейдите в личный кабинет OFD.ru, проверьте наличие предоплаченных фискальных документов
CASHBOX_REREGISTRATION_REQUIRED 1074 По кассе требуется завершение перерегистрации в ФНС. По кассе Ferma® перерегистрация в ФНС не завершена. Перейдите в личный кабинет OFD.ru, подпишите КЭПом заявление на перерегистрацию кассы
CASHBOX_REQUIRES_REREGISTRATION_COMPLETION 1076 По кассе требуется завершение перерегистрации. По кассе Ferma® перерегистрация в ФНС не завершена
CASHBOX_REMOVED_FROM_BALANCING 1075 Касса убрана из балансировки. По кассе проводятся временные технические работы
CASHBOX_WITHDRAWN_FOR_NONPAYMENT 1079 Касса выведена за неуплату. Не оплачена касса Ferma®. Оплатите услуги Ferma®

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

5.1. Описание

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

5.2. Тестовое API Ferma®

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

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

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

  • Логин - fermatest2;
  • Пароль - Go2999483Mb.

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

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

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

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

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

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

  1. перейти в раздел «Кассы»;
  2. в разделе присутствуют две кассы (fermatest1 с ФФД 1.1 и Fermatest2 с ФФД 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.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. Код и описания ошибок дополнена возможными ошибками.

Версия 2.42
Выпущена 15 октября 2021 г.

  • Дополнена таблица 3.3 Параметры элементов структуры «CustomerReceipt»
  • Дополнена таблица 3.4 Параметры элементов структуры «Items» ТЕГ 1059
  • Добавлена таблица 4.2. Ошибка и описание ошибки
  • Добавлено описание параметра «IndustryItemRequisite» (тег 1260) в таблице 3.4. «Параметры элементов структуры «Items» ТЕГ 1059»

Версия 2.43
Выпущена 18 ноября 2021 г.

  • Добавлен раздел 3.2. Передача кода маркировки API Ferma®
  • Добавлен раздел 3.2.1. Передача кода маркировки в ФФД 1.2 в API Ferma®
  • Добавлен раздел 3.1.11. Формирование кассового чека с большим количеством позиций

Версия 2.44
Выпущена 15 декабря 2021 г.

  • Добавлено описание параметра CheckMcMode в таблице 3.3.

Версия 2.45
Выпущена 17 января 2022 г.

  • Изменено описание параметра DateTime

Версия 2.46
Выпущена 20 января 2022 г.

  • Измены примеры значения в структуре параметра «MarkingCodeData»
  • Исправлена общая схема запроса для API Ferma®
  • Добавлено важное условие для параметра «Amount»

Версия 2.47
Выпущена 27 января 2022 г.

  • В разделе 3.2.1. изменена информация о передачи кода маркировки

Версия 2.48
Выпущена 2 февраля 2022 г.

  • В разделе 3.1.1. в таблице 3.4. добавлено описание нового параметра «Excise»
  • В разделе 3.1.1. в таблице 3.5. для параметра «Type» добавлены описания новых значений
  • В разделе 3.1.7. добавлено описание по новым значениям
  • В разделе 3.1.12. добавлен пример чека с параметром «Excise»
  • В разделе 3.2. добавлена информация
  • в разделе 3.1.1. добавлено дополнительная информация по параметру «PlannedStatus»

Версия 2.49
Выпущена 9 февраля 2022 г.

  • Исправлены примеры кодов маркировки
  • Добавлен раздел 3.8.
  • Добавлено описание о параметре «CallbackUrl» в разделе 3.1.
  • Изменены описания по всему документу параметров «InvoiceId» и «ReceiptId»

Версия 2.50
Выпущена 18 февраля 2022 г.

  • Изменена Общая JSON-схема
  • Исправлены примеры в разделе 3.2.5.
  • Исправлены примеры в разделе 3.3

Версия 2.51
Выпущена 29 марта 2022 г.

  • Добавлен раздел 3.3.3.

Версия 2.52
Выпущена 29 апреля 2022 г.

  • Добавлена таблица 3.7
  • Добавлено описание ошибки 1085

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

  • Обновлена информация по всему документу

Версия 2.54
Выпущена 27 октября 2022 г.

  • Добавлена таблица «Список форматов КМ с признаком требования проверки КМ в честном знаке»

Версия 2.55
Выпущена 03 ноября 2022 г.

  • В разделе 3.3.1. Передача кода маркировки в ФФД 1.2 в API Ferma® дополнена информация по работе с Тегом 1192

Версия 2.56
Выпущена 15 ноября 2022 г.

  • Добавлен новый раздел 3.10. Описание запроса на получение информации об очереди

Версия 2.57
Выпущена 26 декабря 2022 г.

  • Обновлена информация в разделе тестирование.

Версия 2.58
Выпущена 18 мая 2023 г.

  • Удален раздел 3.3.2. Передача кода маркировки для версии ФФД 1.1/1.05
  • Добавлен новый раздел «Описание работы параметра повторной проверка КМ в API Ferma®»

Версия 2.59
Выпущена 21 июня 2023 г.
Исправлено описание формата даты и время для параметра «ExpirationDateUtc»

Версия 2.60
Выпущена 23 ноября 2023 г.
Прекращена поддержка ФФД 1.05

Версия 2.61
Выпущена 14 декабря 2023 г.
Удалены неиспользуемые параметры структуры MarkingCodeStructured для пробития чека с данными по кодам маркировки

Версия 2.62
Выпущена 22 января 2024 г.
Удалены параметры «Vat18» — НДС 18%, «CalculatedVat18118» — вычисленный НДС 18% от 118% суммы и «Nds18_TotalSumm»

Версия 2.63
Выпущена 11 марта 2024 г.
В пункте 3.7. Запрос реестра кассовых чеков с детальной информацией по чеку добавлено описание работы с параметрами dateFrom и dateTo в теле запроса

Версия 2.64
Выпущена 10 июня 2024 г.
Добавлены уточнения об обязательности параметра Measure в случае с ФФД 1.2 и обновлены примеры использования (для пунктов 3.2.1 и 3.2.5)

Версия 2.65
Выпущена 25 июня 2024 г.
Добавлено замечание о требовании указания «Content-Type: application/json» в заголовке запроса

Версия 2.66
Выпущена 27 июня 2024 г.
Добавлены уточнения использования доступных значений параметра «PaymentType» в разделах 3.1.4. и 3.2.5.

1)
Значение параметра «AuthToken» представлено в строковом виде, представляет собой 32-значную последовательность шестнадцатеричных цифр, используется для аутентификации в запросах сервиса Ferma®
2)
Значение параметра «ExpirationDateUtc» представлено в строковом виде в формате даты и времени (UTC+3, МОСКОВСКОЕ ВРЕМЯ).
Время представлено в формате «ГГГГ-ММ-ДДTчч:мм:сс». Формат даты и времени соответствует международному стандарту ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601).
Формат представления времени выводится без смещения часовых поясов (Time Zone Offset) и интервалов. Формат даты и времени имеет следующую структуру:
ГГГГ - год;
ММ - месяц;
ДД - день;
T - используется как разделитель даты и времени;
чч - часы;
мм - минуты;
сс - секунды.
3) , 6) , 22) , 28) , 32) , 46)
Параметр специальной части заголовка фискального документа
4) , 7) , 23) , 29) , 33) , 47)
Признак обязательности параметра в запросе
5)
Параметр «Cashier» не обязательно передавать в запросе. Если вы передаете параметр «Cashier» без информация о кассире, то по умолчанию будет использована информация о кассире из настройки кассы. Если в настройках кассы отсутствует информация о кассире, параметр «Cashier» в запросе не будет передаваться.
8) , 9)
Здесь должно быть заполнено хотя бы одно поле с указанием адресата доставки чека: «Email» и «Phone»; в случае заполнения происходит отправка чека; если указан и адрес e-mail и номер телефона, чек отправляется по электронной почте. Для того, чтоб была возможна отправка смс, нужно приобрести пакет смс в личном кабинете.
10) , 27) , 34)
Если параметр передается только в составе чека, и не передано в составе позиции (Items), то данные из PaymentAgentInfo копируются на все позиции. Если параметр передается в составе чека и в составе Items, то на параметр устанавливаются данные из позиции. Если при пробитии чека в составе позиции передается PaymentAgentInfo, то и в составе чека должно быть PaymentAgentInfo с заполненным AgentType.
11) , 19) , 20) , 35) , 43) , 44) , 50) , 57)
Заполняется для всех типов агентов
12) , 13) , 14) , 15) , 16) , 36) , 37) , 38) , 39) , 40)
Заполняется при выборе BANK_PAYMENT_AGENT или BANK_PAYMENT_SUBAGENT
17) , 21) , 41) , 45)
Заполняется при выборе BANK_PAYMENT_AGENT, BANK_PAYMENT_SUBAGENT, PAYMENT_AGENT или PAYMENT_SUBAGENT
18) , 42)
Заполняется при выборе PAYMENT_AGENT или PAYMENT_SUBAGENT
24) , 25) , 51) , 52) , 53) , 54)
Новые значения вида вычисляемого НДС (значения “Vat20” и “CalculatedVat20120”) будут доступны с 01.01.2019, 00:00:01 московского времени.
26) , 56)
Цифровой код страны происхождения товара в соответствии с Общероссийским классификатором стран мира: https://ru.wikipedia.org/wiki/%D0%9E%D0%B1%D1%89%D0%B5%D1%80%D0%BE%D1%81%D1%81%D0%B8%D0%B9%D1%81%D0%BA%D0%B8%D0%B9_%D0%BA%D0%BB%D0%B0%D1%81%D1%81%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%82%D0%BE%D1%80_%D1%81%D1%82%D1%80%D0%B0%D0%BD_%D0%BC%D0%B8%D1%80%D0%B0
30) , 48)
Тег необходим при реализации товаров с КМ поштучно или единицами.
31) , 49)
Параметр «Fractional» используется только со значением «PIECE» в параметре «Measure»
55)
Шестнадцатеричная система счисления
58) , 59) , 60)
/n - префикс маски подсети
61) , 62) , 63) , 64)
дату и время в формате UTC+3
65)
Его вы используете для подстановки в API-запросы вместо ferma.ofd.ru.