Помогаем продавать
Войти в ЛК

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

Версия 2.33 от 30.11.2020 Открыть pdf-файл

Введение

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

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

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

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

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

Здесь:

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


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

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

Здесь:

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

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

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

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

Вид запроса:

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

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

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

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

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

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

Здесь:

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

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

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

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

3.1. Формирование кассового чека

Вид запроса:

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

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

{
    "Request": {
        "Inn": "0123456789",
        "Type": "Income",
        "InvoiceId": "15975364820",
        "LocalDate": "2020-01-24T14:13:24",
        "CustomerReceipt": {
            "TaxationSystem": "Common",
            "Email": "example@mail.ru",
            "Phone": "+79000000000",
            "PaymentType": 1,
            "KktFA": true,
            "AutomatNumber": "123456",
            "BillAddress": "Москва, ул. Ленина, 77",
            "CustomUserProperty": {
                "Name": "название доп. атрибута",
                "Value": "значение доп. атрибута"
            },
            "PaymentAgentInfo": {
                "AgentType": "BANK_PAYMENT_AGENT",
                "TransferAgentPhone": "+79000000001",
                "TransferAgentName": "наименование оператора перевода",
                "TransferAgentAddress": "адрес оператора перевода",
                "TransferAgentINN": "1234567890",
                "PaymentAgentOperation": "операция платежного агента",
                "PaymentAgentPhone": "+79000000002",
                "ReceiverPhone": "+79000000003",
                "SupplierInn": "012345678901",
                "SupplierName": "Иван Иванов",
                "SupplierPhone": "+79000000004"
            },
            "CorrectionInfo": {
                "Type": "SELF",
                "Description": "Неприменение ККТ",
                "ReceiptDate": "20.07.18",
                "ReceiptId": "123456"
            },
            "ClientInfo": {
                "Name": "Иванов Иван Иванович",
                "Inn": "450148839601"
            },
            "Items": [
                {
                    "Label": "Мороженое",
                    "Price": 5,
                    "Quantity": 50,
                    "Amount": 250,
                    "Vat": "Vat0",
                    "MarkingCode": "000559D39E7F197241424331323334",
                    "MarkingCodeStructured": {
                        "Type": "MEDICINES",
                        "Gtin": "77777777777777",
                        "Serial": "RXWWWRRRRRRRR"
                    },
                    "PaymentMethod": 3,
                    "OriginCountryCode": "398",
                    "CustomsDeclarationNumber": "ТаможняДала Добро №1/#15",
                    "PaymentType": 4,
                    "PaymentAgentInfo": {
                        "AgentType": "BANK_PAYMENT_AGENT",
                        "TransferAgentPhone": "+79000000001",
                        "TransferAgentName": "наименование оператора перевода",
                        "TransferAgentAddress": "адрес оператора перевода",
                        "TransferAgentINN": "1234567890",
                        "PaymentAgentOperation": "операция платежного агента",
                        "PaymentAgentPhone": "+79000000002",
                        "ReceiverPhone": "+79000000003",
                        "SupplierInn": "012345678901",
                        "SupplierName": "Иван Иванов",
                        "SupplierPhone": "+79000000004"
                    },
                },
                ...
            ],
            "PaymentItems": [
                {
                    "PaymentType": 0,
                    "Sum": 0.0
                },
                ...
            ],
            "AdditionalReceiptProp": "1234567890"
        },
        "Cashier": {
            "Name": "Фёдорова Нина Тихомирова",
            "Inn": "991133557"
        }
    }
}

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

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

Параметр Вложенные поля Формат значения Описание Тег 4)
Inn Строка ИНН лица, от имени которого генерируется кассовый документ (чек) 1018
Type Строка Тип формируемого документа (чек), см. п. 3.1.2 1054
InvoiceId Строка Идентификатор счета, на основании которого генерируется чек. Важно! Если требуется перепробить чек (в случае ошибок), нельзя изменять InvoiceId. Иначе возможно задвоение чека.
LocalDate Строка, описывающая момент времени (дату и время) Локальная дата и время чека 1012
CustomerReceipt Структура Содержимое клиентского чека. Параметры элементов структуры CustomerReceipt приведены в таблице 1.1
Cashier 5) Структура Информация о кассире
Name Строка ФИО кассира 1021
Inn Строка ИНН кассира 1203

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

