Skip to main content

Integrarea unei aplicații cu POSfix

Aplicația ta rulează pe același terminal Android ca POSfix și îi trimite comenzi: o vânzare, o plată cu cardul, un raport Z. POSfix face partea fiscală și bancară, apoi îți întoarce rezultatul. Ecranul lui nu se deschide.

Pagina e pentru dezvoltatorii care scriu aplicația. Ce trimiți în fiecare comandă e în Referința comenzilor.

Ce poate face aplicația ta​

  • Vânzare fiscală, plătită în numerar, cu cardul sau cu MIA QR. POSfix trimite bonul la SFS și îl tipărește.
  • Introducere și extragere de numerar, cu bon de serviciu.
  • Raport X și raport Z. La Z se închide și ziua bancară a terminalului de card.
  • Anularea și rambursarea unei plăți cu cardul.
  • Copia bonului, lista vânzărilor, rezumatul zilei fiscale.
  • Catalogul: produse, categorii, cote TVA, casieri.
  • Clientul programului de fidelitate: îl cauți după telefon sau card, iar vânzarea îi adună punctele.

Ce nu face​

  • Nu emite bon de retur. Protocolul SFS (ACPS) are doar bon fiscal, bon de serviciu și raport. Banii îi dai înapoi cu card.void sau card.refund, iar returul mărfii rămâne în afara integrării.
  • Nu plătește cu bonusul de fidelitate și nu aplică recompense. Deocamdată doar identifică clientul și îi adună punctele.
  • Nu activează terminalul. Activarea se face o singură dată, pe ecranul POSfix.

Singurul pas pe terminal: activarea​

Instalezi POSfix și îl activezi o dată, din ecranul lui, cu codul generat în Control Panel la alocarea terminalului. De aici nu mai e nimic de configurat: nicio cheie, nicio aprobare, niciun casier logat.

Activarea e și licența. Cât terminalul e activat, orice aplicație de pe el poate da comenzi. Dacă îl dezactivezi din Control Panel, POSfix refuză comenzile cu TERMINAL_NOT_ACTIVATED de la următoarea legătură cu serverul.

Cum lucrează cele două aplicații​

  1. Aplicația ta se leagă la serviciul POSfix. Dacă POSfix nu rula, Android îl pornește, fără ecran.
  2. Trimite comanda ca JSON: numele comenzii, datele ei și o cheie unică.
  3. POSfix o execută cu același cod ca ecranul casei: bonul iese identic cu unul emis de casier.
  4. Rezultatul vine înapoi pe un callback, o singură dată.

Legătura trece prin Android (Binder), nu prin rețea. Android îi spune lui POSfix ce aplicație trimite comanda, iar pachetul ei apare în jurnalul de cereri al terminalului.

După prima comandă, POSfix rămâne pornit în fundal. Pornește singur după o repornire a terminalului și după o actualizare, iar în bara de notificări apare „POSfix”.

Pornire rapidă​

1. Adaugă SDK-ul. În settings.gradle.kts:

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

În build.gradle.kts al aplicației:

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

SDK-ul cere Android 7.0 (API 24) sau mai nou. Adaugă singur în manifestul tău declarația <queries> pentru md.posfix.posfix, pe care o cere Android 11+, deci nu scrii nimic în plus.

2. Conectează-te.

val posfix = PosfixClient(context)

posfix.connect(object : PosfixClient.ConnectionListener {
    override fun onConnected(apiVersion: Int) {
        // gata de comenzi
    }
    override fun onDisconnected(reason: String) {
        // POSfix s-a oprit; comenzile în curs primesc POSFIX_DISCONNECTED,
        // iar SDK-ul se leagă din nou singur
    }
})

3. Verifică terminalul.

posfix.execute("status") { response ->
    val data = response.getJSONObject("data")
    data.getBoolean("activated")   // false = activează POSfix pe ecranul lui
}

4. Emite primul bon. O cafea de 25 lei, plătită cash:

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()   // păstreaz-o până afli rezultatul

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

Toate callback-urile vin pe firul principal. execute întoarce imediat sent.requestId, de care ai nevoie ca să oprești vânzarea cu cancel.

Pentru plata cu cardul pui "type": "2", iar POSfix deschide ecranul de plată al băncii. Detaliile sunt în Plata cu cardul, evenimente și căderi.

Flutter, React Native și aplicația de test​

SDK-ul merge și din partea Android a unei aplicații Flutter sau React Native. Interfața AIDL directă e pentru cine nu vrea dependența SDK-ului: vezi „Fără SDK” în Referința comenzilor.

Sursele SDK-ului vin cu pachetul Maven. Aplicația demo, cu butoane pentru toate comenzile, o primești la cerere, la info@m-373.com.