Версия 11:52, 15 апреля 2022

Введение

Схема работы с ФП

Данное руководство описывает процедуру интеграции ИС (Информационной Системы) заказчика с Фискальным Процессингом (далее ФП) БИФИТ Онлайн. Описаны следующие процедуры:

Авторизация в ФП - процесс необходимый для подключения клиента к фискальному процессингу,
Формирование контент чека - формирование информации для дальнейшей отправки на фискализацию,
Отправка чека в ФП - передача контента чека в фискальный процессинг для дальнейшей фискализации,
Получение документа по ID - получение документа с фискальными признаками по его номеру.

Нумераторы

ReceiptType - тип фискального документа (тэг 1054)
SALE SALE_RETURN PURCHASE PURCHASE_RETURN	Приход Возврат прихода Расход Возврат расхода

TaxSystem - cистема налогообложения (тэг 1055). Если при регистрации устройства в ФНС было выбрано более одного режима налогообложения, то в TaxSystem необходимо указать, к какой системе налогообложения относится данный чек.
COMMON SIMPLIFIED SIMPLIFIED_WITH_EXPENSE COMMON_AGRICULTURAL PATENT	ОСН УСН доход УСН доход - расход ЕСХН ПАТЕНТ

CalculationMethod - признак способа расчета (тэг 1214).

PREPAY_FULL
PREPAY_PARTIAL
AVANS
FULL_PAY
PARTIAL_SETTLEMENT_AND_CREDIT
TRANSFER_ON_CREDIT
CREDIT_PAYMENT

Полная предварительная оплата до момента передачи предмета расчёта
Частичная предварительная оплата до момента передачи предмета расчёта
Аванс
Полная оплата, в том числе с учётом аванса (предварительной оплаты) в момент передачи предмета расчёта
Частичная оплата предмета расчёта в момент его передачи с последующей оплатой в кредит
Передача предмета расчёта без его оплаты в момент его передачи с последующей оплатой в кредит
Оплата предмета расчёта после его передачи с оплатой в кредит (оплата кредита)

vat - ставка НДС (тэг 1199).
WITHOUT_VAT VAT_0 VAT_10 VAT_20 VAT_110 VAT_120	Без НДС НДС 0% НДС 10% НДС 20% НДС 10/110 НДС 20/120

PaymentType - тип оплаты.
CASH CARD PREPAY POSTPAY OTHER	(тэг 1031) Сумма оплаты наличными (тэг 1081) Сумма оплата безналичными (тэг 1215) Сумма оплаты предоплатой (зачётом аванса) (тэг 1216) Сумма оплаты постоплатой (в кредит) (тэг 1217) Сумма оплаты встречным предоставлением

PaymentSubject - признак предмета расчета (тэг 1212).

PRODUCT
EXCISABLE_PRODUCT
JOB
SERVICE
GAMBLING_RATE
GAMBLING_WIN
LOTTERY_TICKET
LOTTERY_WIN
PROVISION_RID
PAYMENT
AGENCY
COMPOUND_SUBJECT
OTHER_SUBJECT
PROPERTY_LAW
NON_OPERATING_INCOME
INSURANCE_CONTRIBUTIONS
TRADE_FEE
RESORT_FEE
PLEDGE

Товар
Подакцизный товар
Работа
Услуга
Ставка азартной игры
Выигрыш азартной игры
Лотерейный билет
Выигрыш лотереи
Предоставление РИД
Платеж
Агентское вознаграждение
Составной предмет расчета
Иной предмет расчета
Имущественное право
Внереализованный доход
Страховые взносы
Торговый сбор
Курортный сбор
Залог

PaymentAddress - место расчётов (тэг 1187).
По умолчанию то, которое задано при регистрации. В этом поле можно указать адрес сайта, на котором сделан чек или место установки вендингового оборудования

address - телефон или электронный адрес покупателя (тэг 1008).
Телефон передаётся в формате "7ХХХХХХХХХХ"

items - массив товарных позиций (тэг 1059).

CALCULATIONMETHOD
PAYMENTSUBJECT
NAME
PRICE
QUANTITY
VAT
TOTAL

(тэг 1244) Признак способа расчета
(тэг 1212) Признак предмета расчета
(тэг 1030) Наименование товарной позиции. Не может быть пустым
(тэг 1079) Цена, цена указывается в рублях 100.00
(тэг 1023) Количество. Количество указывается дробных числах, если вам надо указать 937 грамм, а цена у вас за один килограмм - 0.937
(тэг 1199) Ставка НДС
(тэг 1043) Сумма товарной позиции

Авторизация при помощи токена коннектора

Токен коннектора - строка, содержащая символы и/или буквы и/или цифры. Это ссылка на одну или несколько облачных ККТ в сервисе БИФИТ Онлайн. Токен коннектора генерируется пользователем или партнером в ЛК БИФИТ Бизнес после оплаты аренды облачной ККТ. Таким образом, после авторизации по токену коннектора, все запросы обрабатываются на строго определенной/ых ККТ.

