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

Конвертер программного интерфейса приложений (API) для «АТОЛ Онлайн»

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

Введение

Документ описывает сценарий использования программного интерфейса приложений (API) сервиса «АТОЛ Онлайн» для информационной системы «Ferma».

1. Общая информация по API

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

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

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

--- BEGIN ---
POST https://ferma-at.ofd.ru/possystem/v1/getToken
Content-Type: application/json; charset=utf-8
{"login": "12345","pass": "56789"}
--- END ---

В данном запросе присутствуют параметры: login – «12345» и pass – «56789»; они задаются как значения в JSON-структуре внутри запроса.
login - имя пользователя, которое можно получить в личном кабинете клиента в разделе «Ferma» после покупки кассы Ferma либо у вашего менеджера. Максимальная длина строки – 100 символов.
pass - пароль, который можно получить в личном кабинете клиента в разделе «Ferma» после покупки кассы Ferma либо у вашего менеджера.

Доступен второй вариант получения кода авторизации с помощью метода GET. API-запрос имеет вид:

GET https://ferma-at.ofd.ru/possystem/v1/getToken?login=Login1&pass=Password1

В этом примере параметры login и pass передаются в строке самого API-запроса.

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

{
    "error":null,
    "token":"fj45u923j59ju42395iu9423i59243u0",
    "timestamp":"30.11.2017 17:58:53"
}

Здесь параметр error - ошибка, если параметр пустой (null), значит запрос был успешно выполнен.
token - код авторизации: строка символов, представляет собой 32-значную последовательность шестнадцатеричных цифр, используемую для повторной аутентификации.
timestamp – строка, описывающая момент времени (дату и время), когда был получен token. Время, которое токен будет активен - 24 часа.
Момент времени задается в формате «ДД-ММ-ГГГГ чч:мм:сс»; здесь
ДД – день даты 2 цифры,
ММ – месяц даты, 2 цифры,
ГГГГ – год даты, 4 цифры,
чч – часы, 2 цифры,
мм – минуты, 2 цифры,
сс – секунды, 2 цифры.

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

{
    "error":{
        "error_id":"4475d6d8d-844d-4d05-aa8b-e3dbdf3defd5",
        "code":12,
        "text":"Неверный логин или пароль",
       "type":"system"
    },
    "timestamp":"15.02.2018 13:00:31"
}

Здесь параметр error - массив данных, содержащий информацию об ошибке.
error_id - уникальный идентификатор ошибки.
code - код ошибки.
text - тестовое сообщение ошибки.
type - тип ошибки.
timestamp – строка, описывающая момент времени (дату и время), когда был получена ошибка.

Доступ к кассам по полученному параметру “token” происходит в соответствии с правами доступа, заданными для пользователя, чьи имя и пароль были использованы в процессе генерации параметра “token”. Права пользователя могут быть заданы одновременно для ЛКК нескольких юридических лиц, при этом функции описываемого здесь программного интерфейса приложений (API), связанные со сбором данных по ККТ будут возвращать данные только по тем единицам ККТ, доступ к которым разрешен согласно используемому значению параметра “token”.
Пример запроса с использованием кода авторизации:

GET https://ferma-at.ofd.ru/possystem/v1/<group_code>/<operation>?token=Code1

Здесь:
Code1 – действующий код авторизации, полученный в результате запроса авторизации.
group_code: идентификатор группы ККТ:

  • параметр можно посмотреть в ЛКК Ferma в виджете «Реквизиты доступа»;
  • для тестовой среды параметр равен 1.

3. Создание чеков

Запрос на создание чеков с использованием конвертера «АТОЛ Онлайн»:

POST https://ferma-at.ofd.ru/possystem/v1/<group_code>/<operation>

Здесь:
group_code: идентификатор группы ККТ:

  • параметр можно посмотреть в ЛКК Ferma в виджете «Реквизиты доступа»;
  • для тестовой среды параметр равен 1.

operation: тип операции, которая должна быть выполнена. Возможные типы операции:

  • sell - чек «Приход»;
  • sell_refund - чек «Возврат прихода»;
  • sell_correction - чек «Коррекция прихода»;
  • buy - чек «Расход»;
  • buy_refund - чек «Возврат расхода»;
  • buy_correction - чек «Коррекция расхода».

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

