Integración entre aplicaciones

En el siguiente documento se especifica la integración entre aplicaciones móviles, que permite que una aplicación externa invoque la aplicación TUU Negocio con parámetros específicos. Es imprescindible contar con un terminal POS configurado y habilitado para procesar las transacciones solicitadas por la integración. A continuación, se describe el proceso en detalle según el diagrama:

Diagrama alto nivel de la integración

👍

Antes de comenzar

• Para realizar pruebas debes contar con un terminal TUU, ya que la aplicación de Pagos está certificada para operar solo sobre ese modelo en específico.
• Consideración importante, el nombre del package en develop es diferente al de producción: com.haulmer.paymentapp.dev y com.haulmer.paymentapp -> separar bien

Recursos necesarios para Integración

Para integrar tu App con TUU Negocio y ejecutar transacciones en un POS, necesitas contar con el hardware y el software adecuados, además de un entorno de prueba correctamente aprovisionado. A continuación encontrarás los instaladores DEV por fabricante (Sunmi / Kozen).

Fases del proceso de integración mediante Inter-apps

Fase 1 — Invocación desde la App Integradora

La aplicación externa construye un Intent dirigido explícitamente a la package name de pagos de TUU Negocio. Señalar la package name.

• Dentro del Intent se incluye un JSON bajo la clave paymentData que contiene todos los parámetros de la transacción (amount, method, installmentsQuantity, dteType, extraData, etc.).
• El lanzamiento de la actividad se hace usando la Activity Result API, de modo que la App Integradora pueda recibir una respuesta estructurada al finalizar el flujo.
• En este punto, la App Integradora define un callback que recibirá el resultado cuando TUU Negocio termine de procesar.

Dependiendo la implementación usada, así como librerías y uso de Android nativo, varía la forma de invocación y recepción (Android). A continuación se presenta una forma de hacerlo:

1. Registrar el "Launcher" y el "Callback":

   En la Activity o Fragment, se registra un ActivityResultLauncher. Este launcher se encarga de iniciar la app TUU Negocio y define el callback (la función) que se ejecutará cuando TUU Negocio devuelva un resultado.

   Java

   
   // 1. Registrar el "launcher" (hacer esto en la inicialización de la Activity/Fragment)
   private final ActivityResultLauncher<Intent> paymentLauncher = registerForActivityResult(
       new ActivityResultContracts.StartActivityForResult(),
       new ActivityResultCallback<ActivityResult>() {
           @Override
           public void onActivityResult(ActivityResult result) {
               // 4. El callback se dispara aquí cuando TUU Negocio retorno
               if (result.getResultCode() == Activity.RESULT_OK) {
                   Intent data = result.getData();
                   if (data != null && data.hasExtra("transactionResult")) {
                       String resultJson = data.getStringExtra("transactionResult");
                       Log.d("AppIntegradora", "Resultado OK: " + resultJson);
                       // TODO: Procesar JSON de éxito
                   }
               } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                   Intent data = result.getData();
                   if (data != null && data.hasExtra("transactionResult")) {
                       String errorJson = data.getStringExtra("transactionResult");
                       Log.e("AppIntegradora", "Error: " + errorJson);
                       // TODO: Procesar JSON de error
                   } else {
                       Log.w("AppIntegradora", "Operación cancelada por el usuario.");
                   }
               }
           }
       });

2. Construir y lanzar el Intent

   Se crea un método para construir el Intent y lanzarlo usando el launcher que acabas de registrar.

   Java

   /**
    * Inicia el flujo de pago en la app TUU Negocio.
    * @param request Objeto (DTO) que contiene los datos de pago, 
    * serializable a JSON.
    */
   public void sendPaymentIntent(Request request) {
       if (isFinishing() || isDestroyed()) {
           Log.d("AppConstants.TAG", "La actividad está finalizando. No se puede enviar el intent.");
           return;
       }
   
       PackageManager packageManager = getPackageManager();
       if (null == packageManager) {
           Log.d("AppConstants.TAG", "PackageManager no disponible.");
           return;
       }
   
       // Usar el package name de DEV o PROD según corresponda
       final String TUU_PACKAGE_NAME = "com.haulmer.paymentapp.dev"; // o "com.haulmer.paymentapp"
       Intent sendIntent = packageManager.getLaunchIntentForPackage(TUU_PACKAGE_NAME);
       
       if (null == sendIntent) {
           Log.d("AppConstants.TAG", "App TUU Negocio no encontrada: " + TUU_PACKAGE_NAME);
           // TODO: Informar al usuario (ej. "Por favor, instale la app de pagos")
           return;
       }
   
       // 1. setAction(Intent.ACTION_SEND): 
       //    Define la acción estándar para "enviar" datos.
       sendIntent.setAction(Intent.ACTION_SEND);
   
       // 2. setFlags(0): 
       //    Indica que no se usan flags especiales (como FLAG_ACTIVITY_NEW_TASK).
       //    Esto es crucial para que el resultado vuelva correctamente.
       sendIntent.setFlags(0);
   
       try {
           // 3. putExtra(Intent.EXTRA_TEXT, ...):
           //    Añade el payload de la transacción (tu objeto Request serializado a JSON)
           //    bajo la clave estándar EXTRA_TEXT.
           sendIntent.putExtra(Intent.EXTRA_TEXT, objectMapper.writeValueAsString(request));
       } catch (JsonProcessingException e) {
           Log.d("AppConstants.TAG", "Problemas en la construcción del JSON: " + e.getMessage());
           return;
       }
   
       // Define el tipo de dato que estás enviando
       sendIntent.setType("text/json");
   
       // 4. paymentLauncher.launch(sendIntent):
       //    Inicia la app TUU Negocio y le pasa el Intent.
       //    El sistema ahora espera que TUU Negocio retorne un resultado,
       //    que será capturado por el callback del 'paymentLauncher'.
       paymentLauncher.launch(sendIntent);
   }

