Raiff logo
Documentation Powered by ReDoc

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

OFD.ru

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

Для получения данных по подключенной кассе в OFD.ru перейдите в раздел Ferma в личном кабинете клиента и пролистайте до виджета "Реквизиты доступа". Скопируйте логин, пароль и идентификатор группы ККТ для подключения. Эти данные понадобятся на следующем шаге.

  1. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить

Чек-Онлайн

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

БИФИТ

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

LIFE PAY

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

Эвотор

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

Авторизация

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

  • 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 не поддерживается для сервисов БИФИТ и Chekonline.
Если Вы хотите перейти с ФФД 1.05 на ФФД 1.2, то отправьте заявку в поддержку ecom@raiffeisen.ru

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

Уникальный номер чека. Создается на стороне мерчанта

required
object

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

required
Array of objects (ФФД 1.05) non-empty unique [ items ]

Позиции чека

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

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

total
required
number

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

Responses

Response Schema: application/json;charset=UTF-8
One of
receiptNumber
string <A-Za-z0-9_-> <= 99 characters

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

receiptType
string
Enum: "SELL" "REFUND"

Тип чека (чек прихода, чек возврата)

status
string
Enum: "NEW" "IN_PROGRESS" "DONE" "FAILED" "AWAITING"

Статус регистрации чека

object

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

Array of objects (ФФД 1.05) non-empty unique [ items ]

Позиции чека

Array of objects (платежи) unique [ items ]

Данные об оплате

total
number

Итоговая сумма чека в рублях

Request samples

Content type
application/json;charset=UTF-8
Example
Чек прихода (ФФД 1.05)
Чек прихода (ФФД 1.05)
Чек прихода по агентской операции (ФФД 1.05)
Чек прихода (ФФД 1.2)
{
  • "receiptNumber": "3000827351831",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадные конфеты",
      • "price": 1000,
      • "quantity": 1.2,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PAYMENT",
      • "measurementUnit": "кг",
      • "nomenclatureCode": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
      • "vatType": "VAT20"
      }
    ],
  • "total": 1200
}

Response samples

Content type
application/json;charset=UTF-8
Example
ФФД 1.05
ФФД 1.05
ФФД 1.2
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "SELL",
  • "status": "NEW",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадные конфеты",
      • "price": 1000,
      • "quantity": 1.2,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PAYMENT",
      • "measurementUnit": "кг",
      • "nomenclatureCode": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
      • "vatType": "VAT20",
      • "agentType": "ANOTHER",
      • "supplierInfo": {
        • "phone": "+79991234567",
        • "name": "ООО «Ромашка»",
        • "inn": "287381373424"
        }
      }
    ],
  • "payments": [
    • {
      • "type": "PREPAID",
      • "amount": 1200
      }
    ],
  • "total": 1200
}

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

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

path Parameters
receiptNumber
required
string <= 99 characters

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

header Parameters
Authorization
required

Responses

Response Schema: application/json;charset=UTF-8
One of
receiptNumber
string <A-Za-z0-9_-> <= 99 characters

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

receiptType
string
Enum: "SELL" "REFUND"

Тип чека (чек прихода, чек возврата)

status
string
Enum: "NEW" "IN_PROGRESS" "DONE" "FAILED" "AWAITING"

Статус регистрации чека

object

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

Array of objects (ФФД 1.05) non-empty unique [ items ]

Позиции чека

Array of objects (платежи) unique [ items ]

Данные об оплате

total
number

Итоговая сумма чека в рублях

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
ФФД 1.05
ФФД 1.05
ФФД 1.2
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "SELL",
  • "status": "NEW",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадные конфеты",
      • "price": 1000,
      • "quantity": 1.2,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PAYMENT",
      • "measurementUnit": "кг",
      • "nomenclatureCode": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
      • "vatType": "VAT20",
      • "agentType": "ANOTHER",
      • "supplierInfo": {
        • "phone": "+79991234567",
        • "name": "ООО «Ромашка»",
        • "inn": "287381373424"
        }
      }
    ],
  • "payments": [
    • {
      • "type": "PREPAID",
      • "amount": 1200
      }
    ],
  • "total": 1200
}

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

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

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

Метод возвращает тело чека, а также его тип и статус в дополнительных параметрах ответа.

path Parameters
receiptNumber
required
string <= 99 characters

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

header Parameters
Authorization
required

Responses

Response Schema: application/json;charset=UTF-8
One of
receiptNumber
string <A-Za-z0-9_-> <= 99 characters

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

receiptType
string
Enum: "SELL" "REFUND"

Тип чека (чек прихода, чек возврата)

status
string
Enum: "NEW" "IN_PROGRESS" "DONE" "FAILED" "AWAITING"

Статус регистрации чека

object

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

Array of objects (ФФД 1.05) non-empty unique [ items ]

Позиции чека

Array of objects (платежи) unique [ items ]

Данные об оплате

total
number

Итоговая сумма чека в рублях

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
ФФД 1.05
ФФД 1.05
ФФД 1.2
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "SELL",
  • "status": "NEW",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадные конфеты",
      • "price": 1000,
      • "quantity": 1.2,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PAYMENT",
      • "measurementUnit": "кг",
      • "nomenclatureCode": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
      • "vatType": "VAT20",
      • "agentType": "ANOTHER",
      • "supplierInfo": {
        • "phone": "+79991234567",
        • "name": "ООО «Ромашка»",
        • "inn": "287381373424"
        }
      }
    ],
  • "payments": [
    • {
      • "type": "PREPAID",
      • "amount": 1200
      }
    ],
  • "total": 1200
}

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

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

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

Уникальный номер чека. Создается на стороне мерчанта

required
object

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

required
Array of objects (ФФД 1.05) non-empty unique [ items ]

Позиции чека

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

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

total
required
number

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

Responses

Response Schema: application/json;charset=UTF-8
One of
receiptNumber
string <A-Za-z0-9_-> <= 99 characters

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

receiptType
string
Enum: "SELL" "REFUND"

Тип чека (чек прихода, чек возврата)

status
string
Enum: "NEW" "IN_PROGRESS" "DONE" "FAILED" "AWAITING"

Статус регистрации чека

object

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

Array of objects (ФФД 1.05) non-empty unique [ items ]

Позиции чека

Array of objects (платежи) unique [ items ]

Данные об оплате

total
number

Итоговая сумма чека в рублях

Request samples

Content type
application/json;charset=UTF-8
Example
Чек возврата
Чек возврата
Чек возврата (по агентской операции)
{
  • "receiptNumber": "3000827351831",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадные конфеты",
      • "price": 1000,
      • "quantity": 1.2,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PAYMENT",
      • "measurementUnit": "кг",
      • "nomenclatureCode": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
      • "vatType": "VAT20"
      }
    ],
  • "total": 1200
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "SELL",
  • "status": "NEW",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадные конфеты",
      • "price": 1000,
      • "quantity": 1.2,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PAYMENT",
      • "measurementUnit": "кг",
      • "nomenclatureCode": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
      • "vatType": "VAT20",
      • "agentType": "ANOTHER",
      • "supplierInfo": {
        • "phone": "+79991234567",
        • "name": "ООО «Ромашка»",
        • "inn":