Облачная Касса: Интеграция с Фискальным Процессингом
Версия от 19:03, 1 сентября 2022; Merkulov (обсуждение | вклад)
Введение
Данное руководство описывает процедуру интеграции ИС (Информационной Системы) заказчика с Фискальным Процессингом (далее ФП) БИФИТ Онлайн.
В документе описаны следующие процедуры:
- Авторизация в ФП - процесс необходимый для подключения клиента к фискальному процессингу,
- Формирование контент чека - формирование информации для дальнейшей отправки на фискализацию,
- Отправка чека в ФП - передача контента чека в фискальный процессинг для дальнейшей фискализации,
- Получение документа по ID - получение документа с фискальными признаками по его номеру.
|
Нумераторы
| ReceiptType - тип фискального документа (тэг 1054) | |
|
|
| TaxSystem - cистема налогообложения (тэг 1055). Если при регистрации устройства в ФНС было выбрано более одного режима налогообложения, то в TaxSystem необходимо указать, к какой системе налогообложения относится данный чек. | |
|
|
| CalculationMethod - признак способа расчета (тэг 1214). | |
|
|
| vat - ставка НДС (тэг 1199). | |
|
|
| PaymentType - тип оплаты. | |
|
|
| PaymentSubject - признак предмета расчета (тэг 1212). | |
|
|
| PaymentAddress - место расчётов (тэг 1187). | |
| По умолчанию то, которое задано при регистрации. В этом поле можно указать адрес сайта, на котором сделан чек или место установки вендингового оборудования |
| address - телефон или электронный адрес покупателя (тэг 1008). | |
| Телефон передаётся в формате "7ХХХХХХХХХХ" |
| items - массив товарных позиций (тэг 1059). | |
|
|
Авторизация в OAuth2 при помощи токена коннектора
Токен коннектора - строка, содержащая символы и/или буквы и/или цифры. Это ссылка на одну или несколько облачных ККТ в сервисе БИФИТ Онлайн. Токен коннектора генерируется пользователем или партнером в ЛК БИФИТ Бизнес после оплаты аренды облачной ККТ. Таким образом, после авторизации по токену коннектора, все запросы обрабатываются на строго определенной/ых ККТ.
Примечание
- Все ссылки будут указаны для тестового контура ФП! 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: "P5cKbUUD9uSSrSlGdzspLblvBnD0GzTAE0cLmAPSEMxJ79DtLE"
client_id: "processing-connector-token"
client_secret: "processing-connector-token"
grant_type: "token"
|
| Response | |
|
{
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"
}
|
Авторизация в OAuth2 по 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: "eyJhbGciOiJSUzI1Ni.._782S_MQ"
client_id: "processing-connector-token"
client_secret: "processing-connector-token"
grant_type: "refresh_token"
|
| Response | |
|
{
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"
}
|
Отправка документа на фискализацию в процессинг
| Запрос регистрации чека | 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 | |
|
authorization: "Bearer ero3UNcffhlKdn5e76i...edfr_JU"
idempotency-key: "sdftfc-KF784mkd-skdhkaasca_lf34hKxsf"
|
| Request Body | JSON структура |
|
{
"type": "SALE",
"taxSystem": "COMMON",
"cashier": {
"name": "Иванов И.И."
},
"client": {
"address": "test@test.com"
},
"items": [
{
"calculationMethod": "FULL_PAY",
"paymentSubject": "SERVICE",
"name": "Услуга",
"price": 100.00,
"quantity": 1.500,
"vat": "VAT_20",
"total": 150.00
}
],
"total": 150.00,
"payments": {
"CASH": 150.00
}
}
|
| Response | |
|
254934 |
Запрос информации о документе по ID
| Запрос информации о чеке по ID | GET |
|
https://fp-test.bifit.com/processing-api/protected/documents/{id} Используйте ID документа, полученного на предыдущем шаге, для получения информации о фискализации и контента чека. |
https://fp-test.bifit.com/processing-api/protected/documents/254934 |
| Request Headers | |
|
authorization: "Bearer ero3UNcffhlKdn5e76i...edfr_JU"
|
| Response | ||
Ответ содержит информацию о состоянии отправленного на фискализацию документа. В случае успешной фискализации, будет содержать следующую:
|
{
"id": 254934,
"executorType": "CONNECTOR",
"executorId": 1,
"kkmId": 50,
"kkm": {
"id": 50,
"vendor": "БИФИТ",
"model": "БФР-112ФС",
"factoryNumber": "98065732341002",
"inn": "7724923302",
"registrationNumber": "0000000001053073",
"fdNumber": "9999078902002260",
"fdStatus": null,
"taxSystems": [
"COMMON",
"SIMPLIFIED",
"SIMPLIFIED_WITH_EXPENSE",
"ENVD",
"COMMON_AGRICULTURAL"
],
"lastDocumentDate": 1614173792888,
"brokerVersion": "3.36"
},
"idempotencyKey": "b28463ba-48b6-4d95-8612-d2027d804f42",
"type": "RECEIPT",
"request": {
"type": "SALE",
"taxSystem": "COMMON",
"cashier": {
"name": "Иванов И.И."
},
"client": {
"address": "test@test.com"
},
"items": [
{
"calculationMethod": "FULL_PAY",
"paymentSubject": "SERVICE",
"name": "Услуга",
"price": 100.00,
"quantity": 1.500,
"vat": "VAT_20",
"total": 150.00
}
],
"total": 150.00,
"payments": {
"CASH": 150.00
}
},
"response": {
"raw": "--------------------------------\n Кассовый чек \n ПРИХОД \n АО БИФИТ \nг.Москва, Ниж. Первомайская, д.4\n 6 \n 15:04:22 12:17 \n--------------------------------\nУслуга \n1.5 * 100.00 = 150.00\nНДС 20% \nУСЛУГА \n--------------------------------\nИТОГ = 150.00\nНАЛИЧНЫМИ = 150.00\nСУММА НДС 20% = 25.00\nЭЛ.АДР.ПОКУПАТЕЛЯ test@test.com\nЭЛ.АДР.ОТПРАВИТЕЛЯ \n noname@email.com\nКАССИР Иванов И.И.\nЧЕК 39\nСМЕНА 299\nСНО ОСН\nИНН 7724923302\nРН ККТ 0000000001053073\nФН 9999078902002260\nФД 5088\nФП 3705633526\n",
"shiftNumber": 299,
"receiptNumber": 39
},
"fiscalDocument": 5088,
"fiscalAmount": 150.00,
"fiscalTime": 1650014239472,
"fiscalSign": "3705633526",
"fiscalDrive": "9999078902002260",
"status": "SUCCESS",
"created": 1650014238962,
"changed": 1650014240672
}
|
Оффлайн возможности фискального процессинга
Фискальный процессинг позволяет сформировать HTML страницу с информацией о чеке, для предоставления клиенту, в "оффлайн режиме". Такая возможность обеспечивается за счет использования специального GET запроса без авторизации с использованием ключа идемпотентности. В случае, если документ не может быть передан в процессинг по причине отсутствия связи между клиентом и сервером, сервер вернет информацию о необходимости подождать завершения процесса обработки фискального документа. Такой запрос можно представить в виде QR кода, для считывания камерой смартфона.
| Запрос информации о чеке по Ключу идемпотентности | GET |
|
https://fp-test.bifit.com/processing-api/receipts/{idempotency_key} Используйте ID документа, полученного на предыдущем шаге, для получения информации о фискализации и контента чека. |
https://fp-test.bifit.com/processing-api/receipts/b28463ba-48b6-4d95-8612-d2027d804f42 |
Документ отправлен в ФП, но связи с ФП нет
https://fp-test.bifit.com/processing-api/receipts/b28463ba-48b6-4d95-8612-d2027d804f42 |
Документ отправлен в ФП, и фискализировался
https://fp-test.bifit.com/processing-api/receipts/b28463ba-48b6-4d95-8612-d2027d804f42 |
 |
 |
