Manual Desenvolvedor Scope

Soluo Completa de Pagamento Eletrnico

Manual do desenvolvedor SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13 2

Informaes Gerais

Leia antes de utilizar o software:

imprescindvel a leitura deste material para o correto procedimento de instalao, configurao e administrao deste produto.

Reviso Data Responsvel Histrico 1.0 10/03/2008 Equipe Desenv. SCOPE Verso Inicial. 1.1 07/04/2008 Jailton da S. C. Santana Acrscimo do captulo Totalizao de TEF 1.2 23/04/2008 Equipe Desenv. SCOPE Funes da biblioteca compartilhada de PIN-Pad 1.3 24/04/2008 Jailton da S. C. Santana Apndice B includa a certificao com a Visanet 4.1

1.4 21/06/2008 Paulo dos Santos Reviso do texto, incluso de informaes no fluxo de recarga celular e PBM

1.5 10/07/2008 Paulo dos Santos Documentao de novos retornos

1.6 08/08/2008 Jailton da S. C. Santana Reviso do texto de PBM e de reimpresso de comprovante, e acrscimo do texto para deixar transao pendente e reimpresso on-line.

1.7 11/08/2008 Jailton da S. C. Santana Alterao das funes de reimpresso e melhoria do texto referente CDC.

1.8 01/04/2009 Paulo dos Santos Atualizao da tabela das bandeiras. 1.9 03/04/2009 Paulo dos Santos Atualizao da tabela das bandeiras.

1.10 05/06/2009 Paulo dos Santos Detalhamento do novo estilo versionamento para as bibliotecas do SCOPE Client para Linux.

1.11 14/08/2009 Paulo dos Santos Detalhamento da nova funcionalidade disponvel na recarga celular para a GWCel.

1.12 15/08/2009 Celso Hiroshi Nakata Atualizao das tabelas de Cdigos de Erros do Scope, Cdigos de Bandeiras e Cdigos de Servios

1.13 05/09/2009 Celso Hiroshi Nakata Atualizao da tabela de Cdigos de Bandeiras


ndice ________________________________________________________________________________________________

Prefcio ............................................................................................................................... 8 A quem se destina .......................................................................................................................................... 8 Descrio do Produto ..................................................................................................................................... 8

Objetivo ....................................................................................................................................................... 8 Definio ..................................................................................................................................................... 8 Benefcios .................................................................................................................................................... 8

Conceitos ........................................................................................................................... 8 Transaes ..................................................................................................................................................... 8 Fluxo de estados de coleta ............................................................................................................................ 9 Interfaces de interao com o SCOPE Client .............................................................................................. 10

Interface coleta .......................................................................................................................................... 10 Interface HLAPI ......................................................................................................................................... 10

Padres adotados neste documento............................................................................................................ 11

Instalao ......................................................................................................................... 13 Instalao do SCOPE Client para MS-Windows ........................................................................................ 13 Instalao do SCOPE Client para Linux ...................................................................................................... 13

Configurao .................................................................................................................... 15 Configurao do arquivo scope.ini ............................................................................................................... 15

Sesso [] ....................................................................................................................... 15 Sesso [SCOPEAPI] ................................................................................................................................. 16 Sesso [PPCOMP] .................................................................................................................................... 16 Configurao de porta serial para Linux ................................................................................................... 17

Configurao do registro do MS-Windows ................................................................................................. 17

Funes bsicas da API do SCOPE Client .................................................................... 18 Comunicao com o ScopeSRV .................................................................................................................. 18

Conexo .................................................................................................................................................... 18 Desconexo .............................................................................................................................................. 19

Sesso de transao .................................................................................................................................... 19 Sesso de TEF .......................................................................................................................................... 19 Abrindo uma sesso ................................................................................................................................. 20 Encerrando a sesso ................................................................................................................................ 21 Tratando queda de energia ....................................................................................................................... 22 Deixando transao pendente na queda de energia ................................................................................ 23

Status de transao...................................................................................................................................... 23 Consultando o status ................................................................................................................................ 24

Funes de configurao de ambiente .......................................................................... 25 Configuraes gerais ................................................................................................................................... 25

Configurando em tempo de execuo ...................................................................................................... 26 Configurao de PIN-Pad ............................................................................................................................ 26

Validando a interface de PIN-Pad ............................................................................................................. 26

Funes especficas das interfaces ............................................................................... 27 Interface coleta ............................................................................................................................................. 27

Definindo a interface coleta ....................................................................................................................... 27 Obtendo os parmetros da transao ...................................................................................................... 29 Passando o dado da coleta ao SCOPE Client .......................................................................................... 31

Interface HLAPI ............................................................................................................................................ 32 Suspendendo a transao ........................................................................................................................ 32 Retomando a transao ............................................................................................................................ 34 Abortando a transao .............................................................................................................................. 34

TEF .................................................................................................................................... 35


Carto de crdito .......................................................................................................................................... 35 Compra com carto de crdito .................................................................................................................. 35 Consulta a financiamento de carto de crdito ......................................................................................... 36 Consulta a saldo de carto de crdito ...................................................................................................... 37 Pr-autorizao de crdito ........................................................................................................................ 37

Carto de dbito ........................................................................................................................................... 38 Compra com carto de dbito ................................................................................................................... 38 Compra CDC (Crdito Direto ao Consumidor) ......................................................................................... 39 Consulta CDC ........................................................................................................................................... 39

Carto Dinheiro ................................................................................................................ 40 Operaes .................................................................................................................................................... 40

Compra/Carga do carto dinheiro ............................................................................................................. 40 Compra usando o carto dinheiro (debito) ............................................................................................... 41 Consulta ao saldo de carto dinheiro........................................................................................................ 41 Estornos .................................................................................................................................................... 42

Funes de Consulta ....................................................................................................... 42 Cheque ......................................................................................................................................................... 42

Consulta de cheques ................................................................................................................................ 42 AVS .............................................................................................................................................................. 43

Consulta AVS ............................................................................................................................................ 43

Recarga de celular ........................................................................................................... 44 Processando a recarga de celular................................................................................................................ 44

Iniciando a transao de recarga .............................................................................................................. 44 Obtendo operadoras disponveis .............................................................................................................. 45 Obtendo valores de recarga ...................................................................................................................... 48

Estorno de transaes .................................................................................................... 52 Introduo ..................................................................................................................................................... 52

Estornando a transao ............................................................................................................................ 53

Comprovantes .................................................................................................................. 53 Comprovantes de transaes ...................................................................................................................... 53

Obtendo os cupons de TEF ...................................................................................................................... 54 Reimpresso de comprovante ..................................................................................................................... 55

Solicitando o comprovante off-line ............................................................................................................ 56 Solicitando o comprovante on-line ............................................................................................................ 56 Imprimindo o comprovante correto ........................................................................................................... 57

PBM - Medicamentos ....................................................................................................... 59 Consultando medicamento ........................................................................................................................... 59 Compra de medicamento ............................................................................................................................. 60 Lista de medicamentos ................................................................................................................................ 61 Lista de medicamentos com CRM ............................................................................................................... 62

Funes de PIN-Pad ........................................................................................................ 64 Comunicao com o PIN-Pad ...................................................................................................................... 64

Iniciando a comunicao ........................................................................................................................... 64 Encerrando a comunicao ...................................................................................................................... 64

Mensagens no visor ..................................................................................................................................... 65 Mensagens de tamanho padro ............................................................................................................... 65 Mensagens maiores .................................................................................................................................. 65

Informaes obtidas do PIN-Pad ................................................................................................................. 66 Dados das redes autorizadoras ................................................................................................................ 66 Dados do dispositivo ................................................................................................................................. 66 Obtendo as informaes ........................................................................................................................... 67

Obtendo teclas do PIN-Pad .......................................................................................................................... 67 Iniciando a leitura da tecla ........................................................................................................................ 68 Obtendo a tecla ......................................................................................................................................... 68

Obtendo a senha aberta ............................................................................................................................... 69 Iniciando o modo de leitura da senha aberta ............................................................................................ 69


Lendo a senha aberta ............................................................................................................................... 69 Obtendo a senha criptografada .................................................................................................................... 70

