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

Материал из Касса
Перейти к навигации Перейти к поиску
 
(не показаны 63 промежуточные версии 3 участников)
Строка 1: Строка 1:
= Введение =
= Введение =
[[File:Fp_scheme.png|мини|Схема работы с ФП]]
Данное руководство описывает процедуру интеграции ИС (Информационной Системы) заказчика с Фискальным Процессингом (далее ФП) '''БИФИТ Онлайн'''. <br>В документе описаны следующие процедуры:  
Данное руководство описывает процедуру интеграции ИС (Информационной Системы) заказчика с Фискальным Процессингом (далее ФП) '''БИФИТ Онлайн'''. Описаны следующие процедуры:  
* '''Авторизация в ФП''' - процесс необходимый для подключения клиента к фискальному процессингу,  
* '''Авторизация в ФП''' - процесс необходимый для подключения клиента к фискальному процессингу,  
* '''Формирование контент чека''' - формирование информации для дальнейшей отправки на фискализацию,  
* '''Формирование контент чека''' - формирование информации для дальнейшей отправки на фискализацию,  
* '''Отправка чека в ФП''' - передача контента чека в фискальный процессинг для дальнейшей фискализации,
* '''Отправка чека в ФП''' - передача контента чека в фискальный процессинг для дальнейшей фискализации,
* '''Получение документа по ID''' - получение документа с фискальными признаками по его номеру.
* '''Получение документа по ID''' - получение документа с фискальными признаками по его номеру.
<br clear="all"/>
{|align="center"
|-valign="top"
|[[File:Fp_scheme.png|Схема работы с ФП]]
|}


= Нумераторы =
= Нумераторы =
Строка 91: Строка 93:


{{ProductTable-2
{{ProductTable-2
|title-left='''PaymentType''' - тип оплаты.
|title-left='''Payments''' - тип оплаты.
|title-right=
|title-right=
|content-left=
|content-left=
Строка 133: Строка 135:
* '''RESORT_FEE'''
* '''RESORT_FEE'''
* '''PLEDGE'''
* '''PLEDGE'''
* '''CONSUMPTION'''
* '''CONTRIBUTIONS_MPI_SE'''
* '''CONTRIBUTIONS_MPI'''
* '''CONTRIBUTIONS_CHI_SE'''
* '''CONTRIBUTIONS_CHI'''
* '''CONTRIBUTIONS_MSI'''
* '''CASINO_PAYMENT'''
* '''MONEY_PAYMENT'''
* '''ATNM'''
* '''ATM'''
* '''TNM'''
* '''TM'''
|content-right=
|content-right=
&nbsp;
&nbsp;
Строка 154: Строка 169:
* Курортный сбор
* Курортный сбор
* Залог
* Залог
* Расход
* Вкзносы на ОПС ИП
* Взносы на ОПС
* Взносы на ОМС ИП
* Взносы на ОМС
* Взносы на ОСС
* Платеж казино
* Выплата
* Подакцизный маркируемый товар без КМ
* Подакцизный маркируемый товар с КМ
* Маркируемый товар без КМ
* Марируемый товар с КМ
|}}<br>
|}}<br>


Строка 193: Строка 220:
|}}<br>
|}}<br>


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


Строка 209: Строка 234:
|content-left= URL: https://fp-test.bifit.com/processing-api/oauth/token
|content-left= URL: https://fp-test.bifit.com/processing-api/oauth/token
|content-right=
|content-right=
<syntaxhighlight lang="URL">
<syntaxhighlight>
https://fp-test.bifit.com/processing-api/oauth/token
https://fp-test.bifit.com/processing-api/oauth/token
</syntaxhighlight>
</syntaxhighlight>
Строка 245: Строка 270:
<syntaxhighlight lang="JSON">
<syntaxhighlight lang="JSON">
{
{
     "access_token": "eyJhbGciOiJSUzI1NiI...YQqpk7w",
     access_token: "eyJhbGciOiJSUzI1NiI...YQqpk7w",
     "token_type": "bearer",
     token_type: "bearer",
     "refresh_token": "eyJhbGciOiJSUzI1Ni.._782S_MQ",
     refresh_token: "eyJhbGciOiJSUzI1Ni.._782S_MQ",
     "expires_in": 3599,
     expires_in: 3599,
     "scope": "read write",
     scope: "read write",
     "connector_id": 1,
     connector_id: 1,
     "jti": "2f22e02e-4e72-4b68-991b-6aec065d996c"
     jti: "2f22e02e-4e72-4b68-991b-6aec065d996c"
}
}
</syntaxhighlight>
</syntaxhighlight>
|}}<br>
|}}<br>


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