Справочник Ошибок
| Структура ошибок в формировании запросов или авторизации | Структура ошибок в бизнес логике (некорректные документы, отсутствие прав и т.д) |
{
"error": String,
"error_description": String
}
|
{
"type": String,
"message": String,
"dependentErrors": Object
}
|
| Перечень статусов документов | |
|
| Перечень ошибок | |
| Если запрошенный по ID документ находится в статусе FAIL, это означает, что ККТ по каким-то причинам не фискализировала такую транзакцию. Перечень причин см. в правой части |
ERR20002:
statusCode: 503
code: ERR20002
description: Запрос не может быть выполнен. Попробуйте позже
ERR20005:
statusCode: 400
code: ERR20005
description: Некорректный запрос
ERR20008:
statusCode: 401
code: ERR20008
description: Некорректный пароль
ERR20012:
statusCode: 401
code: ERR20012
description: Доступ запрещен
ERR20013:
statusCode: 400
code: ERR20013
description: Ошибка ФН
ERR20014:
statusCode: 400
code: ERR20014
description: Некорректный запрос
ERR20015:
statusCode: 404
code: ERR20015
description: Неизвестный ФН
ERR20016:
statusCode: 400
code: ERR20016
description: Некорректный запрос
ERR20017:
statusCode: 400
code: ERR20017
description: Смена не открыта
ERR20018:
statusCode: 400
code: ERR20018
description: Смена превысила 24 часа
ERR20019:
statusCode: 400
code: ERR20019
description: Хост недоступен
|
См. также
- Отправка чека на повторную фискализацию
- Авторизация в OAuth2 при помощи токена коннектора
- Авторизация в OAuth2 по refresh token
- Отправка документа на фискализацию в процессинг
- Отправка документа на фискализацию в процессинг (маркированный товар)
- Отправка документа на фискализацию в процессинг (агентский товар)
- Запрос информации о документе по ID
- Оффлайн возможности фискального процессинга
- Справочник Ошибок (ФП)