API Referencia
undefined

POS Integrado

Cómo empezar

Primero, debes instalar en tu máquina la librería/SDK en C, puedes encontrar el código fuente en GitHub y seguir las instrucciones.

También puede probar las DLLs que se adjuntan en el último release

Esta librería y sus dependencias son requisitos para utilizar el SDK.

Por el momento, el SDK está disponible para .Net y lo puedes encontrar en NuGet.org para instalarlo puedes utilizar por ejemplo el package manager de VisualStudio.

PM> Install-Package TransbankPosSDK

Recuerda que necesitas tener instalados los drivers correspondientes a tu tarjeta de puerto serial o adaptador USB Serial.

LibSerialPort

El SDK depende de libSerialPort para la comunicación serial.

Incluimos una DLL compilada en el release de la librería en C, pero puedes obtener el código desde el repositorio oficial usando git:

git clone git://sigrok.org/libserialport

Para compilar en windows necesitarás lo siguiente:

  • msys2 - mingw-w64 Puedes descargarlo siguiendo el link y las instrucciones provistas en su sitio web.
    • Adicionalmente, necesitarás el toolchain para tu arquitectura:
      • x86: pacman -S mingw-w64-i686-toolchain
      • x64: pacman -S mingw-w64-x86_64-toolchain

Primeros pasos

Para usar el SDK es necesario incluir las siguientes referencias.

using Transbank.POS;
using Transbank.POS.Utils;
using Transbank.POS.Responses:
#include "transbank.h"
#include "transbank_serial_utils.h"

Listar puertos disponibles

Si los respectivos drivers están instalados, entonces puedes usar la función ListPorts() del paquete Transbank.POS.Utilspara identificar los puertos que se encuentren disponibles y seleccionar el que corresponda con el puerto donde conectaste el POS Integrado.

using Transbank.POS.Utils;
//...
List<string> ports = Serial.ListPorts();
#include "transbank_serial_utils.h"
//...
char *ports = list_ports();

Abrir un puerto Serial

Para abrir un puerto serial y comunicarte con el POS Integrado, necesitarás el nombre del puerto (El cual puedes identificar usando la función mencionada en el apartado anterior). También necesitarás el baudrate al cual esta configurado el puerto serial del POS Integrado (Por defecto es 115200), y puedes obtener los distintos valores desde la clase TbkBaudrates del paquete Transbank.POS.Utils.

Si el puerto no puede ser abierto, se lanzará una exception TransbankException.

using Transbank.POS;
using Transbank.POS.Utils;
//...
string portName = "COM3";
POS.Instance.OpenPort(portName);
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
char *portName = "COM4";
int retval = open_port(portName, 115200);
if ( retval == TBK_OK ){
    //...
}

Cerrar un puerto Serial

Al finalizar el uso del POS, o si se desea desconectar de la Caja se debe liberar el puerto serial abierto anteriormente.

using Transbank.POS;
//...
bool closed = POS.Instance.ClosePort();
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
retval = close_port();
if(retval == SP_OK){
    //...
}

Transacción de Venta

Este comando es enviado por la caja para solicitar la ejecución de una venta. Los siguientes parámetros deben ser enviados desde la caja:

  • Monto: Monto en pesos informados al POS. Este parámetro es remitido a Transbank para realizar la autorización.
  • Número Ticket/Boleta: Este número es impreso por el POS en el voucher que se genera luego de la venta.
using Transbank.POS;
using Transbank.POS.Responses;
//...
SaleResponse response = POS.Instance.Sale(ammount, ticket);
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
char* response = sale(ammount, ticket, false);

El resultado de la venta se entrega en la forma de un objeto SaleResponse o un char* en el caso de la librería C. Si ocurre algún error al ejecutar la acción en el POS se lanzará una excepción del tipo TransbankSaleException.

"Function": 210
"Response": "Aprobado"
"Commerce Code": 550062700310
"Terminal Id": "ABC1234C"
"Ticket": "AB123"
"Autorization Code": "XZ123456"
"Ammount": 15000
"Shares Number": 3
"Shares Amount": 5000
"Last 4 Digits": 6677
"Operation Number": 60
"Card Type": CR
"Accounting Date":
"Account Number":
"Card Brand": AX
"Real Date": 28/10/2019 22:35:12
"Employee Id":
"Tip": 1500

