Inicio rápido: Tu primera venta
Esta guía de inicio rápido te guía a través de la implementación de una transacción de pago completa utilizando el SDK de Get Mini Android (iTPV-PC). Configurarás tu proyecto, autenticarás tus credenciales de comercio, inicializarás el PIN pad y ejecutarás una transacción de venta de prueba. Este tutorial sigue el “camino feliz” esencial utilizando los componentes principales de la biblioteca.
Requisitos
Antes de comenzar este inicio rápido, asegúrate de tener lo siguiente:
- Android Studio: Última versión estable instalada.
- Dispositivo Físico: Requerido para las pruebas (los emuladores no soportan conectividad Bluetooth con el PIN pad).
- Credenciales:
- Código de Licencia de la Aplicación: Proporcionado por el soporte de Get Mini.
- Credenciales de Usuario: Nombre de usuario y contraseña (el FUC y el Terminal se recuperan dinámicamente durante el inicio de sesión).
- PIN pad Físico: Un PIN pad Bluetooth certificado y tu número de serie.
- JAR del SDK: El archivo
redcls-itpvpc-android.jar.
Esta guía asume que ya has revisado la configuración de Configuración de Permisos en Android. Si no, asegúrate de que tu AndroidManifest.xml incluya los permisos necesarios de Bluetooth e Internet.
Paso 1: Configurar las dependencias del proyecto
El SDK de Get Mini se distribuye como una biblioteca JAR local. Añádela a la carpeta app/libs/ de tu proyecto y configura tu archivo app/build.gradle:
dependencies {
// SDK principal
implementation files('libs/redcls-itpvpc-android.jar')
}En la mayoría de los proyectos, no se requieren dependencias adicionales. Si encuentras errores del proveedor criptográfico o de análisis JSON durante el inicio de sesión, consulta la sección Solución de Problemas o la guía completa Añadir el SDK a tu Proyecto.
Sincroniza tu proyecto con los archivos de Gradle después de realizar estos cambios.
Paso 2: Inicializar la biblioteca e iniciar sesión
Antes de procesar transacciones, debes configurar el entorno y autenticarte para recuperar los datos del terminal.
// 1. Configurar el entorno (INTEGRACION para pruebas, REAL para producción)
RedCLSConfigurationLibrary.setiEntorno(RedCLSConstantes.ENTORNO_INTEGRACION)
// 2. Establecer la licencia de tu aplicación
RedCLSConfigurationLibrary.setAppLicense("SU_CLAVE_DE_LICENCIA")
// 3. Ejemplo de inicio de sesión simplificado para recuperar terminales disponibles
val loginData = RedCLSLoginData(context, "usuario", "contraseña")
Thread {
val loginResponse = RedCLSMerchantConfigurationManager.login(loginData)
if (loginResponse.code == 0) {
// Recuperar el primer terminal disponible
val terminalData = loginResponse.merchantList[0].terminalList[0]
Log.d("GetMini", "Autenticado para Terminal: ${terminalData.terminal}")
// Proceder a la inicialización del PIN pad (Paso 3)
initializePinpad(terminalData)
} else {
Log.e("GetMini", "Inicio de sesión fallido: ${loginResponse.desc}")
}
}.start()Paso 3: Inicializar el PIN pad
El RedCLSPinPadManager gestiona la conexión e inicialización del dispositivo físico. Debes implementar RedCLSPinPadInterface para manejar los eventos de conexión.
class PinpadHandler(private val context: Context, private val terminalData: RedCLSTerminalData) : RedCLSPinPadInterface {
private var pinpadManager: RedCLSPinPadManager? = null
fun start() {
// Conexión Bluetooth mínima usando el Número de Serie del PIN pad
val config = RedCLSConfigurationPinPadData("NUMERO_SERIE_PINPAD")
pinpadManager = RedCLSPinPadManager(this, config, terminalData)
pinpadManager?.connectWithPinPad()
}
override fun getContext(): Context = context
override fun conexionPinPadRealizada() {
Log.d("GetMini", "Conectado. Inicializando...")
// Finalizar la inicialización para sincronizar claves/parámetros
Thread {
val initResponse = pinpadManager?.inicializarPinpad()
if (initResponse?.status == 0) {
Log.d("GetMini", "PIN pad Listo")
// Ahora puedes realizar un pago (Paso 4)
}
}.start()
}
override fun pinPadNoEncontrado() {
Log.e("GetMini", "PIN pad no encontrado o error de Bluetooth")
}
// Métodos de interfaz obligatorios adicionales (selección DCC, etc.)
override fun seleccionMonedaPagoDCC(dccData: RedCLSDCCSelectionData): String = dccData.currencyChangeCode
}Paso 4: Ejecutar una transacción de pago
Una vez que el PIN pad esté preparado, utiliza el método operativaConTarjeta. El SDK manejará la lectura de la tarjeta, la entrada del PIN y la autorización.
fun makeSale(amount: String) {
val saleData = RedCLSOperativeWithCardData(amount)
// Opcional: Añadir un número de referencia/factura
saleData.invoice = "INV-12345"
Thread {
val saleResponse = pinpadManager?.operativaConTarjeta(saleData)
if (saleResponse?.status == 0) {
val tx = saleResponse.transactionData
if (tx.result == "Autorizada") {
Log.d("GetMini", "¡Éxito! Autorización: ${tx.autorizationNumber}")
} else {
Log.w("GetMini", "Transacción Denegada")
}
} else {
Log.e("GetMini", "Error: ${saleResponse?.msgKO}")
}
}.start()
}Paso 5: Manejar el resultado de la transacción
Almacena los siguientes campos clave de RedCLSTransactionData para tus registros e impresión de recibos:
| Campo | Descripción |
|---|---|
autorizationNumber | El código de autorización único del emisor. |
identifierRTS | Una referencia de 24 caracteres para la transacción, devuelta por el TPV PC. |
order | El número de pedido de la operación, devuelto por el TPV PC. |
card | Número de tarjeta enmascarado (ej., ************1234). |
isPinAuthenticated | Si es true, el usuario ingresó un PIN (no se necesita firma). |
Solución de problemas
- Errores de Dependencias
En la mayoría de los proyectos, no se requieren dependencias adicionales. Sin embargo, si encuentras NoSuchAlgorithmException o errores de análisis JSON durante el inicio de sesión, es posible que debas añadir BouncyCastle y Gson a tu app/build.gradle. Consulta Añadir el SDK a tu Proyecto para los detalles específicos de implementación.
- El Inicio de Sesión Falla (p. ej., código 26 - contraseña errónea, o código 28 - usuario bloqueado): Verifica tu código de licencia de la aplicación y que tengas una conexión a Internet estable.
- PIN pad No Encontrado: Asegúrate de que el Bluetooth esté habilitado en el dispositivo Android y que el PIN pad esté en modo de emparejamiento.
- Error de Inicialización: Asegúrate de que el terminal esté correctamente aprovisionado en el portal de Get Mini para tu FUC.
Próximos pasos
- Configuración de Permisos en Android: Guía detallada sobre el manejo de permisos en tiempo de ejecución.
- Ciclo de Vida de la Transacción: Comprenda los estados completos del pago.