Примечание

Все ссылки будут указаны для тестового контура ФП! https://fp-test.bifit.com/processing-api/.../
Для отладки интеграции в тестовом контуре, используйте токен коннектора: P5cKbUUD9uSSrSlGdzspLblvBnD0GzTAE0cLmAPSEMxJ79DtLE
Адрес "боевого" контура ФП https://fp.bifit.com/processing-api/.../

Запрос	POST
URL: https://fp-test.bifit.com/processing-api/oauth/token	https://fp-test.bifit.com/processing-api/oauth/token

Request Body

type: x-www-form-urlencoded

token: токен коннектора ФП. Необходимо получить в ЛК БИФИТ Онлайн, либо у партнера БИФИТ КАССА.
client_id: передать значение "processing-connector-token"
client_secret: передать значение "processing-connector-token"
grant_type: передать значение "token"

token: "P5cKbUUD9uSSrSlGdzspLblvBnD0GzTAE0cLmAPSEMxJ79DtLE"
client_id: "processing-connector-token"
client_secret: "processing-connector-token"
grant_type: "token"

Response

access_token: токен доступа. Используется при отправке запросов ФП
token_type: тип токена
refresh_token: использовать для обновления токена доступа после истечении срока жизни (либо повторно авторизоваться с токеном коннектора)
expires_in: срок жизни токена доступа в секундах.
scope:
connector_id: ID коннектора
jti:

{
    "access_token": "eyJhbGciOiJSUzI1NiI...YQqpk7w",
    "token_type": "bearer",
    "refresh_token": "eyJhbGciOiJSUzI1Ni.._782S_MQ",
    "expires_in": 3599,
    "scope": "read write",
    "connector_id": 1,
    "jti": "2f22e02e-4e72-4b68-991b-6aec065d996c"
}

Авторизация при помощи refresh_token

По истечении времени жизни access_token (по умолчанию 1 час), Вы можете использовать механизм восстановления access_token по значению refresh_token, полученному при помощи авторизации по токену коннектора. Однако, для восстановления access_token, так же можно использовать повторную процедуру авторизации по токену коннектора.

Примечание

Все ссылки будут указаны для тестового контура ФП! https://fp-test.bifit.com/processing-api/.../
Адрес "боевого" контура ФП https://fp.bifit.com/processing-api/.../

Авторизация OAuth2	POST
URL: https://fp-test.bifit.com/processing-api/oauth/token	https://fp-test.bifit.com/processing-api/oauth/token

Request Body	type: x-www-form-urlencoded
refresh_token: полученный при авторизации по токену коннектора client_id: передать значение ":processing-connector-token" client_secret: передать значение ":processing-connector-token" grant_type: передать значение "refresh_token"	refresh_token: "eyJhbGciOiJSUzI1Ni.._782S_MQ" client_id: "processing-connector-token" client_secret: "processing-connector-token" grant_type: "refresh_token"

Response

access_token: токен доступа. Используется при отправке запросов ФП
token_type: тип токена
refresh_token: использовать для обновления токена доступа после истечении срока жизни (либо повторно авторизоваться с токеном коннектора)
expires_in: срок жизни токена доступа в секундах.
scope:
connector_id: ID коннектора
jti:

{
    "access_token": "ero3UNcffhlKdn5e76i...edfr_JU",
    "token_type": "bearer",
    "refresh_token": "tjlsoduopUIy76sdsf.._78tyfbv",
    "expires_in": 3599,
    "scope": "read write",
    "connector_id": 1,
    "jti": "2f22e02e-4e72-4b68-991b-6aec065d996c"
}

Формирование контента чека

JSON структура