Iniciando o modo de leitura da senha criptografada ................................................................................. 70 Lendo a senha criptografada .................................................................................................................... 71

Lendo um carto ........................................................................................................................................... 71 Iniciando a leitura do carto ...................................................................................................................... 72 Recuperando o carto ............................................................................................................................... 72

Abortando o processamento (ScopePPAbort) ............................................................................................. 73 Mensagens de erro (ScopePPMsgErro) ...................................................................................................... 74

Totalizao de TEF .......................................................................................................... 75 Relatrio de TEF .......................................................................................................................................... 75

Iniciando os totais...................................................................................................................................... 76 Cupom dos totais ...................................................................................................................................... 77 Dados dos totais........................................................................................................................................ 78

Funes diversas ............................................................................................................ 79 Dados da transao ..................................................................................................................................... 79

Obtendo handle ......................................................................................................................................... 80 Obtendo os campos .................................................................................................................................. 80

Fornecendo informaes extras para a transao ....................................................................................... 82 Descrio dos tipos de dados ................................................................................................................... 82 Atributos da aplicao ............................................................................................................................... 84 Atrelando dados transao .................................................................................................................... 85

ScopeGetLastMsg ........................................................................................................................................ 86 ScopeGetCheque ......................................................................................................................................... 86 ScopeAtualizaValor ...................................................................................................................................... 87 ScopeGarantiaDescontoCheque .................................................................................................................. 87 ScopeTransacaoFinanceira ......................................................................................................................... 88 ScopeInvestimento ....................................................................................................................................... 88 ScopeObtemCartaoInvestimento ................................................................................................................. 88 ScopeResumoOperacoes ............................................................................................................................ 89 ScopePagamento ......................................................................................................................................... 89

Apndice A Tabelas ...................................................................................................... 91 Cdigos de retorno ....................................................................................................................................... 91

Coleta de dados ........................................................................................................................................ 91 Autorizadoras ............................................................................................................................................ 93 Cdigos de erros do SCOPE .................................................................................................................... 94

Formatos dos dados ..................................................................................................................................... 99 Cdigos das Teclas ...................................................................................................................................... 99 Cdigos de Fluxo........................................................................................................................................ 100 Estados para interrupo ........................................................................................................................... 100 Cdigo das bandeiras ................................................................................................................................ 105 Dados disponveis das transaes ............................................................................................................. 108 Grupo de Servios ...................................................................................................................................... 109 Cdigos dos Servios ................................................................................................................................. 110 Convnios ................................................................................................................................................... 111

Apndice B Especificao Visanet 4.1 ...................................................................... 113 Adequao ................................................................................................................................................. 113 Certificao ................................................................................................................................................. 114

Apndice C PIN-Pad Compartilhado ......................................................................... 115 Apndice D Conjunto de bibliotecas do SCOPE Client ........................................... 117

MS-WINDOWS ......................................................................................................................................... 117 Linguagem Java ...................................................................................................................................... 117

Linux ........................................................................................................................................................... 118 Linguagem Java ...................................................................................................................................... 118

Apndice E Identificando a verso do SCOPE Client .............................................. 119 Verificando no SCOPE Server ................................................................................................................... 119


Verificando no ambiente do PDV ............................................................................................................... 120 SCOPE Client para MS-Windows ........................................................................................................ 120 SCOPE Client para Linux ........................................................................................................................ 121

Apndice F - Glossrio .................................................................................................. 123


ndice de Ilustraes

Figura 1: seqncia de mensagens numa transao completa e bem sucedida. ...................................... 9 Figura 2: janela do SCOPE Client na interface HLAPI ..............................................................................11 Figura 3: rvore do SCOPE no registro do MS-Windows ........................................................................18 Figura 4: viso geral do funcionamento do SCOPE Client. .......................................................................20 Figura 5: fluxo de processamento de uma transao com a interface coleta. ..........................................28 Figura 6: fluxo de processamento de uma transao com a interface HLAPI. .........................................33 Figura 7: atributos da aplicao cadastrados no ScopeCNF ....................................................................85 Figura 8: janela principal do servidor SCOPE .........................................................................................119 Figura 9: informaes adicionais do PDV ................................................................................................120 Figura 10: janela de propriedade de ScopeAPI.dll ..................................................................................121 Figura 11: visualizando a verso do SCOPE Client na linha de comando do Linux ...............................122


Prefcio _____________________________________________________________________________________________________

A quem se destina O manual do integrador destina-se aqueles que desenvolvem aplicao em que necessrio efetuar transaes com autorizadoras, banco, etc. e para isso utilizaro o SCOPE como concentrador de TEF.

Descrio do Produto Objetivo O sistema SCOPE Soluo Completa para Pagamento Eletrnico permite ao software de PDV efetuar o pagamento atravs de TEF, por exemplo, cartes de crdito e dbito, atravs da digitao do emboo ou leitura da tarja magntica ou chip.

Definio O SCOPE foi concebido para gerenciar todas as etapas de uma TEF abstraindo a complexidade inerente transao do aplicativo PDV.

Benefcios O sistema permite uma arquitetura flexvel, multi-empresa, multi-filial, centralizada ou

distribuda, adequando-se necessidade do cliente. Facilita a gesto do negcio, pois oferece ferramentas de consulta e relatrios

operacionais e gerenciais. Permite a gesto da sesso contbil, pelo estabelecimento ou pelo centro de

processamento, de forma a indicar eventuais divergncias nos crditos efetuados pelos bancos.

Permite mecanismos de alta-disponibilidade atravs de soluo cluster e rotas de contingncia.

Conceitos _____________________________________________________________________________________________________

Transaes O SCOPE prov loja diversos tipos de transaes (exemplo: compra com carto de crdito, compra com carto de dbito, recarga de celular, pagamento de contas e de fatura de cartes, etc.). Numa transao, o SCOPE Client comunica-se com o SCOPE Server baseado em mensagens, as quais seguem a norma ISO 8583 que especifica o protocolo de mensagens para transaes financeiras com carto. As mensagens bsicas e as suas seqncias que geralmente


compem uma transao completa e bem sucedida so demonstradas na figura 1 e descritas abaixo. Observe que a informao apresentada abaixo no exposta interface de programao, compreendendo um fluxo interno entre SCOPE Client e SCOPE Server.

9604 mensagem de solicitao da pr-TEF: esse tipo de mensagem geralmente enviado duas vezes com finalidade diferentes (primeira e segunda pr-TEF). A primeira pr-TEF contm o BIN de um carto e um grupo de servio alm de outros dados exigidos numa mensagem ISO. A segunda abrange o produto selecionado.

9614 mensagem de resposta da pr-TEF. Contem os dados solicitados pelo SCOPE Client. Como a mensagem 9604, esta diferir de acordo com o contexto da pr-TEF. A resposta da primeira a rede autorizadora, a bandeira, os servios disponveis e os atributos (ex.: limite de parcelas, data limite de agendamento, etc.) dos produtos habilitados para o carto capturado. A da segunda define para o SCOPE Client como as mensagens das transaes devero ser montadas.

0200 mensagem de solicitao da transao financeira. Neste momento, a mensagem vai at a rede autorizadora para que seja autorizada.

0210 mensagem de resposta da transao financeira. A autorizadora responde a solicitao com esta mensagem que abrange a aprovao ou a rejeio da solicitao.

0202 mensagem de confirmao da transao financeira. Esta mensagem a que confirma que a transao foi realmente efetivada. Ela indica, por exemplo, que o comprovante foi fisicamente impresso e que o processo como um todo foi concludo.

Figura 1: seqncia de mensagens numa transao completa e bem sucedida.

Fluxo de estados de coleta O funcionamento do SCOPE Client baseia-se em fluxos de estados de coleta para as diversas operaes disponveis. A cada iterao entre o aplicativo com o SCOPE Client, este informa em qual estado de coleta se encontra, qual informao deve ser coleta, qual mensagem deve ser exibida e quais opes de fluxo esto disponveis (retornar, prximo e cancelar). Desta forma o fluxo avana at que seja possvel efetuar a transao desejada.


