Especificação Técnica

Bibliotecas CliSiTef e CliSiTefI - Mobile

Versão 2.01

Este documento possui tecnologia e conhecimento de propriedade da Software Express Informática

Não pode ser reproduzido ou utilizado para outros fins que não a interface com algum de nossos produtos.
 Histórico das Revisões
Data Versão Descrição
07/Dez/2012 1.0 Versão inicial para transações digitadas.
14/Mai/2013 1.1 Revisão geral, adição do Ingenico iSMP, PAX D200 e problemas comuns
20/Mai/2013 1.2 Configuração do iSMP para modo serial
24/Mai/2013 1.3 Revisão dos pinpads bluetooth
27/Mai/2013 1.4 Revisão das versões de libs do IOS
29/Mai/2013 1.5 Revisão do IOS e permissões no projeto Android
25/Jun/2013 1.6 Revisão do processo de linkedição com as bibliotecas
01/Jul/2013 1.7 PAX D200 para iOS
02/Ago/2013 1.8 Suporte PinPad USB para Android.
Novo processo para geração de trace em dispositivos Android.
09/Ago/2013 1.9 Observações sobre versão mínima do SDK para conexão USB.
Melhoria no exemplo de habilitação da depuração com PinPad USB.
02/Set/2013 1.91 Biblioteca híbrida para iOS
(1.9a)
10/Out/2013 1.10 Ajustes editoriais no documento: índice, versão e numeração da seção IOS.
Removido comandos obsoletos para conexão/desconexão de pinpad.
14/Nov/2013 1.11 Incluído cláusula sobre obrigatoriedade do PinPad suportar o modo Comunicação Segura.
04/Dez/2013 1.12 Incluídas as funções que estão disponíveis para iOS e Android.
10/Jan/2014 1.13 Observações para Android (a partir da jclisitef-android.jar v1.008):
. DiretorioApp passa a ser opcional
. DiretorioTrace assume valor padrão “/sdcard”
Alterações do iOS
. Adicionado suporte ao pinpad ICMP da Ingenico
. Correção dos protótipos das funções “finaliza”
10/Mar/2014 1.14 Adição do pinpad Datecs
05/Ago/2014 1.15 Revisão do documento Android.
Inclusão da seleção do pinpad via MAC Address (Android).
31/Out/2014 1.16 Suporte para Windows Phone.
Removido textos sobre a necessidade da automação conectar/desconectar o pinpad via
API, já que estas ações foram incorporadas no fluxo normal da transação.
25/02/2015 1.17 Atualização de pinpads suportados no iOS
17/04/2015 1.18 Atualização dos pinpads suportados no Android
24/04/2015 1.19 Correções para o iOS
05/05/2015 1.20 carregaArquivosTraducao para Android
13/08/2015 1.21 iOS: libclisitef32.a passa a se chamar simplesmente libclisitef.a, por comportar também
plataformas 64 bits (item 3.2).
31/08/2015 2.00 Android: alterada a estrutura de arquivos (nomes de bibliotecas a serem incorporados no
projeto).
Modificado o texto de configuração da clisitef, que anteriormente induzia a necessidade
de chamada a cada transação.
Removido texto de validação de canal de comunicação com o pinpad. Este passo é feito
de forma transparente para a Aplicação, na transação.

10/11/2015 2.01 iOS: Filtro de pinpads por Serial

2
 Índice
1. Objetivo ........................................................................................................................................... 4
2. Cenário geral.................................................................................................................................... 5
2.1. Configuração inicial da biblioteca ............................................................................................ 5
2.2. Ciclo de Vida da Transação....................................................................................................... 5
3. Particularidades para cada plataforma ........................................................................................... 7
3.1. Android ..................................................................................................................................... 7
3.1.1. Utilização da classe br.com.softwareexpress.sitef.android.CliSiTefI ................................... 9
3.1.2. Acessando a clisitef em outras atividades (Activity) ............................................................ 9
3.1.3. Configurando a clisitef para acesso a PinPads ................................................................... 10
3.1.4. Pareamento com o PinPad Bluetooth ................................................................................ 13
3.2. IOS .......................................................................................................................................... 14
3.2.1. Ingenico iSMP/iCMP ........................................................................................................... 14
3.2.2. PAX D200 ............................................................................................................................ 14
3.2.3. Gertec Mobipin ................................................................................................................... 15
3.2.4. Datecs Bluepad ................................................................................................................... 15
3.3. Windows Phone ..................................................................................................................... 16
3.3.1. Utilização da classe CliSiTefPRC.CliSiTef ............................................................................. 16
3.3.2. Integração com PinPad Bluetooth ...................................................................................... 18
4. Funções disponíveis ....................................................................................................................... 19
4.1. Android ................................................................................................................................... 19
4.2. iOS .......................................................................................................................................... 20
4.3. Windows Phone (8 e 8.1) ....................................................................................................... 21
5. Confirmação da transação: Processo Iterativo.............................................................................. 22
6. Arquivo de configuração: CLSIT ..................................................................................................... 23
6.1. Trace ....................................................................................................................................... 23
6.2. Android ................................................................................................................................... 23
6.3. IOS .......................................................................................................................................... 24
6.4. Windows Phone ..................................................................................................................... 25
7. Problemas comuns ........................................................................................................................ 26
7.1. Problemas de comunicação com os Pinpads ............................................................................. 26

3
1. Objetivo

