NOVIEMBRE 2005

1






Gua de Funciones para

CAJA_PINPAD.DLL





NOVIEMBRE 2005
2
Gua de Funciones para CAJA_PINPAD.DLL



Constantes utilizadas


Nombre de constante Valor
OP_VENTA 01
OP_VENTA_CASH 02
OP_VENTA_CUOTAS 03
OP_ANULACIN 04
OP_CIERRE 07
OP_SERVICIOS 08
OP_INICIALIZA_TERMINAL 09
OP_SIMULACION_CUOTAS 10
OP_TEST_COMUNICACIONES 11
OP_DUPLICADO 12
OP_DETALLE_OPERACIONES 13
OP_FINANCIERA 90
OP_NO_FINANCIERA 91
RET_RUNNING 1
RET_OK 0
RET_NOK -1



Funciones

FiOpenPort Recupera la configuracin de parmetros para la aplicacin mediante
el archivo INI especificado y aplica esta configuracin para abrir el
puerto de comunicaciones. Esta funcin debe ser llamada antes de
cualquier otra.

Parmetros
ConfigFileName Ruta completa de la ubicacin y nombre del archivo INI

Retorna: RET_OK Se cargo la configuracin
RET_NOK Problema al leer la configuracin o intentar utilizarla.




FiClosePort Cierra el puerto de comunicaciones.

Parmetros
<Ninguno>
NOVIEMBRE 2005
3

Retorna: RET_OK El puerto fue cerrado.
RET_NOK Problema al cerrar el puerto de comunicaciones.


fiStartOperation Enva un mensaje al pinpad para iniciar la operacin.

Parmetros
Operation_Type Tipo de operacin a iniciar por el pinpad (OP_FINANCIERA,
OP_NO_FINANCIERA) Si la operacin requiere un monto y ya ha
sido capturado por la caja, debe enviarse como una cadena de 12
caracteres que expresa la cantidad en centavos y con relleno de
ceros a la izquierda, antecedido por el separador A. Por ejemplo
una operacin financiera por s/.500.00, tendra el siguiente
parmetro:

OP_FINANCIERA + A + 000000050000 = 90A000000050000

Si se trata de una operacin que an no se conoce el monto (el
pinpad lo solicitar) o no lo requiere (como es el caso de una prueba
de comunicaciones o reimpresin), entonces solo es necesario
indicar la operacin a efectuar.

Time_Out Tiempo de espera en segundos para retornar. Se recomiendan
tiempos pequeos (1 o 2 segundos, por ejemplo) para que la caja
pueda monitorear el estatus de la operacin y sea posible efectuar
otras tareas.
Buffer_Ret Bfer de retorno (llenado por el DLL) en caso de finalizar la
operacin o cancelar la operacin por alguna causa (Ver anexo de
formato de mensajes de retorno).

Retorna: RET_OK

RET_RUNNING
La operacin ha iniciado y se requiere monitorear el status.

Cualquier otro valor retornado indica que se produjo algn error cuya
descripcin es recuperada en el bfer de retorno.




NOVIEMBRE 2005
4

FiGetStatus Obtiene el ltimo status del proceso iniciado en el pinpad pudiendo
recuperar mensajes a ser enviados a la impresora o procesados por
la caja.
Esta funcin debe ser llamada en un Loop hasta que se recupere un
mensaje destinado a la caja con multicampos (Ver anexo), que es el
ultimo mensaje enviado por el pinpad al finalizar o cancelar una
operacin.
Parmetros
Buffer_Ret Bfer de retorno (llenado por el DLL) en caso de finalizar la
operacin o cancelar la operacin por alguna causa (Ver anexo de
formato de mensajes de retorno).
Max_Size_Buffer Tamao mximo de bytes a recuperar en el bfer de retorno (se
recomienda 512).

Retorna: Un valor positivo (que indica los bytes recuperados) si hay datos vlidos.
Un valor = 0 indica que no se han recuperado datos
Un valor negativo indica que se produjo un error.

NOVIEMBRE 2005
5
Anexo 1.- Formato de mensajes recuperados en el bfer de retorno.

X L L L D U D a t o s X X
1 2 3 4 5 6 N
L
o
n
g
i
t
u
d

d
e

D
A
T
O
S

+

2

D
e
s
t
i
n
o

d
e
l

m
e
n
s
a
j
e

I
n
d
i
c
a
d
o
r

l
t
i
m
o

m
e
n
s
a
j
e



El bfer que es llenado por el DLL es una cadena en donde el byte D en la posicin 5
(siendo 1 el primero de la izquierda) indica el destino del mensaje:
I : Cadena de texto para enviar a la impresora.
C: Mensaje a ser procesado/desplegado por la caja.