Параметр Вложенные поля Формат значения Описание Тег 6)
TaxationSystem Строка Система налогообложения, см. п. 3.1.3 1055
Email 7) Строка Адрес электронной почты клиента 1008
Phone 8) Строка Контактный телефон клиента 1008
PaymentType Число Признак предмета расчета для всего чека. Важно! Если в данном поле значение клиентом не указано, то используется значение по умолчанию, которое берется из базы данных. Список возможных значений перечислен в п. 3.1.4 1212
KktFA Логическое выражение Если используется касса ФА в сервисе Ferma необходимо установить значение true. В противном случае значение - false. В каких случаях использовать кассу ФА описано в 3.1.8
AutomatNumber Строка Номер автоматического устройства 1036
BillAddress Строка Адрес места осуществления расчетов 1187
CustomUserProperty Структура Дополнительный реквизит пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты 1084
Name Строка Наименование дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты 1085
Value Строка Значение дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты 1086
PaymentAgentInfo 9) Структура Структура, содержащая данные платежного агента 1223
AgentType 10) Строка Тип (признак) платежного агента. Возможные значения:
BANK_PAYMENT_AGENT — банковский платежный агент;
BANK_PAYMENT_SUBAGENT — банковский платежный субагент;
PAYMENT_AGENT — платежный агент;
PAYMENT_SUBAGENT — платежный субагент;
CONFIDANT — поверенный;
COMMISSIONER — комиссионер;
AGENT — агент.
1057
TransferAgentPhone 11) Строка Телефон оператора по переводу денежных средств 1075
TransferAgentName 12) Строка Имя агента 1026
TransferAgentAddress 13) Строка Адрес агента 1005
TransferAgentINN 14) Строка ИНН агента 1016
PaymentAgentOperation 15) Строка Операция платежного агента 1044
PaymentAgentPhone 16) Строка Телефон платежного агента 1073
ReceiverPhone 17) Строка Телефон потребителя 1074
SupplierInn 18) Строка ИНН поставщика 1226
SupplierName 19) Строка Наименование поставщика 1225
SupplierPhone 20) Строка Телефон поставщика 1171
CorrectionInfo Структура Структура, описывающая информацию по чеку коррекции. Внимание! Структура присутствует в данных только в случае генерации чека коррекции. Для генерации обычного чека данная структура не нужна.
Type Строка Тип коррекции:
SELF — коррекция производится самостоятельно;
INSTRUCTION — коррекция производится по предписанию
1173
Description Строка Описание коррекции и причин коррекции 1177
ReceiptDate Строка Дата пробития чека, к которому применяется чек коррекции. В формате «ДД.ММ.ГГ», где ДД — день, ММ — месяц, ГГ — год. 1178
ReceiptId Строка Идентификатор чека, к которому применяется чек коррекции 1179
ClientInfo Структура Данные о покупателе
Name Строка ФИО и паспортные данные покупателя или наименование организации, если клиент юр. лицо. Не более 256 символов в поле 1227
Inn Строка ИНН покупателя. Длина 10-12 цифр 1228
Items Структура Товарные позиции, приобретаемые клиентом. Параметры элементов структуры Items приведены в таблице 1.3 1059
PaymentItems Структура Суммы по типам оплат
PaymentType Число Тип оплаты:
0 – наличными;
1 – безналичными;
2 – предварительная оплата (аванс);
3 – предварительная оплата (кредит);
4 – иная форма оплаты.

1031
1081
1215
1216
1217
Sum Число с точкой Сумма по типу, в рублях 1020
AdditionalReceiptProp Строка Дополнительный реквизит чека (БСО). Применяется в составе кассового чека (БСО). Максимальная длина - 16 символов. 1192

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