type: тип фискального документа, см. раздел "Нумераторы" (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
taxSystem: система налогообложения, см. раздел "Нумераторы" (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
cashier: информация о кассире
- name: ФИО кассира, допускается вместе с ФИО указать должность кассира (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
- inn: ИНН кассира (не обязательный реквизит)
client: информация о клиенте
- address: электронный адрес или номер телефона (не обязательный реквизит)
items: массив, содержащий номенклатурные позиции
- calculationMethod: признак способа расчёта, см. раздел "Нумераторы" (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
- paymentSubject: признак предмета расчёта, см. раздел "Нумераторы" (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
- name: наименование товарной позиции (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
- price: цена товарной позиции с учетом примененной скидки/надбавки (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
- quantity: количество товарных позиций (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
- vat: НДС товарной позиции, по умолчанию передаётся значение "БЕЗ НДС" (не обязательный реквизит)
- total: сумма товарной позиции с учетом примененных скидок/надбавок
total: итоговая сумма чека. Содержит итоговую сумму всех товарных позиций в чеке (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
payments: типы оплаты. В чеке должен быть указан хотя бы один тип оплаты (ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ)
- CASH: сумма по типу оплаты наличными (не обязательный реквизит)

{
    "type": "SALE",
    "taxSystem": "COMMON",
    "cashier": {
        "name": "Иванов И.И."
    },
    "client": {
        "address": "7ХХХХХХХХХХ"
    },
    "items": [
        {
            "calculationMethod": "FULL_PAY",
            "paymentSubject": "SERVICE",
            "name": "Услуга",
            "price": 100,
            "quantity": 1,
            "vat": "VAT_20",
            "total": 100
        }
    ],
    "total": 100,
    "payments": {
        "CASH": 100
    }
}

Примечание

Полное описание всех полей присутствует в swagger`е по ссылке https://fp-test.bifit.com/processing-api/swagger-ui.html#

Отправка чека в фискальный процессинг

Запрос регистрации чека	POST
https://fp-test.bifit.com/processing-api/protected/documents/registration/receipts	https://fp-test.bifit.com/processing-api/protected/documents/registration/receipts

Request Headers

idempotency-key: ключ идемпотентности. Уникальный идентификатор документа в рамках сервиса БИФИТ Онлайн. Ключ генерируется на стороне клиента и обеспечивает невозможность повторного выполнения запроса регистрации чека на сервере. Варианты формирования ключа:
- Используйте GUID для генерации ключа идемпотентности (Рекомендуется)
- Используйте правило генерации ключа: SHA256(Локальный номер документа & PIN(4 символа) & Сумма чека(ххх.хх) & ДатаВремя(ДД.ММ.ГГГГ ЧЧ:ММ)) для случаев, когда необходимо воспроизвести ключ по исходным данным с ИС отправителя запросов
  - Локальный номер документа: Локальный инкрементируемый счетчик в ИС отправителя запросов;
  - PIN: Зафиксированное значение в ИС отправителя запросов;
  - Сумма чека: Сумма чека, переданная в переменную total;
  - Время чека: Время зафиксированное в ИС отправителя;

"idempotency-key": "sdftfc-KF784mkd-skdhkaasca_lf34hKxsf"

Пример:

curl -X POST \ 
https://fp-test.bifit.com/processing-api/protected/documents/registration/
receipts \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer access_token' \ -H 'Idempotency-Key: 
idempotency_key' \ 
-d '{
 "type": "SALE", 
 "taxSystem": "COMMON",
 "cashier": {
 "name": "Иванов И.И."
 },
"client": {
 "address": "7ХХХХХХХХХХ"
}, 
"items": [
 {
 "calculationMethod": "FULL_PAY",
 "paymentSubject": "SERVICE", 
 "name": "Услуга",
 "price": 100,
 "quantity": 1,
 "vat": "VAT_20",
 "total": 100
 } 
],
"total": 100, 
"payments": {
"CASH": 100 
 }
}'

В ответ вы получите идентификатор документа на процессинге (id)

Примечание
Полученные данные имеют ознакомительный характер, актуальные запросы можно посмотреть по адресу:

https://fp.bifit.com/processing-api/swagger-ui.html#/ основной контур
https://fp-test.bifit.com/processing-api/swagger-ui.html#/ тестовый контур

Получение документа по ID

Для получения чека по id необходимо выполнить GET-запрос по адресу https://fp-test.bifit.com/processing-api/protected/documents/{id} , где необходимо заменить {id} на полученный на предыдущем шаге идентификатор документа (id).

Ответ описан в swagger`е по ссылке https://fp-test.bifit.com/processing-api/swagger-ui.html#/

Пример:

curl -X GET \
https://fp-test.bifit.com/processing-api/protected/documents/{id}\
-H 'Authorization: Bearer access_token'

Оффлайн возможности фискального процессинга

Функционал фискального процессинга позволяет осуществлять формирование ссылки на чек даже в оффлайн режиме, путем генерации QR-кода с ссылкой на страницу отслеживания состояния чека.

Ссылка:

https://fp-test.bifit.com/processing-api/receipts/ + idempotency_key, сгенерированный при отправке чека.

@@ Строка 374: / Строка 374: @@
 = Отправка чека в фискальный процессинг =
-В Header`е указывается '''Idempotency-Key''', который генерируется следующим образом:
- SHA256("Номер чека(локальный счетчик на устройстве)/PIN(4 цифры)/Сумма чека(ххх.хх)/ДатаВремя(ДД.ММ.ГГГГ ЧЧ:ММ")
 {{ProductTable-2
 |title-left='''Запрос регистрации чека'''

Облачная Касса: Интеграция с Фискальным Процессингом: различия между версиями

Версия 11:52, 15 апреля 2022

Содержание

Введение

Нумераторы

Авторизация при помощи токена коннектора

Авторизация при помощи refresh_token

Формирование контента чека

Отправка чека в фискальный процессинг

Получение документа по ID

Оффлайн возможности фискального процессинга

Навигация

Облачная Касса: Интеграция с Фискальным Процессингом: различия между версиями

Версия 11:52, 15 апреля 2022

Введение

Нумераторы

Авторизация при помощи токена коннектора

Авторизация при помощи refresh_token

Формирование контента чека

Отправка чека в фискальный процессинг

Получение документа по ID

Оффлайн возможности фискального процессинга

Навигация

Поиск