Documentacion Integracion Caja POS
Documentacion Integracion Caja POS
Documentacion Integracion Caja POS
Tabla de Contenido
1 Tabla de Contenido
2 CONCEPTO
3 VERSION ACTUAL
4 INSTALACIÓN
4.1 En Windows
4.1.1 Paso 1: Copiar Backend del SDK
4.1.2 Paso 2: Instalar Driver del cable (solo para conexión por cable)
4.1.3 Paso 3: Configuración del Backend
4.1.4 Paso 4: Levantar el backend
4.1.5 Paso 5: Levantar el Simulador para pruebas
4.2 En Linux
4.2.1 Paso 1: Copiar backend del SDK
4.2.2 Paso 2: Verificar puerto en el que se conectó el POS (en caso de ser conexión directa por cable)
4.2.3 Paso 3: Configuración del Backend
4.2.4 Paso 4: Asignar permisos y ejecutar backend
4.2.5 Paso 5: Asignar permisos y levantar simulador para realizar pruebas
5 CONFIGURACIONES
5.1 Backend como servicio de Windows
5.2
5.2.1 Paso 1: Instalar SrvStart
5.2.2 Paso 2: Modificar el archivo BancardSDK.ini
5.2.3 Paso 3: Utilizar el simbolo de Sistema para crear el nuevo servicio
5.2.4 Controlar servicio desde el Símbolo de Sistema
5.3 Backend como servicio de Linux
5.3.1 Paso 1: Crear archivo de configuración para systemctl
5.3.2 Paso 2: Activar y controlar el servicio
6 SERVICIOS REST DISPONIBLES
6.1 Solicitud Venta Contado
6.2 Solicitud Venta Cuotas
6.3 Solicitud Venta Forzado Débito
6.4 Solicitud Venta Forzado Crédito
6.5 Envío de Monto
6.6 Verificación de conexión de POS - Mensaje ECO
7 TABLA DE ISSUER ID's
CONCEPTO
El SDK de integración Caja POS es un Servicio REST empaquetado que se instala en el equipo donde se encuentra conectado el POS, su función es
traducir las peticiones que recibe como JSON al protocolo RS232 que es interpretado por el POS, esto facilita a los desarrolladores a realizar la
integración con su sistema de caja.
VERSION ACTUAL
La versión actual del SDK es la 1.5.0 y lo podemos descargar (dependiendo de nuestro S.O y arquitectura) desde el siguiente enlace: https://gitlab.
com/larojas/bancard-integracion-cajapos/-/tree/v1.5.0
INSTALACIÓN
En Windows
Para la instalación del SDK es necesario primeramente descargar el backend que nos servirá para levantar el Web Services REST al
que realizaremos las peticiones para la comunicación con el POS de Bancard, podemos ver la última versión disponible aquí.
apidoc: Archivos necesarios para ver la documentación del WS una vez levantado el backend.
logs: Carpeta donde se guardará el log del backend.
config.json: Archivo de configuración del backend (más adelante veremos su contenido).
index.exe: Archivo ejecutable para levantar el WS del backend.
serialport.node: Librería para la comunicación con el POS.
Paso 2: Instalar Driver del cable (solo para conexión por cable)
Descargar e instalar el Driver necesario para el cable de comunicación con el POS, podemos obtener el driver ingresando en la sección de
Windows del repositorio del SDK que tenemos aquí.
Una vez instalado conectamos el cable a la PC y verificamos en que puerto lo está reconociendo, este dato nos servirá para configurar el
backend antes de iniciarlo. Para ello ingresamos a "Mi PC" Propiedades Administrador de dispositivos
Ver la opción "Ports" o "Puertos" donde se despliegan los dispositivos conectados. El correspondiente a USB-Serial CH 340 es el dispositivo
POS. Por tanto nuestro puerto COM será el 4 según el ejemplo mostrado en la imagen:
{
"com": "com4", // Puerto de conexión del dispositivo POS.
"reintentos": 3, // Reintentos de conexión al POS, se sugiere dejar en 3.
"transaction_timeout": 1, // Tiempo en minutos para que el backend devuelva timeout.
"server": {
"port": 3000 // Puerto en el que se levantará el Web Services de backend.
},
"log": {
"maxSize": 5, // Tamaño en MB de los archivos de logs.
"backups": 3, // Cantidad de archivos de logs que serán generados.
"absolutePath": "C:/sdk-backend-windows-x64/logs/application.log" // Ruta absoluta del log.
},
"tam":100, // Tamaño en bytes de cada mensaje que se envía al pos.
"delayTime":100, // Tiempo en milisegundos que espera para enviar entre los mensaje partidos.
"baudRate": 9600, // Configuraciones propias de la librería serialport que se deben quedar fijos.
"bufferSize": 250, // Configuraciones propias de la librería serialport que se deben quedar fijos.
"useTCP": false, // Indica si se debe utilizar o no conexión TCP/IP para comunicarse con el POS.
"tcpPOS": { // Se utiliza si no se envía los valores en el queryParams de las invocaciones.
"host": "192.168.1.102", // IP asignada al POS (solo si useTCP está en true).
"port": 15000, // Puerto del POS (solo si useTCP está en true).
}
}
Observación
El backend estará activo siempre que la ventana de la consola se encuentre abierta, si queremos poner como servicio de Windows de
forma que arranque al iniciar el Sistema Operativo vayamos a la sección de Configuraciones
En Linux
Para la instalación del SDK es necesario primeramente descargar el backend que nos servirá para levantar el Web Service REST al
que realizaremos las peticiones para la comunicación con el POS de Bancard, podemos ver la última versión disponible para nuestro
Sistema Operativo aquí.
apidoc: Archivos necesarios para ver la documentación del WS una vez levantado el backend.
logs: Carpeta donde se guardará el log del backend.
config.json: Archivo de configuración del backend (más adelante veremos su contenido).
index.exe: Archivo ejecutable para levantar el WS del backend.
serialport.node: Librería para la comunicación con el POS.
Paso 2: Verificar puerto en el que se conectó el POS (en caso de ser conexión directa por cable)
Par saber en que puerto se encuentra conectado el POS debemos ingresar a la terminal y ejecutar el siguiente comando:
Comando
Se listan los dispositivos conectados. Utilizaremos el código tty0, tty1, etc según el número de puerto habilitado para el POS para agregar en el
archivo de configuración.
{
"com": "/dev/ttyUSB0", // Puerto de conexión del dispositivo POS con cable USB.
"reintentos": 3, // Reintentos de conexión al POS, se sugiere dejar en 3.
"transaction_timeout": 1, // Tiempo en minutos para que el backend devuelva timeout.
"server": {
"port": 3000 // Puerto en el que se levantará el Web Services de backend.
},
"log": {
"maxSize": 5, // Tamaño en MB de los archivos de logs.
"backups": 3, // Cantidad de archivos de logs que serán generados.
"absolutePath": "C:/sdk-backend-windows-x64/logs/application.log" // Ruta absoluta del log.
},
"tam":100, // Tamaño en bytes de cada mensaje que se envía al pos.
"delayTime":100, // Tiempo en milisegundos que espera para enviar entre los mensaje partidos.
"baudRate": 9600, // Configuraciones propias de la librería serialport que se deben quedar fijos.
"bufferSize": 250, // Configuraciones propias de la librería serialport que se deben quedar fijos.
"useTCP": false, // Indica si se debe utilizar o no conexión TCP/IP para comunicarse con el POS.
"tcpPOS": { // Se utiliza si no se envía los valores en el queryParams de las invocaciones.
"host": "192.168.1.102", // IP asignada al POS (solo si useTCP está en true).
"port": 15000, // Puerto del POS (solo si useTCP está en true).
}
}
Comando
Al levantar el backend veremos en pantalla la versión y el puerto en el que se encuentra escuchando el Web Services como se muestra en la
imagen.
Comando
También podemos levantar el simulador para pruebas por entorno gráfico haciendo doble clic en el ejecutable simulador-cajapos y se
levantará la aplicación de pruebas, allí tendremos la opción de Listar Puertos para ver en que puerto se encuentra conectado nuestro POS y
podremos usar las opciones disponibles en el backend para venta contado o en cuotas. Para hacer las pruebas debemos cargar la IP y PUERTO
del backend así como también podemos activar el protocolo TCP/IP si tenemos configurada esta opción en el backend.
CONFIGURACIONES
Backend como servicio de Windows
Comando
Cuando se ejecute el comando, debes recibir un mensaje satisfactorio como en la imagen siguiente:
Observación
Cuando se crea el servicio la primera vez debemos arrancarlo, caso contrario recién estará corriendo al reiniciar el equipo.
De ahora en adelante, tu nuevo servicio se ejecutará cada vez que se inicie Windows. Si abres la interfaz de servicios de Windows (haz clic en
Inicio y escribe «Servicios»), puedes encontrar y configurar el nuevo servicio al igual que con cualquier otro.
Controlar servicio desde el Símbolo de Sistema
Comandos
Una vez realizado estos pasos nuestra API se estará ejecutando cada vez que iniciemos el Sistema Operativo.
Comando
Ahora debemos agregar el siguiente contenido para crear nuestro servicio personalizado y hacer, además, que se ejecute automáticamente al
inicio de nuestro servidor Linux:
bancard-integracion.service
[Unit]
Description=Bancard SDK Integracion Caja POS
After=multi-user.target
[Service]
Type=simple
ExecStart=/opt/sdk-backend-linux-x64/index # Solo funcionará si nuestro SDK se encuentra en /opt/
User=root
StandardOutput=syslog
StandardError=syslog
[Install]
WantedBy=multi-user.target
Guardamos y salimos con Ctrl+o y Ctrl+x, y ya tenemos el servicio definido y configurado en /etc/systemd/system/bancard-integracion.service
Comandos
Una vez realizado estos pasos nuestra API se va a ejecutar cada vez que iniciemos el Sistema Operativo.
Solicitud Venta Contado: Opción utilizada para realizar pago al contado y descuentos por BIN si los hubiera (no discrimina tipo de tarjeta
se realiza la transacción en un solo pago).
Solicitud Venta Cuotas: Opción utilizada para venta en cuotas.
Luego de obtener la respuesta del servicio solicitado se envía el monto a cobrar al siguiente servicio:
Envio del Monto: Opción para enviar Descuento o Monto de Transacción si no hubiera descuento por BIN.
Mensaje Eco: Esta opción podría servir para agregar antes de hacer un pedido de venta y asegurarnos que el POS se encuentre conectado.
URL localhost:port/pos/venta-ux
Query Opcionales.
Params
postHost: IP del POS.
{
"facturaNro": 123456789,
"monto": 50000
}
Donde:
{
"bin": "9999999999",
"nsu": "999999"
}
Donde:
bin: string(10) Corresponde al número BIN de la tarjeta asociada a la operación. Se puede utilizar este valor para realizar
descuentos según el tipo de tarjeta.
nsu: string(6) Código de operación interna entre el POS y el SDK. Este número debe ser enviado junto con el monto en el
servicio de Envío de monto.
Una vez recibido los datos del Servicio se envía el monto a cobrar y el nsu al servicio de Envío de monto
Body
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
Método POST
URL localhost:port/pos/venta-ux
Query Opcionales.
Params
postHost: IP del POS.
JSON Entrada
Body
{
"facturaNro": 123456789,
"monto": 50000,
"cuotas": 12,
"plan": 1
}
Donde:
Valor 1 para pago en cuotas (cuando las cuotas son mayores a 1).
Valor 0 para ventas en un solo pago.
{
"bin": "9999999999",
"nsu": "999999"
}
Donde:
bin: string(10) Corresponde al número BIN de la tarjeta asociada a la operación. Se puede utilizar este valor para realizar
descuentos según el tipo de tarjeta.
nsu: string(6) Código de operación interna entre el POS y el SDK. Este número debe ser enviado junto con el monto en el
servicio de Envío de monto.
Una vez recibido los datos del Servicio se envía el monto a cobrar y el nsu al servicio de Envío de monto
Error Status 500: Error interno del SDK
Response
Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra
Body
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
Método POST
URL localhost:8081/pos/venta/debito
Query Opcionales.
Params
postHost: IP del POS.
JSON Entrada
Body
{
"facturaNro": 123456789
}
Donde:
{
"bin": "9999999999",
"nsu": "999999"
}
Donde:
bin: string(10) Corresponde al número BIN de la tarjeta asociada a la operación. Se puede utilizar este valor para realizar
descuentos según el tipo de tarjeta.
nsu: string(6) Código de operación interna entre el POS y el SDK. Este número debe ser enviado junto con el monto en el
servicio de Envío de monto.
Una vez recibido los datos del Servicio se envía el monto a cobrar y el nsu al servicio de Envío de monto
Error Status 500: Error interno del SDK
Response
Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra
Body
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
Método POST
URL localhost:port/pos/venta/credito
Query Opcionales.
Params
postHost: IP del POS.
JSON Entrada
Body
{
"facturaNro": 123456789,
"cuotas": 12,
"plan": 1
}
Donde:
{
"bin": "9999999999",
"nsu": "999999"
}
Donde:
bin: string(10) Corresponde al número BIN de la tarjeta asociada a la operación. Se puede utilizar este valor para realizar
descuentos según el tipo de tarjeta.
nsu: string(6) Código de operación interna entre el POS y el SDK. Este número debe ser enviado junto con el monto en el
servicio de Envío de monto.
Una vez recibido los datos del Servicio se envía el monto a cobrar y el nsu al servicio de Envío de monto
Body
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
Envío de Monto
Método POST
URL IP:PORT/pos/descuento
JSON Entrada {
"bin": "9999999999",
"nsu": "999999",
"monto": 150000
}
Donde:
{
"codigoAutorizacion": "575849",
"nroBoleta": "000270613845",
"codigoComercio": "5051107",
"nombreTarjeta": "VISA - PREPAGA - BANCO ITAU PY",
"pan": "1234",
"mensajeDisplay": "APROBADA",
"saldo": 150000,
"nombreCliente": "GONZALEZ/JOSE",
"issuerId": "VS"
"montoVuelto": 30000,
}
Donde:
pan: string(4) Personal Account Number. Son los últimos 4 dígitos de la tarjeta.
saldo: int(12) Se envía cuando son tarjetas de débito que tienen saldo en cuenta.
Algunos campos pueden no aparecer, dependiendo del tipo de tarjeta utilizada, ningún campo puede ser
utilizado como requerido por el sistema.
{
"statusCode": 400,
"error": "Bad Request",
"message": "Mensaje enviado por el POS"
}
Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación
del usuario
URL IP:PORT/pos/eco
Donde:
eco: int(2) Corresponde a un número de hasta dos dígitos a ser enviado al POS.
{
"eco": 1,
}
Donde:
Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra
{
"statusCode": 400,
"error": "Bad Request",
"message": "No se pudo establecer conexión con el POS"
}
{
"statusCode": 400,
"error": "Bad Request",
"message": "Error de rango: 299"
}
BANCARD Crédito BC
CABAL Crédito CB
CREDICARD Débito IC
CREDICARD Crédito PC
CREDIFIELCO Crédito CC
INFONET Débito ID
MASTERCARD Crédito MC
MASTERCARD Débito MD
PANAL Crédito CP
UNICA Débito UD
VISA Crédito VC
VISA Débito VD