Параметр Вложенные поля Формат значения Описание Тег 21)
Label Строка Наименование предмета расчета.
Важно! Если параметр PaymentType в составе структур Items имеет значение «15 — о внереализационном доходе», то в данном параметре должно быть указано числовое значение от 1 до 31 из п. 3.1.5.
Если параметр PaymentType в составе структур Items имеет значение «16 — о страховых взносах», то в данном параметре должно быть указано числовое значение от 26 до 31 из п. 3.1.5.
1030
Price Число с точкой Цена товарной позиции в рублях 1079
Quantity Число с точкой Количество товара в товарной позиции 1023
Amount Число с точкой Общая стоимость товара в товарной позиции в рублях 1081
Vat Строка Вид вычисляемого НДС см. п 3.1.1. Обязательное поле для чеков коррекции, если Items не равен NULL. 1199
MarkingCode Строка Код маркировки товарной позиции. Передается Hex22) представление кода маркировки.
Является аналогом «MarkingCodeStructured». При использовании данного параметра нельзя использовать «MarkingCodeStructured»
1162
MarkingCodeStructured Структура Код маркировки товарной позиции. Передается структура, содержащая информацию о маркировке товарных позиций.
Является аналогом «MarkingCode». При использовании данного параметра нельзя использовать «MarkingCode»
1162
Type Строка Тип товарной позиции. Возможные значения: MEDICINES, TOBACCO, SHOES
Gtin Строка Идентификационный номер GTIN (артикул)
Serial Строка Серийный номер товара
PaymentMethod Число Признак способа расчета:
1 – предоплата 100%;
2 – предоплата;
3 – аванс;
4 – полный расчет;
5 – частичный расчет;
6 – передача в кредит;
7 – оплата в кредит.
1214
OriginCountryCode Строка Код страны происхождения товара. Не более 3 цифр. 23) 1230
CustomsDeclarationNumber Строка Номер таможенной декларации. Не более 32 символов 1231
PaymentType Число Признак предмета расчета для конкретной позиции в чеке. Если значение отсутствует, берется значение для всего чека. Возможные значения перечислены в п. 3.1.4 1212
PaymentAgentInfo 24) Структура Структура, содержащая данные платежного агента 1223
AgentType 25) Строка Тип (признак) платежного агента. Возможные значения:
BANK_PAYMENT_AGENT — банковский платежный агент;
BANK_PAYMENT_SUBAGENT — банковский платежный субагент;
PAYMENT_AGENT — платежный агент;
PAYMENT_SUBAGENT — платежный субагент;
CONFIDANT — поверенный;
COMMISSIONER — комиссионер;
AGENT — агент.
1057
TransferAgentPhone 26) Строка Телефон оператора по переводу денежных средств 1075
TransferAgentName 27) Строка Имя агента 1026
TransferAgentAddress 28) Строка Адрес агента 1005
TransferAgentINN 29) Строка ИНН агента 1016
PaymentAgentOperation 30) Строка Операция платежного агента 1044
PaymentAgentPhone 31) Строка Телефон платежного агента 1073
ReceiverPhone 32) Строка Телефон потребителя 1074
SupplierInn 33) Строка ИНН поставщика 1226
SupplierName 34) Строка Наименование поставщика 1225
SupplierPhone 35) Строка Телефон поставщика 1171

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

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

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

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

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

Параметр Формат значения Описание
ReceiptId Строка, содержащая UUID Идентификатор чека для дальнейшего запроса состояния

3.1.1. Возможные значения вида вычисляемого НДС (поле “Vat”)

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

3.1.2. Типы формируемых чеков (поле “Type”)

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

3.1.3. Возможные значения типа налогообложения (поле “TaxationSystem”)

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

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

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

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

3.1.5. Возможные значения наименования предмета расчета (Поле "Label")

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

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

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

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

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

  • «Не найдены данные компании с ИНН 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.1.8. Использование кассы ФА (поле “KktFA”)

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

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

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

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