Este documento descreve como utilizar os portes da CliSiTef para plataformas móveis de forma a
atender as particularidades dos diferentes smartphones e dispositivos móveis. Para um completo
entendimento destes portes é pré-requisito o domínio total da interface de acesso ao SiTef via DLL descrita
no documento “SiTef - Interface Simplificada com a aplicação”.

4
2. Cenário geral
2.1. Configuração inicial da biblioteca
A Aplicação deve inicialmente configurar a CliSiTef, através da função ConfiguraIntSiTefInterativoEx(),
passando IP do SiTef, código de empresa/terminal e parâmetros adicionais (descritos posteriormente neste
documento).
Normalmente este procedimento é necessário apenas quando a aplicação sobe pela primeira vez, ou
quando os parâmetros de IP do SiTef/empresa/terminal são alterados dinamicamente.

2.2. Ciclo de Vida da Transação

O fluxo comum de uma transação fica representado pelos passos abaixo:

1. A Automação inicia a transação – a Aplicação chama a função IniciaFuncaoSiTefInterativo(),

indicando a modalidade da transação (zero para venda), valor, número do cupom fiscal, dentre
outros parâmetros. Caso retorne 10000, a Aplicação pode dar início ao Processo Iterativo a seguir.

2. Processo Iterativo – a Aplicação chama a rotina ContinuaFuncaoSiTefInterativo(). Esta rotina possui

características de entrada/saída.
Como entrada, a Aplicação passa a intenção de continuar ou não o processo iterativo, bem
como o buffer com dados coletados no passo anterior. No passo inicial, o buffer é passado zerado.
Caso a rotina retorne 10000, então pode-se analisar os parâmetros de saída: comando a ser
executado, código do campo a ser tratado, tamanho mínimo/máximo do dado solicitado, buffer
com dados adicionais para o tratamento. Estão incluídos aqui comandos para comunicação,
conforme descrito no item “Funcionamento da comunicação”.
Ainda caso a rotina retorne 10000, uma nova chamada à ContinuaFuncaoSiTefInterativo()
deve ser feita, mesmo que a Aplicação tenha manifestado não continuar no processo iterativo.
Neste caso, a CliSiTef finalizará a transação tão logo quanto possível.

3. A Automação finaliza a transação – se a última chamada da ContinuaFuncaoSiTefInterativo()

retornou zero, então a transação foi concluída. Neste caso, se foi retornado o TipoCampo 1 (Dados
de confirmação) para a Aplicação, então a mesma deve proceder à confirmação ou não-
confirmação.
Para tanto, a Aplicação deve chamar a FinalizaTransacaoSiTefInterativoEx(). De forma
análoga à IniciaFuncaoSiTefInterativo(), se a rotina retornar 10000, a Aplicação deve dar início ao
Processo Iterativo.

5
4. Processo Iterativo para confirmação/não-confirmação – valem as mesmas características descritas
no passo 5.

6
3. Particularidades para cada plataforma
3.1. Android

Observação: até a versão da clisitef 4.0.112.38 (inclusive), a plataforma Android utilizava uma outra
estrutura de arquivos e componente .jar. Para maiores informações sobre esta e outras versões anteriores,
consulte o documento “SiTef - Interface CliSiTef Mobile - v1.21.pdf”.

Mudanças a partir da versão da clisitef 4.0.112.39:

 Suporte para processadores 64 bits
 O antigo pacote jclisitef-android.jar passa a se chamar clisitef-android.jar.
 As antigas bibliotecas libjCliSiTefI.so e libclisitef32.so foram aglutinadas e passam a se chamar
simplesmente libclisitef.so
 A integração com a Aplicação foi toda mantida, não foram alterados nomes de classes ou
métodos. Deve-se apenas remover os arquivos antigos da pasta libs, substituindo pelas novas.

Para utilizar a CliSiTef em aplicações Android, é necessário incluir as seguintes bibliotecas no projeto:

1. clisitef-android.jar
2. libclisitef.so

A CliSiTef é acessada pela Automação através da componente Java, formada pelo pacote ‘clisitef-
android.jar’. Além da parte Java, existe um módulo que implementa a translação do mundo java para o
ambiente nativo do Android por meio de JNI. Este módulo é implementado pela biblioteca ‘libclisitef.so’.

Importante: caso o desenvolvedor esteja usando a IDE do Eclipse, vale ressaltar que as bibliotecas
dinâmicas .so devem ficar na pasta correspondente à arquitetura.

Até o momento, existem as seguintes plataformas da CliSiTef para Android:

1. armeabi – os arquivos .so devem ficar na pasta \libs\armeabi do projeto.

2. armeabi-v7a – os arquivos .so devem ficar na pasta \libs\armeabi-v7a do projeto.
3. arm64-v8a – os arquivos .so devem ficar na pasta \libs\arm64-v8a do projeto.
4. mips – os arquivos .so devem ficar na pasta \libs\mips do projeto.
5. mips64 – os arquivos .so devem ficar na pasta \libs\mips64 do projeto.
6. x86 – os arquivos .so devem ficar na pasta \libs\x86 do projeto.
7. x86_64 – os arquivos .so devem ficar na pasta \libs\x86_64 do projeto.

7
 Já o arquivo ‘clisitef-android.jar’, independente de plataforma, pode ser colocado na pasta \libs do
projeto.
Exemplo típico da estrutura de arquivos em um projeto Android:

\assets\CLSIT
\libs\clisitef-android.jar
\libs\armeabi\libclisitef.so
\libs\armeabi-v7a\libclisitef.so
\libs\arm64v8\libclisitef.so
\libs\mips\libclisitef.so
\libs\mips64\libclisitef.so
\libs\x86\libclisitef.so
\libs\x86_64\libclisitef.so

Foi desenvolvida uma classe especial para Android, a fim de abstrair as necessidades de acesso ao
pinpad bluetooth e usb, tornando a utilização transparente para a aplicação.

br.com.softwareexpress.sitef.android.CliSiTefI

Acompanha também java-doc do pacote, que pode ser incorporada no Eclipse de forma a facilitar a
indicação dos argumentos dos métodos durante seu desenvolvimento.
Para facilitar a integração com a aplicação, somente um sub-conjunto de métodos ficará disponível
neste primeiro momento.

8
3.1.1. Utilização da classe br.com.softwareexpress.sitef.android.CliSiTefI
Para acoplar a classe à sua aplicação, basta chamar o construtor, passando como parâmetro o
contexto da aplicação.

Para receber eventos adicionais (como mudanças de status de conexão do PinPad), atribua um
android.os.Handler apropriado.

clisitef = new CliSiTefI (this.getApplicationContext ());

clisitef.setMessageHandler (hndMessage);

A tabela abaixo ilustra a lista de eventos enviados a aplicação para interface com o PinPad. Alguns
eventos podem ou não ser devolvidos, dependendo de cada PinPad.

Código disponível na classe Descrição

EVT_INICIA_ATIVACAO_BT
EVT_FIM_ATIVACAO_BT
EVT_INICIA_AGUARDA_CONEXAO_PP
EVT_FIM_AGUARDA_CONEXAO_PP
EVT_PP_BT_CONFIGURANDO
EVT_PP_BT_CONFIGURADO
EVT_PP_BT_DESCONECTADO
EVT_INICIO_MODO_DISCOVER_BT
EVT_FIM_MODO_DISCOVER_BT
EVT_CONTINUA_CADASTRO_PIN_BT
EVT_SUCESSO_CADASTRO_PIN_BT
EVT_FALHA_CADASTRO_PIN_BT
Evento indicando que será ligado o adaptador BT do celular
Evento indicando término da etapa de ativação do adaptador BT
do celular
Evento indicando que o usuário deve ligar o pinpad bluetooth
Indica conexão de um dispositivo bluetooth
Indica início de configuração com o dispositivo recém-conectado
Indica sucesso na configuração do pinpad
Evento indicando fim de conexão com o pinpad bluetooth
Evento indicando início da operação de discover bluetooth. O
PinPad bluetooth estará apto a "enxergar" o celular para o
primeiro pareamento.
Evento indicando finalização da operação de discover bluetooth
(timeout).
Evento indicando que o usuário deve dar continuidade ao
cadastramento no pinpad.
Evento indicando sucesso no cadastro de pin
Evento indicando falha no cadastro de pin; deve-se reiniciar a
operação.

3.1.2. Acessando a clisitef em outras atividades (Activity)

Para acessar a instância da clisitef que foi criada em outra atividade, é possível utilizar o método de
classe getInstance().

CliSiTefI copia = CliSiTefI.getInstance();

9
3.1.3. Configurando a clisitef para acesso a PinPads
A partir da versão 4.0.0.10 da jCliSiTefI (Android), os seguintes PinPads são suportados(*):

Modelo Modo de acesso

PAX D200 Bluetooth
PAX D180 Bluetooth
Ingenico iCMP Bluetooth
Gertec MobiPin Bluetooth
Datecs Bluepad Bluetooth
Gertec PPC-900 e PPC-910 USB
Ingenico iPP-320 e iPP-350 USB
(*) A lista de pinpad´s USB está fixa internamente, pois cada dispositivo USB possui um Vendor ID e
Product ID específicos, e que foram testados anteriormente pela Software Express.

Importante: a comunicação com pinpad´s USB só é possível em dispositivos Android com SDK 12 ou
superior.

Importante: a comunicação com o pinpad será feita obrigatoriamente no modo “Comunicação

Segura”. Isto é, o pinpad deve ter suporte a esta característica.

Para manter compatibilidade com versões anteriores, a clisitef adota a seguinte heurística de
conexão:
1. Tenta-se obter a lista de dispositivos USB conectados.
2. Se reconhecer algum dos PinPads USB da lista acima, tenta-se fazer a conexão.
3. Se não obter um dispositivo válido, tenta obter um pinpad Bluetooth. Note que, neste caso, a
interface Bluetooth será automaticamente ligada. Além disso, a aplicação deve possuir
permissões no manifesto do projeto (veja a seção abaixo).

Para forçar a utilização da clisitef com exatamente um tipo de conexão com o pinpad (Bluetooth ou
USB), indique nos parâmetros adicionais do método configuraIntSiTefInterativoEx() o parâmetro
TipoPinPad, conforme a tabela abaixo:

Valor para TipoPinPad Descrição

ANDROID_AUTO Tenta obter conexão de acordo com a heurística acima.
ANDROID_USB Tenta obter conexão apenas com pinpad´s USB.
ANDROID_BT Tenta obter conexão apenas com pinpad´s Bluetooth.

Exemplo:

10
 CliSiTef = new CliSiTefI(this.getApplicationContext ());
CliSiTef.configuraIntSiTefInterativoEx ("10.100.100.108", "00000000",
"SE000001", "[TipoPinPad=ANDROID_BT;]");

Filtro de pinpad bluetooth usando seu endereço MAC