{
    "external_id": "12345",
    "receipt": {
        "client": {
            "email": "client@mail.ru",
            "phone": "+79000000001",
            "name": "ИП Долговязов А.А.",
            "inn": "000000001"
        },
        "company": {
            "email": "company@mail.ru",
            "sno": "envd",
            "inn": "00000000002",
            "payment_address": "https://magazin.ru/"
        },
        "agent_info": {
            "type": "bank_paying_subagent",
            "paying_agent": {
                "operation": "sell",
                "phones": [
                    "+79000000002",
                    "+79000000003"
                ]
            },
            "receive_payments_operator": {
                "phones": [
                    "+79000000004",
                    "+79000000005"
                ]
            },
            "money_transfer_operator": {
                "phones": [
                    "+79000000006",
                    "+79000000007"
                ],
                "name": "наименование оператора перевода",
                "address": "адрес оператора перевода",
                "inn": "00000000003"
            },
            "supplier_info": {
                "phones": [
                    "+79000000008",
                    "+79000000009"
                ]
            }
        },
        "items": [
            {
                "name": "колбаса Клинский Брауншвейгская с/к в/с ",
                "price":  1000.00,
                "quantity": 0.3,
                "sum": 300.00,
                "measurement_unit": "кг",
                "payment_method": "full_payment",
                "payment_object": "commodity",
                "nomenclature_code": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
                "vat": {
                    "type": "vat20",
                    "sum": 60.0
                },
                "agent_info": {
                    "type": "bank_paying_subagent",
                    "paying_agent": {
                        "operation": "sell",
                        "phones": [
                            "+79000000002",
                            "+79000000003"
                        ]
                    },
                    "receive_payments_operator": {
                        "phones": [
                            "+79000000004",
                            "+79000000005"
                        ]
                    },
                    "money_transfer_operator": {
                        "phones": [
                            "+79000000006",
                            "+79000000007"
                        ],
                        "name": "наименование оператора перевода",
                        "address": "адрес оператора перевода",
                        "inn": "00000000003"
                    },
                    "supplier_info": {
                        "phones": [
                            "+79000000008",
                            "+79000000009"
                        ],
                        "name": "наименование поставщика",
                        "inn": "000000004"
                    },
                    "user_data": null,
                    "excise": 0.0,
                    "country_code": "112",
                    "declaration_number": "ТаможняДала Добро №1/#15"
                }
            }
        ],
        "payments": [
            {
                "type": 1,
                "sum": 300.0
            }
        ],
        "vats": [
            {
                "type": "vat20",
                "sum": 60.0
            }
        ],
        "total": 300.0,
        "additional_check_props": "",
        "cashier": "Романова Александра Георгиевна",
        "additional_user_props": {
            "name": "",
            "value": ""
        }
    },
    "service": {
        "callback_url": "https://testtest.ru"
    },
    "timestamp":"31.03.20 12:25:00"
}

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

Таблица 1. Параметры структуры данных запроса на Запрос на создание чеков с использованием конвертера «АТОЛ Онлайн»

