SDK

Windows

33min
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 repositorio url https //github com/mobbexco/desktop sdk https //github com/mobbexco/desktop sdk primeros pasos 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 configuración de parámetros 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") "output" { "folder" " ", "printer" { "name" "hp laserjet 1102w", "type" "normal" } } 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 mobbex exe f " " p "hp laserjet 1102w\ normal" 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 operaciones crear checkout 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 https //mobbex dev/vprq checkout ) para generar un checkout en modo test o modo de pruebas, simplemente se debe agregar al programa la opción t ejemplo mobbex exe t cit "{\\"total\\" 100, \\"currency\\" \\"ars\\", \\"description\\" \\"venta de prueba\\", \\"reference\\" \\"referencia001\\", \\"customer\\" {\\"identification\\" \\"99999999\\", \\"email\\" \\"demo\@mobbex com\\", \\"name\\" \\"demo user\\"}}" la respuesta del sdk será similar a la siguiente { "operation" "cit", "type" "result", "data" { "result"\ true, "data" { "id" "znllbhdo0dk1e1fc3g", "url" "https //mobbex com/p/checkout/v2/znllbhdo0dk1e1fc3g", "description" "venta de prueba", "currency" "ars", "total" 100, "created" 1606264299516 } } } } crear pos de cobros 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 mobbex exe cp "{\\"description\\" \\"descripción del pos\\", \\"total\\" 10, \\"input\\" \\"reader\\"}" deberemos almacenar el valor de intent token para utilizarlo en los pasos siguientes crear token de tarjeta 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 mobbex exe ct "{\\"it\\" \\"a143c8e2 46ae 4e61 8ddb ec6f10f6d57b\\"}" 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 mobbex exe ct "{\\"it\\" \\"a143c8e2 46ae 4e61 8ddb ec6f10f6d57b\\"}" m 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 mobbex exe ct "{\\"it\\" \\"a143c8e2 46ae 4e61 8ddb ec6f10f6d57b\\"}" r "bbpos chbt" el resultado de ejecutar el comando tendrá una salida como la siguiente { "operation" "ct", "type" "result", "data" { "result"\ true, "data" { "token" "t\ abgtu olh", "description" "visa débito terminada en 0010", "source" { "references" \["visa debit"], "reference" "visa debit", "generic" "visa debit", "compatreference" "visa debit", "name" "visa débito", "shortname" "visa débito", "currency" "ars", "card" { "level" "classic", "product" { "name" "visa débito", "shortname" "visa débit", "variant" "debit", "lengths" \[16], "gaps" \[4,8,12], "code" { "name" "cvv", "length" 3, "position" 1 }, "logo" "https //res mobbex com/images/sources/png/visa png", "validation" \["length","exp","cvv","luhn"] }, "issuer" { "shortname" "visa", "name" "visa", "color" "#122d98", "logo" "https //res mobbex com/images/sources/png/visa png" } }, "type" "card", "priority" 0 } } }, "options" { "bin" "450799" } } } 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 obtener cuotas de una tarjeta específica 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 mobbex exe gi "{\\"it\\" \\"a143c8e2 46ae 4e61 8ddb ec6f10f6d57b\\", \\"bin\\" \\"450799\\", \\"installments\\" true}" el resultado de esta operación es la siguiente { "operation" "gi", "type" "result", "data" { "result"\ true, "data" { "type" "card", "source" { "references" \["visa debit"], "reference" "visa debit", "generic" "visa debit", "compatreference" "visa debit", "name" "visa débito", "shortname" "visa débito", "currency" "ars", "card" { "level" "classic", "product" { "name" "visa débito", "shortname" "visa débit", "variant" "debit", "lengths" \[16], "gaps" \[4,8,12], "code" { "name" "cvv", "length" 3, "position" 1 }, "logo" "https //res mobbex com/images/sources/png/visa png", "validation" \["length","exp","cvv","luhn"] }, "issuer" { "shortname" "visa", "name" "visa", "color" "#122d98", "logo" "https //res mobbex com/images/sources/png/visa png" } }, "type" "card", "priority" 0 }, "installments" \[{ "name" "débito", "description" "10% de descuento", "sourcereference" "", "count" 1, "reference" "1", "percentage" 10, "entity percentage" 0, "discount" 0, "promo code" "", "modes" \["cnp","cp"], "status" "active", "order" 1, "updated" "2020 10 27t13 39 59 829z", "created" "2020 03 25t22 37 02 155z", " id" "5e7bdd0e2b6c8c490948ad8d", "uid" "4ezzxhee4", "type" "direct", "updatedby" "5d682afc8d0b0318fd9691d7", "totals" { "currency" { "value" "test", "label" "test money", "symbol" "t$", "hidden"\ false }, "installment" { "amount" 90, "count" 1 }, "total" 90, "financial" { "percentage" 10, "amount" 10 } } }] } } } el parámetro a almacenar en este caso es reference del plan de cuotas elegido listar medios de pago de una entidad 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 mobbex exe gp "{\\"total\\" 100}" crear token de cliente 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 mobbex exe cc "{\\"it\\" \\"a143c8e2 46ae 4e61 8ddb ec6f10f6d57b\\", \\"customer\\" {\\"email\\" \\"demo\@mobbex com\\", \\"identification\\" \\"12123123\\", \\"name\\" \\"cliente demo\\"}}" debemos almacenar el valor uid con el token del cliente, para luego confirmar la operación confirmar 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 mobbex exe co "{\\"it\\" \\"a143c8e2 46ae 4e61 8ddb ec6f10f6d57b\\", \\"source\\" {\\"token\\" \\"t\ abgtu olh\\", \\"bin\\" \\"450799\\"}, \\"installment\\" \\"1\\", \\"customer\\" \\"cus\ eoshwl65hh\\"}" 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 {"operation" "co", "type" "result", "data" { "result"\ true, "data" { "view" "result", "options" {}, "id" "erne0mbjk", "status" { "code" "400", "text" "rechazado", "message" "la tarjeta ingresada es inválida verifique la tarjeta ingresada (cod 103)" }, "total" 90, "currency" { "value" "test", "label" "test money", "symbol" "t$", "hidden"\ false}, "data" \[ { "type" "item", "key" "transactionid", "label" "id de transacción", "value" "erne0mbjk", "priority" 2, "visibility" "visible" }, { "type" "item", "key" "cardnumber", "label" "tarjeta", "value" "450799 0010", "priority" 99, "visibility" "hidden" } ], "actions" \[ { "label" "imprimir", "key" "print", "type" "default", "action" { "type" "print", "data" { "url" "https //ms mobbex com/prod/reports", "path" "/v2/coupon/", "id" "erne0mbjk", "schema" "card"} } }, { "label" "reintentar", "key" "retry", "type" "primary", "action" { "type" "reload"} }] } } } 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 recuperar operación por cupón 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 mobbex exe go "{\\"uid\\" \\"erne0mbjk\\"}" 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 mobbex exe go "{\\"uid\\" \\"erne0mbjk\\", \\"save\\" true}" en este caso el comprobante se almacenará y/o imprimirá según los parámetros de configuración definidos recuperar operación por referencia 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 mobbex exe gr "{\\"reference\\" \\"pago 123456\\"}" recuperar listado de operaciones 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 obligatorios page el listado se muestra paginado, por lo que debe indicar la página a mostrar comienza en el índice 0 opcionales 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 https //mobbex dev/whq9 transactions#listado y busqueda de transacciones ejemplo mobbex exe gos "{\\"reference\\" \\"pago 123456\\"}" page 0 limit 20 devolver operación 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 mobbex exe ro "{\\"uid\\" \\"erne0mbjk\\", \\"total\\" 10}" 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 capturar operació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 mobbex exe cap "{\\"uid\\" \\"erne0mbjk\\", \\"total\\" 10}"