## Tabla de Contenido ``` 1 Tabla de Contenido 2 CONCEPTO 3 VERSION ACTUAL 4 IMPLEMENTACIÓN DE LA API REST 5 MIGRACIÓN DE LA SOLUCIÓN CAJAPOS CON SDK A POS ANDROID 6 SERVICIOS REST DISPONIBLES 6.1Solicitud Venta Contado 6.2Solicitud Venta Cuotas 6.3Solicitud Venta Forzado Débito 6.4Solicitud Venta Forzado Crédito 6.5Envío de Monto 6.6Verificación del JSON - Mensaje ECO 6.7Solicitud Venta QR - Vuelto QR 6.8Solicitud Venta QR PIX 6.9Solicitud Venta Canje 6.10Solicitud Venta Billetera 6.11Transacción de Consulta para Anulaciones 6.12Transacción de Anulación 6.13Rechazos Generales 6.14Anexos 7 TABLA DE ISSUER ID 8 TABLA DE BILLETERAS ``` ## CONCEPTO Con el objetivo de dotar de una mayor seguridad y generar un nuevo ecosistema de aplicaciones y experiencias con el uso de los POS, Bancard presenta un nuevo producto de POS basado en terminales Android. La integración CajaPOS entre los sistemas de facturación y las nuevas terminales Android se realizará a través de la red interna del comercio, utilizando servicios REST como protocolo de intercambio de mensajes. A continuación vemos una imagen del funcionamiento de la integración POS Android. #### VERSION ACTUAL #### IMPLEMENTACIÓN DE LA API REST # Integración CAJA POS - Android 2.0 v1.7 202410 ## VERSION ACTUAL ``` La versión de la API REST implementada en el POS es la 1.5.0. ``` ## IMPLEMENTACIÓN DE LA API REST ``` El software de facturación se comunicará con el POS Android a través de servicios REST que estarán publicados en el POS. Se deberá desarrollar en el sistema de facturación los servicios necesarios para poder establecer la comunicación hacia el POS como se describen en la sección SERVICIOS REST DISPONIBLES. ``` #### MIGRACIÓN DE LA SOLUCIÓN CAJAPOS CON SDK A POS ANDROID #### SERVICIOS REST DISPONIBLES ### Solicitud Venta Contado ``` Ver Detalles ``` ``` Los desarrolladores podrán realizar sus pruebas de integración utilizando un software cliente de su preferencia (Ej. Postman), a través de la dirección IP que el POS tiene asignado y el puerto de escucha 3000. ``` ## MIGRACIÓN DE LA SOLUCIÓN CAJAPOS CON SDK A POS ANDROID ``` Para aquellos comercios que ya han implementado la solución CajaPOS con el SDK, el único cambio necesario para utilizar el sistema de facturación con el POS Android será reemplazar en este la IP de conexión del "SDK" por la IP del POS que el punto de acceso inalámbrico le asigna, previos ajustes a nivel de red para asegurar la comunicación TCP/IP entre ambas terminales. Tener en cuenta que desde esta versión del documento, también será necesario ajustar las operaciones existentes debido a las validaciones que se realizan en el aplicativo POS con el fin de salvaguardar la integridad de los datos y de la aplicación misma. ``` ## SERVICIOS REST DISPONIBLES ``` La forma de comunicación con el POS será a través de peticiones REST. Se cuenta con las siguientes opciones: Solicitud Venta Contado : Opción utilizada para realizar una venta 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. Aplica solo para tarjetas de crédito. Solicitud Venta QR: Opción utilizada para venta con QR, donde el pago se realiza mediante la lectura del QR que se muestra en el POS a través de las apps de las entidades habilitadas. Solicitud Venta Billeteras: Opción utilizada para realizar venta con las billeteras habilitadas. Solicitud Venta Canje: Opción utilizada para realizar venta mediante el canje de punto de las tarjetas por Lealtad. Luego de obtener la respuesta del servicio solicitado se envía el monto a cobrar al siguiente servicio. Aplica para la operaciones de Venta Contado y Venta Cuotas. No aplica para Venta QR, Venta con Billeteras y Venta por Canje. Envio del Monto : Opción para enviar Descuento o Monto de Transacción si no hubiera descuento por BIN. También se tiene una llamada para verificar si el POS se encuentra conectado. 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. ``` ``` Método POST ``` ``` URL IP:PORT/pos/venta-ux ``` ``` JSON Entrada Body 1 2 { ``` ### Solicitud Venta Cuotas ``` Ver Detalles ``` ``` Donde: facturaNro : int(15) Corresponde al número de factura generado por el sistema. monto : int(9) es el valor del monto inicial de la transacción mayor a 0. Validaciones: ``` ``` Success Response ``` #### HTTP/1.1 200 OK ``` 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 del POS. Este número debe ser enviado junto con el monto en el servicio de Envío de monto. ``` ``` Error Response ``` ``` Status 500 : Error interno del POS Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra ``` #### 3 #### 4 ``` "facturaNro": 999999999999999, "monto": 999999999 } ``` ``` Body 1 2 3 4 ``` #### { ``` "bin": "9999999999", "nsu": "999999" } ``` ###  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 1 2 3 4 5 ``` #### { ``` "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 IP:PORT/pos/venta-ux JSON Entrada ``` ``` Donde: facturaNro : int(15) Corresponde al número de factura generado por el sistema. monto: int(9) Monto inicial de venta. cuotas : int(2) Cantidad de cuotas para el pago. Valor 0 para ventas en un solo pago. Valor mayor a 1 para ventas en cuotas (con valor 1 retornaría un error). plan : int(2) Plan de pago para promociones o descuentos: ``` ``` Body 1 2 3 4 5 6 { "facturaNro": 999999999999999, "monto": 999999999, "cuotas": 12, "plan": 1 } ``` ### Solicitud Venta Forzado Débito ``` Ver Detalles ``` ``` Valor 1 para pago en cuotas (cuando las cuotas son mayores a 1). Valor 0 para ventas en un solo pago. Validaciones: ``` ``` Success Response ``` #### HTTP/1.1 200 OK ``` 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 del POS. Este número debe ser enviado junto con el monto en el servicio de Envío de monto. ``` ``` Error Response ``` ``` Status 500: Error interno del POS Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra ``` ``` Body 1 2 3 4 ``` #### { ``` "bin": "9999999999", "nsu": "999999" } ``` ###  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 1 2 3 4 5 ``` #### { ``` "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 IP:PORT/pos/venta/debito ``` ``` JSON Entrada ``` ``` Donde: facturaNro : int(15) Corresponde al número de factura generado por el sistema. Validaciones: ``` ``` Success Response ``` #### HTTP/1.1 200 OK ``` Esta opción se utiliza para forzar que la operación sea con una tarjeta de débito, por lo tanto si se utiliza este endpoint dará un error al pasar una tarjeta de crédito. ``` ###  ``` Body 1 2 3 ``` #### { ``` "facturaNro": 999999999999999 } ``` ``` Body 1 { ``` ### Solicitud Venta Forzado Crédito ``` Ver Detalles ``` ``` 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 del POS. Este número debe ser enviado junto con el monto en el servicio de Envío de monto. ``` ``` Error Response ``` ``` Status 500: Error interno del POS Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra ``` #### 2 #### 3 #### 4 ``` "bin": "9999999999", "nsu": "999999" } ``` ###  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 1 2 3 4 5 ``` #### { ``` "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 IP:PORT/pos/venta/credito JSON Entrada ``` ``` Donde: facturaNro : int(12) Corresponde al número de factura generado por el sistema. cuotas : int(2) Cantidad de cuotas para el pago. Valor 0 para ventas en un solo pago. Valor mayor a 1 para ventas en cuotas (con valor 1 retornaría un error). plan : int(2) Plan de pago para promociones o descuentos: Valor 1 para pago en cuotas. Valor 0 para ventas en un solo pago. Validaciones: ``` ``` Success Response ``` #### HTTP/1.1 200 OK ``` Esta opción se utiliza para forzar que la operación sea con una tarjeta de crédito, por lo tanto si se utiliza este endpoint dará un error al pasar una tarjeta de débito ``` ###  ``` Body 1 2 3 4 5 ``` #### { ``` "facturaNro": 999999999999999, "cuotas": 12, "plan": 1 } ``` ``` Body 1 2 3 4 ``` #### { ``` "bin": "999999999999", "nsu": "9999999999" } ``` ### Envío de Monto ``` Ver Detalles ``` ``` 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 del POS. Este número debe ser enviado junto con el monto en el servicio de Envío de monto. ``` ``` Error Response ``` ``` Status 500: Error interno del POS Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra ``` ###  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 1 2 3 4 5 ``` #### { ``` "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 IP:PORT/pos/descuento ``` ``` JSON Entrada ``` ``` Donde: bin : string(10) Es el número BIN que fue respuesta del Paso 1. nsu: string(6) Código de la operación que fue respuesta del Paso 1. monto : int(9) Es el valor de descuento o monto de la transacción. Validaciones: ``` ``` Success Response ``` #### HTTP/1.1 200 OK ``` Donde: codigoAutorizacion : string(6) Es el código de autorización generado por el POS. nroBoleta : string(12) Corresponde al número de ticket. ``` #### 1 #### 2 #### 3 #### 4 #### 5 #### { ``` "bin": "9999999999", "nsu": "999999", "monto": 999999999 } ``` ``` Body 1 2 3 4 5 6 7 8 9 ``` #### 10 #### 11 #### 12 #### { ``` "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, } ``` ### Verificación del JSON - Mensaje ECO ``` Ver Detalles ``` ``` codigoComercio : string(12) Identificador del comercio generado por el POS. nombreTarjeta : string(40) Identificador de la tarjeta. pan : string(4) Personal Account Number. Son los últimos 4 dígitos de la tarjeta. mensajeDisplay : string(40) Mensaje enviado por el POS según el estado de la transacción. saldo : int(12) Se envía cuando son tarjetas de débito que tienen saldo en cuenta. nombreCliente : string(26) Nombre de la persona registrada en la tarjeta. issuerId : string(2) Identificador del tipo de tarjeta utilizado. montoVuelto : integer(12) Monto del vuelto ingresado en el POS. ``` ``` Error Response ``` ``` Status 500: Error interno en el POS Status 400: Transacción cancelada, transacción rechaza, pin inválido o error de validación ``` ``` Algunos campos pueden no aparecer, dependiendo del tipo de tarjeta utilizada, ningún campo puede ser utilizado como requerido por el sistema. ``` ###  1 2 3 4 5 #### { ``` "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 ``` Método POST URL IP:PORT/pos/eco ``` ``` JSON Entrada ``` ``` Donde: eco : int(2) Corresponde a un número de hasta dos dígitos a ser enviado al POS. Validaciones: ``` ``` Success Response ``` #### HTTP/1.1 200 OK ``` Donde: eco : int(2) El POS retorna el mismo número enviado inicialmente ``` ``` Error Response ``` ``` Status 500: Error interno del POS Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra ``` ``` Status 400: Error de rango. El número proporcionado supera el rango permitido, de 0 a 99 ``` #### 1 #### 2 #### 3 #### { ``` "eco": 99, } ``` #### 1 #### 2 #### 3 #### { ``` "eco": 99, } 1 2 3 4 5 ``` #### { ``` "statusCode": 400, "error": "Bad Request", "message": "No se pudo establecer conexión con el POS" } ``` #### 1 #### 2 #### 3 #### 4 #### { ``` "statusCode": 400, "error": "Bad Request", ``` ### Solicitud Venta QR - Vuelto QR ``` Ver Detalles ``` ``` 5 "message": "Error de rango: 299" } ``` ``` Método POST ``` ``` URL :/pos/venta-qr Header No tiene ``` ``` JSON Entrada sin promoción ``` ``` Donde: facturaNro: int(15) Corresponde al número de factura generado por el sistema. monto: int(9) es el valor del monto inicial de la transacción, debe ser mayor a 0. montoVuelto : int(9) es el valor del monto de vuelto. La presencial del campo es opcional. Si el campo está presente pero contiene valor 0, se asume la venta no tiene vuelto. ``` ``` Validaciones: ``` #### JSON ``` Entrada con promoción ``` #### { ``` "facturaNro" : 999999999999999, "monto" : 999999999, "promotions" : [ { "bin": "123456" , “ent_code” : “017” } ] } Donde: facturaNro: int(15) Corresponde al número de factura generado por el sistema. monto: int(9) es el valor del monto inicial de la transacción, debe ser mayor a 0. promotions: Es un array y es opcional, aplica solo para los comercios que quieran integrar QR con Promociones. ``` #### 1 #### 2 #### 3 #### 4 #### 5 #### { ``` "facturaNro" : 999999999999999, "monto" : 20000, "montoVuelto" : 10000 } ``` ``` Elementos de promotions Parámetro Detalle Longitud Maxima Descripción ``` ``` bin String Opcional ``` ``` 12 Bin de la tarjeta que participa en la promocion. ``` ``` ent_code String Opcional ``` ``` 3 Código de entidad que participa de la promoción. ``` ``` client String Opcional ``` ``` 2 Cliente que participa de la promoción. Valores posibles: PM para pago movil ENT para entidad. ``` ``` brand String Opcional ``` ``` 3 Marca de la tarjeta que participa en la promoción. ``` ``` product String opcional 3 Producto de la tarjeta que participa en la promoción. affinity String opcional 6 Afinidad de la tarjeta que participa en la promoción. ``` ``` Observación : Si se manda el atributo promotions debe contener al menos un elemento promotion y promotion a su vez debe contener algún valor de los atributos opcionales. ``` ###  ``` Validaciones: ``` ``` Ejemplos: ``` ``` Error al representar la macro 'code': valor inválido especificado para el parámetro 'firstline' { "facturaNro" : 999999999999999, "monto" : 999999999, "promotions" : [ {"bin": "123456" , "ent_code" : "017", "brand": "VS", "product": "CLA"} ] } ``` **Success Response** #### HTTP/1.1 200 OK ``` Si bien se detallan valores máximos para los valores de los sub-elementos , el array como tal no tiene un limite, debido que se puede enviar un elemento, como x elementos. Limite de 9.000 caracteres para el atributo "Promotions" ``` ``` Ejemplo promotions de un elemento con un sub-elemento 1 2 3 4 5 6 7 { "facturaNro": 999999999999999, "monto" : 999999999, "promotions" : [ {"ent_code" : "017"} ] } ``` ``` Ejemplo promotions de un elemento con varios sub-elementos ``` ``` { "facturaNro": 999999999999999, "monto" : 999999999, "promotions" : [ {"bin": "123456" , "ent_code" : "017"} ] } ``` ``` Ejemplo promotions de varios elementos con un sub-elemento ``` ``` { "facturaNro": 999999999999999, "monto" : 999999999, "promotions" : [ {"ent_code" : "017"}, {"ent_code" : "039"}, {"ent_code" : "042"} ] } ``` ``` Body 1 2 3 4 5 6 7 8 9 ``` #### 10 #### 11 #### 12 #### { ``` "codigoAutorizacion": "575849", ``` ``` "codigoComercio": "5051107", ``` ``` "issuerId": "VS", ``` ``` "mensajeDisplay": "APROBADA", ``` ``` "montoVuelto": 0, ``` ### Solicitud Venta QR PIX ``` Ver Detalles ``` ``` Donde: codigoAutorizacion: string(6) Es el código de autorización generado por el POS. codigoComercio: string(12) Identificador del comercio generado por el POS. issuerId : string(2) Identificador del tipo de tarjeta utilizado. mensajeDisplay : string(40) Mensaje enviado por el POS según el estado de la transacción. montoVuelto : integer(12) Monto del vuelto ingresado en el POS. nombreCliente : string(26) Nombre de la persona registrada en la tarjeta. nombreTarjeta : string(40) Identificador de la tarjeta. nroBoleta : string(12) Corresponde al número de ticket. saldo : int(12) Se envía cuando son tarjetas de débito que tienen saldo en cuenta. ``` ``` Error Response ``` ``` Status 500: Error interno en el POS Status 400: Transacción cancelada, transacción rechaza, pin inválido o error de validación ``` #### 13 #### 14 #### 15 #### 16 #### 17 #### 18 #### 19 #### 20 ``` "nombreCliente": "RODRIGUEZ/RENE", ``` ``` "nombreTarjeta": "VISA - CLASICA - BANCO ITAU PY", ``` ``` "nroBoleta": "000270613845", ``` ``` "saldo": 0 ``` #### } ``` Algunos campos pueden no aparecer, dependiendo del tipo de tarjeta utilizada, ningún campo puede ser utilizado como requerido por el sistema. ``` ###  1 2 3 4 5 #### { ``` "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 ``` Método POST ``` ``` URL :/pos/venta-qr-pix ``` ``` Header No tiene ``` ``` JSON Entrada sin promoción ``` ``` Donde: facturaNro: int(15) Corresponde al número de factura generado por el sistema. monto: int(9) es el valor del monto inicial de la transacción, debe ser mayor a 0. pix_payer_cpf : string(15) Para una venta PIX, se requiere el CPF del comprador pix_payer_phone : string(30) Para una venta PIX, se requiere el número de celular del comprador, a quien el sistema enviará un SMS o Push de confirmación de la venta pix_payer_email : string(30) Opcional, se informará el correo del comprador. La presencia del campo con el valor "" (vacío) es aceptado. ``` ``` Validaciones: ``` #### 1 2 3 4 5 6 7 #### { ``` "facturaNro" : 999999999999999, "monto" : 20000, "pix_payer_cpf" : "00000000000", "pix_payer_phone" : "+55123456789", "pix_payer_email" : "integraciones@gmail.com" } ``` ### Solicitud Venta Canje ``` Ver Detalles ``` ``` Success Response ``` #### HTTP/1.1 200 OK ``` Donde: codigoAutorizacion: string(6) Es el código de autorización generado por el POS. codigoComercio: string(12) Identificador del comercio generado por el POS. issuerId : string(2) Identificador del tipo de tarjeta utilizado. mensajeDisplay : string(40) Mensaje enviado por el POS según el estado de la transacción. montoVuelto : integer(12) Monto del vuelto ingresado en el POS. nombreCliente : string(26) Nombre de la persona registrada en la tarjeta. nombreTarjeta : string(40) Identificador de la tarjeta. nroBoleta : string(12) Corresponde al número de ticket. saldo : int(12) Se envía cuando son tarjetas de débito que tienen saldo en cuenta. montoRs : integer(12) Monto en Reales Error Response Status 500: Error interno en el POS Status 400: Transacción cancelada, transacción rechaza, pin inválido o error de validación ``` ``` Body 1 2 3 4 5 6 7 8 9 ``` #### 10 #### 11 #### 12 #### { ``` "codigoAutorizacion":"211861", "codigoComercio":"21", "issuerId":"PX", "mensajeDisplay":"Pago Exitoso", "montoVuelto":0, "nombreCliente":"QR PIX", "nombreTarjeta":"QR PIX", "nroBoleta":"3915109714", "saldo":100000, "montoRs":74. } 1 2 3 4 5 ``` #### { ``` "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 ``` Método POST URL :/pos/venta-canje ``` ``` Header No tiene ``` ``` JSON Entrada ``` ``` Donde: facturaNro: int(15) Corresponde al número de factura generado por el sistema. monto: int(9) es el valor del monto inicial de la transacción, debe ser mayor a 0. Observaciones: No aplica descuentos y promociones para ventas con Canje Validaciones: ``` #### 1 #### 2 #### 3 #### 4 #### { ``` "facturaNro" : 999999999999999, "monto" : 999999999 } ``` ### Solicitud Venta Billetera ``` Ver Detalles ``` ``` Success Response ``` #### HTTP/1.1 200 OK ``` Donde: codigoAutorizacion: string(6) Es el código de autorización generado por el POS. codigoComercio: string(12) Identificador del comercio generado por el POS. issuerId : string(2) Identificador del tipo de tarjeta utilizado. mensajeDisplay : string(40) Mensaje enviado por el POS según el estado de la transacción. montoVuelto : integer(12) Monto del vuelto ingresado en el POS. nombreCliente : string(26) Nombre de la persona registrada en la tarjeta. nombreTarjeta : string(40) Identificador de la tarjeta. nroBoleta : string(12) Corresponde al número de ticket. saldo : int(12) Se envía cuando son tarjetas de débito que tienen saldo en cuenta. ``` ``` Error Response ``` ``` Status 500: Error interno en el POS Status 400: Transacción cancelada, transacción rechaza, pin inválido o error de validación ``` ``` Body 1 2 3 4 5 6 7 8 9 ``` #### 10 #### 11 #### 12 #### 13 #### 14 #### 15 #### 16 #### 17 #### 18 #### 19 #### { ``` "codigoAutorizacion": "575849", ``` ``` "codigoComercio": "5051107", ``` ``` "issuerId": "LT", ``` ``` "mensajeDisplay": "APROBADA", ``` ``` "montoVuelto": 0, ``` ``` "nombreCliente": "LT", ``` ``` "nombreTarjeta": "VISA - CLASICA - BANCO ITAU PY", ``` ``` "nroBoleta": "000270613845", ``` ``` "saldo": 0 } ``` ``` Algunos campos pueden no aparecer, dependiendo del tipo de tarjeta utilizada, ningún campo puede ser utilizado como requerido por el sistema. ``` ###  1 2 3 4 5 #### { ``` "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 ``` Método POST ``` ``` URL :/pos/venta-billetera ``` ``` Header No tiene JSON Entrada 1 2 3 4 5 ``` #### { ``` "facturaNro" : 999999999999999, "monto" : 999999999, "billetera" : "ZIM", ``` ``` Donde: facturaNro: int(15) Corresponde al número de factura generado por el sistema. monto: int(9) es el valor del monto inicial de la transacción, debe ser mayor a 0. billetera: string(6) Identificador de billetera cuenta: string(16) Número de cuenta o teléfono asociado a la billetera Observaciones: No aplica descuentos y promociones para ventas con billeteras. Validaciones: ``` **Success Response** #### HTTP/1.1 200 OK ``` Donde: codigoAutorizacion: string(6) Es el código de autorización generado por el POS. codigoComercio: string(12) Identificador del comercio generado por el POS. issuerId : string(2) Identificador del tipo de tarjeta utilizado. ZM = Zimple; PI = Personal Itau; VB = Vision Banco; PJ = Paraguayo Japonesa mensajeDisplay : string(40) Mensaje enviado por el POS según el estado de la transacción. montoVuelto : integer(12) Monto del vuelto ingresado en el POS. nombreCliente : string(26) Nombre de la persona registrada en la tarjeta. nombreTarjeta : string(40) Identificador de la tarjeta. nroBoleta : string(12) Corresponde al número de ticket. saldo : int(12) Se envía cuando son tarjetas de débito que tienen saldo en cuenta. ``` **Error Response** ``` Status 500: Error interno en el POS Status 400: Transacción cancelada, transacción rechaza, pin inválido o error de validación ``` ``` 6 "cuenta" : "0981123456" } ``` ``` Body 1 2 3 4 5 6 7 8 9 ``` #### 10 #### 11 #### 12 #### 13 #### 14 #### 15 #### 16 #### 17 #### 18 #### 19 #### { ``` "codigoAutorizacion": "575849", ``` ``` "codigoComercio": "5051107", ``` ``` "issuerId": "ZM", ``` ``` "mensajeDisplay": "APROBADA", ``` ``` "montoVuelto": 0, ``` ``` "nombreCliente": "ZM", ``` ``` "nombreTarjeta": "Zimple - Debito Infonet", ``` ``` "nroBoleta": "000270613845", ``` ``` "saldo": 0 } ``` ``` Algunos campos pueden no aparecer, dependiendo del tipo de tarjeta utilizada, ningún campo puede ser utilizado como requerido por el sistema. ``` ###  1 2 3 4 5 #### { ``` "statusCode": 400, "error": "Bad Request", "message": "Mensaje enviado por el POS" ``` ### Transacción de Consulta para Anulaciones ``` Ver Detalles ``` #### } ###  Es importante usar el campo message para mostrar en la pantalla del Sistema para una mejor interpretación del usuario ``` Método POST ``` ``` URL IP:PORT/pos/consulta/anulacion ``` ``` JSON Entrada ``` ``` Consulta por nro. de boleta ``` ``` Consulta de últimas transacciones ``` ``` Donde: nroBoleta : int(12) Numero de boleta especifico a consultar. cantRegistro : int(2) Cantidad de registros a consultar ``` ``` Success Response ``` #### HTTP/1.1 200 OK ``` Donde: nroTarjeta : string(20) Numero de la tarjeta. nroBoleta : string(12) Corresponde al número de ticket monto : string(11) Monto de la transacción fechaHora : string(20) Fecha y hora de la transacción transacción : string(20) Método de autenticación de transacción. ``` ``` Body 1 2 3 4 ``` #### { ``` "nroBoleta": "002118671406", "cantRegistro": 1 } ``` ``` Body 1 2 3 4 ``` #### { ``` "nroBoleta": "", "cantRegistro": 10 } ``` ``` La consulta de Anulación prioriza el atributo nroBoleta antes que cantRegistro , es decir cuando se envía un numero de boleta omite el atributo cantRegistro , solo tomara la cantidad de registros cuando nroBoleta este con los valores "0", "" o null El limite máximo para consulta de registro es de 50. ``` ###  ``` Body 1 2 3 4 5 6 7 8 9 ``` #### 10 #### 11 #### { ``` "listado":[ { "nroTarjeta":"5421********3703", "nroBoleta":"002118671406", "monto":"28", "fechaHora":"24/10/02 10:27", "transaccion":"Tarjeta" } ] } ``` ###  Una vez recibido los datos del Servicio se envía nroBoleta en Transaccion de Anulacion ### Transacción de Anulación ``` Ver Detalles ``` ``` Error Response ``` ``` Status 500: Error interno del POS Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra ``` ``` Body 1 2 3 4 5 ``` #### { ``` "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 IP:PORT/pos/anulacion ``` ``` JSON Entrada ``` ``` Donde: nroBoleta : int(2) Corresponde al número de ticket a ser anulado. ``` ``` Success Response HTTP/1.1 200 OK ``` ``` Donde: codigoAutorizacion : string(6) Es el código de autorización generado por el POS. codigoComercio : string(12) Identificador del comercio generado por el POS. mensajeDisplay : string(40) Mensaje enviado por el POS según el estado de la transacción. montoVuelto : integer(12) Monto del vuelto ingresado en el POS. nombreCliente : string(26) Nombre de la persona registrada en la tarjeta. nombreTarjeta : string(40) Identificador de la tarjeta. nroBoleta : string(12) Corresponde al número de ticket. 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. ``` ``` Error Response Status 500: Error interno del POS Status 400: Error de validación, error de transacción con el POS. Si la operación no se logra ``` ``` Body 1 2 3 ``` #### { ``` "nroBoleta":"002118671406" } ``` ``` Body 1 2 3 4 5 6 7 8 9 ``` #### 10 #### 11 #### { ``` "codigoAutorizacion": "", "codigoComercio": "", "mensajeDisplay": "APROBADA", "montoVuelto": 0, "nombreCliente": "CESAR DANIEL CASARETTO B.", "nombreTarjeta": "", "nroBoleta": "002118671406", "pan": "3703", "saldo": 28 } ``` ``` Para la transacción de anulación los siguientes atributo llegaran vacíos: "codigoAutorizacion" "codigoComercio" "nombreTarjeta" ``` ###  ### Rechazos Generales ``` Ver Detalles ``` ### Anexos ``` TABLA DE ISSUER ID's ``` #### TABLA DE BILLETERAS ``` Body 1 2 3 4 5 ``` #### { ``` "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 ``` Validaciones en SDK CajaPOS Operación Mensaje Tipo de Dato ``` ``` Longitud Rango Permitido ``` ``` Cuando el Json llega mal construido, vacío o el tipo de petición es incorrecto (diferente POST) ``` #### TODAS ERROR AL RECIBIR DATOS DE #### CAJA #### NA NA NA ``` Cuando no está presente el body del Json TODAS MENSAJE INCOMPLETO NA NA NA ``` ``` Observación: Para aplicar las validaciones se removerán los 0 o espacios a la izquierda antes de validar en rango permitido, excepto para el caso de Billetera. ``` ## TABLA DE ISSUER ID ``` Marca Tipo IssuerID ``` ``` CABAL Crédito CB ``` ``` CREDIFIELCO Crédito CC ``` ``` CARTA CLAVE Crédito CL ``` ``` PANAL Crédito CP ``` ``` DINERS CLUB Crédito DC INFONET Débito ID ``` ``` MASTERCARD Crédito MC ``` ``` MASTERCARD Débito MD ``` ``` CREDICARD Crédito PC UNICA Débito UD ``` ``` VISA Crédito VC ``` ``` VISA Débito VD ``` ``` TARJETA DEBITO Débito TD ``` ``` TARJETA CREDITO Crédito TC DEBITO EN CUENTA Débito CD ``` ``` AMERICAN EXPRESS Crédito AC ``` ``` BANCARD Crédito BC ``` ## TABLA DE BILLETERAS ``` Marca Codigo Billetera ``` ``` IssuerID ``` #### ZIMPLE ZIM ZM ``` Paraguayo Japonesa ``` #### WPJ PJ #### VISION VBV VB ``` Marca Codigo Billetera ``` ``` IssuerID ``` Personal- Itau #### BPI PI Billetera Viru #### BBF BF