Raiff logo
API docs by Redocly

API для фискализации чеков (1.1)

Download OpenAPI specification:Download

Support e-mail: ecom@raiffeisen.ru

Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/fiscal.yaml

Поддержка 54-ФЗ

По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.Клиенты Райффайзенбанка, подключившие интернет-эквайринг, также могут воспользоваться услугой фискализации чеков через онлайн-кассу. Пошаговые инструкции приведены ниже.

Общая схема работы

Подключение онлайн-кассы

Клиенты Райффайзенбанка, подключившие интернет-эквайринг, также могут воспользоваться услугой фискализации чеков через онлайн-кассу. Пошаговые инструкции приведены ниже.

Поставщик кассового оборудования ФФД 1.05 ФФД 1.2
АТОЛ Онлайн + +
Билайн - +
БИФИТ + -
Чек-Онлайн + -
Эвотор + +
LIFE PAY + +
ОFD.ru + +
Orange Data + -

АТОЛ Онлайн

Поддерживает ФФД 1.05 и ФФД 1.2.

  1. Зарегистрируйтесь в сервисе "АТОЛ Онлайн" и подключите онлайн-кассу
  2. Заключите договор с оператором фискальных данных
  3. Зайдите в личный кабинет "АТОЛ Онлайн", чтобы получить логин, пароль и идентификатор. Выберите раздел "Мои компании", нажмите кнопку "Настройки интегратора". Скачается XML-файл с настройками, найдите в файле элемент access, в нём будут все три параметра: login, password, group_code. Если возникли трудности, обратитесь в техподдержку "АТОЛ Онлайн".
  4. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить

Билайн

Поддерживает ФФД 1.2

  1. Зарегистрируйтесь в сервисе “Облачные кассы Билайн” и подключите онлайн-кассу
  2. После подключения облачной кассы в личном кабинете Билайн запомните полученный логин и установленный пароль. Эти данные понадобятся на следующем шаге.
  3. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
    Для идентификатора группы ККТ используйте название “ecom”.

БИФИТ

Поддерживает ФФД 1.05

  1. Заключите договор с БИФИТ на аренду ККТ
  2. Оплатите аренду ККТ и ФН. БИФИТ предоставит бесплатное подключение к ОФД Яндекс. При необходимости можно подключиться к другому ОФД. Для этого в ЛК найдите № ККТ и № ФН и выполните регистрацию в ОФД на свой выбор
  3. Перейдите в личный кабинет БИФИТ для получения данных по подключенной кассе. Откройте пункт меню «Бифит Онлайн» и перейдите в раздел «Коннекторы ККТ». Создайте токен коннектора и привяжите к нему кассу. Скопируйте токен коннектора и заводской номер ККТ (идентификатор ККТ)
  4. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить

Чек-Онлайн

Поддерживает ФФД 1.05

  1. Зарегистрируйтесь в сервисе "Чек-Онлайн" и подключите онлайн-кассу
  2. Заключите договор с оператором фискальных данных
  3. Зайдите в личный кабинет клиента, чтобы получить логин и пароль. Откройте раздел "Предприятия", найдите в списке нужную компанию и нажмите на иконку в поле "Авторизация". Откроется раздел, в котором можно выбрать существующие логин и пароль или сгенерировать новые.Для получения идентификатора группы ККТ вернитесь в раздел "Предприятия" и выберите нужную компанию из списка. В открывшемся профиле предприятия скопируйте API Group ID. Эти данные понадобятся на следующем шаге.
  4. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить

Эвотор

Поддерживает ФФД 1.05 и ФФД 1.2

  1. Оставьте заявку на облачную онлайн-кассу на сайте Эвотор
  2. После подключения облачной кассы зайдите в личный кабинет Эвотор и получите приветственное письмо на E-mail. В личном кабинете и в письме содержатся логин, пароль и идентификатор группы касс. Скопируйте эти данные.
  3. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить

LIFE PAY

