Você está na página 1de 125

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

Jailton da S. C. Santana

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

Jailton da S. C. Santana

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

Jailton da S. C. Santana

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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
5

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


SCOPE Client para MS-Windows ........................................................................................................ 120
SCOPE Client para Linux ........................................................................................................................ 121

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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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).

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de retorno.

Exemplo
...
retorno = ScopeClose ();
...

Sesso de transao
Sesso de TEF
O conceito de sesso de TEF existe para garantir a integridade de uma operao. Desta forma,
entre a abertura e encerramento da sesso, todas as atividades includas na respectiva operao
(autorizao da transao, impresso de comprovante) devero ser completamente realizadas.
Este mecanismo permite que em caso de falha (queda de energia), a operao possa ser
desfeita. Isso corresponde a imprimir corretamente o cupom de TEF e garantir que a falha
ocorrida no atrapalhe no funcionamento da aplicao.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
20

Prottipo
LONG EXPORT ScopeAbreSessaoTEF (void)

Parmetros
No h parmetro.

Retorno
Ver tabela de cdigo de 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)
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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;
...
// Conecta ao servidor do SCOPE
...
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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;
...
// Conecta ao servidor do SCOPE
...
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;

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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
}
...

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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
Ver tabela de cdigo de retorno.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de retorno.

Exemplo
...
// Conexo ao ScopeSRV bem sucedida
...
retorno = ScopeSetAplColeta();
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
27

...

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


Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de retorno.

Exemplo
...
// executa transao (crdito, dbito, etc.)
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de retorno.

Exemplo
...
// executa transao (crdito, dbito, etc.)
char *dados[128];
WORD modo_entrada;
...
// inicia iterao
cod_coleta = ScopeStatus();
if(cod_coleta != 0xFE00)
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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().

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

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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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
Ver tabela de cdigo de 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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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)

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

[in]

String

TxServico

Valor da taxa de servio

Retorno
Ver tabela de cdigo de 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

Valor da transao com a vrgula implcita


(exemplo: R$ 123,00 = 12300)

TxServico

Valor da taxa de servio

Retorno
Ver tabela de cdigo de 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 = ScopeConsultaCredito(valor, taxa);
...
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
36

// processa a transao
...
// 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
Ver tabela de cdigo de retorno.

Exemplo
...
// abre sesso
...
retorno = ScopeConsultaSaldoCredito();
...
// processa a transao
...
// 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

Valor da transao com a vrgula implcita


(exemplo: R$ 123,00 = 12300)

TxServico

Valor da taxa de servio

Retorno
Ver tabela de cdigo de retorno.

Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
37

...
// obtm o valor da compra e armazena em valor
// obtm a taxa de servio e armazena em taxa
// abre sesso
...
retorno = ScopePreAutorizacaoCredito(valor, taxa);
...
// processa a transao
...
// 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

Valor da transao com a vrgula implcita


(exemplo: R$ 123,00 = 12300)

Retorno
Ver tabela de cdigo de retorno.

Exemplo
...
char valor[12 + 1];
...
// obtm o valor da compra e armazena em valor
...
// abre sesso
...
retorno = ScopeCompraCartaoDebito(valor);
...
// processa a transao
...
// fecha a sesso
...

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Valor da transao com a vrgula implcita


(exemplo: R$ 123,00 = 12300)

TxServico

Valor da taxa de servio

Retorno
Ver tabela de cdigo de 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 = ScopeConsultaCDC(valor, taxa);
...
// processa a transao
...
// 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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.
Como as outras transaes, o fluxo de processamento similar.

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

Parmetros
[in]

WORD

Servico

Para efetuar a operao de Compra/Carga


de carto dinheiro usar o servio 110
S_CARGA_CARTAO_DINHEIRO

[in]

String com o
mximo de 12
dgitos

Valor

Valor da transao com a vrgula implcita


(exemplo: R$ 123,00 = 12300)

Retorno
Ver tabela de cdigo de retorno.

Exemplo
...
Long servico = S_CARGA_CARTAO_DINHEIRO; // valor de 110
char valor[12 + 1];
...
// obtm o valor da compra e armazena em valor
// abre sesso
...
retorno = ScopeCartaoDinheiro(servio, valor);
...
// processa a transao
...
// fecha a sesso
...

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.
Como as outras transaes, o fluxo de processamento similar.

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

Parmetros
[in]

WORD

Servico

Para efetuar a operao de Compra/Carga


de carto dinheiro usar o servio 98
S_COMPRA_CARTAO_DINHEIRO

[in]

String com o
mximo de 12
dgitos

Valor

Valor da transao com a vrgula implcita


(exemplo: R$ 123,00 = 12300)

Retorno
Ver tabela de cdigo de retorno.

Exemplo
...
Long servico = S_COMPRA_CARTAO_DINHEIRO;

// valor de 98

char valor[12 + 1];


...
// obtm o valor da compra e armazena em valor
// abre sesso
...
retorno = ScopeCartaoDinheiro(servio, valor);
...
// processa a transao
...
// 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
Ver tabela de cdigo de retorno.

