Windows
En esta documentación se definen los parámetros y elementos necesarios para utilizar el SDK de Mobbex en la plataforma Windows, permitiendo su integración con otras aplicaciones.
Antes de comenzar, debe asegurarse de tener instalada la plataforma .NET Framework versión 4.5.2 Todos los archivos descargados desde nuestro repositorio se deben copiar juntos en la ubicación que usted elija dentro de su aplicación. El archivo principal y con el cuál deberá interactuar vía consola es Mobbex.exe
Para poder utilizar este SDK, es necesario que el usuario inicie sesión desde el propio ejecutable, utilizando la ventana que se le mostrará la primera vez que lo utilice. En el caso de vencerse la sesión, el sistema automáticamente le pedirá que inicie sesión nuevamente.
En forma conjunta, es necesario establecer mediante la variable de entorno ENTITY la entidad con la cual el usuario quiere acceder y operar. Sin este parámetro no es posible acceder a los servicios.
En en caso de algunas operaciones, en lugar de iniciar sesión es posible utilizar las credenciales de API y Access Token generadas para el comercio, posibilitando utilizar el SDK en entornos de backend. Las mismas se definen en las variables de entorno XAPIKEY y XACCESSTOKEN respectivamente Estas operaciones estarán indicadas en cada uno de sus apartados.
Por otro lado, es necesario configurar las opciones de salida del SDK, utilizadas para almacenar y/o imprimir los cupones correspondientes a las transacciones, una vez que son completadas (independientemente de su resultado). Al menos una de las dos opciones de salida debe estar configuradas, caso contrario se generará una alerta al iniciar la aplicación. Estos parámetros se definen en el mismo archivo de configuraciones, dentro del nodo "output".
- folder: indica la carpeta donde se almacenarán los cupones en formato PDF al finalizar la transacción
- printer: este nodo contiene las propiedades de la impresora utilizada para imprimir los cupones al finalizar la transacción. La propiedad name hace referencia al nombre de la impresora tal como está definida en Windows. La propiedad type indica el tipo de impresora (valores admitidos: "normal" y "ticket").
La definición de la carpeta y/o impresora de cupones también puede realizarse enviando estos parámetros como opciones al ejecutar Mobbex.exe, teniendo en cuenta la sintaxis de opciones por consola:
Donde el caracter : es el separador del nombre y tipo de la impresora. Si se opta por esta opción, estas opciones deberán ser enviadas en toda llamada al SDK.
Esta operación permite el uso de clave API y Access Token
Para esto se debe ejecutar la opción -cit del programa, pasando como parámetros de la opción todos los atributos de la operación en formato JSON. Los parámetros son los mismos que los definidos para un Checkout tradicional (para más información ver documentación de Checkout)
Para generar un checkout en modo test o modo de pruebas, simplemente se debe agregar al programa la opción -t Ejemplo:
La respuesta del SDK será similar a la siguiente:
Con el SDK es posible utilizar el servicio de cobros presenciales de Mobbex y ser integrado a otras aplicaciones.
El primer paso para utilizar el servicio es crear el token de la operación, necesario para todas las demás etapas.
Esto se realiza con la opción -cp, pasando como parámetros en formato JSON los siguientes:
- description: Descripción de la Operación. Obligatorio.
- total: Total de la operación. Obligatorio.
- reference: Referencia de la operación a realizar. Este parámetro es opcional.
- input: Alternativa de ingreso de los datos de tarjeta. Este parámetro es obligatorio. Valores posibles: reader / manual
Ejemplo:
Deberemos almacenar el valor de intent.token para utilizarlo en los pasos siguientes.
En este paso crearemos el token perteneciente a la tarjeta con la cuál se realizará la operación. Se realiza con la opción -ct, pasando como parámetro el intent token generado en el paso anterior.
Tal como se especificó al crear el token del POS, existen 2 formas de cargar los datos de la tarjeta:
- Ingreso manual: con la opción -m luego de los parámetros de la opción -ct. Esta opción abre una ventana para que el usuario pueda cargar los datos de la tarjeta y, además, seleccionar el plan de cuotas de la operación. Ejemplo:
- Ingreso a través de lector de tarjetas Mox: con la opción -r luego de los parámetros de la opción -ct. Se debe indicar como parámetro de esta opción el tipo de lector a utilizar para realizar la operación, siendo los valores actualmente soportados:
- BBPOS_CHBT: Permite utilizar el lector BBPOS modelo CHB10
El resultado de ejecutar el comando tendrá una salida como la siguiente:
En este paso debemos almacenar los siguientes valores:
- data.data.token: Es el token que hace referencia a la tarjeta almacenada.
- options.bin: Será utilizado en el próximo paso para identificar el tipo de tarjeta.
- options.installment.reference: Hace referencia al plan de cuotas seleccionado. Aplica solo a carga manual de tarjeta.
En el caso de que la operación de tokenización haya sido realizada con un lector, o simplemente requiera obtener los medios de pago (planes de cuotas) asociados a una determinada marca de tarjeta, debe utilizar esta opción del SDK. Debe llamarse al archivo con la opción -gi pasando como parámetro de la opción los siguientes datos:
- it: Intent token de la operación. Este parámetro es Obligatorio.
- bin: Primeros 6 dígitos de la tarjeta sobre los cuales se quieren obtener los planes de cuotas. Es un valor retornado también de la operación anterior. Este parámetro es Obligatorio.
- installments: esta opción indica si calcular los valores de cuotas de las formas de pago. Valores true/false. Este parámetro es opcional y por defecto es true.
Ejemplo de utilización de esta opción:
El resultado de esta operación es la siguiente:
El parámetro a almacenar en este caso es reference del plan de cuotas elegido.
La opción -gp permite listar todos los medios de pago y cuotas configuradas y habilitadas en un comercio. Simplemente se debe indicar el importe con el cual se desea procesar la operación y mostrar los diferentes planes de cuotas.
El importe se indica dentro de las opciones en formato JSON del comando, en la propiedad total
Ejemplo:
Esta opción debe ser utilizada al cargar los datos de tarjeta a través del lector. De esta forma se especifican los datos del propietario de la tarjeta. En el caso de las tarjetas cargadas manualmente, este paso es opcional.
Se debe utilizar la opción -cc pasando como parámetros los siguientes:
- it: Indica el token del POS generado anteriormente. Obligatorio.
- customer: nodo con los datos del cliente
- customer.email: Email del cliente al cual se le enviará el comprobante. Obligatorio.
- customer.identification: Número de documento del cliente propietario de la tarjeta. Obligatorio.
- customer.name: Nombre del cliente propietario de la tarjeta. Obligatorio.
- customer.phone: Número de celular del cliente. Opcional.
Ejemplo:
Debemos almacenar el valor uid con el token del cliente, para luego confirmar la operación.
Para confirmar la operación y ejecutar finalmente el cobro, únicamente debe llamar al SDK con la opción -co y los siguientes parámetros en formato JSON:
- it: Intent token de la operación.
- source: Nodo que contiene los datos referidos a la tarjeta a procesar.
- source.token: Token de la tarjeta.
- source.bin: Primeros 6 dígitos de la tarjeta (BIN) obtenido en la etapa de tokenización de la tarjeta.
- installment: referencia del plan de cuotas o forma de pago de la tarjeta.
- customer: Token del cliente con el que se procesa la operación. Obligatorio cuando el ingreso de la tarjeta es por lector, opcional cuando el ingreso es manual.
Ejemplo:
Al ejecutar el comando se abrirá una ventana donde deberá ingresar el código de seguridad (CVV) de la tarjeta, para poder confirmar finalmente la operación.
Luego de ingresar el CVV y confirmar, el resultado del comando es similar al siguiente:
Además de la salida por consola, el sistema almacenará el cupón de la operación en formato PDF en la carpeta indicada y/o realizará la impresión del mismo por la impresora configurada.
Esta operación permite el uso de clave API y Access Token
Si se desea recuperar los datos de una operación teniendo su identificador de cupón, se puede hacer utilizando la opción -go del SDK, pasando como parámetro el identificador de operación en formato JSON dentro de la propiedad uid Ejemplo:
Si además de mostrar los datos por consola se desea obtener el comprobante de la operación (en formado PDF o por impresora según lo configurado) se puede agregar opcionalmente la propiedad save con valor true
En este caso el comprobante se almacenará y/o imprimirá según los parámetros de configuración definidos.
Esta operación permite el uso de clave API y Access Token
Si desea recuperar los datos de una operación teniendo la referencia definida al crearla, se puede hacer utilizando la opción -gr del SDK, pasando como parámetro el identificador de operación en formato JSON dentro de la propiedad reference Ejemplo:
Esta operación permite el uso de clave API y Access Token
Permite recuperar un conjunto de operaciones en base en un parámetro particular de las mismas. Se realiza utilizando la opción -gos del SDK. Tiene 2 tipos de parámetros:
- -page: el listado se muestra paginado, por lo que debe indicar la página a mostrar. Comienza en el índice 0.
- -limit: indica la cantidad de registros a mostrar por página. Máximo 50 operaciones. Por defecto se muestran 15 operaciones.
Los parámetros que permiten filtrar las operaciones a listar se deben colocar en formato JSON a continuación del comando. Si no se desean aplicar filtros, simplemente se debe enviar el objeto JSON vacío {}. Los parámetros válidos son equivalentes a los definidos en Listado de Operaciones
Ejemplo:
Desde esta opción puede gestionar la devolución de una operación realizada a través del POS. La opción a utilizar es -ro y únicamente se deben indicar 2 parámetros:
- uid: Identificador único de la operación. Obligatorio.
- total: Indica el monto a devolver, en el caso de que quiera realizarse una devolución parcial. En el caso de devolución total, este parámetro no es obligatorio.
Ejemplo:
En el caso de que la operación haya sido procesada utilizando lector, automáticamente el sistema solicitará deslizar la tarjeta para validar la devolución.
Esta operación permite el uso de clave API y Access Token
Esta opción sólo puede utilizarse en el caso de que se tenga autorizada la operatoria en 2 pasos. Se utiliza la opción -cap indicando 2 parámetros:
- uid: Identificador único de la operación. Obligatorio.
- total: Indica el monto a capturar, en función del porcentaje autorizado por la marca. Obligatorio.
Ejemplo
