Guía del Zeal ECR SDK

Lanza transacciones en terminales con Zeal integrado desde tu ECR Android. Eventos de Pusher en tiempo real y diálogos incluidos.

El Zeal ECR SDK ofrece una interfaz directa para integrar tu aplicación Android con el ecosistema e-POS de Zeal. Se encarga de la inicialización del dispositivo, la gestión de terminales y el procesamiento de transacciones mediante un diseño de API estructurado y asíncrono.

Instalación

Paso 1 · Crea un token de acceso personal de GitHub

Necesitas un PAT con el permiso read:packages. Genera un token (clásico) desde los ajustes para desarrolladores de GitHub.

Paso 2 · Agrega el repositorio Maven

Agrega el repositorio Maven de GitHub Packages a tu settings.gradle.kts de nivel de proyecto:

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()

      // Agrega el repositorio de GitHub Packages
      maven {
          name = "GitHubPackages"
          url = uri("https://maven.pkg.github.com/zeal-io/epos-sdk")
          credentials {
              username = "your-github-username"
              password = "your-github-pat-token"
          }
      }
  }
}

Paso 3 · Agrega la dependencia

En tu app/build.gradle.kts de nivel de módulo:

dependencies {
  implementation("com.zeal:epos_sdk:1.0.4")
  // Necesario para el EPOS SDK
  implementation("io.insert-koin:koin-core:4.1.1")
}

Paso 4 · Permisos

El SDK necesita acceso a internet. Agrega lo siguiente a tu AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

val config = SdkConfig(
  context = applicationContext,
  ecrId = "ECR12345",
  terminalsTokensList = listOf("token1", "token2"),
  appId = "app-id-example"
)

// debe llamarse desde una corrutina u otra función suspend
val initialized = ZealSDK.initialize(config)

// debe llamarse desde una corrutina u otra función suspend
val terminals = ZealSDK.listTerminals()
terminals.forEach {
  println("Terminal ID: ${it.terminalId}")
}

// debe llamarse desde una corrutina u otra función suspend
val syncData = SyncData(tid = "2223223", items = listOf(CatalogItem()))
val success = ZealSDK.syncCatalog(syncData)

val orderItems = listOf(
  OrderItems("Coffee", 2, 25.0),
  OrderItems("Cake", 1, 40.0)
)

// consulta «Mostrar los diálogos de transacción» más abajo
ZealSDK.showDialogs(context as ComponentActivity)

try {
  val trxResponse = ZealSDK.startTrx(
      amount = 20.0,
      terminalId = "T12345",
      items = orderItems
  )
  println("Transaction completed: ${trxResponse.state}")
} catch (e: TimeoutException) {
  println("Transaction timed out.")
} catch (e: Exception) {
  println("Transaction failed: ${e.message}")
}

ZealSDK.showDialogs(this)

Componentes internos

Gestión de errores

El SDK usa un envoltorio Result estructurado para gestionar los estados de éxito y error en todos los casos de uso. Las causas de error habituales son:

• Tokens de terminal no válidos o caducados.
• Fallos de comunicación de red.
• Terminales que no responden.
• Tiempos de espera agotados o respuestas de transacción ausentes.

Envuelve siempre las llamadas al SDK en bloques try/catch para gestionar los errores de forma fiable.

try {
  val success = ZealSDK.initialize(config)
} catch (e: Exception) {
  Log.e("ZealSDK", "Initialization failed: ${e.message}")
}

Recomendaciones sobre el ciclo de vida

1. Inicializa una sola vez: al arrancar tu aplicación o en tu activity principal.
2. Llama a showDialogs() antes de iniciar cualquier transacción para habilitar los diálogos de la interfaz.
3. Usa corrutinas para todas las funciones suspend (initialize, listTerminals, startTrx).
4. Gestiona las excepciones correctamente con try/catch.
5. Ten en cuenta los tiempos de espera: las transacciones fallan automáticamente a los 60 segundos con una TimeoutException.

Ejemplo completo

Flujo de transacción completo dentro de una Activity:

lifecycleScope.launch {
  try {
      // Paso 1: inicializa el SDK
      val initialized = ZealSDK.initialize(config)

      // Paso 2: habilita los diálogos
      ZealSDK.showDialogs(this@MainActivity)

      // Paso 3: obtén los terminales
      val terminals = ZealSDK.listTerminals()
      val terminal = terminals.first()

      // Paso 4: inicia la transacción
      val trxResponse = ZealSDK.startTrx(
          amount = 5000L,
          terminalId = terminal.id,
          items = listOf(OrderItems("Latte", 1, 50.0))
      )

      Log.d("ZealSDK", "Transaction success: ${trxResponse.state}")
  } catch (e: TimeoutException) {
      Log.e("ZealSDK", "Transaction timed out.")
  } catch (e: Exception) {
      Log.e("ZealSDK", "Error: ${e.message}")
  }
}