Exemplificando: Ao iniciar uma transao de crdito, o SCOPE estar no estado de coleta nmero do carto. Uma vez obtido o carto, o estado avana e dependendo de uma srie de variveis, poder migrar para o estado coleta os 4 ltimos dgitos do carto. Conforme as configuraes possveis para o tratamento de servio de crdito, o prximo estado poder ser coletar se vista ou no, o fluxo avana at a impresso do comprovante.

Interfaces de interao com o SCOPE Client Antes de comear o desenvolvimento da integrao com o SCOPE, de fundamental importncia a deciso de como a aplicao ir interagir com o SCOPE Client, escolhendo uma das interfaces disponveis: interface coleta ou interface HLAPI. A escolha do tipo de interface depende de fatores tais como: Tempo de implementao, flexibilidade e plataforma adotada.

Interface coleta Disponvel para todos os sistemas operacionais com os quais o SCOPE Client executado, a interface coleta do SCOPE Client o que apresenta uma maior interao entre a aplicao de PDV e o SCOPE. Atravs desta interface, a aplicao se torna responsvel pela coleta dos dados digitados pelo operador ou cliente conforme a solicitao a cada iterao do SCOPE. Como a aplicao coletar os dados, ela se responsabilizar pela exibio da mensagem na tela e a entrada de dados para o operador, sendo que para alguns casos, dever tratar tambm a limitao do tamanho do campo aceitvel (ex.: para a coleta do nmero de segurana do carto, a aplicao permitir a entrada de um valor com no mnimo 3 e no mximo 5 dgitos).

Caractersticas da interface coleta Interceptar, para uso da prpria aplicao, os dados coletados via digitao para o

SCOPE; No interfere na interface grfica do usurio; Disponvel para qualquer linguagem e sistema operacional; A aplicao deve ter um maior nvel de especializao, portanto, maior lgica na

integrao.

Interface HLAPI Esta interface exige um nvel menor de integrao com a aplicao, pois toda a coleta de dado realizada pelo SCOPE atravs de uma pequena janela, do prprio SCOPE, que exibida na tela (figura 2). Est disponvel apenas para aplicaes MS-Windows de 32-bits.


Figura 2: janela do SCOPE Client na interface HLAPI Caractersticas da interface HLAPI

A coleta realizada pelo SCOPE, portanto a aplicao no sabe o que est sendo coletado;

Disponvel apenas para aplicaes Win32; Pode tratar perifrico (CMC7, impressora, etc.), desde que suportado pelo SCOPE; Possui GUI prpria, que no momento da transao, fica aberta, sobrepondo a

interface da aplicao.

Padres adotados neste documento Este documento descreve funes padronizadas no seguinte formato: LONG EXPORT ScopeNomedaFuncao (argumentos...)

As sesses que descrevem os argumentos ou parmetros das funes exibiro os mesmos numa tabela, cujas linhas representam cada parmetro e as colunas indicaro os seguintes dados:

1 coluna: parmetro de entrada [in] ou sada [out]; 2 coluna: tipo de dado que representa o parmetro; 3 coluna: nome da varivel representada no parmetro 4 coluna: significado do parmetro.

Todos os exemplos de cdigos relacionados neste documento esto seguindo a linguagem C com a seguinte formatao:

int main () { printf (Hello, SCOPE\s Programmers!); }

Para compatibilidade das funes entre diversas linguagens e plataformas, algumas convenes de tipos devem ser adotadas, conforme a tabela a seguir: Definio de Tipo:

Tipo Tamanho Descrio BYTE 1 byte Valor sem sinal de 0 a 255 WORD 2 bytes Valor sem sinal de 0 a 65.535


SHORT 2 bytes Valor com sinal de -32.768 a 32.767 LONG 4 bytes Valor com sinal de -2.147.483.648 a 2.147.483.647

Analogamente, como recurso de portabilidade, algumas constantes devem ser criadas e definidas diferentemente em cada plataforma, com o objetivo de utilizar os mesmos prottipos de funes conforme a tabela a seguir: Constantes:

Tipo Descrio EXPORT Usada nos prottipos das funes que so exportadas CALLBACK Funo cujo endereo de entrada fornecido a outras funes, de

modo que estas possam utilizar internamente da primeira


Instalao _____________________________________________________________________________________________________

Nesta sesso comentada a localizao das bibliotecas do SCOPE Client em cada sistema operacional. Quanto composio do SCOPE Client, deve-se consultar o Apndice E Conjunto de bibliotecas do SCOPE Client.

Instalao do SCOPE Client para MS-Windows As bibliotecas do SCOPE Client para MS-Windows devem estar em um diretrio acessvel pela aplicao. A deciso da localizao destas bibliotecas tomada pela equipe que desenvolve a aplicao de PDV, porque a particularidade da linguagem e/ou ambiente de desenvolvimento tem impacto sobre o acesso a elas. Normalmente, o SCOPE Client colocado no mesmo diretrio da aplicao integradora. No entanto, h casos em que ele est disponvel na pasta do sistema %windir%\System32.

CUIDADO: devido perda de controle sobre qual biblioteca o MS-Windows faz referncia, no aconselhvel que as bibliotecas estejam no diretrio do MS-Windows ou em qualquer subdiretrio.

No CD de instalao do SCOPE, h possibilidade de instalar o SCOPE Client na mquina. Esta instalao executar os seguintes passos:

criar um diretrio com o SCOPE Client; copiar o executvel do HotKey e seu atalho na rea de trabalho; alterar o registro do MS-Windows com os itens de configurao.

O SCOPE se utiliza de alguns arquivos de controle (no formato SXXXXYYYYZZZAAA.sc_), gerados em tempo de execuo. Assim, em sistemas operacionais com conceito de multi-usurios, como Linux e MS-Windows, existe a necessidade de permisso para escrita e leitura no diretrio da aplicao. No caso do MS-Windows, tais arquivos sero gerados em C:\.

Instalao do SCOPE Client para Linux Para a instalao do SCOPE Client em ambiente Linux, disponibilizado um arquivo no formato RPM. Este arquivo um pacote do sistema RPM (Red Hat Package Manager), utilizado em vrias distribuies Linux. O nome do arquivo liberado segue o padro:

itautec-scope--1.i386.rpm

onde: representa a verso e o release do SCOPE Client. Para a sua instalao execute o comando:

$ rpm i itautec-scope--1.i386.rpm Este comando instalar as bibliotecas na pasta /usr/lib.

IMPORTANTE: para a execuo deste comando necessrio ter direitos do usurio root.


CUIDADO: em ambiente Linux, o usurio root tem o direito de realizar comandos que podem danificar o sistema.

LEMBRETE: podem-se acrescentar os parmetros -vh para exibir o progresso da instalao.


Configurao ____________________________________________________________________________________________________

Configurao do arquivo scope.ini O arquivo scope.ini responsvel por parte da configurao da aplicao. Ele deve estar disponvel com o SCOPE Client, independente do sistema operacional que a aplicao executa.

Sesso [] Esta sesso a nica obrigatria para que o SCOPE Client possa se conectar ao ScopeSRV. Dentro dos colchetes deve haver uma seqncia de 8 dgitos, sendo que os 4 primeiros representam o cdigo da empresa e os demais, o cdigo da filial cadastrado no SCOPE. Estes cdigos devem ser iguais aos utilizados como parmetros da funo ScopeOpen(). Os valores das chaves configurveis nesta sesso se encontram na tabela abaixo. Chave Significado Valor

Name Endereo ou nome da mquina em que est o ScopeSRV.

I.P. ou nome da mquina do ScopeSRV

Port Porta de conexo do ScopeSRV. Valor numrico (o padro 2046).

AtualizaDataHora

Parmetro que decide se o SCOPE Client dever alterar a data e a hora da mquina para sincronizar com o ScopeSRV no momento da conexo.

N se no deve sincronizar (padro).

S caso deseja-se que sincronize.

MsgOperReduzida

Controla o tamanho mximo de colunas das mensagens que o SCOPE Client enviar para a aplicao para que esta exiba no teclado do operador ou display com esta finalidade.

N 40 colunas (padro)

s 20 colunas

