POS Integrado

Cómo empezar

La solución de POS integrado se comunica con la caja de tu comercio, permitiendo tener el control del cobro desde tu caja, y que el cliente pueda finalizar la operación sin mayor intervención del operador de la caja de tu comercio. Es importante que antes de comenzar tu integración el equipo se encuentre en modo integrado. Para colocar el equipo en modo integrado puedes seguir las instrucciones disponibles descritas en Cambio a POS Integrado.

Por el momento, hay un SDK para .NET, Java y Javascript (tecnologías web).

SDK .NET

Para .NET lo puedes encontrar en NuGet.org para instalarlo puedes utilizar por ejemplo el package manager de VisualStudio.

PM> Install-Package TransbankPosSDK

SDK Node.js

El SDK de Node.js está disponible en npm como transbank-pos-sdk. Puedes instalarlo usando

npm install transbank-pos-sdk

Puedes ver más documentación en el README del proyecto: https://github.com/TransbankDevelopers/transbank-pos-sdk-nodejs

SDK Java

Para el SDK Java se puede incluir el paquete por Maven. Agregando la siguiente dependencia en el archivo pom.xml

<dependency>
  <groupId>com.github.transbankdevelopers</groupId>
  <artifactId>transbank-sdk-pos-java</artifactId>
  <version>3.1.1</version>
</dependency>

SDK Web

El SDK Web consta de dos partes: SDK Javacript y Cliente Desktop.

Agente Desktop: Este agente es un programa que se debe instalar e inicializar en el computador que tendrá el equipo POS conectado físicamente. Al instalar e inicializar este servicio, se creará un servidor de websockets local en el puerto 8090 que permitirá, a través del SDK de Javascript, poder enviar y recibir mensajes del equipo POS, de manera simple y transparente.

SDK Javascript: Este SDK se debe instalar en el software de caja (o cualquier software web que presente HTML, CSS y JS en un navegador web). Este SDK entrega una interfaz simple para conectarse con el cliente desktop, de manera que se puedan mandar instrucciones al POS con un API fácil de usar directamente desde el browser.

Dentro de cada repositorio se encuentra la documentación más detallada.

Instalar el SDK en el software web donde se realizará la integración

npm install transbank-pos-sdk-web

También se puede incluir directamente el tag script

<script src="https://unpkg.com/transbank-pos-sdk-web@3/dist/pos.js"></script>

<script>
// En este caso, el objeto en vez de ser POS, es Transbank.POS
// Ej: Transbank.POS.connect(...); en vez de POS.connect(...) como se especifica en los ejemplos de mas abajo.
</script>

Instalar el agente desktop

Revisa la lista de versiones publicadas y descarga la última versión. Verás que hay un archivo .exe que debes bajar si usas windows, o un archivo .zip si usas MacOS. Luego, solo debes de instalar y ejecutar el programa.

Este agente debe estar ejecutándose siempre para que el SDK Javascript funcione correctamente. Puedes ejecutarlo automáticamente cuando se inicie el computador. La primera vez que se ejecuta el agente, este se configura automáticamente para iniciar en el startup del computador.

Una vez instalado, ya puedes usar el SDK Javascript. Pruebes probar la conexión con tu POS usando el proyecto web de ejemplo

SDK Python

El SDK de Python se encuentra disponible en pypi.org, y puedes instalarlo ejecutando el siguiente comando:

pip install transbank-pos-sdk

Integración Nativa

Es recomendable utilizar un SDK disponible a la hora de desarrollar la integración, lo que ahorra tiempo y te despreocupa de desarrollar las comunicaciones con el equipo POS Integrado, facilitando bastante la integración, pero en el caso que prefieras realizar la integración por tu cuenta y utilizar los comandos nativos, puedes revisarlos en la Referencia.

Drivers

Actualmente contamos con 2 equipos POS Integrado en circulación.

Verifone VX520 y VX520C

Estos equipos funcionan tanto con puerto serial RS232 y USB (Generalmente plug and play), para el cual puedes necesitar instalar un driver de verifone.

Este driver es compatible con los siguientes sistemas operativos informados por Verifone:

Windows 10 de 32/64 bits
Windows 8/8.1 de 32/64 bits
Windows 7 de 32/64 bits

Por normas PCI los comercios no deben utilizar un Sistema Operativo bajo obsolescencia, además es muy importante mantener su Sistema Operativo con los últimos parches instalado, esto principalmente por un tema de seguridad.