Transacción de Última Venta

Este comando es enviado por la caja, solicitando al POS la re-impresión de la última venta realizada.

Si el POS recibe el comando de Última Venta y no existen transacciones en memoria del POS, se envía la respuesta a la caja indicando el código de respuesta 11. (Ver tabla de respuestas)

using Transbank.POS;
using Transbank.POS.Responses;
//...
LastSaleResponse response = POS.Instance.LastSale();
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
char *lastSaleResponse = last_sale();
}

El resultado de la transacción última venta devuelve los mismos datos que una venta normal y se entrega en forma de un objeto LastSaleResponse o un char* en el caso de la librería C. Si ocurre algún error al ejecutar la acción en el POS se lanzará una excepción del tipo TransbankLastSaleException.

"Function": 260
"Response": "Aprobado"
"Commerce Code": 550062700310
"Terminal Id": "ABC1234C"
"Ticket": "AB123"
"Autorization Code": "XZ123456"
"Ammount": 15000
"Shares Number": 3
"Shares Amount": 5000
"Last 4 Digits": 6677
"Operation Number": 60
"Card Type": CR
"Accounting Date":
"Account Number":
"Card Brand": AX
"Real Date": 28/10/2019 22:35:12
"Employee Id":
"Tip": 1500

Transacción de Anulación

Esta transacción siempre será responsabilidad de la caja y es quien decide cuando realizar una anulación.

El comando de anulación soporta los siguientes parámetros que pueden ser enviados desde la caja.

using Transbank.POS;
using Transbank.POS.Responses;
//...
RefundResp response = POS.Instance.Refund(21);
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
RefundResponse response = refund(21);

Como respuesta el POS enviará un código de aprobación, acompañado de un código de autorización. En caso de rechazo el código de error está definido en la tabla de respuestas. Ver tabla de respuestas

"FunctionCode": 1210
"ResponseCode": 0
"CommerceCode": 597029414300
"TerminalId": "ABCD1234"
"AuthorizationCode": "ABCD1234"
"OperationID": 123456
"ResponseMessage": "Aprobado"
"Success": true

Transacción de Cierre

Este comando es gatillado por la caja y no recibe parámetros. El POS ejecuta la transacción de cierre contra el Autorizador (no se contempla Batch Upload). Como respuesta el POS Integrado enviará un aprobado o rechazado. (Puedes ver la tabla de respuestas en este link)

using Transbank.POS;
using Transbank.POS.Responses;
//...
CloseResponse response = POS.Instance.Close();
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
BaseResponse response = register_close();
}

El resultado del cierre de caja se entrega en la forma de un objeto CloseResponse o una estructura BaseResponse en el caso de la librería C. Si ocurre algún error al ejecutar la acción en el POS se lanzará una excepción del tipo TransbankCloseException.

"FunctionCode": 510
"ResponseMessage": "Aprobado"
"Success": true
"CommerceCode": 550062700310
"TerminalId": "ABC1234C"

Transacción Totales

Esta operación le permitirá a la caja obtener desde el POS un resumen con el monto total y la cantidad de transacciones que se han realizado hasta el minuto y que aún permanecen en la memoria del POS.

Además la caja podrá determinar si existen transacciones que no fueron informadas desde el POS, haciendo una comparación de los totales entre la caja y el POS. La impresión del Voucher con el resumen será realizada por el POS.

using Transbank.POS;
using Transbank.POS.Responses;
//...
TotalsResponse response = POS.Instance.Totals();
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
TotalsCResponse response = get_totals();
}

El resultado de la transacción entrega en la forma de un objeto TotalsResponse o una estructura TotalsCResponse en el caso de la librería C. Si ocurre algún error al ejecutar la acción en el POS se lanzará una excepción del tipo TransbankTotalsException.

"Function": 710
"Response": "Aprobado"
"TX Count": 3     // Cantidad de transacciones
"TX Total": 15000 // Suma total de los montos de cada transaccion

Transacción de Detalle de Ventas