Exemplo
...
// abre sesso
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
41

...
retorno = ScopeConsultaCartaoDinheiro();
...
// processa a transao
...
// 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

Valor da transao com a vrgula implcita


(exemplo: R$ 123,00 = 12300)

Retorno
Ver tabela de cdigo de retorno.

Exemplo
...
char valor[12 + 1];
...
// obtm o valor do cheque e armazena em valor
// abre sesso
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
42

...
retorno = ScopeConsultaCheque(valor);
...
// processa a transao
...
// 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
Ver tabela de cdigo de retorno.

Exemplo
...
// abre sesso
...
retorno = ScopeConsultaAVS();
...
// processa a transao
...
// fecha a sesso
...

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de retorno.

Exemplo
...
// abre sesso
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
44

...
retorno = ScopeRecargaCelular();
...
// processa a transao
...
// 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++)
{
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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,
(int) buffer[ind_op], buffer[ind_op+1]);

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;

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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,
(int) buffer[ind_op], buffer[ind_op+1]);

}
}

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
Ver tabela de cdigo de retorno.

Exemplo
...
stREC_CEL_OPERADORAS ListaOper;
...
// obtm status do SCOPE
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Valor fixo 2 da recarga, com 2 casas decimais

12 bytes

Bnus da recarga para o valor 2

12 bytes

Custo da recarga para o valor 2

12 bytes

Valor fixo 3 da recarga, com 2 casas decimais

12 bytes

Bnus da recarga para o valor 3

12 bytes

Custo da recarga para o valor 3

12 bytes

Valor fixo 4 da recarga, com 2 casas decimais

12 bytes

Bnus da recarga para o valor 4

12 bytes

Custo da recarga para o valor 4

12 bytes

Valor fixo 5 da recarga, com 2 casas decimais

12 bytes

Bnus da recarga para o valor 5

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

41 bytes

12 bytes

Custo da recarga para o valor 5

12 bytes

Valor fixo 6 da recarga, com 2 casas decimais

12 bytes

Bnus da recarga para o valor 6

12 bytes

Custo da recarga para o valor 6

12 bytes

Valor fixo 7 da recarga, com 2 casas decimais

12 bytes

Bnus da recarga para o valor 7

12 bytes

Custo da recarga para o valor 7

12 bytes

Valor fixo 8 da recarga, com 2 casas decimais

12 bytes

Bnus da recarga para o valor 8

12 bytes

Custo da recarga para o valor 8

12 bytes

Valor fixo 9 da recarga, com 2 casas decimais

12 bytes

Bnus da recarga para o valor 9

12 bytes

Custo da recarga para o valor 9

12 bytes

Valor fixo 10 da recarga, com 2 casas decimais

12 bytes

Bnus da recarga para o valor 10

12 bytes

Custo da recarga para o valor 10

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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
representando o valor R$15,00);

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
representando o valor R$100,00);

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
representando o valor R$50,00);