{
    "Inn": "2465165753",
    "Type": "Income",
    "InvoiceId": "1",
    "CustomerReceipt": {
        "TaxationSystem": "SimpleIn",
        "Email": "example@yandex.ru",
        "Phone": "+79000000000",
        "InstallmentPlace": null,
        "InstallmentAddress": null,
        "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": 1.0,
                "Vat": "VatNo",
                "MarkingCodeStructured": null,
                "MarkingCode": null,
                "PaymentMethod": 3,
                "PaymentType": 4,
                "OriginCountryCode": "643",
                "CustomsDeclarationNumber": null,
                "PaymentAgentInfo": null
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

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

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

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

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

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

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

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

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

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

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

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

{
    "Inn": "089137465",
    "Type": "Income",
    "InvoiceId": "6f550fee-bbac-4445-bda1-e5111556fcc5",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@yahoo.ru",
        "Phone": "+79000000001",
        "InstallmentPlace": "108812, Московский, , п. Московский, здание офиса продаж, ",
        "InstallmentAddress": "108812, Московский, , п. Московский, здание офиса продаж, ",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo" : null,
        "Items": [
            {
                "Label": "Таблетки от кашля",
                "Price": 10.00,
                "Quantity": 1.0,
                "Amount": 10.00,
                "Vat": "VatNo",
                "MarkingCodeStructured": {
                    "Type": "MEDICINES",
                    "Gtin": "05995327115555",
                    "Serial": "RXFMY9PH7ZZZZ"
                },
                "PaymentMethod": 0,
                "PaymentType": 10
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

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

{
    "Inn": "0258469137",
    "Type": "Income",
    "InvoiceId": "6f290fee-bbac-1111-bda1-e1111116fcc1",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "InstallmentPlace": "108812, Московский, , п. Московский, здание офиса продаж, ",
        "InstallmentAddress": "108812, Московский, , п. Московский, здание офиса продаж, ",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": null,
        "ClientInfo" : null,
        "Items": [
            {
                "Label": "Таблетки от кашля",
                "Price": 10.00,
                "Quantity": 1.0,
                "Amount": 10.00,
                "Vat": "VatNo",
                "MarkingCode": "0003574EA75F63675258464D5939504837435A5057",
                "PaymentMethod": 0,
                "PaymentType": 10
            }
        ],
        "PaymentItems": null,
        "CustomUserProperty": null
    }
}

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

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

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

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

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

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

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

{
    "Inn": "1739284652",
    "Type": "IncomeCorrection",
    "InvoiceId": "2f222fee-bbac-4444-bda9-e9ce9999fcc9",
    "CustomerReceipt": {
        "TaxationSystem": "Common",
        "Email": "example@mail.ru",
        "Phone": "+79000000001",
        "InstallmentPlace": "108812, Московский, , п. Московский, здание офиса продаж, ",
        "InstallmentAddress": "108812, Московский, , п. Московский, здание офиса продаж, ",
        "AutomaticDeviceNumber": "46204",
        "PaymentType": 4,
        "PaymentAgentInfo": null,
        "CorrectionInfo": {
            "Type": "SELF",
            "Description": "Коррекция",
            "ReceiptDate": "12.06.2019",
            "ReceiptId": "123"
        },
        "ClientInfo": null,
        "Items": null,
        "PaymentItems": [
            {
                "PaymentType": 1,
                "Sum": 150.00
            }
        ],
        "Vat": "Vat20",
        "CustomUserProperty": null
    }
}

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

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

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

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

Вид запроса:

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

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

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

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

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

Параметр Вложенные поля Формат значения Описание
Request Структура Параметры запроса статуса кассового документа
ReceiptId Строка Идентификатор чека, полученный из запроса на формирование кассового документа
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.1

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

Параметр Вложенные поля Формат значения Описание
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.2.

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметр Формат значения Описание
ReceiptId Строка в формате UUID Идентификатор чека, полученный из запроса на формирование кассового документа
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,
                    "InstallmentPlace": null,
                    "InstallmentAddress": null,
                    "BillAddress": "Тестируем маркировку табака",
                    "KktFA": true,
                    "PaymentType": 4,
                    "PaymentAgentInfo": null,
                    "CorrectionInfo": null,
                    "ClientInfo": null,
                    "Items": [
                        {
                            "Label": "Табак с кодом маркировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": {
                                "markingCodeHex": "000346BD0CD0DC7152585757575252525252525252",
                                "codeCorrect": true,
                                "gtinHex": "46BD0CD0DC71",
                                "serialHex": "52585757575252525252525252",
                                "typeHex": "0003",
                                "Gtin": "77777777777777",
                                "Serial": "RXWWWRRRRRRRR",
                                "Type": "MEDICINES"
                            },
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        },
                        {
                            "Label": "Табак с кодом маркировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": {
                                "markingCodeHex": "000346BD0CD0DC7152585757575252525252525253",
                                "codeCorrect": true,
                                "gtinHex": "46BD0CD0DC71",
                                "serialHex": "52585757575252525252525253",
                                "typeHex": "0003",
                                "Gtin": "77777777777777",
                                "Serial": "RXWWWRRRRRRRS",
                                "Type": "MEDICINES"
                            },
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        },
                        {
                            "Label": "Табак с кодом ма12154215ркировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": {
                                "markingCodeHex": "000300000000000752585757575252525252525252",
                                "codeCorrect": true,
                                "gtinHex": "000000000007",
                                "serialHex": "52585757575252525252525252",
                                "typeHex": "0003",
                                "Gtin": "7",
                                "Serial": "RXWWWRRRRRRRR",
                                "Type": "MEDICINES"
                            },
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        },
                        {
                            "Label": "Табак с кодом марк2222ировки",
                            "Price": 1000.0,
                            "Quantity": 1.0,
                            "Amount": 1000.0,
                            "Vat": "Vat20",
                            "MarkingCodeStructured": null,
                            "MarkingCode": null,
                            "PaymentMethod": 4,
                            "PaymentType": 4,
                            "OriginCountryCode": null,
                            "CustomsDeclarationNumber": null,
                            "PaymentAgentInfo": null
                        }
                    ],
                    "PaymentItems": [
                        {
                            "PaymentType": 1,
                            "Sum": 4000.0
                        }
                    ],
                    "Vat": null,
                    "CustomUserProperty": null,
                    "AdditionalReceiptProp": null
                },
                "Cashier": {}
            }
        }
        ...
    ]
}

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

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

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

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