Строка 269: Строка 294:
|content-left= URL: https://fp-test.bifit.com/processing-api/oauth/token
|content-left= URL: https://fp-test.bifit.com/processing-api/oauth/token
|content-right=
|content-right=
<syntaxhighlight lang="URL">
<syntaxhighlight>
https://fp-test.bifit.com/processing-api/oauth/token
https://fp-test.bifit.com/processing-api/oauth/token
</syntaxhighlight>
</syntaxhighlight>
Строка 305: Строка 330:
<syntaxhighlight lang="JSON">
<syntaxhighlight lang="JSON">
{
{
     "access_token": "ero3UNcffhlKdn5e76i...edfr_JU",
     access_token: "ero3UNcffhlKdn5e76i...edfr_JU",
     "token_type": "bearer",
     token_type: "bearer",
     "refresh_token": "tjlsoduopUIy76sdsf.._78tyfbv",
     refresh_token: "tjlsoduopUIy76sdsf.._78tyfbv",
     "expires_in": 3599,
     expires_in: 3599,
     "scope": "read write",
     scope": "read write,
     "connector_id": 1,
     connector_id: 1,
     "jti": "2f22e02e-4e72-4b68-991b-6aec065d996c"
     jti: "2f22e02e-4e72-4b68-991b-6aec065d996c"
}
}
</syntaxhighlight>
</syntaxhighlight>
|}}<br>
|}}<br>


=Формирование контента чека=
 
= Отправка документа на фискализацию в процессинг =
{{ProductTable-2
|title-left='''Запрос регистрации чека'''
|title-right='''POST'''
|content-left= https://fp-test.bifit.com/processing-api/protected/documents/registration/receipts
|content-right=
<syntaxhighlight>
https://fp-test.bifit.com/processing-api/protected/documents/registration/receipts
</syntaxhighlight>
|}}<br>
 
{{ProductTable-2
|title-left= Request Headers
|title-right=
|content-left=&nbsp;
* '''authorization''': переменная для передачи access_token. Введите тип токена (в нашем случае слово "Bearer") перед значением '''access_token'''
* '''idempotency-key''': ключ идемпотентности. Уникальный идентификатор документа в рамках сервиса '''БИФИТ Онлайн'''. Ключ генерируется на стороне клиента и обеспечивает невозможность повторного выполнения запроса регистрации чека на сервере. Варианты формирования ключа:
** Используйте '''[https://ru.wikipedia.org/wiki/GUID GUID]''' для генерации ключа идемпотентности ('''Рекомендуется''')
** Используйте правило генерации ключа: '''SHA256(Локальный номер документа & PIN(4 символа) & Сумма чека(ххх.хх) & ДатаВремя(ДД.ММ.ГГГГ ЧЧ:ММ))''' для случаев, когда необходимо воспроизвести ключ по исходным данным с ИС отправителя запросов
*** '''Локальный номер документа''': Локальный инкрементируемый счетчик в ИС отправителя запросов;
*** '''PIN''': Зафиксированное значение в ИС отправителя запросов;
*** '''Сумма чека''': Сумма чека, переданная в переменную '''total''';
*** '''Время чека''': Время зафиксированное в ИС отправителя;
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
authorization: "Bearer ero3UNcffhlKdn5e76i...edfr_JU"
idempotency-key: "sdftfc-KF784mkd-skdhkaasca_lf34hKxsf"
</syntaxhighlight>
|}}<br>