Na versão Android, a aplicação pode passar o endereço MAC da interface bluetooth do pinpad a ser
utilizado.
Esta funcionalidade pode ser interessante para acelerar o processo de conexão com um pinpad
específico, previamente pareado com o smartphone.
Para tanto, passe nos parâmetros adicionais do método configuraIntSiTefInterativoEx() o parâmetro
PinPad.MAC com o MAC Address correspondente.
Exemplo:

CliSiTef.configuraIntSiTefInterativoEx ("192.168.0.1", "00000000",

"SE000001", "[TipoPinPad=ANDROID_BT;PinPad.MAC=00:AE:BF:60:33:21;]");

Nota: não há distinção entre maiúsculos e minúsculos, no nome do parâmetro ou de seu valor.
É importante ressaltar que os demais pinpads previamente pareados não serão utilizados.
Entretanto, se for habilitada a utilização de pinpad usb (via configuração anterior), poder-se-á utilizar o
pinpad USB que for reconhecido.

Filtro de pinpad bluetooth usando seu Número Serial

Na versão iOs, a aplicação pode passar o número serial do pinpad a ser utilizado.
Esta funcionalidade pode ser interessante para acelerar o processo de conexão com um pinpad
específico, previamente pareado com o iPhone.
Para tanto, passe nos parâmetros adicionais do método ConfiguraIntSiTefInterativo da classe
ClisitefAsynco parâmetro PinPad.SERIAL com o número serial do pinpad desejado.
Exemplo:
[clisitef ConfiguraIntSiTefInterativo : @”192.168.0.1"
pCodigoLoja:@”11111111” pNumeroTerminal:@”00000001”ConfiguraResultado:0
pParametrosAdicionais:@”[PinPad.SERIAL=1234567890];"];
É importante ressaltar que os demais pinpads previamente pareados não serão utilizados.

11
 Depuração da aplicação ao usar um pinpad USB
Para depuração da aplicação com pinpad´s USB, muitas vezes será necessário colocar o dispositivo
para depuração TCP/IP, ao invés do convencional cabo USB. Neste caso, siga os passos abaixo:
1. Conecte o aparelho no computador com o cabo USB.
2. Certifique-se que o dispositivo está com o modo “Depuração de USB” habilitado.
3. Rode o comando:
adb tcpip 5555

4. Digite o comando de conexão ao dispositivo wifi, indicando seu IP (note que o DHCP pode dar IP´s
dinâmicos a cada conexão):
adb connect <IP do dispositivo Android>

Exemplo, supondo que o dispositivo Android está no IP 192.168.0.7:

C:\>adb tcpip 5555

restarting in TCP mode port: 5555

C:\>adb connect 192.168.0.7

connected to 192.168.0.7:5555

Pronto, desta forma deve ser possível fazer a depuração wi-fi pelo Eclipse.
Para retornar o adb ao modo USB, conecte o dispositivo novamente na porta USB de seu
computador, e digite:
adb usb

Outras informações:
http://developer.android.com/guide/topics/connectivity/usb/index.html

12
3.1.4. Pareamento com o PinPad Bluetooth
Para garantir acesso aos recursos de Bluetooth e redes requeridos pela clisitef na sua aplicação, é
necessário adicionar algumas permissões no manifesto do projeto (arquivo .xml):

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

Para que a CliSiTef possa utilizar os pinpads Bluetooth suportados os mesmos devem ser pareados
nas configurações do Android, cada pinpad possui uma forma de pareamento e obtenção do pin, as
instruções para configuração dos pinpads deverão ser obtidas com os fabricantes.

13
3.2. IOS

A CliSiTef/CliSiTefI/libSEPPEmv para dispositivos IOS é disponibilizada através de uma biblioteca

estática única.
‘libclisitef.a’ = Implementa os Pinpads Ingenico iSMP, iCMP, Datecs bluepad, Gertec Mobipin, PAX
D180 e PAX D200, compatível com os dispositivos IOS armv7, armv7s, arm64 e com os simuladores i386 e
x86_64 (somente transações digitadas).
Para adicionar a biblioteca ao projeto no XCode deve-se seguir os seguintes passos:
- Clicar no projeto na janela da esquerda para que apareçam suas configurações na área
central
- Abrir a guia “Build Phases”
- Expandir a guia “Link Binary with libraries”
- Clicar no sinal de “+” e adicionar o arquivo “.a“ desejado, conforme descrito acima
Também é necessário adicionar a aplicação o framework “External Accessory” fornecido pela Apple
na mesma janela descrita acima.
Devido ao modelo de eventos do iOS a clisitef deve ser executada assincronamente em outro
thread, deixando o thread principal livre para processar o eventos do sistema operacional, baseado nisso é
fornecida juntamente com a biblioteca iOS uma classe em objective C que abstrai as funções da clisitef
para o modelo utilizado pela Apple. A classe é descrita no arquivo ClisitefAsync.h e funciona através de
“protocols” para retornar os valores de saída da clisitef para a aplicação. Para maiores detalhes consultar o
programa exemplo fornecido junto com os binários da biblioteca.
A ultima versão do iOS suportada oficialmente até o momento é a versão 8.3

3.2.1. Ingenico iSMP/iCMP

Para utilizar os PinPads da Ingenico, além de adicionar a biblioteca estática correspondente
também é necessário adicionar ao projeto na tag “Supported external accessory protocols” da guia
“Info/Custom iOS target properties” o valor “com.ingenico.easypayemv.spm-transaction”.
Para utilização do pinpad iCMP é necessário parear o pinpad manualmente através das configurações
de Bluetooth no iOS.
Para maiores detalhes da integração com o iSMP/iCMP consultar os manuais fornecidos pela
Ingenico.

3.2.2. PAX D200

Para utilizar o PinPad PAX D200, além de adicionar a biblioteca estática correspondente também é
necessário adicionar ao projeto na tag “Supported external accessory protocols” da guia “Info/Custom iOS
target properties” o valor “com.paxsz.iPOS”.
Além disso o Pinpad precisa ser pareado ao dispositivo iOS manualmente, através da opção
Bluetooth disponível na tela de ajustes do iPhone/iPod/iPad.
O PIN a ser utilizado no pareamento é mostrado na tela do PinPad quando o mesmo é ligado.
14
3.2.3. Gertec Mobipin
Para utilizar o PinPad Gertec Mobipin, além de adicionar a biblioteca estática correspondente
também é necessário adicionar ao projeto na tag “Supported external accessory protocols” da guia
“Info/Custom iOS target properties” o valor “br.com.gertec.protocoloGertec”.
Além disso o Pinpad precisa ser pareado ao dispositivo iOS manualmente, através da opção
Bluetooth disponível na tela de ajustes do iPhone/iPod/iPad.
O PIN a ser utilizado no pareamento é mostrado na tela do PinPad quando o mesmo é ligado.

3.2.4. Datecs Bluepad

Para utilizar o PinPad Datecs Bluepad, além de adicionar a biblioteca estática correspondente
também é necessário adicionar ao projeto na tag “Supported external accessory protocols” da guia
“Info/Custom iOS target properties” o valor “com.datecs.pinpad”.
Além disso o Pinpad precisa ser pareado ao dispositivo iOS manualmente, através da opção
Bluetooth disponível na tela de ajustes do iPhone/iPod/iPad.
O PIN a ser utilizado no pareamento é mostrado na tela do PinPad quando o mesmo é ligado.

15
3.3. Windows Phone
A CliSiTef é disponibilizada no ambiente Windows Phone (8.0 ou 8.1) através de um Windows Phone
Runtime Component. Este componente disponibiliza métodos equivalentes à documentação da CliSiTefI.
Para utilizar a CliSiTef em aplicações Windows Phone, é necessário incluir no projeto os arquivos:
1. CliSiTefPRC.dll
2. CliSiTefPRC.winmd

Até o momento, existem as seguintes plataformas da CliSiTef para Windows Phone:

 arm

Até o momento, somente são suportados pinpad´s Bluetooth:

Modelo Modo de acesso
PAX D200 Bluetooth
PAX D180 Bluetooth
Ingenico iCMP Bluetooth
Gertec MobiPin Bluetooth
Datecs Bluepad Bluetooth

Importante: a comunicação com o pinpad será feita obrigatoriamente no modo “Comunicação

Segura”. Isto é, o pinpad deve ter suporte a esta característica.

3.3.1. Utilização da classe CliSiTefPRC.CliSiTef

Para utilizar a CliSiTef na aplicação Windows Phone, basta chamar o construtor da classe CliSiTef,
usando o namespace CliSiTefPRC.

var clisitef = new CliSiTefPRC.CliSiTef();

O evento OnNotify permite que a aplicação seja notificada de eventos adicionais (como mudanças de
status de conexão do PinPad). Para utilizar, basta incluir um método que siga a interface abaixo:

public delegate void TEventoNotificacao (Evento iEvento);

16
 Exemplo:

void clisitef_OnNotify (Evento evento)

{
/*
* Não é possível colocar o código do Dispatcher dentro do componente PRC C++,
* então a automação é obrigada a fazê-la. Exemplo:
*/
Dispatcher.BeginInvoke((Action)delegate()
{
switch (evento)
{
case Evento.EVT_INICIA_ATIVACAO_BT :
LabelStatus.Text = "Ativando BT";
break;
case Evento.EVT_INICIA_AGUARDA_CONEXAO_PP:
LabelStatus.Text = "Aguardando conexão pinpad";
break;
case Evento.EVT_FIM_AGUARDA_CONEXAO_PP:
LabelStatus.Text = "";
break;
case Evento.EVT_PP_BT_CONFIGURANDO:
LabelStatus.Text = "Pinpad conectado, aguarde...";
break;
case Evento.EVT_PP_BT_CONFIGURADO:
LabelStatus.Text = "Pinpad OK, prosseguindo com a transação";
break;
case Evento.EVT_PP_BT_DESCONECTADO:
LabelStatus.Text = "Pinpad desconectado";
break;
}
}, null);
}

...

clisitef.OnNotify += clisitef_OnNotify;

17
3.3.2. Integração com PinPad Bluetooth
Para garantir acesso aos recursos de Bluetooth e redes requeridos pela CliSiTef na sua aplicação, é
necessário incluir as capacidades ID_CAP_NETWORKING e ID_CAP_PROXIMITY no manifesto do projeto
(arquivo WMAppManifest.xml).

Filtro de pinpad bluetooth usando seu endereço MAC

A versão Windows Phone também permite que a aplicação passe o endereço MAC da interface
bluetooth do pinpad a ser utilizado.
Esta funcionalidade pode ser interessante para acelerar o processo de conexão com um pinpad
específico, previamente pareado com o smartphone.
Para tanto, passe nos parâmetros adicionais do método ConfiguraIntSiTefInterativoEx() o parâmetro
PinPad.MAC com o MAC Address correspondente.
Exemplo:

clisitef.ConfiguraIntSiTefInterativoEx ("192.168.0.1", "00000000",

"SE000001", "[TipoPinPad=WINPHONE_BT;PinPad.MAC=00:AE:BF:60:33:21;]");

É importante ressaltar que os demais pinpads previamente pareados não serão utilizados, mesmo no
caso em que o pinpad indicado esteja desligado.

18
4. Funções disponíveis

Neste capítulo estão listadas as funções da clisitef disponíveis nas plataformas móveis.

4.1. Android

Retorno Função
int carregaArquivosTraducao (java.lang.String arqTraducao)
Permite carregar um novo arquivo de mensagens para localização/tradução.
int carregaArquivosTraducao (java.lang.String arqTraducao,
java.lang.String arqTraducaoCielo)
int configuraIntSiTefInterativoEx (java.lang.String enderecoSiTef,
java.lang.String codigoLoja, java.lang.String numeroTerminal,
java.lang.String parametrosAdicionais)
int continuaFuncaoSiTefInterativo (java.lang.String buffer, int continuaNavegacao)
int correspondenteBancarioSiTefInterativo (java.lang.String cupomFiscal,
java.lang.String dataFiscal, java.lang.String horario, java.lang.String operador,
java.lang.String restricoes)
int descarregaMensagens ()
int escreveMensagemPermanentePinPad (java.lang.String mensagem)
int finalizaTransacaoSiTefInterativoEx(int confirma, java.lang.String cupomFiscal,
java.lang.String dataFiscal, java.lang.String horario,
java.lang.String parametrosAdicionais)
int iniciaFuncaoSiTefInterativo (int modalidade, java.lang.String valor,
java.lang.String cupomFiscal, java.lang.String dataFiscal, java.lang.String horario,
java.lang.String operador, java.lang.String restricoes)
int leCartaoDiretoSeguro (java.lang.String mensagem)
int leSenhaDireto (java.lang.String chaveSeguranca)
int leSimNaoPinPad (java.lang.String mensagem)
int obtemInformacoesPinPad ()
int obtemQuantidadeTransacoesPendentes (java.lang.String dataFiscal,
java.lang.String cupomFiscal)
int obtemVersao ()
Esta função é utilizada pelo terminal para obter as versões da CliSiTef e CliSiTefI.
Em caso de sucesso (retorno 0) utilize os métodos getVersaoCliSiTef() e
getVersaoCliSiTefI().
int pinpadConecta ()

19
int pinpadDesconecta ()
void setMessageHandler (android.os.Handler hndMessage)
Grava um handler para recepção de eventos genéricos
int validaCampoCodigoEmBarras (java.lang.String codigoEmBarras)
Int verificaPresencaPinPad()

4.2. iOS
As funções abaixo são as chamadas fornecidas pela classe ClisitefAsync, as chamadas a essas
funções são assíncronas, portanto para obter os resultados das chamadas é necessário
implementar os métodos delegate de retorno correspondentes descritos na definição da classe.
Função Delegate de Retorno
ConfiguraIntSiTefInterativo: (NSString*)pEnderecoIP respostaConfigura: (int)pResposta;
pCodigoLoja:(NSString*) pCodigoLoja
pNumeroTerminal:(NSString*) pNumeroTerminal
ConfiguraResultado:(short)ConfiguraResultado
pParametrosAdicionais:(NSString*)
pParametrosAdiionais;
IniciaFuncaoSiTefInterativo: (int)pModalidade respostaInicia: (int)pResposta;
pValor:(NSString*)pValor
pNumeroCupomFiscal:(NSString*)pNumeroCupomFiscal
pDataFiscal:(NSString*)pDataFiscal
pHorario:(NSString*)pHorario
pOperador:(NSString*)pOperador
pRestricoes:(NSString*)pRestricoes;
ContinuaFuncaoSiTefInterativo: (int)pContinua respostaContinua: (int)pResposta
pBuffer:(NSString*)pBuffer; pComando:(int)pComando
pTipoCampo:(long)pTipoCampo
pTamanhoMinimo:(short)pTamanhoMinimo
pTamanhoMaximo:(short)pTamanhoMaximo
pBuffer:(NSString*)pBuffer;
FinalizaTransacaoSiTefInterativo: (int)pConfirma respostaFinaliza;
pNumeroCupomFiscal:(NSString*)pNumeroCupomFiscal
pDataFiscal:(NSString*)pDataFiscal
pHorario:(NSString*)pHorario;
FinalizaTransacaoSiTefInterativoEx: (int)pConfirma respostaFinalizaEx: (int)pResposta;
pNumeroCupomFiscal:(NSString*)pNumeroCupomFiscal
pDataFiscal:(NSString*)pDataFiscal
pHorario:(NSString*)pHorario
pParametrosAdicionais:

20
(NSString*)pParametrosAdicionais;
LeCartaoSeguro: (NSString*)pMensagem; respostaLeCartaoSeguro:(int)Resultado;
LeSenhaDireto: (NSString*)pChave; respostaLeSenhaDireto:(int)Resultado
Senha:(NSString*)Senha;

4.3. Windows Phone (8 e 8.1)

Retorno Função
int CarregaArquivosTraducao (String^ arqTraducao)
Permite carregar um novo arquivo de mensagens para localização/tradução.
Na versão inicial, o arquivo deve ser carregado na pasta Assets da aplicação, indicando também
esta pasta no parâmetro arqTraducao. Exemplo:

clisitef.CarregaArquivosTraducao (“Assets\\mensagens_pt-br.txt”);

int CarregaArquivosTraducao (String^ arqTraducao, String^ arqTraducaoCielo)

int ConfiguraIntSiTefInterativoEx (String^ enderecoSiTef, String^ codigoLoja,
String^ codigoTerminal, String^ parametrosAdicionais)
int ContinuaFuncaoSiTefInterativo (int *comando, int *tipoCampo, short
*tamanhoMinimo, short *tamanhoMaximo, String^ *entrada, String^ saida, int
continuaNavegacao)

No Windows Phone não é possível termos um parâmetro de entrada e saída

simultaneamente. Neste caso, “entrada” contém valores retornados pela clisitef
para a automação, e “saida” deve conter o valor coletado pela automação, a ser
usado pela clisitef.
int CorrespondenteBancarioSiTefInterativo (String^ numeroCupomFiscal, String^
dataFiscal, String^ horario, String^ operador, String^ restricoes)
int DescarregaMensagens ()
int EscreveMensagemPermanentePinPad (String^ mensagemDisplay)
int FinalizaTransacaoSiTefInterativoEx (int confirma, String^ numeroCupomFiscal,
String^ dataFiscal, String^ horario, String^ parametrosAdicionais)
int IniciaFuncaoSiTefInterativo (int funcao, String^ valor, String^
numeroCupomFiscal, String^ dataFiscal, String^ horario, String^ operador,
String^ restricoes)
int LeSimNaoPinPad (String^ mensagemDisplay)
int ObtemInformacoesPinPad (String^ *infoPinPad)
int ObtemQuantidadeTransacoesPendentes (String^ dataFiscal, String^
numeroCupomFiscal)
int ObtemVersao (String^ *versaoCliSiTef, String^ *versaoCliSiTefI)
int ValidaCampoCodigoEmBarras (String^ codigoEmBarras, int *tipo)
int VerificaPresencaPinPad ()

21
5. Confirmação da transação: Processo Iterativo

Nas versões Mobile, a CliSiTef irá realizar a confirmação da transação de modo diferente, por meio
da função FinalizaTransacaoSitefInterativoEx.
Se o retorno for 10000, deve-se chamar a função ContinuaFuncaoSitefInterativo e o processo
interativo deverá ser retomado. Enquanto a CliSiTef retornar 10000, a chamada deve ser repetida até que
o valor de retorno seja 0, indicando que tudo ocorreu bem, ou diferente de 0 e de 10000, indicando que
ocorreu alguma interrupção anormal. Os parâmetros desta função são:

int FinalizaTransacaoSitefInterativoEx (Confirma, NumeroCupomFiscal,

DataFiscal, Horario, ParametrosAdicionais)

Parâmetro Binária ASCII Descrição

Tipo Tipo Tamanho
Confirma short F 1 Indica se a transação deve ser confirmada(1) ou
estornada(0)
CupomFiscal char * V Máx. 20 Número do cupom fiscal correspondente à venda
DataFiscal char * F 8 Data Fiscal no formato AAAAMMDD
Horario char * F 6 Horário Fiscal no formato HHMMSS
ParametrosAdicionais char * V - Parâmetros adicionais de configuração da CliSiTef

22
6. Arquivo de configuração: CLSIT

No documento “SiTef - Interface Simplificada com a aplicação” consta que o arquivo de

configuração da CliSiTef é “CliSiTef.ini”, mas para as plataformas mobile utilizaremos a denominação
‘CLSIT’ (sem extensão e em caixa alta).

6.1. Trace
Por padrão a gravação de informações de trace é desabilitada, para habilitar a gravação de traces
para diagnóstico de problemas pela equipe da Software Express, deve-se adicionar as seguintes
configurações no arquivo CLSIT:

[CliSiTef]
HabilitaTrace=1

[CliSiTefI]
HabilitaTrace=1

[PinPad]
HabilitaTrace=1
ChaveTrace= <Neste campo deve ser informada uma chave fornecida pelo suporte
técnico da Software Express>

Consulte as seções seguintes para maiores informações sobre traces para cada plataforma.

6.2. Android
O arquivo de configuração da CliSiTef (CLSIT) deverá ser incluído como um ‘asset’ da aplicação. Ao
instanciar a classe br.com.softwareexpress.sitef.android.*.CliSiTefI, este arquivo será copiado
automaticamente para a pasta ‘files’ da área de dados especificada para a aplicação:
/data/data/(package)/files.
Até a versão 1.007 da jclisitef-android.jar, era necessário especificar a área de dados da aplicação (
/data/data/(package) ).
Esta configuração era passada para a CliSiTef como um parâmetro adicional pelo método
ConfiguraIntSiTefInterativoEx, seguindo o formato: “[DiretorioApp=...]”.

Exemplo:

CliSiTef = new CliSiTefI();

CliSiTef.configuraIntSiTefInterativoEx ("192.168.0.1", "00000000", "SE000001",
"[DiretorioApp="+DiretorioApp+"];...");

23
 A partir da versão 1.008 da jclisitef-android.jar (2.000 da clisitef-android.jar), este valor é obtido
internamente, caso a automação não a configure.

Para geração e obtenção dos dados de trace em dispositivos Android, é necessário indicar a pasta
destino onde será gerado o trace. Isto é feito na seção CliSiTef, item DiretorioTrace.
No exemplo abaixo, configuramos a clisitef para armazenar o trace na memória interna do
dispositivo:

[CliSiTef]
DiretorioTrace=/sdcard

A partir da versão 1.008 da jclisitef-android.jar (2.000 da clisitef-android.jar), o valor padrão para

geração de traces (quando habilitado) é “/sdcard”. A configuração acima permite alterar este valor, caso
desejado.

Importante: para que a clisitef gere o trace na memória interna, a aplicação deve ter permissão para
escrita. Isto é feito no arquivo AndroidManifest.xml de sua aplicação.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="..."
android:versionCode="1"
android:versionName="1.0">
...

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

...
</manifest>

6.3. IOS
O arquivo de configuração da CliSiTef (CLSIT) deverá estar localizado na pasta da aplicação (<Nome
da aplicação>.app), como um bundle resource.
O CLSIT e os arquivos de Trace podem ser transferidos do dispositivo utilizando-se aplicativos que
permitem acesso aos arquivos dos dispositivos iOS como por exemplo o iExplorer disponível para Windows
e Mac em http://www.macroplant.com/iexplorer/ (a versão 2.0 é freeware e ainda pode ser obtida pelo
site na seção de produtos descontinuados)
Os arquivos de trace serão gravados em: <Dispositivo>/apps/<nome do aplicativo>/Library
No caso dos simuladores os arquivos de Trace podem ser obtidos diretamente pelo sistema de
arquivos do Mac de desenvolvimento no caminho: /Users/<nome do usuário>/Library/Application
Suport/iPhone Simulator/<Versão>/Applications/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX/Library