Параметр Вложенные поля Вложенные поля Формат значения Описание
cashboxInfoHolder Структура Информация о кассовом аппарате
checkNumInShift Число Номер чека в смене
shiftNum Число Номер смены
totalSum Число Общая сумма по чеку
cashboxType Число Тип кассы, на которой был сгенерирован чек
DeviceId Число Сервисный идентификатор устройства, на котором был сгенерирован чек
RNM Строка Регистрационный номер кассы
ZN Строка Заводской номер кассы
FN Строка Номер фискального накопителя
FDN Строка Номер фискального документа
FPD Строка Фискальный признак документа
Inn Строка ИНН лица, от имени которого был сгенерирован кассовый документ (чек)
Type Строка Типы сформированных чеков, см. п. 3.1.2.
InvoiceId Строка Идентификатор счета, на основании которого был сгенерирован чек
CustomerReceipt Структура Содержимое клиентского чека
TaxationSystem Строка Система налогообложения, см. п. 3.1.3.
Email Строка Адрес электронной почты клиента
Phone Строка Контактный телефон клиента
InstallmentPlace Строка Наименование места установки кассы. При использовании в Интернете указывается адрес(а) сайта(ов), при развозной торговле марка и номер транспортного средства.
InstallmentAddress Строка Место установки кассы
BillAddress Строка Адрес места осуществления расчетов
KktFA Логическое выражение Если используется касса ФА в сервисе Ferma необходимо установить значение true. В противном случае значение - fasle. В каких случаях использовать кассу ФА описано в 3.1.8
PaymentType Число Признак предмета расчета для всего чека. Список возможных значений перечислен в п. 3.1.4.
PaymentAgentInfo Структура Структура, содержащая данные платежного агента
AgentType Строка Тип (признак) платежного агента. Возможные значения:
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 приведены в таблице 4.3
PaymentItems Структура Суммы по типам оплат
PaymentType Число Тип оплаты:
0 – наличными;
1 – безналичными;
2 – предварительная оплата (аванс);
3 – предварительная оплата (кредит);
4 – иная форма оплаты.
Sum Число с точкой Сумма по типу, в рублях
Vat Строка Вид вычисляемого НДС см. п 3.1.1
CustomUserProperty Структура Дополнительный реквизит пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты
Name Строка Наименование дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты
Value Строка Значение дополнительного реквизита пользователя с учетом особенностей сферы деятельности, в которой осуществляются расчеты
AdditionalReceiptProp
Cashier Структура Информация о кассире
Name Строка ФИО кассира
Inn Строка ИНН кассира

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