Поддерживает ФФД 1.05 и ФФД 1.2

  1. Оставьте заявку на облачную онлайн-кассу по ссылке. В заявке в поле Продукт укажите "Облачная касса".
    Поля для ИНН, номера телефона, имени и E-mail обязательны к заполнению. В поле "Комментарий" при необходимости можно указать дополнительную информацию. Например, "Позвонить по заявке завтра после 14:00"
  2. После подключения облачной кассы зайдите в личный кабинет LIFE PAY → Настройки → Разработчикам. В этом разделе скопируйте API KEY
  3. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
    В поле Логин укажите номер телефона в формате 7xxxxxxxxxx, а в поле Пароль - API KEY, скопированный ранее

OFD.ru

Поддерживает ФФД 1.05 и ФФД 1.2

  1. Подключите онлайн-кассу в сервисе OFD.ru
  2. Зарегистрируйте кассу в ФНС через сервис Ferma по инструкции

    Для получения данных по подключенной кассе в OFD.ru перейдите в раздел Ferma в личном кабинете клиента и пролистайте до виджета "Реквизиты доступа". Скопируйте логин, пароль и идентификатор группы ККТ для подключения. Эти данные понадобятся на следующем шаге.
  3. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить

Orange Data

Поддерживает ФФД 1.05

  1. Зарегистрируйтесь в системе “Orange Data” и подключите онлайн-кассу
  2. В разделе “Интеграция” ЛК Orange Data сгенерируйте файлы сертификации и пару ключей RSA.
  3. Для получения логина и пароля направьте следующие данные на E-mail api@orangedata.ru с указанием темы письма "Запрос данных Райффайзен Банк":
  • ИНН
  • Файл сертификата .pfx и private_key.xml, созданные на шаге 2.
  1. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
    Для идентификатора группы ККТ используйте название “main”.

Авторизация

Для успешной авторизации необходимо использовать:

  • secretKey - секретный ключ, который используется для межсервисного взаимодействия. Данный ключ мерчант получает при регистрации.

BАЖНО: Секретный ключ необходимо хранить в защищенном месте, нельзя публиковать на сторонних ресурсах или передавать третьим лицам.

Межсервисные запросы авторизуются посредством секретного ключа API (SECRET_KEY). Параметр авторизации указывается в заголовке Authorization, значение которого формируется как "Bearer SECRET_KEY".

Методы API

Для фискализации чеков через партнёра Райффайзенбанк предоставляет API из следующих запросов:

  • Сохранение чека
  • Регистрация чека
  • Получение статуса чека

Bзаимодействие осуществляется по протоколу HTTP с использованием методов POST, PUT, GET.

В описании каждого запроса явно указаны требуемые метод, адрес и параметры.

POST-запросы используют JSON-структуру, PUT- и GET-запросы работают со строками запросов.

Ответ любого метода возвращает HTTP-код. Если при обработке запроса происходит ошибка, API дополнительно возвращает ее описание.

Сохранение чека прихода

Метод предназначен для создания нового чека прихода с указанным receiptNumber. Также позволяет обновить уже существующий чек прихода при повторном запросе с тем же receiptNumber. Метод возвращает тело чека, а также его тип и статус в дополнительных параметрах ответа.
Отправка чека по ФФД 1.2 не поддерживается для сервисов БИФИТ, Orange Data и Chekonline.
Отправка чека по ФФД 1.05 не поддерживается для сервисов Билайн.
Если Вы хотите перейти с ФФД 1.05 на ФФД 1.2, то отправьте заявку в поддержку ecom@raiffeisen.ru

header Parameters
Authorization
required
Request Body schema: application/json;charset=UTF-8
receiptNumber
required
string <A-Za-z0-9_-> <= 99 characters

Уникальный номер чека

required
object

Данные о покупателе

required
Array of objects (ФФД 1.05 | ФФД 1.2) non-empty unique

Позиции чека

Array of objects (платежи) non-empty unique

Данные об оплате
Объект заполняется только для чеков с зачетом аванса или частичной предоплаты. Если чек содержит только безналичный вид оплаты (без зачета аванса/частичной предоплаты), то объект payments не заполняется.
Если payments не передан, то по умолчанию заполняется безналичным видом оплаты и ее суммой, которая равна сумме чека