{{ProductTable-2
{{ProductTable-2
|title-left=
|title-left=Request Body
|title-right=JSON структура
|title-right=JSON структура
|content-left=&nbsp;
|content-left=&nbsp;
Строка 328: Строка 382:
** '''inn''': ИНН кассира ('''не обязательный реквизит''')
** '''inn''': ИНН кассира ('''не обязательный реквизит''')
* '''client''': информация о клиенте
* '''client''': информация о клиенте
** '''address''': электронный адрес или номер телефона ('''не обязательный реквизит''')
** '''address''': электронный адрес или номер телефона ('''не обязательный реквизит''')
* '''items''': массив, содержащий номенклатурные позиции
* '''items''': массив, содержащий номенклатурные позиции
** '''calculationMethod''': признак способа расчёта, см. раздел "Нумераторы" ('''ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ''')
** '''calculationMethod''': признак способа расчёта, см. раздел "Нумераторы" ('''ОБЯЗАТЕЛЬНЫЙ РЕКВИЗИТ''')
Строка 349: Строка 403:
     },
     },
     "client": {
     "client": {
         "address": "7ХХХХХХХХХХ"
         "address": "test@test.com"
     },
     },
     "items": [
     "items": [
Строка 356: Строка 410:
             "paymentSubject": "SERVICE",
             "paymentSubject": "SERVICE",
             "name": "Услуга",
             "name": "Услуга",
             "price": 100,
             "price": 100.00,
             "quantity": 1,
             "quantity": 1.500,
             "vat": "VAT_20",
             "vat": "VAT_20",
             "total": 100
             "total": 150.00
         }
         }
     ],
     ],
     "total": 100,
     "total": 150.00,
     "payments": {
     "payments": {
         "CASH": 100
         "CASH": 150.00
     }
     }
}
}
Строка 370: Строка 424:
|}}<br>
|}}<br>