Ingenico Desk 3500

Estos equipos funcionan tanto con puerto serial RS232 y USB (Generalmente plug and play), para el cual puedes necesitar instalar un driver de Ingenico.

Este driver es compatible con los siguientes sistemas operativos:

Windows 10 de 32/64 bits
Windows Server 2016
Windows Server 2012
Windows 8/8.1 de 32/64 bits
Windows 7 de 32/64 bits

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

LibSerialPort

Algunos SDK dependen 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

Prueba tu POS

Probando con el agente web

Una de las maneras más simple de hacer una prueba de conexión con tu POS es usar el SDK Web.

Descarga e instala el agente POS
Entra a pos.continuumhq.dev donde verás el proyecto de ejemplo del SDK Web ya montado y funcionando.
Prueba la conexión, y las diferentes operaciones.

Probando directamente desde tu navegador

Otra forma de probar tu POS, es con el proyecto de ejemplo de la librería javascript que utiliza la API serial del navegador.

Ingresa a pos-serial.continuumhq.dev y verifica que tu navegador se encuentre soportado.
Configura la velocidad y dale al botón de conectar.
Prueba las diferentes operaciones.

Nota: No olvides colocar tu POS en modo POS integrado.

Proyectos de ejemplo

Para cada SDK se creó un proyecto de ejemplo:

Primeros pasos

Para usar el SDK es necesario incluir las siguientes referencias.

  from transbank import POSIntegrado

using Transbank.POSIntegrado;
using Transbank.Responses.CommonResponses;
using Transbank.Responses.IntegradoResponse;

#include "transbank.h"
#include "transbank_serial_utils.h"

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.exceptions.common.*;
import cl.transbank.pos.exceptions.integrado.*;
import cl.transbank.pos.responses.common.*;
import cl.transbank.pos.responses.integrado.*;

import POS from "transbank-pos-sdk"; // Si se instala por NPM

import POS from "transbank-pos-sdk-web"; // Si se instala por NPM

Si decides insertar directamente el script en el HTML

javascript
<script src="https://unpkg.com/transbank-pos-sdk-web@3/dist/pos.js"></script>

En el caso de incrustar el script, recordar que el objeto se llama Transbank.POS y NO POS como se menciona en los siguientes ejemplos.

Para el caso de SDK de Js, considera en los siguiente ejemplos que debes primero conectarte con el agente web mediante el comando POS.connect() antes de proder enviar comandos al POS.

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.POSIntegrado;
//...
List<string> ports = POSIntegrado.Instance.ListPorts();

from transbank import POSIntegrado

POS = POSIntegrado()
ports = POS.list_ports()
print(ports)

#include "transbank_serial_utils.h"
//...
char *ports = list_ports();

import cl.transbank.pos.POSIntegrado;
//...
POSIntegrado pos = new POSIntegrado();
List<String> ports = pos.listPorts();

import POS from "transbank-pos-sdk";
POS.listPorts().then((ports) => {
    console.log('ports');
}).catch(() => {
    console.log('Ocurrió un error inesperado', err);
})

import POS from "transbank-pos-sdk-web";
pos.getPorts().then( (ports) => {
    console.log(ports);
}).catch( (err) => {
    alert("No se pudo obtener puertos. ¿Está corriendo el servicio Transbank POS?");
});

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).

Si el puerto no puede ser abierto, se lanzará una excepción TransbankException en .NET y Java.

  from transbank import POSIntegrado
    
POS = POSIntegrado()
port = "/dev/cu.usbmodem0123456789ABCD1"
print(POS.open_port(port))
# Con baudrate
print(POS.open_port(port=port, baud_rate=9600))

using Transbank.POSIntegrado;
//...
string portName = "COM3";
POSIntegrado.Instance.OpenPort(portName);

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
char *portName = "COM4";
int retval = open_port(portName, 115200);
if ( retval == TBK_OK ){
    //...
}

import cl.transbank.pos.POSIntegrado;
//...

POSIntegrado pos = new POSIntegrado();
String port = "COM4";
pos.openPort(port);

