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

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

Версия 1.3 от 16.03.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. Создание чека

Вид запроса:

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

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

3.1 Описание

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

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

Для того, чтобы пробить чеки на тестовой кассе Ferma, которая находится в демо ЛКК, используйте данные:
Домен1) - ferma-test-o.ofd.ru
Авторизация осуществляется по 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)
Его вы используете для подстановки в API-запросы вместо ferma-o.ofd.ru