Параметр Вложенные поля Формат значения Описание
Label Строка Наименование предмета расчета из п. 3.1.5.
Price Число с точкой Цена товарной позиции в рублях
Quantity Число с точкой Количество товара в товарной позиции
Amount Число с точкой Общая стоимость товара в товарной позиции в рублях
Vat Строка Вид вычисляемого НДС см. п 3.1.1.
MarkingCode Строка Код маркировки товарной позиции. Передается Hex38) представление кода маркировки.
Является аналогом «MarkingCodeStructured». При использовании данного параметра нельзя использовать «MarkingCodeStructured»
MarkingCodeStructured Структура Код маркировки товарной позиции. Передается структура, содержащая информацию о маркировке товарных позиций.
Является аналогом «MarkingCode». При использовании данного параметра нельзя использовать «MarkingCode»
markingCodeHex Строка Hex39) представление кода маркировки
codeCorrect Логическое выражение true - корректный код маркировки
false - некорректный код маркировки
gtinHex Строка GTIN (артикул) кода маркировки
serialHex Строка Серийный номер кода маркировки
typeHex Строка Тип товарной позиции маркировки
Type Строка Тип товарной позиции. Возможные значения: MEDICINES, TOBACCO, SHOES
Gtin Строка Идентификационный номер GTIN (артикул) товара
Serial Строка Серийный номер товара
PaymentMethod Число Признак способа расчета:
1 – предоплата 100%;
2 – предоплата;
3 – аванс;
4 – полный расчет;
5 – частичный расчет;
6 – передача в кредит;
7 – оплата в кредит.
PaymentType Число Признак предмета расчета для конкретной позиции в чеке. Если значение отсутствует берется значение для всего чека. Возможные значения перечислены в п. 3.1.4.
OriginCountryCode Число Код страны происхождения товара. Не более 3 цифр. 40)
CustomsDeclarationNumber Строка Номер таможенной декларации. Не более 32 символов
PaymentAgentInfo Структура Структура, содержащая данные платежного агента
AgentType Строка Тип (признак) платежного агента. Возможные значения:
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» при получении ответа с ошибкой приведены в таблице 4.4.

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

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

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

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

Вид запроса:

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

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

Успешным ответом на запрос возвращается структура данных 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.5. Запрос реестра кассовых чеков с детальной информацией по чеку

Вид запроса:

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

Здесь:

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

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

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

   ......

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

4. Коды ошибок

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) cовместно с флагом KktFA = false

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

5.1. Описание

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

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

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

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

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

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

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

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

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

  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 добавлены новые коды ошибок.
1)
Время, которое токен будет активен - 24 часа.
2)
Данный формат описан в стандарте ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Здесь используется только формат представления времени без задания смещения часовых поясов (Time Zone Offset) и интервалов.
3)
Далее в запросах параметр кода авторизации не указывается
4) , 6) , 21)
Атрибут, указывающий содержание специфической части заголовка фискального документа в электронной форме, позволяющий идентифицировать фискальный документ по значению этого атрибута в соответствии с ФФД
5)
Структура не обязательна. Если информация о кассире не передается в API-запросе, то будет использована дефолтная информация, заданная в OFD.ru. Если дефолтная информация не задана, то информация о кассире не будет передаваться.
7) , 8)
Здесь должно быть заполнено хотя бы одно поле с указанием адресата доставки чека: «Email» и «Phone»; в случае заполнения происходит отправка чека; если указан и адрес e-mail и номер телефона, чек отправляется по электронной почте. Для того, чтоб была возможна отправка смс, нужно приобрести пакет смс в личном кабинете.
9) , 24)
Если параметр передается только в составе чека, и не передано в составе позиции (Items), то данные из PaymentAgentInfo копируются на все позиции. Если параметр передается в составе чека и в составе Items, то на параметр устанавливаются данные из позиции. Если при пробитии чека в составе позиции передается PaymentAgentInfo, то и в составе чека должно быть PaymentAgentInfo с заполненным AgentType.
10) , 18) , 19) , 25) , 33) , 34)
Заполняется для всех типов агентов
11) , 12) , 13) , 14) , 15) , 26) , 27) , 28) , 29) , 30)
Заполняется при выборе BANK_PAYMENT_AGENT или BANK_PAYMENT_SUBAGENT
16) , 20) , 31) , 35)
Заполняется при выборе BANK_PAYMENT_AGENT, BANK_PAYMENT_SUBAGENT, PAYMENT_AGENT или PAYMENT_SUBAGENT
17) , 32)
Заполняется при выборе PAYMENT_AGENT или PAYMENT_SUBAGENT
22) , 38) , 39)
Шестнадцатеричная система счисления
23) , 40)
Цифровой код страны происхождения товара в соответствии с Общероссийским классификатором стран мира: 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
36) , 37)
Новые значения вида вычисляемого НДС (значения “Vat20” и “CalculatedVat20120”) будут доступны с 01.01.2019, 00:00:01 московского времени.
41)
Его вы используете для подстановки в API-запросы вместо ferma.ofd.ru.