let portName = '/dev/tty.usb2412412'; //Ejemplo En caso de mac
let portName = 'COM4'; //Ejempo en caso de windows
pos.connect(portName).then( (response) => {
    console.log('Conectado correctamente');
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";
POS.openPort("COM4").then((result) => {
    if (result === true) {
  alert("Conectado satisfactoriamente")
    } else {
  alert("No se pudo conectar conectado")
    }
}).catch(error => console.log(error))

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.

  from transbank import POSIntegrado

POS = POSIntegrado()
print(POS.close_port())

using Transbank.POSIntegrado;
//...
POSIntegrado.Instance.ClosePort();

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
retval = close_port();
if(retval == SP_OK){
    //...
}

import cl.transbank.pos.POSIntegrado;
//...

POSIntegrado pos = new POSIntegrado();
pos.closePort();

pos.disconnect().then( (response) => {
    console.log('Puerto desconectado correctamente');
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";
POS.closePort();

Transacciones

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.
Enviar Status: (Opcional) Indica si se envían los mensajes intermedios (verdadero) o se omiten (falso, por defecto)

En el caso de C#, los mensajes intermedios se reciben mediante el evento IntermediateResponseChange y el argumento retornado es de tipo IntermediateResponse.

Si usas mensajes intermedios en Javascript, entonces puedes pasar un callback como tercer parámetro.

  from transbank import POSIntegrado
    
POS = POSIntegrado()
# Venta con mensajes intermedios
def intermediate_message_callback(response):
  print("Intermediate message: {}".format(str(response['response_message'])))

print(POS.sale(25000, "abcd12", True, callback=intermediate_message_callback))

# Venta sin mensajes intermedios
print(POS.sale(25000, "123456"))

using Transbank.POSIntegrado;
using Transbank.Responses.CommonResponses;
using Transbank.Responses.IntegradoResponse;
//...

POSIntegrado.Instance.IntermediateResponseChange += NewIntermediateMessageReceived; //EventHandler para los mensajes intermedios.
Task<SaleResponse> response = POSIntegrado.Instance.Sale(amount, ticket, true);

//...
//Manejador de mensajes intermedios...
private static void NewIntermediateMessageReceived(object sender, IntermediateResponse e){
  //...
}
//...

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
char* response = sale(amount, ticket, false);

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.integrado.*;
//...

POSIntegrado pos = new POSIntegrado();
SaleResponse response = pos.sale(amount, ticket, true);

pos.setOnIntermediateMessageReceivedListener(this::onIntermediateMessageReceived);

//...
//Manejador de mensajes intermedios...
private void onIntermediateMessageReceived(IntermediateResponse response) {
  //...
}
//...

// Venta simple sin estados intermedios
pos.sale(1500, '12423').then( (response) => {
    console.log('sale finalizado. Respuesta: ', response);
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

// Venta con estados intermedios
let callback = function (data) {
    console.log('Mensaje intermedio recibido:  ', data)
}
pos.sale(1500, '12423', true, callback)
    .then( (response) => {
        console.log('sale finalizado. Respuesta: ', response);
    }).catch( (err) => {
        console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";

POS.doSale(this.total, "ticket1", (data) => {
//Este tercer parámetro es opcional. Si está presente, se ejecutará cada vez que llegue un mensaje de status de la venta.
console.log('Mensaje de status recibido', data);
}).then((saleResponse) => {
    console.log(saleResponse);
    //Acá llega la respuesta de la venta. Si saleDetails.responseCode es 0, entonces la compra fue aprobada
    if (saleResponse.responseCode===0) {
  alert("Transacción aprobada", "", "success");
    } else {
  alert("Transacción rechazada o fallida")
    }
});

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 en .NET y en Java.

El objeto SaleResponse retornará un objeto con los siguientes datos.

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

Transacción de Venta Multicódigo

Este comando es enviado por la caja para solicitar la ejecución de una venta multicódigo. 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.
Código De Comercio: Código de comercio que realiza la venta. (No es el mismo código del POS, ya que en multicódigo el código padre no puede realizar ventas.)
Enviar Status: (Opcional) Indica si se envían los mensajes intermedios (verdadero) o se omiten (falso, por defecto)

En el caso de C#, los mensajes intermedios se reciben mediante el evento IntermediateResponseChange y el argumento retornado es de tipo IntermediateResponse

Si usas mensajes intermedios en Javascript, entonces puedes pasar un callback como tercer parámetro.

  from transbank import POSIntegrado
    
POS = POSIntegrado()
# Venta con mensajes intermedios
def intermediate_message_callback(response):
  print("Intermediate message: {}".format(str(response['response_message'])))
       
print(POS.multicode_sale(1200, "Tic123", 597029414301, send_status=True, callback=intermediate_message_callback))
     
# Venta sin mensajes intermedios
print(POS.multicode_sale(1200, "Tic123", 597029414301))

using Transbank.POSIntegrado;
using Transbank.Responses.CommonResponses;
using Transbank.Responses.IntegradoResponse;
//...

POSIntegrado.Instance.IntermediateResponseChange += NewIntermediateMessageReceived; //EventHandler para los mensajes intermedios.
Task<MultiCodeSaleResponse> response = POSIntegrado.Instance.MultiCodeSale(amount, ticket, commerceCode, true);

//...
//Manejador de mensajes intermedios...
private static void NewIntermediateMessageReceived(object sender, IntermediateResponse e){
  //...
}
//...

// No Soportado

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.integrado.*;
//...

POSIntegrado pos = new POSIntegrado();
MultiCodeSaleResponse response = pos.multiCodeSale(amount, ticket, commerceCode, true);

pos.setOnIntermediateMessageReceivedListener(this::onIntermediateMessageReceived);

//...
//Manejador de mensajes intermedios...
private void onIntermediateMessageReceived(IntermediateResponse response) {
  //...
}
//...

import POS from "transbank-pos-sdk-web";

POS.doMulticodeSale(this.total, "ticket2", "597029414301", (data) => {
//Este tercer parámetro es opcional. Si está presente, se ejecutará cada vez que llegue un mensaje de status de la venta.
console.log('Mensaje de status recibido', data);
}).then((saleResponse) => {
    console.log(saleResponse);
    //Acá llega la respuesta de la venta. Si saleDetails.responseCode es 0, entonces la compra fue aprobada
    if (saleResponse.responseCode===0) {
  alert("Transacción aprobada", "", "success");
    } else {
  alert("Transacción rechazada o fallida")
    }
});

El resultado de la venta se entrega en la forma de un objeto MultiCodeSaleResponse 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 TransbankMultiCodeSaleException en .NET. y en Java.

El objeto MultiCodeSaleResponse retornará un objeto con los siguientes datos.

{

  "Function": 210,
  "Response": "Aprobado",
  "Commerce Code": 550062700310,
  "Terminal Id": "ABC1234C",
  "Ticket": "ABC123",
  "Authorization Code": "XZ123456",
  "Amount": 15000,
  "Shares Number": 3,
  "Shares Amount": 5000,
  "Last 4 Digits": 6677,
  "Operation Number": 60,
  "Card Type": "CR",
  "Accounting Date":"28/10/2019 22:35:12",
  "Account Number":"300000000",
  "Card Brand": "AX",
  "Real Date": "28/10/2019 22:35:12",
  "Employee Id":1,
  "Tip": 1500,
  "Change": 150,
  "CommerceProviderCode:": 550062712310
}

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)

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.last_sale())

using Transbank.POSIntegrado;
using Transbank.Responses.IntegradoResponse;
//...
Task<LastSaleResponse> response = POSIntegrado.Instance.LastSale();

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
char *lastSaleResponse = last_sale();
}

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.integrado.*;
//...

POSIntegrado pos = new POSIntegrado();
LastSaleResponse lastSaleResponse = pos.lastSale();

pos.getLastSale().then( (response) => {
    console.log('getLastSale ejecutado. Respuesta: ', response);
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";

POS.getLastSale().then((response) => {
    console.log(response)
}).catch(() => {
    alert('Error al obtener última venta');
})

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 en .NET y en Java.

{

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

Transacción de última venta multicódigo

Este comando es enviado por la caja, solicitando al POS la re-impresión de la última venta realizada, y además permite recepcionar el voucher como parte de la respuesta del pos.

Enviar Voucher: Indica si se envía un voucher formateado en la respuesta del POS (verdadero) o si se debe omitir (false).

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)

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.multicode_last_sale(True))

using Transbank.POSIntegrado;
using Transbank.Responses.IntegradoResponse;
//...
Task<MultiCodeLastSaleResponse> response = POSIntegrado.Instance.MultiCodeLastSale(true); //bool indica si pos envía o no el voucher como parte de la respuesta

// No Soportado

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.integrado.*;
//...

POSIntegrado pos = new POSIntegrado();
MultiCodeLastSaleResponse response = pos.multiCodeLastSale(true); 
//bool indica si pos envía o no el voucher como parte de la respuesta

// No Soportado

El resultado de la transacción última venta devuelve los mismos datos que una venta normal y se entrega en forma de un objeto MultiCodeLastSaleResponse. Si ocurre algún error al ejecutar la acción en el POS se lanzará una excepción del tipo TransbankMultiCodeLastSaleException.

{

  "Function": 260,
  "Response": "Aprobado",
  "Commerce Code": 550062700310,
  "Terminal Id": "ABC1234C",
  "Ticket": "ABC086",
  "Authorization Code": "XZ123456",
  "Amount": 15000,
  "Shares Number": 3,
  "Shares Amount": 5000,
  "Last 4 Digits": 6677,
  "Operation Number": 60,
  "Card Type": "CR",
  "Accounting Date": "28/10/2019 22:35:12",
  "Account Number": "300000000000",
  "Card Brand": "AX",
  "Real Date": "28/10/2019 22:35:12",
  "Employee Id": 1,
  "Tip": 1500,
  "Voucher": "VOUCHER COMPLETO EN STRING",
  "Change": 20000,
  "CommerceProviderCode": 550062712310
}

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.

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.refund(83))

using Transbank.POSIntegrado;
using Transbank.Responses.CommonResponses;

//...
Task<RefundResponse> response = POSIntegrado.Instance.Refund(21);

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
char *refundResponse = refund(21);

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.common.*;
//...

POSIntegrado pos = new POSIntegrado();
RefundResponse response = pos.refund(21);

pos.refund('102').then( (response) => {
    console.log('refund ejecutado. Respuesta: ', response);
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";

POS.refund(21).then(response => console.log(response));

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)

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.close())

using Transbank.POSIntegrado;
using Transbank.Responses.IntegradoResponse;
//...
Task<CloseResponse> response = POSIntegrado.Instance.Close();

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
BaseResponse response = register_close();
}

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.integrado.*;
//...

POSIntegrado pos = new POSIntegrado();
CloseResponse response = pos.close()

pos.closeDay().then( (response) => {
    console.log('closeDay ejecutado. Respuesta: ', response);
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";

POS.closeDay()

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.

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.totals())

using Transbank.POSIntegrado;
using Transbank.Responses.IntegradoResponse;
//...
Task<TotalsResponse> response = POSIntegrado.Instance.Totals();

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
TotalsCResponse response = get_totals();
}

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.integrado.*;
//...

POSIntegrado pos = new POSIntegrado();
TotalsResponse response = pos.totals();

pos.getTotals().then( (response) => {
    console.log('getTotals ejecutado. Respuesta: ', response);
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";

POS.getTotals().then(response => console.log(response));

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 transacción
}

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. Si se realiza la impresión, la caja recibirá una lista vacía de transacciones.

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.details(False))

using Transbank.POSIntegrado;
using Transbank.Responses.IntegradoResponse;
//...
bool printOnPOS = false;
Task<List<DetailResponse>> details = POSIntegrado.Instance.Details(printOnPOS)

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
bool print_on_pos = false;
char *response = sales_detail(print_on_pos);
}

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.integrado.*;
//...

POSIntegrado pos = new POSIntegrado();
boolean printOnPOS = false;
List<DetailResponse> response = pos.details(printOnPOS);

pos.salesDetail().then( (response) => {
    console.log('salesDetail ejecutado. Respuesta: ', response);
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";

let printOnPOS = false;
POS.getDetails(printOnPOS).then(response => console.log(response));

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",
    "Authorization Code": "XZ123456",
    "Amount": 15000,
    "Last 4 Digits": 6677,
    "Operation Number": 60,
    "Card Type": "CR",
    "Accounting Date": "28/10/2019 22:35:12",
    "Account Number": "30000000",
    "Card Brand": "AX",
    "Real Date": "28/10/2019 22:35:12",
    "Employee Id": ,
    "Tip": 1500,
    "Shares Amount": 5000,
    "Shares Number": 3,
  },
  {
    "Function": 261,
    "Response": "Aprobado",
    "Commerce Code": 550062700310,
    "Terminal Id": "ABC1234C",
    "Ticket": "AB123",
    "Authorization Code": "XZ123456",
    "Amount": 15000,
    "Last 4 Digits": 6677,
    "Operation Number": 60,
    "Card Type": "CR",
    "Accounting Date": "28/10/2019 22:35:12",
    "Account Number": "30000000",
    "Card Brand": "AX",
    "Real Date": "28/10/2019 22:35:12",
    "Employee Id": ,
    "Tip": 1500,
    "Shares Amount": 5000,
    "Shares Number": 3,
  }
]

Transacción de Detalle de Ventas Multicódigo

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.multicode_details(False))

using Transbank.POSIntegrado;
using Transbank.Responses.IntegradoResponse;
//...
bool printOnPOS = false;
Task<List<MultiCodeDetailResponse>> details = POSIntegrado.Instance.MultiCodeDetails(printOnPOS)

// No Soportado

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.integrado.*;
//...

POSIntegrado pos = new POSIntegrado();
boolean printOnPOS = false;
List<MultiCodeDetailResponse> response = pos.multiCodeDetails(printOnPOS);

// No Soportado

El resultado de la transacción entrega una lista de objetos MultiCodeDetailResponse. Si ocurre algún error al ejecutar la acción en el POS se lanzará una excepción del tipo TransbankMultiCodeDetailException.

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

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)

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.load_keys())

