Помогаем продавать

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

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

Введение

Документ описывает сценарий использования программного интерфейса приложений (API) сервиса Orange Data для взаимодействия с интернет-кассой Ferma

1. Основные сведения о запросе и ответе

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

Пример запроса с подписью:

POST https://ferma-o.ofd.ru/api/v2/documents/ 

{
  "id": "2_loc_z5bYWHvD",
  "inn": 1234567890,
  "group": "Main",
  "key": 1234567890,
  "content": {
    "type": 1,
    "positions": [
      {
        "quantity": 2.0,
        "price": 10.0,
        "tax": 1,
        "text": "\u0421\u0430\u043c\u043e\u0432\u044b\u0432\u043e\u0437 ru",
        "paymentMethodType": 4,
        "paymentSubjectType": 1
      },
      {
        "quantity": 1.0,
        "price": 0.0,
        "tax": 1,
        "text": "\u0414\u043e\u0441\u0442\u0430\u0432\u043a\u0430",
        "paymentMethodType": 4,
        "paymentSubjectType": 4
      }
    ],
    "checkClose": {
      "payments": [
        {
          "type": 2,
          "amount": 20.0
        }
      ],
      "taxationSystem": 0
    },
    "customerContact": "user@domain.com"
  }
}

Подробно параметры можно посмотреть в таблице Таблица 1.

2. Описание работы с orange data Создание чека

2.1.Создание чека

Вид запроса:

POST https://ferma-o.ofd.ru/api/v2/documents/

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

{
  "id": "12345678990",
  "inn": "123456789012",
  "group": "Main",
  "content": {
    "type": 1,
    "positions": [
      {
        "quantity": 1.000,
        "price": 123.45,
        "tax": 6,
        "text": "Булка",
        "paymentMethodType": 4,
        "paymentSubjectType": 1
      },
      {
        "quantity": 2.000,
        "price": 4.45,
        "tax": 4,
        "text": "Спички",
        "paymentMethodType": 3,
        "paymentSubjectType": 13
      }
    ],
    "checkClose": {
      "payments": [
        {
          "type": 1,
          "amount": 123.45
        },
        {
          "type": 2,
          "amount": 8.90000
        }
      ],
      "taxationSystem": 1
    },
    "customerContact": "foo@example.com"
  }
}

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

Параметр Вложенный параметр Вложенный параметр Вложенный параметр Формат значения Описание Признак обязательности в запросе
Id Строка Идентификатор документа да
Inn Строка ИНН организации, для которой пробивается чек да
group Строка Группа устройств, с помощью которых будет пробит чек нет
callbackUrl Строка URL для отправки результатов обработки чека POST запросом нет
content Структура Содержимое документа нет
type Число Признак расчета, 1054:
1 - Приход;
2 - Возврат прихода;
3 - Расход;
4 - Возврат расхода.
да
positions Структура Идентификатор счета, на основании которого генерируется чек. Важно!Если чек пробился и был ответ 201 перепробивать чек нужно с другим Id. Если при пробитии чека статус ответа не 201, то он пробивается с тем же invoiceId да
quantity Число Количество предмета расчета, 1023 да
price Число Цена за единицу предмета расчета с учетом скидок и наценок, 1079 да
tax Число Ставка НДС, 1199:
1 – ставка НДС 20%
2 – ставка НДС 10%
3 – ставка НДС расчетная 20/120
4 – ставка НДС расчетная 10/110
5 – ставка НДС 0%
6 – НДС не облагается
да
taxSum Число Сумма НДС за предмет расчета, 1200. Параметр актуален для ставок НДС 1-4. Для ставок 5 и 6 данный тег в предмете расчета не передается, переданное значение игнорируется. Если передать значение 0, то тег не будет записан. нет
text Строка Наименование предмета расчета, 1030. Строка до 128 символов. да
paymentMethodType Число Признак способа расчета, 1214: 1 – Предоплата 100%; 2 – Частичная предоплата; 3 – Аванс; 4 – Полный расчет; 5 – Частичный расчет и кредит; 6 – Передача в кредит; 7 – оплата кредита. нет
paymentSubjectType Число Признак предмета расчета, 1212:
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 – Платеж казино
да
checkClose Число Параметры закрытия чека да
payments Структура
type Число Тип оплаты:
1 – сумма по чеку наличными, 1031;
2 – сумма по чеку безналичными, 1081;
14 – сумма по чеку предоплатой (зачетом аванса и (или) предыдущих платежей), 1215;
15 – сумма по чеку постоплатой (в кредит), 1216;
16 – сумма по чеку (БСО) встречным предоставлением, 1217.
да
amount Число Параметры закрытия чека да
taxationSystem Число Система налогообложения, 1055:
0 – Общая, ОСН, доход;
1 – Упрощенная доход, УСН;
2 – Упрощенная доход минус расход, УСН доход - расход;
3 – Единый налог на вмененный доход, ЕНВД;
4 – Единый сельскохозяйственный налог, ЕСН;
5 – Патентная система налогообложения, Патент;
да
customerContact Строка Телефон или электронный адрес покупателя, 1008 да

