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

Материал из Касса
Перейти к навигации Перейти к поиску

Введение

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

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

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


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

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

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"
}


Авторизация при помощи 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": "7ХХХХХХХХХХ"
    },
    "items": [
        {
            "calculationMethod": "FULL_PAY",
            "paymentSubject": "SERVICE",
            "name": "Услуга",
            "price": 100,
            "quantity": 1,
            "vat": "VAT_20",
            "total": 100
        }
    ],
    "total": 100,
    "payments": {
        "CASH": 100
    }
}


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

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

Получение документа по 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, сгенерированный при отправке чека.