24
6.4. Windows Phone
O arquivo de configuração da CliSiTef (CLSIT) deve ser incluído como um ‘asset’ na aplicação.
Para isso, certifique-se que a CLSIT esteja presente na pasta “Assets” de seu projeto, com a
propriedade “Build Action” configurada para “Content”.
Já na versão inicial desta plataforma, não é necessário informar a configuração “DiretorioApp”. O
componente internamente identificará a pasta da aplicação, e a localização do arquivo CLSIT.
Por uma limitação da versão inicial, os traces são gravados internamente na Isolated Storage da
aplicação.
Para recuperar o arquivo, deve-se utilizar a ferramenta Isolated Storage Explorer (isetool.exe),
normalmente instalada na pasta

Program Files (x86)\Microsoft SDKs\Windows Phone\v8.0\Tools\IsolatedStorageExplorerTool

Além disso, é necessário utilizar o código de produto (product id) da aplicação. Este código pode ser
obtido no arquivo Manifest do projeto.
O comando para recuperar os dados da Isolated Storage é:

isetool ts de <product-id>
exemplo:
isetool ts de {7ad8ab6a-50c3-4315-a7ca-7d544cd25412}

Outras informações:
http://msdn.microsoft.com/en-us/library/windows/apps/hh286408%28v=vs.105%29.aspx