Пример запроса с данными агента, дополнительным реквизитом пользователя, данными поставщика, номером автомата, адресом расчета и местом расчета:

{
  "id": "12345678990",
  "inn": "123456789012",
  "group": "Main",
  "key": "1234567",
  "content": {
    "type": 1,
    "positions": [
      {
        "quantity": 1.000,
        "price": 123.45,
        "tax": 6,
        "text": "Булка",
        "paymentMethodType": 4,
        "paymentSubjectType": 1,
        "nomenclatureCode": "igQVAAADMTIzNDU2Nzg5MDEyMwAAAAAAAQ==",
        "agentType": 127,
        "agentInfo": {
          "paymentTransferOperatorPhoneNumbers": [ "+79200000001", "+74997870001" ],
          "paymentAgentOperation": "Какая-то операция 1",
          "paymentAgentPhoneNumbers": [ "+79200000003" ],
          "paymentOperatorPhoneNumbers": [ "+79200000002", "+74997870002" ],
          "paymentOperatorName": "ООО \"Атлант\"",
          "paymentOperatorAddress": "Воронеж, ул. Недогонная, д. 84",
          "paymentOperatorINN": "7727257386"
        },
        "unitOfMeasurement": "Кг",
        "additionalAttribute": "Доп. атрибут и все тут",
        "manufacturerCountryCode": "643",
        "customsDeclarationNumber": "АД 11/77 от 01.08.2018",
        "excise": 23.45
      },
      {
        "quantity": 2.000,
        "price": 4.45,
        "tax": 4,
        "text": "Спички",
        "paymentMethodType": 3,
        "paymentSubjectType": 13,
        "supplierINN": "9715225506",
        "supplierInfo": {
          "phoneNumbers": [ "+79266660011", "+79266660022" ],
          "name": "ПАО \"Адамас\""
        }
      }
    ],
    "checkClose": {
      "payments": [
        {
          "type": 1,
          "amount": 123.45
        },
        {
          "type": 2,
          "amount": 8.90000
        }
      ],
      "taxationSystem": 1
    },
    "customerContact": "foo@example.com",
    "agentType": 127,
    "paymentTransferOperatorPhoneNumbers": [ "+79260000001", "+74957870001" ],
    "paymentAgentOperation": "Какая-то операция",
    "paymentAgentPhoneNumbers": [ "+79260000003" ],
    "paymentOperatorPhoneNumbers": [ "+79260000002", "+74957870002" ],
    "paymentOperatorName": "ООО \"Росинка\"",
    "paymentOperatorAddress": "Москва, Мастеркова 4",
    "paymentOperatorINN": "9715225506",
    "supplierPhoneNumbers": [ "+74957870004" ],
    "additionalUserAttribute": {
      "name": "Любимая цитата",
      "value": "В здоровом теле здоровый дух, этот лозунг еще не потух!"
    },
    "automatNumber": "123456789",
    "settlementAddress": "г.Москва, Красная площадь, д.1",
    "settlementPlace": "Палата №6",
    "additionalAttribute": "Доп атрибут чека",
    "customer": "Кузнецов Иван Петрович",
    "customerINN": "789456123488"
  }
}

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

{
  "errors": [
    "Не указан идентификатор документа 'Id'",
    "Не указан ИНН организации 'INN'",
    "Отсутствует содержимое документа 'Content'"
  ]
}

В ответ: api может возвращать следующие http статус-коды

  • 201 Created – чек создан и добавлен в очередь на обработку, пустое тело ответа
  • 401 Unauthorized – клиентский сертификат не прошел проверку
  • 409 Conflict– чек с данным идентификатором уже был создан в системе, пустое тело ответа
  • 400 Bad Request – переданные данные содержат ошибки валидации, либо подпись не прошла проверку, тело ответа п.2.1.2
  • 503, Service Unavailable – очередь документов переполнена, в ответе возвращается хедер Retry-After с таймаутом в секундах, через который стоит повторить запрос, тело ответа п.2.1.2.