Параметр Формат значения Описание Тег
external_id Строка Уникальный идентификатор документа. Если данный external_id известен системе, будет возвращен UUID, ранее присвоенный этому чеку, иначе чек добавится в систему с присвоением нового UUID.
receipt Структура Структура чека
client Структура Информация о покупателе
email1) Строка Электронная почта покупателя 1008
phone2) Строка Телефон покупателя 1008
name Строка Наименование покупателя 1227
inn Строка ИНН покупателя 1228
company Структура Информация о компании
email Строка Электронная почта компании 1117
sno Строка Система налогообложения:
«osn» – общая СН;
«usn_income» – упрощенная СН (доходы);
«usn_income_outcome» – упрощенная СН (доходы минус расходы);
«envd» – единый налог на вмененный доход;
«esn» – единый сельскохозяйственный налог;
«patent» – патентная СН.
1055
inn Строка ИНН компании 1018
payment_address Строка Место рассчёта 1187
agent_info3) Структура Структура, содержащая данные платежного агента
type Строка Тип (признак) платежного агента. Возможные значения:
«bank_paying_agent» – банковский платежный агент.
«bank_paying_subagent» – банковский платежный субагент.
«paying_agent» - платежный агент.
«paying_subagent» – платежный субагент.
«attorney» – поверенный.
«commission_agent» - комиссионер.
«another» – другой тип агента.
1057
paying_agent Структура Информация о платежной агенте
operation Строка Наименование операции:
sell - чек «Приход»;
sell_refund - чек «Возврат прихода»;
sell_correction - чек «Коррекция прихода»;
buy - чек «Расход»;
buy_refund - чек «Возврат расхода»;
buy_correction - чек «Коррекция расхода».
1044
phones Массив данных Телефоны платежного агента 1073
receive_payments_operator Структура Информация об операторе по приему платежей
phones Массив данных Телефоны оператора по приему платежей 1074
money_transfer_operator Структура Информация об операторе перевода
phones Массив данных Телефоны оператора перевода 1075
name Строка Наименование оператора перевода 1026
address Строка Адрес оператора перевода 1005
inn Строка ИНН оператора перевода 1016
supplier_info4) Структура Информация о поставщике
phones Массив данных Телефоны поставщика 1171
items Массив структур Товарные позиции, приобретаемые клиентом
name Строка Наименование товара.
Важно! Если параметр payment_object имеет значение «nonoperating_gain» для данного предмета расчета, то поле «name» должно принимать значение от 1 до 25 из п. 3.1.
Если параметр payment_object имеет значение «insurance_premium» для данного предмета расчета, то «name» должно принимать значение от 26 до 31 из п. 3.1.
1030
price Число с точкой Цена в рублях:
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
Максимальное значение цены – 42 949 672.95.
1079
quantity Число с точкой Количество/вес:
- целая часть не более 5 знаков;
- дробная часть не более 3 знаков.
Максимальное значение – 99 999.999
1023
sum Число с точкой Сумма в рублях:
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
Максимальное значение – 42 949 672.95.
1043
measurement_unit Строка Единица измерения товара, работы, услуги, платежа, выплаты, иного предмета расчета. 1197
nomenclature_code Строка Код товара в шестнадцатеричном представлении с пробелами. 1162
payment_method 5) Строка Способ рассчёта. Список всех значение указан в п. 3.2 1214
payment_object Строка Признак предмета расчёта. Список всех значение указан в п. 3.3 1212
vat Структура Налог на позицию. Необходимо передать либо сумму налога на позицию, либо сумму налога на чек. Если будут переданы и сумма налога на позицию и сумма налога на чек, сервис учтет только сумму налога на чек.
type Строка Устанавливает номер налога в ККТ. Список всех значение указан в п. 3.4 1199
sum Число с точкой Сумма налога позиции в рублях:
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков
1200
agent_info 6) Структура Структура, содержащая данные платежного агента
type Строка Тип (признак) платежного агента. Возможные значения:
«bank_paying_agent» – банковский платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом.
«bank_paying_subagent» – банковский платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным субагентом.
«paying_agent» - платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным агентом.
«paying_subagent» – платежный субагент. Оказание услуг покупателю (клиенту)nпользователем, являющимся платежным субагентом.
«attorney» – поверенный. Осуществление расчета с покупателем (клиентом) пользователем, являющимся поверенным.
«commission_agent» - комиссионер. Осуществление расчета с покупателем (клиентом) пользователем, являющимся комиссионером.
«another» – другой тип агента. Осуществление расчета с покупателем (клиентом) пользователем, являющимся агентом и не являющимся банковским платежным агентом (субагентом), платежным агентом (субагентом), поверенным, комиссионером.
1222
paying_agent Структура Информация о платежной агенте
operation Строка Наименование операции:
sell - чек «Приход»;
sell_refund - чек «Возврат прихода»;
sell_correction - чек «Коррекция прихода»;
buy - чек «Расход»;
buy_refund - чек «Возврат расхода»;
buy_correction - чек «Коррекция расхода».
1044
phones Массив данных Телефоны платежного агента 1073
receive_payments_operator Структура Информация об операторе по приему платежей
phones Массив данных Телефоны оператора по приему платежей 1074
money_transfer_operator Структура Информация об операторе перевода
phones Массив данных Телефоны оператора перевода 1075
name Строка Наименование оператора перевода 1026
address Строка Адрес оператора перевода 1005
inn Строка ИНН оператора перевода 1016
supplier_info 7) Структура Информация о поставщике
phones Массив данных Телефоны поставщика 1171
name Строка Наименование поставщика 1225
inn Строка ИНН поставщика 1226
user_data Строка Дополнительный реквизит предмета расчета 1191
excise Число с точкой Сумма акциза в рублях
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков;
- значение не может быть отрицательным.
1229
country_code Строка Цифровой код страны происхождения товара. Если переданный код страны происхождения имеет длину меньше 3 цифр, то он дополняется справа пробелами 1230
declaration_number Строка Номер таможенной декларации. Не более 32 символов 1231
payments Массив структур Оплаты. Ограничение по количеству от 1 до 10.
type Целое число Вид оплаты. Возможные значения:
«0» – наличные;
«1» – безналичный;
«2» – предварительная оплата (зачет аванса и/или предыдущих платежей);
«3» – постоплата (кредит);
«4» – иная форма оплаты (встречное предоставление);
«5» – «9» – расширенные виды оплаты. Для каждого фискального типа оплаты можно указать расширенный вид оплаты.
1031 - сумма по чеку (БСО) наличными;
1081 - Сумма по чеку безналичными;
1215 - Сумма по чеку предоплатой (зачет аванса и/или предыдущих платежей);
1216 - Сумма по чеку постоплатой (кредит);
1217 - Сумма по чеку встречным представлением
sum Число с точкой Сумма к оплате в рублях:
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
vats Массив структур Налог на чек.
Необходимо передать либо сумму налога на позицию, либо сумму налога на чек. Если будет переданы и сумма налога на позицию и сумма налога на чек, сервис учтет только сумму налога на чек.
type Строка Устанавливает номер налога в ККТ. Список всех значение указан в п. 1.4 1105 - Сумма расчета по чеку без НДС;
1104 - Сумма расчета по чеку с НДС по ставке 0%;
1103 - Сумма НДС чека по ставке 10%;
1102 - Сумма НДС чека по ставке 20%;
1107 - Сумма НДС чека по расч. ставке 10/110;
1106 - Сумма НДС чека по расч. ставке 20/120.
sum Число с точкой Сумма налога позиции в рублях:
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
total Число с точкой Итоговая сумма чека в рублях с заданным в CMS округлением:
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
Сумму чека можно округлить, но не более, чем на 99 копеек.
При регистрации в ККТ происходит расчёт фактической суммы: суммирование значений sum позиций.
1020
additional_check_props Строка Дополнительный реквизит чека. Максимальная длина строки – 16 символов. 1192
cashier Строка ФИО кассира. Максимальная длина строки – 64 символа. 1021
additional_user_props Структура Дополнительный реквизит пользователя.
name 8) Строка Наименование дополнительного реквизита пользователя. Максимальная длина строки – 64 символа. 1084
value 9) Строка Значение дополнительного реквизита пользователя. Максимальная длина строки – 256 символов. 1085
service Структура Служебный раздел 1086
callback_url Строка URL, на который необходимо ответить после обработки документа.
Если поле заполнено корректно, то после обработки документа (успешной или не успешной фискализации в ККТ: статус «done» или «fail»), ответ будет отправлен POST запросом по URL указанному в данном поле.
Корректность заполненного поля определяется по регулярному выражению:
^http(s?)\:\/\/[0-9a-zA-Zа-яА-Я]([-.\w]*[0-9a-zA-Zа-яА-Я])*(:(0-9)*)*(\/?)([azA-Z0-9а-яА-Я\-\.\?\,\'\/\\\+&=%\$#_]*)?$
timestamp Дата и время Дата и время документа внешней системы в формате: «dd.mm.yyyy HH:MM:SS»
dd – День месяца. Формат DD. Возможные значения от «01» до «31»;
mm – Месяц. Формат MM. Возможные значения от «01» до «12»;
yyyy – Год. Формат YYYY. Допустимое количество символов – четыре;
HH – Часы. Формат HH. Возможные значения от «00» до «24»;
MM – Минуты. Формат MM. Возможные значения от «00» до «59»;
SS – Секунды. Формат SS. Возможные значения от «00» до «59»

В ответ на POST запрос возвращается структура данных в формате JSON, содержащая уникальный идентификатор, присвоенный данному документу и статус. Поля ответов описаны в таблице 2.
Способы получения результатов обработки документа по уникальному идентификатору описаны в разделе 4. Пример ответа:

{
  "uuid": "2ea26f17–0884–4f08–b120–306fc096a58f",
  "timestamp": "12.04.2017 06:15:06",
  "error": null,
  "status": "wait",
}

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

{
  "timestamp": "12.04.2017 06:15:06",
  "status": "fail",
  "error": {
    "error_id": "475d6d8d-844d-4d05-aa8b-e3dbdf4defd6",
    "code": 30,
    "text": " Передан некорректный UUID : \"{0}\". Необходимо повторить запрос с корректными данными ",
    "type": "system"
  }
}

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

Параметр Формат поля Описание
uuid Строка Уникальный идентификатор. Максимальная длина строки – 128 символов. Если документ не удалось зарегистрировать, документу не будет присвоен UUID.
timestamp Дата и время Дата и время документа внешней системы в формате: «dd.mm.yyyy HH:MM:SS»
dd – День месяца. Формат DD. Возможные значения от «01» до «31»;
mm – Месяц. Формат MM. Возможные значения от «01» до «12»;
yyyy – Год. Формат YYYY. Допустимое количество символов – четыре;
HH – Часы. Формат HH. Возможные значения от «00» до «24»;
MM – Минуты. Формат MM. Возможные значения от «00» до «59»;
SS – Секунды. Формат SS. Возможные значения от «00» до «59»
status Строка Статус. Возможные значения:
«fail» – ошибка;
«wait» – ожидание.
error Структура Описание ошибки.
error_id Строка Уникальный идентификатор ошибки.
code Целое число Код ошибки. Отображается только при ошибке. Если параметр присутствует, то со значением «fail» или «wait».
text Строка Текст ошибки (кодировка utf–8).
type Строка Тип источника ошибки. Возможные значения:
«system» – системная ошибка;
«unknown» – неизвестная ошибка.

3.1. Возможные значения наименования товара (Поле "name")

  • 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.2. Возможные значения способа расчёта (Поле "payment_method")

  • «full_prepayment» – предоплата 100%. Полна предварительная оплата до момента передачи предмета расчета.
  • «prepayment» – предоплата. Частичная предварительная оплата до момента передачи предмета расчета.
  • «advance» – аванс.
  • «full_payment» – полный расчет. Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета.
  • «partial_payment» – частичный расчет и кредит. Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит.
  • «credit» – передача в кредит. Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит.
  • «credit_payment» – оплата кредита. Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита).

3.3. Возможные значения признака предмета расчёта (Поле "payment_object")

  • «commodity» – товар. О реализуемом товаре, за исключением подакцизного товара (наименование и иные сведения, описывающие товар).
  • «excise» – подакцизный товар. О реализуемом подакцизном товаре (наименование и иные сведения, описывающие товар).
  • «job» – работа. О выполняемой работе (наименование и иные сведения, описывающие работу).
  • «service» – услуга. Об оказываемой услуге (наименование и иные сведения, описывающие услугу).
  • «gambling_bet» – ставка азартной игры. О приеме ставок при осуществлении деятельности по проведению азартных игр.
  • «gambling_prize» – выигрыш азартной игры. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр.
  • «lottery» – лотерейный билет. О приеме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приеме лотерейных ставок при осуществлении деятельности по проведению лотерей.
  • «lottery_prize» – выигрыш лотереи. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей.
  • «intellectual_activity» – предоставление результатов интеллектуальной деятельности. О предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации.
  • «payment» – платеж. Об авансе, задатке, предоплате, кредите, взносе в счет оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчета.
  • «agent_commission» – агентское вознаграждение. О вознаграждении пользователя, являющегося платежным агентом (субагентом), банковским платежным агентом (субагентом), комиссионером, поверенным или иным агентом.
  • «composite» – составной предмет расчета. О предмете расчета, состоящем из предметов, каждому из которых может быть присвоено значение выше перечисленных признаков.
  • «another» – иной предмет расчета. О предмете расчета, не относящемуся к выше перечисленным предметам расчета.
  • «property_right» – имущественное право. О передаче имущественных прав.
  • «non-operating_gain» – внереализационный доход. О внереализационном доходе.
  • «insurance_premium» – страховые взносы. О суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации.
  • «sales_tax» – торговый сбор. О суммах уплаченного торгового сбора.
  • «resort_fee» – курортный сбор. О курортном сборе.

3.4. Возможные значения налога (Поле "type")

  • «none» – без НДС;
  • «vat0» – НДС по ставке 0%;
  • «vat10» – НДС чека по ставке 10%;
  • «vat18» – НДС чека по ставке 18%;
  • «vat110» – НДС чека по расчетной ставке 10/110;
  • «vat118» – НДС чека по расчетной ставке 18/118;
  • «vat20» – НДС чека по ставке 20%;
  • «vat120» – НДС чека по расчетной ставке 20/120.

Важно! Согласно приказу ФНС России от 22.10.2018 N ММВ-7-20/605@ с 01.04.2019 00:00 налоговая ставка 18% заменена на 20%, а налоговая ставка 18/118 замена на 20/120. Поэтому при отправке ставки vat18 или vat118 в чеках приход и расход, сервис будет возвращать ошибку IncomingValidationException с текстом: «Передана некорректная ставка налога. С 01.04.2019 ставки НДС 18 и 18/118 не могут использоваться в чеках sell(приход) и buy(расход)».

4. Получение результата обработки документа

Результат обработки документа может быть получен двумя способами. Если поле «callback_url» было заполнено, то после обработки документа (успешной или не успешной фискализации в ККТ), ответ будет отправлен POST запросом по URI указанному в данном поле. Если в течение 300 секунд ответ не поступил, необходимо запросить статус обработки документа с помощью метода GET. Результат обработки документа одинаков для всех способов получения и приведен в таблице 3 и 4.

Запрос на получение результата обработки документа:

GET https://ferma-at.ofd.ru/possystem/v1/<group_code>/report/<uuid>

Здесь:
group_code: идентификатор группы ККТ:

  • параметр можно посмотреть в ЛКК Ferma в виджете «Реквизиты доступа»;
  • для тестовой среды параметр равен 1.

uuid: уникальный идентификатор, присвоенный документу после выполнения запроса на регистрацию.

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

{
    "error": null,
    "timestatmp": "31.03.2020 13:32:25",
    "uuid": "0099caf8-2c9c-4888-a289-b8ac879cdd91",
    "status": "done",
    "payload": {
        "total": 1598,
        "ofd_inn": "7709364545",
        "fns_site": "www.nalog.ru",
        "fn_number": "1110000100231111",
        "ecr_registration_number": "0000111118041111",
        "shift_number": 23,
        "receipt_datetime": "12.04.2017 20:16:00",
        "fiscal_receipt_number": 6,
        "fiscal_document_number": 133,
        "fiscal_document_attribute": 3449555955
        "ofd_receipt_url": "https://check.ofd.ru/"
    },
    "group_code": " MyCompany_MyShop",
    "daemon_code": "prod–agent–1",
    "device_code": "KSR13.00–1–11",
    "external_id": "TRF10601_1",
    "callback_url": ""
 }

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

Параметр Формат поля Описание
error Строка Сообщение об ошибке
timestamp Дата и время Дата и время документа из ФН
uuid Строка Уникальный идентификатор. Максимальная длина строки – 128 символов. Если документ не удалось зарегистрировать, документу не будет присвоен UUID.
status Строка Статус. Возможные значения:
«done» – готово;
«fail» – ошибка;
«wait» – ожидание.
payload Структура Реквизиты фискализации документа.
total Число с точкой Итоговая сумма документа в рублях с заданным в CMS округлением:
- целая часть не более 8 знаков;
- дробная часть не более 2 знаков.
При регистрации в ККТ происходит расчёт фактической суммы: суммирование значений sum позиций.
ofd_inn Строка ИНН ОФД, через которого был зарегистрирован чек
fns_site Строка Адрес сайта ФНС
fn_number Строка Номер ФН
ecr_registration_number Строка Регистрационный номер ККТ
shift_number Целое число Номер смены
receipt_datetime Дата и время Дата и время документа внешней системы в формате: «dd.mm.yyyy HH:MM:SS»
dd – День месяца. Формат DD. Возможные значения от «01» до «31»;
mm – Месяц. Формат MM. Возможные значения от «01» до «12»;
yyyy – Год. Формат YYYY. Допустимое количество символов – четыре;
HH – Часы. Формат HH. Возможные значения от «00» до «24»;
MM – Минуты. Формат MM. Возможные значения от «00» до «59»;
SS – Секунды. Формат SS. Возможные значения от «00» до «59»
fiscal_receipt_number Целое число Номер чека в смене.
fiscal_document_number Целое число Фискальный номер документа
fiscal_document_attribute Целое число Фискальный признак документа.
ofd_receipt_url Строка URL для просмотра чека на сайте ОФД
group_code Строка Идентификатор группы ККТ
daemon_code Строка Наименование сервера
device_code Строка Код ККТ
external_id Строка Идентификатор документа внешней системы, уникальный среди всех документов, отправленных в данную группу ККТ.
callback_url Строка URL, на который необходимо ответить после обработки документа

В случае ошибки ответ имеет следующий вид:

{
    "error": {
        "error_id": "474d4d4d-444d-4d44-aa4b-e3dbdf4defd3",
        "code": 34,
        "text": "Состояние чека не найдено. Попробуйте позднее",
        "type": "system"
    },
    "status": "wait",
    "timestamp": "12.04.2017 18:58:38",
    "callback_url": ""
}

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

Параметр Формат поля Описание
error Структура Описание ошибки.
error_id Строка Уникальный идентификатор ошибки.
code Целое число Код ошибки. Отображается только при ошибке. Если параметр присутствует, то со значением «fail» или «wait».
text Строка Текст ошибки (кодировка utf–8).
type Строка Тип источника ошибки. Возможные значения:
«system» – системная ошибка;
«unknown» – неизвестная ошибка.
status Строка Статус. Возможные значения:
«fail» – ошибка;
«wait» – ожидание.
timestamp Дата и время Дата и время документа внешней системы в формате: «dd.mm.yyyy HH:MM:SS»
dd – День месяца. Формат DD. Возможные значения от «01» до «31»;
mm – Месяц. Формат MM. Возможные значения от «01» до «12»;
yyyy – Год. Формат YYYY. Допустимое количество символов – четыре;
HH – Часы. Формат HH. Возможные значения от «00» до «24»;
MM – Минуты. Формат MM. Возможные значения от «00» до «59»;
SS – Секунды. Формат SS. Возможные значения от «00» до «59»
callback_url Строка URL, на который необходимо ответить после обработки документа

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

5.1. Описание

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

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

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

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

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

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

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

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

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

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

История изменений

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

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

Версия 1.2
Выпущена 25 июня 2020 г.
В описание к параметру timestamp, который присутствует при получении кода авторизации (token), добавлена информация о том, сколько времени токен доступен для использования.

Версия 1.3
Выпущена 8 сентября 2020 г.
Добавлена информация откуда берется параметр group_code.

Версия 1.4
Выпущена 9 сентября 2020 г.
В блок 5.4. Тестовое API Ferma добавлена информация по параметру group_code.

Версия 1.5
Выпущена 18сентября 2020 г.
Исправлен url для доступа.

1) , 2)
В запросе обязательно должно быть заполнено хотя бы одно из полей: email или phone. Если заполнены оба поля, ОФД отправит электронный чек только на email
3)
Параметр обязателен, если передан «supplier_info».
4) , 7)
Поле обязательно, если передан «agent_info».
5)
Если признак не передан, по умолчанию используется значение «full_prepayment»
6)
Параметр обязателен, если передан «supplier_info».
8)
Если передан объект «additional_user_props», в нём обязательно должно быть передано поле «name».
9)
Если передан объект «additional_user_props», в нём обязательно должно быть передано поле «value».