typedef struct
{
char TipoValor;
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de retorno.

Exemplo
...
stREC_CEL_VALORES tabVal;
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
51

...
// obtm status do SCOPE
switch(status_scope)
{
...
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Valor da transao com a vrgula implcita


(exemplo: R$ 123,00 = 12300)

TxServico

Valor da taxa de servio

Retorno
Ver tabela de cdigo de 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 = 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).

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ponteiro para rea onde ser recebida a
via da loja que sempre estar disponvel
para a aplicao
Tamanho reservado pelo aplicativo para
receber o cupom reduzido
Ponteiro para rea onde ser recebida a
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
Ver tabela de cdigo de retorno.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
54

Exemplo
...
BYTE NroLnhReduzido = 0;
char Cabec[1024],
CpCliente[2048],
CpLoja[2048],
CpReduzido[2048];
LONG retorno;
...
// obtm status do SCOPE
switch(status_scope)
{
...
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de retorno.

Exemplo
...
// abre sesso
...
retorno = ScopeReimpressaoOffLine ();
...
// processa a transao
...
// 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)
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
56

Parmetros
[in]

WORD

CodBandeira

Cdigo da bandeira do carto (ver Cdigo


das bandeiras)

Retorno
Ver tabela de cdigo de retorno.

Exemplo
...
WORD CodBandeira;
// abre sesso
...
// Obtm a bandeira do carto
...
retorno = ScopeReimpressaoOnLine(CodBandeira);
...
// processa a transao
...
// 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

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

2: apenas a via do cliente

Retorno
Ver tabela de cdigo de retorno.

Exemplo
...
BYTE NroLnhReduzido = 0,
EhReimpressao,
ViaReimpressao;
char Cabec[1024],
CpCliente[2048],
CpLoja[2048],
CpReduzido[2048];
LONG retorno;
...
// obtm status do SCOPE
switch(status_scope)
{
...
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);
ImprimeCupomTEF("CUPOM DO CLIENTE", CpCliente);
ImprimeCupomTEF("CUPOM DA LOJA", CpLoja);
if (NroLnhReduzido > 0)
ImprimeCupomTEF("CUPOM REDUZIDO", CpReduzido);
}
else
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
58

{
switch(ViaReimpressao)
{
case 0:
ImprimeCupomTEF("CUPOM DO CLIENTE", CpCliente);
ImprimeCupomTEF("CUPOM DA LOJA", CpLoja);
break;
case 1:
ImprimeCupomTEF("CUPOM DO CLIENTE", CpCliente);
break;
case 2:
ImprimeCupomTEF("CUPOM DA LOJA", CpLoja);
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
Ver tabela de cdigo de retorno.

Exemplo
...
BYTE

TipoConvenio, CodigoRede;

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

...
// abre sesso
...
// coleta o tipo do convnio, o cdigo da rede
...
retorno = ScopeConsultaMedicamento (TipoConvenio, CodigoRede);
...
// processa a transao
...
// 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];
...
switch(status_scope)
{
...
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
Ver tabela de cdigo de retorno.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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);
...
// processa a transao
...
// 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

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

Retorno
Ver tabela de cdigo de 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

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

[in]

WORD

TamLista

Tamanho, em bytes, do campo


ListaMedicamentos

Retorno
Ver tabela de cdigo de retorno.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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

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

Retorno
Ver tabela de cdigo de 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
Ver tabela de cdigo de 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

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

Prottipo
LONG EXPORT ScopePPDisplayEx (char* Msg)

Parmetros
[in]

String

Msg String ASCII de caracteres com o formato abaixo.

Retorno
Ver tabela de cdigo de 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",

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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
Pressionada tecla de funo #2.
6
Pressionada tecla de funo #3.
7
Pressionada tecla de funo #4.
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;
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
68

case 4: printf("\nPressionada a tecla de funcao 1\n"); break;


case 5: printf("\nPressionada a tecla de funcao 2\n"); break;
case 6: printf("\nPressionada a tecla de funcao 3\n"); break;
case 7: printf("\nPressionada a tecla de funcao 4\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
Ver tabela de cdigo de 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)
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
69

Parmetros
[out] String

PIN

Senha capturada do usurio (j descriptografada), finalizada com


caractere nulo ('\0').

Retorno
Ver tabela de cdigo de 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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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
Ver tabela de cdigo de 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);
} while (retorno == 1); // enquanto em processamento
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().

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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);
} while (retorno == 1); // enquanto em processamento
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
Ver tabela de cdigo de retorno.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
73

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 (_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

printf("\nOs dados do carto so [%s]\n", cartao);


}
...

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
Ver tabela de cdigo de retorno.

Exemplo
...
char cartao [256];
char mensagem [256];
LONG retorno = 0;
...
retorno = ScopePPStartGetCard(99, "000");
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
74

if (retorno == 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 (_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

printf("\nOs dados do carto so [%s]\n", cartao);


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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Ver tabela de cdigo de retorno.

Exemplo
...
// carrega configurao do PDV de um novo dia
...
// conecta ao SCOPE Server
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

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

Retorno
Ver tabela de cdigo de 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:

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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;
// processa a transao
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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


memset(aux, '\0', sizeof(aux));
ScopeObtemCampoExt(h, 0x00, 0x00004000, ':', aux);
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
81

ArmazenaCampo(aux);

// exemplo de retorno 02:

// cdigo e nome da bandeira


memset(aux, '\0', sizeof(aux));
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,
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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");
...
// processa a transao
if (RC == RCS_EXISTE_TRN_SUSPENSA)
{
// coletou o telefone do cliente e nmero do pedido
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de retorno.

ScopeGetCheque
Obtm os parmetros para impresso de cheque.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Ver tabela de cdigo de 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
Ver tabela de cdigo de 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.

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

Retorno
Ver tabela de cdigo de 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
Ver tabela de cdigo de 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
Ver tabela de cdigo de 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).

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

[in]

WORD

TamBuf

A aplicao deve informar ao SCOPE o


tamanho da rea reservada

Retorno
Ver tabela de cdigo de 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
executado. Use 0 (zero) para indicar que o
cdigo da bandeira dever ser coletado.

Retorno
Ver tabela de cdigo de 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
executado. Use 0 (zero) para indicar que o
cdigo da bandeira dever ser coletado.

Retorno
Ver tabela de cdigo de retorno.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
89

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Reimpresso de comprovante
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)

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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().
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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)

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Pressionada a tecla de funo #2
Pressionada a tecla de funo #3

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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 de funo #4
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).

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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)

LEMBRETE: utilizado apenas com a interface coleta.

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

LEMBRETE: utilizado apenas com a interface coleta.

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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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
Reimpresso de comprovante
Fidelidade
Recarga de celular
Transao financeira
Investimento
Medicamento

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

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

Cdigos do Convnio
Hexadeci
Decimal
mal
0x0009
0009
0x000A
0010

Significado
FarmaSeg
Pharmalink

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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).

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico V2.25 Verso 1 Reviso 13
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.

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