using Transbank.POSIntegrado;
using Transbank.Responses.CommonResponses;
//...
Task<LoadKeysResponse> response = POSIntegrado.Instance.LoadKeys();

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
BaseResponse response = load_keys();
}

import cl.transbank.pos.POSIntegrado;
import cl.transbank.pos.responses.common.*;
//...

POSIntegrado pos = new POSIntegrado();
LoadKeysResponse response = pos.loadKeys();

pos.loadKeys().then( (response) => {
    console.log('loadKeys ejecutado. Respuesta: ', response);
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";

let printOnPOS = false;
POS.loadKeys();

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 en .NET y en Java.

{
  "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.

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.poll())

using Transbank.POSIntegrado;
//...
Task<bool> connected = POSIntegrado.Instance.Poll();

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
int retval = poll();
if (retval == TBK_OK){
    //...
}

import cl.transbank.pos.POSIntegrado;
//...

POSIntegrado pos = new POSIntegrado();
boolean pollResult = pos.poll();

import POS from "transbank-pos-sdk-web";

let printOnPOS = false;
POS.poll().then(result => console.log(result));

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.

  from transbank import POSIntegrado
    
POS = POSIntegrado()
print(POS.set_normal_mode())

using Transbank.POSIntegrado;
//...
Task<bool> isInNormalMode = POSIntegrado.Instance.SetNormalMode();

#include "transbank.h"
#include "transbank_serial_utils.h"
//...
int retval = set_normal_mode();
if (retval == TBK_OK){
    //...
}

import cl.transbank.pos.POSIntegrado;
//...

POSIntegrado pos = new POSIntegrado();
boolean isInNormalMode = pos.setNormalMode();

pos.changeToNormalMode().then( (response) => {
    console.log('changeToNormalMode ejecutado. Respuesta: ', response);
}).catch( (err) => {
    console.log('Ocurrió un error inesperado', err);
});

import POS from "transbank-pos-sdk-web";

let printOnPOS = false;
POS.setNormalMode().then(result => console.log(result));

Operación y Configuración del POS

Cambio Modalidad POS Integrado

Primero debes ingresar al menú Comercio en el POS, seleccionando la opción correspondiente en la pantalla del POS e ingresar la Clave Supervisora confirmando con la tecla Enter (verde).
Luego debes seleccionar la opción POS Integrado desde la pantalla 2-2. Para ingresar a la pantalla 2 debes apretar la tecla Enter.
Ingresa nuevamente la Clave Supervisora confirmando con la tecla Enter.
Finalmente, debes seleccionar la opción Conectar Caja. El equipo indicará que se está activando el modo integrado.

Cambio Modalidad POS Normal

Si el POS se encuentra en modo Integrado, podrás ver una imagen de Transbank en la pantalla. Para volver al modo Normal de forma manual debes realizar lo siguiente:

Presionar la tecla Asterisco (*) e ingresar la clave supervisora.
Seleccionar la opción Desconectar Caja.
Luego de esto el equipo volverá a modo Normal, y verás el menú de venta nuevamente.

Cambio de dirección IP

El POS Integrado puede ser configurado con DHCP y dirección IP fija, para configurar la dirección IP se deben seguir los siguientes pasos:

Con el equipo en modo normal, se debe ingresar a la opción Técnico desde la pantalla 2-2. Para ingresar a la pantalla 2 debes apretar la tecla Enter (verde).
Luego debes seleccionar la opción Func. Instalación e ingresar el RUT y la clave de técnico correspondiente.
Seleccionar la opción Mod Param Conexión.
Seleccionar la opción Ethernet.
En el menú Ethernet seleccionar la opción Conf IP Comercio.
Seleccionar IP Fija e ingresar la configuración de red (IP, Máscara de red y Puerta de enlace).

Configuración de comunicación POS - Caja

Para permitir la recepción de comandos desde la caja, es necesario que la configuración interna de comunicación del POS coincida con la configuración con la que estás intentando conectarte. Es importante destacar que, para llevar a cabo los siguientes pasos, es necesario que el POS esté en modo normal.

Si deseas cambiar el tipo de comunicación de tu POS, ya sea de serial a USB o viceversa, sigue estas instrucciones:

Ingresar al menú de comercio desde la pantalla principal, presionando el número 3
Desde el menú comercio, acceder al menú 2/2 con la tecla Enter (verde).
Ingresar al menú POS INTEGRADO con el número 2.
Desde ese menú se pueden gestionar las opciones de comunicación. Ingresaremos a SETEO DE COM.
Indicar el tipo de comunicación que vamos a utilizar, USB o SERIAL.

Como habrás notado, siguiendo estos mismos pasos también es posible configurar la velocidad de comunicación del POS desde el menú de POS INTEGRADO.

POS Integrado

Cómo empezar

SDK .NET

SDK Node.js

SDK Java

SDK Web

SDK Python

Integración Nativa

Drivers

LibSerialPort

Prueba tu POS

Probando con el agente web

Probando directamente desde tu navegador

Proyectos de ejemplo

Primeros pasos

Listar puertos disponibles

Abrir un puerto Serial

Cerrar un puerto Serial

Transacciones

Transacción de Venta

Transacción de Venta Multicódigo

Transacción de última venta

Transacción de última venta multicódigo

Transacción de Anulación

Transacción de Cierre

Transacción Totales

Transacción de Detalle de Ventas

Transacción de Detalle de Ventas Multicódigo

Transacción de Carga de Llaves

Transacción de Poll

Transacción de Cambio a POS Normal

Operación y Configuración del POS

Cambio Modalidad POS Integrado

Cambio Modalidad POS Normal

Cambio de dirección IP

Configuración de comunicación POS - Caja

¿Tienes alguna duda de integración?

Si aún tienes dudas envíanos un mensaje

Productos

Nuestros productos

Comercio

¿Necesitas alguien que te ayude a integrar?

Documentación

Comenzar a integrar

Recursos

SDK

Webpay

POS

Patpass

Plugins

Status de nuestro sistemas

Dejanos tus ideas en GitHub

Comunidad y soporte Slack

Tutoriales de integración

Referencia API

Consulta toda la información de nuestra APIs

Status de nuestro sistemas

Dejanos tus ideas en GitHub

Comunidad y soporte Slack

Tutoriales de integración

Ayuda y Soporte

Status de nuestro sistemas

Dejanos tus ideas en GitHub

Comunidad y soporte Slack

Tutoriales de integración

POS Integrado

Cómo empezar

SDK .NET

SDK Node.js

SDK Java

SDK Web

SDK Python

Integración Nativa

Drivers

LibSerialPort

Prueba tu POS

Probando con el agente web

Probando directamente desde tu navegador

Proyectos de ejemplo

Primeros pasos

Listar puertos disponibles

Abrir un puerto Serial

Cerrar un puerto Serial

Transacciones

Transacción de Venta

Transacción de Venta Multicódigo

Transacción de última venta

Transacción de última venta multicódigo

Transacción de Anulación

Transacción de Cierre

Transacción Totales

Transacción de Detalle de Ventas

Transacción de Detalle de Ventas Multicódigo

Transacción de Carga de Llaves

Transacción de Poll

Transacción de Cambio a POS Normal

Operación y Configuración del POS

Cambio Modalidad POS Integrado

Cambio Modalidad POS Normal

Cambio de dirección IP

Configuración de comunicación POS - Caja

¿Tienes alguna duda de integración?

Si aún tienes dudas envíanos un mensaje