total
required
number

Итоговая сумма чека в рублях. Допустимо 8 символов для целой части и 2 символа для дробной

Responses

Request samples

Content type
application/json;charset=UTF-8
Example
{
  • "receiptNumber": "3000827351831",
  • "client": {
    },
  • "items": [
    ],
  • "total": 1200
}

Response samples

Content type
application/json;charset=UTF-8
Example
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "SELL",
  • "status": "NEW",
  • "client": {
    },
  • "items": [
    ],
  • "total": 1200
}

Регистрация чека прихода

Метод предназначен для отправки чека прихода на регистрацию в ОФД. Метод возвращает тело чека, а также его тип и статус в дополнительных параметрах ответа. После отправки чека на регистрацию он будет недоступен для редактирования.

path Parameters
receiptNumber
required
string <= 99 characters

Уникальный номер чека

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request PUT 'https://test.ecom.raiffeisen.ru/api/fiscal/v1/receipts/sell/3000827351831' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json;charset=UTF-8
Example
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "SELL",
  • "status": "IN_PROGRESS",
  • "client": {
    },
  • "items": [
    ],
  • "total": 1200
}

Получение статуса чека прихода

Метод предназначен для получения актуального статуса чека прихода. Чек может принимать один из статусов:

  • "NEW" – чек создан и может быть отредактирован перед отправкой на регистрацию,
  • "IN_PROGRESS" – чек в процессе регистрации,
  • "DONE" – чек успешно зарегистрирован,
  • "FAILED" – при регистрации чека возникла ошибка,
  • "AWAITING" – чек в ожидании отправки на регистрацию (технический статус).
path Parameters
receiptNumber
required
string <= 99 characters

Уникальный номер чека

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/fiscal/v1/receipts/sell/3000827351831' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json;charset=UTF-8
Example
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "SELL",
  • "status": "DONE",
  • "client": {
    },
  • "items": [
    ],
  • "total": 1200,
  • "ofdUrl": "https://lk.platformaofd.ru/web/noauth/cheque?fn=7284440500012345&fp=1702712345&i=1234"
}

Сохранение чека возврата

Метод предназначен для создания нового чека возврата с указанным receiptNumber. Также позволяет обновить уже существующий чек возврата при повторном запросе с тем же receiptNumber. Метод возвращает тело чека, а также его тип и статус в дополнительных параметрах ответа.
Отправка чека по ФФД 1.2 не поддерживается для сервисов БИФИТ, Orange Data и Chekonline.
Отправка чека по ФФД 1.05 не поддерживается для сервисов Билайн.
Если Вы хотите перейти с ФФД 1.05 на ФФД 1.2, то отправьте заявку в поддержку ecom@raiffeisen.ru

header Parameters
Authorization
required
Request Body schema: application/json;charset=UTF-8
receiptNumber
required
string <A-Za-z0-9_-> <= 99 characters

Уникальный номер чека

required
object

Данные о покупателе

required
Array of objects (ФФД 1.05 | ФФД 1.2) non-empty unique

Позиции чека

Array of objects (платежи) non-empty unique

Данные об оплате
Объект заполняется только для чеков с зачетом аванса или частичной предоплаты. Если чек содержит только безналичный вид оплаты (без зачета аванса/частичной предоплаты), то объект payments не заполняется.
Если payments не передан, то по умолчанию заполняется безналичным видом оплаты и ее суммой, которая равна сумме чека

total
required
number

Итоговая сумма чека в рублях. Допустимо 8 символов для целой части и 2 символа для дробной

Responses

Request samples

Content type
application/json;charset=UTF-8
Example
{
  • "receiptNumber": "3000827351831",
  • "client": {
    },
  • "items": [
    ],
  • "total": 1200
}

Response samples

Content type
application/json;charset=UTF-8
Example
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "REFUND",
  • "status": "NEW",
  • "client": {
    },
  • "items": [
    ],
  • "total": 1200
}

Регистрация чека возврата

Метод предназначен для отправки чека возврата на регистрацию в ОФД. Метод возвращает тело чека, а также его тип и статус в дополнительных параметрах ответа. После отправки чека на регистрацию он будет недоступен для редактирования.

