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

Download OpenAPI specification:Download

Support e-mail: ecom@raiffeisen.ru

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

Оплата по 54-ФЗ

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

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

Схема работы:

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

Услуга фискализации чеков через онлайн-кассу доступна для клиентов банка, подключивших один из продуктов:

  • Интернет-эквайринг
  • СБП (только для оплаты на сайте)

OFD.ru

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

В заявке необходимо указать данные:

  • Поставщик кассового оборудования – OFD.ru
  • Идентификаторы мерчантов (publicId)
  • Применяемая система налогообложения
  • E-mail (для получения чека, если E-mail не указан покупателем)
  • Логин, пароль и идентификатор группы ККТ от OFD.ru (см. ниже)

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

  1. Отправьте заявку в банк одним из способов:
  • По E-mail ecom@raiffeisen.ru. Пример заявки доступнен при нажатии на E-mail
  • Через менеджера банка. Для этого отправьте ему безопасным способом необходимые для подключения данные.

АТОЛ Онлайн

  1. Зарегистрируйтесь в сервисе "АТОЛ Онлайн" и подключите онлайн-кассу
  2. Заключите договор с оператором фискальных данных
  3. Составьте заявку на подключение

В заявке необходимо указать данные:

  • Поставщик кассового оборудования – "АТОЛ Онлайн"
  • Идентификаторы мерчантов (publicId)
  • Применяемая система налогообложения
  • E-mail (для получения чека, если E-mail не указан покупателем)
  • Логин, пароль и идентификатор группы ККТ от "АТОЛ Онлайн" (см. ниже)

Чтобы получить логин, пароль и идентификатор, зайдите в личный кабинет "АТОЛ Онлайн". Выберите раздел "Мои компании", нажмите кнопку "Настройки интегратора". Скачается XML-файл с настройками, найдите в файле элемент access, в нём будут все три параметра: login, password, group_code. Если возникли трудности, обратитесь в техподдержку "АТОЛ Онлайн".

  1. Отправьте заявку в банк одним из способов:
  • По E-mail ecom@raiffeisen.ru. Пример заявки доступнен при нажатии на E-mail
  • Через менеджера банка. Для этого отправьте ему безопасным способом необходимые для подключения данные.

Чек-Онлайн

  1. Зарегистрируйтесь в сервисе "Чек-Онлайн" и подключите онлайн-кассу
  2. Заключите договор с оператором фискальных данных
  3. Составьте заявку на подключение

В заявке необходимо указать данные:

  • Поставщик кассового оборудования – "Чек-Онлайн"
  • Идентификаторы мерчантов (publicId)
  • Применяемая система налогообложения
  • E-mail (для получения чека, если E-mail не указан покупателем)
  • Логин, пароль и идентификатор группы ККТ от "Чек-Онлайн" (см. ниже)

Чтобы получить логин и пароль, зайдите в личный кабинет клиента. Откройте раздел "Предприятия", найдите в списке нужную компанию и нажмите на иконку в поле "Авторизация". Откроется раздел, в котором можно выбрать существующие логин и пароль или сгенерировать новые. Для получения идентификатора группы ККТ вернитесь в раздел "Предприятия" и выберите нужную компанию из списка. В открывшемся профиле предприятия скопируйте API Group ID.

  1. Отправьте заявку в банк одним из способов:
  • По E-mail ecom@raiffeisen.ru. Пример заявки доступнен при нажатии на E-mail
  • Через менеджера банка. Для этого отправьте ему безопасным способом необходимые для подключения данные.

БИФИТ

  1. Заключите договор с БИФИТ на аренду ККТ
  2. Оплатите аренду ККТ и ФН. БИФИТ предоставит бесплатное подключение к ОФД Яндекс. При необходимости можно подключиться к другому ОФД. Для этого в ЛК найдите № ККТ и № ФН и выполните регистрацию в ОФД на свой выбор
  3. Составьте заявку на подключение

В заявке необходимо указать данные:

  • Поставщик кассового оборудования – БИФИТ
  • Идентификаторы мерчантов (publicId)
  • Применяемая система налогообложения
  • E-mail (для получения чека, если E-mail не указан покупателем)
  • Токен коннектора и идентификатор ККТ в системе БИФИТ (см. ниже)

Для получения данных по подключенной кассе в БИФИТ перейдите в личный кабинет, откройте пункт меню "Бифит Онлайн" и перейдите в раздел "Коннекторы ККТ". Создайте токен коннектора и привяжите к нему кассу. Скопируйте токен коннектора и заводской номер ККТ (идентификатор ККТ).

  1. Отправьте заявку в банк одним из способов:
  • По E-mail ecom@raiffeisen.ru. Пример заявки доступнен при нажатии на E-mail
  • Через менеджера банка. Для этого отправьте ему безопасным способом необходимые для подключения данные.

Авторизация

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

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

header Parameters
Authorization
required
Content-Type
required
string

application/json;charset=UTF-8

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 ]

Позиции чека

total
required
number

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

Responses

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_PREPAYMENT",
      • "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
{
  • "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_PREPAYMENT",
      • "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
}

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

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

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": "NEW",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадные конфеты",
      • "price": 1000,
      • "quantity": 1.2,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PREPAYMENT",
      • "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

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": "NEW",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадные конфеты",
      • "price": 1000,
      • "quantity": 1.2,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PREPAYMENT",
      • "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
}

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

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

header Parameters
Authorization
required
Content-Type
required
string

application/json;charset=UTF-8

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 ]

Позиции чека

total
required
number

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

Responses

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_PREPAYMENT",
      • "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
{
  • "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_PREPAYMENT",
      • "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
}

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

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

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": "SELL",
  • "status": "NEW",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадные конфеты",
      • "price": 1000,
      • "quantity": 1.2,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PREPAYMENT",
      • "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

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": "SELL",
  • "status": "NEW",
  • "client": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name":