API для фискализации чеков Raif Pay (1.1)
Download OpenAPI specification:Download
Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/fiscal.yaml
По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.Клиенты Райффайзенбанка, подключившие интернет-эквайринг, также могут воспользоваться услугой фискализации чеков через онлайн-кассу. Пошаговые инструкции приведены ниже.
Клиенты Райффайзенбанка, подключившие интернет-эквайринг, также могут воспользоваться услугой фискализации чеков через онлайн-кассу. Пошаговые инструкции приведены ниже.
| Поставщик кассового оборудования | ФФД 1.05 | ФФД 1.2 |
|---|---|---|
| АТОЛ Онлайн | + | + |
| Билайн | - | + |
| БИФИТ | + | - |
| Чек-Онлайн | + | - |
| Эвотор | + | + |
| LIFE PAY | + | + |
| ОFD.ru | + | + |
| Orange Data | + | + |
| Модулькасса | - | + |
Поддерживает ФФД 1.05 и ФФД 1.2.
- Зарегистрируйтесь в сервисе "АТОЛ Онлайн" и подключите онлайн-кассу
- Заключите договор с оператором фискальных данных
- Зайдите в личный кабинет "АТОЛ Онлайн", чтобы получить логин, пароль и идентификатор. Выберите раздел "Мои компании", нажмите кнопку "Настройки интегратора". Скачается XML-файл с настройками, найдите в файле элемент access, в нём будут все три параметра: login, password, group_code. Если возникли трудности, обратитесь в техподдержку "АТОЛ Онлайн".
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
Поддерживает ФФД 1.2
- Зарегистрируйтесь в сервисе “Облачные кассы Билайн” и подключите онлайн-кассу
- После подключения облачной кассы в личном кабинете Билайн запомните полученный логин и установленный пароль. Эти данные понадобятся на следующем шаге.
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
Для идентификатора группы ККТ используйте название “ecom”.
Поддерживает ФФД 1.05
- Заключите договор с БИФИТ на аренду ККТ
- Оплатите аренду ККТ и ФН. БИФИТ предоставит бесплатное подключение к ОФД Яндекс. При необходимости можно подключиться к другому ОФД. Для этого в ЛК найдите № ККТ и № ФН и выполните регистрацию в ОФД на свой выбор
- Перейдите в личный кабинет БИФИТ для получения данных по подключенной кассе. Откройте пункт меню «Бифит Онлайн» и перейдите в раздел «Коннекторы ККТ». Создайте токен коннектора и привяжите к нему кассу. Скопируйте токен коннектора и заводской номер ККТ (идентификатор ККТ)
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
Поддерживает ФФД 1.05
- Зарегистрируйтесь в сервисе "Чек-Онлайн" и подключите онлайн-кассу
- Заключите договор с оператором фискальных данных
- Зайдите в личный кабинет клиента, чтобы получить логин и пароль. Откройте раздел "Предприятия", найдите в списке нужную компанию и нажмите на иконку в поле "Авторизация". Откроется раздел, в котором можно выбрать существующие логин и пароль или сгенерировать новые.Для получения идентификатора группы ККТ вернитесь в раздел "Предприятия" и выберите нужную компанию из списка. В открывшемся профиле предприятия скопируйте API Group ID. Эти данные понадобятся на следующем шаге.
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
Поддерживает ФФД 1.05 и ФФД 1.2
- Оставьте заявку на облачную онлайн-кассу на сайте Эвотор
- После подключения облачной кассы зайдите в личный кабинет Эвотор и получите приветственное письмо на E-mail. В личном кабинете и в письме содержатся логин, пароль и идентификатор группы касс. Скопируйте эти данные.
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
Поддерживает ФФД 1.05 и ФФД 1.2
- Оставьте заявку на облачную онлайн-кассу по ссылке. В заявке в поле Продукт укажите "Облачная касса".
Поля для ИНН, номера телефона, имени и E-mail обязательны к заполнению. В поле "Комментарий" при необходимости можно указать дополнительную информацию. Например, "Позвонить по заявке завтра после 14:00" - После подключения облачной кассы зайдите в личный кабинет LIFE PAY → Настройки → Разработчикам. В этом разделе скопируйте API KEY
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
В поле Логин укажите номер телефона в формате 7xxxxxxxxxx, а в поле Пароль - API KEY, скопированный ранее
Поддерживает ФФД 1.05 и ФФД 1.2
- Подключите онлайн-кассу в сервисе OFD.ru
- Зарегистрируйте кассу в ФНС через сервис Ferma по инструкции
Для получения данных по подключенной кассе в OFD.ru перейдите в раздел Ferma в личном кабинете клиента и пролистайте до виджета "Реквизиты доступа". Скопируйте логин, пароль и идентификатор группы ККТ для подключения. Эти данные понадобятся на следующем шаге.
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
Поддерживает ФФД 1.05 и ФФД 1.2
- Зарегистрируйтесь в системе “Orange Data” и подключите онлайн-кассу
- В разделе “Интеграция” ЛК Orange Data сгенерируйте файлы сертификации и пару ключей RSA.
- Для получения логина и пароля направьте следующие данные на E-mail api@orangedata.ru с указанием темы письма "Запрос данных Райффайзен Банк":
- ИНН
- Файл сертификата .pfx, private_key.xml и public_key.xml, созданные на шаге 2.
- Если Вы работаете с новыми ставками НДС 5%, 5/105%, 7%, 7/107%, то сообщите об этом в данном письме. На кассу будет установлено необходимое ПО.
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
Для идентификатора группы ККТ используйте название “Main” для ФФД 1.05 и “Main_2” для ФФД 1.2.
Поддерживает ФФД 1.2
- Оставьте заявку на облачную онлайн-кассу по ссылке
- После оплаты счета мы зарегистрируем кассу в ФНС, настроим и подключим к ОФД
- После подключения облачной кассы зайдите в личный кабинет Модулькассы и создайте точку продаж по инструкции
Если точка уже создана, то включите функцию приема чеков интернет-магазина:
- Выберите точку продаж, к которой хотите подключить интернет-магазин;
- Нажмите на точку продаж и включите функцию «Использовать для документов интернет магазина»;
- В окне редактирования скопируйте значение из поля "Идентификатор" - оно понадобится для подключения интеграции, его лучше сохранить в отдельном текстовом файле.
- Получите логин и пароль для подключения интеграции:
- Нажмите «Настройки» в верхнем правом углу;
- Перейдите в раздел «Сервисы»;
- Активируйте ползунок «Чеки интернет-магазина»;
- В новом окне появятся специальные логин и пароль для интеграции. Если эта комбинация вам не нравится, нажмите кнопку «Сгенерировать логин и пароль»;
- Скопируйте логин и пароль отдельно в документ, где ранее сохранили идентификатор точки продаж.
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
Для идентификатора группы ККТ используйте идентификатор точки продаж.
Для фискализации чеков через партнёра Райффайзенбанк предоставляет API из следующих запросов:
- Сохранение чека
- Регистрация чека
- Получение статуса чека
Взаимодействие осуществляется по протоколу HTTP с использованием методов POST, PUT, GET.
В описании каждого запроса явно указаны требуемые метод, адрес и параметры.
POST-запросы используют JSON-структуру, PUT- и GET-запросы работают со строками запросов.
Ответ любого метода возвращает HTTP-код. Если при обработке запроса происходит ошибка, API дополнительно возвращает ее описание.
Сохранение чека прихода
Метод предназначен для создания нового чека прихода с указанным receiptNumber. Также позволяет обновить уже существующий чек прихода при повторном запросе с тем же receiptNumber. Метод возвращает тело чека, а также его тип и статус в дополнительных параметрах ответа.
Отправка чека по ФФД 1.2 не поддерживается для сервисов БИФИТ и Chekonline.
Отправка чека по ФФД 1.05 не поддерживается для сервисов Билайн и Модулькасса.
Если Вы хотите перейти с ФФД 1.05 на ФФД 1.2, то отправьте заявку в поддержку ecom@raiffeisen.ru
header Parameters
| Authorization required | string |
Request Body schema: application/json;charset=UTF-8
| receiptNumber required | string <A-Za-z0-9_-> <= 99 characters Уникальный номер чека |
| timezone | string
|
| onlinePayment | boolean
|
required | object Данные о покупателе |
required | Array of objects (ФФД 1.05 | ФФД 1.2) non-empty unique Позиции чека |
Array of objects (платежи) non-empty unique Данные об оплате | |
| total required | number
|
object (additionalUserProperty)
|
Responses
Request samples
- Payload
- cURL
{- "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
- 200
- 400
- 403
- 409
- 415
{- "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"
}
], - "total": 1200
}Регистрация чека прихода
Метод предназначен для отправки чека прихода на регистрацию в ОФД. Метод возвращает тело чека, а также его тип и статус в дополнительных параметрах ответа. После отправки чека на регистрацию он будет недоступен для редактирования.
path Parameters
| receiptNumber required | string <= 99 characters Уникальный номер чека |
header Parameters
| Authorization required | string |
Responses
Request samples
- cURL
curl --location --request PUT 'https://test.ecom.raiffeisen.ru/api/fiscal/v1/receipts/sell/3000827351831' \ --header 'Authorization: Bearer eyJ0eXA***'
Response samples
- 200
- 403
- 404
- 409
- 500
{- "receiptNumber": "3000827351831",
- "receiptType": "SELL",
- "status": "IN_PROGRESS",
- "client": {
- "email": "customer@test.ru",
- "name": "Иванов Иван Иванович"
}, - "items": [
- {
- "name": "Шоколадные конфеты",
- "price": 1200,
- "quantity": 1,
- "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"
}
}
], - "total": 1200
}Получение статуса чека прихода
Метод предназначен для получения актуального статуса чека прихода. Чек может принимать один из статусов:
- "NEW" – чек создан и может быть отредактирован перед отправкой на регистрацию,
- "IN_PROGRESS" – чек в процессе регистрации,
- "DONE" – чек успешно зарегистрирован,
- "FAILED" – при регистрации чека возникла ошибка,
- "AWAITING" – чек в ожидании отправки на регистрацию (технический статус).
path Parameters
| receiptNumber required | string <= 99 characters Уникальный номер чека |
header Parameters
| Authorization required | string |
Responses
Request samples
- cURL
curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/fiscal/v1/receipts/sell/3000827351831' \ --header 'Authorization: Bearer eyJ0eXA***'
Response samples
- 200
- 403
- 404
{- "receiptNumber": "3000827351831",
- "receiptType": "SELL",
- "status": "DONE",
- "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"
}
}
], - "total": 1200,
- "ofdDocumentNumber": 133,
- "ofdDocumentAttribute": "3449555941"
}Сохранение чека возврата
Метод предназначен для создания нового чека возврата с указанным receiptNumber. Также позволяет обновить уже существующий чек возврата при повторном запросе с тем же receiptNumber. Метод возвращает тело чека, а также его тип и статус в дополнительных параметрах ответа.
Отправка чека по ФФД 1.2 не поддерживается для сервисов БИФИТ, Orange Data и Chekonline.
Отправка чека по ФФД 1.05 не поддерживается для сервисов Билайн и Модулькасса.
Если Вы хотите перейти с ФФД 1.05 на ФФД 1.2, то отправьте заявку в поддержку ecom@raiffeisen.ru
header Parameters
| Authorization required | string |
Request Body schema: application/json;charset=UTF-8
| receiptNumber required | string <A-Za-z0-9_-> <= 99 characters Уникальный номер чека |
| timezone | string
|
| onlinePayment | boolean
|
required | object Данные о покупателе |
required | Array of objects (ФФД 1.05 | ФФД 1.2) non-empty unique Позиции чека |
Array of objects (платежи) non-empty unique Данные об оплате | |
| total required | number
|
object (additionalUserProperty)
|
Responses
Request samples
- Payload
- cURL
{- "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
- 200
- 400
- 403
- 409
- 415
{- "receiptNumber": "3000827351831",
- "receiptType": "REFUND",
- "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"
}
], - "total": 1200
}Регистрация чека возврата
Метод предназначен для отправки чека возврата на регистрацию в ОФД. Метод возвращает тело чека, а также его тип и статус в дополнительных параметрах ответа. После отправки чека на регистрацию он будет недоступен для редактирования.
path Parameters
| receiptNumber required | string <= 99 characters Уникальный номер чека |
header Parameters
| Authorization required | string |
Responses
Request samples
- cURL
curl --location --request PUT 'https://test.ecom.raiffeisen.ru/api/fiscal/v1/receipts/refund/3000827351831' \ --header 'Authorization: Bearer eyJ0eXA***'
Response samples
- 200
- 403
- 404
- 409
- 500
{- "receiptNumber": "3000827351831",
- "receiptType": "REFUND",
- "status": "IN_PROGRESS",
- "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"
}
}
], - "total": 1200
}Получение статуса чека возврата
Метод предназначен для получения актуального статуса чека возврата. Чек может принимать один из статусов:
- "NEW" – чек создан и может быть отредактирован перед отправкой на регистрацию,
- "IN_PROGRESS" – чек в процессе регистрации,
- "DONE" – чек успешно зарегистрирован,
- "FAILED" – при регистрации чека возникла ошибка,
- "AWAITING" – чек в ожидании отправки на регистрацию (технический статус).
path Parameters
| receiptNumber required | string <= 99 characters Уникальный номер чека |
header Parameters
| Authorization required | string |
Responses
Request samples
- cURL
curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/fiscal/v1/receipts/refund/3000827351831' \ --header 'Authorization: Bearer eyJ0eXA***'
Response samples
- 200
- 403
- 404
{- "receiptNumber": "3000827351831",
- "receiptType": "REFUND",
- "status": "DONE",
- "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"
}
}
], - "total": 1200,
- "ofdDocumentNumber": 133,
- "ofdDocumentAttribute": "3449555941"
}Стандартный ответ сервиса содержит код сообщения (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 |
Версия документации 1.1:
- Обновление файла до версии OpenAPI 3.0
- Перенос документации на новый URL https://pay.raif.ru/
- Внесение небольших правок
- В чеки прихода и расхода добавлены новые параметры для агентских операций: agentType, supplierInfo. Дополнена структура запроса на создание чека и ответ на него
- В модель чека добавлен параметр paymentMode для передачи способа расчёта (100% предоплата, полный расчет)
- В документацию добавлен партнер "БИФИТ", приведена инструкция по подключению онлайн-кассы сервиса БИФИТ
- Добавлены примеры запроса на сохранение чека (по агентским операциям и без них)
- Дополнено правило заполнения номенклатурного кода для партнера "БИФИТ"
- Небольшие правки по тексту
- Добавлены новые значения параметра vatType (НДС чека по ставке 5%, НДС чека по расчетной ставке 5/105, НДС чека по ставке 7%, НДС чека по расчетной ставке 7/107)