Manual Desenvolvedor Scope

Soluo Completa de Pagamento Eletrnico
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
Apndice B includa a certificao com a Visanet 4.1
1.4
21/06/2008
Paulo dos Santos
1.5
10/07/2008
Paulo dos Santos
Reviso do texto, incluso de informaes no fluxo de

recarga celular e PBM
Documentao de novos retornos
Reviso do texto de PBM e de reimpresso de
1.6
08/08/2008
comprovante, e acrscimo do texto para deixar

transao pendente e reimpresso on-line.
Alterao das funes de reimpresso e melhoria do
1.7
11/08/2008
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
1.11
14/08/2009
Paulo dos Santos
1.12
15/08/2009
Celso Hiroshi Nakata
1.13
05/09/2009
Celso Hiroshi Nakata
texto referente CDC.
Detalhamento do novo estilo versionamento para as

bibliotecas do SCOPE Client para Linux.
Detalhamento da nova funcionalidade disponvel na
recarga celular para a GWCel.
Atualizao das tabelas de Cdigos de Erros do
Scope, Cdigos de Bandeiras e Cdigos de Servios
Atualizao da tabela de Cdigos de Bandeiras
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
2
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 [<empresa><filial>] ....................................................................................................................... 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
3
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
4
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
5
Verificando no ambiente do PDV ............................................................................................................... 120

SCOPE Client para MS-Windows ........................................................................................................ 120
SCOPE Client para Linux ........................................................................................................................ 121
Apndice F - Glossrio .................................................................................................. 123
6
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
7
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
8
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.
9
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.
10
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
BYTE
WORD
Tamanho
1 byte
2 bytes
Descrio
Valor sem sinal de 0 a 255
Valor sem sinal de 0 a 65.535
11
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
EXPORT
CALLBACK
Descrio
Usada nos prottipos das funes que so exportadas
Funo cujo endereo de entrada fornecido a outras funes, de
modo que estas possam utilizar internamente da primeira
12
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 multiusurios, 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-<verso>-1.i386.rpm
onde: <verso> representa a verso e o release do SCOPE Client. Para a sua instalao execute
o comando:
$ rpm i itautec-scope-<verso>-1.i386.rpm
Este comando instalar as bibliotecas na pasta /usr/lib.
IMPORTANTE: para a execuo deste comando necessrio ter direitos do usurio root.
13
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.
14
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 [<empresa><filial>]
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
Name
Port
Significado
Valor
Endereo ou nome da mquina em que
I.P. ou nome da mquina do
est o ScopeSRV.
ScopeSRV
Porta de conexo do ScopeSRV.

Parmetro que decide se o SCOPE Client
AtualizaDataHora
dever alterar a data e a hora da mquina

para sincronizar com o ScopeSRV no
momento da conexo.
Controla o tamanho mximo de colunas
Valor numrico (o padro

2046).
N
se no deve sincronizar
(padro).
caso deseja-se que
sincronize.
N 40 colunas (padro)
das mensagens que o SCOPE Client

MsgOperReduzida
enviar para a aplicao para que esta

exiba no teclado do operador ou display
20 colunas
m 16 colunas
com esta finalidade.

ShowCupom
Configura a exibio do cupom na tela.
n No exibe
Utilizado apenas na interface HLAPI.
Configura o tempo, em segundos, de

TimeOutLogon
espera para a conexo do SCOPE Client

com o ScopeSRV.
Configura o tempo, em segundos, de
TimeOutAdm
espera da resposta da autorizadora em

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

HLAPI.
VersaoAutomacao
Verso da automao passada pela rea
Exibe (padro)
Valor numrico entre 10 e 60

(padro 10).
Valor numrico entre 15 e 180

(padro 30).
n No exibir
s
Exibir
Seqncia de caracteres no
15
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 ./)
Habilita o log do PIN-pad compartilhado.
n No habilita (padro)
Em MS-Windows, ser gerado no C:\, nos

demais sistemas, no diretrio corrente da
TracePin
aplicao, o arquivo TracePin.sc_. O

sistema de log circular, assim quando o
Habilita
tamanho desse arquivo for 1 MB, ele ser

renomeado para TracePin.bak e um novo
TracePin.sc_ ser criado.
Sesso [PPCOMP]
Aqui, configuram-se itens relacionados ao PIN-Pad compartilhado
Chave
Significado
Configura para no abrir o digitado se
NaoAbrirDigitado
cancelada a leitura do carto no PIN-Pad

compartilhado.
Valor
n
s
16
no abre digitao
(padro)
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
SerialNumPorts
Nmero de portas a ser configuradas.
SerialPortx
Valor
Dispositivo com novo direcionamento para

a porta (x-1).
Valor entre 1 e 6 (o padro

6)
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).
17
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
Localizao no editor do registro
scope.ini
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
18
[in]
[in]
[in]
String com quatro

dgitos
String com quatro
dgitos
String com trs
dgitos
Empresa Cdigo de identificao da empresa conforme

cadastrado no ScopeCNF
Filial
Cdigo de identificao da filial conforme cadastrado
no ScopeCNF
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
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.
19
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.
20
Prottipo
LONG EXPORT ScopeAbreSessaoTEF (void)
Parmetros
No h parmetro.
Retorno
Exemplo
...
// 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)
[out]
Ponteiro para
byte
Informa o SCOPE para confirmar ou

desfazer a(s) transao(s) da sesso de
TEF atual
Retorna se a(s) transao(s) da sesso
DesfezTEFAposQueda de TEF foram desfeitas aps uma queda
de energia.
Acao
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)
21
...
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
22
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;
23
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)
Parmetros
No h parmetro.
Retorno
Exemplo
...
// 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 <= 0xFC00) || (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
}
...
24
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
Descrio
identificao
Permite que a aplicao cancele a transao que est sendo executada no PINPad quando este esteja coletando algo. Por padro, a aplicao no tem
conhecimento do momento em que o SCOPE est coletando o carto, a senha
1
ou outra informao no PIN-Pad, pois ele retorna o estado indicando

processamento (65024), o qual no um estado de coleta, e, portanto,
inviabilizando
uso
da
funo
ScopeResumeParm()
para
possvel
cancelamento.
Habilitado este item, o SCOPE retornar o estado para obter os servios (64644)
2
durante o fluxo de TEF para que a aplicao de PDV possa obter os servios e
parmetros configurados no ScopeCNF.
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.
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.
PDVs com impressora com papel de carbono podem habilitar este item para no
16
imprimir a informao de 1
Via Cliente ou 2
Via Estabelecimento nos
respectivos cupons.
IMPORTANTE: este tipo de configurao s permitido quando a aplicao est utilizando

a interface coleta.
25
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
[in]
LONG
Param
Identifica o parmetro a ser configurado

conforme tabela acima
Informa se deve habilitar ou desabilitar o
item. Para habilitar a aplicao dever
passar o valor 1 e para desabilitar, o valor
0.
Retorno
Exemplo
...
// 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
26
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)
Parmetros
No h parmetro.
Retorno
Exemplo
...
// Conexo ao ScopeSRV bem sucedida
...
retorno = ScopeSetAplColeta();
27
...
Figura 5: fluxo de processamento de uma transao com a interface coleta.

28
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
29
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
[out] ptPARAM_COLETA lpParam
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.
Conjunto de dados para a coleta
detalhado acima
Retorno
Exemplo
...
// executa transao (crdito, dbito, etc.)
30
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
[in]
String
dados
[in]
WORD
dadosParam
[in]
eACAO_APL
Ao
Cdigo do estado, obtido pela funo

ScopeStatus(), para qual o dado foi coletado
Dado coletado pela aplicao
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)
Ao tomada pelo operador (ver Cdigos de Fluxo)
Retorno
Exemplo
...
// executa transao (crdito, dbito, etc.)
char *dados[128];
WORD modo_entrada;
...
// inicia iterao
cod_coleta = ScopeStatus();
if(cod_coleta != 0xFE00)
31
{
...
// 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().
32
Figura 6: fluxo de processamento de uma transao com a interface HLAPI.
33
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)
Retorno
Exemplo
...
// 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)
Parmetros
No h parmetro.
Retorno
Exemplo
...
// 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
34
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)
Parmetros
No h parmetro.
Retorno
Exemplo
...
// 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)
35
[in]
String
TxServico
Valor da taxa de servio
Retorno
Exemplo
...
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
[in]
[in]
String com o
mximo de 12
dgitos
String
Valor

(exemplo: R$ 123,00 = 12300)
TxServico
Retorno
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
...
// abre sesso
...
retorno = ScopeConsultaCredito(valor, taxa);
...
36
...
// fecha a sesso
...
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
Exemplo
...
// abre sesso
...
retorno = ScopeConsultaSaldoCredito();
...
...
// fecha a sesso
...
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
[in]
[in]
String com o
mximo de 12
dgitos
String
Valor

(exemplo: R$ 123,00 = 12300)
TxServico
Retorno
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
37
...
// abre sesso
...
retorno = ScopePreAutorizacaoCredito(valor, taxa);
...
...
// fecha a sesso
...
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
[in]
String com o
mximo de 12
dgitos
Valor

(exemplo: R$ 123,00 = 12300)
Retorno
Exemplo
...
char valor[12 + 1];
...
...
// abre sesso
...
retorno = ScopeCompraCartaoDebito(valor);
...
...
// fecha a sesso
...
38
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
[in]
[in]
String com o
mximo de 12
dgitos
String
Valor

(exemplo: R$ 123,00 = 12300)
TxServico
Retorno
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
...
// abre sesso
...
retorno = ScopeConsultaCDC(valor, taxa);
...
...
// fecha a sesso
...
LEMBRETE: a compra CDC efetuada no fluxo de dbito, ou seja, dever ser chamada a
funo ScopeCompraCartaoDebito() para a realizao dessa compra.
39
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, devese utilizar a funo ScopeCartaoDinheiro(), como descrito abaixo.
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
[in]
String com o
mximo de 12
dgitos
Valor

(exemplo: R$ 123,00 = 12300)
Retorno
Exemplo
...
Long servico = S_CARGA_CARTAO_DINHEIRO; // valor de 110
char valor[12 + 1];
...
// abre sesso
...
retorno = ScopeCartaoDinheiro(servio, valor);
...
...
// fecha a sesso
...
40
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.
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
[in]
String com o
mximo de 12
dgitos
Valor

(exemplo: R$ 123,00 = 12300)
Retorno
Exemplo
...
Long servico = S_COMPRA_CARTAO_DINHEIRO;
// valor de 98
char valor[12 + 1];

...
// abre sesso
...
retorno = ScopeCartaoDinheiro(servio, valor);
...
...
// fecha a sesso
...
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
Exemplo
...
// abre sesso
41
...
retorno = ScopeConsultaCartaoDinheiro();
...
...
// fecha a sesso
...
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/12/1983.
Consulta de cheques
A transao de consulta a cheque iniciada pela funo ScopeConsultaCheque(). O fluxo de
processamento similar s outras transaes.
Prottipo
LONG EXPORT ScopeConsultaCheque (char *Valor)
Parmetros
[in]
String com o
mximo de 12
dgitos
Valor

(exemplo: R$ 123,00 = 12300)
Retorno
Exemplo
...
char valor[12 + 1];
...
// obtm o valor do cheque e armazena em valor
// abre sesso
42
...
retorno = ScopeConsultaCheque(valor);
...
...
// fecha a sesso
...
AVS
Termo em ingls Adress Verification Service, tambm conhecido por outras autorizadoras como
VAS Verificao Automtica de Endereo, um servio de verificao de endereo do portador
do carto utilizado para comparar o endereo que o cliente forneceu com o que est cadastrado
junto com a administradora de carto. O AVS uma transao no financeira e no atrelada a
nenhuma transao de venda, isto , a consulta no garante que a pessoa que esteja realizando
a transao seja realmente o portador do carto.
CUIDADO: Este tipo de informao recebida pela consulta AVS tem o intuito apenas de
oferecer suporte para a deciso do estabelecimento comercial, quanto realizao ou no
da venda.
Consulta AVS
A funo ScopeConsultaAVS() aciona o SCOPE client para efetuar uma transao de consulta
AVS para confirmar os dados do endereo fornecido com o cadastrado na administradora.
Prottipo
LONG EXPORT ScopeConsultaAVS (void)
Parmetros
No h parmetros.
Retorno
Exemplo
...
// abre sesso
...
retorno = ScopeConsultaAVS();
...
...
// fecha a sesso
...
43
Recarga de celular
_____________________________________________________________________________________________________
Com o crescimento nmero de pessoas que utilizam celulares do tipo pr-pago, a necessidade de
disponibilizar pontos de recarga tem sido incentivada pelas operadoras de celulares. O SCOPE
contribui com este movimento provendo facilidades para esse tipo de servio.
Processando a recarga de celular

Apesar do processamento seguir de maneira similar s outras transaes, nesta modalidade
existem cdigos de coleta especficos. Durante a iterao do processamento da transao de
recarga de celular, a aplicao de PDV dever estar preparada para receber, da funo
ScopeStatus(), no caso de uso da interface Coleta, os dois cdigos de coleta abaixo, alm de
outros comuns a outras transaes:
Cdigo 64624 (0xFC70): neste momento, a aplicao dever recuperar do SCOPE a lista
de operadoras disponveis;
Cdigo 64558 (0xFC2E): este cdigo representa que a aplicao deve obter a lista de
valores disponveis de recarga.
No caso da interface HLAPI, antes do incio da transao de recarga (chamada funo

ScopeRecargaCelular()), a aplicao deve informar ao SCOPE que o processamento deve ser
suspenso (via ScopeSuspend()) no estado 187 (coleta a operadora). Quando a ScopeStatus()
retornar 65027 (existe transao suspensa), a aplicao deve receber a lista de operadoras
disponveis (via ScopeRecuperaOperadorasRecCel()), exibi-la ao usurio de alguma forma,
informar ao SCOPE um novo estado de suspenso, o 95 (coleta o valor de recarga de celular) e
dar continuidade ao processamento com a ScopeResume(). Posteriormente, a ScopeStatus() ir
retornar novamente o valor 65027 (existe transao suspensa), nesse contexto, indicando o
momento para a exibio dos valores de recarga disponveis. Tais valores sero obtidos pela
funo ScopeRecuperaValoresRecCel() e devero ser exibidos ao usurio pela aplicao. A
aplicao deve informar um novo estado de suspenso, 4 (imprime cupom) e
permitir a
continuidade do processamento com a ScopeResume().
Iniciando a transao de recarga

O incio desta transao dado pela chamada funo ScopeRecargaCelular(). Esta transao
como todas as outras, deve estar numa sesso de TEF (ver Sesso de transao).
Prottipo
LONG EXPORT ScopeRecargaCelular (void)
Parmetros
No h parmetros.
Retorno
Exemplo
...
// abre sesso
44
...
retorno = ScopeRecargaCelular();
...
...
// fecha a sesso
...
Obtendo operadoras disponveis