path Parameters
receiptNumber
required
string <= 99 characters

Уникальный номер чека

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request PUT 'https://test.ecom.raiffeisen.ru/api/fiscal/v1/receipts/refund/3000827351831' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json;charset=UTF-8
Example
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "REFUND",
  • "status": "IN_PROGRESS",
  • "client": {
    },
  • "items": [
    ],
  • "total": 1200
}

Получение статуса чека возврата

Метод предназначен для получения актуального статуса чека возврата. Чек может принимать один из статусов:

  • "NEW" – чек создан и может быть отредактирован перед отправкой на регистрацию,
  • "IN_PROGRESS" – чек в процессе регистрации,
  • "DONE" – чек успешно зарегистрирован,
  • "FAILED" – при регистрации чека возникла ошибка,
  • "AWAITING" – чек в ожидании отправки на регистрацию (технический статус).
path Parameters
receiptNumber
required
string <= 99 characters

Уникальный номер чека

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/fiscal/v1/receipts/refund/3000827351831' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json;charset=UTF-8
Example
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "REFUND",
  • "status": "DONE",
  • "client": {
    },
  • "items": [
    ],
  • "total": 1200,
  • "ofdUrl": "https://lk.platformaofd.ru/web/noauth/cheque?fn=7284440500012345&fp=1702712345&i=1234"
}

Справочник ошибок

Стандартный ответ сервиса содержит код сообщения (code). Если в процессе обработки запроса произойдет логическая ошибка, API вернет описание ошибки (message).

Описание основных ошибок:

code message
FISCAL_CLIENT_NOT_FOUND Фискальный клиент {value} не найден
MERCHANT_NOT_FOUND Мерчант с publicId = {value} не зарегистрирован в сервисе
CREDENTIALS_NOT_FOUND Учетные данные ОФД для мерчанта с publicId = {value} не найдены
RECEIPT_TYPE_NOT_SUPPORTED Регистрация чеков типа {value} не поддерживается
RECEIPT_VALIDATION_FAILED Чек не прошел валидацию. Причина: {value}
RECEIPT_NOT_FOUND Чек {value} не найден
RECEIPT_FOR_ORDER_NOT_FOUND Чек для заказа {value} не найден
RECEIPT_STATUS_CONFLICT Чек {value} в статусе {value}, действие невозможно
TOKEN_REQUEST_FAILED Не удалось получить токен для отправки чека в ОФД
RECEIPT_REGISTRATION_FAILED Не удалось зарегистрировать чек {value}
STATUS_REQUEST_FAILED Не удалось запросить статус чека ofdId = {value} мерчанта с publicId = {value}
USER_PERMISSIONS_VALIDATION_FAILED Мерчант с publicId {value} не прошел валидацию user permissions

06.10.2021

  • Первоначальная версия документа 1.0

08.12.2021

Версия документации 1.1:

  • Обновление файла до версии OpenAPI 3.0
  • Перенос документации на новый URL https://pay.raif.ru/
  • Внесение небольших правок

18.01.2022

  • В чеки прихода и расхода добавлены новые параметры для агентских операций: agentType, supplierInfo. Дополнена структура запроса на создание чека и ответ на него

25.03.2022

  • В модель чека добавлен параметр paymentMode для передачи способа расчёта (100% предоплата, полный расчет)

15.04.2022

  • В документацию добавлен партнер "БИФИТ", приведена инструкция по подключению онлайн-кассы сервиса БИФИТ
  • Добавлены примеры запроса на сохранение чека (по агентским операциям и без них)
  • Дополнено правило заполнения номеклатурного кода для партнера "БИФИТ"
  • Небольшие правки по тексту

26.08.2022

  • Добавлен ФФД 1.2 для сервиса "АТОЛ Онлайн"

30.09.2022

  • Реализована поддержка авансовых чеков и чеков частичной предоплаты

13.02.2023

  • Добавлен ФФД 1.2 для сервиса "OFD.ru"

22.07.2024

  • В документации объединены форматы фискальных документов (ФФД 1.05 и 1.2)