Ferma® с Orange Data

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

Кодировка, используемая в запросах и ответах, в 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.

Вид запроса:

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": "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.
  

Запрос:

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. «Параметры состояния чека»

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

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

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

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

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

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

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 Состояние чека".

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

Для того чтобы пробить чеки на тестовой кассе Ferma®, которая находится в демо ЛКК, используйте данные:

• Домен - ferma-test-o.ofd.ru;
• Авторизация осуществляется по сертификату.

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

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

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

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

Для того, чтобы пробить чеки на кассе 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.6
Выпущена 24 апреля 2024 г.

• Изменен домен в пункте 3.2. Тестовое API сервиса «Orange Data» для информационной системы Ferma® на ferma-test-o.ofd.ru

Версия 1.7
Выпущена 14 июня 2024 г.

• Обновлен сертификат, доступный для скачивания в разделе 3. Порядок тестирования
• Проведена общая корректировка и актуализация документа