m 16 colunas

ShowCupom Configura a exibio do cupom na tela. Utilizado apenas na interface HLAPI.

n No exibe s Exibe (padro)

TimeOutLogon Configura o tempo, em segundos, de espera para a conexo do SCOPE Client com o ScopeSRV.

Valor numrico entre 10 e 60 (padro 10).

TimeOutAdm Configura o tempo, em segundos, de espera da resposta da autorizadora em cada transao.

Valor numrico entre 15 e 180 (padro 30).

CupomReduzido Configura se deve exibir o cupom reduzido na tela. Utilizado apenas na interface HLAPI.

n No exibir

s Exibir

VersaoAutomacao Verso da automao passada pela rea Seqncia de caracteres no


de certificao da Visanet. formato RRAAAACCCC, sendo que: RR release de certificao do TEF AAAA Nome da automao CCCC Cdigo do memorando xxx (o padro 01HOTK0000)

As chaves mnimas exigidas so as duas primeiras (Name e Port), enquanto as outras so opcionais e depender da situao de cada aplicao. Exemplo: para a configurao de um PDV cadastrado na empresa 0001 e filial 0007, que ir se conectar ao ScopeSRV no IP 10.50.9.70, o scope.ini dever ser configurado da seguinte maneira: [00010007] Name=10.50.9.70

Port=2046

VersaoAutomacao= 01CAPS0001 ; valor fictcio

Sesso [SCOPEAPI] Esta sesso no obrigatria e define os parmetros abaixo relacionados ao ambiente: Chave Significado Valor SaveCupom Diretrio para salvar o cupom Diretrio (padro ./)

TracePin

Habilita o log do PIN-pad compartilhado. Em MS-Windows, ser gerado no C:\, nos demais sistemas, no diretrio corrente da aplicao, o arquivo TracePin.sc_. O sistema de log circular, assim quando o tamanho desse arquivo for 1 MB, ele ser renomeado para TracePin.bak e um novo TracePin.sc_ ser criado.

n No habilita (padro)

s Habilita

Sesso [PPCOMP] Aqui, configuram-se itens relacionados ao PIN-Pad compartilhado Chave Significado Valor

NaoAbrirDigitado Configura para no abrir o digitado se cancelada a leitura do carto no PIN-Pad compartilhado.

n no abre digitao (padro)

s abre digitao


Configurao de porta serial para Linux Atualmente, o SCOPE Client preparado para trabalhar apenas com PIN-Pad conectados porta serial. No entanto, para ambiente Linux, possvel conectar um PIN-Pad serial numa porta USB, utilizando um conversor SerialUSB. Normalmente os drivers existentes para esse conversor criam dispositivos (em /dev) nomeados ttyUSBx, ao invs dos ttySx. Para o redirecionamento da porta de comunicao no SCOPE, existem duas chaves a serem colocadas no arquivo scope.ini, configuradas conforme tabela abaixo. Chave Significado Valor

SerialNumPorts Nmero de portas a ser configuradas. Valor entre 1 e 6 (o padro 6)

SerialPortx Dispositivo com novo direcionamento para a porta (x-1). Valores de 0 a 5.

LEMBRETE: a configurao pode ser alternada entre as diversas portas.

Exemplo: suponhamos que possumos 3 equipamentos seriais, mas o computador que rodar a aplicao possui uma porta serial e duas USB. Ser necessrio que dois equipamentos utilizem conversores SerialUSB, que ao serem conectados, so criados dois novos dispositivos: ttyUSB0 e ttyUSB1 (os nmeros terminais 0 e 1 podem variar). Portanto, em algum ponto do arquivo scope.ini, deve ser colocado a configurao abaixo para atender esta mquina: SerialNumPorts=3

SerialPort0=/dev/ttyS0 ; porta 1 serial SerialPort1=/dev/ttyUSB0 ; porta 2 USB SerialPort2=/dev/ttyUSB1 ; porta 3 USB

CUIDADO: de acordo com a configurao acima, conectamos um equipamento na porta 1 e os outros dois, nas portas 2 e 3.

Configurao do registro do MS-Windows No sistema operacional MS-Windows possvel configurar o SCOPE Client utilizando o registro do sistema operacional. Abrindo o editor de registro, as configuraes do SCOPE devem estar em HKEY_LOCAL_MACHINE\SOFTWARE\Scope (figura 3).


Figura 3: rvore do SCOPE no registro do MS-Windows Relacionado na tabela abaixo, esto as chaves do scope.ini com o registro do MS-Windows.

Chave do arquivo scope.ini

Localizao no editor do registro

AtualizaDataHora HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\AtualizaDataHora CupomReduzido HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\CupomReduzido MsgOperReduzida HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\MsgOperReduzida Name HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPESRV\Name NaoAbrirDigitado HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\NaoAbrirDigitado Port HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPESRV\Port ShowCupom HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\ShowCupom TimeOutAdm HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\TimeOutAdm TimeOutLogon HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\ TimeOutLogon VersaoAutomacao HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\VersaoAutomacao

Funes bsicas da API do SCOPE Client _____________________________________________________________________________________________________

Comunicao com o ScopeSRV O funcionamento correto da maior parte das funes do SCOPE Client demanda a conexo com o ScopeSRV. Esta conexo possui a finalidade de carregar inicialmente todos os parmetros de configurao da aplicao, para que o SCOPE Client consiga realizar as transaes bsicas. Toda mensagem trocada entre o SCOPE Client e o ScopeSRV deve utilizar o protocolo TCP/IP.

Conexo Inicia o SCOPE Client, procedendo alocao dos recursos necessrios. Essa funo dever ser executada uma nica vez no incio do aplicativo de PDV.

Prottipo LONG EXPORT ScopeOpen (char *Modo, char *Empresa, char *Filial, char *PDV)

Parmetros [in] String (constante

igual 2) Modo Modo de operao


[in] String com quatro dgitos

Empresa Cdigo de identificao da empresa conforme cadastrado no ScopeCNF

[in] String com quatro dgitos

Filial Cdigo de identificao da filial conforme cadastrado no ScopeCNF

[in] String com trs dgitos

PDV Nmero do PDV conforme cadastrado no ScopeCNF

Retorno Ver tabela de cdigo de retorno. Exemplo ...

char empresa[] = 0001; char filial[] = 0001; char pdv[] = 0001; ...

retorno = ScopeOpen (2, empresa, filial, pdv); if (retorno != 0) { printf(Erro ao conectar com o SCOPE Server. Erro(%d), retorno); exit(0); } ...

Desconexo Encerra o SCOPE Client, procedendo liberao de todos os recursos alocados. Essa funo dever ser executada uma nica vez no trmino do aplicativo usurio.

Prottipo LONG EXPORT ScopeClose (void)

Parmetros No h parmetro. Retorno Ver tabela de cdigo de retorno. Exemplo ...

retorno = ScopeClose (); ...

Sesso de transao Sesso de TEF

O conceito de sesso de TEF existe para garantir a integridade de uma operao. Desta forma, entre a abertura e encerramento da sesso, todas as atividades includas na respectiva operao (autorizao da transao, impresso de comprovante) devero ser completamente realizadas. Este mecanismo permite que em caso de falha (queda de energia), a operao possa ser desfeita. Isso corresponde a imprimir corretamente o cupom de TEF e garantir que a falha ocorrida no atrapalhe no funcionamento da aplicao.


Sendo multi-TEF, o SCOPE implementa o conceito de sesso de TEF com o intuito de garantir que todas as transaes numa mesma sesso sero aprovadas ou desfeitas. Com isto, o cliente pode efetuar o pagamento parcialmente de diversas maneiras (exemplo: 40% do valor da venda sero pagos em dbito e o restante com o carto de crdito), e para validar a venda, todas as transaes devero ser aprovadas, caso contrrio, as transaes no podem ser concludas (no tem sentido que a venda seja considerada concluda apenas com a aprovao de parte do valor da compra). Em cada venda realizada, a aplicao deve abrir a sesso, realizar as diversas transaes e finalmente fechar a sesso, confirmando ou desfazendo todas as transaes desta venda. A estrutura do fluxo bsico de funcionamento do SCOPE Client encontra-se na figura 4.

