В документе приводятся технические сведения о программном интерфейсе приложений (API) предоставляющем возможность регистрировать онлайн-кассы и инициировать генерацию кассовых документов посредством информационной системы (ИС) “Ferma”.
Обмен данными с онлайн-кассами происходит по протоколу HTTP с использованием зашифрованного канала (HTTPS). Данные запросов и ответов передаются в виде структуры JSON. Вне зависимости от наличия ошибок в данных, обязательным условием успешного выполнения запроса является ответ с кодом 200 согласно протоколу HTTP.
Ниже описаны запросы HTTP, которыми реализуются функции API по работе с онлайн-кассами.
На рисунке 1 показана схема запросов к ИС “Ferma”. Для получения данных по чекам и кассовым аппаратам, используйте API "Чеки и ККТ".
Кодировка, используемая в запросах и ответах – UTF-8. Запросы выполняются методами POST и GET, параметры запроса располагаются в структуре данных формата JSON, передаваемой в блоке данных запроса (при использовании POST), также параметры могут передаваться в строке запроса (при использовании GET).
Ответы выдаются сервером в формате JSON и, в случае успешности ответа согласно его заголовку (код ответа по протоколу HTTP равен 200), данные имеют следующий обобщенный вид:
{
"Status": "Success",
"Data": {}
}
Здесь:
В случае неуспешного ответа (код ответа по протоколу HTTP не равен 200) данные имеют следующий обобщенный вид:
{
"Status": "Failed",
"Error": {
Code: 0,
Message: "string"
}
}
Здесь:
Возможность множественных обращений к ИС “Ferma” после одной авторизации без использования механизма Cookies реализуется с помощью механизма AuthToken: после авторизации с передачей имени и пароля система возвращает код авторизации – строку символов, которая используется, как параметр авторизации при обращении к соответствующему личному кабинету (ЛК).
Параметры запроса:
HTTP/1.1
Content-Length: 38
Content-Type: application/json
charset=utf-8
Вид запроса:
POST https://ferma.ofd.ru/api/Authorization/CreateAuthToken
Тело запроса представляет собой структуру JSON, содержащую:
{
"Login": "12345","Password": "56789"
}
В данном запросе присутствуют примеры значений: Login – «12345» и Password – «56789». Они задаются как значения в JSON-структуре внутри запроса.
Их можно получить в личном кабинете клиента в разделе «Ferma», после покупки кассы Ferma, либо у вашего менеджера.
В ответ на данный запрос будет получен ответ по протоколу HTTP, который в случае успешной авторизации будет иметь код равный 200 и содержать структуру, подобную следующей (приведены примеры значений):
{
"Status": "Success",
"Data": {
"AuthToken": "f3accdfda7574736ba94a78d00e974f4",
"ExpirationDateUtc": "2017-01-24T14:44:21"
}
}
Здесь:
В случае проблем с авторизацией (код ответа по протоколу HTTP будет равен 401) данные будут отсутствовать, JSON-структура будет пустой (будет иметь вид «{}»).
Полученный код авторизации используется в виде дополнительного параметра в запросах документов для сверки, где необходима авторизация 3). Пример запроса с использованием кода авторизации:
POST https://ferma.ofd.ru/api/kkt/cloud/receipt?AuthToken=Code1
Вид запроса:
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 | Число | Признак предмета расчета для всего чека. Важно! Если в данном поле значение клиентом не указано, то используется значение по умолчанию, которое устанавливается по умолчанию при заведении учетной записи в информационной системе Ferma. Список возможных значений перечислен в п. 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. Не более 1024 символов в поле | 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 | Число с точкой | Общая стоимость товара в товарной позиции в рублях. Правила округления для стоимости товара зависят от типа кассы. В кассах типа Эфир Pro ФС и Эфир Pro ФА стоимость округляется по математическим правилам округления. | 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 | Идентификатор чека для дальнейшего запроса состояния |
Внимание! Возможные (корректные) значения типа налогообложения ограничиваются значениями, отмеченными, как разрешенные при регистрации кассы. Для того, чтобы изменить список допустимых типов налогообложения, необходимо произвести перерегистрацию кассы.
Внимание! Некоторые комбинации предметов расчета и систем налогообложения могут вызывать ошибку. Это связано с особенностями работ касс.
Сформированный чек будет считаться корректным, если он соответствует следующим условиям:
Касса ФА используется:
Чек получения денежных средств с информацией о клиенте:
{
"Inn": "2465165753",
"Type": "Income",
"InvoiceId": "1",
"CustomerReceipt": {
"TaxationSystem": "SimpleIn",
"Email": "example@yandex.ru",
"Phone": "+79000000000",
"AutomaticDeviceNumber": null,
"PaymentType": 1,
"PaymentAgentInfo": null,
"CorrectionInfo": null,
"ClientInfo": {
"Name": "Иванов Иван Иванович",
"Inn": "5645645319"
},
"Items": [
{
"Label": "Апартамент A005 с 21.08 по 25.08",
"Price": 7600.0,
"Quantity": 1.0,
"Amount": 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",
"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",
"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",
"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",
"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",
"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",
"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",
"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",
"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",
"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",
"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.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 | Строка | Ссылка на чек |
Возможные значения:
В случае, если чек не прошёл ФЛК при пробитии на кассе, ответ имеет следующий вид:
{
"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 | Структура | Информация об устройстве (ККТ), на котором была произведена операция |
При получении ошибки необходимо проверить введенные данные и исправить их в соответствии с сообщением системы. После чего повторно отправить запрос на пробитие чека. Список всех возможных ошибок представлен здесь. Если самостоятельно не удается разобраться с проблемой, то обратитесь к вашему менеджеру, либо в нашу техподдержку.
Запрос реестра кассовых чеков включает в себя 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,
"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. | ||
Строка | Адрес электронной почты клиента | |||
Phone | Строка | Контактный телефон клиента | ||
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 | Структура | Информация об устройстве (ККТ), на котором была произведена операция |
При получении ошибки необходимо проверить введенные данные и исправить их в соответствии с сообщением системы. После чего повторно отправить запрос на пробитие чека. Список всех возможных ошибок представлен здесь. Если самостоятельно не удается разобраться с проблемой, то обратитесь к вашему менеджеру, либо в нашу техподдержку.
Вид запроса:
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"
},
...
]
}
Вид запроса:
GET https://ferma.ofd.ru/api/kkt/cloud/stats/receipts/extended?AuthToken=AuthToken&dateFromIncl=dateFromIncl&dateToIncl=dateToIncl&receiptId=receiptId&zn=zn&fn=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
}
]
}
]
}
}
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 |
400 | 1064 | Чек коррекции содержит некорректный признак расчёта(тег 1054) |
Раздел описывает способ тестирования услуги «Ferma» с пробитием чеков и возможностью их просмотра. Для тестирования используется демонстрационный личный кабинет клиента (ЛКК), а также кассовый аппарат с установленным тестовым фискальным накопитель (ФН МГМ), который подключен к тестовой информационной системе Ferma.
Для того, чтобы пробить чеки на тестовой кассе Ferma, которая находится в демо ЛКК, используйте данные:
Домен41) - ferma-test.ofd.ru
Логин - fermatest1
Пароль - Hjsf3321klsadfAA
Логин и пароль используются в API-запросе для получения кода авторизации (AuthToken).
Чтобы войти в демо личный кабинет клиента для дальнейшего просмотра чеков, нужно выполнить следующие действия:
После того, как вошли в демо ЛКК, для просмотра пробитых чеков на кассе, нужно:
Версия 2.0
Выпущена 24 августа 2018 г.
Первая регистрируемая версия документа.
Версия 2.1
Выпущена 14 ноября 2018 г.
Версия 2.2
Выпущена 17 января 2019 г.
Исправлена ошибка в тексте предыдущей версии документа: замена строки «FPD» на «FDP» в примерах структур данных.
Версия 2.3
Добавлена 28 января 2019 г.
Добавлена информация в соответствии с изменениями в структуре данных «CustomerReceipts».
Версия 2.6
Добавлена 04 апреля 2019 г.
Версия 2.7
Добавлена 28 мая 2019 г.
Версия 2.8
Добавлена 19 июня 2019 г.
Версия 2.9
Добавлена 21 июня 2019 г.
Версия 2.10
Добавлена 08 июля 2019 г.
Версия 2.11
Добавлена 15 июля 2019 г.
Версия 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 г.
Версия 2.18
Добавлена 10 января 2020 г.
Версия 2.19
Добавлена 27 января 2020 г.
Исключен из API-запроса на формирование кассового чека параметр «AutomaticDeviceNumber».
Версия 2.20
Добавлена 18 февраля 2020 г.
Добавлены примеры API-запросов на формирование кассового чека.
Версия 2.21
Выпущена 7 апреля 2020 г.
Добавлен раздел описывающий порядок тестирования.
Версия 2.22
Выпущена 13 апреля 2020 г.
Версия 2.23
Выпущена 16 июнь 2020 г.
В список возможных ошибок при формировании кассового чека добавлена ошибка 1055.
Версия 2.24
Выпущена 27 августа 2020 г.
Версия 2.25
Выпущена 08 сентября 2020 г.
Версия 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 г.
Версия 2.31
Выпущена 14 октября 2020 г.
Версия 2.32
Выпущена 06 ноября 2020 г.
Добавлен раздел 3.5
Версия 2.33
Выпущена 30 ноября 2020 г.
Версия 2.34
Выпущена 09 февраля 2021 г.
Версия 2.35
Выпущена 09 февраля 2021 г.
Версия 2.36
Выпущена 10 февраля 2021 г.
Исправлено описание тега 1179 в таблице 1.1 Параметры элементов структуры «CustomerReceipt»
Версия 2.37
Выпущена 12 февраля 2021 г.
Убраны параметры InstallmentPlace,InstallmentAddress