2.2 Состояние чека

Запрос:

GET https://ferma-o.ofd.ru/api/v2/documents/{inn}/status/{document_id}

{inn} – ИНН организации, для которой пробивается чек; {document_id} –идентификатор документа, который был указан при его создании

Ответ: api может возвращать следующие статус-коды

  • 202 Accepted – чек создан и добавлен в очередь на обработку, но еще не обработан, пустое тело ответа
  • 400 Bad Request – организация не найдена, чек с указанным идентификатором не найден
  • 401 Unauthorized – клиентский сертификат не прошел проверку
  • 200 OK – чек обработан, тело ответа п.2.2.1
  • 524, Document Expired Before Processing – серверу не удалось за отведенное время обработать документ, отправьте чек с новым идентификатором для повторной обработки, пустое тело ответа

Пример ответа:

{
  "id": "12345678990",
  "deviceSN": "0000000000001358",
  "deviceRN": "0000000400054952",
  "fsNumber": "9999078900001341",
  "ofdName": "ООО \"Ярус\"(\"ОФД-Я\")",
  "ofdWebsite": "www.ofd-ya.ru",
  "ofdinn": "7728699517",
  "fnsWebsite": "www.nalog.ru",
  "companyINN": "123456789012",
  "companyName": "ЗАО ТОРГОВЫЙ ОБЪЕКТ №1",
  "documentNumber": 117,
  "shiftNumber": 20,
  "documentIndex": 5,
  "processedAt": "2017-02-14T14:16:00",
  "content": {
    "type": 1,
    "positions": [
      {
        "quantity": 1.000,
        "price": 123.45,
        "tax": 6,
        "text": "Булка",
        "paymentMethodType": 4,
        "paymentSubjectType": 1
      },
      {
        "quantity": 2.000,
        "price": 4.45,
        "tax": 4,
        "text": "Спички",
        "paymentMethodType": 3,
        "paymentSubjectType": 13
      }
    ],
    "checkClose": {
      "payments": [
        {
          "type": 1,
          "amount": 123.45
        },
        {
          "type": 2,
          "amount": 8.90000
        }
      ],
      "taxationSystem": 1
    },
    "customerContact": "+79123456789"
  },
  "change": 974.01,
  "fp": "2364009522

Таблица 2. «Параметры состояния чека»

Параметр Формат значения Строка от 1 до 64 символов
id Заводской номер устройства пробившего чек Строка до 20 символов
deviceSN Регистрационный номер устройства пробившего чек Строка до 20 символов
deviceRN Регистрационный номер устройства пробившего чек Строка до 20 символов
fsNumber Номер фискального накопителя Строка 16 символов
ofdName Наименование ОФД Строка до 256 символов
odfWebsite Web-сайт ОФД Строка до 58 символов
odfINN ИНН ОФД Строка 12 символов
fnsWebsite Web-сайт ФНС Строка до 256 символов
companyINN ИНН пользователя Строка 12 символов
companyName Наименование пользователя Строка до 256 символов
documentNumber Номер ФД Число
shiftNumber Номер смены Число
documentIndex Номер чека за смену Число
processedAt Время регистрации фискального документа в ФН Время в виде строки в формате ISO8601
content Содержимое документа Структура
change Сдача Десятичное число с точностью до 2 символов после точки
fp Фискальный признак Строка 10 символов
callbackUrl URL для отправки результатов обработки чека POST запросом Строка от 1 до 1024 символов или null

2.3 Описание запроса на формирование чека коррекции

Запрос на формирование чека коррекции выполняется самостоятельно или по предписанию из ФНС. Чек коррекции формируется запросом методом POST с передачей параметров в JSON-структуре.

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

POST https://ferma-o.ofd.ru/api/v1/corrections

В таблице 3 приведено описание параметров запроса для формирования чека коррекции.

Таблица 3. Описание параметров запроса для формирования чека коррекции

Параметр Вложенный параметр Формат значения Описание Признак обязательности
Id Строка Идентификатор документа да
Inn Строка ИНН организации, для которой пробивается чек да
key Строка Название ключа да
callbackUrl Строка URL-адрес для отправки результатов обработки чека. Результат обработки выполняется методом POST нет
content Структура Содержимое документа да
correctionType Строка Тип коррекции.
Тип коррекции может принимать значения:
- SELF — коррекция производится самостоятельно;
- INSTRUCTION — коррекция производится по предписанию
да
type Число Признак расчета может принимать следующие значения:
1 - Приход;
3 - Расход.
да
causeDocumentDate Строка Дата документа основания для коррекции . Значение даты передается в формате «ДД.ММ.ГГ», где ДД — день, ММ — месяц, ГГ — год. да
causeDocumentNumber Строка Номер предписания налогового органа да
totalSum Строка Общая сумма чека да
cashSum Строка Сумма платежа наличными расчетом да
eCashSum Строка Сумма платежа безналичными расчетом да
prepaymentSum Строка Сумма платежа расчета по предоплате да
postpaymentSum Строка Сумма платежа расчета по постоплате да
otherPaymentTypeSum Строка Сумма другого типа платежа да
tax1Sum Число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 20 %
tax2Sum Число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10 %
tax3Sum Число Сумма по операциям, облагаемая НДС по ставке 0%
tax4Sum Число Сумма по операциям, не облагаемая НДС
tax5Sum Число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 20/120
tax6Sum Число Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10/110
taxationSystem Число Система налогообложения принимает следующие значения:
0 – Общая, ОСН, доход;
1 – Упрощенная доход, УСН;
2 – Упрощенная доход минус расход, УСН доход - расход;
3 – Единый налог на вмененный доход, ЕНВД;
4 – Единый сельскохозяйственный налог, ЕСН;
5 – Патентная система налогообложения, Патент;
да
automatNumber Строка Номер автоматического устройства
settlementAddress Строка Полный адрес места расчёта
settlementPlace Строка Место расчёта

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

POST https://ferma-o.ofd.ru/api/v1/corrections
Content-Type: application/json

{
  "id": "9c4c3f8a-a166-4ccf-8a20-6325efe41955",
  "inn": "7724465109",
  "group": "409",
  "content": {
    "correctionType": 1,
    "type": 1,
    "causeDocumentDate": "2017-08-10T00:00:00",
    "causeDocumentNumber": "ФЗ-54",
    "totalSum": 17.25,
    "cashSum": 1.23,
    "eCashSum": 2.34,
    "prepaymentSum": 5.67,
    "postpaymentSum": 4.56,
    "otherPaymentTypeSum": 3.45,
    "tax1Sum": 1.34,
    "taxationSystem": 1,
    "settlementAddress": "г.Москва, Красная площадь, д.1",
    "settlementPlace": "Палата №6"
  }
}

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

  • 201 Created – чек создан и добавлен в очередь на обработку;
  • 401 Unauthorized – клиентский сертификат не прошел проверку;
  • 409 Conflict – чек с данным идентификатором уже был создан в системе;
  • 400 Bad Request – переданные данные содержат ошибки валидации, либо подпись не прошла проверку;
  • 503 Service Unavailable – очередь документов переполнена.

Проверка статуса чека коррекции выполняется запросом описанным в разделе "2.2 Состояние чека".

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

3.1 Описание

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

3.2. Тестовое API сервиса «Orange Data» для информационной системы «Ferma»

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

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

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

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

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

Авторизация осуществляется по test_certificate.zip.

3.3 Вход в демо ЛКК

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

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

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

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

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

4. Как посмотреть чеки на реальном аккаунте

Для того, чтобы пробить чеки на кассе Ferma в продовом режиме, воспользуйтесь следующей инструкцией:
Авторизация осуществляется по сертификату.

Для получения продового сертификата сделайте следующие действия:

1. Перейдите в свой Личный кабинет клиента

2. В левом меню укажите Сервис Ferma


3. Пролистайте до виджета «Реквизиты доступа».


4. Нажмите скачать сертификат.

5. Используйте скачанный сертификат для подстановки в запросах на фискализацию на продовом контуре.

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

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

Версия 1.2
Выпущена 15 марта 2021 г.

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

Версия 1.3
Выпущена 16 марта 2021 г.

  • Добавлен раздел 3
  • Добавлен раздел 4

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

  • Устранены мелкие недочеты по всему документу

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

  • Добавлен новый раздел 2.3 Описание запроса на формирование чека коррекции
1)
Его вы используете для подстановки в API-запросы вместо ferma.ofd.ru.