25
7. Problemas comuns

7.1. Problemas de comunicação com os Pinpads

PinPad PAX D200 Não habilita o Bluetooth
1. Caso a comunicação com o pinpad via Bluetooth não funcione e o pinpad não apareça para
pareamento, à comunicação Bluetooth dele pode estar desabilitada, para habilitá-la deve se seguir os
passos:
2. Inicialmente, note que, se o brilho da tela do pinpad diminuir, as teclas ficarão inativas. Neste caso,
pressione a tecla liga/desliga, que o brilho voltará ao estado normal, bem como o teclado.
3. - Com o pinpad ligado, digite a sequencia de teclas (não simultânea):
4. Amarelo, Verde, F2
5. Cada vez que esta sequencia for digitada, o pinpad fará o chaveamento da conexão, mostrando uma
mensagem na tela.
- CONFIGURACAO USB ATIVADA
- CONFIGURACAO SERIAL ATIVADA
- CONFIGURACAO BLUETOOTH ATIVADA
No último, aparecerá também o PIN de pareamento.
6. Para rever o PIN de pareamento basta religar o pinpad, ou pressionar as teclas (não simultânea):
7. Amarelo, Verde, F1
8. Neste caso ele mostra também o status de conexão bluetooth (ativado ou não ativado)

PinPad iSMP Não se comunica com o dispositivo iOS

Caso o dispositivo não reconheça o iSMP verifique se o mesmo está configurado para operar em
modo serial, para isto deve-se fazer como segue:
- Desligue o iSMP segurando os botões ‘clear’ (amarelo) e ‘.’ Ao mesmo tempo até que a tela se
apague;
- Ligue o iSMP segurando o botão ‘enter’ (verde) até que a tela acenda;
- Pressione repetidamente e em sequencia as teclas ‘1’ e ‘3’ até que o pinpad inicie, se o
procedimento for executado corretamente após alguns segundos irá aparecer um menu de opções. Caso o
pinpad inicie na tela normal desligue-o a repita a operação;
- Dentro do menu de configuração do iSMP use as teclas ‘f2’ e ‘f3’ para navegar entre as opções,
‘enter’ para confirmar e ‘clear’ para voltar;
- Selecione a opção ’Porta Comunic.’;
- Selecione a opção ‘Porta’;
- No iSMP selecione a opção ‘Serial’
- No iCMP selecione a opção ‘Bluetooth’, volte a tela anterior e indique a “assoc bt ios” para parear
com o dispositivo;
- Reinicie o dispositivo;

26