Recebendo o cdigo de coleta 64624 da funo ScopeStatus(), a aplicao dever obter as
operadoras disponveis, atravs da funo ScopeRecuperaOperadorasRecCel(). A lista
disponibilizada no segundo parmetro da funo contm o formato abaixo:
Posio
Formato
Descrio
01 at 02
Short
Quantidade de operadoras disponveis
03
Byte
Cdigo da operadora 1
04 at 25
String
Nome da operadora 1
26
Byte
Cdigo da operadora 2
27 at 48
String
Nome da operadora 2
Pos n = (n 1) 23 + 3
Byte
Cdigo da operadora n
(Posn + 1) at (Posn + 21)
String
Nome da operadora n
Exemplo: Quando houver 5 operadoras, as posies dos cdigos de cada operadora no buffer
sero:
Pos1 = (1 1) 23 + 3 = 3
Pos 2 = (2 1) 23 + 3 = 26
Pos3 = (3 1) 23 + 3 = 49
Pos 4 = (4 1) 23 + 3 = 72
Pos5 = (5 1) 23 + 3 = 95
Portanto, codificando de maneira simples em linguagem C, temos:
...
short *qtd_op;
char buffer[2002];
int operadora, ind_op;
long retorno;
...
retorno = ScopeRecuperaOperadorasRecCel (2, buffer, sizeof(buffer));
if(retorno == 0)
{
qtd_op = (short *) buffer;
for(operadora = 0; operadora < *qtd_op; operadora++)
{
45
ind_op = (operadora 1) * 23 + 3;
printf(\nCod %d
- Oper. %.21s,
(int) buffer[ind_op], buffer[ind_op+1]);
}
}
...
No entanto, de outra maneira mais iterativa e sem utilizar frmulas matemticas, podemos obter a
lista de operadoras como segue no exemplo abaixo:
...
short *qtd_op;
char buffer[2002];
int operadora, ind_op;
long retorno;
...
retorno = ScopeRecuperaOperadorasRecCel (2, buffer, sizeof(buffer));
if(retorno == 0)
{
qtd_op = (short *) buffer;
ind_op = 3;
for(operadora = 0; operadora < *qtd_op; operadora++)
{
printf(\nCod %d
- Oper. %.21s,
ind_op = ind_op + 23;

}
}
...
Estruturas de apoio
Aplicaes escritas em linguagem C podem usufruir de estruturas definidas no arquivo de
cabealho ScopeApi.h. O buffer recebido contendo a lista de operadoras resume-se na
estrutura abaixo:
typedef struct
{
short NumOperCel;
char
OperCel[2000];
} stREC_CEL_OPERADORAS, *ptREC_CEL_OPERADORAS;
, onde:
NumOperCel: nmero de operadoras de celular retornadas nesta transao;
OperCel: tabela de operadoras.
No entanto, o membro OperCel da estrutura acima contem a lista desejada e para

percorr-la pode-se utilizar a estrutura:
typedef struct
{
char CodOperCel;
46
char NomeOperCel[TAM_NOME_OP];
} stREC_CEL_ID_OPERADORA, *ptREC_CEL_ID_OPERADORA;
, onde:
CodOperCel: cdigo, da operadora, que ser escolhido pelo operador e devolvido

para o SCOPE;
NomeOperCel: nome da operadora representada por uma string.
Reescrevendo o cdigo exemplificado acima, obtemos:

int i;
stREC_CEL_OPERADORAS ListaOper;
stREC_CEL_ID_OPERADORA Oper;
long retorno;
...
retorno = ScopeRecuperaOperadorasRecCel(2,
(char *) &ListaOper, sizeof(ListaOper));
if(retorno == 0)
{
printf("\n\n LISTA DE OPERADORAS:\n\n");
/* Exibe as operadoras */
for(i = 0; I < (int)ListaOper.NumOperCel; i++)
{
// inicializa estruturas
memcpy(&Oper, &ListaOper.OperCel[i*sizeof(stREC_CEL_ID_OPERADORA)],
sizeof(stREC_CEL_ID_OPERADORA));
printf(\nCod %d
- Oper. %.21s,
}
}
Prottipo
LONG
EXPORT
ScopeRecuperaOperadorasRecCel
(BYTE
TpTab,
char
*buffer,
WORD TamBuf)
Parmetros
[in]
BYTE
TpTab
[out] String
Buffer
[in]
TamBuf
WORD
Informa o formato da tabela que a

aplicao deseja receber a lista de
operadoras. Aceita apenas o valor 2.
Buffer com a lista de operadoras.
Tamanho do buffer anterior, previamente
alocado, que deve ser maior ou igual a
2002 bytes.
Retorno
Exemplo
...
stREC_CEL_OPERADORAS ListaOper;
...
// obtm status do SCOPE
47
switch(status_scope)
{
...
case 64624:
ScopeRecuperaOperadorasRecCel(2, (char *)&ListaOper, sizeof(buffer));
ApresentaListaAoOperador(ListaOper);
// Obtm cdigo da operadora escolhido pelo cliente
break;
...
}
// passa a informao coletada para o SCOPE
...
Obtendo valores de recarga

Com o status do SCOPE igual a 64558, a aplicao dever informar as opes de recarga
disponveis
para
operadora
escolhida,
que
so
disponibilizadas
pela
funo
ScopeRecuperaValoresRecCel() de maneira similar funo que recupera as operadoras. A

estrutura do buffer recebido a seguinte:
1 byte
Um caractere representando o tipo de valor.
Valor (ASCII)
Significado
Valor varivel
Valor Fixo
Todos valores
12 bytes
Valor mnimo representado por string
12 bytes
Valor mximo representado por string
1 byte
Total de valores fixos da tabela

12 bytes
Valor fixo 1 da recarga, com 2 casas decimais
12 bytes
Bnus da recarga para o valor 1
12 bytes
Custo da recarga para o valor 1
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
48
41 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
Mensagem promocional a ser exibida com os valores
Estruturas de apoio
Definidas no arquivo de cabealho ScopeApi.h, esto as estruturas abaixo, que so
utilizadas para o recebimento do buffer de valores. A primeira delas:
typedef struct
{
char TipoValor;
char ValorMinimo[12];
char ValorMaximo[12];
char Totvalor;
stREC_CEL_VALOR TabValores[10];
char MsgPromocional[41];
} stREC_CEL_VALORES, *ptREC_CEL_VALORES;
, onde:
TipoValor: caractere que representa o tipo de valor permitido para a operadora e

que define quais valores sero exibidos. O domnio de valores para este campo :
o
V valor varivel entre o que est indicado no campo ValorMinimo e

ValorMaximo desta mesma estrutura
F valores fixos que esto no campo TabValores
T disponvel tanto o valor varivel quanto o fixo
ValorMinimo: este campo uma cadeia com 12 caracteres numricos que

representam o valor mnimo do intervalo de valores variveis com a vrgula implcita
(exemplo: caso o dado neste campo seja 000000001000, ento ele est
representando o valor R$10,00);
49
ValorMaximo: este campo uma cadeia com 12 caracteres numricos que

representam o valor mximo do intervalo de valores variveis com a vrgula
implcita (exemplo: caso o dado neste campo seja 000000001500, ento ele est
Totvalor: este campo binrio e indica a quantidade de valores fixos que esto no
campo TabValores;
TabValores: cadeia de registros, descrita abaixo, com todos os valores fixos

disponveis para a recarga desta transao que, embora seja fixo com 10 registros,
deve-se sempre observar a quantidade vlida representada pelo campo anterior;
MsgPromocional: string contendo uma mensagem promocional a ser exibida com

os valores de recarga.
CUIDADO: como a estrutura de valores sempre fixa com dez registros de valores e por
esses vrios valores do domnio do campo de tipo de valor, extremamente recomendvel
que a aplicao sempre verifique a quantidade de valores fixos, informada pelo campo
TotValor, disponveis.
Como se pode notar pela definio, o campo TabValores do tipo da estrutura

stREC_CEL_VALOR, descrita abaixo.
typedef struct
{
char Valor[12];
char Bonus[12];
char Custo[12];
} stREC_CEL_VALOR, *ptREC_CEL_VALOR;
Valor: este campo uma cadeia com 12 caracteres numricos que representam um
valor fixo, para escolha do cliente, com a vrgula implcita (exemplo: caso o dado
neste campo seja 000000001500, ento ele est representando o valor R$15,00);
Bnus: este campo uma cadeia com 12 caracteres numricos que representam o
bnus que o cliente ganha ao escolher o valor fixo deste registro com a vrgula
implcita (exemplo: caso o dado neste campo seja 000000010000, ento ele est
Custo: este campo uma cadeia com 12 caracteres numricos que representam o
custo da recarga ao escolher o valor fixo deste registro com a vrgula implcita
(exemplo: caso o dado neste campo seja 000000005000, ento ele est
typedef struct
{
char TipoValor;
50
char ValorMinimo[10];
char ValorMaximo[10];
char Totvalor;
stREC_CEL_VALOR TabValores[10];
char MsgPromocional[41];
char TotFaixaValores;
stREC_CEL_FAIXA_VALORES TabFaixaValores[10];
} stREC_CEL_VALORES_MODELO_3, *ptREC_CEL_VALORES_MODELO_3;
Para a rede GWCel existe uma funcionalidade, a qual permite que o cliente faa uma
recarga, utilizando uma faixa de valores, ao invs de valores pr-definidos. A maioria dos
membros dessa estrutura so os mesmos da stREC_CEL_VALORES, sendo adicionais:
TotFaixaValores: indica a quantidade total de faixas de valores disponveis;
TabFaixaValores: cadeia de registros, descrita abaixo, com todos as faixas de

valores disponveis para a recarga desta transao que, embora seja fixo com 10
registros, deve-se sempre observar a quantidade vlida representada pelo campo
anterior;
typedef struct
{
char ValorMin[10];
char ValorMax[10];
} stREC_CEL_FAIXA_VALORES, *ptREC_CEL_FAIXA_VALORES;
ValorMin: indica o valor mnimo aceitvel para a recarga;
ValorMax: indica o valor mximo aceitvel para a recarga.
Prottipo
LONG EXPORT ScopeRecuperaValoresRecCel (BYTE TpTab, char *buffer, WORD
TamBuf)
Parmetros
[in]
BYTE
TpTab
[out] String
Buffer
[in]
TamBuf
WORD
Informa o formato da tabela que a

aplicao deseja receber a lista de
operadoras. Aceita apenas o valor 2.
Buffer com a lista de valores de recarga
disponveis.
Tamanho do array buffer (segundo
parmetro) alocado que deve ser igual a
427 bytes.
Retorno
Exemplo
...
stREC_CEL_VALORES tabVal;
51
...
{
...
case 64558:
ScopeRecuperaValoresRecCel(2, (char *)&tabVal, sizeof(buffer));
ApresentaValoresAoOperador(tabVal);
// Obtm o valor de recarga escolhido pelo cliente
break;
...
}
// passa a informao coletada para o SCOPE
...
CUIDADO: os campos de valores representados nas estruturas de recarga no

so strings terminadas com o caractere nulo, mas so cadeias de caracteres de
tamanho fixo igual a 12 com zeros esquerda.
Estorno de transaes
_____________________________________________________________________________________________________
Introduo
O estorno uma transao de anulao de outra transao que j est confirmada no lado da
autorizadora e pode ser realizada quando ocorrerem erros na digitao (valor, data de
agendamento das parcelas, numero de parcelas, etc.) ou desistncia da compra por parte do
cliente. O SCOPE disponibiliza uma nica funo para o estorno das diversas transaes:
ScopeCancelamento(). No entanto, nem todas as transaes so estornveis, como por exemplo,
transaes de consultas. Na tentativa de estorno destas transaes, o SCOPE retornar atravs
da funo ScopeStatus() o cdigo de erro 65286, informando que a transao no cancelvel.
O estorno difere do desfazimento no sentido em que o primeiro uma nova transao isolada,
enquanto o segundo a finalizao de uma transao. Tanto, que existe o desfazimento do
estorno, que no permite que ocorra o cancelamento da transao original, mantendo-a com o
status de confirmada.
CUIDADO: no possvel o cancelamento de uma transao sem que esta j tenha sido
confirmada. Em outras palavras, no SCOPE no se pode cancelar uma transao que ainda
est numa sesso de TEF em aberto. Para este, cancelamento a transao deve ser
52
desfeita (ver Encerrando a sesso).
Estornando a transao
Para a realizao do estorno, necessrio informar ao SCOPE os dados da transao original, e,
em muitas vezes, o nmero do controle gerado pelo prprio SCOPE na transao.
Prottipo
LONG EXPORT ScopeCancelamento (char *Valor, char *TxServico)
Parmetros
[in]
[in]
String com o
mximo de 12
dgitos
String
Valor

(exemplo: R$ 123,00 = 12300)
TxServico
Retorno
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
...
// abre sesso
...
retorno = ScopeCancelamento(valor, taxa);
...
// processa o cancelamento
...
// fecha a sesso
...
Comprovantes
_____________________________________________________________________________________________________
Comprovantes de transaes
Qualquer transao realizada com sucesso e com algum tipo de comprovante para a impresso
deve ser obtido pela funo ScopeGetCupomEx().
IMPORTANTE: quando a aplicao utiliza a interface HLAPI, ela sempre deve chamar a
funo ScopeSuspend() passando como parmetro o valor inteiro 4 (ver Suspendendo a
transao).
53
Obtendo os cupons de TEF

Durante o processamento de uma transao, a aplicao dever esperar pelos cdigos de coleta:
64582 (0xFC46): imprimir cupom parcial;
64514 (0xFC02): imprimir cupom;
64539 (0xFC1B): imprimir consulta;
64546 (0xFC22): imprime nota promissria;
64593 (0xFC51): imprime cupom promocional.
Neste momento, a aplicao chamar a funo para obter os cupons da transao.
CUIDADO: quando a aplicao realizar uma consulta CDC no meio de uma TEF de dbito,
a aplicao no dever enviar o cupom da consulta para a impressora, mas apenas exib-lo
na tela. No entanto, quando for apenas uma transao de consulta, isto , foi chamada
apenas uma funo do tipo ScopeConulta<transao>(), o comprovante recebido deve ser
enviado para a impressora.
Prottipo
LONG EXPORT ScopeGetCupomEx(WORD CabecLen, char *Cabec,
WORD CupomClienteLen, char *CupomCliente,
WORD CupomLojaLen, char *CupomLoja,
WORD CupomReduzLen, char *CupomReduz,
BYTE *NroLinhasReduz)
Parmetros
[in]
WORD
CabecLen
[out] String
Cabec
[in]
CupomClienteLen
WORD
[out] String
CupomCliente
[in]
CupomLojaLen
WORD
[out] String
CupomLoja
[in]
CupomReduzLen
WORD
[out] String
CupomReduz
[out] WORD
NroLinhasReduz
Tamanho reservado pela aplicao de

PDV para receber o cabealho do cupom
Ponteiro para rea onde ser recebido o
cabealho do cupom
Tamanho reservado pela aplicao de
PDV para receber a via do cupom Cliente
Ponteiro para rea onde ser recebida a
via do cliente que sempre estar
disponvel para a aplicao de PDV
Tamanho reservado pela aplicao para
receber a via da loja
via da loja que sempre estar disponvel
para a aplicao
Tamanho reservado pelo aplicativo para
receber o cupom reduzido
via cupom reduzido que poder substituir a
via do cliente e que em alguns casos, esta
via pode no estar disponvel para a
aplicao
Nmero de linhas que tem o cupom
reduzido. Se o valor for zero, no h
cupom reduzido disponvel
Retorno
54
Exemplo
...
BYTE NroLnhReduzido = 0;
char Cabec[1024],
CpCliente[2048],
CpLoja[2048],
CpReduzido[2048];
LONG retorno;
...
{
...
case 64582:
case 64514:
case 64539:
case 64546:
case 64593:
memset(Cabec, 0, sizeof(Cabec));
memset(CpCliente, 0, sizeof(CpCliente));
memset(CpLoja, 0, sizeof(CpLoja));
memset(CpReduzido, 0, sizeof(CpReduzido));
retorno = ScopeGetCupomEx(sizeof(Cabec), Cabec,
sizeof(CpCliente), CpCliente,
sizeof(CpLoja), CpLoja,
sizeof(CpReduzido), CpReduzido,
&NroLnhReduzido);
if (RC == RCS_SUCESSO)
{
ImprimeCupomTEF("CABECALHO", Cabec);
ImprimeCupomTEF("CUPOM DO CLIENTE", CpCliente);
ImprimeCupomTEF("CUPOM DA LOJA", CpLoja);
if (NroLnhReduzido > 0)
ImprimeCupomTEF("CUPOM REDUZIDO", CpReduzido);
}
break;
...
}
...
Reimpresso de comprovante
Conforme necessidade, o operador pode solicitar uma nova cpia do comprovante da ltima
transao realizada ou alguma especfica anterior a ltima, desde que tenha sido aprovada e se
encontre no SCOPE. So duas as modalidades de reimpresso: on-line e off-line. Essa
55
necessidade pode ter sido ocasionada por algum problema com a impresso original (cupom
ilegvel, papel enroscado na impressora, etc.).
As duas modalidades de reimpresso do comprovante uma transao e como tal, dever ser
tratada numa sesso de TEF, preferencialmente, sendo a nica da sesso.
Solicitando o comprovante off-line

Para toda e qualquer rede, o SCOPE permite reimprimir apenas o ltimo comprovante realizado
num PDV. Exclusivamente para a especificao da Visanet 4.1 possvel reimprimir cupons
antigos, exceto o reduzido, desde que estes estejam na base de dados do SCOPE. Esta
reimpresso atua apenas entre o SCOPE Client e o SCOPE Server e no vai para a autorizadora.
Prottipo
LONG EXPORT ScopeReimpressaoOffLine (void)
Parmetros
No h parmetros.
Retorno
Exemplo
...
// abre sesso
...
retorno = ScopeReimpressaoOffLine ();
...
...
// fecha a sesso
...
IMPORTANTE: na reimpresso no h cupom reduzido.
IMPORTANTE:
funo
ScopeReimpressaoOffLine()
ScopeReimpressaoComprovante(). No entanto,
substitui
esta ltima ainda
anterior
mantida por
compatibilidade.
Solicitando o comprovante on-line

Utilizada nos casos em que a rede autorizadora ou o correspondente bancrio oferece a
transao (on-line) de reimpresso do comprovante do pagamento de conta. Para TEF de crdito
e dbito, apenas para a rede Redecard este tipo de modalidade de reimpresso est disponvel.
Prottipo
LONG EXPORT ScopeReimpressaoOnLine (WORD CodBandeira)
56
Parmetros
[in]
WORD
CodBandeira
Cdigo da bandeira do carto (ver Cdigo

das bandeiras)
Retorno
Exemplo
...
WORD CodBandeira;
// abre sesso
...
// Obtm a bandeira do carto
...
retorno = ScopeReimpressaoOnLine(CodBandeira);
...
...
// fecha a sesso
...
IMPORTANTE: para a certificao da Visanet 4.1 esta funo no necessria estar

implementada.
IMPORTANTE:
funo
ScopeReimpressaoOnLine()
substitui
anterior
ScopeReimpressaoComprovantePagamento(). No entanto, esta ltima ainda mantida por

compatibilidade.
Imprimindo o comprovante correto

Como acontece em qualquer outra transao, na reimpresso de comprovante, os cupons so
recebidos pela funo de cupons (ver Comprovantes de transaes), a qual retorna todos os
cupons. Entretanto, devido exigncia da Visanet, a aplicao dever imprimir apenas o cupom
solicitado pelo operador. Para isso, a aplicao dever consultar no SCOPE qual o cupom que
dever ser impresso, com a ajuda da funo ScopeObtemTipoViaReimpressao().
A necessidade desta funo surgiu por causa da interface HLAPI, porque o SCOPE coletava do
operador qual a via que deveria ser impressa, mas a aplicao, que envia os comprovantes para
a impressora, no sabia dessa escolha.
Prottipo
LONG EXPORT ScopeObtemTipoViaReimpressao (BYTE *EhReimpre, BYTE *Via)
Parmetros
[out] BYTE
EhReimpre
[out] BYTE
Via
Informa se uma transao de

reimpresso (valor = 1) ou qualquer outra
transao (valor = 0)
Caso seja uma transao de reimpresso,
informa qual a via a ser impressa:
- 0: todas as vias
- 1: apenas a via da loja
57
2: apenas a via do cliente
Retorno
Exemplo
...
BYTE NroLnhReduzido = 0,
EhReimpressao,
ViaReimpressao;
char Cabec[1024],
CpCliente[2048],
CpLoja[2048],
CpReduzido[2048];
LONG retorno;
...
{
...
case 64582:
case 64514:
case 64539:
case 64546:
case 64593:
memset(Cabec, 0, sizeof(Cabec));
memset(CpCliente, 0, sizeof(CpCliente));
memset(CpLoja, 0, sizeof(CpLoja));
memset(CpReduzido, 0, sizeof(CpReduzido));
retorno = ScopeGetCupomEx(sizeof(Cabec), Cabec,
sizeof(CpCliente), CpCliente,
sizeof(CpLoja), CpLoja,
sizeof(CpReduzido), CpReduzido,
&NroLnhReduzido);
if (retorno == RCS_SUCESSO)
{
retorno = ScopeObtemTipoViaReimpressao( &EhReimpressao,
&ViaReimpressao );
if(EhReimpressao == 0)
{
ImprimeCupomTEF("CABECALHO", Cabec);
if (NroLnhReduzido > 0)
ImprimeCupomTEF("CUPOM REDUZIDO", CpReduzido);
}
else
58
{
switch(ViaReimpressao)
{
case 0:
break;
case 1:
break;
case 2:
break;
}
}
}
break;
...
}
...
PBM - Medicamentos
_____________________________________________________________________________________________________
Aqui trataremos do grupo de funes que atendem a funcionalidade de PBM.
Consultando medicamento
A funo ScopeConsultaMedicamento() aciona uma transao no SCOPE para obter uma lista de
medicamentos relacionados a uma autorizao, assim como a quantidade autorizada, o PMC
(Preo Mximo para o Consumidor) e o preo e-Pharma para cada um destes.
O processamento segue a linha de uma transao qualquer de TEF, em que a aplicao deve
processar atravs das chamadas funo de consulta status (ver Status de transao) e coleta
de dados. O PDV deve esperar pelo estado 64580 para chamar a funo especfica e obter a lista
de medicamentos (ver Lista de medicamentos e Lista de medicamentos com CRM).
Prottipo
LONG EXPORT ScopeConsultaMedicamento(BYTE TipoConvenio, BYTE CodigoRede)
Parmetros
[in]
BYTE
TipoConvenio
Tipo do convnio. (0=PBM, 1=Empresa)
[in]
BYTE
CodigoRede
Cdigo da rede (ver Convnios)
Retorno
Exemplo
...
BYTE
TipoConvenio, CodigoRede;
59
...
// abre sesso
...
// coleta o tipo do convnio, o cdigo da rede
...
retorno = ScopeConsultaMedicamento (TipoConvenio, CodigoRede);
...
...
// fecha a sesso
...
Nesse tipo de transao, o SCOPE no possui controle do valor de venda a ser registrado.
Portanto, ao receber o cdigo 64579 da funo de status, a aplicao deve atualizar o valor (ver
ScopeAtualizaValor), informando assim o valor da venda.
Exemplo
char VlOperac [12+1];
...
{
...
Case 64579:
RecebeValorDoOperador (&VlOperac);
iRet = ScopeAtualizaValor (VlOperac);
if (iRet != RCS_SUCESSO)
// Tratar erro
break;
...
Compra de medicamento
Para
iniciar
uma
compra
de
medicamentos
PDM,
deve-se
chamar
funo
ScopeCompraMedicamento(). O comportamento se assemelha consulta de medicamento e

tambm pode retornar no fluxo de coleta o cdigo de coleta 64580 para obter a lista de
medicamentos.
Prottipo
LONG EXPORT ScopeCompraMedicamento(BYTE TipoConvenio,
BYTE CodigoRede,
char *NumCpFiscal)
Parmetros
[in]
BYTE
TipoConvenio
Tipo do convnio. (0=PBM, 1=Empresa)
[in]
BYTE
CodigoRede
Cdigo da rede (ver Convnios)
NumCpFiscal
Nmero do cupom fiscal para o PDV
[out] String
Retorno
60
Exemplo
...
BYTE
TipoConvenio, CodigoRede;
char
*NumCpFiscal;
...
// abre sesso
...
// coleta o tipo do convnio, o cdigo da rede e o nmero do cupom fiscal
...
retorno = ScopeCompraMedicamento (TipoConvenio, CodigoRede, NumCpFiscal);
...
...
// fecha a sesso
...
Lista de medicamentos
Num fluxo de compra ou consulta de medicamento, recebendo o cdigo de coleta 64580 (ver
Status de transao), a aplicao dever obter a lista de medicamentos disponveis, atravs das
funes ScopeObtemMedicamentos() ou ScopeObtemMedicamentosComCRM(), que ser tratada
logo abaixo. O formato da lista obtido pela funo ScopeObtemMedicamentos() encontra se na
tabela abaixo.
Posio
Formato
Descrio
01 a 13
String
Cdigo EAN do medicamento.
14 a 15
String
Quantidade autorizada do produto.
16 a 22
String
Preo mximo ao consumidor.
23 a 29
String
Preo de venda.
30 a 36
String
Preo de fbrica.
37 a 43
String
Preo de aquisio.
44 a 50
String
Preo de repasse.
51
Byte
52 a 53
String
Reservado para uso futuro.

Motivo da rejeio.
Prottipo
LONG EXPORT ScopeObtemMedicamentos(BYTE *Qtd,
char *ListaMedicamentos,
WORD TamLista)
Parmetros
[out] BYTE
Qtd
[out] String
ListaMedicamentos
[in]
TamLista
WORD
Retorna a quantidade de medicamentos

consultados ou comprados
Retorna os medicamentos consultados ou
comprados
Tamanho, em bytes, do campo
ListaMedicamentos
61
Retorno
Exemplo
BYTE bQtdVias = 0;
LONG lRet;
stREGISTRO_MEDICAMENTO lstMedsCRM [38] = {0};
lRet = ScopeObtemMedicamentos
( &bQtdVias, (char *) &lstMedsCRM, sizeof (lstMedsCRM) );
if (lRet == RCS_SUCESSO)
{
/* Sucesso no recebimento dos medicamentos,
os membros das estruturas estaro preenchidos */
}
else
// Erro ...
Lista de medicamentos com CRM

A funo ScopeObtemMedicamentosComCRM() recupera a lista dos medicamentos consultados
ou comprados com o CRM do mdico. Esta funo no suporta as bandeiras Novartis e FlexMed
e seu formato obedece definio da tabela abaixo.
Posio
Formato
Descrio
Dados do medicamento, obedecendo a definio da
01 a 53
String
tabela
retornada
para
funo
ScopeObtemMedicamentos().
54 a 62
String
Nmero do CRM.
Prottipo
LONG EXPORT ScopeObtemMedicamentosComCRM(BYTE *Qtd,
BYTE *TipoConv,
char *ListaMedicamentos,
WORD TamLista)
Parmetros
[out] BYTE
Qtd
[out] BYTE
TipoConv
[out] String
ListaMedicamentos
Retorna a quantidade de medicamentos

consultados ou comprados
Retorna o tipo de convnio:
0: Pagamento vista;
1: Pagamento a prazo;
2: Empresa Fechada;
3: Empresa Aberta.
Retorna os medicamentos consultados ou
comprados
62
[in]
WORD
TamLista
Tamanho, em bytes, do campo

ListaMedicamentos
Retorno
63
Funes de PIN-Pad
_____________________________________________________________________________________________________
Esta seo documenta as funes de acesso ao PIN-Pad utilizando a biblioteca compartilhada.

Estas funes seguem o formato ScopePPFuncao(). Utilize o apndice B, C e a tabela de cdigo
de retorno como complemento.
IMPORTANTE: A utilizao destas funes, com exceo das usadas para a exibio de
mensagens no visor, est condicionada configurao no ScopeCNF, onde a opo Uso
exclusivo do Scope deve estar desmarcada.
Comunicao com o PIN-Pad

Como em qualquer dispositivo, a comunicao com o PIN-Pad precisa ser iniciada e, aps o uso,
finalizada: ScopePPOpen() e ScopePPClose(). As funes aqui relacionadas devem sempre ser
chamadas quando a opo Uso exclusivo do Scope no estiver marcada.
Iniciando a comunicao
Antes do incio de qualquer transao, a aplicao deve abrir o PIN-Pad, ou seja, iniciar o canal
de comunicao com o PIN-Pad. A chamada bem sucedida desta funo pr-requisito para
todas as outras da interface com o PIN-Pad.
Prottipo
LONG EXPORT ScopePPOpen (WORD PortaSerial)
Parmetros
[in] WORD PortaSerial
Porta serial que se encontra conectado o PIN-Pad.
Retorno
Exemplo
...
WORD porta = 1;
LONG retorno = 0;
...
retorno = ScopePPOpen(porta);
...
Encerrando a comunicao
Uma vez que o PIN-Pad no ser mais utilizado, a aplicao pode encerrar a comunicao com o
PIN-Pad, deixando uma mensagem no visor (display) do PIN-Pad.
Prottipo
LONG EXPORT ScopePPClose (char* IdleMsg)
Parmetros
[in]
Mensagem de 32 caracteres (2 linhas x 16 colunas) a ser mantida

String IdleMsg
no display do PIN-Pad aps o fechamento
64
Retorno
Exemplo
...
LONG retorno = 0;
...
retorno = ScopePPClose(
Itautec S.A.
);
...
Mensagens no visor
Para personalizao da aplicao de frente de loja, a aplicao pode enviar mensagens para o
PIN-Pad, desde que o SCOPE Client no esteja processando alguma transao.
IMPORTANTE: Estas so as nicas funes que no dependem da configurao do
ScopeCNF quanto ao uso exclusivo do SCOPE.
Mensagens de tamanho padro

Devido diversidade de formatos de visor, por padro, todos os PIN-Pads devem prover um visor
com o mnimo de 2 linhas por 16 colunas para exibir mensagens. Para este formato padro existe
a funo ScopePPDisplay().
Prottipo
LONG EXPORT ScopePPDisplay (char* Msg)
Parmetros
[in]
Mensagem de 32 caracteres (2 linhas x 16 colunas) a ser apresentada

String Msg
no display do PIN-Pad.
Retorno
Exemplo
...
LONG retorno = 0;
...
retorno = ScopePPDisplay(
Itautec S.A.
);
...
Mensagens maiores
Para aproveitar os recursos do visor de certos equipamentos, o SCOPE Client disponibiliza a
funo ScopePPDisplayEx() que recebe, junto com a mensagem, o tamanho desta. O parmetro
uma String que obedece ao formato abaixo:
Posio
Formato
001-003
N3
Descrio
Tamanho da mensagem a seguir (xxx).
Mensagem a ser apresentada, podendo conter caracteres de controle
004-???
AXXX
aceitos pelo display do PIN-Pad, tal como o CR (0Dh) para quebra de

linha
65
Prottipo
LONG EXPORT ScopePPDisplayEx (char* Msg)
Parmetros
[in]
String
Msg String ASCII de caracteres com o formato abaixo.
Retorno
Exemplo
...
char *mensagem = 065Enviando uma mensagem maior que a mensagem padro para
o PIN-Pad;
LONG retorno = 0;
...
retorno = ScopePPDisplayEx(mensagem);
...
Informaes obtidas do PIN-Pad

Internamente, os PIN-Pads com a biblioteca compartilhada, possuem informaes armazenadas
sobre a verso dos dados das redes autorizadoras e do prprio dispositivo. Quando o parque de
PDVs muito grande, o levantamento via aplicativo dos PIN-Pads uma maneira mais segura e
rpida que o mtodo manual.
Dados das redes autorizadoras

Para algumas autorizadoras, o PIN-Pad armazena tabelas com dados para utilizao nas leituras
de carto e senha. Com o tempo, estes dados podem ficar obsoletos, sendo necessrio o
armazenamento da verso destas tabelas nos PIN-Pads. Estas tabelas so retornadas pelo PINPad atravs da funo ScopePPGetInfo(), no formato abaixo.
Posio
Formato
Descrio
001-020
A20
Nome da rede adquirente (com espaos direita)
021-033
A13
Verso da aplicao da rede adquirente, no formato "VVV.VV AAMMDD"
034-040
A7
Informaes proprietrias da rede adquirente
041-042
A2
Tamanho em bytes dos dados a seguir ("00" a "yy")
043-???
Hxx(Byy)
Dados binrios de identificao do SAM, caso existente, no layout

exigido pela rede adquirente
Dados do dispositivo
O formato das informaes do PIN-Pad padro e segue o formato abaixo:
Posio
Formato
001-020
A20
021-040
A20
Descrio
Nome do fabricante do PIN-Pad
Modelo / verso do hardware, no formato "xxx...xxx;mmm", onde "xxxx"
o Nome do equipamento e "mmm" a capacidade de memria ("512KB",
66
"1MB", "2MB", ...)

041-060
A20
Verso do firmware (formato livre)
061-064
A4
Verso da especificao, no formato "V.VV" (neste caso, fixo em "1.05")
065-080
A16
081-100
A20
Verso da aplicao bsica, no formato "VVV.VV AAMMDD" (com 3

espaos direita)
Nmero de srie do PIN-Pad (com espaos direita)
Obtendo as informaes
A funo ScopePPGetInfo() retorna as informaes sobre o PIN-Pad e suas aplicaes, como
descrito acima. Caso alguma informao no exista ou no se aplique para o modelo de PIN-Pad,
ela dever ser fornecida em branco (espaos). Para decidir qual informao a aplicao quer
obter, o primeiro parmetro deve receber o valor correspondente:
valor 0: dados do PIN-Pad;
valor maior que 0: dependendo do valor, sero obtidas as informaes especficas das
aplicaes das autorizadoras.
Prottipo
LONG EXPORT ScopePPGetInfo (WORD IdSaida, WORD DadosLen, char* Dados)
Parmetros
WORD IdSaida
Informa a opo do formato dos dados de sada.
[in] WORD DadosLen Tamanho reservado pelo aplicativo para receber os dados.
Dados sobre o PIN-Pad. Utilize as tabelas descritas nas
[out] String Dados
sesses acima para a especificao do buffer retornado.
[in]
Retorno
Exemplo
...
char aux[255];
...
if (ScopePPGetInfo(0, (WORD) sizeof(aux), aux))
{
printf("Nome do fabricante do PIN-Pad..: [%20.20s]\n", &aux[00]);
printf("Modelo / versao do hardware....: [%20.20s]\n", &aux[20]);
printf("Versao do firmware.............: [%20.20s]\n", &aux[40]);
printf("Versao da especificacao........: [%4.4s]
\n", &aux[60]);
printf("Versao da aplicacao basica.....: [%16.16s]\n", &aux[64]);

printf("Numero de serie do PIN-Pad.....: [%20.20s]\n", &aux[80]);
}
...
Obtendo teclas do PIN-Pad

O par de funes ScopePPStartGetKey() / ScopePPGetKey() captura uma tecla pressionada no
PIN-Pad. Elas fazem parte do conjunto de funes no-blocantes. No-blocantes significa que a
67
chamada a essas funes so de retorno imediato, no interrompendo o fluxo de processamento

da aplicao.
Iniciando a leitura da tecla

A funo ScopePPStartGetKey() responsvel pelo incio do processo, colocando o PIN-Pad em
modo de espera por uma tecla no-numrica.
Prottipo
LONG EXPORT ScopePPStartGetKey (void)
Parmetros
No h parmetro.
Retorno
Obtendo a tecla
Aps ter posto o PIN-Pad em modo de captura de tecla, a funo ScopePPStartGetKey() dever
ser chamada continuamente at que o retorno dela seja diferente de 1 (PIN-Pad em
processamento). Esta funo finaliza o processo iniciado por ScopePPStartGetKey(). Enquanto o
retorno for igual a 1, o processo pode ser cancelado pelo checkout atravs da funo
ScopePPAbort().
Prottipo
LONG EXPORT ScopePPGetKey (void)
Parmetros
No h parmetro.
Retorno
0
Pressionada tecla de confirmao (OK ou ENTER)
4
Pressionada tecla de funo #1.
5
6
7
8
Pressionada tecla de limpeza (backspace).
13
Pressionada tecla de cancelamento.
Para os valores de retorno, veja a tabela de cdigo de retorno.
Exemplo
...
LONG retorno = 0;
...
if (ScopePPStartGetKey() == 0) // se OK
{
printf("\nAguardando tecla a ser pressionada no PIN-Pad...");
do
{
retorno = ScopePPGetKey();
}
while (retorno == 1);
// enquanto em processamento
switch (retorno)
{
case 0: printf("\nPressionada a tecla <OK>\n"); break;
68
case 4: printf("\nPressionada a tecla de funcao 1\n"); break;

case 8: printf("\nPressionada a tecla <Limpa>\n"); break;
case 13: printf("\nPressionada a tecla <Cancela>\n"); break;
default: printf("\nERRO: = %d\n", retorno); break;
}
}
...
Obtendo a senha aberta

O conjunto ScopePPStartGetPIN() / ScopePPGetPIN(), tambm no-blocantes, responsvel
pela captura da senha do usurio. A senha criptografada pelo PIN-Pad com a Master Key da
Itautec, e ser retornada sem criptografia pela funo ScopePPGetPIN(), em caso de sucesso. A
Master Key da Itautec est inserida, por padro, nos PIN-Pads homologados pela Visanet.
CUIDADO: A utilizao destas funes apenas para a captura de informaes que diz
respeito apenas ao prprio estabelecimento (exemplo: senha do supervisor da loja ou de
algum funcionrio) e no deve ser utilizado para captura de senha de cartes de banco dos
clientes.
Como a informao digitada no PIN-Pad aberta e possvel passar a mensagem a ser exibida
no display do PIN-Pad, a aplicao pode utiliz-las para coletar apenas informaes de domnio
da aplicao.
Iniciando o modo de leitura da senha aberta

A funo ScopePPStartGetPIN() responsvel pelo incio do processo, o qual complementado
pela funo ScopePPGetPIN().
Prottipo
LONG EXPORT ScopePPStartGetPIN (char *MsgDisplay)
Parmetros
[in] String MsgDisplay
Mensagem que ser exibida no PIN-Pad. Esta mensagem

deve ter no mximo 32 caracteres sendo duas linhas de 16
caracteres.
Retorno
Lendo a senha aberta

O processo de leitura da senha finalizado por ScopePPGetPIN(). Ela deve ser chamada
constantemente enquanto retornar o valor igual a 1 (PIN-Pad em processamento). Nessa
situao, o processo de captura de senha pode ser cancelado pelo checkout atravs da funo
ScopePPAbort().
Prottipo
LONG EXPORT ScopePPGetPIN (char* PIN)
69
Parmetros
[out] String
PIN
Senha capturada do usurio (j descriptografada), finalizada com

caractere nulo ('\0').
Retorno
Exemplo
...
char pin[40];
LONG retorno = 0;
...
if (ScopePPStartGetPIN("DIGITE A SENHA") == 0)
{
printf("\nAguardando digitao da senha...");
do
{
retorno = ScopePPGetPIN(pin);
} while (retorno == 1); // enquanto em processamento
if (retorno == 0)
// se OK
printf("\nA senha digitada [%s]\n", pin);

}
...
Obtendo a senha criptografada

O conjunto ScopePPStartGetPINEx()/ScopePPGetPINEx() responsvel pela captura da senha
do usurio. Estas funes so teis para clientes que possuem algum mdulo de descriptografia e
vai trafegar a informao, que sigilosa, por algum meio condutor.
A senha criptografada pelo PIN-Pad com a Master Key da Itautec e ser retornada com
criptografia pelo mtodo ScopePPGetPINEx(). A Master Key da Itautec est inserida, por padro,
nos PIN-Pads homologados pela Visanet.
Iniciando o modo de leitura da senha criptografada

A funo ScopePPStartGetPINEx() responsvel pelo incio do processo, o qual
complementado pela funo ScopePPGetPINEx().
Prottipo
LONG EXPORT ScopePPStartGetPINEx (char* msgDisplay, int mode, int mkey,
char* wkey, char* pan)
Parmetros
[in]
String
msgDisplay
[in]
int
mode
[in]
int
mkey
[in]
String
wkey
Mensagem que ser exibida no PIN-Pad. Esta mensagem

deve ter no mximo 32 caracteres sendo duas linhas de 16
caracteres.
Modo de criptografia. Previsto receber s o valor 0, que usa
a Master Key / Working Key (DES). Outros modos sero
utilizados no futuro.
ndice da MasterKey. Previsto receber apenas o valor 0.
Outros ndices para uso futuro.
A Working Key. Para o modo 0, devero ser enviados 8
bytes. Caso seja null, a funo no devolver a senha
70
[in]
String
pan
criptografada e o PAN no ser utilizado.

PAN do carto com tamanho entre 11 e 19 dgitos. Caso o
pan ou a wkey seja null, ser utilizado um valor fixo interno.
Retorno
Lendo a senha criptografada

A funo ScopePPGetPINEx() finaliza o processo iniciado por ScopePPStartGetPINEx(). Ela deve
ser chamada constantemente enquanto retornar valor igual a 1 (PIN-Pad em processamento).
Nessa situao, o processo de captura de senha pode ser cancelado atravs da funo
ScopePPAbort(). Em caso de sucesso, esta funo retorna o valor 0. Neste caso, a senha
criptografada de acordo com os parmetros usados na funo ScopePPStartGetPINEx()
retornada no parmetro PIN.
Prottipo
LONG EXPORT ScopePPGetPINEx (char *PIN)
Parmetros
[in]
Senha retornada pelo PIN-Pad, criptografada. Para senhas

criptografadas com os algoritmos DES/3DES, o PIN deve ter 16 bytes.
PIN
String
Para senhas criptografadas com o algoritmo DUKPT, PIN dever ter 36
bytes.
Retorno
Exemplo
...
char pin[40];
LONG retorno = 0;
...
if (ScopePPStartGetPINEx("DIGITE A SENHA", 0, 0, NULL, NULL) == 0)
{
printf("\nAguardando digitao da senha...");
do
{
retorno = ScopePPGetPINEx(pin);
if (retorno == 0)
// se OK
printf("\nA senha digitada [%s]\n", pin);

}
...
Lendo um carto
Como a leitura de senha e de teclas, a captura de carto tambm se d com o uso de funes
no-blocantes: ScopePPStartGetCard() / ScopePPGetCard().
71
Iniciando a leitura do carto

ScopePPStartGetCard() a funo que inicia o processo de leitura do carto, seja ele magntico
ou com chip.
Prottipo
LONG EXPORT ScopePPStartGetCard (WORD TipoApl, char* ValorInicial)
Parmetros
Identifica o tipo de aplicao desejada (crdito = 1, dbito = 2
e para qualquer aplicao = 99).
Valor inicial da transao. Podendo ser 0 (zero) caso este
ValorInicial dado no esteja disponvel. Este campo dever ter tamanho
mximo de 12 (doze) bytes, sendo 2 (duas) casas decimais.
[in]
WORD TipoApl
[in]
String
Retorno
Recuperando o carto
A funo ScopePPGetCard() finaliza o processo iniciado por ScopePPStartGetCard() e deve ser
chamada diversas vezes enquanto retornar 1 (PIN-Pad em processamento) ou 2 (exibir para o
cliente e para o operador a mensagem que o PIN-Pad passou). Enquanto nessa situao, o
processo pode ser cancelado pelo checkout atravs da funo ScopePPAbort().
Quando a funo ScopePPGetCard() retornar o cdigo igual a 2, o PIN-Pad colocou uma
mensagem no segundo parmetro da funo e a aplicao deve exibi-la na tela. Logo aps a
exibio da mensagem, a aplicao deve continuar chamando esta funo at que esta no
retorne mais um dos dois valores relacionados acima. Ao retornar o valor 0 (sucesso), o ltimo
parmetro da funo estar preenchido com os dados do carto que segue o seguinte formato:
Posio
Formato
Descrio
Tipo de carto lido:
001-002
N2
"00" Magntico
"01" - Moedeiro VisaCash sobre TIBC v1
"02" - Moedeiro VisaCash sobre TIBC v3
"03" EMV
"04" - Easy-Entry sobre TIBC v1
003-004
N2
Tamanho da trilha 1
005-080
A76
081-082
N2
Tamanho da trilha 2
083-119
A37
Trilha 2 (sem as sentinelas), alinhada esquerda com espaos direita.
120-121
N2
Tamanho do PAN
122-139
A19
PAN, alinhado esquerda com espaos direita
140-166
A26
Nome do proprietrio do carto, com espaos direita
Trilha 1 (sem as sentinelas e com o byte de formato - primeiro caractere

alfanumrico), alinhada esquerda com espaos direita.
72
Prottipo
LONG EXPORT ScopePPGetCard (WORD Id, char* MsgNotify, WORD Len, char*
Dados)
Parmetros
Informa a opo do formato dos dados de sada. Inicialmente
fixo com 0 (zero).
Mensagem de 32 caracteres a ser apresentada no
MsgNotify
String
"checkout" caso a funo retorne PP_NOTIFY.
Len
WORD
Tamanho do buffer alocado para os dados.
Dados sobre o carto finalizado. Consulte a tabela abaixo
String Dados
para a especificao do formato.
WORD Id
[in]
[in]
[in]
[out]
Retorno
Exemplo
...
char cartao [256];
char mensagem [256];
LONG retorno = 0;
...
if (ScopePPStartGetCard(99, "000") == 0)
{
printf("\nAguardando inserir ou passar o cartao...");
do
{
retorno = ScopePPGetCard(0, mensagem, sizeof(cartao), cartao);
if (retorno == 2)
printf("\nMensagem do PIN-Pad\n[%s]\n", mensagem);
if (retorno == 0)
// se OK
printf("\nOs dados do carto so [%s]\n", cartao);

}
...
Abortando o processamento (ScopePPAbort)

Esta funo finaliza um processo em andamento, iniciado por uma funo do tipo no-blocante
que seguem o padro ScopePPStartFunc(). Ela deve ser chamada caso o operador do checkout
decida abortar a operao enquanto a funo complementar ScopePPFunc() estiver retornando o
valor 1 (PIN-Pad em processamento).
Prottipo
LONG EXPORT ScopePPAbort (void)
Parmetros
No h parmetro.
Retorno
73
Exemplo
...
char cartao [256];
LONG retorno = 0;
...
if (ScopePPStartGetCard(99, "000") == 0)
{
do
{
if (retorno == 2)
if (_kbhit())
{
// se operador pressionou tecla do teclado
// cancela o processamento do cartao

ScopePPAbort();
retorno = 13;
}
} while (retorno == 1 || retorno == 2); // enquanto em processamento ou
mensagem
if (retorno == 0)
// se OK

}
...
Mensagens de erro (ScopePPMsgErro)

Esta funo retorna a descrio referente ao cdigo de erro informado retornado pelas funes de
acesso ao PIN-Pad.
Prottipo
LONG EXPORT ScopePPMsgErro (LONG RC, char *MsgErro)
Parmetros
[in]
[in]
WORD RC
Cdigo do erro.
String MsgErro Mensagem referente ao cdigo de erro informado.
Retorno
Exemplo
...
char cartao [256];
LONG retorno = 0;
...
retorno = ScopePPStartGetCard(99, "000");
74
if (retorno == 0)
{
do
{
if (retorno == 2)
if (_kbhit())
{
// se operador pressionou tecla do teclado
// cancela o processamento do cartao

ScopePPAbort();
retorno = 13;
}
} while (retorno == 1 || retorno == 2); // enquanto em processamento
// ou mensagem
}
...
if (retorno == 0)
// se OK

else
{
ScopePPMsgErro (retorno, mensagem);
printf("\n[%s]\n", mensagem);
}
...
Totalizao de TEF
_____________________________________________________________________________________________________
Esta sesso trata uma funcionalidade que o SCOPE disponibiliza para a aplicao de frente de
loja: a totalizao de TEF.
Relatrio de TEF
Pensando na facilidade de fazer o balano dos valores de venda realizados no checkout, o
SCOPE Client prov aplicao um relatrio com informaes do total de TEF confirmadas e
canceladas por bandeira num certo perodo e que pode ser enviado para a impressora ou para
outro meio de armazenamento. Estas informaes podem ser levantadas por PDV ou por
operador. No entanto, mesmo que a aplicao se interesse pelas informaes relativas apenas
por uma das opes (PDV ou operador), o SCOPE atualizar ambos. Portanto, no haver
otimizao ao escolher apenas um dos dois.
No caso do PDV, o perodo escolhido para a totalizao dos valores pode ser dirio, semanal,
mensal, etc., mas recomenda-se que abranja o perodo do movimento, isto , ao iniciar o perodo
num dia, seja zerado o totalizador e, no final do dia, o relatrio seja obtido.
75
Quanto ao relatrio por operador, aconselha-se que seja zerado o totalizador na entrada do
operador ao caixa e obtenha-se o relatrio, na sada do mesmo.
IMPORTANTE: o SCOPE no controla (identifica) qual operador est operando o PDV.
papel da aplicao o controle da entrada e sada de cada operador e conseqentemente,
iniciar o totalizador e obter o relatrio no momento correto.
Iniciando os totais
No incio do perodo de totalizao, a aplicao dever chamar a funo ScopeIniciaTotalTEF(),
passando no parmetro o cdigo referente ao totalizador que se deseja zerar, conforme abaixo:
valor 0: ser zerados ambos os totalizadores, o do PDV e o do operador
valor 1: ser zerado apenas o do operador
Prottipo
LONG ScopeIniciaTotalTEF (BYTE Nivel)
Parmetros
[in]
Indica a que nvel dever ser inicializado

os totais de TEF (0: ambos, 1: apenas do
operador)
Nivel
BYTE
Retorno
Cdigo
0x0000
Descrio
Sucesso
na
Ao
inicializao
dos
totalizadores
0xFB07
Erro na totalizao de TEF, causado por
um dos motivos:
verifique o valor do parmetro

passado;
parmetro invlido;
no foi possvel criar o arquivo;
no foi possvel atualizar o arquivo;
no foi possvel ler o arquivo.
verifique
parmetro
passado funo;
-
verifique direitos de gravao,

criao e leitura de arquivos
para o usurio logado no
PDV;
verifique se existe espao

disponvel no disco.
0xFE00
Transao
em
andamento,
que Revisar a aplicao, pois, ela est
impossibilita a execuo desta funo
chamando a funo em momentos

errado.
Exemplo
...
// carrega configurao do PDV de um novo dia
...
// conecta ao SCOPE Server
76
...
if (ScopeIniciaTotalTEF (0) != 0) // zera ambos
{
// erro ao zerar o arquivo
}
...
Cupom dos totais

No importa se por PDV ou por operador, uma forma que o SCOPE entrega o relatrio para a
aplicao um texto formatado, com 40 colunas, que pode ser enviado diretamente para a
impressora, conforme exemplo abaixo:
------
CARTAO
BANDEIRA
DE
CREDITO
----
EFETUADO
CANCELADO
VISA
167.00
0.00
MASTERCARD
564.80
0.00
------
CARTAO
BANDEIRA
CHEQUE
DE
CANCELADO
1650.00
0.00
18.00
4.00
ELECTRON
CARTAO
BANDEIRA
------
DE
DEBITO
EFETUADO
CONSULTA
BANDEIRA
----
EFETUADO
ELETRONIC
------
DEBITO
CHEQUE
(CDC)
----
CANCELADO
----
CONSULTADO
CUIDADO: O valor efetuado contm o valor cancelado. Assim, no exemplo anterior, a

bandeira Electron indica uma receita de R$ 14,00 (R$ 18,00 - R$ 4,00) para a loja.
Prottipo
LONG ScopeObtemTotalTEF (BYTE Nivel, char *Cupom, WORD TamCupom, char
SeparadorLinhasCupom)
Parmetros
[in]
BYTE
[out] String
[in]
WORD
[in]
char
Indica a que nvel dever ser

inicializado os totais de TEF (0: PDV, 1:
operador)
Cupom
com o relatrio de totais de TEF
Cupom
por bandeira
Tamanho da rea que a aplicao
TamCupom
alocou pela varivel Cupom
Caractere a ser usado na separao
das linhas do cupom. Atualmente,
SeparadorLinhasCupom suporta apenas o caractere @. Para
qualquer outro caractere ser utilizado
\n.
Nivel
77
Retorno
Exemplo
...
WORD TamCupom;
char Cupom[2048];
...
// encerrando o Dia
...
TamCupom = sizeof(Cupom);
if(ScopeObtemTotalTEF(0, Cupom, TamCupom, \n) == 0)
{
...
EnviaCupomParaImpressora(Cupom);
...
}
else
{
// erro ao obter o cupom com o relatrio
}
...
Dados dos totais

A outra maneira que o SCOPE fornece o relatrio para a aplicao por meio de um buffer com
os campos de tamanho fixo, conforme a tabela abaixo:
Tamanho
Descrio
3 bytes
Identificao do buffer (R01)
2 bytes
Quantidade de bandeiras retornadas que indica a quantidade de repeties

dos registros abaixo
1 byte
Identifica a funo:
-
C: Crdito
D: Dbito;
H: Cheque
A: CDC
2 bytes
Cdigo da bandeira
17 bytes
Descrio da bandeira
14 bytes
Valor efetivado (2 casas decimais)
14 bytes
Valor cancelado (2 casas decimais)
Prottipo
LONG ScopeObtemDadosTotalTEF (BYTE Nivel, char *Buffer, WORD TamBuffer)
Parmetros
[in]
BYTE
Nivel
Indica a que nvel dever ser

inicializado os totais de TEF (0: PDV, 1:
78
[out] char *
Buffer
[in]
TamBuffer
WORD
Operador)
Retorna os dados de totais TEF
Tamanho da rea que a aplicao
alocou pela varivel Buffer
Retorno
Exemplo
...
WORD TamBuffer;
char Buffer[2048];
...
// encerrando o Dia
...
TamBuffer = sizeof(Buffer);
if(ScopeObtemDadosTotalTEF(0, Buffer, TamBuffer) == 0)
{
...
GeraRelatorioEmArquivo(Buffer);
...
}
else
{
// erro ao obter o cupom com o relatrio
}
...
Funes diversas
_____________________________________________________________________________________________________
Neste captulo, abordamos diversas funes de uso freqente por diversas empresas, mas que
no conseguimos categoriz-las.
Dados da transao
Aps uma transao ou at mesmo durante o processamento desta, pode-se querer guardar
dados da transao junto aos dados de venda, utilizados pela aplicao para controle ou relatrio
das vendas.
No caso da interface HLAPI, muito til obter esses dados, j que o SCOPE quem coleta e ela
no conhece nenhum dado. Ento ao final da transao, a aplicao poder obter do SCOPE
alguns dados que esto disponveis.
J na interface coleta, quase todos os dados da transao a aplicao consegue obter, uma vez
que ela que prov a entrada de dados e repassa o que foi coletado para o SCOPE. A aplicao
pode conhecer o dado coletado a partir do cdigo do estado de coleta que o SCOPE passa para
ela coletar.
79
Para obter estes dados, primeiramente, a aplicao solicita um handle para a transao. Uma vez
obtido este handle, a aplicao solicita os dados da transao, um de cada vez ou todos de uma
nica vez.
Obtendo handle
A aplicao dever solicitar o handle com a funo ScopeObtemHandle(). Dependendo do
momento em que coletar os dados, o parmetro desta funo ser diferente:
valor 0: este valor dever ser passado para uma referncia da ltima transao ou da
transao em andamento aps a solicitao de autorizao;
valor 9: este valor usado quando o momento de obteno de algum dado acontecer
durante o processamento da transao, antes da solicitao de autorizao.
Prottipo
LONG EXPORT ScopeObtemHandle (LONG Desloc)
Parmetros
[in]
LONG
Desloc
Momento de obteno do handle
Retorno
Valores maiores que 0xFFFF significam valores vlidos de handle. Qualquer outro valor
significa um cdigo de erro (Ver tabela de cdigo de retorno).
Exemplo
...
LONG handle;
handle = ScopeObtemHandle(0);
if(handle > 0xFFFF)
{
// obtm os dados desejados
}
else
{
// erro! no conseguiu o handle
}
...
// fecha a sesso
...
Obtendo os campos
Aps obter um handle vlido, a aplicao est apta para o recebimento dos dados da transao.
Estes dados podem ser obtidos de uma vez s ou campo a campo, ou at mesmo agrupados em
partes. Isto conseguido atravs de campos com combinao de bits.
Cada bit das duas variveis de mscara passadas para o SCOPE possui um significado que
podem ser combinados de qualquer maneira. A relao completa de campos e os bits que
representam estes campos podem ser encontrados na seo Dados disponveis das transaes.
Para casos em que a aplicao solicitar vrios dados, o SCOPE os retornar num nico buffer
80
separado por um caractere separador que a aplicao passar para o SCOPE usar. Mesmo que a
aplicao solicitar um dado que no exista na transao, o SCOPE separar o campo em que
estaria o dado com o caractere separador.
A seqncia dos dados que sero devolvidos para a aplicao ser a partir da mscara 1 e
depois para a mscara 2, na seqncia do bit menos significativo para o mais significativo.
Prottipo
LONG EXPORT ScopeObtemCampoExt (LONG Handle,
LONG Masc1,
LONG Masc2,
char FieldSeparator,
char *Buffer)
Parmetros
[in]
LONG
Handle
[in]
LONG
Masc1
[in]
LONG
Masc2
[in]
char
FieldSeparator
[out] string
Buffer
Handle da transao, uma referncia ao

registro contendo os dados da transao,
que deve ser um valor retornado pela
funo ScopeObtemHandle()
Mscara de bits indicando os campos de
dados da transao a serem recuperados
que pode ser um valor tipo bitwise (Ver bits
relacionados na tabela Dados disponveis
das transaes na parte da mscara 1)
Mscara de bits indicando os campos de
dados da transao a serem recuperados
que pode ser um valor tipo bitwise (Ver bits
relacionados na tabela Dados disponveis
das transaes na parte da mscara 2)
Caractere de separao usado quando
Masc1 e/ou Masc2 forem do tipo bitwise
recuperando mais de um campo no
mesmo buffer
Buffer de destino que conter os dados
que o SCOPE retornar
Retorno
Exemplo
...
long h;
char aux[128];
handle = ScopeObtemHandle(0);
if(handle > 0xFFFF)
{
// obtendo o nsu da transao
memset(aux, '\0', sizeof(aux));
ScopeObtemCampoExt(h, 0x00000004, 0x00 , ';', aux);
ArmazenaCampo(aux);
// exemplo de retorno 015236:
// obtendo o cdigo da operadora de celular

ScopeObtemCampoExt(h, 0x00, 0x00004000, ':', aux);
81
ArmazenaCampo(aux);
// exemplo de retorno 02:
// cdigo e nome da bandeira

ScopeObtemCampoExt(h, 0x00040000 | 0x00800000, 0x00 , ':', aux);
ArmazenaCampo(aux);
// exemplo de retorno 002:Mastercard:
}
else
{
// erro! no conseguiu o handle
}
...
CUIDADO: tente alocar um buffer razoavelmente grande conforme os dados que se deseja
recuperar, pois o SCOPE no alocar buffer.
Fornecendo informaes extras para a transao

Para passar alguma informao que no padro do fluxo da transao, existe a funo
ScopeForneceCampo() como meio de passar esses dados. So vrias as informaes que so
recebidas por esta funo.
Descrio dos tipos de dados

O SCOPE conhece cada tipo de dado pelo valor recebido no primeiro parmetro, pois cada tipo
possui um significado diferente, no tendo relao entre si. Os dados so esperados no segundo
parmetro (buffer).
No arquivo ScopeApi.h que segue com as bibliotecas do SCOPE Client, existe uma enumerao
contendo todos os valores que indicam cada tipo de dado, cuja declarao :
typedef enum {
SCOPE_DADO_MIN,
SCOPE_DADO_EMPRESA,
SCOPE_DADO_PLANO_LOJA,
SCOPE_DADO_ATRIBUTOS_APLIC,
SCOPE_DADO_TRILHA_01,
SCOPE_DADO_REG_FORMA_PAGTO,
SCOPE_DADO_AUT_SUPERVISOR,
SCOPE_DADO_IMPRIME_CHEQUE,
SCOPE_DADO_SEPARADOR_LINHA,
SCOPE_DADOS_APLIC,
SCOPE_DADOS_PAGAMENTO,
SCOPE_DADOS_APLIC_CBD,
SCOPE_DADO_DATA_MOVIMENTO,
SCOPE_DADO_NSU_CUPOM_FISCAL,
SCOPE_DADOS_AUTOMACAO,
SCOPE_DADOS_COD_AUT_MEDICAMENTOS,
82
SCOPE_DADOS_LISTA_MEDICAMENTOS,
SCOPE_AUTOMACAO_PERMITE_SALDO_VOUCHER,
SCOPE_COD_TABELA_PARCELE_MAIS,
SCOPE_DADO_MAX,
} tDadoForneceCampo;
, onde:
SCOPE_DADO_MIN (igual a 0): limite inferior do domnio de valores que o primeiro

parmetro pode receber
SCOPE_DADO_EMPRESA (igual a 1): buffer onde os 7 primeiros bytes representam uma

string com o nmero do cupom/nota fiscal e outros 7 bytes com a srie da nota fiscal
(exemplo: 123456\0598654\0 = {1, 2, 3, 4, 5, 6, \0, 5, 9, 8, 6, 5, 4, \0})
SCOPE_DADO_PLANO_LOJA (igual a 2): string com o mximo 12 bytes de comprimento

contendo o valor total do ticket,
dado complementar utilizado pela funo
ScopeCompraCDC (exemplo: 10000 para R$100,00)
SCOPE_DADO_ATRIBUTOS_APLIC (igual a 3): ver Atributos da aplicao
SCOPE_DADO_TRILHA_01 (igual a 4): string com a trilha 01 do carto lida no PIN-Pad
SCOPE_DADO_REG_FORMA_PAGTO (igual a 5): string de no mximo 30 bytes de

comprimento com a descrio do registrador de forma de pagamento
SCOPE_DADO_AUT_SUPERVISOR (igual a 6): string de no mximo 15 bytes de

comprimento com a autorizao do supervisor
SCOPE_DADO_IMPRIME_CHEQUE (igual a 7): string com 1 byte de comprimento

informando se imprime (S) ou no (N) o cheque
SCOPE_DADO_SEPARADOR_LINHA (igual a 8): string com 1 byte de comprimento com

o separador de linha no cupom (exemplo: $)
SCOPE_DADOS_APLIC (igual a 9): tipo de terminal (A para ATM ou P para PDV) e

usurio
SCOPE_DADOS_PAGAMENTO (igual a 10): dados do pagamento
SCOPE_DADOS_APLIC_CBD (igual a 11): utilizado pela rede CBD, string com o primeiro
byte informando o tipo de terminal (1 ou4) e o restante da string representando a data
de movimento no formato MMDD
SCOPE_DADO_DATA_MOVIMENTO (igual a 12): no mais suportado
SCOPE_DADO_NSU_CUPOM_FISCAL (igual a 13): no mais suportado
SCOPE_DADOS_AUTOMACAO (igual a 14): buffer onde os 21 primeiros bytes

representam uma string com o fabricante do software de automao e outros 21 bytes
com a verso do software da automao
SCOPE_DADOS_COD_AUT_MEDICAMENTOS (igual a 15): string com 13 bytes que

contm o cdigo de autorizao da PBM
SCOPE_DADOS_LISTA_MEDICAMENTOS (igual a 16): buffer com a lista de

medicamentos da PBM
SCOPE_AUTOMACAO_PERMITE_SALDO_VOUCHER (igual a 17): Atravs deste

campo, a automao informa ao Scope se permite que o pagamento efetuado atravs de
83
voucher utilize o valor disponvel no saldo (neste caso deve informar S) ou aceita
somente pagamento para os casos em que o saldo do voucher seja igual ou superior ao
valor da transao (neste caso deve informar N). Observe que este campo deve ser
informado somente na abertura de conexo entre a aplicao e o Scope Cliente
(ScopeOpen).
SCOPE_COD_TABELA_PARCELE_MAIS (igual a 18): Automao pode fornecer um

cdigo de tabela a ser usado na transao de Parcele Mais, indicando o custo financeiro.
SCOPE_DADO_MAX (igual a 17): limite superior do domnio de valores que o primeiro

parmetro pode receber
Atributos da aplicao
Permite implementar atributos (campos) dinamicamente, que so vinculados as transaes
efetuadas pelo SCOPE. Existem trs mdulos envolvidos por esta funcionalidade:
ScopeCNF: cadastrando os atributos (ver no documento de instalao, configurao e

administrao, informaes sobre cadastramento)
Aplicao do PDV: dever usar a funo ScopeForneceCampo()
ScopeADM: ir exibir as transaes vinculadas aos atributos cadastrados (ver o

documento de instalao, configurao e administrao para informaes sobre relatrio)
Exemplo: voc poder consultar as transaes efetuadas pelo SCOPE, vinculadas a outras
informaes teis a empresa, como: nmero da nota fiscal, do pedido, da compra, nome e
telefone do cliente, etc.
O formato dos dados deve ser uma string que obedece ao seguinte padro:
nnc1tt1xx..x1c2tt2xx..x2cnttnxx..xn
, onde:
nn = quantidade de atributos (tamanho 2)
c1 = cdigo do atributo 1 (tamanho 2)
tt1 = tamanho do atributo 1 (tamanho 3)
xx..x1 = atributo 1 (tamanho tt1)
c2 = cdigo do atributo 2 (tamanho 2)
tt2 = tamanho do atributo 2 (tamanho 3)
xx..x2 = atributo 2 (tamanho tt2)
...
cn = cdigo do atributo n (tamanho 2)
ttn = tamanho do atributo n (tamanho 3)
xx..xn = atributo n (tamanho ttn)

IMPORTANTE: por razes de otimizao de trfego, o SCOPE Client envia estes dados
para o servidor na solicitao da segunda pr-TEF. Portanto, a aplicao deve fornecer este
buffer antes da realizao da mesma.
84
IMPORTANTE: na interface HLAPI, a aplicao deve mandar suspender em um dos

estados de coleta que antecedem a segunda pr-TEF.
Atrelando dados transao

Passar algum dado ao SCOPE com a funo ScopeForneceCampo() exige que ela seja chamada
antes do envio da segunda pr-TEF.
Prottipo
LONG EXPORT ScopeForneceCampo (char TypeField, void *StructField)
Parmetros
[in]
[in]
char
void *
TypeField
StructField
Tipo de dado
Ponteiro para os dados
Retorno
Exemplo
Digamos que a cada venda paga com o carto de crdito, a empresa deseja que seja
atrelada a transao o nmero de telefone do cliente e o nmero do pedido. Para isso, o
administrador do SCOPE criou dois atributos no ScopeCNF (figura 7).
Figura 7: atributos da aplicao cadastrados no ScopeCNF
A aplicao coletar estes dados sempre que houver uma venda com carto de crdito.
Exemplificando na linguagem C uma compra com carto de crdito (interface Alto Nvel HLAPI):
...
LONG RC;
char szAtributosAplic[40];
...
// operador selecionou crdito
...
// abre sesso de TEF
...
ScopeSuspend(EC_COLETA_CARTAO);
ScopeCompraCartaoCredito("100", "0");
...
if (RC == RCS_EXISTE_TRN_SUSPENSA)
{
// coletou o telefone do cliente e nmero do pedido
85
...
// montou o buffer do atributo da aplicao
// (ex. "0201014(11) 6097-123402006123456" e guardou em szAtributosAplic
...
ScopeForneceCampo(SCOPE_DADO_ATRIBUTOS_APLIC, szAtributosAplic);
ScopeResume();
}
...
// encerra sesso de TEF
Separando o buffer do exemplo acima conforme o padro descrito, obtemos:
02 2 campos no buffer
01 este campo representa o que est cadastrado como cdigo 1 no ScopeCNF
014 o atributo que seguir contm 14 bytes
(11) 6097-1234 valor do atributo de cdigo 1 com 14 bytes
02 este campo representa o que est cadastrado como cdigo 2 no ScopeCNF
006 o atributo que seguir contm 6 bytes
123456 valor do atributo de cdigo 2 com 6 bytes
ScopeGetLastMsg
Obtm as ltimas mensagens a serem mostradas para o operador e/ou cliente.
Prottipo
LONG EXPORT ScopeGetLastMsg (ptCOLETA_MSG ptParamColetaMsg)
Parmetros
Ponteiro para
uma rea com o
ptParamColetaMsg
[out] formato da
estrutura
stCOLETA_MSG
Estrutura contendo as mensagens do

operador e do cliente (tanto a linha 1
como a linha 2). As mensagens so
finalizadas pelo caractere nulo (\0)
Estruturas de apoio
typedef struct _stCOLETA_MSG {
char Op1[64];
char Op2[64];
char Cl1[64];
char Cl2[64];
} stCOLETA_MSG, *ptCOLETA_MSG;
Retorno
ScopeGetCheque
Obtm os parmetros para impresso de cheque.
86
Prottipo
LONG EXPORT ScopeGetCheque(ptPARAM_CHEQUE ptParamCheque)
Parmetros
Ponteiro para uma
rea com o formato ptParamCheque
[out]
da estrutura
ptPARAM_CHEQUE
Dados para impresso do cheque
Estruturas de apoio
typedef struct
_stPARAM_CHEQUE {
char Banco[4];
// nmero do banco
char Agencia[5];
// nmero da agncia
char NumCheque[13];
// nmero do cheque
char Valor[13];
// valor do cheque
char BomPara[9];
// data do cheque
char CodAut[11];
// cd. de autor. retornado pelas autorizadoras
char Municipio[41];
// municpio
short Ordem;
// reservado
} stPARAM_CHEQUE, *ptPARAM_CHEQUE;
Retorno
ScopeAtualizaValor
Atualiza ou fornece o novo valor da transao. Esta funo deve ser executada aps a funo de
transao e antes do envio da solicitao de autorizao para a Autorizadora.
Prottipo
LONG EXPORT ScopeAtualizaValor(char *Valor)
Parmetros
[in]
String
Valor
Valor da transao. Deve ser uma string de

at 12 bytes.
Retorno
ScopeGarantiaDescontoCheque
Aciona o SCOPE client para efetuar uma transao de Garantia de Cheque ou de Desconto
Antecipado de Cheque (Factoring).
Prottipo
LONG EXPORT ScopeGarantiaDescontoCheque (char *Valor)
Parmetros
[in]
String
Valor
Valor da transao. Deve ser uma string de

at 12 bytes.
87
Retorno
ScopeTransacaoFinanceira
Aciona o SCOPE client para efetuar uma transao financeira.
Prottipo
LONG EXPORT ScopeTransacaoFinanceira (char *Valor, WORD Servico)
Parmetros
[in]
String
Valor
[in]
WORD
Servio
Valor da transao
Informa qual o servio a ser adotado. Caso
0 (zero) a coleta do servio ser feita pelo
procedimento usual (ver Cdigos dos
servios)
Retorno
ScopeInvestimento
Aciona o SCOPE client para efetuar um investimento.
Prottipo
LONG EXPORT ScopeInvestimento (char *Valor, WORD Servico)
Parmetros
[in]
String
Valor
[in]
WORD
Servico
Valor da transao
Informa qual o servio a ser adotado. Caso
0 (zero) a coleta do servio ser feita pelo
procedimento usual (ver Cdigos dos
Servios)
Retorno
ScopeObtemCartaoInvestimento
Aciona o SCOPE client para obter o nmero do carto a partir do CPF do cliente. Viabiliza efetuar
uma transao de aplicao pelo nmero do CPF.
Prottipo
LONG EXPORT ScopeObtemCartaoInvestimento (char *CPF,
char *Buf,
WORD TamBuf)
Parmetros
[in]
String
[out] String
CPF
Buf
CPF do cliente
rea reservada pela aplicao para
receber o carto (ou lista de cartes). O
layout dos dados foi definido pelo SAB (o
SCOPE no critica nem altera este layout).
88
[in]
WORD
TamBuf
A aplicao deve informar ao SCOPE o

tamanho da rea reservada
Retorno
ScopeResumoOperacoes
Utilizada nos casos em que a rede ou correspondente bancrio oferece a possibilidade de
obteno de um resumo das operaes realizadas.
Prottipo
LONG EXPORT ScopeResumoOperacoes (WORD CodServico, WORD CodBandeira)
Parmetros
[in]
WORD
CodServico
[in]
WORD
CodBandeira
Cdigo do servio do produto a ser

executado. Use 0 (zero) para indicar que o
cdigo do servio dever ser coletado
durante o fluxo da transao.
Cdigo da bandeira do produto a ser
cdigo da bandeira dever ser coletado.
Retorno
ScopePagamento
Utilizada para pagamento de conta (ttulo ou convnio) ou fatura, atravs de uma rede
autorizadora ou por intermdio de correspondente bancrio. Os servios atuais disponveis so
pagamento de conta com carto, pagamento de conta sem carto e pagamento de fatura. O
pagamento de conta com carto usado quando a rede exige uma determinada bandeira
(Electron, Cheque Eletrnico), sendo que neste caso o SCOPE valide o BIN do carto.
Pagamento de conta sem carto quando o pagamento pode ser realizado atravs de dinheiro,
cheque ou TEF externa (outra transao realizada separadamente). Pagamento de fatura usado
para o recebimento prprio de fatura de carto de crdito. Neste caso, o cdigo de barras no
obrigatrio, j que o pagamento pode ser atravs do nmero do carto (digitado ou lido).
Prottipo
LONG EXPORT ScopePagamento (WORD CodServico, WORD CodBandeira)
Parmetros
[in]
WORD
CodServico
[in]
WORD
CodBandeira
Cdigo do servio do grupo Pagamento

de Contas a ser executado. Use 0 (zero)
para indicar que a deciso do servio ser
atravs de coleta.
Cdigo da bandeira do produto a ser
cdigo da bandeira dever ser coletado.
Retorno
89
90
Apndice A Tabelas
_____________________________________________________________________________________________________
Cdigos de retorno
Coleta de dados
Estes cdigos sero retornados pela funo ScopeStatus() quando a aplicao optar pela coleta
dos dados atravs da funo ScopeSetAplColeta(). Estes cdigos informam para a aplicao de
PDV a ao a ser tomada. Como exemplo, coletar um dado, imprimir um cupom e/ou cheque, ou
at mesmo mostrar informaes no display do operador e/ou cliente aguardando a confirmao.
Cdigos Retorno
Hexade Decimal
cimal
0xFC00
64512
0xFC01
64513
0xFC02
64514
0xFC03
64515
0xFC04
64516
0xFC05
64517
0xFC06
64518
0xFC07
64519
0xFC08
64520
0xFC09
64521
0xFC0A
64522
0xFC0B
0xFC0C
0xFC0D
0xFC0E
0xFC0F
0xFC10
0xFC11
0xFC12
0xFC13
0xFC14
0xFC15
0xFC16
0xFC17
0xFC18
0xFC19
0xFC1A
0xFC1B
0xFC1C
0xFC1D
0xFC1E
0xFC1F
0xFC20
0xFC21
0xFC22
0xFC23
0xFC24
0xFC25
0xFC26
64523
64524
64525
64526
64527
64528
64529
64530
64531
64532
64533
64534
64535
64536
64537
64538
64539
64540
64541
64542
64543
64544
64545
64546
64547
64548
64549
64550
Significado
Coletar carto
Coletar validade do carto
Imprime Cupom
Coletar CGC ou CPF
Coletar banco
Coletar agncia
Coletar nmero do cheque
Coletar data do cheque (bom para)
Imprime cheque
Coletar se a transao ser a vista ou no
Coletar se a transao ser parcelada pela administradora ou pelo
estabelecimento
Coletar se a transao ser pr-datada
Coletar se a parcela ser vista
Coletar quantidade de dias entre parcelas
Coletar quantidade de parcelas
Coletar o plano de financiamento
Coletar o dia e o ms (DDMM)
Coletar a senha
Coletar o controle do SCOPE
Coletar a forma de pagamento
Coletar data do primeiro vencimento
Coletar valor de entrada
Coletar a forma de entrada
Coletar conta corrente
Coletar ltimos dgitos do carto
Coletar se deseja consultar parcelas
Imprime consulta
Coletar deciso de continuar
Coletar decide ltimo
Coletar nmero de cheque CDC
Coletar quantidade de dias
Coletar o nmero da pr-autorizao
Coletar dia do ms fechado
Imprime nota promissria
Coletar CEP
Coletar nmero do endereo
Coletar parte numrica do complemento
Coletar plano de pagamento (Fininvest)
91
Cdigos Retorno
Hexade Decimal
cimal
0xFC27
64551
0xFC28
64552
0xFC29
64553
0xFC2A
64554
0xFC2B
64555
0xFC2C
64556
0xFC2D
64557
0xFC2E
64558
0xFC2F
64559
0xFC30
64560
0xFC31
64561
0xFC32
64562
0xFC33
64563
0xFC34
64564
0xFC35
64565
0xFC36
64566
0XFC37
64567
0xFC38
64568
0xFC39
64569
0xFC40
64576
0xFC41
64577
0xFC42
64578
0xFC43
64579
0xFC44
64580
0xFC45
64581
0xFC46
64582
0xFC47
64583
0xFC48
64584
0xFC49
64585
0xFC4A
64586
0xFC4B
64587
0xFC4C
64588
0xFC4D
64589
0xFC4E
64590
0xFC4F
64591
0xFC50
64592
0xFC51
64593
0xFC52
64594
0xFC53
64595
0xFC54
64596
0xFC55
64597
0xFC56
64598
0xFC57
64599
0xFC58
64600
0xFC59
64601
0xFC5A
64602
0xFC5B
64603
0xFC5C
64604
0xFC5D
64605
0xFC5E
64606
0xFC5F
64607
0xFC60
64608
0xFC61
64609
0xFC62
64610
0xFC63
64611
Significado
Coletar ciclos a pular (Fininvest)
Coletar nmero do item (Fininvest)
Coletar cdigo de segurana
Coleta se cdigo de segurana ausente ou ilegvel
Coleta se com ou sem garantia de pr-datado
Coleta se aceita ou no risco
Coleta valor do saque
Coleta valor da recarga de celular pr-pago
Coleta cdigo da localidade do telefone
Coleta nmero do telefone
Coleta dgito verificador do telefone
Coleta data (formato DDMMAA)
Coleta valor da taxa de servio
Coleta valor
Coleta se quer realizar saque
Coleta se quer realizar simulao de saque
Coleta se quer saldo ou extrato
Coleta se quer o extrato resumido ou a segunda via
Coleta se consulta investimento ou resgate
Coleta se resgate avulso
Coleta data (formato DDMMAAAA)
Coleta o cdigo de autorizao PBMS
Coleta a lista de medicamentos
Retorna a lista de medicamentos
Exibir mensagem
Imprime cupom parcial
Coleta quantidade de parcelas e aceita 1 parcela
Coleta cdigo de barras
Coleta cdigo de consulta PBM
Coleta CRM mdico
Coleta cdigo UF CRM mdico
Coleta se cliente deseja aderir ao seguro (IBICred)
Coleta se pagamento com carto
Coleta dados especficos da rede Tokoro
Coleta se deseja pagar aps vencimento
Coleta se a transao com senha
Imprime cupom promocional
Coleta se utiliza saldo
Coleta cdigo do material
Coleta cdigo do plano
Coleta se o pagamento em cheque
Coleta se confirma transao
Coleta se o pagamento no rotativo
Coleta CMC7
Coleta se o pagamento em dinheiro ou TEF (carto)
Coleta o cdigo do grupo de servio (para a TEF Externa)
Coleta o cdigo da rede (para a TEF Externa)
Coleta o cdigo do estabelecimento (para a TEF Externa)
Coleta o NSU do Host (para TEF Externa)
Coleta data (ddmmaaaa) (para TEF Externa)
Coleta se consulta
Coleta se continua aps verificar a conta
Coleta o cdigo da bandeira
Coleta se conta da fatura
Coleta o valor total
92
Cdigos Retorno
Hexade Decimal
cimal
0xFC64
64612
0xFC65
64613
0xFC66
64614
0xFC67
64615
0xFC68
64616
0xFC69
64617
0xFC6A
64618
0xFC6B
64619
0xFC6C
64620
0xFC6D
64621
0xFC6E
64622
0xFC6F
64623
0xFC70
64624
0xFC71
64625
0xFC72
64626
0xFC73
64627
0xFC74
64628
0xFC75
64629
0xFC76
64630
0xFC77
64631
0xFC78
64632
0xFC79
64633
0xFC7A
64634
0xFC7B
64635
0xFC7C
64636
0xFC7D
64637
0xFC7E
64638
0xFC7F
64639
0xFC80
64640
0xFC81
64641
0xFC82
64642
0xFC83
64643
0xFC84
64644
0xFC85
64645
0xFC86
64646
0xFC87
64647
0xFC88
64648
0xFC89
64649
0xFC8A
64650
0xFC8B
64651
0xFC8C
64652
0xFC8D
64653
0xFC8E
64654
0xFC8F
64655
0xFCFC
0xFCFD
0xFCFE
0xFCFF
64764
64765
64766
64767
Significado
Coleta RG
Coleta se deseja realizar novamente a transao (retentativa)
Coleta somente CPF
Coleta o endereo
Coleta o andar
Coleta o conjunto
Coleta o bloco
Coleta o bairro
Coleta a autorizao ou o carto
Coleta a data de emisso do carto
Coleta o plano Infocards
Coleta nmero do cupom fiscal
Coleta a operadora de recarga de celular pr-pago
Coleta dados SAB
Coleta o nmero do telefone com o dgito verificador
Coleta os dados transao forada SAB
Coleta o tipo de servio tcnico: baixa tcnica, teste comum ou estatstica
Coleta o nmero da OS
Coleta identificao do tcnico
Coleta o cdigo de ocorrncia
Coleta a EPS credenciada
Decide se coleta valor de entrada (no mais utilizado)
Decide se coleta valor da primeira parcela (no mais utilizado)
Coleta o valor da primeira parcela
Coleta os dados adicionais
Coleta se cancela ou no a transao
Go On Chip
Retira o carto
Coleta o valor da taxa de embarque
Exibe a mensagem de saldo
Exibir a mensagem e retorna o fluxo (no mais utilizado)
Exibir a mensagem aguarda confirmao do operador (no mais utilizado)
Obtm os servios
Coleta o carto digitado
Coleta o cdigo do produto
Exibe o menu
Coleta se INSS ou cheque
Coleta o contrato
Coleta a data quando o cliente aderiu ao carto
Exibir o valor da consulta Vale Gs
Coleta data da transao original no formato DDMMAA
Coleta o NSU da transao original (nmero de 6 dgitos)
Exibir os dados do cancelamento (no mais utilizado)
Coletar qual a via da reimpresso (0: todas as vias; 1: apenas da loja; 2:
apenas do cliente)
Coleta carto em andamento (PIN-Pad)
Coleta em andamento (PIN-Pad)
Mostrar informaes e retornar fluxo para o cliente SCOPE
Mostrar Informaes e aguardar confirmao do operador
Autorizadoras
Abaixo se encontram relacionados os cdigos devolvidos pelas redes autorizadoras na
mensagem 0210 e entregue para a aplicao atravs da funo ScopeStatus().
93
Cdigos Retorno
Hexadeci Decimal
mal
0x0000
0
0x0003
3
0x0006
6
0x0009
9
0x000C
12
0x000D
13
0x000E
14
0x000F
15
0x0013
19
0x001E
30
0x001F
31
0x0026
38
0x0029
41
0x002B
43
0x0033
51
0x0034
52
0x0036
54
0x0037
55
0x0038
56
0x0039
57
0x003C
60
0x003D
61
0x0041
65
0x004C
76
0x004D
77
0x004E
78
0x004F
79
0x0050
80
0x0051
81
0x0052
82
0x0053
83
0x0054
84
0x0055
85
0x0056
86
0x0059
89
0x005A
90
0x005B
91
0x0100
256
0x0101
0x0102
0x0103
0x0104
0x0105
0x0106
257
258
259
260
261
262
Significado
Sucesso
Estabelecimento comercial invlido
Erro
Transao em andamento
Transao invlida
Valor da transao invlido
Carto invlido
Instituio no cadastrada
Refaa transao
Erro de formato
Instituio no pertence rede
Excedido o nmero de tentativas do PIN
Carto extraviado
Carto roubado
Saldo insuficiente
Conta corrente no cadastrada
Carto vencido
Senha incorreta
Carto sem registro
Transao no permitida a esse cliente
Entrar em contato com a instituio
Excedido o limite de saque
Excedida a freqncia de saque
Carto bloqueado
Pendente de confirmao
Transao cancelada
Transao no permitida neste ciclo
Transao inexistente
Transao estornada
Chave de criptografia invlida
Timeout
Logon / Desfazimento
Problema rede local
Transao desfeita
Mensagem enviada pelo Host
Fechamento contbil
Instituio temporariamente fora de operao
Retorno genrico para cdigos alfanumricos. Para obter o exato
cdigo alfanumrico retornado necessrio chamar a funo
ScopeObtemCampoExt() passando o bit equivalente ao cdigo de
resposta (ver Obtendo os campos).
Cliente com restrio na lista negra local
J consultou sob mesmo banco e agncia
J consultou sob banco e/ou agncia diferente(s)
Cdigo GAR no autorizado
Compre Saque Redecard aprovado parcial
Voucher Redecard aprovado parcial
Cdigos de erros do SCOPE

Em qualquer momento, na chamada de qualquer funo o SCOPE Client devolver um cdigo de
retorno. O cdigo que no estiver na relao dos cdigos de coleta e na das autorizadoras,
encontram-se abaixo e geralmente denota um erro.
94
Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFA03
64003
0xFA04
64004
0xFA05
64005
0xFB01
64257
0xFB02
64258
0xFB03
64259
0xFB04
64260
0xFB05
64261
0xFB06
64262
0xFB07
64263
0xFB08
64264
0xFB09
64265
0xFB0A
64266
0xFB0B
64267
0xFE00
65024
0xFE01
65025
0xFE02
65026
0xFE03
65027
0xFE04
65028
0xFE05
65029
0xFE06
0xFE07
65030
65031
0xFE08
0xFE09
0xFE0A
65032
65033
65034
0xFE0B
65035
0xFE0C
65036
0xFE0D
0xFF00
65037
65280
0xFF01
0xFF02
65281
65282
0xFF03
0xFF04
0xFF05
0xFF06
0xFF07
0xFF08
0xFF09
0xFF0A
0xFF0B
0xFF0C
65283
65284
65285
65286
65287
65288
65289
65290
65291
65292
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Parmetro 3 invlido
Parmetro 4 invlido
Parmetro 5 invlido
No foi possvel criar a thread na coleta de dados
Erro na montagem do servio pela API
Erro ao verificar mensagem mensagem invlida
Erro ao montar mensagem
Erro no arquivo de controle da TEF
Erro no contexto do arquivo de TEF (no mais utilizado)
Erro na totalizao de TEF
Erro no arquivo de controle utilizado finalizao no ciclo multi-TEF
Estourou o nmero mximo de TEF numa sesso multi-TEF
No salvou a mensagem de confirmao para o SAB
No salvou a mensagem de desfazimento para o SAB
A transao em andamento a aplicao deve aguardar
SCOPE API no foi inicializada corretamente
SCOPE API j foi inicializada corretamente
Existe transao suspensa
No existe transao suspensa
API ainda no fez nenhuma transao aps a inicializao. A
aplicao est tentando obter um handle sem ter feito nenhuma
transao desde ltima conexo com o ScopeSRV
Logon duplicado
Protocolo no suportado SCOPE Client com verso de protocolo
superior ao SCOPE Server
POS no cadastrado
Servidor no configurado no arquivo scope.ini
No h mais PDVs disponveis. Erro retornado quando a aplicao
passa o caractere # como PDV para que o SCOPE Server lhe d
um nmero de PDV vlido, mas no h mais PDVs disponveis
Protocolo incompatvel SCOPE Client com verso de protocolo
extremamente antigo (P00, P01 ou P02).
No pode mais desfazer uma transao que j iniciou o ciclo de
finalizao situao que pode ocorrer apos queda de energia ou na
inicializao da aplicao.
No h arquivo com dados da transao anterior salvo
ScopeSrv off-line ou o IP configurado no arquivo scope.ini est
apontando para a mquina errada
Instituio off-line
Transao cancelada pelo operador ou no caso de um estorno via
REDECARD: estorno fora do prazo permitido, validade no confere.
Servio ou BIN no configurado
Transao j foi cancelada
Transao no encontrada
Transao no permite cancelamento
Dados informados no conferem com a transao original
Erro no acesso ao banco de dados
Time-out no acesso ao banco de dados
Banco de dados off-line
Transao abortada pelo aplicativo
Transao no implementada
95
Cdigos Retorno
Hexadeci Decimal
mal
0xFF0D
65293
0xFF0E
65294
0xFF0F
65295
0xFF10
65296
0xFF11
65297
0xFF12
65298
0xFF13
0xFF14
0xFF15
0xFF16
0xFF17
0xFF18
0xFF19
0xFF1A
0xFF1B
0xFF1C
0xFF1D
65299
65300
65301
65302
65303
65304
65305
65306
65307
65308
65309
0xFF1E
0xFF1F
0xFF20
0xFF21
0xFF22
0xFF23
0xFF24
0xFF25
0xFF26
0xFF27
0xFF28
0xFF29
0xFF2A
0xFF2B
0xFF2C
0xFF2D
0xFF2E
0xFF30
0xFF31
0xFF32
0xFF33
0xFF34
0xFF35
0xFF36
0xFF37
65310
65311
65312
65313
65314
65315
65316
65317
65318
65319
65320
65321
65322
65323
65324
65325
65326
65328
65329
65330
65331
65332
65333
65334
65335
0xFF38
0xFF39
0xFF3A
0xFF3B
0xFF3C
0xFF3D
0xFF3E
0xFF3F
0xFF40
0xFF41
65336
65337
65338
65339
65340
65341
65342
65343
65344
65345
Significado
Handle invlido (ver Obtendo handle)
Taxa de servio invlida
Taxa de servio excede limite
Dado invlido
No existe cupom vlido
rea reservada para o buffer insuficiente para o SCOPE Client
preencher com os dados solicitados
Limite invlido inferior ao permitido
Transao desfeita
Digitao no permitida
Memria insuficiente
Service Code invlido
Data invlida
Carto vencido
Carto invlido
Desfazimento no disponvel
Erro na impresso do cupom
Sesso em andamento a transao solicitada deve ser nica numa
sesso de TEF, ou seja, no pode ser chamada se h transaes na
sesso de TEF atual
Transao j efetuada
Inserir chip do carto
Controle obrigatrio
Pr-autorizao obrigatria
Servio no configurado
Servio no definido
Nmero de parcelas invlidas
Valor invlido
Servio ou BIN no configurado para Visanet
Estado de coleta no definido
Operao no permitida
CNPJ/CPF invlido
Primeiro bloco do cdigo de barras est invlido
Segundo bloco do cdigo de barras est invlido
Terceiro bloco do cdigo de barras est invlido
Quarto bloco do cdigo de barras est invlido
Dados adicionais AID do chip do carto inexistente
Autorizador retornou dados invlidos
Conta no permitida
Conta vencida
No existe resumo
Cdigo de barra invlido
Erro na consistncia do DAC
Erro no envio da confirmao ou desfazimento da transao anterior
Servio invertido a aplicao est tentando fazer uma transao de
dbito com um carto de crdito ou vice-versa
Carto no permitido
Permitido somente a coleta do CPF consulta de cheque
Erro interno na execuo da coleta
Lista (de produtos, de medicamentos, etc.) no est disponvel.
Erro de leitura do carto
Controle invlido
Erro ao enviar mensagem para o servidor
Interface SAB no inicializada
Erro: dados ainda no disponveis (SAB)
Erro: dados indisponveis (SAB)
96
Cdigos Retorno
Hexadeci Decimal
mal
0xFF42
65346
0xFF43
65347
0xFF44
65348
0xFF45
65349
0xFF46
65350
0xFF47
65351
0xFF48
65352
0xFF49
65353
0xFF50
65360
0xFF51
65361
0xFF52
65362
0xFF53
65363
0xFF54
65364
0xFF55
65365
0xFF56
65366
0xFF57
65367
0xFF58
0xFF59
0xFF5A
0xFF5B
65368
65369
65370
65371
0xFF5C
65372
0xFF5D
0xFF5E
0xFF5F
0xFF60
0xFF61
0xFF62
0xFF63
0xFF64
0xFF65
0xFF66
0xFF67
0xFF68
0xFF69
0xFFFF
65373
65374
65375
65376
65377
65378
65379
65380
65381
65382
65383
65384
65385
65535
Significado
Servidor SAB off-line
Erro de conexo entre SCOPE e SAB
Erro no NSU recebido
Erro no logon do PDV
Erro no processamento do chip
Operadora invlida
Dados, da recarga de celular, no encontrados.
Transao cancelada pelo cliente
Transao aprovada off-line
Verso do banco de dados incompatvel
Cancelamento fora do prazo permitido
Mensagem invlida
PIN-Pad no foi aberto
PIN-Pad j foi aberto a aplicao abriu o PIN-Pad antes de conectar
ao ScopeSRV, mas no deveria ter-lo feito, pois no ScopeCNF est
configurado com uso exclusivo do SCOPE
Estado invlido a aplicao est tentando obter os servios
disponveis num estado de coleta inadequado
PIN-Pad compartilhado no est configurado, mas a rede exige que
seja compartilhado
PIN-Pad compartilhado no trabalha com a verso 2000 da VISA
Funo de uso exclusivo na interface coleta
rea insuficiente para os atributos do servio
O SCOPE est configurado para uso de PIN-Pad compartilhado, mas
a aplicao informou que est com o kit Visanet para PIN-Pad
O SCOPE no est configurado para uso de PIN-Pad compartilhado,
mas a aplicao informou que est com PIN-Pad compartilhado
Erro ao inicializar perifricos na interface HLAPI
Erro ao desmontar a estrutura ISO
Bandeira no est configurada
Funo indisponvel
Valor mnimo da parcela invlido
Valor da consulta Vale Gs ainda no est disponvel
Nmero de Telefone invlido
DDD invlido
Erro Rede Modelo 2
Erro Rede Modelo 3
Confirmao Positiva Inconsistente
Transao Offline Permitido apenas reimpresso offline
Contrato Suspenso
Erro genrico
PIN-Pad compartilhado
Para alguns casos, o SCOPE poder retornar erros reportados pelo PIN-Pad compartilhado, cujos
cdigos se encontram descritos na tabela abaixo.
Cdigos Retorno
Hexadeci Decimal
mal
0x0000
0
0x0001
1
0x0002
2
0x0004
4
0x0005
5
0x0006
6
Significado
Operao OK
Operao em processamento
Notificar o operador com a mensagem recebida do PIN-Pad
Pressionada a tecla de funo #1
97
Cdigos Retorno
Hexadeci Decimal
mal
0x0007
7
0x0008
8
0x000A
10
0x000B
11
0x000C
12
0x000D
13
0x000E
14
0x000F
15
0x0010
16
0x0011
17
0x0012
18
0x0013
19
0x0014
20
0x0015
21
0x0016
22
0x001E
30
0x001F
31
0x0020
0x0021
0x0022
32
33
34
0x0028
0x0029
0x002A
40
41
42
0x002B
0x002C
43
44
0x0032
0x0033
0x0034
0x003C
0x003D
0x003E
50
51
52
60
61
62
0x003F
63
0x0040
64
0x0041
0x0042
0x0043
65
66
67
0x0044
68
0x0045
69
0x0046
70
Significado
Pressionada a tecla Limpar/Clear
Necessria operao previa
Parmetro invlido
Time-out esgotado o tempo de resposta
Operao cancelada
PIN-Pad j foi aberto
PIN-Pad no foi aberto
Erro interno de execuo
Funo no suportada
Funo no disponvel
Ausncia de dado mandatrio para o processamento.
Tabelas expiradas
Erro ao tentar gravar tabelas (falta de espao, por exemplo)
Aplicao da rede adquirente no existe no PIN-Pad.
Erro de comunicao: porta serial do PIN-Pad provavelmente
ocupada.
Erro de comunicao: PIN-Pad provavelmente desconectado ou
problemas com a interface serial. Pode ser que a porta que est
passando como parmetro esteja errada.
Status informado pelo PIN-Pad no conhecido.
Mensagem recebida do PIN-Pad possui formato invlido.
Tempo esgotado ao esperar pela resposta do PIN-Pad (no caso de
comandos no-blocantes).
Erro interno do PIN-Pad.
Erro de leitura do carto magntico.
Erro na captura do PIN (senha) - Master Key pode no estar
presente.
No h carto inteligente presente no acoplador. Carto removido.
PIN-Pad no pode processar a captura de PIN temporariamente
devido a questes de segurana (como quando atingido o limite de
capturas dentro de um intervalo de tempo).
Erro genrico no mdulo SAM.
SAM ausente, "mudo", ou com erro de comunicao.
SAM invlido, desconhecido ou com problemas.
Carto no responde ("mudo") ou chip no presente.
Erro de comunicao do PIN-Pad com o carto inteligente.
Carto do tipo invlido ou desconhecido, no pode ser tratado (no
EMV nem TIBC v1).
Carto bloqueado por nmero excessivo de senhas incorretas
(somente para Easy-Entry TIBC v1).
Carto TIBC v1 no autenticado pelo mdulo SAM (somente para
Easy-Entry TIBC v1).
Carto TIBC v1 expirado (somente para Easy-Entry TIBC v1).
Carto com erro de estrutura - arquivos esto faltando.
Carto foi invalidado. Se o carto for TIBC v1, quando seleo de
arquivo ou ATR retornar status 6284. Se o carto for EMV, quando
seleo de aplicao retornar status 6A81.
Carto com problemas. Esse status vlido para muitas ocorrncias
no processamento de cartes TIBC v1 e EMV onde o carto no se
comporta conforme o esperado e a transao deve ser finalizada.
O carto, seja TIBC v1 ou EMV, comporta-se corretamente porm
possui dados invlidos ou inconsistentes.
Carto sem nenhuma aplicao disponvel para as condies pedidas
(ou carto reconhecido como TIBC v1 ou EMV mas no possui
nenhuma aplicao compatvel com a requerida).
98
Cdigos Retorno
Hexadeci Decimal
mal
0x0047
71
0x0048
72
0x0049
73
0x00C8
0x00C9
0x00CA
0x00CB
0x00CC
0x00CD
0x00CE
0x00CF
0x00D0
0x00D1
0x00D2
0x00D3
0x00D4
200
201
202
203
204
205
206
207
208
209
210
211
212
Significado
Somente para carto EMV. A aplicao selecionada no pode ser
utilizada neste terminal pois o Get Processing Options retornou
status 6985.
Somente para aplicao de moedeiro. O saldo do moedeiro
insuficiente para a operao.
Somente para aplicao de moedeiro. O limite mximo para a
operao foi excedido.
Transao negada na funcao PP_GoOnChip()
Transao negada na funcao PP_GoOnChip()
Memria no alocada para a estrutura do PIN-Pad compartilhado
Erro alocando memria
Memria insuficiente para receber os dados
PIN-Pad j aberto via SCOPE
No foi possvel definir a Master Key a ser utilizada
No foi possvel definir o Estado de coleta no PIN-Pad
Erro no parmetro da funcao GetPIN
PIN-Pad no configurado
Display no permitido neste momento ou situao
PIN-Pad no foi aberto pela aplicacao
Time-out do cliente / usurio
Formatos dos dados

Utilizado na coleta do dado, a aplicao valida a entrada de dado que o usurio forneceu de
acordo com o cdigo do formato do dado recebido.
Cdigos Formato
Hexadeci Decimal
mal
0x0000
00
0x0001
01
0x0002
02
0x0003
03
0x0004
04
0x0005
05
0x0006
06
0x0007
07
0x0008
08
Significado
String representando uma data no formato DDMMAA
String representando uma data no formato DDMM
String representando uma data no formato MMAA
String representando uma hora no formato HHMMSS
String representando um nmero
String representando uma senha que numrica
String representando um nmero com 4 dgitos
String representando um dado alfanumrico
String representando uma data no formato DDMMAAAA
LEMBRETE: utilizado apenas com a interface coleta.
Cdigos das Teclas

Durante o processamento da transao, a aplicao dever disponibilizar um meio que permita
que usurio prossiga, retorne ou cancele o processamento. No entanto, de acordo com o
momento do processamento, ou seja, conforme o estado da coleta de dados em que o SCOPE
Client se encontra, nem sempre estas trs opes estaro disponveis. Para que a aplicao
saiba qual(is) ao(es) ela deve disponibilizar ao usurio, ela deve utilizar o membro HabTeclas
99
da estrutura stPARAM_COLETA, aps a chamada funo ScopeGetParam(). O valor deste

campo a combinao binria (bitwise) de:
Cdigos Formato
Significado
Hexadeci Decimal
mal
0x0001
01
Tecla cancela habilitada
0x0002
02
Tecla prximo habilitada
0x0004
04
Tecla retorna habilitada
Ele dever ser verificado a cada iterao, logo aps a chamada funo (ver Obtendo os
parmetros da transao)
Cdigos de Fluxo
Num determinado momento, coletado o dado ou no, a aplicao dever informar ao SCOPE qual
ao que ele dever tomar (ver Passando o dado da coleta ao SCOPE Client). Esta ao est
associada s opes que o usurio pode tomar: avanar para o prximo estado, retornar para o
estado anterior ou cancelar a transao. Cada ao tem um cdigo amarrado a ela que se
encontra na tabela que segue.
Cdigos Formato
Hexadeci Decimal
mal
0x0000
00
0x0001
01
0x0002
02
0x0003
03
Significado
Prximo estado
Estado anterior
Cancelar
Erro na coleta de dados
Estados para interrupo

Na tabela abaixo esto relacionados os cdigos referentes aos estados de coleta, nos quais o
SCOPE poder ser suspenso (ver Suspendendo a transao).
ndice
0
1
2
3
4
5
6
7
8
9
10
11
12
Exit Point
Coleta do carto
Coleta da data de validade do carto
Montagem e envio da mensagem
Exibio de mensagens de no autorizao
Impresso do cupom
Recuperao dos servios vlidos
Coleta de CPF ou CGC
Resultado com transao cancelada
Resultado com transao autorizada
Coleta do nmero do banco
Coleta do nmero da agncia
Coleta do nmero do cheque
Coleta da data para depsito
100
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
33
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
Impresso de cheque
Escolha de pagamento vista
Escolha do plano de parcelamento da administradora de carto ou da loja
Escolha de pr-datado
Escolha de parcela vista
Coleta do intervalo de datas entre parcelas
Coleta de quantidade de parcelas
Decidindo o plano de financiamento
Coleta de nmero de dias ou da data de dbito
Decide se coleta a senha
Coleta de senha
Carrega da bandeira
Desfazimento de transao
Recuperao de dados de transao
Coleta o nmero de controle
Consistncia dos dados originais da transao (cancelamento)
Consistncia do carto
Montagem e envio da mensagem de pr-autorizao
Escolha da forma de pagamento (1 - cheque, 2 carn, 4 - C/C)
Coleta do valor da entrada (Valor Entrada ?)
Coleta do cheque da parcela ("Num Cheque Entrada ?" ou "Num Cheque Parcela ?)
Coleta do nmero da conta-corrente do cheque (Conta Corrente ?)
Encerramento da transao abortada
Decide se deve coletar os 4 ltimos dgitos
Coleta os ltimos 4 dgitos do carto
Verificao do carto e do servio localmente
Decide se a ltima transao
Recuperao do comprovante
Decide se consulta parcelas
Consulta de parcelas
Impresso de consulta
Decide de continua a transao
Exibe mensagem de erro
Exibe autorizado
Decide se coleta vista
Decide se coleta o tipo de financiamento ou a quantidade de parcelas
Decide se pr-datado ou parcelado
Decide se coleta se a parcela vista
Coleta carto para resumo de vendas
Decide se continua ou termina
Exibe continua
Exibe fim
Coleta o nmero do cheque de entrada
Decide se imprime cheque
Coleta a quantidade de dias
Coleta a quantidade de dias para a primeira parcela
Coleta a data para a primeira parcela
Carrega os atributos para pr-datado
Carrega os atributos de parcela com a primeira vista
Carrega os atributos dos dias entre parcelas
Carrega os atributos referentes s quantidades de parcela
Decide se coleta pr-autorizao
Coleta pr-autorizao
Coleta se confirma o dia do ms fechado
Carrega os atributos de parcela sem parcela vista
Decide se coleta o carto
Verifica o cheque
Imprime a nota promissria
101
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
Coleta a data da pr-autorizao

Coleta o CEP
Coleta o nmero da residncia
Coleta o complemento do endereo
Decide se consulta saque
Consulta saque
Decide se coleta o nmero do item
Coleta o plano de pagamento
Coleta ciclos a pular
Coleta o nmero do item
Decide se coleta o cdigo de segurana
Coleta o cdigo de segurana
Coleta a autorizao do supervisor
Coleta se o cdigo de segurana do carto est ausente ou ilegvel
Carrega os atributos de garantia pr-datado
Coleta se com ou sem garantia
Decide se aceita risco
Decide se coleta o valor do saque
Coleta o valor do saque
Consulta valores
Coleta o valor de recarga de celular
Verifica o valor de recarga
Coleta o cdigo de localidade do telefone
Coleta o nmero de telefone
Carrega a sugesto de recarga de celular
Verifica a transao
Coleta o dgito verificador do telefone
Decide se coleta a taxa de servio
Coleta a taxa de servio
Coleta data no formato DDMMAA
Decide se coleta data no formato DDMMAA
Deciso prvia do servio
Deciso prvia do servio de consulta
Deciso prvia do servio de extrato
Decide se haver saque
Decide se haver simulao de saque
Decide se saldo ou extrato
Decide o extrato resumido ou segunda via
Decide se coleta valor
Coleta valor
Decide se coleta a quantidade de parcelas
Valida dados
Exibe mensagem de erro
Coleta se quer consultar ou resgatar
Deciso prvia do servio de resgate
Coleta se resgate avulso
Desfazimento de risco pr-datado
Decide se coleta data no formato DDMMAAAA
Coleta data no formato DDMMAAAA
Verifica mensagem de advertncia
Exibe mensagem
Coleta cdigo de autorizao de medicamento
Coleta registro de medicamento
Obtm lista de medicamentos
Imprime cupom parcial
Coleta a quantidade de parcelas e aceita 1 parcela
Coleta o cdigo de barras
Decide se coleta vencimento
102
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
Coleta vencimento
Coleta o cdigo de consulta PBM
Coleta medicamento se receita
Coleta CRM do mdico
Coleta a UF do CRM do mdico
Decide se coleta seguro
Coleta seguro
Decide se coleta carto
Coleta se pagamento com carto
Coleta dados da Tokoro
Deciso prvia de financiamento pela administradora
Decide se quer pagar aps o vencimento
Decide se coleta a senha
Imprime o cupom promocional
Coleta se utiliza o saldo
Coleta o cdigo de material
Coleta o nmero do plano
Coleta se o pagamento em cheque
Coleta se confirma a transao
Verifica a no confirmao da transao
Decide se o pagamento no rotativo
Confirma o valor
Exibe garantia no autorizada
Coleta CMC7
Coleta se o pagamento em dinheiro ou carto
TEF Externa: coleta o cdigo do grupo de servio
TEF Externa: coleta o cdigo da rede
TEF Externa: coleta o cdigo do estabelecimento
TEF Externa: coleta o NSU do host
TEF Externa: coleta a data no formato DDMMAAAA
TEF Externa: verifica a transao
Decide se quer realizar uma consulta antes
Consultando
Coleta se continua aps a aprovao da conta
Coleta o cdigo de bandeira
Coleta se fatura
Verifica o cdigo de barras
Coleta a confirmao do valor
Decide se imprime cupom total ou parcial
Coleta valor total
Coleta se quer resumo do pagamento
Coleta RG
Decide retentativa
Coleta CPF
Coleta endereo
Coleta andar
Coleta nmero do conjunto
Coleta o bloco
Coleta o bairro
Coleta cdigo de autorizao ou carto
Coleta data da emisso do carto
Coleta o plano - Infocards
Coleta o nmero do cupom fiscal
Coleta a operadora
Coleta dados SAB
Coleta o nmero do telefone com o dgito verificador
Coleta dados da transao forada SAB
Decide o tipo de servio tcnico
103
194
195
196
197
198
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
Coleta o nmero da OS
Coleta o nmero de identificao do tcnico
Coleta cdigo da ocorrncia
Coleta cdigo da EPS credenciada
Go On Chip
Recupera as tabelas de PIN-Pad
Coleta confirmao positiva
Decide se coleta o valor da entrada
Decide se coleta o valor da 1 parcela
Coleta o valor da 1 parcela
Salva servio escolhido
Decide se consulta parcelas ou envia TEF
Decide se coleta Chip ou senha
Decide se coleta dados adicionais
Coleta dados adicionais
Decide se carrega bandeira ou consulta operadora
Consulta operadora
Decide se confirma valor no PIN-Pad
Transao cancelada pelo cliente
Decide se cancela transao
Coleta se cancela a transao
Coleta em andamento
Retirar o carto
Transao aprovada
Decide se coleta a taxa de embarque
Coleta a taxa de embarque
Coleta de carto em andamento
Exibe mensagem de saldo
Coleta carto digitado
Obtm servios
Exibe saldo no PIN-Pad
Encerra transao por erro
Coleta o cdigo do produto
Exibe mensagem recebida do PIN-Pad e retorna
Exibe mensagem de erro recebida do PIN-Pad e retorna
Exibe menu
Encerra menu
Encerra transao
Decide se INSS
Coleta contrato
Verifica CPF
Coleta data de membership do cliente
Recupera comprovante do servidor
Fornece valor
Recupera menu de cancelamento
Coleta dados da transao original
Retorna dados da transao original
Coleta nmero da autorizao original
Coleta data da transao original
Coleta NSU da transao original
Exibe dados de cancelamento
Decide as vias de reimpresso
Exibe mensagem rotativa
104
Cdigo das bandeiras

Como algumas transaes exigem, o operador deve escolher uma bandeira e passar para o
SCOPE o seu cdigo cuja relao se encontra abaixo. Para que o operador possa escolher,
necessrio que ele tenha uma lista com os cdigos de cada bandeira. Uma opo ter uma lista
impressa disponvel para o operador. No entanto, como geralmente nem todas as bandeiras so
utilizadas para uma determinada loja, pode ser vivel a aplicao, por meio de configurao,
exibir na tela uma lista de opes, somente com as bandeiras utilizadas, no momento que for
necessrio.
Cdigos Bandeira
Hexadeci Decimal
mal
0x0000
000
0x0001
001
0x0002
002
0x0003
003
0x0004
004
0x0005
005
0x0006
006
0x0007
007
0x0008
008
0x0009
009
0x000A
010
0x000B
011
0x000C
012
0x000D
013
0x000E
014
0x000F
015
0x0010
016
0x0011
017
0x0012
018
0x0013
019
0x0014
020
0x0015
021
0x0016
022
0x0017
0x0018
0x0019
0x001A
0x001B
0x001C
0x001D
0x001E
0x001F
0x0020
0x0021
0x0022
0x0023
0x0024
0x0025
023
024
025
026
027
028
029
030
031
032
033
034
035
036
037
Significado
SCOPE
Visa
Mastercard
Amex
Lojista
Dinners
Sollo
Cheque Eletrnico
Mastercard Maestro (conhecido tambm como Redeshop)
Ita
Bradesco
Fidelidade
Serasa
Telecheque
Cheque Cardpio (carto voucher da CSU)
BrasilCard (antiga RVA)
Ticket Alimentao
Hipercard
CardCo (antiga CNS)
MaxiCred
Banrisul
Visa Electron
Redecard (bandeira para operaes internas, independentes de
carto. Exemplo: Resumo de Vendas)
JCB
Quality Card
Unnisa
Fininvest
Multi-Cheque
VR (carto voucher da CSU)
TransCheck
TecBan (bandeira genrica para servios TECBAN)
ACC Card
Sorocred
Parati
BEM - Banco do Estado do Maranho
Tokoro
Zogbi
TopPremium
105
Cdigos Bandeira
Hexadeci Decimal
mal
0x0026
038
0x0027
039
0x0028
040
0x0029
041
0x002A
042
0x002B
043
0x002C
044
0x002D
045
0x002E
046
0x002F
047
0x0030
0x0031
0x0032
0x0033
0x0034
0x0035
0x0036
0x0037
0x0038
0x0039
0x003A
0x003B
0x003C
0x003D
0x003E
0x003F
0x0040
0x0041
0x0042
0x0043
0x0044
0x0045
0x0046
0x0047
0x0048
0x0049
0x004A
0x004B
0x004C
0x004D
0x004E
0x004F
0x0050
0x0051
0x0052
0x0053
0x0054
0x0055
0x0056
0x0057
0x0058
0x0059
0x005A
0x005B
048
049
050
051
052
053
054
055
056
057
058
059
060
061
062
063
064
065
066
067
068
069
070
071
072
073
074
075
076
077
078
079
080
081
082
083
084
085
086
087
088
089
090
091
Significado
Carrefour (carto voucher da CooperCred)
Rainbow (carto voucher da TecBan)
Telesp Celular
Policard
Via Financeira
IBI
e-Pharma (PBM)
Vidalink (PBM)
PrevSaude (PBM)
e-Pharma balco (solicitao de autorizao via conexo direta com
ScopeGW.)
Aura
Correspondente bancrio Unibanco
Correspondente bancrio Citibank
Recebimento Fininvest
Multi-Benefcios
VA Eletrnico (carto alimentao)
Valetik
Losango
Goodcard
FIC
Banestik (carto voucher da TecBan)
Cabal
TMS
Bonus (carto voucher)
Visa Vale
Correspondente bancrio Banco do Brasil
Colaborador (carto de crdito do SONAE)
Correspondente bancrio Banco de Boston
Portal Card
Vale Card
Personal Card
Green Card
AsCard
Evangelico
Funcional card (PBM)
ACSP - Associao Comercial de So Paulo
ExtraBom/ABN
Ediguay
GoodMed (PBM)
Bnus Eletrnico (carto voucher do SONAE)
RefeiSul
Multi-Alimentao
Multi-Cheque (Novo)
CheckCheck
EcxCard
BigCard
SuperCard
Banese - Banco do Estado de Sergipe
Novartis (PBM)
FlexMed (PBM)
TrnCentre - Transaction Centre
InfoCards
BaseCard
SysData
106
Cdigos Bandeira
Hexadeci Decimal
mal
0x005C
092
0x005D
093
0x005E
094
0x005F
095
0x0060
096
0x0061
097
0x0062
098
0x0063
099
0x0064
100
0x0065
101
0x0066
102
0x0067
103
0x0068
104
0x0069
105
0x006A
106
0x006B
107
0x006C
108
0x006D
109
0x006E
110
0x006F
111
0x0070
112
0x0071
113
0x0072
114
0x0073
115
0x0074
116
0x0075
117
0x0076
118
0x0077
119
0x0078
120
0x0079
121
0x007A
122
0x007C
124
0x007D
125
0x007E
126
0x007F
127
0x0080
128
0x0081
129
0x0082
130
0x0083
131
0x0084
132
0x0085
133
0x0086
134
0x0087
135
0x0088
136
0x0089
137
0x008A
138
0x008B
139
0x008C
140
0x008D
141
0x008E
142
0x008F
143
0x0090
144
0x0091
145
0x0092
146
0x0093
147
Significado
Correspondente bancrio Bradesco
Ticket Restaurante
ValeCash
BankCard
MedCheque
Premium (carto de crdito do SONAE)
Vale Gs
Datasus (PBM)
BankTec
PoupCard
ChequePre
Banquet (carto voucher alimentao)
Private Label da Redecard
Private Label da Visanet 4.1
Rancho Convnio - PortalCard
Rancho Alimentao - PortalCard
PlanVale
IBICard
IBI PL,
Pague-Conta Visanet
Carto Fcil (EPA)
Carto Fcil Losango (EPA)
CPF - IBI PL deposito CDB
ComproCard
FarmaSeg (PBM)
Unik
Verde Card
Rossi
Somar
Solucard
Banquet Smart
Planvale Redecard
Obo Card
DaCasa
CABAL Vale (TECBAN e GETNET 6.0)
CABAL Dbito (TECBAN e GETNET 6.0)
BRTelecom Telefonia FIXA
Brasil Telecom
GoodVale (GETNET 6.0 Voucher)
Pleno Card
PratiCard
PrestaServ
Safra Amanco
SimCred
Premiao SONAE
Presente SONAE
ValeShop
PREZUNIC
FAI/Orbital
ConvCard
Operadora Claro
Operadora OI
Operadora TIM
Operadora Telemig
Operadora Amaznia Celular
107
Cdigos Bandeira
Hexadeci Decimal
mal
0x0094
148
0x0095
149
0x0096
150
0x0097
151
0x0098
152
0x0099
153
0x009A
154
0x009B
155
0x009C
156
0x009D
157
0x009E
158
0x009F
159
0x00A0
160
0x00A2
162
0x00A3
163
0x00A5
165
0x00A6
166
0x00A7
167
0x00A8
168
0x00A9
169
0x00AA
170
0x00AB
171
Significado
Operadora Embratel
Operadora Telefonica
Operadora TELEMAR
Operadora CTBC-Celular
Operadora CTBC Fixo
Operadora SERCOMTEL Celular
Operadora SERCOMTEL Fixo
Operadora Telefonica Famlia
Operadora NEXTEL
Operadora VIVO
Carto Parcele Mais (REDECARD L0401)
BANPARA
NEUS
Credi-Shop
Sapore
Verocheque
Getnet
PHARMALINK PBM
Aura FNAC
Aura BERGAMAIS
Com Voc
BANESCARD
Dados disponveis das transaes

Abaixo est a relao dos campos disponveis que podem ser obtidos das transaes pela funo
Mscara 1
ScopeObtemCampoExt().
Campo de Dados
PAN Personal Account Number (nmero do carto)
Valor da transao
NSU (Nmero Seqencial nico) da transao
Hora local da transao
Data local da transao
Data de validade do carto
Data contbil da transao
Nmero do cheque
Cdigo de autorizao
Cdigo de resposta
Identificao do terminal
Cdigo do estabelecimento (contrato)
Nmero de parcelas
Taxa de servio (gorjeta)
NSU do Host
Nmero do banco
Nmero da agncia
Data de agendamento
Cdigo da bandeira
Cdigo do Servio (*)
Contedo do BIT 62
Nmero do controle
Cdigo de rede
Nome da bandeira
108
Valor do Bit
0x00000001
0x00000002
0x00000004
0x00000008
0x00000010
0x00000020
0x00000040
0x00000080
0x00000100
0x00000200
0x00000400
0x00000800
0x00001000
0x00002000
0x00004000
0x00008000
0x00010000
0x00020000
0x00040000
0x00080000
0x00100000
0x00200000
0x00400000
0x00800000
Mscara 2
Nome da Rede
Trilha 02 do carto
Nmero de notas promissrias
Cdigo de estabelecimento Visanet
Cdigo CMC7
CGC do convnio PBMS
Mensagem de autenticao do cheque
Saldo disponvel (carto convnio)
NSU da transao original
Cliente aderente ao seguro (IBICred)
Dados do parcelado da rede Cetelem
Data do movimento (Interchange, BBGCB)
Nome do cedente ou empresa de convnio (Interchange, BBGCB)
Lista das formas de pagamento em TEF permitidas (Interchange)
Linha de autenticao (Interchange Fininvest)
Dados da consulta de fatura (Interchange Fininvest) (Vide ScopeApi.h)
Formas de financiamento (A: Administradora E: Estabelecimento)
Cdigo especfico da consulta AVS
Pontos adquiridos ou resgatados
Fator de compra
NSU do Host da transao original (estornada)
Identificao do cliente PBM junto autorizadora (apenas Vidalink)
Cdigo da operadora de celular
Cdigo de rea (DDD)
Nmero do telefone
ULTRAGAZ: dados do ValeGs
Cdigo IF (Instituio Financeira)
Nmero do item da Fininvest ou Cetelem, ou nmero do contrato
(CPCHEQUE/INSS) do IBI
Valor da taxa de embarque
Uso exclusivo do SONAE
Informao contida no bit 124 - CDC Orbitall
Cdigo de servio da transao original (estorno)
Cdigo de barras
Permite desfazimento
Grupo de Servios
Nesta tabela encontram-se os grupos de servios que o SCOPE trabalha.
Cdigos Bandeira
Hexadeci
Decimal
mal
0x0001
001
0x0002
002
0x0003
003
0x0004
004
0x0005
005
0x0006
006
0x0007
007
0x0008
008
0x0009
009
0x000A
010
0x000C
012
0x000E
014
0x000F
015
0x0010
016
0x0011
017
0x0012
018
Significado
Carto de dbito
Carto de crdito
Consulta a cheques
Controle SCOPE/Autorizador
Controle API/Server
PAT
CDC
Garantia de desconto de cheques
Resumo de vendas
IATA para companhias areas
Fidelidade
Recarga de celular
Transao financeira
Investimento
Medicamento
109
0x01000000
0x02000000
0x04000000
0x08000000
0x10000000
0x20000000
0x40000000
0x80000000
0x00000001
0x00000002
0x00000004
0x00000008
0x00000010
0x00000020
0x00000040
0x00000080
0x00000100
0x00000200
0x00000400
0x00000800
0x00001000
0x00002000
0x00004000
0x00008000
0x00010000
0x00020000
0x00040000
0x00080000
0x00100000
0x00200000
0x00400000
0x00800000
0x01000000
0x02000000
Cdigos Bandeira
Hexadeci
Decimal
mal
0x0013
019
Significado
Pagamento de conta
Cdigos dos Servios

Alm dos grupos de servios, o SCOPE trabalha com o conceito de servios. Estes servios esto
na tabela abaixo.
Cdigo de
servio
006
009
013
017
018
020
021
022
023
024
027
028
031
032
034
035
036
037
039
040
041
042
043
044
045
047
048
050
051
056
058
059
060
061
062
063
064
065
068
069
070
071
072
073
074
075
Descrio
Compra com carto de dbito vista
Compra com carto de crdito vista
Pr-Autorizao com carto de crdito
Consulta de cheques a vista
Consulta de cheques pr-datados
Compra com carto de dbito vista forada
Compra com carto de dbito pr-datada
Compra com carto de dbito parcelada sem parcela vista
Compra com carto de dbito parcelada parcela vista
Compra com carto de dbito parcelada parcela vista forada
Compra com carto de crdito parcelado pela administradora
Compra com carto de crdito parcelado pelo estabelecimento
Cancelamento de compra de dbito
Cancelamento de compra de crdito
Compra CDC (CNS)
Garantia de cheques
Desconto de cheques
Solicitao de resumo de vendas
Compra com carto de crdito IATA
Compra com carto de crdito IATA parcelado com juros
Compra com carto de crdito IATA parcelado sem juros
Cancelamento de compra de credito IATA
Cancelamento compra com carto CDC
Consulta planos de pagamento para carto CDC
Compra com carto CDC
Consulta parcelas de crdito
Consulta parcelas de dbito
Compra com carto de dbito Voucher (Alimentao)
Cancelamento de compra com carto de dbito Voucher (Alimentao)
Cancelamento de garantia de cheque
Consulta AVS
Cash
Cancelamento de Cash
Confirmao de Pr-Autorizao
Estorno de Pr-Autorizao
Fidelidade
Consulta saldo de crdito
Consulta Cash
Consulta valores possveis de recarga de celular
Recarga de celular
Consulta saldo
Consulta extrato resumido
Consulta extrato
Simulao de saque
Saque
Consulta saldo de investimento
110
076
077
078
079
080
081
082
083
084
085
086
087
088
089
090
091
092
093
094
095
096
097
098
099
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
118
Consulta extrato de investimento

Resgate avulso
Resgate
Cancelamento de saque
Cancelamento de resgate
Obtm carto de investimento
Consulta medicamento
Compra medicamento
Estorno compra medicamento
Pagamento de conta com carto
Solicitao de autorizao
Pagamento de conta sem carto
Dbito Voucher parcelado
Consulta pagamento de conta
Estorno de pagamento de conta
Pagamento de fatura
Consulta Saldo Dbito
Resumo de Pagamentos
Baixa de O.S.
Teste de Comunicao
Estatstica
Moedeiro
Compra com Carto Dinheiro
Estorno da compra com Carto Dinheiro
Consulta Contrato
Saque INSS
Saque Cpcheque
Consulta Vale Gs
Compra de Cheque Pr-Datada
Depsito CDB
Resgate CDB
Estorno de Depsito CDB
Estorno de Resgate CDB
Compra com Carto de Crdito com juros
Carga de Carto Dinheiro
Consulta Saldo do Carto Dinheiro
Estorno da Carga de Carto Dinheiro
Parcele Mais
Estorno do Parcele Mais
Transao Off-line
Troco Surpresa (Chance Legal)
Convnios
As transaes relacionadas s transaes de PBM exigem o cdigo das redes, as quais so
listadas abaixo.
Cdigos do Convnio
Hexadeci
Decimal
mal
0x0001
0001
0x0002
0002
0x0003
0003
0x0004
0004
0x0005
0005
0x0006
0006
0x0007
0007
0x0008
0008
Significado
E-Pharma
Vidalink
PrevSaude
Funcional Card
GoodCard
Novartis
FlexMed
DataSUS
111
Cdigos do Convnio
Hexadeci
Decimal
mal
0x0009
0009
0x000A
0010
Significado
FarmaSeg
Pharmalink
112
Apndice B Especificao Visanet 4.1

_____________________________________________________________________________________________________
Com a nova especificao da Visanet, denominada Visanet 4.1, as automaes j integradas ao

SCOPE necessitaro se readequar e se certificar perante a Visanet. Este apndice descreve as
alteraes necessrias.
Adequao
Para suportar a Visanet 4.1, os pinpads tero seu firmware atualizado. Os pinpads atualizados
so denominados pinpads compartilhados. Este novo firmware compatvel com as verses
atuais, ou seja, tambm suporta as funes antigas de acesso ao pinpad realizada pela biblioteca
PPVISA da Visanet, e que eram utilizadas pelas aplicaes de PDV. No entanto, quando o
SCOPE estiver configurado para trabalhar com o pinpad compartilhado, o acesso ao pinpad ser
feito pelo SCOPE e no mais pelas aplicaes de PDV.
Abaixo seguem algumas funcionalidades da Visanet 4.1 que exigiro adequao por parte da
aplicao de PDV:
Transao de venda crdito vista ou parcelada.
Transao de venda dbito vista, parcelada e pr-datada. Esta funcionalidade tambm

contempla o Vale Alimentao e o Vale Refeio. Assim atende as operaes da Visanet
como prestadora de servios de Acquirer para os produtos Visa Vale e Valetik. Vinculado
transao de dbito vista, o produto Compre & Saque possibilita ao portador a
realizao de saque em dinheiro. Durante o fluxo de coleta, desde que habilitado pela
rede,
SCOPE
solicitar
valor
do
saque
atravs
do
estado
TC_COLETA_VALOR_SAQUE (0xFC2D).
O cancelamento de venda pode ser feito quando ocorrerem erros na digitao (valor, data
de agenda, nmero de parcelas etc.) ou desistncia da compra por parte do cliente,
sendo necessrio informar os dados da transao original a ser cancelada.
Reimpresso de comprovante. Esta funo possibilita ao lojista a impresso de uma nova

cpia do comprovante da ltima transao realizada ou alguma especfica, desde que
tenha sido aprovada e se encontre no log do Concentrador TEF, funcionando como
soluo para o caso da existncia de algum problema com a impresso original.
Pagamento de contas. Possibilidade de pagamento de contas de concessionrias com

carto Visa Electron em estabelecimentos comerciais afiliados a Visanet (rede de
farmcias, supermercados e estabelecimentos de varejo). Somente sero permitidas
transaes de dbito vista.
Pr-autorizao de crdito. No momento que esta transao aprovada, a administradora

de crdito sensibiliza o limite do carto, de acordo com o valor informado, como forma de
reserva e garantia ao Comrcio Usurio que no momento de receber efetivamente o
pagamento da despesa. Atualmente somente hotis e locadoras so autorizados para
utilizao da Pr-Autorizao.
113
Consulta CDC. Consulta direta ao banco emissor, possibilita o acesso a taxas aplicadas
no momento da inteno de compra.
AVS. Transao utilizada para verificao do endereo de envio da fatura do portador do

carto. Estes dados so informados pelo mesmo em uma compra feita atravs de carto
no presente.
Pagamento de Fatura cartes Private Label.
Certificao
Uma vez que a aplicao de PDV cumpra as adequaes mencionadas anteriormente, ela deve
ser certificada pela Visanet.
A certificao deve ser agendada com a Itautec S.A., atravs do e-mail apoioscope@itautec.com,
e consiste em:
Pr-homologao: realizada pela Itautec;
Homologao: realizada pela Visanet ou por empresa designada por ela.
114
Apndice C PIN-Pad Compartilhado

_____________________________________________________________________________________________________
IMPORTANTE: Este tpico deve ser considerado apenas pela automao que utiliza a
interface coleta do SCOPE.
Abaixo segue alguns aspectos para integrao com SCOPE na interface coleta:
O SCOPE ser responsvel por toda a interao com o PIN-Pad Compartilhado num
processo de TEF;
Quando configurado o PIN-Pad Compartilhado no ScopeCNF, o SCOPE no retornar

mais para a aplicao de PDV alguns estados de coleta, pois estes estados sero
executados internamente pelo SCOPE. Os estados so:
TC_CARTAO
TC_COLETA_AUT_OU_CARTAO
TC_SENHA
TC_DECISAO_CONT
A aplicao ter a possibilidade de interromper a interao do SCOPE com o PIN-Pad.

Para isto a Aplicao PDV dever:
o
Executar a funo ScopeConfigura sinalizando que a aplicao PDV utilizar tal

recurso (ver Configuraes gerais);
Quando configurado, o SCOPE na leitura do carto ir devolver o cdigo

TC_COLETA_CARTAO_EM_ANDAMENTO (0xFCFC) e durante as demais
interaes com o PIN-Pad devolver o cdigo TC_COLETA_EM_ANDAMENTO
(0xFCFD) atravs da funo ScopeStatus. Neste momento, a aplicao de PDV
poder decidir se continua ou interrompe o processo;
Para continuar o processo, a aplicao de PDV dever executar a funo

ScopeResumeParam() com o parmetro PROXIMO_ESTADO (0x00), e para
cancelar, CANCELAR (0x02).
Observao: O SCOPE devolver os cdigos TC_COLETA_EM_ANDAMENTO

(0xFCFD) e TC_COLETA_CARTAO_EM_ANDAMENTO (0xFCFC) ao menos
uma vez por segundo.
Para a aplicao de PDV cancelar uma leitura de carto no PIN-Pad e realizar uma
transao digitada, nos casos permitidos, sero oferecidas as seguintes opes:
o
Durante a coleta do carto, se for acionado a tecla Cancela no PIN-Pad;
E se no estado TC_COLETA_CARTAO_EM_ANDAMENTO (0xFCFC) for

executada a funo ScopeResumeParam, com o parmetro CANCELA.
Se ocorrer uma das opes acima, o SCOPE devolver o estado de coleta

TC_CARTAO_DIGITADO (0xFC85) para receber da aplicao de PDV o nmero do
carto digitado.
115
No arquivo scope.ini poder ser desabilitado as opes acima - digitao do carto (ver
Sesso [PPCOMP]). Opcionalmente, a aplicao de PDV tambm poder utilizar a funo
ScopeConfigura() para o mesmo fim.
O SCOPE tambm disponibilizar a funo ScopeValidaInterfacePP() que possibilitar a

aplicao de PDV validar se est utilizando a mesma interface de acesso ao PIN-Pad que
o que est configurado no SCOPE.
116
Apndice D Conjunto de bibliotecas do SCOPE Client

_____________________________________________________________________________________________________
Neste apndice, relacionamos o conjunto de bibliotecas e arquivos que compe o ambiente em

que se localiza o SCOPE Client para cada sistema operacional e linguagem.
MS-WINDOWS
Para a maioria dos ambientes de programao, as bibliotecas necessrias para a execuo do
SCOPE Client em MS-Windows so:
CMC7.DLL
COMVERIFONE.DLL
CSMSG.DLL
ECF4000.DLL
ECNF.DLL
PINPAD.DLL
PPDIOW32.DLL
PPGERW32.DLL
PPINGW32.DLL
PPSLBW32.DLL
PPVFNW32.DLL
PPW32.DLL
SCOPEAPI.DLL
SCOPECLT.DLL
SCOPECNX.DLL
SCOPECOM.DLL
SCOPEECF.DLL
SCOPEISO.DLL
SCOPELIB.DLL
SCOPEPRF.DLL
SCOPEREG.DLL
SCOPETCP.DLL
scope.ini
Linguagem Java
Aplicativos de PDV escritos em Java, alm das bibliotecas citadas acima, tambm precisam das
seguintes:
PINPADJAVA.DLL
PINPADJAVA.JAR
SCOPEJAVA.DLL
SCOPEJAVA.JAR
117
Linux
Os ambientes executados no sistema operacional Linux precisam das seguintes bibliotecas:
libScopeApi.so
libScopeCom.so
libScopeSerial.so
libSenha.so
scope.ini
Linguagem Java
Como acontece em MS-Windows , o aplicativo de PDV escrito em Java tambm precisa das
seguintes bibliotecas:
libPinpadJava.so
pinpadjava.jar
libScopeJava.so
scopejava.jar
118
Apndice E Identificando a verso do SCOPE Client

_____________________________________________________________________________________________________
Antes de atualizar o SCOPE Client ou reportar um problema para a Itautec S.A. muitas vezes
necessria no s a verificao da verso do SCOPE Server, mas tambm do SCOPE Client.
Abaixo exibimos as diversas formas de verificar a verso do SCOPE Client.
Verificando no SCOPE Server

A verificao da verso do SCOPE Client no Server, cuja tela exibida na figura 8, simples.
Basta clicar no PDV cuja verso do SCOPE Client deseja-se consultar, e clicar no boto PDV:
<empresa>/<filial>/<PDV>.
Figura 8: janela principal do servidor SCOPE
A janela similar a da figura 9 ser apresentada. Alm de outras informaes, nela est a verso
do SCOPE Client representado no campo ScopeAPI (neste exemplo vemos 2.25.07.01). Percebese que embora tenha clicado num PDV especfico na janela principal do servidor SCOPE, a janela
com as informaes do PDV possibilita a consulta de outros PDVs pelo campo Emp. Filial Pdv.
119
Figura 9: informaes adicionais do PDV
IMPORTANTE: na consulta da verso do SCOPE Client no preciso que este esteja

conectado no servidor, mas obrigatrio que ele o tenha feito ao menos uma vez desde o
start do servidor SCOPE.
Verificando no ambiente do PDV

No necessrio ter acesso ao servidor SCOPE para consulta da verso do SCOPE Client e s
vezes, por poltica da empresa, nem todo colaborador tem acesso ao servidor. Para estes casos,
deve-se verificar a verso do SCOPE Client no prprio ambiente do PDV.
SCOPE Client para MS-Windows

Para isso, deve-se conhecer o local de instalao das DLLs do SCOPE. Localize a biblioteca
ScopeAPI.dll e abra a janela de propriedades do arquivo (clicando nela com o boto direito e na
opo Propriedades). A janela Propriedade de ScopeAPI.dll ser aberta. Clique na aba
Verso e ser possvel visualizar informaes como na figura 10. No campo Verso do
arquivo: encontra-se a verso do SCOPE Client (no exemplo vemos 2.25.7.1, que a mesma
do exemplo da sesso anterior).
120
Figura 10: janela de propriedade de ScopeAPI.dll
SCOPE Client para Linux

Em Linux, no prprio nome das bibliotecas j est a verso. Elas normalmente so instaladas no
diretrio /usr/lib (ver Instalao do SCOPE Client para Linux), bastando a listagem dos
arquivos do SCOPE. Execute:
$ ls libScope*
As bibliotecas e seus versionamentos so definidos da seguinte forma:
libScopeApi.so.<a>.<bbb><cc>.<dd>
libScopeCom.so.<a>.<bbb><cc>.<dd>
libScopeJava.so.<a>.<bbb>.<e>
, onde:
<a> a verso da interface do SCOPE Client, cuja alterao deste implica em

incompatibilidade entra as bibliotecas (exemplo: alterao de parmetros de funes ou
nomes de constantes). Este item faz parte do soname utilizado em Linux com shared
libraries para prover informao de compatibilidade.
<bbb> a verso e o release do produto SCOPE. Esta verso representada sem o

ponto como, por exemplo, 225 o SCOPE 2.25.
<cc> a verso do pacote do SCOPE. Perceba que no h ponto separador entre a

verso, o release e o pacote.
<dd> o build do pacote.
<e> a verso da camada de interface Java.
121
Um exemplo da sada gerada por esse comando est na figura 11. No exemplo, apresentada a
verso 2.25.07.01.
Figura 11: visualizando a verso do SCOPE Client na linha de comando do Linux
122
Apndice F - Glossrio
_____________________________________________________________________________________________________
Endereo IP (Internet Protocol): trata-se de uma
tecnologia que permite a comunicao padronizada
Acquirer: veja Adquirente
plataformas diferentes, cada mquina possui um
Adquirente: a entidade ou associao de entidades
endereo IP que a diferencie das demais.
financeiras que a partir de transaes efetuadas com
Estabelecimento: ou estabelecimento comercial a
cartes nos estabelecimentos comerciais (Merchant)
entidade que aceita o carto (card acceptor) como
associados, estabelece o devido vnculo com as
forma de pagamento referente comercializao de
entidades autorizadoras (authorizing agent) (VISA,
um bem ou servio prestado ao portador do carto
MasterCard, Amex).
(card holder).
entre computadores, mesmo que estes sejam de
Aplicao frente de caixa: software executado no

PDV com a finalidade de realizar a venda de produtos
da empresa.
Aplicao de PDV: veja Aplicao frente de caixa.
Grupo de servio: um servio no SCOPE pertence
Authorizing agent: veja Autorizador
sempre a um grupo, que pode definir a forma de
Autorizador: a organizao (VISA, MasterCard,
pagamento, ou ainda, a tecla finalizadora do PDV.
Amex) que gerencia e controla operaes com cartes
Exemplos: carto de crdito, carto de dbito, consulta
de crdito, passando informaes entre o Adquirente e
de cheque, recarga de celular, estorno. Ver Servio.
o Banco emissor.
GUI: do ingls Graphic User Interface que a

interface grfica exibida para o usurio da aplicao.
B
Banco de dados: tambm conhecido como base de
dados, so arquivos ou sistemas com uma estrutura
I
Issuer: Veja Banco emissor.
regular que organizam informaes. Essas estruturas

podem ter a forma de uma tabela: cada tabela
composta por linhas e colunas. As informaes
utilizadas para um mesmo fim so agrupadas em uma
PDV: acrnimo para Ponto de Venda. Terminal
base de dados.
inteligente utilizado na operao de pagamento. Veja
Bandeira: entidade detentora de marcas e logotipos
tambm PoS.
utilizados em cartes de crdito, dbito e outros meios
PoS: termo em ingls Point of Sale. Veja tambm
de pagamentos. Exemplos: Visa, Mastercard, American
PDV.
Express, Visa Electron, Maestro, Cheque Eletrnico.

Banco emissor: a entidade financeira associada a
uma ou mais organizaes autorizadoras e que
responsvel pela emisso de cartes para seus
Rede
clientes.
recebimento
BIN
(bank
identification
number):
nmero
de
identificao do banco representado pelos primeiros 6
autorizadora:
de
transaes
que
TEF
concentra
de
diversos
estabelecimentos, e as autoriza atravs de um sistema

autorizador. Exemplos: Visanet, Redecard, TecBan.
dgitos do carto.
empresa
123
SCOPE:
SCOPE
soluo
Itautec
para
pagamentos eletrnicos
ScopeCNF (SCOPE Configurador):
Servio: o termo servio no contexto do SCOPE define

o objetivo de uma transao. Exemplos: compra com
o mdulo
carto de crdito vista, compra com carto de crdito
responsvel pela configurao e cadastramento de
parcelada pelo estabelecimento (sem juros), compra
parmetros para a soluo SCOPE.
com carto de crdito parcelada de administradora
SCOPE Client: conjunto de bibliotecas localizadas na
(com juros), compra com carto de dbito vista,
mquina em que a aplicao de frente de loja. O
compra com carto de dbito pr-datado, compra com
conjunto de bibliotecas pode variar conforme o sistema
carto de dbito voucher, consulta cheque, estorno
operacional e a linguagem de programao utilizada.
crdito, estorno dbito.
ScopeGW (SCOPE Gateway): funciona como um
Servidor: o computador que administra e fornece
roteador de mensagens entre um ou mais servidores
programas e informaes para os outros computadores
SCOPE e uma ou diversas redes.
conectados em rede.
ScopeSRV (SCOPE Server): o mdulo principal da

soluo SCOPE. responsvel por estabelecer o
contato inicial de todos os contratos cadastrados na
base de dados com as respectivas redes, garantindo
TSR: abreviao do termo em ingls Terminate and
tambm o fluxo de transaes com estas redes
Stay Resident. Veja Mdulo residente.
124
2009
Esse documento propriedade da Itautec S.A. Grupo Itautec.
Tem carter tcnico/informativo. Todos os direitos so reservados.
No pode, no todo ou em parte, ser copiado, fotocopiado, reproduzido, traduzido ou reduzido a qualquer meio eletrnico
ou forma legvel por mquina, sem a autorizao escrita da I t a u t e c S . A . - G r u p o I t a u t e c .
Esta se reserva, por outro lado, o direito de alterar seu contedo e forma, sem qualquer aviso prvio.
Produzido no Brasil.
125

Manual Desenvolvedor Scope

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Manual Desenvolvedor Scope

Enviado por

Direitos autorais:

Formatos disponíveis

Soluo Completa de Pagamento Eletrnico

Leia antes de utilizar o software:

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

Equipe Desenv. SCOPE

Acrscimo do captulo Totalizao de TEF

Equipe Desenv. SCOPE

Funes da biblioteca compartilhada de PIN-Pad

Apndice B includa a certificao com a Visanet 4.1

Paulo dos Santos

Paulo dos Santos

Reviso do texto, incluso de informaes no fluxo de

comprovante, e acrscimo do texto para deixar

Paulo dos Santos

Atualizao da tabela das bandeiras.

Paulo dos Santos

Atualizao da tabela das bandeiras.

Paulo dos Santos

Paulo dos Santos

Celso Hiroshi Nakata

Celso Hiroshi Nakata

texto referente CDC.

Detalhamento do novo estilo versionamento para as

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

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

Funes bsicas da API do SCOPE Client .................................................................... 18

Funes de configurao de ambiente.......................................................................... 25

Funes especficas das interfaces ............................................................................... 27

Carto de crdito .......................................................................................................................................... 35

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

Recarga de celular ........................................................................................................... 44

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

PBM - Medicamentos ....................................................................................................... 59

Funes de PIN-Pad ........................................................................................................ 64

Lendo a senha aberta ............................................................................................................................... 69

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

Funes diversas ............................................................................................................ 79

Apndice A Tabelas ...................................................................................................... 91

Apndice B Especificao Visanet 4.1...................................................................... 113

Apndice C PIN-Pad Compartilhado ......................................................................... 115

MS-WINDOWS ......................................................................................................................................... 117

Apndice E Identificando a verso do SCOPE Client .............................................. 119

Verificando no ambiente do PDV ............................................................................................................... 120

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

Figura 3: rvore do SCOPE no registro do MS-Windows ........................................................................18

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

Facilita a gesto do negcio, pois oferece ferramentas de consulta e relatrios

Permite a gesto da sesso contbil, pelo estabelecimento ou pelo centro de

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

compem uma transao completa e bem sucedida so demonstradas na figura 1 e descritas

9604 mensagem de solicitao da pr-TEF: esse tipo de mensagem geralmente

9614 mensagem de resposta da pr-TEF. Contem os dados solicitados pelo SCOPE

0200 mensagem de solicitao da transao financeira. Neste momento, a mensagem

0210 mensagem de resposta da transao financeira. A autorizadora responde a

0202 mensagem de confirmao da transao financeira. Esta mensagem a que

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

Fluxo de estados de coleta

Exemplificando: Ao iniciar uma transao de crdito, o SCOPE estar no estado de coleta

Interfaces de interao com o SCOPE Client

Caractersticas da interface coleta

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

(figura 2). Est disponvel apenas para aplicaes MS-Windows de 32-bits.

Figura 2: janela do SCOPE Client na interface HLAPI