Skip to main content

Интеграция приложения с POSfix

Ваше приложение работает на том же Android-терминале, что и POSfix, и отправляет ему команды: продажу, оплату картой, Z-отчёт. POSfix выполняет фискальную и банковскую часть, а затем возвращает вам результат. Его экран не открывается.

Эта страница — для разработчиков, которые пишут приложение. Что вы передаёте в каждой команде, описано в Справочнике команд.

Что умеет ваше приложение​

  • Фискальная продажа с оплатой наличными, картой или MIA QR. POSfix отправляет чек в SFS и печатает его.
  • Внесение и выдача наличных с сервисным чеком.
  • X-отчёт и Z-отчёт. При Z закрывается и банковский день карточного терминала.
  • Отмена и возврат оплаты картой.
  • Копия чека, список продаж, сводка фискального дня.
  • Каталог: товары, категории, ставки НДС, кассиры.
  • Клиент программы лояльности: вы находите его по телефону или карте, а продажа начисляет ему баллы.

Чего оно не делает​

  • Не выдаёт чек возврата. В протоколе SFS (ACPS) есть только фискальный чек, сервисный чек и отчёт. Деньги вы возвращаете через card.void или card.refund, а возврат товара остаётся за рамками интеграции.
  • Не оплачивает бонусами программы лояльности и не применяет вознаграждения. Пока оно только идентифицирует клиента и начисляет ему баллы.
  • Не активирует терминал. Активация выполняется один раз, на экране POSfix.

Единственный шаг на терминале: активация​

Установите POSfix и активируйте его один раз, на его экране, кодом, который создаётся в Control Panel при назначении терминала. Дальше ничего настраивать не нужно: ни ключей, ни подтверждений, ни входа кассира.

Активация — это и лицензия. Пока терминал активирован, любое приложение на нём может отправлять команды. Если вы деактивируете его в Control Panel, POSfix начнёт отклонять команды с кодом TERMINAL_NOT_ACTIVATED после следующего соединения с сервером.

Как работают два приложения​

  1. Ваше приложение привязывается к сервису POSfix. Если POSfix не был запущен, Android запускает его без экрана.
  2. Оно отправляет команду в виде JSON: имя команды, её данные и уникальный ключ.
  3. POSfix выполняет её тем же кодом, что и экран кассы: чек получается точно таким же, как выданный кассиром.
  4. Результат приходит обратно в callback, один раз.

Связь идёт через Android (Binder), а не через сеть. Android сообщает POSfix, какое приложение отправляет команду, и пакет этого приложения попадает в журнал запросов терминала.

После первой команды POSfix остаётся запущенным в фоне. Он сам запускается после перезагрузки терминала и после обновления, а в панели уведомлений появляется «POSfix».

Быстрый старт​

1. Добавьте SDK. В settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://docs.posfix.md/sdk/maven") }
    }
}

В build.gradle.kts приложения:

dependencies {
    implementation("md.posfix:posfix-integration-sdk:1.0.0")
}

SDK требует Android 7.0 (API 24) или новее. Он сам добавляет в ваш манифест объявление <queries> для md.posfix.posfix, которого требует Android 11+, так что дописывать ничего не нужно.

2. Подключитесь.

val posfix = PosfixClient(context)

posfix.connect(object : PosfixClient.ConnectionListener {
    override fun onConnected(apiVersion: Int) {
        // готово к командам
    }
    override fun onDisconnected(reason: String) {
        // POSfix остановился; выполняемые команды получают POSFIX_DISCONNECTED,
        // а SDK сам заново привязывается к нему
    }
})

3. Проверьте терминал.

posfix.execute("status") { response ->
    val data = response.getJSONObject("data")
    data.getBoolean("activated")   // false = активируйте POSfix на его экране
}

4. Выдайте первый чек. Кофе за 25 леев, оплата наличными:

val sale = JSONObject("""
{
  "items": [ { "name": "Cafea", "unitPrice": 25.00, "quantity": 1, "vatCode": "B" } ],
  "payments": [ { "type": "1", "amount": 25.00 } ],
  "amountReceived": 25.00,
  "printReceipt": true
}
""")

val key = PosfixClient.newIdempotencyKey()   // сохраните его, пока не узнаете результат

val sent = posfix.execute("sale.create", sale, key) { response ->
    if (response.getBoolean("success")) {
        val receipt = response.getJSONObject("data").getInt("receiptNumber")
    } else {
        val code = response.getJSONObject("error").getString("code")
    }
}

Все callback-и приходят в главном потоке. execute сразу возвращает sent.requestId — он нужен, чтобы остановить продажу через cancel.

Для оплаты картой укажите "type": "2", и POSfix откроет платёжный экран банка. Подробности — в разделе Оплата картой, события и сбои.

Flutter, React Native и тестовое приложение​

SDK работает и из Android-части приложения на Flutter или React Native. Интерфейс AIDL напрямую — для тех, кто не хочет зависеть от SDK: см. раздел «Без SDK» в Справочнике команд.

Исходный код SDK поставляется вместе с пакетом Maven. Демо-приложение с кнопками для всех команд можно получить по запросу на info@m-373.com.