IMPORTANTE: numa sesso de multi-TEF em que h vrias transaes, no possvel desfazer uma ou outra transao. Para isso, o operador dever cancelar todas daquela sesso ou confirm-las.

Figura 4: viso geral do funcionamento do SCOPE Client.

Abrindo uma sesso A funo ScopeAbreSessaoTEF() informa ao SCOPE para iniciar uma sesso de TEF (ciclo com uma ou mais transaes TEF). Ela deve ser invocada ao finalizar a venda e antes de selecionar o meio de pagamento.


Prottipo LONG EXPORT ScopeAbreSessaoTEF (void)


// Conecta ao servidor do SCOPE ...

// Realiza a venda ...

retorno = ScopeAbreSessaoTEF(); if (retorno != 0) { // Trata o erro e interrompe a seqncia. } else

{ // Inicia a(s) transao(s) desejada(s) } ...

Encerrando a sesso Aciona o SCOPE para finalizar uma sesso de TEF (ciclo com uma ou mais transaes de TEF), ou seja, confirmar ou desfazer as transaes da sesso em aberto, aps encerrar o processamento da transao.

Prottipo LONG EXPORT ScopeFechaSessaoTEF(BYTE Acao, BYTE *DesfezTEFAposQueda)

Parmetros

[in] Byte (0:Desfaz; 1:Confirma)

Acao Informa o SCOPE para confirmar ou desfazer a(s) transao(s) da sesso de TEF atual

[out] Ponteiro para byte DesfezTEFAposQueda Retorna se a(s) transao(s) da sesso de TEF foram desfeitas aps uma queda de energia.

Retorno Caso retorne sucesso (0x0000), significa que o SCOPE conseguiu com xito confirmar ou desfazer a(s) transao(s) de uma sesso de TEF. Caso contrrio, ocorreu algum problema na confirmao ou desfazimento da(s) transao(s). Para maiores detalhes dos cdigos relacionados, ver tabela de cdigo de retorno. Exemplo BYTE acao, defez;

...

// Realiza a(s) transao(s) desejada(s)


...

acao = 1; // confirmar retorno = ScopeFechaSessaoTEF(acao, &defez); if (retorno != 0) { // Erro no encerramento da sesso } ...

Tratando queda de energia A funo que encerra a sesso tambm utilizada para desfazer as transaes pendentes de uma sesso de TEF aps uma queda de energia no PDV. Nesse caso, aps a aplicao ter restabelecido a conexo com o servidor SCOPE, ela dever chamar essa funo para finalizar uma possvel sesso que ainda esteja em aberto. Nesse caso, realizado o desfazimento das transaes pendentes, independentemente, do parmetro de entrada. Um detalhe importante que uma sesso de TEF considerada finalizada ao iniciar a execuo dessa funo. Desta forma, mesmo que ocorra queda de energia durante a execuo dessa funo, o SCOPE considera como finalizado a sesso de TEF e proceder para realizar a ao solicitada. O segundo parmetro faz o papel principal no tratamento em queda de energia. Este parmetro independente do primeiro parmetro e somente tem funcionalidade nesta situao. Caso este parmetro seja devolvido com o valor 1 (True), a aplicao deve exibir a mensagem A transao TEF anterior foi desfeita (cancelada). Reter o cupom TEF, e se possvel, acionar um supervisor para verificar a situao.

Exemplo ...

BYTE acao, defez;

...


ScopeFechaSessaoTEF(acao, &defez); if (desfez) { printf(A transao TEF anterior foi desfeita (cancelada).); printf(\n Reter o cupom TEF.); } ...

IMPORTANTE: sempre que tratar uma possvel queda de energia e o segundo parmetro da funo ScopeFechaSessaoTEF() retornar o valor 1, deve-se imprimir a mensagem:

A transao TEF anterior foi desfeita (cancelada). Reter o cupom TEF


Deixando transao pendente na queda de energia Embora no haja como permitir confirmar uma transao depois que o PDV se recuperou da queda de energia, possvel deixar a transao pendente para depois realizar o acerto de pendncia manual no mdulo de pendncia SCOPEPND. Este acerto s dever ser realizado por um gerente, algum de finanas ou quem a empresa deposite confiana e seja responsvel para tal procedimento. O aplicativo deve chamar a funo ScopeMTEFOnOff(), antes do tratamento de queda de energia, informando se deseja desfazer ou deixar pendente as transaes.

Prottipo LONG EXPORT ScopeMTEFOnOff (BYTE Trata)

Parmetros

[in] Byte Trata Informa o SCOPE para desfazer (0) possveis transao interrompidas ou deixar pendente (1) para o posterior acerto manual.

Retorno 0x0000 definiu com xito a ao a ser tomada conforme o parmetro passado. 0xFE00 no foi aberta a conexo com o SCOPE Server. 0xFE01 tem transao em sendo processado.

Exemplo ...

BYTE acao, defez;

...


ScopeMTEFOnOff(1); // deixa pendente ScopeFechaSessaoTEF(acao, &defez); if (desfez) { printf(A transao TEF anterior foi desfeita (cancelada).); printf(\n Reter o cupom TEF.); } ...

Status de transao Durante o processamento da transao, a aplicao pode consultar o estado em que a transao est e tomar alguma ao baseado no valor dela. Esta ao pode estar entre uma das situaes abaixo, conforme o intervalo de cdigos retornado pelo SCOPE Client:

valor igual 0: transao finalizada com sucesso. valores entre 3 (3h) e 92 (5Bh): erro de algum parmetro passado para o SCOPE; valores entre 64001 (FA01h) e 64005 (FA05h): erro de algum parmetro passado para o

SCOPE;


valores entre 64257 (FB01h) e 64267 (FB0Bh): erro interno do SCOPE; valores entre 64512 (FC00h) e 64767 (FCFFh): coleta de algum dado necessrio

transao; valores entre 65024 (FE00h) e 65535 (FFFFh): erro reportado pelo SCOPE referente

transao; Enquanto o SCOPE Client devolver o cdigo de status igual a 65024 (FE00h), a aplicao dever aguardar algum tempo at que outro status seja fornecido. Consultando o status A consulta do status da transao deve ocorrer enquanto uma transao (carto de crdito, carto de dbito, recarga de celular, etc.) est em processamento.

Prottipo LONG EXPORT ScopeStatus (void)


// Abre sesso retorno = ScopeCompraCartaoCredito(valor, taxa_servico); if (retorno == 0) { do

{ retorno = ScopeStatus(); // trata conforme retorno if (retorno == 64024) { sleep (1000); continue;

} else

if ((retorno = 0xFCFF)) processando == 0; //saiu da faixa de coleta // trata a coleta de algum dado } while (processando == 1); } // fim do if else

{ // Trata erro retornado na solicitao da transao } ...


Funes de configurao de ambiente _____________________________________________________________________________________________________

O SCOPE Client carrega diversos parmetros de configurao para seu funcionamento no ambiente de PDV em que est executando. Estes dados so carregados na conexo com o ScopeSRV e na leitura do arquivo scope.ini. Alm destas duas fontes de configurao, h tambm aquela que a aplicao pode fazer por meio de algumas funes disponveis nas bibliotecas do SCOPE Client. Dependendo do tipo de configurao a que nos referimos, ela permite a aplicao ativar ou desativar as configuraes durante a execuo do programa.

Configuraes gerais No momento de execuo do aplicativo, a aplicao de frente de loja poder configurar os seguintes itens:

Cdigo de identificao

Descrio

1

Permite que a aplicao cancele a transao que est sendo executada no PIN-Pad quando este esteja coletando algo. Por padro, a aplicao no tem conhecimento do momento em que o SCOPE est coletando o carto, a senha ou outra informao no PIN-Pad, pois ele retorna o estado indicando processamento (65024), o qual no um estado de coleta, e, portanto, inviabilizando o uso da funo ScopeResumeParm() para o possvel cancelamento.

2 Habilitado este item, o SCOPE retornar o estado para obter os servios (64644) durante o fluxo de TEF para que a aplicao de PDV possa obter os servios e parmetros configurados no ScopeCNF.

4 Se habilitado, no abrir o digitado na leitura do carto com o PIN-Pad Compartilhado. Por padro, ao pressionar a tecla cancela no PIN-Pad, o SCOPE Client retornar um estado para coletar o PAN do carto.

8

Normalmente, ao solicitar a digitao da senha no PIN-Pad pela funo ScopePPStartGetPIN(), a funo ScopePPGetPIN() retorna para a aplicao a senha digitada no PIN-Pad descriptografada. Habilitando este item, a senha retornada estar criptografada pela MasterKey da Itautec.

16 PDVs com impressora com papel de carbono podem habilitar este item para no imprimir a informao de 1a Via Cliente ou 2a Via Estabelecimento nos respectivos cupons.

IMPORTANTE: este tipo de configurao s permitido quando a aplicao est utilizando a interface coleta.


Configurando em tempo de execuo A funo ScopeConfigura(), responsvel para a configurao da aplicao de PDV citada acima, poder ser executada apenas uma nica vez aps a inicializao do SCOPE ou antes das operaes TEF.

Prottipo LONG EXPORT ScopeConfigura (LONG Id, LONG Param)

Parmetros [in] LONG Id Identifica o parmetro a ser configurado

conforme tabela acima

[in] LONG Param Informa se deve habilitar ou desabilitar o item. Para habilitar a aplicao dever passar o valor 1 e para desabilitar, o valor 0.


// conexo com o scope server bem sucedida ...

// trabalhando com impressora carbonada retorno = ScopeConfigura(16, 1); ...

Configurao de PIN-Pad Para evitar a substituio de PIN-Pad por um tipo incompatvel com a configurao do ScopeCNF, h a possibilidade de informar o SCOPE o tipo do PIN-Pad que est conectado e proibir a execuo de transao. A validao est baseada nas seguintes opes:

valor 0: no possui PIN-Pad conectado; valor 1: utilizando PIN-Pad via biblioteca VISANET; valor 2: utilizando PIN-Pad com biblioteca compartilhada.

Validando a interface de PIN-Pad A validao da interface utilizada pela aplicao de PDV versus a configurada no ScopeCNF somente ocorrer na chamada funo ScopeOpen(). Sendo assim, a aplicao de PDV deve solicitar a validao antes da conexo com o servidor do SCOPE.

Prottipo LONG EXPORT ScopeValidaInterfacePP (BYTE IntPP)

Parmetros

[in] BYTE IntPP informa ao SCOPE a interface de acesso ao PIN-Pad compartilhada utilizada pela Aplicao PDV.

Retorno Ver tabela de cdigo de retorno.


Exemplo ...

// PIN-Pad compartilhado conectado retorno = ScopeValidaInterfacePP(2); // conecta ao ScopeSRV ...

LEMBRETE: a chamada a essa funo deve ser feita antes de chamar a funo ScopeOpen().

Funes especficas das interfaces _____________________________________________________________________________________________________

Dependendo da interface sobre a qual a aplicao de PDV foi desenvolvida, a aplicao dever tratar funes especficas da interface escolhida.

Interface coleta Como a aplicao ser responsvel pela coleta (entrada de dados do usurio), esta deve obter do SCOPE Client informaes para solicitar os dados. Da mesma maneira, a aplicao deve devolver o que foi coletado para o SCOPE Client. Antes de tudo, a aplicao necessita de um meio para informar ao SCOPE Client que o modo de interao ser pela interface coleta. O fluxo da aplicao, quando esta utiliza a interface coleta, est esboado no diagrama da figura 5. Nos tpicos subseqentes explicamos os mecanismos para realizar estas operaes. Na interface coleta, o SCOPE Client retornar, atravs da funo ScopeStatus(), um cdigo (ver cdigos na tabela Coleta de dados) sempre que necessitar de uma atuao do aplicativo, como por exemplo, coletar dados, imprimir cupons e cheques, mostrar mensagens para o operador e/ou cliente, entre outros.

Definindo a interface coleta Antes de realizar qualquer transao, a aplicao deve definir a interface coleta como meio de interao, o que realizado pela funo ScopeSetAplColeta(). Isto dever ser feito aps a conexo do SCOPE Client com o servidor.

Prottipo LONG EXPORT ScopeSetAplColeta(void)


// Conexo ao ScopeSRV bem sucedida ...

retorno = ScopeSetAplColeta();


...

Figura 5: fluxo de processamento de uma transao com a interface coleta.


Obtendo os parmetros da transao Durante a iterao do processamento de uma transao, a aplicao deve obter informaes necessrias para solicitar a coleta do dado para o operador e/ou cliente. A funo ScopeGetParam(), responsvel em descrever os dados a coletar, deve ser chamada sempre que o SCOPE Client retornar um estado de coleta correspondente a uma coleta de dados (ver Status de transao). Com o retorno do SCOPE Client, a aplicao de PDV dever atualizar as mensagens das telas do operador e/ou cliente, disponibilizar um meio de entrada de dado, validar a entrada, entre outras aes. A aplicao deve prover o operador de algum meio que ele possa cancelar, retornar e continuar a coleta de dados da transao. As mensagens que o SCOPE Client disponibiliza para serem exibidas, so fundamentadas no fato de que no PDV haja dois visores (display): um que apresentado ao cliente da loja e outro, apresentado ao operador do PDV. Alm disso, por padro, considera-se que cada um desses visores possua 2 linhas de exibio de mensagens com largura de 40 caracteres. possvel configurar o tamanho mximo de colunas para at 20 ou 16 (ver o captulo Configurao).

Estruturas de apoio Para a aplicao receber do SCOPE Client as informaes para coleta, ela dever passar um endereo de memria de um buffer que representado, em linguagem C, pela estrutura ptPARAM_COLETA definida no arquivo ScopeApi.h, cuja declarao : typedef struct _stPARAM_COLETA { WORD Bandeira; WORD FormatoDado; WORD HabTeclas; char MsgOp1[64]; char MsgOp2[64]; char MsgCl1[64]; char MsgCl2[64]; char WrkKey[16+1]; #ifdef __linux__ char filler; #endif WORD PosMasterKey; char PAN[19+1]; BYTE UsaCriptoPinpad; BYTE IdModoPagto; BYTE AceitaCartaoDigitado; char Reservado[105]; } stPARAM_COLETA, *ptPARAM_COLETA; A descrio de cada campo encontra-se abaixo:

Bandeira: a bandeira do carto relativa operao em andamento (ver Cdigo das bandeiras);

FormatoDado: cdigo respectivo ao formato do dado a ser coletado (ver tabela de cdigos em Formato dos dados);

HabTeclas: teclas que esto disponveis para a aplicao. um campo com combinao de bits. Exemplo: se o campo estiver com o valor 6 (2 + 4 = 6), significa que as teclas para prosseguir (valor 2) e retornar (valor 4) a coleta devem estar


habilitadas, desabilitando a tecla cancelar (valor 1) (ver cdigos relacionados na tabela Cdigo das teclas);

MsgOp1: mensagem para exibio na linha 1 do visor do operador (string); MsgOp2: mensagem para exibio na linha 2 do visor do operador (string); MsgCl1: mensagem para exibio na linha 1 do visor do cliente (string); MsgCl2: mensagem para exibio na linha 2 do visor do cliente (string); WrkKey: chave de trabalho utilizada pela funo PP_iGetPIN() que responsvel

pela coleta de senha criptografada no PIN-Pad (string). Este campo utilizado apenas com a biblioteca da VISANET para PIN-Pad;

filler: para alinhamento em 8 bytes nos ambientes executados sobre o sistema operacional Linux;

PosMasterKey: posio da Master Key utilizada pela funo PP_iGetPIN(). Este campo utilizado apenas com a biblioteca da VISANET para PIN-Pad;

PAN: nmero do carto utilizado pela funo PP_iGetPIN(). Este campo utilizado apenas com a biblioteca da VISANET para PIN-Pad;

UsaCriptoPinpad: indica se a aplicao dever coletar senha com criptografia no PIN-Pad (funo PP_iGetPIN()) ou sem criptografia no PIN-Pad (funo PP_iGetString()). Para o valor 1 (um), deve coletar com criptografia no PIN-Pad e para o valor 0 (zero), sem criptografia. Este campo utilizado apenas com a biblioteca da VISANET para PIN-Pad;

IdModoPagto: modalidade de pagamento (crdito, dbito ou outros). Parmetro utilizado na chamada da funo PP_iGetCard(). Este campo utilizado apenas com a biblioteca da VISANET para PIN-Pad;

AceitaCartaoDigitado: indica se aceita a entrada digitada do nmero do carto. Informao disponvel no estado de coleta do carto;

Reservado: utilizao futura.

Prottipo LONG EXPORT ScopeGetParam (LONG tipoParam, ptPARAM_COLETA lpParam)

Parmetros

[in] LONG TipoParam

Aplicao informa que tipo de parmetro (retornado pelo ScopeStatus()) deseja-se obter, isto , os parmetros para uma coleta de dados e/ou exibio de uma mensagem.

[out] ptPARAM_COLETA lpParam Conjunto de dados para a coleta detalhado acima


// executa transao (crdito, dbito, etc.)


stPARAM_COLETA Pcoleta;

...

// inicia iterao retorno = ScopeStatus(); if(retorno != 0xFE00) { ...

memset(&PColeta, '\0', sizeof(PColeta)); retorno = ScopeGetParam(retorno, &PColeta); // atualiza as teclas retornar, avanar e cancelar // coleta os dados ...

// entrega o que coletou ao SCOPE ...

} // finaliza iterao

Passando o dado da coleta ao SCOPE Client Realizando a coleta de dados solicitada pelo SCOPE via funo ScopeStatus(), a aplicao devolver o que foi coletado e alguma ao ao SCOPE. A ao se refere interrupo do processamento, retorno para um estado anterior ou continuao para o prximo estado de coleta. Os dados coletados so entregues ao SCOPE por meio da funo ScopeResumeParam().

Prottipo LONG EXPORT ScopeResumeParam (LONG codTipoColeta, char *dados, WORD dadosParam, eACAO_APL acao)

Parmetros [in] LONG codTipoColeta Cdigo do estado, obtido pela funo ScopeStatus(), para qual o dado foi coletado [in] String dados Dado coletado pela aplicao

[in] WORD dadosParam

Modo de captura do dado. Informa se a captura foi feita pelo teclado (0x0004) ou pela leitura magntica (0x0020) ou pela interface que suporta tanto a leitura magntica como a leitura do Chip (0x0080) ou pela leitura de CMC7 (0x0010)

[in] eACAO_APL Ao Ao tomada pelo operador (ver Cdigos de Fluxo)


// executa transao (crdito, dbito, etc.) char *dados[128]; WORD modo_entrada;

...

// inicia iterao cod_coleta = ScopeStatus(); if(cod_coleta != 0xFE00)


{ ...

// obtm os parmetros para a coleta // atualiza as teclas retornar, avanar e cancelar // coleta os dados e armazena em na varivel dados modo_entrada = 0x0004; // pelo teclado // obtm a ao que o usurio escolheu e coloca em acao ...

// entrega o que coletou ao SCOPE na funo abaixo ScopeResumeParam(cod_coleta, dados, modo_entrada, acao); ...

} // finaliza iterao

Interface HLAPI Sendo o SCOPE responsvel pela coleta de dados, a aplicao possui menos trabalho durante a transao. Entretanto ainda so necessrios 2 outros tratamentos: obteno de dados para uso da aplicao e notificao do SCOPE para impresso do cupom (figura 6). Muitas vezes a aplicao necessita controlar a venda e seu meio de pagamento. Para aquelas vendas que so pagas com carto, a aplicao pode manter na informao da venda, alguns dados da TEF para controle de caixa. As informaes da TEF que a aplicao poder precisar para esse controle so vrias. O SCOPE Client fornece a funo ScopeObtemCampoExt() para a obteno dos dados da transao. A impresso de cupons outro ponto de ateno que a aplicao deve tratar para compensar este tipo de interface. Uma vez que na interface HLAPI o SCOPE Client coleta todos os dados e a aplicao no tm conhecimento do que ele est fazendo, num determinado momento ela deve pedir para o SCOPE suspender a transao, para que o cupom seja impresso. Uma vez suspensa, a aplicao obtm os cupons, imprime-os e informa ao SCOPE que ele poder continuar ou at mesmo cancelar a transao.

Suspendendo a transao A aplicao deve fazer isso ao menos uma vez na interface HLAPI antes de cada transao. A aplicao poder solicitar ao SCOPE Client para que ele suspenda em diversos momentos. Mas, ao menos uma vez, porque primordial que a transao esteja suspensa para imprimir o cupom. Existem diversos cdigos representando pontos ou estados de coleta em que o SCOPE Client pode suspender a transao, sendo feitos com a funo ScopeSuspend().


Figura 6: fluxo de processamento de uma transao com a interface HLAPI.


Prottipo LONG EXPORT ScopeSuspend (LONG estado)

Parmetros

[in] LONG estado

Estado de parada. Indica o passo de execuo aps o qual o controle de execuo retornar ao aplicativo. O SCOPE client manter o contexto de sada e aguardar que o aplicativo retome, ou aborte o seu fluxo de execuo. (Ver a lista de cdigos de estado na tabela Estados para interrupo)


// definindo o ponto de suspenso retorno = ScopeSuspend(4); ...

LEMBRETE: uma vez suspensa a transao, o SCOPE Client no retomar sozinho. necessrio que a aplicao notifique o SCOPE para retoma-la.

Retomando a transao Todo o tempo em que a transao est suspensa, a aplicao far algo que ela necessita. Realizado o que a aplicao deveria fazer enquanto a transao est suspensa, a aplicao deve informar para o SCOPE que pode continuar, caso contrrio, a transao no ser concluda.

Prottipo LONG EXPORT ScopeResume (void)


// SCOPE passou o controle para a aplicao, suspendendo a transao ...

// A aplicao fez o que desejava (ex: imprimiu o cupom) ...

retorno = ScopeResume(); ...

Abortando a transao Em certos momentos, a transao no pode ser concluda. Por problema na impressora, desistncia do cliente, etc. Enquanto a transao estiver suspensa, caso se deseje cancelar a transao, a aplicao poder continuar a transao e fechar a sesso solicitando que o SCOPE


desfaa-a ou simplesmente aborte no ponto em que est suspensa. A complicao em desfazer a transao no momento do encerramento da sesso, que todas as transaes sero desfeitas. A funo ScopeAbort() aborta o fluxo de execuo do SCOPE Client suspenso pela funo ScopeSuspend() ou quando o SCOPE Client est aguardando uma ao do aplicativo.

Prottipo LONG EXPORT ScopeAbort(void)


// transao suspensa ...

// deseja-se cancelar a transao ScopeAbort(); ...

CUIDADO: s possvel abortar uma transao quando ela est suspensa.

TEF _____________________________________________________________________________________________________

Nas sees seguintes, trataremos sobre as transaes com carto crdito e dbito, desde compras a saldo at as prprias consultas de saldo.

Carto de crdito Uma das operaes mais realizadas numa loja e muito incentivada pelas empresas de cartes, o pagamento de compra com o carto de crdito apresenta diversos servios relacionados: compra vista, parcelada pela loja, parcelada pela administradora de carto, consulta de saldo e de financiamento e cancelamento (que dedicamos um captulo exclusivo). Compra com carto de crdito Embora haja diversos servios relacionados ao carto de crdito, apenas uma funo est disponvel: ScopeCompraCartaoCredito(). Ela se refere ao grupo de servio de crdito e trata os seus servios. O que determinar cada um destes servios ser o fluxo do SCOPE de acordo com o que este solicitar e o que o usurio devolver. Assim, a transao poder terminar como vista, parcelada pelo estabelecimento ou parcelada pela administradora.

Prottipo LONG EXPORT ScopeCompraCartaoCredito (char *Valor, char *TxServico)

Parmetros

[in] String com o mximo de 12 dgitos

Valor Valor da transao com a vrgula implcita (exemplo: R$ 123,00 = 12300)


[in] String TxServico Valor da taxa de servio


char valor[12 + 1]; char taxa[12 + 1]; ...

// obtm o valor da compra e armazena em valor // obtm a taxa de servio e armazena em taxa // abre sesso ...

retorno = ScopeCompraCartaoCredito(valor, taxa); ...

// processa a transao ...

// fecha a sesso ...

Consulta a financiamento de carto de crdito Antes de realizar uma compra financiada pela administradora de carto de crdito, possvel consulta das parcelas do financiamento. A consulta seguir os moldes de uma transao de compra, sendo que em nenhum momento ser efetivada. Portanto, aps a consulta, necessrio realizar a compra, que solicitar os mesmos dados da consulta.

Prottipo LONG EXPORT ScopeConsultaCredito (char *Valor, char *TxServico)

Parmetros


Valor Valor da transao com a vrgula implcita (exemplo: R$ 123,00 = 12300) [in] String TxServico Valor da taxa de servio




retorno = ScopeConsultaCredito(valor, taxa); ...




Consulta a saldo de carto de crdito Um dos motivos que uma transao pode no ser aprovada a falta de saldo suficiente do cliente no carto de crdito. Alguns cartes permitem esta consulta.

Prottipo LONG EXPORT ScopeConsultaSaldoCredito (void)

Parmetros No h parmetros. Retorno Ver tabela de cdigo de retorno. Exemplo ...

// abre sesso ...

retorno = ScopeConsultaSaldoCredito(); ...



Pr-autorizao de crdito Como a consulta de saldo do carto de crdito no est disponvel para todos os cartes e por representar certo risco (cartes roubados podero ter todo o seu limite gasto, sendo conhecido o seu saldo), outras administradoras disponibilizam a opo de pr-autorizao. Assim, antes de fazer a compra, possvel realizar uma pr-autorizao para verificar se a compra proceder com sucesso.

Prottipo LONG EXPORT ScopePreAutorizacaoCredito (char *Valor, char *TxServico)

Parmetros




char valor[12 + 1]; char taxa[12 + 1];


...


retorno = ScopePreAutorizacaoCredito(valor, taxa); ...



Carto de dbito Abrangendo diversos servios, como o carto de dbito, uma das transaes mais realizadas nos estabelecimentos. Falando em servios, nos referimos a dbito vista, dbito pr-datado, dbito parcelado com a 1 parcela agendada ou vista, dbito Voucher, saque e CDC.

Compra com carto de dbito Para os servios de dbito vista, dbito pr-datado, dbito parcelado com a 1 parcela agendada ou vista e dbito Voucher, deve-se utilizar a funo ScopeCompraCartaoDebito(). Como as outras transaes, o fluxo de processamento similar.

Prottipo LONG EXPORT ScopeCompraCartaoDebito (char *Valor)

Parmetros




char valor[12 + 1]; ...

// obtm o valor da compra e armazena em valor ...

// abre sesso ...

retorno = ScopeCompraCartaoDebito(valor); ...




Compra CDC (Crdito Direto ao Consumidor) Apesar de exisitir uma funo ScopeCompraCDC() responsvel por essa modalidade de servio, esta transao foi incorporada ao fluxo da transao ScopeCompraCartaoDebito() devido exigncia da especificao Visanet 4.1. O que difere no fluxo de um pagamento com carto de dbito que um CDC um dbito parcelado pela administradora. Caso no fluxo de compra CDC for realizado uma consulta, os cupons da consulta no podero ser impressos devido a problemas de controle fiscal. Estes cupons devero ser exibidos no visor para o cliente. Somente os cupons da compra que devero ser impressos caso haja interesse em continuar a compra aps a consulta.

Consulta CDC Para uma simples consulta CDC, independente da compra, deve-se utilizar a funo especfica para a transao: ScopeConsultaCDC(). O resultado desta transao ser um cupom com valores do parcelamento com as taxas. Quando a consulta for realizada por esta funo, os cupons da consulta devero ser enviados para a impressora.

Prottipo LONG EXPORT ScopeConsultaCDC (char *Valor, char *TxServico)

Parmetros






retorno = ScopeConsultaCDC(valor, taxa); ...



LEMBRETE: a compra CDC efetuada no fluxo de dbito, ou seja, dever ser chamada a funo ScopeCompraCartaoDebito() para a realizao dessa compra.


Carto Dinheiro _____________________________________________________________________________________________________

So cartes ao portador, protegido por senha, semelhante ao carto de debito que adquirido (comprado) com um valor fixo, e posteriormente pode ser recarregado. utilizado principalmente para efetuar compras, debitando esse valor do saldo do carto, cujo objetivo a substituio de dinheiro por este carto. Tambm, conhecido como Carto Presente ou Gift Card.

Operaes As operaes (transaes) que podem ser efetuadas com o carto dinheiro so: - Compra/Carga de carto - Compra usando carto (debito) - Consulta a saldo - Estornos

Compra/Carga do carto dinheiro Para realizar a operao de recarga, e tambm, a compra (carga inicial) do carto dinheiro, deve-se utilizar a funo ScopeCartaoDinheiro(), como descrito abaixo. Como as outras transaes, o fluxo de processamento similar.

Prottipo LONG EXPORT ScopeCartaoDinheiro (WORD servico, char *Valor)

Parmetros

[in] WORD Servico Para efetuar a operao de Compra/Carga de carto dinheiro usar o servio 110 S_CARGA_CARTAO_DINHEIRO




Long servico = S_CARGA_CARTAO_DINHEIRO; // valor de 110 char valor[12 + 1]; ...

// obtm o valor da compra e armazena em valor // abre sesso ...

retorno = ScopeCartaoDinheiro(servio, valor); ...




Compra usando o carto dinheiro (debito) Para realizar a operao compra usando o carto dinheiro, isto , debitar o valor da compra do saldo disponvel, pode ser feito de duas formas: 1 Usar a funo ScopeCompraCartaoDebito(), como se fosse um carto de debito normal (vide item Compra com carto de debito). 2 Usar a funo ScopeCartaoDinheiro(), como descrito abaixo. Como as outras transaes, o fluxo de processamento similar.

Prottipo LONG EXPORT ScopeCartaoDinheiro (WORD servico, char *Valor)

Parmetros

[in] WORD Servico Para efetuar a operao de Compra/Carga de carto dinheiro usar o servio 98 S_COMPRA_CARTAO_DINHEIRO




Long servico = S_COMPRA_CARTAO_DINHEIRO; // valor de 98 char valor[12 + 1]; ...

// obtm o valor da compra e armazena em valor // abre sesso ...

retorno = ScopeCartaoDinheiro(servio, valor); ...



Consulta ao saldo de carto dinheiro A consulta ao saldo de carto dinheiro e a respectiva impresso de cupom deve ser feita usando a funo ScopeConsultaCartaoDinheiro(), como descrito abaixo.

Prottipo LONG EXPORT ScopeConsultaCartaoDinheiro (void)

Parmetros No h parmetros. Retorno Ver tabela de cdigo de retorno. Exemplo ...

// abre sesso


...

retorno = ScopeConsultaCartaoDinheiro(); ...



Estornos Tanto para realizar a operao de estorno de compra/carga do carto dinheiro como a compra usando o carto dinheiro (debito) deve se usar a funo genrica de estorno chamada ScopeCancelamento(). A documentao desta funo esta descrita no capitulo Estorno de transaes.

Funes de Consulta _____________________________________________________________________________________________________

Neste captulo falamos sobre as transaes de consultas que no se referem aos cartes.

Cheque Outra funcionalidade que o SCOPE dispe a consulta de cheques no Serasa ou na ACSP Associao Comercial de So Paulo. Nas consultas de cheques, via PDVs, as respostas so baseadas no nmero do documento (CPF/CGC), banco, nmero do cheque do comprador, valor e data de vencimento da compra. O nmero do cheque composto por seis caracteres numricos, por definio do Banco Central do Brasil com base na resoluo 885, de 22/

Manual Desenvolvedor Scope

Documents

Transcript of Manual Desenvolvedor Scope