{{ Note | '''''Примечание'''''
{{ProductTable-2
* Полное описание всех полей присутствует в swagger`е по ссылке https://fp-test.bifit.com/processing-api/swagger-ui.html# |800}}
|title-left=Response
|title-right=
|content-left=&nbsp;
* Ответ сервера содержит '''ID''' зарегистрированного чека
|content-right=&nbsp;
<syntaxhighlight>
254934
</syntaxhighlight>
|}}<br>


= Отправка чека в фискальный процессинг =
= Запрос информации о документе по ID =
{{ProductTable-2
{{ProductTable-2
|title-left='''Запрос регистрации чека'''
|title-left='''Запрос информации о чеке по ID'''
|title-right='''POST'''
|title-right='''GET'''
|content-left= https://fp-test.bifit.com/processing-api/protected/documents/registration/receipts
|content-left=&nbsp;
|content-right=
https://fp-test.bifit.com/processing-api/protected/documents/{id}
<syntaxhighlight lang="URL">
''Используйте ID документа, полученного на предыдущем шаге, для получения информации о фискализации и контента чека.''
https://fp-test.bifit.com/processing-api/protected/documents/registration/receipts
|content-right=&nbsp;
<syntaxhighlight>
https://fp-test.bifit.com/processing-api/protected/documents/254934
</syntaxhighlight>
</syntaxhighlight>
|}}<br>
|}}<br>
Строка 386: Строка 450:
{{ProductTable-2
{{ProductTable-2
|title-left= Request Headers
|title-left= Request Headers
|title-right=&nbsp;
|content-left=&nbsp;
* '''authorization''': переменная для передачи access_token. Введите тип токена (в нашем случае слово "Bearer") перед значением '''access_token'''
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
authorization: "Bearer ero3UNcffhlKdn5e76i...edfr_JU"
</syntaxhighlight>
|}}<br>
{{ProductTable-2
|title-left=Response
|title-right=
|content-left=
Ответ содержит информацию о состоянии отправленного на фискализацию документа. В случае успешной фискализации, будет содержать следующую:
* Информацию о ККТ, на которой был фискализирован документ
* Исходный запрос
* Информацию для генерации QR:
** Тип документа
** Дата/время расчета (фискализации документа на ККТ)
** Сумма чека
** Номер фискального накопителя
** Номер фискального документа
** Фискальный признак документа
* Печатную форму фискального документа<br>
<TABLE width="260px"><tr><td><syntaxhighlight lang="JSON">
--------------------------------
          Кассовый чек         
            ПРИХОД           
            АО БИФИТ           
г.Москва, Ниж. Первомайская, д.4
              6               
        15:04:22 12:17       
--------------------------------
Услуга                         
1.5 * 100.00            = 150.00
НДС 20%                       
УСЛУГА                         
--------------------------------
ИТОГ                    = 150.00
НАЛИЧНЫМИ              = 150.00
СУММА НДС 20%            = 25.00
ЭЛ.АДР.ПОКУПАТЕЛЯ  test@test.com
ЭЛ.АДР.ОТПРАВИТЕЛЯ             
                noname@email.com
КАССИР              Иванов И.И.
ЧЕК                          39
СМЕНА                        299
СНО                          ОСН
ИНН                  7724923302
РН ККТ          0000000001053073
ФН              9999078902002260
ФД                          5088
ФП                    3705633526
</syntaxhighlight></td></tr></TABLE>
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
{
    "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
}
</syntaxhighlight>
|}}<br>
= Оффлайн возможности фискального процессинга =
Фискальный процессинг позволяет сформировать HTML страницу с информацией о чеке, для предоставления клиенту, в "оффлайн режиме". Такая возможность обеспечивается за счет использования специального GET запроса без авторизации с использованием ключа идемпотентности. В случае, если документ не может быть передан в процессинг по причине отсутствия связи между клиентом и сервером, сервер вернет информацию о необходимости подождать завершения процесса обработки фискального документа. Такой запрос можно представить в виде QR кода, для считывания камерой смартфона.
{{ProductTable-2
|title-left='''Запрос информации о чеке по Ключу идемпотентности'''
|title-right='''GET'''
|content-left=&nbsp;
https://fp-test.bifit.com/processing-api/receipts/{idempotency_key}
''Используйте ID документа, полученного на предыдущем шаге, для получения информации о фискализации и контента чека.''
|content-right=&nbsp;
<syntaxhighlight>
https://fp-test.bifit.com/processing-api/receipts/b28463ba-48b6-4d95-8612-d2027d804f42
</syntaxhighlight>
|}}<br>
{{ProductTable-2
|title-left=
Документ отправлен в ФП, но связи с ФП нет
<syntaxhighlight>
https://fp-test.bifit.com/processing-api/receipts/b28463ba-48b6-4d95-8612-d2027d804f42
</syntaxhighlight>
|title-right=
|title-right=
Документ отправлен в ФП, и фискализировался
<syntaxhighlight>
https://fp-test.bifit.com/processing-api/receipts/b28463ba-48b6-4d95-8612-d2027d804f42
</syntaxhighlight>
|content-left=&nbsp;
[[File:Fp_no_connect_receipt.png|300px]]
|content-right=&nbsp;
[[File:Fp_connect_receipt.png|300px]]
|}}<br>
= Справочник Ошибок =
{{ProductTable-2
|title-left='''Структура ошибок в формировании запросов или авторизации'''
|title-right='''Структура ошибок в бизнес логике (некорректные документы, отсутствие прав и т.д)'''
|content-left=&nbsp;
<syntaxhighlight lang="JSON">
{
    "error": String,
    "error_description": String
}
</syntaxhighlight>
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
{
    "type": String,
    "message": String,
    "dependentErrors": Object
}
</syntaxhighlight>
|}}<br>
{{ProductTable-2
|title-left= Перечень статусов документов
|title-right=&nbsp;
|content-left=&nbsp;
|content-left=&nbsp;
* '''authorization''': переменная для передачи access_token. Введите тип токена (в нашем случае слово "Bearer") перед значением '''access_token'''
* '''NEW''' - только что созданный документ, еще не отправлен в очередь (фискальные данные в документе отсутствуют).
* '''idempotency-key''': ключ идемпотентности. Уникальный идентификатор документа в рамках сервиса '''БИФИТ Онлайн'''. Ключ генерируется на стороне клиента и обеспечивает невозможность повторного выполнения запроса регистрации чека на сервере. Варианты формирования ключа:
* '''QUEUE''' - документ находится в очереди на фискализацию (фискальные данные в документе отсутствуют).
** Используйте '''[https://ru.wikipedia.org/wiki/GUID GUID]''' для генерации ключа идемпотентности ('''Рекомендуется''')
* '''REGISTRATION''' - документ находится в процессе регистрации на ККТ (фискальные данные в документе отсутствуют).
** Используйте правило генерации ключа: '''SHA256(Локальный номер документа & PIN(4 символа) & Сумма чека(ххх.хх) & ДатаВремя(ДД.ММ.ГГГГ ЧЧ:ММ))''' для случаев, когда необходимо воспроизвести ключ по исходным данным с ИС отправителя запросов
* '''FAIL''' - ошибка при фискализации документа (фискальные данные в документе отсутствуют).
*** '''Локальный номер документа''': Локальный инкрементируемый счетчик в ИС отправителя запросов;
* '''SUCCESS''' - документ успешно фискализирован (в документе присутствуют фискальные данные и печатная форма чека).
*** '''PIN''': Зафиксированное значение в ИС отправителя запросов;
*** '''Сумма чека''': Сумма чека, переданная в переменную '''total''';
*** '''Время чека''': Время зафиксированное в ИС отправителя;
|content-right=&nbsp;
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
<syntaxhighlight lang="JSON">
"authorization": "Bearer ero3UNcffhlKdn5e76i...edfr_JU"
"idempotency-key": "sdftfc-KF784mkd-skdhkaasca_lf34hKxsf"
</syntaxhighlight>
</syntaxhighlight>
|}}<br>
|}}<br>




Пример:


curl -X POST \
{{ProductTable-2
https://fp-test.bifit.com/processing-api/protected/documents/registration/
|title-left= Перечень ошибок
receipts \
|title-right=&nbsp;
-H 'Content-Type: application/json' \
|content-left=&nbsp;
-H 'Authorization: Bearer access_token' \ -H 'Idempotency-Key:
Если запрошенный по ID документ находится в статусе '''FAIL''', это означает, что ККТ по каким-то причинам не фискализировала такую транзакцию. Перечень причин см. в правой части
idempotency_key' \
|content-right=&nbsp;
-d '{
<syntaxhighlight lang="JSON">
  "type": "SALE",  
ERR20002:
  "taxSystem": "COMMON",
   statusCode: 503
  "cashier": {
   code: ERR20002
  "name": "Иванов И.И."
   description: Запрос не может быть выполнен. Попробуйте позже
  },
"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)'''
ERR20005:
  statusCode: 400
  code: ERR20005
  description: Некорректный запрос


{{ Note | '''''Примечание''''' <br>
ERR20008:
Полученные данные имеют ознакомительный характер, актуальные запросы можно посмотреть по адресу:  
  statusCode: 401
* https://fp.bifit.com/processing-api/swagger-ui.html#/ основной контур
  code: ERR20008
* https://fp-test.bifit.com/processing-api/swagger-ui.html#/ тестовый контур|800}}
  description: Некорректный пароль


=Получение документа по ID=
ERR20012:
  statusCode: 401
  code: ERR20012
  description: Доступ запрещен


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


Ответ описан в swagger`е по ссылке https://fp-test.bifit.com/processing-api/swagger-ui.html#/
ERR20014:
  statusCode: 400
  code: ERR20014
  description: Некорректный запрос


Пример:
ERR20015:
  statusCode: 404
  code: ERR20015
  description: Неизвестный ФН


curl -X GET \
ERR20016:
https://fp-test.bifit.com/processing-api/protected/documents/{id}\
  statusCode: 400
-H 'Authorization: Bearer access_token'
  code: ERR20016
  description: Некорректный запрос


ERR20017:
  statusCode: 400
  code: ERR20017
  description: Смена не открыта


=Оффлайн возможности фискального процессинга=
ERR20018:
  statusCode: 400
  code: ERR20018
  description: Смена превысила 24 часа
 
ERR20019:
  statusCode: 400
  code: ERR20019
  description: Хост недоступен
</syntaxhighlight>
|}}<br>


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


Ссылка:  
* [https://kassa.bifit.com/wiki/index.php?title=API:Отправка_чека_на_повторную_фискализацию Отправка чека на повторную фискализацию]
https://fp-test.bifit.com/processing-api/receipts/ + idempotency_key, сгенерированный при отправке чека.
* [https://kassa.bifit.com/wiki/index.php?title=БИФИТ_ОНЛАЙН:Авторизация_в_OAuth2_при_помощи_токена_коннектора Авторизация в OAuth2 при помощи токена коннектора]
* [https://kassa.bifit.com/wiki/index.php?title=БИФИТ_ОНЛАЙН:Авторизация_в_OAuth2_по_refresh_token Авторизация в OAuth2 по refresh token]
* [https://kassa.bifit.com/wiki/index.php?title=БИФИТ_ОНЛАЙН:Отправка_документа_на_фискализацию_в_процессинг Отправка документа на фискализацию в процессинг]
* [https://kassa.bifit.com/wiki/index.php?title=БИФИТ_ОНЛАЙН:Отправка_документа_на_фискализацию_в_процессинг_(маркированный_товар) Отправка документа на фискализацию в процессинг (маркированный товар)]
* [https://kassa.bifit.com/wiki/index.php?title=БИФИТ_ОНЛАЙН:Отправка_документа_на_фискализацию_в_процессинг_(агентский_товар) Отправка документа на фискализацию в процессинг (агентский товар)]
* [https://kassa.bifit.com/wiki/index.php?title=БИФИТ_ОНЛАЙН:Запрос_информации_о_документе_по_ID Запрос информации о документе по ID]
* [https://kassa.bifit.com/wiki/index.php?title=БИФИТ_ОНЛАЙН:Оффлайн_возможности_фискального_процессинга Оффлайн возможности фискального процессинга]
* [https://kassa.bifit.com/wiki/index.php?title=БИФИТ_ОНЛАЙН:Справочник_Ошибок_(ФП) Справочник Ошибок (ФП)]

Текущая версия на 15:15, 16 июня 2023

Введение

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

  • Авторизация в ФП - процесс необходимый для подключения клиента к фискальному процессингу,
  • Формирование контент чека - формирование информации для дальнейшей отправки на фискализацию,
  • Отправка чека в ФП - передача контента чека в фискальный процессинг для дальнейшей фискализации,
  • Получение документа по 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


Payments - тип оплаты.
 
  • 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
  • CONSUMPTION
  • CONTRIBUTIONS_MPI_SE
  • CONTRIBUTIONS_MPI
  • CONTRIBUTIONS_CHI_SE
  • CONTRIBUTIONS_CHI
  • CONTRIBUTIONS_MSI
  • CASINO_PAYMENT
  • MONEY_PAYMENT
  • ATNM
  • ATM
  • TNM
  • TM
  
  • Товар
  • Подакцизный товар
  • Работа
  • Услуга
  • Ставка азартной игры
  • Выигрыш азартной игры
  • Лотерейный билет
  • Выигрыш лотереи
  • Предоставление РИД
  • Платеж
  • Агентское вознаграждение
  • Составной предмет расчета
  • Иной предмет расчета
  • Имущественное право
  • Внереализованный доход
  • Страховые взносы
  • Торговый сбор
  • Курортный сбор
  • Залог
  • Расход
  • Вкзносы на ОПС ИП
  • Взносы на ОПС
  • Взносы на ОМС ИП
  • Взносы на ОМС
  • Взносы на ОСС
  • Платеж казино
  • Выплата
  • Подакцизный маркируемый товар без КМ
  • Подакцизный маркируемый товар с КМ
  • Маркируемый товар без КМ
  • Марируемый товар с КМ


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) Сумма товарной позиции


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

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

Note.svg  Примечание


Запрос 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"
}


Авторизация в OAuth2 по refresh token

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

Note.svg  Примечание


Авторизация 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"
}



Отправка документа на фискализацию в процессинг

Запрос регистрации чека 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: переменная для передачи access_token. Введите тип токена (в нашем случае слово "Bearer") перед значением access_token
  • idempotency-key: ключ идемпотентности. Уникальный идентификатор документа в рамках сервиса БИФИТ Онлайн. Ключ генерируется на стороне клиента и обеспечивает невозможность повторного выполнения запроса регистрации чека на сервере. Варианты формирования ключа:
    • Используйте GUID для генерации ключа идемпотентности (Рекомендуется)
    • Используйте правило генерации ключа: SHA256(Локальный номер документа & PIN(4 символа) & Сумма чека(ххх.хх) & ДатаВремя(ДД.ММ.ГГГГ ЧЧ:ММ)) для случаев, когда необходимо воспроизвести ключ по исходным данным с ИС отправителя запросов
      • Локальный номер документа: Локальный инкрементируемый счетчик в ИС отправителя запросов;
      • PIN: Зафиксированное значение в ИС отправителя запросов;
      • Сумма чека: Сумма чека, переданная в переменную total;
      • Время чека: Время зафиксированное в ИС отправителя;
   
authorization: "Bearer ero3UNcffhlKdn5e76i...edfr_JU"
idempotency-key: "sdftfc-KF784mkd-skdhkaasca_lf34hKxsf"


Request Body 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": "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
 
  • Ответ сервера содержит ID зарегистрированного чека
   
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: переменная для передачи access_token. Введите тип токена (в нашем случае слово "Bearer") перед значением access_token
   
authorization: "Bearer ero3UNcffhlKdn5e76i...edfr_JU"


Response
Ответ содержит информацию о состоянии отправленного на фискализацию документа. В случае успешной фискализации, будет содержать следующую:
  • Информацию о ККТ, на которой был фискализирован документ
  • Исходный запрос
  • Информацию для генерации QR:
    • Тип документа
    • Дата/время расчета (фискализации документа на ККТ)
    • Сумма чека
    • Номер фискального накопителя
    • Номер фискального документа
    • Фискальный признак документа
  • Печатную форму фискального документа
--------------------------------
          Кассовый чек          
             ПРИХОД             
            АО БИФИТ            
г.Москва, Ниж. Первомайская, д.4
               6                
         15:04:22 12:17         
--------------------------------
Услуга                          
1.5 * 100.00            = 150.00
НДС 20%                         
УСЛУГА                          
--------------------------------
ИТОГ                    = 150.00
НАЛИЧНЫМИ               = 150.00
СУММА НДС 20%            = 25.00
ЭЛ.АДР.ПОКУПАТЕЛЯ  test@test.com
ЭЛ.АДР.ОТПРАВИТЕЛЯ              
                noname@email.com
КАССИР               Иванов И.И.
ЧЕК                           39
СМЕНА                        299
СНО                          ОСН
ИНН                   7724923302
РН ККТ          0000000001053073
ФН              9999078902002260
ФД                          5088
ФП                    3705633526
  
{
    "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
  Fp no connect receipt.png   Fp connect receipt.png


Справочник Ошибок

Структура ошибок в формировании запросов или авторизации Структура ошибок в бизнес логике (некорректные документы, отсутствие прав и т.д)
  
{
    "error": String,
    "error_description": String
}
  
{
    "type": String,
    "message": String,
    "dependentErrors": Object
}


Перечень статусов документов  
 
  • NEW - только что созданный документ, еще не отправлен в очередь (фискальные данные в документе отсутствуют).
  • QUEUE - документ находится в очереди на фискализацию (фискальные данные в документе отсутствуют).
  • REGISTRATION - документ находится в процессе регистрации на ККТ (фискальные данные в документе отсутствуют).
  • FAIL - ошибка при фискализации документа (фискальные данные в документе отсутствуют).
  • SUCCESS - документ успешно фискализирован (в документе присутствуют фискальные данные и печатная форма чека).
  



Перечень ошибок  
  Если запрошенный по 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: Хост недоступен


См. также

Источник — http://kassa.bifit.com/wiki/index.php?title=Облачная_Касса:_Интеграция_с_Фискальным_Процессингом&oldid=49823