En el caso de mensajes destinados a la caja con varios campos, estos campos son
recuperados en una lista con un identificador (A, B, C, ...) que antecede a cada
campo y un carcter FS (0x1C) al final del campo. Los campos que pueden ser
recuperados (*) son:
Identificador de
campo
Contenido del campo
A Cdigo de respuesta del host (campo 39 de ISO8583)
B Mensaje a desplegar en la pantalla de la caja
C Nombre del cliente
D Nmero de aprobacin devuelto por el host.
E Nmero de referencia.
F PAN de la tarjeta
G Fecha de expiracin (MM/AA)
H Fecha de la transaccin (DD/MM/AA)
I Hora de la transaccin (HH:MM)
J Cdigo de operacin efectuada:
01 Venta
02 Venta con cashback
03 Venta Cuotas
04 Anulacin
06 Captura propina
08 POS Servicios
K Indica corte de papel (1) al finalizar una impresin.
L Monto de cashback (solo en operaciones con Cashback)
(*) Pueden cambiar de acuerdo a especificaciones de software.

El valor del byte en la posicin 6 para un mensaje dirigido a la impresora no debe ser
considerado por la aplicacin que utiliza el DLL.

La X representa un byte cuyo valor es irrelevante para procesar el mensaje.

NOVIEMBRE 2005
6

Ejemplo 1: Mensaje que contiene una lnea a ser enviada a impresora.

X020I1MENSAJE A IMPRIMIRXX

La cadena MENSAJE A IMPRIMIR es de 18 caracteres, la longitud (posiciones 2,
3 y 4) indican 2 bytes adicionales (20) que corresponden la los bytes de las
posiciones 5 y 6. Una vez que la aplicacin extraiga la cadena en rojo, esta debe
ser enviada a la impresora en este caso.


Ejemplo 2: Mensaje que contiene algunos campos devueltos para la caja:

X024C0A00<FS>BFIN DE OPERACION<FS>J01<FS>XX

La cadena de datos va dirigida a la caja y contiene los campos: A (Codigo de
respuesta = 00), B que es el mensaje a desplegar por la caja (FIN DE
OPERACION) y J indica el tipo de operacin efectuada (01=Venta).




NOVIEMBRE 2005
7


Anexo 2.- Parmetros recuperados del archivo DLL3500 para inicializar.


Nombre del parmetro Valores posibles
COM 1 : Utiliza COM1
2 : Utiliza COM2
...
SET Configuracin del puerto serial:
19200,n,8,1
HOST Direccin IP del host autorizador, por ejemplo:
200.48.12.10
PORT Puerto del host para establecer la conexin, por
ejemplo:
2016

Hay otros parmetros en el archivo DLL3500.INI que se recomienda no modificarlos.

NOVIEMBRE 2005
8
Anexo 3.- Definiciones de constantes y funciones para utilizar el DLL en una aplicacin
(para el caso de VB, para otros lenguajes de programacin se deber trasladar estas
definiciones a lo requerido).


DLL3500.BAS


Public Const OP_VENTA = "01"
Public Const OP_VENTA_CUOTAS = "03"
Public Const OP_ANULACION = "04"
Public Const OP_CIERRE = "07"
Public Const OP_SERVICIOS = "08"
Public Const OP_INICIALIZA_TERMINAL = "09"
Public Const OP_SIMULACION_CUOTAS = "10"
Public Const OP_TEST_COMUNICACIONES = "11"
Public Const OP_DUPLICADO = "12"
Public Const OP_DETALLE_OPERACIONES = "13"
Public Const OP_FINANCIERA = "90"
Public Const OP_NO_FINANCIERA = "91"



Public Const RET_RUNNING = 1
Public Const RET_OK = 0
Public Const RET_NOK = -1
Public Const ERR_COM = -2
Public Const ERR_PPAD_NO_RESP = -3
Public Const ERR_TYPE_OPER = -4
Public Const ERR_SOCKET = -5
Public Const ERR_HOST_NO_RESP = -6
Public Const ERR_PRINTER = -7
Public Const ERR_NAK_RECEIVED = -8
Public Const ERR_LRC_PPAD = -9

Declare Function fiOpenPort Lib "caja_pinpad.dll" (ConfigFileName As String) As Integer

Declare Function fiClosePort Lib "caja_pinpad.dll" () As Integer

Declare Function fiStartOperation Lib "caja_pinpad.dll" _
(pucTipoOperation As String, iTimeOut As Integer, ByRef pucResponse As String) As
Integer

Declare Function fiGetStatus Lib "caja_pinpad.dll" (ByRef sBuffer As String, ByVal
SizeBuffer As Integer) As Integer