Esta transacción solicita al POS todas las transacciones que se han realizado y permanecen en la memoria del POS. El parámetro que recibe esta función es de tipo booleano e indica si se realiza la impresión del detalle en el POS. En el caso de que no se solicite la impresión, el POS envía todas las transacciones a la caja, una por una.

using Transbank.POS;
using Transbank.POS.Responses;
//...
bool printOnPOS = false;
List<DetailResponse> Details(printOnPOS)
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
bool print_on_pos = false;
char *response = sales_detail(print_on_pos);
}

El resultado de la transacción entrega una lista de objetos DetailResponse o un char * en el caso de la librería C. Si ocurre algún error al ejecutar la acción en el POS se lanzará una excepción del tipo TransbankSalesDetailException.

[
  {
    "Function": 261,
    "Response": "Aprobado",
    "Commerce Code": 550062700310,
    "Terminal Id": "ABC1234C",
    "Ticket": "AB123",
    "Autorization Code": "XZ123456",
    "Ammount": 15000,
    "Shares Number": 3,
    "Shares Amount": 5000,
    "Last 4 Digits": 6677,
    "Operation Number": 60,
    "Card Type": CR,
    "Accounting Date": ,
    "Account Number": ,
    "Card Brand": AX,
    "Real Date": "28/10/2019 22:35:12",
    "Employee Id": ,
    "Tip": 1500,
  },
  {
    "Function": 261,
    "Response": "Aprobado",
    "Commerce Code": 550062700310,
    "Terminal Id": "ABC1234C",
    "Ticket": "AB123",
    "Autorization Code": "XZ123456",
    "Ammount": 15000,
    "Shares Number": 3,
    "Shares Amount": 5000,
    "Last 4 Digits": 6677,
    "Operation Number": 60,
    "Card Type": CR,
    "Accounting Date": ,
    "Account Number": ,
    "Card Brand": AX,
    "Real Date": "28/10/2019 22:35:12",
    "Employee Id": ,
    "Tip": 1500
  }
]

Transacción de Carga de Llaves

Esta transacción permite al POS Integrado del comercio requerir cargar nuevas Working Keys desde Transbank. Como respuesta el POS Integrado enviará un aprobado o rechazado. (Puedes ver la tabla de respuestas en este link)

using Transbank.POS;
using Transbank.POS.Responses;
//...
LoadKeysResponse response = POS.Instance.LoadKeys();
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
BaseResponse response = load_keys();
}

El resultado de la carga de llaves entrega en la forma de un objeto LoadKeysResponse o una estructura BaseResponse en el caso de la librería C. Si ocurre algún error al ejecutar la acción en el POS se lanzará una excepción del tipo TransbankLoadKeysException.

"FunctionCode": 810
"ResponseMessage": "Aprobado"
"Success": true
"CommerceCode": 550062700310
"TerminalId": "ABC1234C"

Transacción de Poll

Esta mensaje es enviado por la caja para saber si el POS está conectado. En el SDK el resultado de esta operación es un Booleano o un 0 representado en la constante TBK_OK en el caso de la librería en C. Si ocurre algún error al momento de ejecutar la acción en el POS, se lanzará una excepción del tipo TransbankException.

using Transbank.POS;
//...
bool connected = POS.Instance.Poll();
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
int retval = poll();
if (retval == TBK_OK){
    //...
}

Transacción de Cambio a POS Normal

Este comando le permitirá a la caja realizar el cambio de modalidad a través de un comando. El POS debe estar en modo integrado y al recibir el comando quedara en modo normal. El resultado de esta operación es un Booleano en el caso del SDK o un 0 representado en la constante TBK_OK en el caso de la librería en C. Si ocurre algún error al momento de ejecutar la acción en el POS, se lanzará una excepción del tipo TransbankException.

using Transbank.POS;
//...
bool connected = POS.Instance.SetNormalMode();
#include "transbank.h"
#include "transbank_serial_utils.h"
//...
int retval = set_normal_mode();
if (retval == TBK_OK){
    //...
}

Ejemplos de integración

Ponemos a tu disposición un ejemplo en nuestro Github para ayudarte a entender mejor la integración.