Ejemplo de JSON enviado en el paymentData

{
   "amount":10000,
   "tip":0,
   "cashback":0,
   "method":2,
   "installmentsQuantity":5,
   "printVoucherOnApp":true,
   "dteType":48,
   "extraData":{
      "taxIdnValidation":"8886274-2",
      "exemptAmount":9000,
      "netAmount":1000,
      "sourceName":"Nombre App Integradora",
      "sourceVersion":"2023.01.20-6",
      "customFields":[
         {
            "name":"nombre",
            "value":"valor",
            "print":true
         }
      ]
   }
}

Fase 2 — Procesamiento en TUU Negocio y en el POS

Cuando TUU Negocio recibe el Intent:

1. Lectura de parámetros

   • Extrae el paymentData y lo deserializa desde JSON.

2. Validaciones iniciales

   • Revisa que los atributos cumplan con el contrato, (validación del dato, explicar de otra forma) (ejemplo: amount > 0, method ∈ {0,1,2}, cashback solo permitido si method=2, longitudes de customFields, etc.).

3. Interacción con el POS

   • Muestra interfaz al usuario final para seleccionar método de pago, insertar tarjeta, ingresar PIN, etc.

4. Comunicación con sistema transaccional

• TUU Negocio se conecta al sistema transaccional, enviando los datos validados para que el servidor procese y confirme la transacción.

❌ En caso de errores de validación o de entorno (ejemplo: terminal no configurado, SDK desactualizado, parámetros inválidos), TUU Negocio prepara un JSON de error con errorCode / errorMessage.

Fase 3 — Generación y devolución del resultado

Una vez procesada la transacción:

• TUU Negocio construye un Intent de respuesta, donde añade un JSON en el extra transactionResult.

• Este JSON contiene los campos de salida principales:

  • transactionStatus (true/false)
  • sequenceNumber (identificador único de 12 dígitos)
  • printerVoucherCommerce (si el voucher se imprimió automáticamente en el POS)
  • transactionTip, transactionCashback (si aplican)
  • extraData (eco de lo enviado, para trazabilidad).

{
   "transactionStatus":true,
   "sequenceNumber":"000000004719",
   "printerVoucherCommerce":true,
   "transactionTip":,
   "extraData":{
      "taxIdnValidation":"8886274-2",
      "exemptAmount":9000,
      "netAmount":1000,
      "sourceName":"Nombre App Integradora",
      "sourceVersion":"2023.01.20-6",
      "customFields":[
         {
            "name":"nombre",
            "value":"valor",
            "print":true
         }
      ]
   }
}

❌ En caso de que exista un fallo en la transacción, se devuelve el control directamente a la app integradora

Fase 4 — Manejo del resultado en la App Integradora

El control regresa a la aplicación externa. La aplicación TUU Negocio utiliza internamente el método setResult() para finalizar su flujo y devolver los datos.

1. Uso de setResult()

• A través del uso de setResult(), método del ciclo de vida de una Activity en Android. Se permite que una actividad —en este caso, TUU Negocio— envíe un resultado de vuelta a la actividad que la invocó —tu App Integradora.
• El método recibe dos parámetros:

1. Código de resultado:
   • Activity.RESULT_OK → Indica que el flujo se completó correctamente (transacción procesada).
   • Activity.RESULT_CANCELED → Indica que el flujo se canceló o se produjo un error.
2. Intent de respuesta:
   • Este Intent contiene el String JSON bajo la clave "transactionResult", que encapsula el resultado o el error de la transacción.

2. Recepción del Callback

• El callback del ActivityResultLauncher registrado en la Fase 1 se dispara automáticamente al recibir el resultado. El objeto ActivityResult que recibe tu callback incluye tanto el resultCode (el código de resultado) como el Intent con los datos retornados por TUU Negocio.

3. Verificación del resultCode

• La aplicación integradora debe analizar el código de resultado y procesar el contenido del Intent según corresponda.

RESULT_OK

• La transacción fue procesada (exitosa o rechazada por el banco, pero el flujo se completó correctamente).
• El Intent contendrá el JSON bajo "transactionResult", con los campos de salida principales:
  • transactionStatus
  • sequenceNumber
  • printerVoucherCommerce
  • transactionTip
  • transactionCashback
  • extraData
• Tu aplicación debe leer el JSON, interpretar los valores y registrar la venta o mostrar la confirmación al usuario.

RESULT_CANCELED

• El flujo se interrumpió antes de finalizar.
• Posibles causas:
  • El usuario presionó “Atrás”.
  • Error de validación (por ejemplo, amount inválido).
  • Error de configuración del terminal o SDK.
• En este caso, el Intent contendrá un JSON de error en "transactionResult" con:
  • errorCode
  • errorMessage

4. Manejo del Voucher

• El comportamiento de impresión depende del valor del parámetro printVoucherOnApp enviado en la Fase 1:

  • true → El voucher fue impreso directamente por TUU Negocio (en el POS).

  • false → Tu aplicación integradora debe encargarse de la impresión o presentación del comprobante.

Manejo de errores

Errores pre-transaccionales

Cuando exista algún error, ya sea con la validación de los parámetros de entrada o del lado del servidor, se retornará un JSON con la siguiente estructura a la app.

{
	"errorCode": 1,
	"errorMessage": "La app de pago no soporta propina de acuerdo a sus configuraciones.",
	"errorCodeOnApp": 500,
	"errorMessageOnApp": "Internal Server Error"
}

Errores post-transaccionales

Listado de errores se encuentra disponible en Errores Post-Transaccionales