Manual Desenvolvedor

SCOPE
Manual do Desenvolvedor
Informaes Gerais
Leia antes de utilizar o software:
imprescindvel a leitura deste material para o correto procedimento de instalao, configurao e

administrao deste produto.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27
Reviso
Data
Responsvel
1.0
13/04/2010
Equipe Desenv. SCOPE
1.1
30/04/2010
Equipe Desenv. SCOPE
1.2
01/07/2010
1.3
31/08/2010
Histrico
Verso Inicial.
Reviso do texto e incluso de novos retornos e tipos de
dados.
FacTI Vinicius
Peracini
Paulo dos Santos
Incluso de tabela com cdigo das redes.

Incluso da mscara Logo_PAN (usada na
ScopeObtemCampoExt).
Incluso dos cdigos de retorno (coleta de dados), da
descrio do novo tipo de dado, incluso da nova funo na
FacTI Tiago Valrio

1.4
04/10/2010
Frederico C. Goulart
Jailton da S. C. Santana
sesso Funes diversas - obtendo os campos, incluso do

cdigo de bandeira, cdigo do grupo de servios e cdigo do
servio, referentes Plataforma Promocional da rede Cielo.
Novo tipo no ScopeForneceCampo.
Alteraes referentes s transaes Banrisul EMV.
Acrscimo de tpico para detalhes especficos das redes.
1.5
29/12/2010
Paulo dos Santos
Atualizao da tabela de bandeiras.
1.6
05/01/2011
Marcos Teruhiro

Incluso da mscara para a funo
ScopeObtemCampoExt2;
Incluso dos novos servios de pagamento, DARF e
GPS;
Incluso dos novos estados para interrupo e coleta de
dados.
Excluso da bandeira GreenCard
1.7
16/02/2011
Atualizao da seo Configuraes gerais e Tratando

queda de energia.
Incluso das bandeiras Goodcard Senha, NEUS
SENHA, Nutricash e Diamante.
Reviso do texto referente reimpresso de
comprovantes.
Incluso da funo ScopeServicoTecnico.
Incluso da chave WKPAN na configurao do arquivo
scope.ini.
1.8
17/03/2011
Paulo dos Santos
1.9
18/03/2011
Paulo dos Santos
1.10
19/04/2011
1.12
26/04/2011
FacTI Daniel Alves

Paraiso
FacTI Rafael D. Tardivo

Incluso das Mscaras DescResgateMonetario e
Tipo_Cartao para uso na funo ScopeObtemCampoExt2.
Atualizao da tabela de redes e bandeiras.
Incluso de Rede / Bandeira DMCARD em suas respectivas
tabelas.
1.13
29/04/2011
1.14
04/05/2011
1.15
11/05/2011
1.16
07/06/2011
FacTI Felipe M.
Schaden
FacTI Vinicius Peracini
FacTI Felipe M.
Schaden
FacTI Vinicius Peracini
Incluso da Rede Siscred / Bandeiras Siscred e Planvale.

Atualizao da tabela de cdigos de erro.
Incluso da Bandeira DMCARD SENHA.
Atualizao da tabela de cdigos de erro com o erro
1.17
02/08/2011
FacTI Juliana Bersi
0xFF6B.
Incluso do prottipo das funes:
ScopeMenuSelecionaItem e ScopeMenuRecuperaItens.
1.18
09/08/2011
Frederico C. Goulart

Coleta/Confirmao do valor do saque pelo PIN-pad.
Incluso de ndices/mscaras nas funes
ScopeForneceCampo, ScopeSuspend, ScopeConfigura e
1.19
23/08/2011
FacTI Rafael D. Tardivo
ScopeObtemCampoExt2 para uso em configuraes de

coleta/validao do saque.
Incluso da chave ScopeValidaSaque, configurvel por
chave no .INI ou REGISTRY.
Consulta Crdito Infocards.
1.20
12/09/2011
Marcelo Dionysio da
Fonseca
Nova coleta: TC_COLETA_TIPO_CONSULTA (0xFCB8)

Novo campo da Mascara 3 do ObtemCampo:
Resposta_Consulta_Infocards (0x00000020) 0x0000002
Incluso dos trs novos estados de coleta (0xFCB6,
1.21
15/09/2011
FacTI Juliana Bersi
0xFCB7, 0xFCB9), para quando for solicitado o carto

digitado no Pin Pad.
1.22
04/11/2011
1.23
29/11/2011
1.24
5/01/2012
Edison Ogata
Douglas Sebastiani
Bucciolli
Facti Rafael D. Tardivo
FacTI Srgio R. A.
1.25
20/01/2012
Assuno
1.26
05/03/2012
Facti Felipe M. Schaden

Facti Tiago F. Valrio
1.27
23/03/2012
Edison Ogata
1.28
16/04/2012
Facti Tiago F. Valrio
Incluso dos estados de coleta 0xFCBA e 0xFCBB para o

Troco Visa
Incluso dos tpicos Plataformas Compatveis, Requisitos
de HW e Requisitos de SW
Atualizao do glossrio.
Incluso dos cdigos de coleta de Coleta DDD + Telefone
no PIN Pad e Redigita DDD + Telefone no PIN Pad
Nova interrupo: EC_COLETA_DADOS_ECF
Nova coleta: TC_COLETA_DADOS_ECF (0xFCB9)
Nova bandeira: Ticket Car
Nova funo: ScopeAtualizaParametrosChip
Novo cdigo para ScopeForneceCampo
Acrescentado tpico da rede Ticket Edenred
Acrescentada a rede e a bandeira EPay
Alterao da bandeira PL-COSAN para PL GETNET
VISA.
Incluso da Bandeira PL GETNET MASTER.
Incluso da seo PINPAD no arquivo scope.ini
Incluso da rede TENDENCIA.
Incluso do detalhamento sobre as configuraes de

1.29
26/04/2012
registro do SCOPE no WoW64

Incluso da sesso Fontes de Dados do Scope no
WoW64
1.30
11/05/2012
Incluso da nova estrutura de Dados de Recarga de

Celular stREC_CEL_VALORES_MODELO_4
1.31
22/05/2012
Incluso da Bandeira POLICARD SENHA
1.32
20/06/2012
Edison Ogata
1.33
21/06/2012
1.34
03/07/2012
Edison Ogata
1.35
08/08/2012
Marcelo D. Fonseca
1.36
10/08/2012
Facti Tiago F. Valerio
1.37
30/08/2012
1.38
13/09/2012
Edison Ogata
1.39
19/09/2012
1.40
21/09/2012
Edison Ogata
1.41
15/10/2012
1.42
17/10/2012
1.43
03/01/2013
Edison Ogata
1.44
04/01/2013
1.45
05/03/2013
Edison Ogata
Incluso da bandeira ABRAPETITE
1.46
08/03/2013
Edison Ogata
Acrscimo da seo ArqControlPath no scope.ini
1.47
13/03/2013
1.48
18/04/2013
1.49
07/05/2013
1.50
25/06/2013
Facti Camila M. Dutra
1.51
01/07/2013
Facti - Felipe M. Schaden
Facti Henrique de O.
Buzachero
Edison Ogata
Facti Henrique de O.
Buzachero
Incluso da funo ScopeVersao

Incluso da rede RVTECNOLOGIA.
Incluso da funo ScopeObtemDadosTotalTEFEx() e
atualizao dos tipos de layouts que podem ser utilizados
por ela.
Nova funo: Simulao Credirio;
Novos servios: Credirio e Simulao Credirio.
Incluso da funo adicional e nova lista de
medicamentos na sesso sobre PBM.
Incluido novo cdigo na lista de cdigos de erro do Scope.
Incluso de novo estado de coleta de dados
TC_DECIDE_PGTO_CARNE e estado para interrupo
EC_DECIDE_PGTO_CARNE.
Incluso do cdigo 32 para a funo ScopeConfigura()
permitindo a gravao dos dados da coleta em arquivo.
Incluso do valor 8 para a funo ScopeObtemHandle()
que recupera dados da coleta gravados em arquivo.
Valores sero retornados somente se o cdigo 32 estiver
habilitado ScopeConfigura().
Incluso da rede CREDITEM e bandeira CREDITEM
SENHA.
Atualizao das tabelas de redes e bandeiras.
Incluso do ID para obteno dos valores retornados na
resposta de consulta de saldo da EPAY na mscara 3 da
funo ScopeObtemCampo
Incluso da rede GIVEX, bandeira GIVEX, atualizao das
sesses Estados para interrupo e Coleta de dados.
Atualizao da "Sesso [PINPAD]" com informao da
limitao de dgitos de coleta do pinpad.
Atualizao da "Recarga de celular" com informaes de
parametrizao de coleta.
Incluso da bandeira Sodexo Refeicao
Incluso da rede e bandeira TOPCARD

Incluso do parmetro MascararDados
Incluso da rede VR e bandeiras da VR
Incluso da rede e bandeira INCOMM, reutilizando o
cdigo de rede e bandeira BANKBOSTON.
Incluso de Apndice sobre o formato do cdigo de barras
da INCOMM tratado pela automao comercial.
Incluso da descrio de novas funcionalidades de
Atualizao de Preos e Fornecimento de Lista de
Mercadorias para a Ticket Car
1.52
01/07/2013
Regina M. N. Sato
1.53
06/08/2013
Facti Juliana Bersi

Facti Camila M. Dutra
1.54
11/10/2013
1.55
14/10/2013
1.56
13/01/2014
Jovelina M. de Jesus
1.57
11/02/2014
Jovelina M. de Jesus
1.58
21/03/14
1.59
25/03/2014
Edison Ogata
Facti - Felipe M. Schaden
1.60
02/06/2014
1.61
04/07/2014
Facti-Camila M. Dutra
1.62
07/07/2014
1.63
07/07/2014
1.64
08/07/2014
Alcimar Joaquim
1.65
14/07/2014
Alcimar Joaquim
1.66
30/07/2014
Alcimar Joaquim
1.67
26/08/2014
Marcelo Dionysio da
Fonseca
Incluso da mscara da funo ScopeObtemCampoExt2

para obteno do Maximo de Mercadorias permitidas para
transao TicketCar.
Incluso da rede e bandeira ELAVON
Incluso das bandeiras Bancred Senha e Vegas Card
Senha
Incluso da rede VR e das bandeiras VR e Multibeneficios
Descrio do ForneceCampo
SCOPE_DADOS_APLIC_CBD
Incluso de rede e bandeira PharmaSystem; funes:
Elegibilidade, Pr-Autorizao, Cancelamento de PrAutorizao; layouts de lista de medicamentos; funo para
recuperao de lista de projetos.
Incluso das rotinas de PIN-Pad para leitura e limpeza de
comanda. Insero de dois cdigos de retorno de erro para
PIN-Pad compartilhado.
Descrio da funcionalidade de transao POS
Incluso da configurao do scope.ini para a transao
POS
Incluso da bandeira FORTBRASIL
Inserido item Consulta a saldo de carto de dbito
Corrigido cdigo para TC_COLETA_DADOS_ECF
Incluida informao de Consulta das Mercadorias
configuradas pela Inicializao de Tabelas da Ticket
Edenred.
Complemento e correo de informaes especficas para
a rede Ticket.
Incluso de cdigos de Convnio, Rede e Bandeira da
PBM PADRO
Atualizao da sesso Compra de medicamento a
respeito do funcionamento do layout 5
Atualizao da sesso "Lista de medicamentos Ex"
Incluso da coluna com os Cdigos SAT na tabela Cdigo
das redes.
Incluso da mscara da funo ScopeObtemCampoExt2,
na tabela Dados Disponveis, para obteno do cdigo SAT
da transao.
Melhoria do detalhamento do campo
SCOPE_DADO_SEPARADOR_LINHA da funo
ScopeForneceCampo() para parametrizao do finalizador
de linha do cupom
Informaes adicionais para formatao do finalizador de
linha da funo ScopeGetCupomEx.
Incluso dos possveis erros retornados pelas as funes
do Scope.
Incluso dos cdigos de coleta o Scope para as funes:
ScopeCompraCartaoCredito, ScopeCompraCartaoDebito,
ScopeRecargaCelular e ScopeAtualizaPrecosMercadorias.
Incluso do tpico Cielo na seo Redes com
tratamentos especficos
No tpico Cielo est descrito como implementar as
funcionalidades do Cielo Premia.
Incluso da funo
ScopeObtemOperadorasRecCelOffTEF
Incluso da funo
ScopeRecuperaValoresRecCelOffTEF
Incluso da rede Bin
1.68
27/08/2014
1.69
28/08/2014
Edison M. Ogata
1.70
23/09/2014
1.71
19/12/2014
Regina Megumi
Marcelo Dionysio da
1.72
22/12/2014
1.73
27/01/2015
Edison Ogata
1.74
19/02/2015
Edison Ogata
1.75
27/02/2015
1.76
12/03/2015
Jailton Santana
Fonseca
Incluso de seo especifica para detalhamento da rede

SAVS
Descrio da funo ScopeRecuperaBufTabelaGen para
SAVS
Incluso de Cdigos de retorno para SAVS
Incluso de Estados para interrupo para SAVS
Incluso de Cdigo de Rede e Bandeira SAVS
Incluso de Cdigo de Servio para SAVS
Incluso de Constante Versao_Carga_Tabelas_Host da
mscara 3 da funo ScopeObtemCampoExt2
Incluso da rede CONDUCTOR-PL
Incluso da bandeira BAHAMAS CRDITO
Incluso da bandeira BAHAMAS ALIMENTAO
Correo de nome da funo
ScopeRecuperaBufTabelaGen e de parmetro da funo
ScopeRecuperaBufTabela
Incluso de informaes sobre Cielo Auto
Atualizao para Transaes Sem Contato (Contactless)
Incluso da tabela Cdigos de Retorno de Pr-TEF no
Apndice A.
Acrscimo da bandeira CABAL VOUCHER na lista de
bandeiras.
Reitrada da bandeira CABAL VOUCHER da lista de
bandeiras, pois j existe uma bandeira semelhante: CABAL
VALE
Incluso da mscara da funo ScopeObtemCampoExt2,
na tabela Dados Disponveis, para obteno do cdigo SAT
e CNPJ da rede credenciadora da transao.
Incluso do parmetro GenTiemout
Formatao
ndice
Prefcio............................................................................................................................. 13
A quem se destina ........................................................................................................................................ 13
Requisitos ..................................................................................................................................................... 13
Plataformas Compatveis .......................................................................................................................... 13
Requisitos de HW...................................................................................................................................... 13
Requisitos de SW ...................................................................................................................................... 13
Descrio do Produto ................................................................................................................................... 13
Objetivo ..................................................................................................................................................... 13
Definio ................................................................................................................................................... 13
Benefcios .................................................................................................................................................. 13
Conceitos ......................................................................................................................... 15
Transaes ................................................................................................................................................... 15
Fluxo de estados de coleta .......................................................................................................................... 16
Interfaces de interao com o SCOPE Client .............................................................................................. 16
Interface coleta .......................................................................................................................................... 16
Interface HLAPI ......................................................................................................................................... 17
Padres adotados neste documento............................................................................................................ 17
Legenda de Abreviaes .......................................................................................................................... 19
Instalao ......................................................................................................................... 20
Instalao do SCOPE Client para MS-Windows ........................................................................................ 20

Instalao do SCOPE Client para Linux ...................................................................................................... 20
Configurao .................................................................................................................... 22
Configurao do arquivo scope.ini ............................................................................................................... 22
Sesso [<empresa><filial>] ....................................................................................................................... 22
Sesso [SCOPEAPI] ................................................................................................................................. 24
Sesso [PPCOMP] .................................................................................................................................... 24
Configurao de porta serial para Linux ................................................................................................... 24
Sesso [PINPAD] ...................................................................................................................................... 25
Seo [SCOPEAPIPOS] ........................................................................................................................... 25
Seo [SCOPEAPIPOS-RXXX] ................................................................................................................ 26
Configurao do registro do MS-Windows ................................................................................................. 27

Fontes de Dados do SCOPE no WoW64 .................................................................................................... 28
Funes bsicas da API do SCOPE Client .................................................................... 29

Comunicao com o ScopeSRV .................................................................................................................. 29
Conexo .................................................................................................................................................... 29
Desconexo .............................................................................................................................................. 30
Sesso de transao .................................................................................................................................... 31
Sesso de TEF.......................................................................................................................................... 31
Abrindo uma sesso ................................................................................................................................. 32
Encerrando a sesso ................................................................................................................................ 33
Tratando queda de energia ....................................................................................................................... 34
Deixando transao pendente na queda de energia ................................................................................ 35
Status de transao...................................................................................................................................... 36
Consultando o status ................................................................................................................................ 36
Funes de configurao de ambiente.......................................................................... 38

Configuraes gerais ................................................................................................................................... 38
Configurando em tempo de execuo ...................................................................................................... 39
Configurao de PIN-Pad ............................................................................................................................ 40
Validando a interface de PIN-Pad ............................................................................................................. 40
Funes especficas das interfaces ............................................................................... 41

Interface coleta ............................................................................................................................................. 41
Definindo a interface coleta ....................................................................................................................... 41
Obtendo os parmetros da transao ...................................................................................................... 43

Passando o dado da coleta ao SCOPE Client .......................................................................................... 45
Interface HLAPI ............................................................................................................................................ 48
Suspendendo a transao ........................................................................................................................ 48
Retomando a transao ............................................................................................................................ 50
Abortando a transao .............................................................................................................................. 51
TEF .................................................................................................................................... 53
Carto de crdito .......................................................................................................................................... 53
Compra com carto de crdito .................................................................................................................. 53
Consulta a financiamento de carto de crdito ......................................................................................... 55
Consulta a saldo de carto de crdito ...................................................................................................... 56
Pr-autorizao de crdito ........................................................................................................................ 57
Carto de dbito ........................................................................................................................................... 59
Compra com carto de dbito ................................................................................................................... 59
Compra CDC (Crdito Direto ao Consumidor) ......................................................................................... 61
Consulta CDC ........................................................................................................................................... 61
Simulao Credirio .................................................................................................................................. 62
Consulta a saldo de carto de dbito ....................................................................................................... 64
Carto Dinheiro ................................................................................................................ 65

Operaes .................................................................................................................................................... 65
Compra/Carga do carto dinheiro ............................................................................................................. 65
Compra usando o carto dinheiro (dbito) ............................................................................................... 66
Consulta ao saldo de carto dinheiro........................................................................................................ 67
Estornos .................................................................................................................................................... 67
Funes de Consulta....................................................................................................... 68
Cheque ......................................................................................................................................................... 68
Consulta de cheques ................................................................................................................................ 68
AVS .............................................................................................................................................................. 69
Consulta AVS ............................................................................................................................................ 69
Recarga de celular ........................................................................................................... 71

Configurando a recarga de celular ............................................................................................................... 71
Processando a recarga de celular................................................................................................................ 71
Iniciando a transao de recarga .............................................................................................................. 72
Obtendo operadoras disponveis .............................................................................................................. 73
Obtendo valores de recarga...................................................................................................................... 76
Funes de consulta para recarga de celular .............................................................................................. 81
Obtendo operadoras disponveis fora do fluxo de recarga ....................................................................... 81
Obtendo valores de recarga disponveis fora do fluxo de recarga ........................................................... 82
Estorno de transaes .................................................................................................... 84

Estornando a transao ............................................................................................................................ 84
Comprovantes .................................................................................................................. 86
Comprovantes de transaes ...................................................................................................................... 86
Obtendo os cupons de TEF ...................................................................................................................... 86
Reimpresso de comprovante ..................................................................................................................... 88
Solicitando o comprovante off-line ............................................................................................................ 88
Solicitando o comprovante on-line ............................................................................................................ 89
Imprimindo o comprovante correto ........................................................................................................... 91
PBM - Medicamentos ....................................................................................................... 94

Consultando medicamento ........................................................................................................................... 94
Compra de medicamento ............................................................................................................................. 95
Lista de medicamentos ................................................................................................................................ 97
Lista de medicamentos com CRM ............................................................................................................... 98
Lista de medicamentos Extendida ............................................................................................................. 100
Lista de Projetos ......................................................................................................................................... 101
Elegibilidade do Carto PBM ..................................................................................................................... 102
Pre-Autorizacao de Medicamentos PBM ................................................................................................... 104

Cancelamento de Pre-Autorizacao de Medicamentos PBM ...................................................................... 105
Funes de PIN-Pad ...................................................................................................... 107

Comunicao com o PIN-Pad .................................................................................................................... 107
Iniciando a comunicao ......................................................................................................................... 107
Encerrando a comunicao .................................................................................................................... 108
Mensagens no visor ................................................................................................................................... 108
Mensagens de tamanho padro ............................................................................................................. 108
Mensagens maiores ................................................................................................................................ 109
Informaes obtidas do PIN-Pad ............................................................................................................... 110
Dados das redes autorizadoras .............................................................................................................. 110
Dados do dispositivo ............................................................................................................................... 110
Obtendo as informaes ......................................................................................................................... 111
Obtendo teclas do PIN-Pad ........................................................................................................................ 112
Iniciando a leitura da tecla ...................................................................................................................... 112
Obtendo a tecla ....................................................................................................................................... 112
Obtendo a senha aberta ............................................................................................................................. 113
Iniciando o modo de leitura da senha aberta .......................................................................................... 113
Lendo a senha aberta ............................................................................................................................. 114
Obtendo a senha criptografada .................................................................................................................. 115
Iniciando o modo de leitura da senha criptografada ............................................................................... 115
Lendo a senha criptografada .................................................................................................................. 116
Lendo um carto......................................................................................................................................... 117
Iniciando a leitura do carto .................................................................................................................... 117
Recuperando o carto ............................................................................................................................. 117
Abortando o processamento (ScopePPAbort) ........................................................................................... 119
Mensagens de erro (ScopePPMsgErro) .................................................................................................... 120
Obtendo a comanda de um carto ............................................................................................................. 121
Iniciando o modo de leitura da comanda ................................................................................................ 121
Lendo a comanda.................................................................................................................................... 122
Limpando a comanda de um carto ........................................................................................................... 123
Iniciando o modo de limpeza da comanda ............................................................................................. 123
Limpando a comanda .............................................................................................................................. 123
Totalizao de TEF ........................................................................................................ 125

Relatrio de TEF ........................................................................................................................................ 125
Iniciando os totais.................................................................................................................................... 125
Cupom dos totais .................................................................................................................................... 126
Dados dos totais...................................................................................................................................... 128
Transao de POS para conciliao ............................................................................ 132

Descrio da funcionalidade ...................................................................................................................... 132
Transao POS .......................................................................................................................................... 132
Redes e bandeiras ..................................................................................................................................... 135
Cdigos de servios ................................................................................................................................... 139
Cupom CIELO X ScopeObtemCampoExt2 X arquivo ............................................................................... 140
Cupom REDECARD X ScopeObtemCampoExt2 X arquivo ...................................................................... 141
Outros cupons X ScopeObtemCampoExt2 X arquivo ............................................................................... 143
Formatao para o arquivo de conciliao ................................................................................................ 144
Funes diversas .......................................................................................................... 145

Dados da transao ................................................................................................................................... 145
Obtendo handle ....................................................................................................................................... 145
Obtendo os campos ................................................................................................................................ 146
Fornecendo informaes extras para a transao ..................................................................................... 150
Descrio dos tipos de dados ................................................................................................................. 150
Atributos da aplicao ............................................................................................................................. 152
Atrelando dados transao .................................................................................................................. 153
ScopeGetLastMsg ...................................................................................................................................... 155
ScopeGetCheque ....................................................................................................................................... 156
10
ScopeAtualizaValor .................................................................................................................................... 156

ScopeGarantiaDescontoCheque ................................................................................................................ 157
ScopeTransacaoFinanceira ....................................................................................................................... 157
ScopeInvestimento ..................................................................................................................................... 158
ScopeObtemCartaoInvestimento ............................................................................................................... 159
ScopeResumoOperacoes .......................................................................................................................... 160
ScopePagamento ....................................................................................................................................... 161
ScopeServicoTecnico ................................................................................................................................. 162
ScopeAtualizaParametrosChip .................................................................................................................. 163
ScopeVersao .............................................................................................................................................. 164
ScopeAtualizaPrecosMercadorias ............................................................................................................. 165
Redes com tratamentos especficos ............................................................................ 167

Banrisul EMV .............................................................................................................................................. 167
PINPads com suporte a rede .................................................................................................................. 167
Associao dos produtos e as funes do SCOPE ................................................................................ 167
Transao convnio combustvel ............................................................................................................ 167
Ticket Edenred ........................................................................................................................................... 168
PINPads com suporte a rede .................................................................................................................. 169
Dados coletados...................................................................................................................................... 170
Consulta saldo......................................................................................................................................... 170
Dados do ECF ......................................................................................................................................... 170
Dados da Lista de Mercadorias Consumidas ......................................................................................... 171
Descrio do formato do registro "SC101": ............................................................................................ 172
Dados da Lista de Atualizao de Preos de Mercadorias .................................................................... 172
Comprovantes ......................................................................................................................................... 173
Cdigo das Mercadorias ......................................................................................................................... 173
Cielo Premia ............................................................................................................................................... 174
Como a gesto da campanha? ............................................................................................................ 174
Quais tipos de prmios o comprador pode receber? .............................................................................. 174
Que tipos de transaes podem receber os prmios? ........................................................................... 175
possvel restringir para tratar apenas prmios no monetrios, ou seja, no permitir descontos? .... 175
O que preciso configurar no SCOPE CNF? ......................................................................................... 175
A Cielo precisa habilitar o Cielo Premia? ................................................................................................ 175
possvel integrar e testar atravs do SCOPE Autorizador? ................................................................ 175
possvel fazer um teste usuando o HotKey? ....................................................................................... 176
A Automao Comercial deve se adequar? ........................................................................................... 176
O que a Automao Comercial precisa fazer para estar aderente? ....................................................... 176
Como saber se houve um prmio no monetrio (brinde) recebido durante uma compra? .................. 177
Como fazer um Resgate de Prmio? ...................................................................................................... 178
Existe uma forma de tratar os itens do Menu Dinmico pela aplicao de AC? .................................... 180
Existe um cdigo exemplo? .................................................................................................................... 180
Qual a verso mnima do SCOPE que contempla Cielo Premia? ....................................................... 180
Cielo Auto ................................................................................................................................................... 180
Lista de produtos e/ou servios principais Cielo Auto ............................................................................ 181
Lista de produtos e/ou servios secundarios Cielo Auto ........................................................................ 181
Informaes Adicionais Cielo Auto ......................................................................................................... 184
SAVS .......................................................................................................................................................... 184
Autorizao de Vouchers e Servios ...................................................................................................... 185
Estorno de Autorizao de Vouchers e Servios .................................................................................... 187
Lista de Fornecedores ............................................................................................................................ 187
Lista de Produtos .................................................................................................................................... 188
Cielo Transaes Sem Contato (Contactless) ........................................................................................ 190
Requisitos ................................................................................................................................................ 190
Funcionamento........................................................................................................................................ 190
Apndice A Tabelas .................................................................................................... 192

Cdigos de retorno ..................................................................................................................................... 192
Coleta de dados ...................................................................................................................................... 192
11
Autorizadoras .......................................................................................................................................... 196

Cdigos de erros do SCOPE .................................................................................................................. 197
PIN-Pad compartilhado ........................................................................................................................... 200
Cdigos de Retorno de Pr-TEF............................................................................................................. 202
Formatos dos dados ................................................................................................................................... 204
Cdigos das Teclas .................................................................................................................................... 204
Cdigos de Fluxo........................................................................................................................................ 205
Estados para interrupo ........................................................................................................................... 205
Cdigo das redes ....................................................................................................................................... 211
Cdigo de especificao das redes ........................................................................................................... 214
Cdigo das bandeiras ................................................................................................................................ 214
Dados disponveis das transaes ............................................................................................................. 219
Grupo de Servios ...................................................................................................................................... 221
Cdigos dos Servios ................................................................................................................................. 221
Convnios ................................................................................................................................................... 223
Apndice B Especificao Visanet 4.1...................................................................... 225

Adequao ................................................................................................................................................. 225
Certificao ................................................................................................................................................. 226
Apndice C PIN-Pad Compartilhado ......................................................................... 227

Apndice D Conjunto de bibliotecas do SCOPE Client ........................................... 229
MS-WINDOWS ......................................................................................................................................... 229

Linguagem Java ...................................................................................................................................... 229
Linux ........................................................................................................................................................... 230
Linguagem Java ...................................................................................................................................... 230
Apndice E Identificando a verso do SCOPE Client .............................................. 231

Verificando no SCOPE Server ................................................................................................................... 231
Verificando no ambiente do PDV ............................................................................................................... 232
SCOPE Client para MS-Windows ........................................................................................................ 232
SCOPE Client para Linux ........................................................................................................................ 233
Apndice F Formato do Cdigo de Barras InComm ................................................ 235

Apndice G - Glossrio ................................................................................................. 236
12
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.
Requisitos
Plataformas Compatveis
Todos os mdulos da soluo SCOPE, so compatveis com as plataformas Windows 7 e
Windows Server 2008.
O mdulo SCOPE Client, alm das plataformas acima, tambm compatvel com a plataforma
Linux (Librix, RedHat, SUSE e outros).
Requisitos de HW
PC com processador de 1 GHz ou mais de velocidade
512 megabytes (MB) de RAM ou mais so recomendados
1 gigabyte (GB) de espao disponvel em disco rgido ou mais so recomendados
Requisitos de SW
Banco de Dados (SGBD). Os seguintes SGBDs so suportados pela soluo SCOPE:
SQL Server 2005 ou 2008
Oracle 10g ou 11g
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
13
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.
14
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 sequncias que geralmente
compoem 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. Contm 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.
15
Figura 1: sequncia de mensagens numa transao completa e bem sucedida.
Fluxo de estados de coleta

O funcionamento do SCOPE Client baseia-se em fluxos de estados de coleta para as diversas
operaes disponveis. A cada iterao entre o aplicativo com o SCOPE Client, este informa em
qual estado de coleta se encontra, qual informao deve ser coleta, qual mensagem deve ser
exibida e quais opes de fluxo esto disponveis (retornar, prximo e cancelar). Desta forma o
fluxo avana at que seja possvel efetuar a transao desejada.
Exemplificando: Ao iniciar uma transao de crdito, o SCOPE estar no estado de coleta
nmero do carto. Uma vez obtido o carto, o estado avana e dependendo de uma srie de
variveis, poder migrar para o estado coleta os 4 ltimos dgitos do carto. Conforme as
configuraes possveis para o tratamento de servio de crdito, o prximo estado poder ser
coletar se vista ou no, o fluxo avana at a impresso do comprovante.
Interfaces de interao com o SCOPE Client

Antes de comear o desenvolvimento da integrao com o SCOPE, de fundamental importncia
a deciso de como a aplicao ir interagir com o SCOPE Client, escolhendo uma das interfaces
disponveis: interface coleta ou interface HLAPI. A escolha do tipo de interface depende de fatores
tais como: Tempo de implementao, flexibilidade e plataforma adotada.
Interface coleta
Disponvel para todos os sistemas operacionais com os quais o SCOPE Client executado, a
interface coleta do SCOPE Client o que apresenta uma maior interao entre a aplicao de
PDV e o SCOPE. Atravs desta interface, a aplicao se torna responsvel pela coleta dos dados
digitados pelo operador ou cliente conforme a solicitao a cada iterao do SCOPE. Como a
16
aplicao coletar os dados, ela se responsabilizar pela exibio da mensagem na tela e a

entrada de dados para o operador, sendo que para alguns casos, dever tratar tambm a
limitao do tamanho do campo aceitvel (ex.: para a coleta do nmero de segurana do carto, a
aplicao permitir a entrada de um valor com no mnimo 3 e no mximo 5 dgitos).
Caractersticas da interface coleta
Interceptar, para uso da prpria aplicao, os dados coletados via digitao para o
SCOPE;
No interfere na interface grfica do usurio;
Disponvel para qualquer linguagem e sistema operacional;
A aplicao deve ter um maior nvel de especializao, portanto, maior lgica na

integrao.
Interface HLAPI
Esta interface exige um nvel menor de integrao com a aplicao, pois toda a coleta de dado
realizada pelo SCOPE atravs de uma pequena janela, do prprio SCOPE, que exibida na tela
(figura 2). Est disponvel apenas para aplicaes MS-Windows de 32-bits.
Figura 2: janela do SCOPE Client na interface HLAPI
Caractersticas da interface HLAPI
A coleta realizada pelo SCOPE, portanto a aplicao no sabe o que est sendo
coletado;
Disponvel apenas para aplicaes Win32;
Pode tratar perifrico (CMC7, impressora, etc.), desde que suportado pelo SCOPE;
Possui GUI prpria, que no momento da transao, fica aberta, sobrepondo a

interface da aplicao.
Padres adotados neste documento

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

As sesses que descrevem os argumentos ou parmetros das funes exibiro os mesmos numa
tabela, cujas linhas representam cada parmetro e as colunas indicaro os seguintes dados:
1 coluna: parmetro de entrada [in] ou sada [out];
2 coluna: tipo de dado que representa o parmetro;
3 coluna: nome da varivel representada no parmetro
4 coluna: significado do parmetro.
Todos os exemplos de cdigos relacionados neste documento esto seguindo a linguagem C com
a seguinte formatao:
int main ()
{
printf (Hello, SCOPE\s Programmers!);
}
Para compatibilidade das funes entre diversas linguagens e plataformas, algumas convenes
de tipos devem ser adotadas, conforme a tabela a seguir:
Definio de Tipo:
Tipo
Tamanho
Descrio
BYTE
1 byte
Valor sem sinal de 0 a 255
WORD
2 bytes
Valor sem sinal de 0 a 65.535
SHORT
2 bytes
Valor com sinal de -32.768 a 32.767
LONG
4 bytes
Valor com sinal de -2.147.483.648 a 2.147.483.647
Analogamente, como recurso de portabilidade, algumas constantes devem ser criadas e definidas
diferentemente em cada plataforma, com o objetivo de utilizar os mesmos prottipos de funes
conforme a tabela a seguir:
Constantes:
Tipo
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
18
Legenda de Abreviaes
Formato
a
n
an
ans
MM
DD
AA
hh
mm
ss
LLvar
LLLvar
10
..10
b
Atributo
Caracteres alfabticos.
Caracteres numricos.
Caracteres alfabticos e numricos.
Caracteres alfabticos, numricos e especiais.
Ms.
Dia.
Ano.
Hora.
Minuto.
Segundo.
Tamanho de um campo varivel.
Ex. Se o contedo do campo = AB1234CD, teremos para represent-lo: 08
AB1234CD .
Tamanho de um campo varivel.
Ex. Se o contedo do campo = AB1234CD, teremos para represent-lo: 008
AB1234CD .
Tamanho fixo de 10 caracteres.
Tamanho varivel de at 10 caracteres.
Representao binria dos dados.
19
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.
20
IMPORTANTE: para a execuo deste comando necessrio ter direitos do usurio root.
CUIDADO: em ambiente Linux, o usurio root tem o direito de realizar comandos que
podem danificar o sistema.
LEMBRETE: podem-se acrescentar os parmetros -vh para exibir o progresso da instalao.
21
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 sequncia 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 est o
I.P. ou nome da mquina do
ScopeSRV.
ScopeSRV
Porta de conexo do ScopeSRV.

Parmetro que decide se o SCOPE Client
AtualizaDataHora
mensagens que o SCOPE Client enviar para a

aplicao para que esta exiba no teclado do
CupomReduzido
(padro).
caso deseja-se que
sincronize.
40 colunas (padro)
20 colunas
m 16 colunas
Configura a exibio do cupom na tela. Utilizado
No exibe
apenas na interface HLAPI.
Exibe (padro)
para a conexo do SCOPE Client com o

ScopeSRV.
TimeOutAdm
se no deve sincronizar
operador ou display com esta finalidade.
Configura o tempo, em segundos, de espera

TimeOutLogon
sincronizar com o ScopeSRV no momento da
Controla o tamanho mximo de colunas das
ShowCupom
2046).
dever alterar a data e a hora da mquina para
conexo.
MsgOperReduzida
Valor numrico (o padro
Valor numrico entre 10 e 60

(padro 10).
Configura o tempo, em segundos, de espera da
Valor numrico entre 15 e 180
resposta da autorizadora em cada transao.
(padro 30).
Configura se deve exibir o cupom reduzido na
No exibir
tela. Utilizado apenas na interface HLAPI.
Exibir
Sequncia de caracteres no
VersaoAutomacao
Verso da automao passada pela rea de
formato RRAAAACCCC, sendo
certificao da Visanet.
que:
RR release de certificao do
22
TEF
AAAA Nome da automao
CCCC Cdigo do memorando
xxx
(o padro 01HOTK0000)
WKPAN
ScopeValidaSaque
Configura se deve habilitar a Comunicao
No habilitar
Segura com o PIN Pad.
Habilitar
Configura se o Scope deve consistir o valor do
No habilitar
Habilitar
saque digitado com os valores configurados nos

limites de saque do produto, localizados no
ScopeCnf.
n
s(0)
Nenhum carto
mascarado.
Todos os cartes sero
mascarados com zeros.
mascarados com zeros.
s(*)
mascarados com
asteriscos.
MascararDados
Todos os cartes que
Indica como o valor do PAN deve ser enviado

para a aplicao.
seguem o padro PCI DSS

sero mascarados com
zeros.
Todos os cartes que
p(0)

sero mascarados com
zeros.
Todos os cartes que
p(*)

sero mascarados com
asteriscos.
Valor numrio de 1 99 que

representa o tempo em
segundos. Se no tiver
configurado ou o valor estiver
GenTimeout
Define um tempo mximo, em segundo,
invlido, ser assumido o
para o SCOPE Client gerar as chaves de
valor padro de 99
criptografia utilizado na conexo.
segundos. Neste caso, ser

praticamente impossvel
alcanar esse tempo e a
chave ideal ser gerada
sempre.
23
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. Em
No habilita (padro)
Habilita
MS-Windows, ser gerado no C:\, nos demais

sistemas, no diretrio corrente da aplicao, o
TracePin
arquivo TracePin.sc_. O sistema de log

circular, assim quando o tamanho desse
arquivo for 1 MB, ele ser renomeado para
TracePin.bak e um novo TracePin.sc_ ser
criado.
Diretrio para salvar os arquivos de controle do
ArqControlPath
Scope Client. Somente vlido para o sistema
Diretrio (padro C:\)
operacional Windows
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
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.
24
Chave
Significado
Valor
SerialNumPorts
Nmero de portas a ser configuradas.
Valor entre 1 e 6 (o padro 6)
SerialPortx
Dispositivo com novo direcionamento para a

porta (x-1).
Valores de 0 a 5.
LEMBRETE: a configurao pode ser alternada entre as diversas portas.
Exemplo: suponhamos que possumos 3 equipamentos seriais, mas o computador que rodar a
aplicao possui uma porta serial e duas USB. Ser necessrio que dois equipamentos utilizem
conversores SerialUSB, que ao serem conectados, so criados dois novos dispositivos:
ttyUSB0 e ttyUSB1 (os nmeros terminais 0 e 1 podem variar). Portanto, em algum ponto do
arquivo scope.ini, deve ser colocado a configurao abaixo para atender esta mquina:
SerialNumPorts=3
SerialPort0=/dev/ttyS0
; porta 1 serial
SerialPort1=/dev/ttyUSB0
; porta 2 USB
SerialPort2=/dev/ttyUSB1
; porta 3 USB
CUIDADO: de acordo com a configurao acima, conectamos um equipamento na porta 1 e

os outros dois, nas portas 2 e 3.
Sesso [PINPAD]
Aqui, configura-se item relacionado ao tamanho mnimo de dados permitidos para serem lidos
pelo PIN-Pad.
Chave
TamMinDados
Significado
Valor
Tamanho mnimo de entrada de dados
Valor numrico acima de 1 (o
permitidos pelo PIN-Pad.
padro 1).
CUIDADO: Caso o PIN Pad utilize a Biblioteca Compartilhada 1.07 e PCI 2.0 a quantidade
mnima de dgitos permitidos para serem lidos por coleta deve ser 4 dgitos, sendo assim,
TamMinDados deve estar parametrizado com um valor de no mnimo 4.
Seo [SCOPEAPIPOS]
Essa seo permite configuraes gerais, como para habilitar a digitao dos cdigos e
acrescentar redes e/ou bandeiras.
25
Chave
Significado
Valor
Configura se d a opo de outra rede.
ATENO: essa chave ignorada se a
DigitacaoCodigo
chave Complementar existir.

Configura se acrescenta rede tabela
padro ou as substitui.
ATENO: a existncia dessa chave
Complementar
desconsidera a configurao chave

DigitacaoCodigo, pois ela prioritria.
Redes
Bandeiras
no pergunta se outra rede

pergunta se outra e coleta o
cdigo da rede e da bandeira
substitui as tabelas padro pelas
que esto configuradas
acrescenta a configurao de redes
e bandeiras que esto no arquivo a

listagem padro
Lista de at 7 cdigos de redes distintas
Nmeros de at 3 dgitos cada,
para perguntar no fluxo
separados por vrgula
Lista de at 14 cdigos de bandeiras
distintas para perguntar no fluxo
Nome da bandeira YYY que ser exibida no

fluxo, onde YYY uma das bandeiras
NomeBandeiraYYY
listadas na chave Bandeiras.

ATENO: se faltar a chave para alguma
String de at 20 caracteres
das bandeiras, ser exibido cdigo da

bandeira para o operador.
Seo [SCOPEAPIPOS-RXXX]
Essa seo permite configuraes de uma das redes configuradas na seo detalhada
anteriormente, onde XXX uma das redes listas na chave Redes. Portanto, deve haver uma
seo para cada rede da lista.
ATENO: se no houver a seo para alguma das redes listadas, ser exibido o cdigo da rede
como opo e todas as bandeiras listadas estaro associadas rede.
Chave
Significado
Valor
Nome
Nome da rede XXX que ser exibida no fluxo
String de at 20 caracteres
Lista de bandeiras associadas a esta rede. A

Bandeiras
bandeira deve existir na chave Bandeiras da

seo [SCOPEAPIPOS].

Lista de cdigos de servios permitidos para

essa bandeira, associada a essa rede, onde XXX
o cdigo com 3 dgitos (zeros esquerda) de
ServicoBXXX
uma das bandeiras listada no campo Bandeiras.

Se houver bandeiras sem configurao de

servio, sero associados todos os servios

previstos.
26
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: rvore do SCOPE no registro do MS-Windows

Em sistemas operacionais MS-Windows de 64 bits (x64), o SCOPE instalado sobre o
subsistema Wow64 para funcionar corretamente. No WoW64 as configuraes do SCOPE so
armazenadas em HKEY_LOCAL_MACHINE/SOFTWARE/Wow6432Node/Scope:
Figura 4: rvore do SCOPE no registro do Wow64

Para maiores informaes sobre o Wow64, consulte a sesso Instalao do SCOPE em
Sistemas Operacionais Microsoft Windows de 64-Bits, no documento Scope Manual de
Instalao e Configurao.
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
27
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
ScopeValidaSaque
HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\ScopeValidaSaque
Fontes de Dados do SCOPE no WoW64

No WoW64,as fontes de dados (ou DSNs) so criadas por um Administrador de Fontes de Dados
ODBC compatvel com 32 bits do WoW64 e no o de 64 bits que acessvel por padro a partir
do Painel de Controle do Windows. Assim, ao instalar o Scope so criados links com as bases de
dados
que
podem
depois
ser
alterados
se
necessrio
em
%SystemRoot%\SysWOW64\odbcad32.exe.
Para maiores informaes sobre o Wow64, consulte a sesso Instalao do SCOPE em
Sistemas Operacionais Microsoft Windows de 64-Bits, no documento Scope Manual de
Instalao e Configurao
28
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.
Antes de enviar o logon para o SCOPE Server, o client gera um par de chaves pblica e privada.
Dependendo da configurao de hardware do PDV, esse processo pode levar alguns segundos.
Isso necessrio para gerar uma chave de tamanho seguro e assegurar a conformidade com o
PCI-DSS. Entretanto, o estabelecimento pode definir um tempo mximo de para gerar essas
chaves, configurando o parmetro GenTimeout no arquivo scope.ini do client (ver tpico Sesso
[<empresa><filial>]).
ATENO: a configurao do parmetro GenTimeout poder acarretar em no conformidade

com o PCI-DSS.
Prottipo
LONG EXPORT ScopeOpen (char *Modo, char *Empresa, char *Filial, char
*PDV)
Parmetros
[in]
[in]
[in]
[in]
String (constante
igual 2)
String com quatro
dgitos
String com quatro
dgitos
String com trs
dgitos
Modo
Modo de operao
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.
Possveis Retornos de Erros

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
Significado
Parmetro 1 invlido
Parmetro 2 invlido
29
Cdigos Retorno
Hexadeci Decimal
mal
0xFA03
64003
0xFE02
65026
0xFE09
65033
Significado
Parmetro 3 invlido
SCOPE API j foi inicializada corretamente
Servidor no configurado no arquivo scope.ini
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

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE00
65024
Significado
SCOPE API no foi inicializada corretamente
A transao em andamento a aplicao deve aguardar
Exemplo
...
retorno = ScopeClose ();
...
30
Sesso de transao
Sesso de TEF
O conceito de sesso de TEF existe para garantir a integridade de uma operao. Desta forma,
entre a abertura e encerramento da sesso, todas as atividades includas na respectiva operao
(autorizao da transao, impresso de comprovante) devero ser completamente realizadas.
Este mecanismo permite que em caso de falha (queda de energia), a operao possa ser
desfeita. Isso corresponde a imprimir corretamente o cupom de TEF e garantir que a falha
ocorrida no atrapalhe no funcionamento da aplicao.
Sendo multi-TEF, o SCOPE implementa o conceito de sesso de TEF com o intuito de garantir
que todas as transaes numa mesma sesso sero aprovadas ou desfeitas. Com isto, o cliente
pode efetuar o pagamento parcialmente de diversas maneiras (exemplo: 40% do valor da venda
sero pagos em dbito e o restante com o carto de crdito), e para validar a venda, todas as
transaes devero ser aprovadas, caso contrrio, as transaes no podem ser concludas (no
tem sentido que a venda seja considerada concluda apenas com a aprovao de parte do valor
da compra).
Em cada venda realizada, a aplicao deve abrir a sesso, realizar as diversas transaes e
finalmente fechar a sesso, confirmando ou desfazendo todas as transaes desta venda. A
estrutura do fluxo bsico de funcionamento do SCOPE Client encontra-se na figura 4.
IMPORTANTE: numa sesso de multi-TEF em que h vrias transaes, no possvel
desfazer uma ou outra transao. Para isso, o operador dever cancelar todas daquela
sesso ou confirm-las.
31
Figura 5: viso geral do funcionamento do SCOPE Client.
Abrindo uma sesso

A funo ScopeAbreSessaoTEF() informa ao SCOPE para iniciar uma sesso de TEF (ciclo com
uma ou mais transaes TEF). Ela deve ser invocada ao finalizar a venda e antes de selecionar o
meio de pagamento.
Prottipo
LONG EXPORT ScopeAbreSessaoTEF (void)
Parmetros
No h parmetro.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE00
65024
Significado
Exemplo
...
// Conecta ao servidor do SCOPE
32
...
// Realiza a venda
...
retorno = ScopeAbreSessaoTEF();
if (retorno != 0)
{
// Trata o erro e interrompe a sequncia.
}
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.

Cdigos Retorno
Hexadeci Decimal
mal
0xFB08
64264
0xFE00
0xFE01
65024
65025
Significado
Erro no arquivo de controle utilizado finalizao no ciclo multiTEF
Exemplo
BYTE acao, defez;
...
// Realiza a(s) transao(s) desejada(s)
...
33
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. Se o parmetro que permite que a
aplicao interfira na concluso de transaes em caso de quedas de energia estiver habilitado
(ver tabela de configuraes gerais), realizado o desfazimento ou a confirmao das transaes
pendentes, de acordo com o parmetro de entrada escolhido pelo operador. Se o parmetro
estiver desabilitado, aps a aplicao ter restabelecido a conexo com o servidor SCOPE, ela
dever chamar essa funo para finalizar uma possvel sesso que ainda esteja em aberto.
Nesse caso, realizado o desfazimento das transaes pendentes, independentemente, do
parmetro de entrada.
Um detalhe importante que uma sesso de TEF considerada finalizada ao iniciar a execuo
dessa funo. Desta forma, mesmo que ocorra queda de energia durante a execuo dessa
funo, o SCOPE considera como finalizado a sesso de TEF e proceder para realizar a ao
solicitada.
O segundo parmetro faz o papel principal no tratamento em queda de energia. Este parmetro
independente do primeiro parmetro e somente tem funcionalidade nesta situao. Caso este
parmetro seja devolvido com o valor 1 (True), a aplicao deve exibir a mensagem A
transao TEF anterior foi desfeita (cancelada). Reter o cupom TEF, e se possvel, acionar
um supervisor para verificar a situao.
Exemplo
...
BYTE acao, defez;
...
...
ScopeFechaSessaoTEF(acao, &defez);
if (desfez)
{
printf(A transao TEF anterior foi desfeita (cancelada).);
printf(\n Reter o cupom TEF.);
}
...
34
IMPORTANTE: sempre que tratar uma possvel queda de energia e o segundo parmetro
da funo ScopeFechaSessaoTEF() retornar o valor 1, deve-se imprimir a mensagem:
A transao TEF anterior foi desfeita (cancelada). Reter o cupom TEF
Deixando transao pendente na queda de energia

possvel tambm 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 pendentes as transaes.
Prottipo
LONG EXPORT ScopeMTEFOnOff (BYTE Trata)
Parmetros
[in]
Byte
Trata
Informa o SCOPE para desfazer (0)

possveis transaes 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.

Cdigos Retorno
Hexadeci Decimal
mal
0xFE00
65024
0xFE01
65025
Significado
Exemplo
...
BYTE acao, defez;
...
...
ScopeMTEFOnOff(1);
// deixa pendente
ScopeFechaSessaoTEF(acao, &defez);
if (desfez)
{
printf(A transao TEF anterior foi desfeita (cancelada).);
printf(\n Reter o cupom TEF.);
}
...
35
Status de transao
Durante o processamento da transao, a aplicao pode consultar o estado em que a transao
est e tomar alguma ao baseado no valor dela. Esta ao pode estar entre uma das situaes
abaixo, conforme o intervalo de cdigos retornado pelo SCOPE Client:
valor igual 0: transao finalizada com sucesso.
valores entre 3 (3h) e 92 (5Bh): erro de algum parmetro passado para o SCOPE;
valores entre 64001 (FA01h) e 64005 (FA05h): erro de algum parmetro passado para o
SCOPE;
valores entre 64257 (FB01h) e 64267 (FB0Bh): erro interno do SCOPE;
valores entre 64512 (FC00h) e 64767 (FCFFh): coleta de algum dado necessrio
transao;
valores entre 65024 (FE00h) e 65535 (FFFFh): erro reportado pelo SCOPE referente
transao;
Enquanto o SCOPE Client devolver o cdigo de status igual a 65024 (FE00 h), 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

Cdigos Retorno
Hexadeci Decimal
mal
0xFE00
65024
0xFE01
65025
Significado
Exemplo
...
// Abre sesso
retorno = ScopeCompraCartaoCredito(valor, taxa_servico);
if (retorno == 0)
{
do
{
retorno = ScopeStatus();
// trata conforme retorno
if (retorno == 64024)
36
{
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
}
...
37
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.
32
128
Permite a gravao em arquivo dos dados da coleta para ser recuperado em

caso de queda de energia.
Permite que a aplicao interfira na concluso de transaes que no foram
38
finalizadas apropriadamente em caso de quedas de energia, confirmando ou

desfazendo as transaes de acordo com a deciso do operador.
Se habilitado, permitir a coleta de saque em operaes de dbito vista.
256
Atualmente s usado pela rede autorizadora Cielo.
IMPORTANTE: este tipo de configurao s permitido quando a aplicao est utilizando

a interface coleta.
Configurando em tempo de execuo

A funo ScopeConfigura(), responsvel para a configurao da aplicao de PDV citada acima,
poder ser executada apenas uma nica vez aps a inicializao do SCOPE ou antes das
operaes TEF.
Prottipo
LONG EXPORT ScopeConfigura (LONG Id, LONG Param)
Parmetros
[in]
LONG
Id
[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

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
0xFF59
65369
Significado
Parmetro 1 invlido
Funo de uso exclusivo na interface coleta
Exemplo
...
// conexo com o scope server bem sucedida
...
// trabalhando com impressora carbonada
retorno = ScopeConfigura(16, 1);
...
39
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

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
Significado
Parmetro 1 invlido
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().
40
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 subsequentes 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

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
Significado
Exemplo
...
// Conexo ao ScopeSRV bem sucedida
...
retorno = ScopeSetAplColeta();
...
41
42
Figura 6: fluxo de processamento de uma transao com a interface coleta.
Obtendo os parmetros da transao

Durante a iterao do processamento de uma transao, a aplicao deve obter informaes
necessrias para solicitar a coleta do dado para o operador e/ou cliente. A funo
ScopeGetParam(), responsvel em descrever os dados a coletar, deve ser chamada sempre que
o SCOPE Client retornar um estado de coleta correspondente a uma coleta de dados (ver Status
de transao). Com o retorno do SCOPE Client, a aplicao de PDV dever atualizar as
mensagens das telas do operador e/ou cliente, disponibilizar um meio de entrada de dado, validar
a entrada, entre outras aes. A aplicao deve prover o operador de algum meio que ele possa
cancelar, retornar e continuar a coleta de dados da transao.
As mensagens que o SCOPE Client disponibiliza para serem exibidas so fundamentadas no fato
de que no PDV haja dois visores (display): um que apresentado ao cliente da loja e outro,
apresentado ao operador do PDV. Alm disso, por padro, considera-se que cada um desses
visores possua 2 linhas de exibio de mensagens com largura de 40 caracteres. possvel
configurar o tamanho mximo de colunas para at 20 ou 16 (ver o captulo Configurao).
Estruturas de apoio
Para a aplicao receber do SCOPE Client as informaes para coleta, ela dever passar
um endereo de memria de um buffer que representado, em linguagem C, pela estrutura
ptPARAM_COLETA definida no arquivo ScopeApi.h, cuja declarao :
typedef struct _stPARAM_COLETA
{
WORD
Bandeira;
WORD
FormatoDado;
WORD
HabTeclas;
char
MsgOp1[64];
char
MsgOp2[64];
char
MsgCl1[64];
char
MsgCl2[64];
char
WrkKey[16+1];
#ifdef __linux__
char
filler;
#endif
WORD
PosMasterKey;
char
PAN[19+1];
BYTE
UsaCriptoPinpad;
BYTE
IdModoPagto;
BYTE
AceitaCartaoDigitado;
char
Reservado[105];
} stPARAM_COLETA, *ptPARAM_COLETA;
A descrio de cada campo encontra-se abaixo:
Bandeira: a bandeira do carto relativa operao em andamento (ver Cdigo das

bandeiras);
FormatoDado: cdigo respectivo ao formato do dado a ser coletado (ver tabela de

cdigos em Formato dos dados);
HabTeclas: teclas que esto disponveis para a aplicao. um campo com

combinao de bits. Exemplo: se o campo estiver com o valor 6 (2 + 4 = 6), significa
que as teclas para prosseguir (valor 2) e retornar (valor 4) a coleta devem estar
43
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

Cdigos Retorno
Significado
44
Hexadeci
mal
0xFA01
0xFE01
Decimal
64001
65025
Parmetro 1 invlido
Exemplo
...
// executa transao (crdito, dbito, etc.)
stPARAM_COLETA Pcoleta;
...
// inicia iterao
retorno = ScopeStatus();
if(retorno != 0xFE00)
{
...
memset(&PColeta, '\0', sizeof(PColeta));
retorno = ScopeGetParam(retorno, &PColeta);
// atualiza as teclas retornar, avanar e cancelar
// coleta os dados
...
// entrega o que coletou ao SCOPE
...
}
// finaliza iterao
Passando o dado da coleta ao SCOPE Client

Realizando a coleta de dados solicitada pelo SCOPE via funo ScopeStatus(), a aplicao
devolver o que foi coletado e alguma ao ao SCOPE. A ao se refere interrupo do
processamento, retorno para um estado anterior ou continuao para o prximo estado de coleta.
Os dados coletados so entregues ao SCOPE por meio da funo ScopeResumeParam().
Prottipo
LONG
EXPORT
ScopeResumeParam
(LONG
codTipoColeta,
char
*dados,
WORD
dadosParam, eACAO_APL acao)
Parmetros
[in]
LONG
codTipoColeta
[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

45
Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE01
65025
0xFE04
65028
0xFF10
65296
Significado
Parmetro 1 invlido
No existe transao suspensa
Dado invlido
Exemplo
...
// executa transao (crdito, dbito, etc.)
char *dados[128];
WORD modo_entrada;
...
// inicia iterao
cod_coleta = ScopeStatus();
if(cod_coleta != 0xFE00)
{
...
// obtm os parmetros para a coleta
// atualiza as teclas retornar, avanar e cancelar
// coleta os dados e armazena em na varivel dados
modo_entrada = 0x0004;
// pelo teclado
// obtm a ao que o usurio escolheu e coloca em acao

...
// entrega o que coletou ao SCOPE na funo abaixo
ScopeResumeParam(cod_coleta, dados, modo_entrada, acao);
...
}
// finaliza iterao
Para resolver uma necessidade de alguns clientes que desejam manipular os itens do Menu
Dinmico montados atravs da Inicializao de Tabelas pelas redes VISANET-4.1 e CIELO,
foram definidas duas novas funes exportadas pelo SCOPE Client, conforme abaixo. A ideia
que, ao receber o estado TC_EXIBE_MENU (que j existe hoje), o PDV possa opcionalmente
chamar a funo ScopeMenuRecuperaItens do SCOPE para receber os itens do Menu a serem
exibidos e em seguida chamar a ScopeMenuSelecionaItem para indicar ao SCOPE qual item foi
selecionado.
Desta forma, o PDV poder, por exemplo:
Exibir todos os itens na mesma tela (hoje, pelo fluxo do SCOPE Client, apresentado um
item por vez);
Excluir algum item da lista que eventualmente no deva ser exibido ao operador;
Alterar a descrio de algum item para melhor entendimento do operador;
Fazer a seleo automtica de um determinado item sem apresent-lo ao operador;
46
OBSERVAO: O ndice do item selecionado deve ser equivalente ao item da tabela

fornecida pelo Scope, independente de ter sido exibido para o usurio ou no. Por exemplo,
se o menu tem 10 itens, alguns deles no foram exibidos e o operador seleciona o ltimo
item do menu, o item a ser selecionado continua sendo o ndice 10 (valor a ser passado
pelo ScopeMenuSelecionaItem).
Prottipo
dllScopeAPI ScopeMenuRecuperaItens(BYTE _TipoTabela, char *_Buffer, WORD
_TamBuffer);
Parmetros
Fixo em 1. Para permitir evolues futuras.
[in] BYTE
_TipoTabela
[in] String
_Buffer
Ponteiro para rea alocada pela aplicao, para receber os

itens do menu, formato abaixo.
[in] WORD
_TamBuffer
Tamanho da rea alocada disponvel;
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFA03
64003
0xFF6B
65387
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Parmetro 3 invlido
No Encontrado (para quando no veio menu dinmico na
carga de tabelas).
Estruturas do Menu Dinmico

typedef struct {
char
CodFuncao[4+1];
char
Descricao[40+1];
char
CodGrupoServico[2+1];
char
CodFluxoPDV[3+1];
char
CodRede[3+1];
char
CodBandeira[3+1];
char
CodFuncaoRede[4+1];
} stScopeItemMenuDinamico, *LPScopeItemMenuDinamico;
typedef struct {
char
TipoTabela;
char
QtdItens;
stScopeItemMenuDinamico sItem[15];
} stScopeMenuDinamico, *LPScopeMenuDinamico;
Prottipo
dllScopeAPI ScopeMenuSelecionaItem(char _Item);
47
Parmetros
[in] BYTE
_Item
ndice do item selecionado
Retorno
O uso destas novas funes opcional. Caso no utilizadas o tratamento do Menu Dinmico ser
da mesma forma sem a chamada (todos os itens exibidos).
As configuraes relativas ao Menu Dinmico existentes hoje no SCOPE.INI do ScopeSRV sero
mantidas.
Caso seja necessrio alterar algum item ou comportamento do menu, recomendamos antes entrar
em contato com o representante da Cielo para solicitar aprovao das alteraes e verificar a
necessidade de recertificao do software de frente de loja.
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().
48
Figura 7: fluxo de processamento de uma transao com a interface HLAPI.

49
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

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE01
65025
Significado
Parmetro 1 invlido
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

Cdigos Retorno
Significado
50
Hexadeci
mal
0xFE00
0xFE01
0xFE04
Decimal
65024
65025
65028

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

Cdigos Retorno
Hexadeci Decimal
mal
0xFE00
65024
0xFE01
65025
0xFE04
65028
0xFB01
64257
0xFB09
64265
Significado
No foi possvel criar a thread na coleta de dados
Estourou o nmero mximo de TEF numa sesso multi-TEF
Exemplo
...
// transao suspensa
...
// deseja-se cancelar a transao
ScopeAbort();
...
51
CUIDADO: s possvel abortar uma transao quando ela est suspensa.
52
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]
[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
Estados de coleta
A tabela abaixo mostra os estados de coleta que o fluxo poder retornar, no modo coleta.
Cdigos Retorno
Hexadeci Decimal
mal
0xFC00
64512
0xFC01
64513
0xFC02
64514
0xFC03
64515
0xFC09
64521
0xFC0E
64526
0xFC0A
64522
Significado
0xFC18
64536
Coletar carto
Coletar validade do carto
Imprime Cupom
Coletar CGC ou CPF
Coletar se a transao ser a vista ou no
Coletar quantidade de parcelas
Coletar se a transao ser parcelada pela administradora ou
pelo estabelecimento
Coleta os 4 ltimos dgitos do carto
0xFC1F
0xFC24
64543
64548
Coletar quantidade de dias

Coletar nmero do endereo
53
0xFC26
0xFC28
0xFC34
64550
64552
64564
Coletar plano de pagamento (Fininvest)

Coletar nmero do item (Fininvest)
Coleta o valor da transao
0xFC53
0xFC6D
0xFC6E
0xFC6F
0xFC0E
0xFC15
0xFC1B
0xFC20
0xFC23
0xFC33
0xFC64
0xFC7E
0xFC80
0xFC84
0xFC85
0xFC8A
0xFC29
0xFC2F
0xFC30
0xFC51
0xFCA5
0xFCFE
0xFCFF
64595
64621
64622
64623
64526
64533
64539
64544
64547
64563
64612
64638
64640
64644
64645
64650
64553
64559
64560
64593
64677
64766
64767
Coleta cdigo do material

Coleta a data de emisso do carto
Coleta o plano Infocards
Coleta nmero do cupom fiscal
Coletar valor de entrada
Imprime consulta
Coletar o nmero da pr-autorizao
Coletar CEP
Coleta valor da taxa de servio
Coleta RG
Go On Chip
Coleta o valor da taxa de embarque
Obtm os servios
Coleta o carto digitado
Coleta a data quando o cliente aderiu ao carto
Coletar cdigo de segurana
Coleta cdigo da localidade do telefone
Coleta nmero do telefone
Imprime cupom promocional
Coleta o nmero do Voucher
Mostrar informaes e retornar fluxo para o cliente SCOPE
Mostrar Informaes e aguardar confirmao do operador

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFB01
64257
0xFB03
0xFB09
0xFE01
0xFE05
64259
64265
65025
65029
0xFE06
0xFE07
65030
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFF0C
65290
65292
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Erro ao verificar mensagem mensagem invlida
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
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).
ScopeSrv off-line ou o IP configurado no arquivo scope.ini est
apontando para a mquina errada
Banco de dados off-line
Transao no implementada
54
0xFF1D
65309
0xFF36
65334
0xFF3A
0xFF60
0xFF5E
65338
65376
65374
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
Erro no envio da confirmao ou desfazimento da transao
anterior
Erro interno na execuo da coleta
Funo indisponvel
Erro ao desmontar a estrutura ISO
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
...
// obtm o valor da compra e armazena em valor
// obtm a taxa de servio e armazena em taxa
// abre sesso
...
retorno = ScopeCompraCartaoCredito(valor, taxa);
...
// processa a transao
...
// fecha a sesso
...
Consulta a financiamento de carto de crdito

Antes de realizar uma compra financiada pela administradora de carto de crdito, possvel
consulta das parcelas do financiamento. A consulta seguir os moldes de uma transao de
compra, sendo que em nenhum momento ser efetivada. Portanto, aps a consulta, necessrio
realizar a compra, que solicitar os mesmos dados da consulta.
Prottipo
LONG EXPORT ScopeConsultaCredito (char *Valor, char *TxServico)
Parmetros
[in]
[in]
String com o
mximo de 12
dgitos
String
Valor

(exemplo: R$ 123,00 = 12300)
TxServico
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
0xFE01
65025
0xFE06
65030
Significado
Parmetro 1 invlido
Logon duplicado
55
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFF1D
65290
65309
0xFFFF
0xFF5E
65535
65374

POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
...
// abre sesso
...
retorno = ScopeConsultaCredito(valor, taxa);
...
...
// 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

Cdigos Retorno
Hexadeci Decimal
mal
0xFE00
65024
Significado
56
0xFE01
0xFE06
0xFE07
65025
65030
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
*0xFF1D
65290
65309
0xFFFF
0xFF5E
65535
65374

Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
// abre sesso
...
retorno = ScopeConsultaSaldoCredito();
...
...
// fecha a sesso
...
Pr-autorizao de crdito
Como a consulta de saldo do carto de crdito no est disponvel para todos os cartes e por
representar certo risco (cartes roubados podero ter todo o seu limite gasto, sendo conhecido o
seu saldo), outras administradoras disponibilizam a opo de pr-autorizao. Assim, antes de
fazer a compra, possvel realizar uma pr-autorizao para verificar se a compra proceder com
sucesso.
Prottipo
LONG EXPORT ScopePreAutorizacaoCredito (char *Valor, char *TxServico)
Parmetros
[in]
[in]
String com o
mximo de 12
dgitos
String
Valor

(exemplo: R$ 123,00 = 12300)
TxServico
Retorno

57
Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFE00
65024
0xFE01
65025
0xFF1D
65309
0xFE06
0xFE07
65030
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFF1D
65290
65309
0xFFFF
0xFF5E
65535
65374
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
...
// abre sesso
...
retorno = ScopePreAutorizacaoCredito(valor, taxa);
...
...
// fecha a sesso
...
58
Carto de dbito
Abrangendo diversos servios, como o carto de dbito, uma das transaes mais realizadas
nos estabelecimentos. Falando em servios, nos referimos a dbito vista, dbito pr-datado,
dbito parcelado com a 1 parcela agendada ou vista, dbito Voucher, saque e CDC.
Compra com carto de dbito

Para os servios de dbito vista, dbito pr-datado, dbito parcelado com a 1 parcela
agendada ou vista e dbito Voucher, deve-se utilizar a funo ScopeCompraCartaoDebito().
Como as outras transaes, o fluxo de processamento similar.
Prottipo
LONG EXPORT ScopeCompraCartaoDebito (char *Valor)
Parmetros
[in]
String com o
mximo de 12
dgitos
Valor

(exemplo: R$ 123,00 = 12300)
Retorno
Estados de coleta
A tabela abaixo mostra os estados de coleta que o fluxo poder retornar, no modo coleta
Cdigos Retorno
Hexadeci Decimal
mal
0xFC00
64512
0xFC01
64513
0xFC02
64514
0xFC03
64515
0xFC09
64521
0xFC0B
64523
0xFC0C
64524
0xFC0D
64525
0xFC0E
64526
0xFC10
64528
0xFC11
64529
0xFC13
64531
0xFC14
64532
0xFC15
64533
0xFC18
64536
0xFC1A
64538
0xFC1B
64539
0xFC22
64546
0xFC23
64547
0xFC24
64548
0xFC25
0xFC2B
0xFC2C
0xFC30
64549
64555
64556
64560
Significado
Coletar carto
Imprime Cupom
Coletar CGC ou CPF
Coletar se a transao ser pr-datada
Coletar se a parcela ser vista
Coletar quantidade de dias entre parcelas
Coletar o dia e o ms (DDMM)
Coletar a senha
Coletar a forma de pagamento
Coletar data do primeiro vencimento
Coletar ltimos dgitos do carto
Coletar se deseja consultar parcelas
Imprime consulta
Imprime nota promissria
Coletar CEP
Coletar parte numrica do complemento
Coleta se com ou sem garantia de pr-datado
Coleta se aceita ou no risco
59
0xFC32
0xFC33
0xFC47
0xFC51
0xFC52
0xFC64
0xFC66
0xFC7B
0xFC7D
0xFC7E
0xFC7F
0xFC80
0xFC85
0xFC87
0xFC95
0xFC96
0xFC9F
64562
64563
64583
64593
64594
64612
64614
64635
64637
64638
64639
64640
64645
64647
64661
64662
64671
0xFCA5
0xFCBE
0XFCC1
64677
64702
64705
0xFCCB
0xFCFE
0xFCFF
64715
64766
64767
Coleta data (formato DDMMAA)

Coleta quantidade de parcelas e aceita 1 parcela
Coleta se utiliza saldo
Coleta RG
Coleta somente CPF
Coleta o valor da primeira parcela
Coleta se cancela ou no a transao
Go On Chip
Retira o carto
Exibe o menu
Coleta o valor das parcelas
Coleta se a primeira parcela para 30 ou 60 dias
Coleta a placa do veculo (transao de convnio combustvel
Banrisul)
Coleta dados ECF
Coleta opo de pagamento de carn para GetnetLAC no
servio de dbito a vista para bandeira ELECTRON (0=No
para pagamento de carn, 1=Sim para pagamento de carn).
*Coleta da Lista de Mercadorias Consumidas

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374
Significado
Parmetro 1 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
char valor[12 + 1];
...
60
...
// abre sesso
...
retorno = ScopeCompraCartaoDebito(valor);
...
...
// fecha a sesso
...
Compra CDC (Crdito Direto ao Consumidor)

Apesar de existir uma funo ScopeCompraCDC() responsvel por essa modalidade de servio,
esta transao foi incorporada ao fluxo da transao ScopeCompraCartaoDebito() devido
exigncia da especificao Visanet 4.1. O que difere no fluxo de um pagamento com carto de
dbito que um CDC um dbito parcelado pela administradora.
Caso no fluxo de compra CDC for realizado uma consulta, os cupons da consulta no podero ser
impressos devido a problemas de controle fiscal. Estes cupons devero ser exibidos no visor para
o cliente. Somente os cupons da compra que devero ser impressos caso haja interesse em
continuar a compra aps a consulta.
Consulta CDC
Para uma simples consulta CDC, independente da compra, deve-se utilizar a funo especfica
para a transao: ScopeConsultaCDC(). O resultado desta transao ser um cupom com valores
do parcelamento com as taxas.
Quando a consulta for realizada por esta funo, os cupons da consulta devero ser enviados
para a impressora.
Prottipo
LONG EXPORT ScopeConsultaCDC (char *Valor, char *TxServico)
Parmetros
[in]
[in]
String com o
mximo de 12
dgitos
String
Valor

(exemplo: R$ 123,00 = 12300)
TxServico
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
Significado
Parmetro 1 invlido
Logon duplicado
61
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFF0C
0xFF1D
65290
65292
65309
0xFFFF
0xFF5E
65535
65374
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
...
// abre sesso
...
retorno = ScopeConsultaCDC(valor, taxa);
...
...
// fecha a sesso
...
LEMBRETE: a compra CDC efetuada no fluxo de dbito, ou seja, dever ser chamada a
funo ScopeCompraCartaoDebito() para a realizao dessa compra.
Simulao Credirio
Atualmente esta transao de uso exclusivo da rede Cielo. Seu uso opcional, j que a mesma
transao pode ser feita atravs da ScopeMenu. Quando feita atravs desta ltima, segue as
regras de seleo de produtos da Cielo.
Prottipo
LONG EXPORT ScopeSimulacaoCrediario (WORD CodGrupoServico, char *Valor,
char *TxServico)
Parmetros
[in]
Numrico
CodGrupoServico
Reservado para uso futuro. H previso de

62
esta funcionalidade ser usada atravs de

cartes de Crdito no futuro, mas
atualmente est disponvel apenas para
cartes de Dbito.
Portanto, usar fixo 1 (Dbito).
[in]
[in]
String com o
mximo de 12
dgitos
String
Valor

(exemplo: R$ 123,00 = 12300)
TxServico
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFF0C
0xFF1D
65290
65292
65309
0xFFFF
0xFF5E
65535
65374
Significado
Parmetro 1 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
...
// abre sesso
...
retorno = ScopeSimulacaoCrediario(1, valor, taxa);
...
...
63
// fecha a sesso
...
LEMBRETE: A transao de Compra Credirio efetuada no fluxo de dbito, ou seja,

dever ser chamada a funo ScopeCompraCartaoDebito() para a realizao dessa
compra. Quando configurada na inicializao da Cielo (tabela 7C de Produtos), o SCOPE
ir exibir um menu de seleo, por exemplo (Dbito ou Credirio). Se selecionado Dbito, o
SCOPE seguir o fluxo convencional de Dbito. Se selecionado Credirio o SCOPE seguir
o fluxo especfico desta transao.
Consulta a saldo de carto de dbito

Um dos motivos que uma transao pode no ser aprovada a falta de saldo suficiente do cliente
no carto de dbito. Alguns cartes permitem esta consulta.
Prottipo
LONG EXPORT ScopeConsultaSaldoDebito (char *Valor)
Parmetros
[in]
String com o
mximo de 12
dgitos
Valor

(exemplo: R$ 123,00 = 12300)
Retorno
Exemplo
...
char valor[12 + 1];
...
...
// abre sesso
...
retorno = ScopeConsultaSaldoDebito(valor);
...
...
// fecha a sesso
...
64
Carto Dinheiro
So cartes ao portador, protegido por senha, semelhante ao carto de dbito 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 (dbito)
Consulta a saldo
Estornos
Compra/Carga do carto dinheiro

Para realizar a operao de recarga, e tambm, a compra (carga inicial) do carto dinheiro, devese utilizar a funo ScopeCartaoDinheiro(), como descrito abaixo.
Prottipo
LONG EXPORT ScopeCartaoDinheiro (WORD servico, char *Valor)
Parmetros
[in]
WORD
Servico
Para efetuar a operao de Compra/Carga

de carto dinheiro usar o servio 110
S_CARGA_CARTAO_DINHEIRO
[in]
String com o
mximo de 12
dgitos
Valor

(exemplo: R$ 123,00 = 12300)
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
0xFE01
65025
0xFF0C
65292
Significado
Parmetro 1 invlido
Exemplo
...
Long servico = S_CARGA_CARTAO_DINHEIRO; // valor de 110
char valor[12 + 1];
...
65

// abre sesso
...
retorno = ScopeCartaoDinheiro(servico, valor);
...
...
// fecha a sesso
...
Compra usando o carto dinheiro (dbito)

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 dbito

normal (vide item Compra com carto de dbito).
2.
Usar a funo ScopeCartaoDinheiro(), como descrito abaixo.
Prottipo
LONG EXPORT ScopeCartaoDinheiro (WORD servico, char *Valor)
Parmetros
[in]
WORD
Servico
Para efetuar a operao de Compra/Carga

de carto dinheiro usar o servio 98
S_COMPRA_CARTAO_DINHEIRO
[in]
String com o
mximo de 12
dgitos
Valor

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

...
// abre sesso
...
retorno = ScopeCartaoDinheiro(servico, valor);
...
...
// fecha a sesso
...
66
Consulta ao saldo de carto dinheiro

A consulta ao saldo de carto dinheiro e a respectiva impresso de cupom deve ser feita usando
a funo ScopeConsultaCartaoDinheiro(), como descrito abaixo.
Prottipo
LONG EXPORT ScopeConsultaCartaoDinheiro (void)
Parmetros
No h parmetros.
Retorno
Exemplo
...
// abre sesso
...
retorno = ScopeConsultaCartaoDinheiro();
...
...
// fecha a sesso
...
Estornos
Tanto para realizar a operao de estorno de compra/carga do carto dinheiro como a compra
usando o carto dinheiro (dbito) deve se usar a funo genrica de estorno chamada
ScopeCancelamento(). A documentao desta funo esta descrita no captulo Estorno de
transaes.
67
Funes de Consulta
Neste captulo falamos sobre as transaes de consultas que no se referem aos cartes.
Cheque
Outra funcionalidade que o SCOPE dispe a consulta de cheques no Serasa ou na ACSP
Associao Comercial de So Paulo. Nas consultas de cheques, via PDVs, as respostas so
baseadas no nmero do documento (CPF/CGC), banco, nmero do cheque do comprador, valor e
data de vencimento da compra.
O nmero do cheque composto por seis caracteres numricos, por definio do Banco Central
do Brasil com base na resoluo 885, de 22/12/1983.
Consulta de cheques
A transao de consulta a cheque iniciada pela funo ScopeConsultaCheque(). O fluxo de
processamento similar s outras transaes.
Prottipo
LONG EXPORT ScopeConsultaCheque (char *Valor)
Parmetros
[in]
String com o
mximo de 12
dgitos
Valor

(exemplo: R$ 123,00 = 12300)
Retorno

Hexadeci
mal
0xFA01
0xFE00
0xFE01
0xFE06
0xFE07
Decimal
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374
64001
65024
65025
65030
65031
Parmetro 1 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
68
Exemplo
...
char valor[12 + 1];
...
// obtm o valor do cheque e armazena em valor
// abre sesso
...
retorno = ScopeConsultaCheque(valor);
...
...
// fecha a sesso
...
AVS
Termo em ingls Address 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

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
Significado
Parmetro 1 invlido
69
0xFE01
0xFF0C
0xFE06
0xFE07
65025
65292
65030
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374

Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
// abre sesso
...
retorno = ScopeConsultaAVS();
...
...
// fecha a sesso
...
70
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.
Configurando a recarga de celular

Para a Recarga de Celular devem ser efetuadas as configuraes a seguir:
ScopeCNF: ver no documento 'Scope - Manual de Instalao e Configurao.doc'

cadastrando os atributos para a Recarga de Celular.
ScopeINI: O tamanho mnimo de dgitos permitidos para serem lidos pelo PIN-Pad deve
ser configurado como descrito no item "Configurao do arquivo scope.ini" seo "Sesso
[PINPAD]" deste documento.
Processando a recarga de celular

Apesar de o 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().
71
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
Estados de coleta
Cdigos Retorno
Hexadeci Decimal
mal
0xFC02
64514
0xFC2E
64558
0xFC2F
64559
0xFC30
64560
0xFC70
64624
0xFC90
64656
0xFCB5
64693
0xFCBC
64700
0xFCBD
64701
Significado
Imprime Cupom
Coleta valor da recarga de celular pr-pago
Coleta a operadora de recarga de celular pr-pago
Coleta o DDD no PINPad
Coleta redigitao do DDD
Coleta DDD + Telefone no PIN Pad
Redigita DDD + Telefone no PIN Pad

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374
Significado
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
// abre sesso
...
72
retorno = ScopeRecargaCelular();
...
...
// fecha a sesso
...
Obtendo operadoras disponveis

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

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

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

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

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

aplicao deseja receber a lista de
operadoras. Aceita apenas o valor 2.
Buffer com a lista de operadoras.
Tamanho do buffer anterior, previamente
alocado, que deve ser maior ou igual a
2002 bytes.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
Significado
Parmetro 1 invlido
75
0xFA02
0xFA03
64002
64003
Parmetro 2 invlido
Parmetro 3 invlido
Exemplo
...
stREC_CEL_OPERADORAS ListaOper;
...
// obtm status do SCOPE
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
76
41 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
12 bytes
Mensagem promocional a ser exibida com os valores
Estruturas de apoio
Definidas no arquivo de cabealho ScopeApi.h, esto as estruturas abaixo, que so
utilizadas para o recebimento do buffer de valores. A primeira delas:
typedef struct
{
char TipoValor;
char ValorMinimo[12];
char ValorMaximo[12];
char Totvalor;
stREC_CEL_VALOR TabValores[10];
char MsgPromocional[41];
} stREC_CEL_VALORES, *ptREC_CEL_VALORES;
, onde:
77
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);
ValorMaximo: este campo uma cadeia com 12 caracteres numricos que

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

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

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

stREC_CEL_VALOR, descrita abaixo.
typedef struct
{
char Valor[12];
char Bonus[12];
char Custo[12];
} stREC_CEL_VALOR, *ptREC_CEL_VALOR;
Valor: este campo uma cadeia com 12 caracteres numricos que representam um
valor fixo, para escolha do cliente, com a vrgula implcita (exemplo: caso o dado
neste campo seja 000000001500, ento ele est representando o valor R$15,00);
78
Bnus: este campo uma cadeia com 12 caracteres numricos que representam o
bnus que o cliente ganha ao escolher o valor fixo deste registro com a vrgula
implcita (exemplo: caso o dado neste campo seja 000000010000, ento ele est
Custo: este campo uma cadeia com 12 caracteres numricos que representam o
custo da recarga ao escolher o valor fixo deste registro com a vrgula implcita
(exemplo: caso o dado neste campo seja 000000005000, ento ele est
typedef struct
{
char TipoValor;
char ValorMinimo[10];
char ValorMaximo[10];
char Totvalor;
stREC_CEL_VALOR TabValores[10];
char MsgPromocional[41];
char TotFaixaValores;
stREC_CEL_FAIXA_VALORES_2 TabFaixaValores[10];
} stREC_CEL_VALORES_MODELO_4, *ptREC_CEL_VALORES_MODELO_4;
A rede GWCel 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;
Existe uma diferena na estrutura dos dados enviados pela GWCel dependendo a verso
de sua especificao.
Para a rede GWCel verso 003 a estrutura de Valores de Faixa a seguinte:
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.
Para a Gwcel verso 005, as estruturas de Valores de Faixa tambm possuem os campos
Bonus e Custo, antes s presentes na estrutura de valores fixos:
79
typedef struct
{
char ValorMin[12];
char ValorMax[12];
char Bonus[12];
char Custo[12];
} stREC_CEL_FAIXA_VALORES_2, *ptREC_CEL_FAIXA_VALORES_2;
ValorMin: indica o valor mnimo aceitvel para a recarga;
ValorMax: indica o valor mximo aceitvel para a recarga.
Bonus: Indica o valor do bnus que o cliente receber ao escolher a faixa.
Custo: Indica o custo da recarga.
Prottipo
LONG EXPORT ScopeRecuperaValoresRecCel (BYTE TpTab, char *buffer, WORD
TamBuf)
Parmetros
[in]
BYTE
TpTab
[out] String
Buffer
[in]
TamBuf
WORD

Buffer com a lista de valores de recarga
disponveis.
Tamanho do array buffer (segundo
parmetro) alocado que deve ser igual a
427 bytes.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFA03
64003
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Parmetro 3 invlido
Exemplo
...
stREC_CEL_VALORES tabVal;
...
{
...
case 64558:
ScopeRecuperaValoresRecCel(2, (char *)&tabVal, sizeof(buffer));
80
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.
Funes de consulta para recarga de celular

O Scope Client no disponibilizava funes de consulta a planos de recarga de celular, teis para
sistemas de retaguarda que desejavam vender pacotes de recarga antecipadamente dentro de
um pr-pedido.
Para contornar isso, foram adicionadas duas funes, uma para retornar as
operadoras e outra para retornar os valores disponveis para recarga de uma operadora de uma
localidade especfica.
Obtendo operadoras disponveis fora do fluxo de recarga

Para
obter
as
operadoras
disponveis,
deve
ser
feita
uma
chamada
funo
ScopeObtemOperadorasRecCelOffTEF(),ela retornar um buffer com as operadoras disponveis .
Prottipo
LONG
EXPORT
ScopeObtemOperadorasRecCelOffTEF
(BYTE
_TipoTabela,
char
*_Buffer, WORD _TamBuffer)
Parmetros
[in]
BYTE
_TipoTabela
[out] String
_Buffer
[in]
_TamBuffer
WORD

Buffer com a lista de operadoras.
Tamanho do buffer anterior, previamente
alocado, que deve ser maior ou igual a
2002 bytes.
Retorno
Exemplo
...
LONG RC;
stREC_CEL_OPERADORAS
ListaOper
stREC_CEL_ID_OPERADORA
OPER;
= {0};
...
// Obtem as operadoras.
81
RC = ScopeObtemOperadorasRecCelOffTEF(REC_CEL_OPERADORAS_MODELO_2,(P_CHAR)
&ListaOper, sizeof (ListaOper);
if(RC =! != RCS_SUCESSO)
{
return RC;
}
...
// exibe as operadoras
Obtendo valores de recarga disponveis fora do fluxo de recarga

Para obter os valores disponveis para recarga, deve ser feita uma chamda a funo
ScopeRecuperaValoresRecCelOffTEF() ela retornar um buffer com a lista de valores disponveis
para uma operadora de uma localidade especfica.
Prottipo
LONG
EXPORT
ScopeRecuperaValoresRecCelOffTEF(BYTE
_TipoTabela,
char
*_Buffer, WORD _TamBuffer, char* _CodOperadora, char* _CodLocalidade)
Parmetros
[in]
BYTE
_TipoTabela
[out] String
_Buffer
[in]
WORD
_TamBuffer
[in]
[in
String
String
_CodOperadora
_CodLocalidade

Buffer com a lista de valores de recarga
disponveis.
Tamanho do array buffer (segundo
parmetro) alocado que deve ser igual a
427 bytes.
Cdigo da bandeira da operadora
Cdigo da localidade (DDD)
Retorno
Exemplo
...
LONG RC;
char
codOperadora[3 + 1];
char
codLocalidade[2 + 1];
stREC_CEL_VALORES ListaValores = {0};

...
// Entra com o cdigo da operadora e a localidade
RC=ScopeRecuperaValoresRecCelOffTEF((BYTE)REC_CEL_VALORES_MODELO_2,(P_CHAR)
&ListaValores, sizeof (ListaValores),codOperadora,codLocalidade );
if ( RC == RCS_SUCESSO || RC == RCS_ACQUIRER_OFF)
{
// Exibe os valores
}
82
...
83
Estorno de transaes
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
desfeita (ver Encerrando a sesso).
Estornando a transao
Para a realizao do estorno, necessrio informar ao SCOPE os dados da transao original, e,
em muitas vezes, o nmero do controle gerado pelo prprio SCOPE na transao.
Prottipo
LONG EXPORT ScopeCancelamento (char *Valor, char *TxServico)
Parmetros
[in]
[in]
String com o
mximo de 12
dgitos
String
Valor

(exemplo: R$ 123,00 = 12300)
TxServico
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
65032
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Logon duplicado
POS no cadastrado
84
0xFE0A
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374

PDVs disponveis
Erro genrico
Exemplo
...
char valor[12 + 1];
char taxa[12 + 1];
...
// abre sesso
...
retorno = ScopeCancelamento(valor, taxa);
...
// processa o cancelamento
...
// fecha a sesso
...
85
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).
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 exibi-lo
na tela. No entanto, quando for apenas uma transao de consulta, isto , foi chamada
apenas uma funo do tipo ScopeConsulta<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
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
86
[in]
WORD
CupomLojaLen
[out] String
CupomLoja
[in]
CupomReduzLen
WORD
[out] String
CupomReduz
[out] WORD
NroLinhasReduz
IMPORTANTE:
disponvel para a aplicao de PDV

Tamanho reservado pela aplicao para
receber a via da loja
via da loja que sempre estar disponvel
para a aplicao
Tamanho reservado pelo aplicativo para
receber o cupom reduzido
via cupom reduzido que poder substituir a
via do cliente e que em alguns casos, esta
via pode no estar disponvel para a
aplicao
Nmero de linhas que tem o cupom
reduzido. Se o valor for zero, no h
cupom reduzido disponvel
Os
finalizadores
ScopeGetCupomEx
esto
de
de
linha
acordo
dos
cupons
com
retornados
pela
funo
parametrizao
do
ScopeForneceCampo(SCOPE_DADO_SEPARADOR_LINHA).
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE04
65028
0xFF12
65298
Significado
rea reservada para o buffer insuficiente para o SCOPE
Client x os dados solicitados
Exemplo
...
BYTE NroLnhReduzido = 0;
char Cabec[1024],
CpCliente[2048],
CpLoja[2048],
CpReduzido[2048];
LONG retorno;
...
{
...
case 64582:
case 64514:
case 64539:
case 64546:
case 64593:
87
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
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. 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
88

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
*0xFF1D
65290
65309
0xFFFF
0xFF5E
65535
65374
Significado
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
// abre sesso
...
retorno = ScopeReimpressaoOffLine ();
...
...
// fecha a sesso
...
IMPORTANTE: na reimpresso no h cupom reduzido.
IMPORTANTE:
funo
ScopeReimpressaoOffLine()
ScopeReimpressaoComprovante(). No entanto,
substitui
esta ltima ainda
anterior
mantida por
compatibilidade.
Solicitando o comprovante on-line

Utilizada nos casos em que a rede autorizadora ou o correspondente bancrio oferece a
transao (on-line) de reimpresso do comprovante do pagamento de conta.
Prottipo
LONG EXPORT ScopeReimpressaoOnLine (WORD CodBandeira)
89
Parmetros
[in]
WORD
CodBandeira
Cdigo da bandeira do carto (ver Cdigo

das bandeiras)
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
*0xFF1D
65290
65309
0xFFFF
0xFF5E
65535
65374
Significado
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
WORD CodBandeira;
// abre sesso
...
// Obtm a bandeira do carto
...
retorno = ScopeReimpressaoOnLine(CodBandeira);
...
...
// fecha a sesso
...
IMPORTANTE: para a certificao da Visanet 4.1 esta funo no necessria estar

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

90
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
- 2: apenas a via do cliente
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE04
65028
0xFF11
65297
Significado
No existe cupom vlido
Exemplo
...
BYTE NroLnhReduzido = 0,
EhReimpressao,
ViaReimpressao;
char Cabec[1024],
CpCliente[2048],
CpLoja[2048],
CpReduzido[2048];
LONG retorno;
...
{
91
...
case 64582:
case 64514:
case 64539:
case 64546:
case 64593:
memset(Cabec, 0, sizeof(Cabec));
memset(CpCliente, 0, sizeof(CpCliente));
memset(CpLoja, 0, sizeof(CpLoja));
memset(CpReduzido, 0, sizeof(CpReduzido));
retorno = ScopeGetCupomEx(sizeof(Cabec), Cabec,
sizeof(CpCliente), CpCliente,
sizeof(CpLoja), CpLoja,
sizeof(CpReduzido), CpReduzido,
&NroLnhReduzido);
if (retorno == RCS_SUCESSO)
{
retorno = ScopeObtemTipoViaReimpressao( &EhReimpressao,
&ViaReimpressao );
if(EhReimpressao == 0)
{
ImprimeCupomTEF("CABECALHO", Cabec);
if (NroLnhReduzido > 0)
ImprimeCupomTEF("CUPOM REDUZIDO", CpReduzido);
}
else
{
switch(ViaReimpressao)
{
case 0:
break;
case 1:
break;
case 2:
break;
}
}
}
break;
92
...
}
...
93
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, Lista de medicamentos com CRM e Lista de
medicamentos Ex).
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

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
94
Exemplo
...
BYTE
TipoConvenio, CodigoRede;
...
// abre sesso
...
// coleta o tipo do convnio, o cdigo da rede
...
retorno = ScopeConsultaMedicamento (TipoConvenio, CodigoRede);
...
...
// fecha a sesso
...
Nesse tipo de transao, o SCOPE no possui controle do valor de venda a ser registrado.
Portanto, ao receber o cdigo 64579 da funo de status, a aplicao deve atualizar o valor (ver
ScopeAtualizaValor), informando assim o valor da venda.
Exemplo
char VlOperac [12+1];
...
{
...
Case 64579:
RecebeValorDoOperador (&VlOperac);
iRet = ScopeAtualizaValor (VlOperac);
if (iRet != RCS_SUCESSO)
// Tratar erro
break;
...
Compra de medicamento
Para
iniciar
uma
compra
de
medicamentos
PBM,
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)
95
Parmetros
[in]
BYTE
TipoConvenio
[in]
BYTE
CodigoRede
NumCpFiscal
Nmero do cupom fiscal para o PDV
[out] String
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFA03
64003
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Parmetro 3 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
BYTE
char
*NumCpFiscal;
...
// abre sesso
...
// coleta o tipo do convnio, o cdigo da rede e o nmero do cupom fiscal
...
retorno = ScopeCompraMedicamento (TipoConvenio, CodigoRede, NumCpFiscal);
...
...
// fecha a sesso
...
96
Funcionamento a partir do layout 5

A mudana para o layout 5 (conforme descrito no documento Scope PBM - Verso
1.10.doc ) trouxe mudanas significativas no funcionamento da compra de medicamentos.
Para realizar uma compra de medicamentos, preciso obrigatoriamente ter feito uma
consulta de medicamentos antes e estar na mesma sesso TEF.
O motivo para tal funcionamento que a partir do layout 5, pode ser requisitado coleta de
senha atravs do bit 22 do retorno da consulta (mensagem 0110). Como essa informao
referente necessidade de coleta de senha deve ser coletada em uma transao diferente
(0200), ela armazenada em um arquivo de contexto e recuperado na compra de
medicamentos. Atualmente, as redes Vidalink e PBM Padro trabalham com o layout na
nova verso.
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(),
ScopeObtemMedicamentosComCRM()
ou
ScopeObtemMedicamentosEx(), que sero tratadas 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
97
ListaMedicamentos
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE04
65028
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374
Significado
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
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.
98
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
[in]
TamLista
WORD

consultados ou comprados
Retorna o tipo de convnio:
0: Pagamento vista;
1: Pagamento a prazo;
2: Empresa Fechada;
3: Empresa Aberta.
comprados
ListaMedicamentos
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE04
65028
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF11
0xFF12
65297
65298
0xFFFF
0xFF5E
65535
65374
Significado
Logon duplicado
POS no cadastrado
PDVs disponveis
rea reservada para o buffer insuficiente para o SCOPE
Client x os dados solicitados
Erro genrico
99
Lista de medicamentos Extendida

A funo ScopeObtemMedicamentosEx() recupera a lista dos medicamentos consultados ou
comprados em qualquer formato disponvel atualmente. A funo deve receber qual a verso que
se deseja da lista de medicamentos como ser descrito a seguir. Os formatos de listas antigas
permanecem os mesmos, porm, h o formato do layout 5 (conforme descrito no documento
Scope PBM - Verso 1.10.doc ) que obedece tabela abaixo:
Posio
Formato
Descrio
01 a 13
String
Cdigo EAN do medicamento.
14 a 15
String
Quantidade autorizada do produto.
16 a 17
String
Motivo da rejeio.
18 a 26
String
Cdigo do convnio.
27 a 34
String
Preo mximo ao consumidor.
35 a 42
String
Preo de venda.
43 a 50
String
Preo de fbrica.
51 a 58
String
Preo de aquisio.
59 a 66
String
Preo de repasse.
67 a 79
String
Nmero do CRM.
Prottipo
LONG EXPORT ScopeObtemMedicamentosEx(BYTE IdLayout,
BYTE *_QtdRegistros,
char *_ListaMedicamentos,
WORD _TamLista,
BYTE *_TipoConvenio)
Parmetros
[in]
BYTE
IdLayout
[out] BYTE
QtdRegistros
[out] String
ListaMedicamentos
[in]
TamLista
WORD
[out] BYTE
TipoConvenio
Verso da lista de medicamentos que se

deseja recuperar, devendo ser como
definido na tabela a seguir.
consultados ou comprados.
comprados.
ListaMedicamentos
Retorna o tipo de convnio:
0: Pagamento vista;
1: Pagamento a prazo;
2: Empresa Fechada;
3: Empresa Aberta.
100

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE04
65028
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFFFF
0xFF5E
65535
65374
Significado
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Layouts:
ID layout
Usar estrutura
stREGISTRO_MEDICAMENTO
stREGISTRO_MEDICAMENTO_CRM
stREGISTRO_MEDICAMENTO_L3
stREGISTRO_PHARMASYSTEM_RET
IMPORTANTE: Atualmente, somente a rede Vidalink e PBM Padro compatvel com o

layout 3 de estrutura.
Lista de Projetos
A funo ScopeRecuperaBufTabela() fornecer para a aplicao de automao comercial uma
lista de informaes a serem exibidas na tela para facilitar a seleo da opo desejada. Ela
servir para facilitar futuras implementaes que atendam a mesma finalidade. O parmetro
_TipoTabela indicar o formato dos dados que sero fornecidos.
LONG EXPORT ScopeRecuperaBufTabela
(BYTE TipoTabela,
char *_QtdRegistros,
char *_Buffer,
WORD _TamBuffer)
101
Parmetros
[out] String
QtdRegistros
[out] String
Buffer
Tipo de lista de elementos que se deseja

recuperar, devendo ser como definido na
tabela a seguir.
Retorna a quantidade de elementos da
tabela
Retorna os elementos da tabela.
[in]
TamBuffer
Tamanho, em bytes, do campo Buffer
[in]
TipoTabela
BYTE
WORD

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFA03
64003
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Parmetro 3 invlido
Layouts:
ID layout
Usar estrutura
BUF_TAB_PRJ_PHARMASYSTEM
(ID 0)
Descrio
stREGISTRO_PROJETO_PHMS
Projeto
PharmaSystem
O formato obedece tabela, conforme a especificao da PharmaSystem
Posio
Formato
Descrio
01 a 06
String
Cdigo do Projeto
07 a 36
String
Descrio do Projeto
37 a 56
String
Operadora do Projeto
Elegibilidade do Carto PBM

Para iniciar uma compra de medicamentos PDM, sem a existncia de uma autorizao
previamente fornecida por uma aplicao de balco de farmcia, deve-se chamar a funo
ScopeElegibilidadeCartao(), que far a validao dos dados do cliente que deseja efetuar a
compra. Essa funo suporta a bandeira PharmaSystem.
Prottipo
LONG EXPORT ScopeElegibilidadeCartao (BYTE _TipoConvenio,
102
BYTE _CodRede,
char *NumCpFiscal)
Parmetros
[in]
BYTE
_TipoConvenio
[in]
BYTE
_CodRede
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
Exemplo
...
BYTE
_TipoConvenio, _CodigoRede;
...
// abre sesso
...
...
retorno = ScopeElegibilidadeCartao (_TipoConvenio, _CodigoRede);
...
...
// fecha a sesso
...
103
Pre-Autorizacao de Medicamentos PBM

Para informar cada produto que ser includo na compra, obtendo informaes do mesmo, deve
ser chama a funo ScopePreAutorizacaoMedicamento(). A funo pode retornar no fluxo de
coleta o cdigo de coleta 64579 para fornecer a lista de medicamentos, e o cdigo de coleta
64580 para obter a lista de medicamentos. Essa funo suporta a bandeira PharmaSystem.
Prottipo
LONG EXPORT ScopePreAutorizacaoMedicamento (BYTE _TipoConvenio,
BYTE _CodRede,
char *NumCpFiscal)
Parmetros
[in]
BYTE
_TipoConvenio
[in]
BYTE
_CodRede
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Logon duplicado
Protocolo no suportado SCOPE Client com verso de protocolo
superior ao SCOPE Server
POS no cadastrado
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).
Erro genrico
Exemplo
...
BYTE
...
// abre sesso
...
...
104
retorno = ScopePreAutorizacaoMedicamento (TipoConvenio, CodigoRede);

...
...
// fecha a sesso
...
Cancelamento de Pre-Autorizacao de Medicamentos PBM

Para cancelar um produto da lista dos produtos autorizados, deve-se chamar a funo
ScopeCancelaPreAutMedicamento(), que excluir o produto e a quantidade da lista de produtos. A
funo pode retornar no fluxo de coleta o cdigo de coleta 64579 para fornecer a lista de
medicamentos, e o cdigo de coleta 64580 para obter a lista de medicamentos. Essa funo
suporta a bandeira PharmaSystem.
Prottipo
LONG EXPORT ScopeCancelaPreAutMedicamento()
Parmetros
[in]
BYTE
_TipoConvenio
[in]
BYTE
_CodRede
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFFFF
0xFF5E
65290
65535
65374
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
Erro genrico
105
Exemplo
...
BYTE
...
// abre sesso
...
...
retorno = ScopeCancelaPreAutMedicamento (TipoConvenio, CodigoRede);
...
...
// fecha a sesso
...
106
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

Cdigos Retorno
Hexadeci Decimal
mal
0x000E
14
0x001F
31
0x00CA
202
0x00CB
0x00CD
203
205
Significado
PIN-Pad j foi aberto
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.
Memria no alocada para a estrutura do PIN-Pad
compartilhado
Erro alocando memria
PIN-Pad j aberto via SCOPE
Exemplo
...
WORD porta = 1;
LONG retorno = 0;
...
107
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
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x00D3
211
Significado
PIN-Pad no foi aberto pela aplicao
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.
108
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x00D1
209
0x00D2
210
0x00D3
211
Significado
PIN-Pad no configurado
Display no permitido neste momento ou situao
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
Prottipo
LONG EXPORT ScopePPDisplayEx (char* Msg)
Parmetros
[in]
String
Msg String ASCII de caracteres com o formato abaixo.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x00D1
209
0x00D2
210
0x00D3
211
Significado
Exemplo
...
109
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
Descrio
Nome do fabricante do PIN-Pad
Modelo / verso do hardware, no formato "xxx...xxx;mmm", onde "xxxx"
021-040
A20
o Nome do equipamento e "mmm" a capacidade de memria ("512KB",

"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)
110
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

Cdigos Retorno
Hexadeci Decimal
mal
0x00CA
202
0x00D1
0x00D2
0x00D3
209
210
211
Significado
compartilhado
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]);
}
...
111
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
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

Cdigos Retorno
Hexadeci Decimal
mal
0x000A
10
0x000F
15
0x00D3
211
Significado
Necessria operao previa
PIN-Pad no foi aberto
Obtendo a tecla
Aps ter posto o PIN-Pad em modo de captura de tecla, a funo ScopePPStartGetKey() dever
ser chamada continuamente at que o retorno dela seja diferente de 1 (PIN-Pad em
processamento). Esta funo finaliza o processo iniciado por ScopePPStartGetKey(). Enquanto o
retorno for igual a 1, o processo pode ser cancelado pelo checkout atravs da funo
ScopePPAbort().
Prottipo
LONG EXPORT ScopePPGetKey (void)
Parmetros
No h parmetro.
Retorno
0
Pressionada tecla de confirmao (OK ou ENTER)
4
Pressionada tecla de funo #1.
5
6
7
8
Pressionada tecla de limpeza (backspace).
13
Pressionada tecla de cancelamento.
Para os valores de retorno, veja a tabela de cdigo de retorno.
Exemplo
...
LONG retorno = 0;
112
...
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;
case 4: printf("\nPressionada a tecla de funcao 1\n"); break;
case 8: printf("\nPressionada a tecla <Limpa>\n"); break;
case 13: printf("\nPressionada a tecla <Cancela>\n"); break;
default: printf("\nERRO: = %d\n", retorno); break;
}
}
...
Obtendo a senha aberta

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

A funo ScopePPStartGetPIN() responsvel pelo incio do processo, o qual complementado
pela funo ScopePPGetPIN().
Prottipo
LONG EXPORT ScopePPStartGetPIN (char *MsgDisplay)
113
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

Cdigos Retorno
Hexadeci Decimal
mal
0x00CE
206
0x000F
15
Significado
No foi possvel definir a Master Key a ser utilizada
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)
Parmetros
[out] String
PIN
Senha capturada do usurio (j descriptografada), finalizada com

caractere nulo ('\0').
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x00D0
208
Significado
Erro no parmetro da funo GetPIN
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
114
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
[in]
String
pan
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
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

Cdigos Retorno
Hexadeci Decimal
mal
0x0002
2
0x000A
10
0x000F
15
0x0010
16
0x00CE
206
0x00D3
211
Significado
Notificar o operador com a mensagem recebida do PIN-Pad
Erro interno de execuo
115
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.
String PIN
Para senhas criptografadas com o algoritmo DUKPT, PIN dever ter 36
bytes.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x00D0
208
0x00D3
211
Significado
Exemplo
...
char pin[40];
LONG retorno = 0;
...
if (ScopePPStartGetPINEx("DIGITE A SENHA", 0, 0, NULL, NULL) == 0)
{
printf("\nAguardando digitao da senha...");
do
{
retorno = ScopePPGetPINEx(pin);
if (retorno == 0)
// se OK
printf("\nA senha digitada [%s]\n", pin);

}
...
116
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().
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

Cdigos Retorno
Hexadeci Decimal
mal
0x00D3
211
Significado
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
003-004
N2
N2
"00" Magntico
"01" - Moedeiro VisaCash sobre TIBC v1
"02" - Moedeiro VisaCash sobre TIBC v3
"03" EMV
"04" - Easy-Entry sobre TIBC v1
Tamanho da trilha 1
117
Trilha 1 (sem as sentinelas e com o byte de formato - primeiro caractere
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
alfanumrico), alinhada esquerda com espaos direita.
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
String MsgNotify
"checkout" caso a funo retorne PP_NOTIFY.
WORD Len
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

Cdigos Retorno
Hexadeci Decimal
mal
0x0002
2
0x000B
11
0x00D3
211
Significado
Parmetro invlido
Exemplo
...
char cartao [256];
char mensagem [256];
LONG retorno = 0;
...
if (ScopePPStartGetCard(99, "000") == 0)
{
printf("\nAguardando inserir ou passar o cartao...");
do
{
retorno = ScopePPGetCard(0, mensagem, sizeof(cartao), cartao);
if (retorno == 2)
printf("\nMensagem do PIN-Pad\n[%s]\n", mensagem);
if (retorno == 0)
// se OK
118
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

Cdigos Retorno
Hexadeci Decimal
mal
0x00D3
211
Significado
Exemplo
...
char cartao [256];
LONG retorno = 0;
...
if (ScopePPStartGetCard(99, "000") == 0)
{
do
{
if (retorno == 2)
if (_kbhit())
{
// se operador pressionou tecla do teclado
// cancela o processamento do cartao

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

}
...
Mensagens de erro (ScopePPMsgErro)

Esta funo retorna a descrio referente ao cdigo de erro informado retornado pelas funes de
acesso ao PIN-Pad.
Prottipo
LONG EXPORT ScopePPMsgErro (LONG RC, char *MsgErro)
Parmetros
[in]
[in]
WORD RC
Cdigo do erro.
String MsgErro Mensagem referente ao cdigo de erro informado.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x00D3
211
Significado
Exemplo
...
char cartao [256];
LONG retorno ;
...
retorno = ScopePPStartGetCard(99, "000");
if (retorno == 0)
{
do
{
if (retorno == 2)
if (_kbhit())
{
// se operador pressionou tecla do teclado
// cancela o processamento do cartao

ScopePPAbort();
retorno = 13;
}
120
} while (retorno == 1 || retorno == 2); // enquanto em processamento

// ou mensagem
}
...
if (retorno == 0)
// se OK

else
{
ScopePPMsgErro (retorno, mensagem);
printf("\n[%s]\n", mensagem);
}
...
Obtendo a comanda de um carto

A leitura de um carto do tipo comanda se d com o uso de funes no-blocantes:
ScopePPStartObtemComanda() e, para o tipo comanda caf, ScopePPObtemComanda().
Iniciando o modo de leitura da comanda

ScopePPStartObtemComanda () a funo que inicia o processo de leitura do carto, inicializa o
timer a ser utilizado para verificao de time out, e direciona para a funo que trata aquele
determinado tipo de comanda.
Prottipo
LONG EXPORT ScopePPStartObtemComanda (int
TipoComanda)
Parmetros
[in]
TipoComanda
int
Tipo de comanda (Atualmente existe

apenas o tipo Comanda Caf)
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x000A
10
0x000F
15
0x00CA
202
0x00D3
211
Significado
compartilhado
121
Lendo a comanda
A
funo
ScopePPObtemComanda()
finaliza
processo
iniciado
por
ScopePPStartObtemComanda(). chamada caso o tipo seja comanda caf, onde o carto tem
chip. Ela deve ser chamada constantemente enquanto retornar valor igual a 1 (PIN-Pad em
processamento). Em caso de sucesso, esta funo retorna o valor 0. Neste caso, a comanda ser
salva na rea de memria passada como parmetro. Existe a opo de permanecer com o carto
no PIN-Pad, proporcionando a limpeza do carto logo depois da leitura, sem necessidade de
chamada separada dessa funo. Para essa opo, deve ser passado o valor 0 no parmetro
RemoveComanda.
Prottipo
LONG
EXPORT
ScopePPObtemComanda(int
TipoComanda,
char
*Comanda,
int
RemoveComanda);
Parmetros
[in]
int
[in]
char
[in]
int
Tipo de comanda (Atualmente existe apenas o tipo

Comanda Caf)
*Comanda
Buffer onde ser salva a comanda lida nessa operao
Opo de remover a comanda posteriormente leitura
RemoveComanda (1), ou permanecer com o carto para posterior limpeza
(0).
TipoComanda
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x000D
13
0x0021
33
0x00D3
211
0x00D4
212
0x00D6
214
0X00D7
215
Significado
Operao cancelada
Mensagem recebida do PIN-Pad possui formato invlido.
Time-out do cliente / usurio
Comanda Vazia
Comanda Invlida
Exemplo
...
char szComanda[4096+1];
LONG Retorno;
...
Retorno = ScopePPStartObtemComanda (comanda_cafe);
if (Retorno == 0)
{
printf("\nCOMANDA: INSIRA O CARTAO\n");
}
122
do
{
memset(szComanda, 0x00, sizeof(szComanda));
Retorno = ScopePPObtemComanda(comanda_cafe, szComanda, 1);
}
while (Retorno == 1);
...
Limpando a comanda de um carto

A limpeza de um carto do tipo comanda se d com o uso de funes no-blocantes:
ScopePPStartLimpaComanda () e, para o tipo comanda caf, ScopePPLimpaComanda ().
Iniciando o modo de limpeza da comanda

ScopePPStartLimpaComanda() a funo que inicia o processo de limpeza do carto, inicializa o
timer a ser utilizado para verificao de time out, e direciona para a funo que trata aquele
determinado tipo de comanda.
Prottipo
LONG EXPORT ScopePPStartLimpaComanda (int
TipoComanda)
Parmetros
[in]
TipoComanda
int
Tipo de comanda (Atualmente existe

apenas o tipo Comanda Caf)
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x00D3
211
0X00D7
215
Significado
Comanda Invlida
Limpando a comanda
A
funo
ScopePPLimpaComanda()
finaliza
processo
iniciado
por
ScopePPStartLimpaComanda(). chamada caso o tipo seja comanda caf, onde o carto tem
chip. Ela deve ser chamada constantemente enquanto retornar valor igual a 1 (PIN-Pad em
processamento). Em caso de sucesso, esta funo retorna o valor 0.
Prottipo
LONG EXPORT ScopePPLimpaComanda(int
TipoComanda);
123
Parmetros
[in]
int
TipoComanda
Tipo de comanda (Atualmente existe apenas o tipo

Comanda Caf)
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0x000D
13
0x0021
33
0x00D3
211
0x00D4
212
0x00D6
214
0X00D7
215
Significado
Operao cancelada
Comanda Vazia
Comanda Invlida
Exemplo
...
LONG Retorno;
...
Retorno = ScopePPStartLimpaComanda (comanda_cafe);
if (Retorno == 0)
{
printf("\nCOMANDA: INSIRA O CARTAO\n");
}
do
{
Retorno = ScopePPLimpaComanda(comanda_cafe);
}
while (Retorno == 1);
...
124
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.
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 consequentemente,
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
inicializao
Ao
dos
totalizadores
0xFB07
Erro na totalizao de TEF, causado por
verifique o valor do parmetro

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

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

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

errado.
Exemplo
...
// carrega configurao do PDV de um novo dia
...
// conecta ao SCOPE Server
...
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
ELETRONIC
DE
BANDEIRA
CARTAO
----
EFETUADO
CANCELADO
1650.00
0.00
18.00
4.00
ELECTRON
------
DEBITO
DE
DEBITO
EFETUADO
(CDC)
----
CANCELADO
126
------
CONSULTA
BANDEIRA
CHEQUE
----
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
Retorno

Cdigos Retorno
Significado
Hexadeci Decimal
mal
0xFE00
65024
0xFB07 0xFB07
64263 64263
Erro na totalizao de TEF
Exemplo
...
WORD TamCupom;
char Cupom[2048];
...
// encerrando o Dia
...
TamCupom = sizeof(Cupom);
if(ScopeObtemTotalTEF(0, Cupom, TamCupom, \n) == 0)
{
...
EnviaCupomParaImpressora(Cupom);
...
}
else
127
{
// 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. H 3 tipos de layouts conforme as tabelas abaixo:
Layout Verso 1:
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)
Layout Verso 2:
Tamanho
Descrio
3 bytes
3 bytes
Quantidade de bandeiras retornadas que indica a quantidade de repeties dos

registros abaixo
3 bytes
Cdigo da bandeira
17 bytes
Descrio da bandeira
1 byte
Quantidade de Funes retornadas que indica a quantidade de repeties dos

registros abaixo (29 bytes por funo)
1 byte
14
Identifica a funo:
- C: Crdito
- D: Dbito;
- H: Cheque
- A: CDC
- S: Saque
128
bytes
14
bytes
Layout Verso 3:
Tamanho
Descrio
3 bytes
3 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
3 bytes
Cdigo da bandeira
17 bytes
Descrio da bandeira
14 bytes
14 bytes
Prottipo
LONG ScopeObtemDadosTotalTEF (BYTE Nivel, char *Buffer, WORD TamBuffer)
Parmetros
[in]
BYTE
Nivel
[out] char *
Buffer
[in]
TamBuffer
WORD

Operador)
Retorna os dados de totais TEF
alocou pela varivel Buffer
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFE00
65024
0xFB07
64263
Significado
Exemplo
...
WORD TamBuffer;
char Buffer[2048];
...
// encerrando o Dia
129
...
TamBuffer = sizeof(Buffer);
if(ScopeObtemDadosTotalTEF(0, Buffer, TamBuffer) == 0)
{
...
GeraRelatorioEmArquivo(Buffer);
...
}
else
{
}
...
CUIDADO: Esta funo somente aceita o layout Verso 1.
Prottipo
LONG ScopeObtemDadosTotalTEFEx (BYTE Versao, BYTE Nivel, char *Buffer,
WORD TamBuffer)
Parmetros
[in]
BYTE
Versao
[in]
BYTE
Nivel
[out] char *
Buffer
[in]
TamBuffer
WORD
Verso do layout a ser utilizado: 1, 2 ou

3
Operador)
Retorna os dados de totais TEF
alocou pela varivel Buffer
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFE00
65024
0xFB07
64263
Significado
Exemplo
...
WORD TamBuffer;
char Buffer[2048];
...
// encerrando o Dia
...
TamBuffer = sizeof(Buffer);
if(ScopeObtemDadosTotalTEFEx(3, 0, Buffer, TamBuffer) == 0)
130
{
...
GeraRelatorioEmArquivo(Buffer);
...
}
else
{
}
...
131
Transao de POS para conciliao

Aqui ser tratada uma funcionalidade que guia a coleta de dados de um cupom de TEF.
Descrio da funcionalidade
Essa funcionalidade determina um fluxo de coleta que direcione o operador (a automao
comercial) a entrar os dados do cupom de uma transao que foi realizada na mquina de POS.
Este recurso foi criado para que a automao cormercial obtivesse os dados do cupom para
gravar no arquivo de conciliao do SCOPECON e que tais transaes fossem conciliadas. Essa
funcionalidade no se comunica com o SCOPE Server e a conexo pode estar offline. No entanto,
necessrio que o SCOPE Client tenha feito o logon com o Server, isto , que a funo
ScopeOpen tenha sido executado com sucesso.
A funcionalidade tinha como foco cartes que o SCOPE s passam em POS, como o
CONSTRUCARD e o BNDES. No entanto, quaisquer cartes que passaram pelo POS podem
usar esse recurso. H situaes em que a rede autorizadora ou at mesmo o prprio SCOPE
Server est offline. Quando acontece isso, normalmente os estabelecimentos passam as
transaes em POS, que so utilizados como contingncia do concentrador de TEF.
Em linhas gerais, o portador do carto ao pagar sua compra na loja com um dos cartes, o
funcionrio da loja encaminha-o para o sistema que vai fazer o pagamento. Uma vez paga, o
funcionrio poder registrar essa venda no PDV para a futura conciliao com a rede
autorizadora.
Os dados da transao sero retornados para a automao comercial pela funo
ScopeObtemCampoExt2. Assim, esses dados podero ser gravados em arquivo e exportados
posteriormente para o mdulo SCOPECon. Em outras palavras, os dados da transao para a
conciliao no feita pelo SCOPE. de responsabilidade da automao comercial a gerao do
arquivo com os dados da transao. A participao do SCOPE nesse processo est em dois
momentos:
1.
A coleta dos dados do cupom pelo SCOPE Client para que a automao tenha os dados
para o arquivo. Nessa situao o SCOPE serve apenas como um guia ao operador para
solicitar as informaes do cupom. No final da coleta, a automao solicitar ao SCOPE
Client tais dados para o arquivo.
2.
A conciliao da transao pelo SCOPECon. O arquivo gerado pela automao comercial

ser importado por esse mdulo.
Transao POS
Essa funo inicia um fluxo padro de coleta do SCOPE para coletar as informaes necessrias
para que a automao comercial gere um registro do arquivo de conciliao que este seja
132
futuramente importado pelo SCOPECon. No final desse fluxo a automao comercial poder obter
quase todos os campos necessrio utilizando a funo ScopeObtemCampoExt2.
Na loja, o operador de caixa ir com o portador do carto a um POS passar o carto para pagar a
venda. O operador retornar ao caixa com o cupom do estabelecimento impresso pelo POS e
executar essa transao. Os dados contidos na via do estabelecimento so importantes para
alimentar os dados da transao. A no utilizao do SCOPE poder ser por diversas situaes.
A principal quando o carto CONSTRUCARD ou BNDES, pois eles no so tratados pelo
SCOPE. Outra situao quando a rede autorizadora ou o prprio SCOPE Server estiver offline.
Nesse caso, a transao ser paga no POS, mas o estabelecimento poder fazer a conciliao da
transao.
Os parmetros da funo no so obrigatrios. Passar valores diferentes do padro simplificar o
fluxo de coleta, no sendo solicitado ao operador. Se esta funo vai ser chamada para finalizar a
venda que est aberta, a automao poder passar o valor da venda automaticamente.
IMPORTANTE: Essa transao no exige abertura de sesso. Tambm ela no tem

garantia de queda de energia, ou seja, no caso de interrupo da transao, os dados
coletados sero perdidos. Se aberta a sesso de TEF, ela no considerada no limite de 9
TEFs permitidos na sesso.
Prottipo
LONG EXPORT ScopeTransacaoPOS(char
WORD
WORD
WORD
*Valor,
Rede,
Bandeira,
Servico)
Parmetros
[in]
String com o
mximo de 12
dgitos
Valor
[in]
WORD
Rede
[in]
WORD
Bandeira
[in]
WORD
Servico

(exemplo: R$ 123,00 = 12300). Passar
string vazia para o SCOPE solicitar. No
pode ser nulo nem string apenas com
zeros.
Nmero positivo que representa cdigo da
rede autorizadora segundo o SCOPE.
Passar zero para o SCOPE solicitar.
Nmero positivo que representa cdigo da
bandeira segundo o SCOPE. Passar zero
para o SCOPE solicitar.
Nmero positivo que representa cdigo do
servio segundo o SCOPE. Passar zero
para o SCOPE solicitar.
Retorno
Ver tabela de cdigo de retorno no SCOPE.

133
Cdigos Retorno
Hexadeci Decimal
mal
0xFB01
64257
0xFB09
64265
0xFE00
65024
Significado
Exemplo
...
retorno = ScopeTransacaoPOS(, 0, 0, 0);
...
...
Estados de coleta
A tabela abaixo mostra os estados de coleta que o fluxo poder retornar, no modo coleta. A
maioria dos estados no necessitam tratamentos especficos pela automao. Basta que
mostre a mensagem na tela do operador e aguarde a digitao. Quando necessrio, est
descrito abaixo o tratamento especfico que a automao poder fazer.
ESTADO DE COLETA
HEX
0xFC87
DESCRIO
DECIMAL
64647
TRATAMENTO
Exibe menu.
Obter a lista de opes do menu para a
Para essa transao, esse estado
exibio de todas numa nica vez. Ver
poder ser utilizado para coletar dois
tpico especfico.
dados diferentes. Um para a coleta da

rede. Outro para a coleta da bandeira.
0xFC09
64521
Coletar se a transao a vista ou

no
Coletar se a transao parcelada
0xFC0A
64522
Padro
pela
administradora
ou
Padro
pelo
estabelecimento
0xFC0E
64526
Coleta a quantidade de parcelas
Padro
0xFC34
64564
Coleta o valor da transao
Padro
0xFCC7
64711
Coleta os 6 primeiros dgitos do carto
Padro
0xFC18
64536
Coleta os 4 ltimos dgitos do carto
Padro
0xFC32
64562
Coleta a data da transao no formato
Padro
0xFCC8
64712
Coleta o campo DOC (NSU)
Padro
0xFC3A
64570
Coleta o campo CV (NSU do host)
Padro
DDMMAA
134
0xFCC9
64713
0xFCFD
64765
0xFCFE
Coleta o campo AUT (cdigo de
Padro
autorizao)
Coleta em andamento
Aguarda a troca de estado. No solicita

dados ao operador.
64766
Mostrar informaes e retornar fluxo
Mostrar a mensagem para o operador e
para o cliente SCOPE
devolver o controle para o SCOPE. No

solicita dados ao operador.
Constantes em C dos estados de coleta

Esta tabela mostra as constantes definidas no arquivo de cabealho ScopeApi.h. Esse
arquivo disponibilizado junto com o SCOPE Client. Muito til para automaes escritas em
linguagem C.
CONSTANTE
CDIGO EM HEXA
TC_DECIDE_AVISTA
0xFC09
TC_DECIDE_P_ADM_EST
0xFC0A
TC_QTDE_PARCELAS
0xFC0E
TC_ULTIMOS_DIGITOS
0xFC18
TC_COLETA_DDMMAA
0xFC32
TC_COLETA_VALOR
0xFC34
TC_COLETA_NSU_HOST
0xFC3A
TC_EXIBE_MENU
0xFC87
TC_PRIMEIROS_DIGITOS
0xFCC7
TC_COLETA_CAMPO_AUT
0xFCC8
TC_COLETA_CAMPO_DOC
0xFCC9
TC_COLETA_EM_ANDAMENTO
0xFCFD
TC_INFO_RET_FLUXO
0xFCFE
Redes e bandeiras
O SCOPE Client tem um conjunto mnimo padro implementado internamente para permitir a
transao POS. So garantidas as redes CIELO e REDECARD-L0500, cujos respectivos cdigos
no SCOPE so 102 e 103. As bandeiras garantidas so VISA, MASTERCARD, ELECTRON, ELO
DEBITO, ELO CREDITO, BNDES, CONSTRUCARD. Os servios so: Dbito Vista, Crdito
Vista, Crdito Parc. Adm, Crdito Parc. Loja, Compra CDC e Credirio. A tabela abaixo mostra o
relacionamento que o SCOPE Client mantm internamente.
CD
102
102
REDE
NOME
CIELO
CIELO
CD
1
1
BANDEIRA
NOME
VISA
VISA
CD
9
27
SERVIO
NOME
Crdito Vista
Crdito Parc. Adm
135
102
102
102
102
102
102
102
102
102
102
102
102
103
103
103
103
103
103
103
103
103
103
103
103
CIELO
1 VISA
28 Crdito Parc. Loja
CIELO
2 MASTERCARD
9 Crdito Vista
CIELO
2 MASTERCARD
27 Crdito Parc. Adm
CIELO
2 MASTERCARD
CIELO
8 MAESTRO
6 Dbito Vista
CIELO
8 MAESTRO
134 Credirio
CIELO
21 ELECTRON
6 Dbito Vista
CIELO
21 ELECTRON
134 Credirio
CIELO
247 BNDES
6 Dbito Vista
CIELO
247 BNDES
134 Credirio
CIELO
246 CONSTRUCARD
6 Dbito Vista
CIELO
246 CONSTRUCARD
134 Credirio
REDECARD-L0500
1 VISA
9 Crdito Vista
REDECARD-L0500
1 VISA
27 Crdito Parc. Adm
REDECARD-L0500
1 VISA
REDECARD-L0500
2 MASTERCARD
9 Crdito Vista
REDECARD-L0500
2 MASTERCARD
27 Crdito Parc. Adm
REDECARD-L0500
2 MASTERCARD
REDECARD-L0500
8 MAESTRO
6 Dbito Vista
REDECARD-L0500
8 MAESTRO
45 Compra CDC
REDECARD-L0500
21 ELECTRON
6 Dbito Vista
REDECARD-L0500
21 ELECTRON
45 Compra CDC
REDECARD-L0500
246 CONSTRUCARD
6 Dbito Vista
REDECARD-L0500
246 CONSTRUCARD
45 Compra CDC
Este relacionamento interno poder ser desconsiderado se configurado no scope.ini um novo
relacionamento. Ver tpico Configurao do arquivo scope.ini.
Exemplos de configurao 1
Esse exemplo mostra uma configurao em que a transao teria um comportamento
similar como situao em que o arquivo no est configurado. O comportamento similar,
mas no igual, pois no temos a associao de servio para cada configurao de rede ou
bandeira. Logo, no fluxo as bandeiras no sero separadas conforme a opo escolhida de
crdito, dbito ou CDC (credirio) e todas elas aparecero para que o operador escolha
uma.
[SCOPEAPIPOS]
DigitacaoCodigo=n
Complementar=n
Redes=102,103
Bandeiras=1,2,8,21,246,247
NomeBandeira001=VISA
NomeBandeira002=MASTERCARD
NomeBandeira008=MAESTRO
NomeBandeira021=ELECTRON
NomeBandeira246=BNDES
NomeBandeira247=CONSTRUCARD
[SCOPEAPIPOS-R102]
Nome=CIELO
136
Bandeiras=1,2,8,21,247,246
[SCOPEAPIPOS-R103]
Nome= REDECARD
Bandeiras=1,2,8,21, 246
Aqui temos uma configurao para um estabelecimento que tem apenas POS da CIELO
como contingncia. No ser perguntada pela rede REDECARD.
[SCOPEAPIPOS]
DigitacaoCodigo=n
Complementar=n
Redes=102
Bandeiras=1,2,8,21,246,247
[SCOPEAPIPOS-R102]
Nome=CIELO
Bandeiras=1,2,8,21,247,246
A configurao desse exemplo agrega rede GETNET e as bandeiras SIMCRED e VISA
para um estabelecimento que tem um POS da GETNET como contingncia alm do POS
da CIELO e da REDECARD.
[SCOPEAPIPOS]
DigitacaoCodigo=n
Complementar=s
Redes=73
Bandeiras=136
NomeBandeira136=SIMCRED
[SCOPEAPIPOS-R073]
Nome=GETNET
Bandeiras=136,1
Com essa configurao ser dada a opo OUTRA e coletado o cdigo de bandeira se
essa opo for selecionada.
[SCOPEAPIPOS]
DigitacaoCodigo=s
137
A configurao desse exemplo agrega rede GETNET e as bandeiras SIMCRED e VISA e
ELECTRON para um estabelecimento que tem um POS da GETNET como contingncia
alm do POS da CIELO e da REDECARD. Alm disso, associa os servios de crdito para
SIMCRED e VISA e o servio de dbito para ELECTRON.
[SCOPEAPIPOS]
DigitacaoCodigo=n
Complementar=s
Redes=73
Bandeiras=136
NomeBandeira136=SIMCRED
[SCOPEAPIPOS-R073]
Nome=GETNET
Bandeiras=136,1,21
ServicoB001=9,027,28
ServicoB136=009,27,028
ServicoB021=6
Esse exemplo mostra uma configurao em que a transao teria um comportamento igual
situao em que o arquivo no est configurado. Diferente do exemplo 1, aqui o
comportamento igual, pois temos a associao de servio para cada configurao de rede
ou bandeira.
[SCOPEAPIPOS]
DigitacaoCodigo=n
Complementar=n
Redes=102,103
Bandeiras=1,2,8,21,246,247
[SCOPEAPIPOS-R102]
Nome=CIELO
Bandeiras=1,2,8,21,247,246
ServicoB001=009,27,28
ServicoB002=9,27,28
ServicoB008=6,134
ServicoB021=6,134
ServicoB247=6,134
ServicoB246=6,134
[SCOPEAPIPOS-R103]
Nome= REDECARD
138
Bandeiras=1,2,8,21, 246
ServicoB008=6,45
ServicoB021=6,45
ServicoB246=6,45
Cdigos de servios
No SCOPE existem vrios cdigos de servios disponveis, mas nem todos so aplicveis nesta
funcionalidade. Cada servio agrupado em um grupo de servio. Abaixo est a relao de
grupos de servios e os servios previstos como no SCOPE.
Grupo de servio
Cdigo
Descrio
01
Carto de Dbito
02
Carto de Crdito
Cdigo
6
45
134
9
27
28
Servio
Descrio
Dbito Vista
Compra CDC
Credirio
Crdito Vista
Crdito Parc. Adm
Crdito Parc. Loja
Percebe-se que o CDC e o Credirio esto agrupados em dbito, mas para fins da transao
POS, os servios estaro agrupados nos conforme abaixo:
Grupo de servio
Descrio
Carto de Dbito
CDC
Carto de Crdito
Servio
Cdigo
Descrio
6
Dbito Vista
45
Compra CDC
134
Credirio
45
Compra CDC
134
Credirio
9
Crdito Vista
27
Crdito Parc. Adm
28
Crdito Parc. Loja
O servio 134 (credirio) idntico ao CDC, mas utilizado apenas para a rede CIELO. Qualquer
outra rede o servio utilizado deve ser o 45 (compra CDC). Esses dois servios esto em ambos
os grupos, para manter como o agrupamento no SCOPE. No entanto, escolhendo a opo de
CDC logo no comeo, simplifica o fluxo, j que no perguntar se vista e perguntar o nmero
de parcelas. Consequentemente, o fluxo poder chegar ao servio CDC, respondendo tanto
dbito, quanto CDC na primeira coleta.
139
Figura 8: cupom da CIELO
Cupom CIELO X ScopeObtemCampoExt2 X arquivo

Nesse tpico so mapeados os campos de cupons da rede CIELO com as constantes da funo
ScopeObtemCampoExt2 do SCOPE Client e os campos do registro do arquivo de conciliao.
Na transao POS o cupom utilizado dever ser a via do estabelecimento.
Seguindo o exemplo do cupom de uma transao da CIELO da Figura 8, os campos sero
mapeados da forma conforme abaixo.
ARQUIVO CONCILIAO
DESCRIO
Tipo de registro
POS
1
TAM TIPO
COMENTRIOS
1
N
Constante 1
Numero do PV
15
Data da venda
17
NSU
25
NSU do Host
31
15
Cdigo de
autorizao
41
14
Valor da
compra
Nmero do
carto
51
15(2)
Valor da operao
66
22
Nmero do carto
Status da
transao
85
Cdigo
Empresa
86
Cdigo do
Estabelecimento
Data da venda
(YYYYMMDD)
Num. seqencial
nico
NSU complementar
Cdigo de
autorizao
FUNO ScopeObtemCampoExt2
CUPOM
MSCARA 1
NA*
MSCARA 2
NA*
MSCARA 3
NA*
CAMPO
0x00000800
NA*
NA*
NA*
NA*
0x00000008
NA*
Data
0x00000004
NA*
NA*
DOC
0x00004000
NA*
NA*
NA*
0x00000100
NA*
NA*
0x00000002
NA*
NA*
0x00000001
NA*
NA*
NA*
NA*
NA*
NA*
0x08000000
NA*
NA*
AUT
Transaes OK,
preencher com a
letra O
Formato 0000
VALOR
6 primeiros e 4
ltimos dgitos do
carto
NA*
NA*
140
Cdigo Filial
90
Qtd Parcelas
94
Forma Captura
96
97
Formato 0000
NA*
Quantidade de
parcelas. Se venda
for vista,
preencher 00
P-POS, IInternet, MManual, T-TEF ou
O Outros.
NA*
NA*
NA*
0x00001000
NA*
NA*
NA*
NA*
0x00000080
0x00040000
NA*
NA*
Nmero de
parcelas
NA*
Cdigo
Bandeira
Cdigo Rede
100
Cdigo da Rede
0x00400000
NA*
NA*
Rede
Cdigo Servio
103
0x00080000
NA*
NA*
RESERVADO
108
89
Cdigo do Servio
RESERVADO
NA*
NA*
NA*
Venda
NA*
Cdigo da Bandeira
Bandeira
* NA no se aplica
Para ilustrar o mapeamento, considera-se o cdigo da empresa e o cdigo da filial do PDV sendo
0001 e 0001, respectivamente, e o cupom de exemplo. Aps a transao POS do SCOPE
Client e a formatao da automao comercial, o cupom dever resultar no registro com exibido
na prxima tabela.
CUPOM
CAMPO
ARQUIVO
MSCARA 1
-
MSCARA 2
-
MSCARA 3
-
0x00000800
0x00000000
0x00000000 "
041212
0x00000000
0x00000008
0x00000000 "041212"
"20121204"
096044
0x00000004
0x00000000
0x00000000 "096044"
"096044"
0x00004000
0x00000000
0x00000000 ""
"
095023
0x00000100
0x00000000
0x00000000 "095023"
"095023
1000
0x00000002
0x00000000
0x00000000 "1000"
"000000000001000"
444054-2871
0x00000001
0x00000000
0x00000000 "444054-2871"
"444054-2871
REGISTRO
"1"
"
"
"
"
0x00000000
0x08000000
0x00001000
0x00000000
0x00000000 "2"
"02"
0x00000000
0x00000000
0x00000080 "P"
"P"
ELECTRON
0x00040000
0x00000000
0x00000000 "21"
"021"
CIELO
0x00400000
0x00000000
0x00000000 "102"
"102"
Dbito
parcelado
0x00080000
0x00000000
0x00000000 "134"
"134"
RETORNO
0x00000000 "0001"
-
"
"
"O"
"0001"
"0001"
...
Cupom REDECARD X ScopeObtemCampoExt2 X arquivo

Como no tpico anterior, nesse so mapeados os campos de cupons da rede REDECARD com
as constantes da funo ScopeObtemCampoExt2 do SCOPE Client e os campos do registro do
arquivo de conciliao. Na transao POS o cupom utilizado dever ser a via do estabelecimento.
141
Figura 9: cupom da rede REDECARD

Seguindo o exemplo do cupom de uma transao da REDECARD da Figura 9, os campos sero
mapeados da forma conforme tabela.
ARQUIVO CONCILIAO
DESCRIO
Tipo de registro
POS
1
TAM TIPO
COMENTRIOS
1
N
Constante 1
Cdigo do
15
N
Estabelecimento
Data da venda
8
D
(YYYYMMDD)
Num. seqencial
6
A
nico
15
A
NSU complementar
Numero do PV
Data da venda
17
NSU
25
NSU do Host
31
Cdigo de
autorizao
41
14
Valor da
compra
51
15(2)
Nmero do
carto
66
Status da
transao
CUPOM
MSCARA 1
NA*
MSCARA 2
NA*
MSCARA 3
NA*
NA*
0x00000800
NA*
NA*
NA*
NA*
0x00000008
NA*
Data
0x00000004
NA*
NA*
NA*
0x00004000
NA*
NA*
CV
Cdigo de
autorizao
0x00000100
NA*
NA*
AUTO
Valor da operao
0x00000002
NA*
NA*
22
Nmero do carto
0x00000001
NA*
NA*
TOT.
APROVADO
6 primeiros
opcionais e 4
ltimos
obrigatrios
dgitos do carto
85
Transaes OK,
preencher com a
letra O
NA*
NA*
NA*
NA*
Cdigo
Empresa
86
Formato 0000
NA*
0x08000000
NA*
NA*
Cdigo Filial
90
Formato 0000
NA*
NA*
NA*
NA*
0x00001000
NA*
NA*
Nmero de
parcelas
NA*
NA*
Qtd Parcelas
94
Forma Captura
96
Quantidade de
parcelas. Se venda
for vista,
preencher 00
O Outros.
CAMPO
0x00000080 NA*
142
Cdigo
Bandeira
Cdigo Rede
97
Cdigo da Bandeira
0x00040000
NA*
NA*
Bandeira
100
Cdigo da Rede
0x00400000
NA*
NA*
Rede
Cdigo Servio
103
Cdigo do Servio
0x00080000
NA*
NA*
Venda
RESERVADO
108
* NA no se aplica
89
RESERVADO
NA*
NA*
NA*
NA*
Para ilustrar o mapeamento, considera-se o cdigo da empresa e o cdigo da filial do PDV sendo
0001 e 0001, respectivamente, e o cupom de exemplo. Aps a transao POS do SCOPE
Client e a formatao da automao comercial, o cupom dever resultar no registro com exibido
nessa tabela.
CUPOM
CAMPO
ARQUIVO
MSCARA 1
-
MSCARA 2
-
MSCARA 3
-
RETORNO
REGISTRO
0x00000800
0x00000000
0x00000000 "000000000000000"
"000000000000000"
121212
0x00000000
0x00000008
0x00000000 "121212"
"20121212"
0x00000004
0x00000000
0x00000000 "096044"
"096044"
499931944
0x00004000
0x00000000
0x00000000 "499931944"
"499931944
018833
0x00000100
0x00000000
0x00000000 "018833"
"018833
1330
0x00000002
0x00000000
0x00000000 "1330"
"000000000001330"
8096
0x00000000 "000000-8096"
"000000-8096
"1"
0x00000001
0x00000000
0x00000000
0x08000000
0x00001000
0x00000000
0x00000000 "1"
"01"
0x00000000
0x00000000
0x00000080 "P"
"P"
MAESTRO
0x00040000
0x00000000
0x00000000 "8"
"008"
REDECARD
0x00400000
0x00000000
0x00000000 "103"
"103"
Dbito vista
0x00080000
0x00000000
0x00000000 "6"
"006"
"
"0001"
"
"O"
0x00000000 "0001"
-
"
"0001"
0000...000
Outros cupons X ScopeObtemCampoExt2 X arquivo

Pela configurao do scope.ini, o SCOPE Client poder coletar dados de cupom de outras redes.
No entanto, os nomes dos campos coletados sero genricos.
ARQUIVO CONCILIAO
COMENTRIOS
MSCARA MSCARA MSCARA
1
2
3
NA*
NA*
NA*
NA*
NA*
DESCRIO
POS
TAM
TIPO
Tipo de registro
Constante 1
Numero do PV
15
0x00000800 NA*
Data da venda
17
NSU
25
NSU do Host
31
15
Cdigo do
Estabelecimento
Data da venda
(YYYYMMDD)
Num. seqencial
nico
NSU complementar
Cdigo de
autorizao
41
14
Cdigo de
autorizao
Valor da
compra
Nmero do
carto
51
15(2)
Valor da operao
0x00000002 NA*
NA*
66
22
Nmero do carto
0x00000001 NA*
NA*
NA*
NA*
0x00000008 NA*
CUPOM
CAMPO
Data
0x00000004 NA*
NA*
NA*
0x00004000 NA*
NA*
CV
0x00000100 NA*
NA*
AUTO
OBRIG.
NA*
NA*
SIM
NO
NO
NO
TOT.
APROVADO
6 primeiros
dgitos do
carto
SIM
NO
143
Status da
transao
85
Cdigo
Empresa
Cdigo Filial
86
90
NA*
NA*
4 ltimos
dgitos do
carto
NA*
NA*
Transaes OK,
preencher com a
letra O
Formato 0000
NA*
0x08000000 NA*
NA*
Formato 0000
NA*
NA*
NA*
SIM
NA*
NA*
NA*
NA*
Qtd Parcelas
94
Forma Captura
96
97
Cdigo
Bandeira
Cdigo Rede
100
Cdigo Servio
103
RESERVADO
108
89
Quantidade de
parcelas. Se venda
for vista,
preencher 00
O Outros.
0x00001000 NA*
NA*
NA*
NA*
0x00000080 NA*
NA*
NA*
Cdigo da Bandeira 0x00040000

Cdigo do Servio
RESERVADO
SIM
NA*
N
Cdigo da Rede
Nmero de
parcelas
Bandeira
SIM
0x00400000 NA*
0x00080000 NA*
NA*
Rede
SIM
NA*
NA*
Venda
NA*
SIM
NA*
NA*
NA*
Formatao para o arquivo de conciliao

Observa-se nos exemplos a automao comercial precisar tratar alguns campos, formatando-os
para gravar no arquivo de conciliao. Ser necessria a formatao nos campos:
Tipo de registro: preencher sempre com o dgito 1.
Data da transao: o SCOPE Cliente fornece a data no formato DDMMAA e a automao

alterar para o formato AAAAMMDD.
NSU do host: completar com espaos direita.
Cdigo de autorizao: completar com espaos direita.
Valor da transao: completar com zeros esquerda.
Nmero do carto: completar com espaos direita.
Status da transao: preencher sempre com a letra O.
Cdigo da filial: preencher com o cdigo da filial usado na funo ScopeOpen.
Nmero de parcelas: completar com zeros esquerda.
Cdigo da rede: completar com zeros esquerda.
Cdigo da bandeira: completar com zeros esquerda.
Reservado: preencher sempre com espaos direita.
144
Funes diversas
_____________________________________________________________________________________________________
Neste captulo, abordamos diversas funes de uso frequente 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.
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 8: este valor utilizado para a obteno de dados de uma transao aps queda de
energia.
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).

Cdigos Retorno
Hexadeci Decimal
mal
Significado
145
0xFA01
0xFB01
0xFB09
0xFE01
0xFE05
64001
64257
64265
65025
65029
0xFE0D
65037
Parmetro 1 invlido
No h arquivo com dados da transao anterior salvo
Exemplo
...
LONG handle;
handle = ScopeObtemHandle(0);
if(handle > 0xFFFF)
{
// obtm os dados desejados
}
else
{
// erro! no conseguiu o handle
}
...
// fecha a sesso
...
Obtendo os campos
Aps obter um handle vlido, a aplicao est apta para o recebimento dos dados da transao.
Estes dados podem ser obtidos de uma vez s ou campo a campo, ou at mesmo agrupados em
partes. Isto conseguido atravs de campos com combinao de bits.
Cada bit das 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 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 sequncia dos dados que sero devolvidos para a aplicao ser a partir da mscara 1, depois
para a mscara 2 e logo depois para a mscara 3 na sequncia do bit menos significativo para o
mais significativo. importante observar que a mscara 3 somente pode ser obtida atravs da
funo ScopeObtemCampoExt2(), juntamente com as mscaras 1 e 2
Prottipo
LONG EXPORT ScopeObtemCampoExt (LONG Handle,
LONG Masc1,
LONG Masc2,
146
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)
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

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFA03
64003
0xFA04
64004
0xFB09
64265
0xFE01
65025
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Parmetro 3 invlido
Parmetro 4 invlido
Exemplo
...
long h;
char aux[128];
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

147

ScopeObtemCampoExt(h, 0x00, 0x00004000, ':', aux);
ArmazenaCampo(aux);
// cdigo e nome da bandeira

ScopeObtemCampoExt(h, 0x00040000 | 0x00800000, 0x00 , ':', aux);
ArmazenaCampo(aux);
// exemplo de retorno 002:Mastercard:
}
else
{
}
...
Prottipo
LONG EXPORT ScopeObtemCampoExt2 (LONG Handle,
LONG Masc1,
LONG Masc2,
LONG Masc3,
char FieldSeparator,
char *Buffer)
Parmetros
[in]
LONG
Handle
[in]
LONG
Masc1
[in]
LONG
Masc2
[in]
LONG
Masc3
[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()
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
148
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFA02
64002
0xFA03
64003
0xFA04
64004
0xFB09
64265
0xFE01
65025
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Parmetro 3 invlido
Parmetro 4 invlido
Exemplo
...
long h;
char aux[128];
if(handle > 0xFFFF)
{
// obtendo o nsu da transao
ScopeObtemCampoExt2(h, 0x00000004, 0x00 , 0x00 ,';', aux);
ArmazenaCampo(aux);
// obtendo o cdigo da operadora de celular

ScopeObtemCampoExt2(h, 0x00, 0x00004000, 0x00 ':', aux);
ArmazenaCampo(aux);
// cdigo e nome da bandeira e dados da plataforma promocional

ScopeObtemCampoExt2(h, 0x00040000 | 0x00800000, 0x00 , 0x00000001 ':',
aux);
ArmazenaCampo(aux);
// exemplo de retorno 002:Mastercard:
}
else
{
}
...
CUIDADO: tente alocar um buffer razoavelmente grande conforme os dados que se deseja
recuperar, pois o SCOPE no alocar buffer.
149
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,
SCOPE_DADOS_LISTA_MEDICAMENTOS,
SCOPE_AUTOMACAO_PERMITE_SALDO_VOUCHER,
SCOPE_COD_TABELA_PARCELE_MAIS,
SCOPE_DADOS_PAGAMENTO_EX,
SCOPE_AUTOMACAO_PARTICIPA_PPONLINE,
SCOPE_PERMITIR_SAQUE,
SCOPE_RESULTADO_VALIDACAO,
SCOPE_DADOS_ECF_BENEFICIO,
SCOPE_NOME_PRODUTO,
SCOPE_DADOS_CARTAO_PRESENTE,
SCOPE_DADOS_LISTA_PRECOS,
SCOPE_DADOS_LISTA_MERCADORIAS,
SCOPE_DADO_MAX,
150
} tDadoForneceCampo;
Onde:
SCOPE_DADO_MIN (ID 0): limite inferior do domnio de valores que o primeiro parmetro
pode receber
SCOPE_DADO_EMPRESA (ID 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 (ID 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 (ID 3): ver Atributos da aplicao
SCOPE_DADO_TRILHA_01 (ID 4): string com a trilha 01 do carto lida no PIN-Pad
SCOPE_DADO_REG_FORMA_PAGTO (ID 5): string de no mximo 30 bytes de

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

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

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

parametrizando o separador de linha do cupom (exemplo: @). Atualmente, suporta
apenas o caractere '@', sendo que para qualquer outro caractere parametrizado, ou caso
esta parametrizao no seja efetuada, ser considerado o caractere '\n' como finalizador
de linha do cupom.
SCOPE_DADOS_APLIC (ID 9): tipo de terminal (A para ATM ou P para PDV) e usurio
SCOPE_DADOS_PAGAMENTO
(ID
10):
dados
do
pagamento
(confronte
com
SCOPE_DADOS_PAGAMENTO_EX)
SCOPE_DADOS_APLIC_CBD (ID 11): desenvolvido para a rede CBD e utilizado tambm

pela rede VR (SmartNet), sendo um string com o primeiro char informando o tipo de
terminal (numero de 1 a 5) e o restante da string representando a data de movimento no
formato MMDD, como demonstrado a seguir:
Campo
Formato
Tipo Terminal
n1
Data de Movimento
n4
Descrio
Tipos de Terminal que podem ser configurados:
1 = Frente de loja, (default)
2 = Magazine,
3 = Batimento/retaguarda
4 = Posto de gasolina
5 = WEB
Data de Movimento no formato MMDD
SCOPE_DADO_DATA_MOVIMENTO (ID 12): no mais suportado
SCOPE_DADO_NSU_CUPOM_FISCAL (ID 13): no mais suportado
151
SCOPE_DADOS_AUTOMACAO (ID 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 (ID 15): string com 13 bytes que contm

o cdigo de autorizao da PBM
SCOPE_DADOS_LISTA_MEDICAMENTOS (ID 16): buffer com a lista de medicamentos

da PBM
SCOPE_AUTOMACAO_PERMITE_SALDO_VOUCHER (ID 17): Atravs deste campo, a

automao informa ao Scope se permite que o pagamento efetuado atravs de 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 (ID 18): Automao pode fornecer um cdigo

de tabela a ser usado na transao de Parcele Mais, indicando o custo financeiro.
SCOPE_DADOS_PAGAMENTO_EX (ID 19): dados do pagamento para transaes que

necessitam do nmero do carto (confronte com SCOPE_DADOS_PAGAMENTO)
SCOPE_AUTOMACAO_PARTICIPA_PPONLINE (ID 20): responsvel por informar se a

automao comercial est apta a trabalhar com a plataforma promocional.
SCOPE_PERMITIR_SAQUE (ID 21): em transaes de dbito vista com a rede Cielo,

ao fornecer o valor 1 indicar que o SCOPE pode pedir a digitao do valor do saque se
configurado pela rede e ao fornecer 0 o SCOPE no perguntar pelo saque, mesmo
configurado pela rede Cielo e no SCOPECNF.
SCOPE_RESULTADO_VALIDACAO(ID 22): aps a validao do saque pela automao,

est passar o valor 1 aprovando o valor do saque digitado pelo portador do carto no
pinpad ou passar o valor 0 recusando o valor do saque solicitado.
SCOPE_DADOS_ECF_BENEFICIO (ID 23): fornecer os dados da ECF e do comprovante

para a transao.
SCOPE_DADOS_LISTA_PRECOS (ID 26): fornecer os dados da Lista de Atualizao de

Preos das Mercadorias.
SCOPE_DADOS_LISTA_MERCADORIAS (ID 27): fornecer os dados da Lista de

Mercadorias Consumidas na Aplicao.
SCOPE_DADO_MAX (ID 29): 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)
152
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.
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

153
Cdigos Retorno
Hexadeci Decimal
mal
0xFB01
64257
0xFE01
65025
0xFE05
65029
0xFE0D
0xFB09
65037
64265
Significado
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 10: atributos da aplicao cadastrados no ScopeCNF

A aplicao coletar estes dados sempre que houver uma venda com carto de crdito.
Exemplificando na linguagem C uma compra com carto de crdito (interface Alto Nvel HLAPI):
...
LONG RC;
char szAtributosAplic[40];
...
// operador selecionou crdito
...
// abre sesso de TEF
...
ScopeSuspend(EC_COLETA_CARTAO);
ScopeCompraCartaoCredito("100", "0");
...
if (RC == RCS_EXISTE_TRN_SUSPENSA)
{
// coletou o telefone do cliente e nmero do pedido
...
// montou o buffer do atributo da aplicao
// (ex. "0201014(11) 6097-123402006123456" e guardou em szAtributosAplic
...
ScopeForneceCampo(SCOPE_DADO_ATRIBUTOS_APLIC, szAtributosAplic);
ScopeResume();
154
}
...
// 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

Cdigos Retorno
Hexadeci Decimal
mal
0xFB01
64257
0xFE01
65025
Significado
155
ScopeGetCheque
Obtm os parmetros para impresso de cheque.
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

Cdigos Retorno
Hexadeci Decimal
mal
0xFE01
65025
0xFE04
65028
Significado
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
156

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE01
65025
Significado
Parmetro 1 invlido
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]
Valor
String
Valor da transao. Deve ser uma string de

at 12 bytes.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFB09
64265
0xFE00
65024
0xFE01
65025
0xFE05
65029
0xFE0D
0xFF36
65037
65334
0xFF3A
65338
Significado
Parmetro 1 invlido
anterior
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)
157
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64002
0xFB09
64265
0xFB01
64257
0xFE00
65024
0xFE01
65025
0xFF1D
65309
Significado
Parmetro 2 invlido
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

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64002
0xFB09
64265
0xFE01
65025
0xFE05
65029
0xFE06
0xFE07
65030
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
Significado
Parmetro 2 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
158
0xFF1D
65309
0xFF3A
0xFB03
0xFF00
65338
64259
65280
0xFF0A
0xFF5E
0xFFFF
65290
65374
65535

Erro genrico
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]
CPF
String
[out] String
Buf
[in]
TamBuf
WORD
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).
A aplicao deve informar ao SCOPE o
tamanho da rea reservada
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
0xFE01
65025
0xFE06
65030
0xFE07
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
65290
Significado
Parmetro 1 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
159
0xFFFF
0xFF5E
65535
65374
Erro genrico
ScopeResumoOperacoes
Utilizada nos casos em que a rede ou correspondente bancrio oferece a possibilidade de
obteno de um resumo das operaes realizadas.
Prottipo
LONG EXPORT ScopeResumoOperacoes (WORD CodServico, WORD CodBandeira)
Parmetros
[in]
WORD
CodServico
[in]
WORD
CodBandeira
Cdigo do servio do produto a ser

executado. Use 0 (zero) para indicar que o
cdigo do servio dever ser coletado
durante o fluxo da transao.
Cdigo da bandeira do produto a ser
cdigo da bandeira dever ser coletado.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE01
65025
0xFE05
65029
0xFE06
0xFE07
65030
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFE0D
0xFB01
0xFB03
0xFB09
0xFF00
65037
64257
64259
64265
65280
0xFF0A
*0xFF1D
65290
65309
Significado
Parmetro 1 invlido
Logon duplicado
POS no cadastrado
PDVs disponveis
160
0xFF36
65334
0xFF3A
0xFF5E
0xFF60
0xFFFF
65338
65374
65376
65535

anterior
Funo indisponvel
Erro genrico
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.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
0xFE00
65024
0xFE01
65025
0xFE05
65029
0xFE06
0xFE07
65030
65031
0xFE08
65032
Significado
Parmetro 1 invlido
Logon duplicado
POS no cadastrado
161
0xFE0A
65034
0xFE0B
65035
0xFE0D
0xFB01
0xFB03
0xFB09
0xFF00
65037
64257
64259
64265
65280
0xFF0A
*0xFF1D
65290
65309
0xFF36
65334
0xFF3A
0xFF5E
0xFF60
0xFFFF
65338
65374
65376
65535

PDVs disponveis
anterior
Funo indisponvel
Erro genrico
ScopeServicoTecnico
Utilizada para execuo de um servio tcnico disponvel para determinada rede autorizadora.
Temos os seguintes servios tcnicos: Baixa de OS, Teste de Comunicao, Estatistica e Injeo
de Chaves DUKPT.
O servio tcnico de Injeo de Chaves DUKPT insere a senha DUKPT no pinpad atravs de uma
transao 0900/0800 Injeo de Chaves e sua resposta 0910/0810 quando o pinpad no possui a
senha, isto o servio no atualiza senha; para isso utiliza-se a funo VerificaChaveDUKPT
para verificar se o pinpad possue senha DUKPT.
Prottipo
LONG EXPORT ScopeServicoTecnico (WORD CodServico, WORD CodBandeira)
Parmetros
[in]
WORD
CodServico
[in]
WORD
CodBandeira
Cdigo do servio do grupo Tcnico a ser

executado. Use 0 (zero) para indicar que a
deciso do servio ser atravs de coleta.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
Significado
Parmetro 1 invlido
162
0xFE00
0xFE01
0xFE05
65024
65025
65029
0xFE06
0xFE07
65030
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFE0D
0xFB01
0xFB03
0xFB09
0xFF00
65037
64257
64259
64265
65280
0xFF0A
*0xFF1D
65290
65309
0xFF36
65334
0xFF3A
0xFF5E
0xFF60
0xFFFF
65338
65374
65376
65535

Logon duplicado
POS no cadastrado
PDVs disponveis
anterior
Funo indisponvel
Erro genrico
ScopeAtualizaParametrosChip
Utilizada quando parmetros do chip do carto necessitam ser atualizados. Esta funo inicia o
fluxo de coleta necessrio para a atualizao de parmetros do chip do carto.
Redes que utilizam esta funo so: Ticket Edenred e Cielo R2014.
Coleta bsica da transao
Solicita ao portador a insero do carto no pinpad
Solicita a senha
Solicita a retirada do carto do pinpad
Prottipo
LONG EXPORT ScopeAtualizaParametrosChip(char *UsoFuturo1,
char *UsoFuturo2)
163
Parmetros
[in]
char
UsoFuturo1
[in]
char
UsoFuturo2
Reservado para uso futuro. Usar como

parmetro uma string vazia.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFB01
64257
0xFB03
64259
0xFB09
64265
0xFE01
65025
0xFE05
65029
0xFE06
0xFE07
65030
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
*0xFF1D
65290
65309
0xFF36
65334
0xFFFF
65535
Significado
Logon duplicado
POS no cadastrado
PDVs disponveis
anterior
Erro genrico
ScopeVersao
Esta funo retorna a verso do Scope.
Prottipo
LONG EXPORT ScopeVersao(char *_VersaoScope, int_TamBufVersao)
164
Parmetros
[out] char
_VersaoScope
[in]
_TamBufVersao
int
Informa o valor da verso do Scope em

formato string e null-terminated. Em caso
de erro, o buffer passado no sofre
alterao.
Contm o valor do tamanho da rea que
contm a verso. Deve conter o valor
mnimo de 12 bytes.
Retorno

Cdigos Retorno
Hexadeci Decimal
mal
0xFA01
64001
Significado
Parmetro 1 invlido
ScopeAtualizaPrecosMercadorias
Utilizada quando os Preos das Mercadorias do Estabelecimento necessitam ser atualizados na
rede Ticket Edenred. Esta funo inicia o fluxo de coleta necessrio para a Atualizao de Preos
das Mercadorias.
Redes que utilizam esta funo so: Ticket Edenred.
Prottipo
LONG EXPORT ScopeAtualizaPrecosMercadorias ( WORD _CodBandeira,
char *UsoFuturo1 )
Parmetros
[in]
WORD
_CodBandeira
[in]
char
UsoFuturo1
Cdigo da Bandeira (Ex. "228" - Ticket Car)

Retorno
Estados de coleta
Cdigos Retorno
Hexadeci Decimal
mal
0xFCCA
64714
Significado
Coleta da Lista de Atualizao de Preos de Mercadorias
165

Cdigos Retorno
Hexadeci Decimal
mal
0xFB01
64257
0xFB03
64259
0xFB09
64265
0xFE01
65025
0xFE05
65029
0xFE06
0xFE07
65030
65031
0xFE08
0xFE0A
65032
65034
0xFE0B
65035
0xFB03
0xFF00
64259
65280
0xFF0A
0xFF0C
*0xFF1D
65290
65292
65309
0xFF36
65334
Significado
Logon duplicado
POS no cadastrado
PDVs disponveis
anterior
166
Redes com tratamentos especficos

O objetivo de captulo abordar peculiaridades de tratamentos para algumas redes autorizadoras
como a coleta de dados no fluxo do SCOPE ou o relacionamento dos produtos da rede e as
transaes do SCOPE.
Banrisul EMV
Esta a implementao da nova especificao do Banrisul e que trata principalmente a utilizao
de cartes com chip. Com esta implementao, ser possvel realizar as seguintes transaes do
Banrisul no SCOPE:
Dbito vista, parcelado e pr-datado com o carto Banricompras;
Dbito vista e parcelado com o carto Banco SIM;
Crdito 1 minuto, que uma transao de CDC;
Dbito voucher de convnio Refeisul alimentao e refeio;
Consulta saldo de convnio Refeisul alimentao e refeio;
Dbito voucher de convnio Refeisul combustvel
Crdito com carto convnio Private Label
PINPads com suporte a rede

Para a realizao das transaes com cartes com chip nos PINPads deve-se garantir que o
PINPad saiba tratar estes cartes do Banrisul. Os PINPad com a verso da especificao da
biblioteca compartilha 1.06a j suportam, porm aqueles com a verso 1.05g pode no suportar.
Nestes casos dever ser efetuada a transao com a tarja magntica do carto. Para saber se o
PINPad suporta o tratamento do carto com chip Banrisul, deve-se entrar em contato do o banco
Banrisul.
Associao dos produtos e as funes do SCOPE

Abaixo est uma tabela onde so relacionados os produtos do Banrisul e as funes da API do
SCOPE que deve ser invocada para realizar a transao.
Produto Banrisul
Convnio Refeisul combustvel
Cancelamento
Pagamento vista, prazo e parcelado
Crdito 1 minuto
Banco SIM parcelado
Convnio Refeisul alimentao e refeio
Convnio Private label
Consulta de saldo de convnio Refeisul alimentao/refeio
Funo da API do SCOPE

ScopeCompraCartaoDebito
ScopeCancelamento
ScopeCompraCDC
ScopeCompraCartaoCredito
ScopeConsultaDebito
Transao convnio combustvel

Durante o fluxo de coleta desta transao, surgiro coletas especficas para a realizao desta
com o Banrisul, que so:
Cdigo de servio: este um cdigo de 2 dgitos que informa o tipo de servio realizado
previsto pelo Banrisul. Os possveis cdigos e seus significados so:
167
01 - Gasolina
02 - lcool
03 - Diesel
04 - GNV
05 - Combustvel Aviao
06 - leo
07 - Lavagem
08 - Borracharia
09 - leo Martimo
10 - Graxa
11 - Outros
12 - Gs GLP
13 - Filtro de Ar
14 - Filtro de leo
15 - leo Lubrificante
16 - Filtro de Combustvel
17 - Gasolina Aditivada
18 - Servio de Oficina
Quantidade de servio: um valor numrico de at 12 dgitos que representa a

quantidade do servio prestado. Exemplo: se o cdigo do servio escolhido foi 03, ento a
quantidade solicitada a quantidade de litros de diesel. Se o cdigo foi 08, ento a
quantidade de servio de borracharia executado, que nesse caso poderia ser apenas 1.
Matrcula: valor alfanumrico de at 11 dgitos.
Hodmetro: valor numrico que o hodmetro que est registrando no carro.
Placa do veculo: campo numrico apenas de at 8 dgitos e deve ser entrada apenas a
parte numrica da placa do carro.
Ticket Edenred
A implementao desta trata da especificao das transaes com o carto com chip Ticket Car,
na modalidade Benefcio e Gesto de Frotas. Transaes com carto so suportadas apenas
utilizando o chip do carto Ticket Car. As transaes disponveis no SCOPE que podem ser
realizadas com esta rede so:
Dbito Voucher;
Estorno Voucher;
Consulta saldo;
Atualizao de parmetros (Chip).
Atualizao de preos.
168
Para trabalhar com Gesto de Frotas necessria configurao descrita na seo

Parametrizao de Gesto de Frota do Manual de Instalao e Configurao do
Scope.
O SCOPE suporta a aprovao off-line, efetuada em POS, e uma caracterstica deste carto
que as transaes aprovadas off-line so armazenadas no prprio chip do carto para ser
descarregado numa prxima transao realizada noutro estabelecimento. Portanto o SCOPE
suporta o envio de transaes realizadas em POS e gravadas no chip. Para a transao de envio
destas off-line, verdade que:
o
Pode acontecer em qualquer uma das transaes desta rede;
No visvel para o operador do caixa ou portador do carto, ou seja, nenhum

dos dois sabem que est enviando tais mensagens;
No impresso comprovante para elas;
No visto em relatrios do SCOPEADM;
Apenas possvel verificar a existncia do envio da offline pelos logs do SCOPE

Server.
No h transaes com os cartes Ticket Alimentao e Ticket Restaurante roteadas para esta
rede no SCOPE.
PINPads com suporte a rede

Para a realizao das transaes com cartes com chip nos PINPads deve-se garantir que o
PINPad saiba tratar os cartes Ticket Car. Para isto deve-se utilizar PINPads Gertec modelo
PPC900 com a verso da especificao da biblioteca compartilhada 1.07A (ou superior) contendo
a chave Masterkey 3.

Abaixo est uma tabela onde so relacionados os produtos da rede Ticket Edenred e as funes
da API do SCOPE que deve ser invocada para realizar a transao.
Produto Ticket Edenred
Compra online (Dbito Voucher)
Estorno online
(vide item Compra com carto de dbito)

ScopeCancelamento
Consulta saldo
(vide item Estornando a transao)

ScopeConsultaSaldoDebito
Atualizao de parmetros
(vide item ScopeConsultaSaldoDebito)

ScopeAtualizaParametrosChip
Atualizao de preos
(vide item ScopeAtualizaParametrosChip)

ScopeAtualizaPrecosMercadorias
169
(vide item ScopeAtualizaPrecosMercadorias)
Dados coletados
Abaixo est a relao do que pode ser solicitado em cada transao:
Transao
Coletas
Estorno online
Consulta saldo
Atualizao de parmetros
Atualizao de preos
Carto
Dados do ECF (veja mais abaixo)
Senha
Imprimir cupons
Dados Livres (Dados Adicionais)
Nmero de controle da compra
Carto
Imprimir cupons
Carto
Senha
Imprimir cupom do cliente
Carto
Senha
Nenhuma coleta
Consulta saldo
A funo utilizada para esta transao a ScopeConsultaSaldoDebito que como parmetro
espera receber um valor. No entanto, para os cartes Ticket Car no utilizado este, portanto, a
automao pode passar uma string vazia.
Esta transao no possui cupom da loja, mas apenas do cliente.
Dados do ECF
Na transao de compra online (dbito Voucher) necessrio enviar dados do cupom e do ECF.
O SCOPE retorna, no modo coleta, ento o estado de coleta TC_COLETA_DADOS_ECF
(FCBEh) e a automao deve invocar a funo ScopeForneceCampo com os seguintes
parmetros:
TypeField: tipo de dado:

o
SCOPE_DADOS_ECF_BENEFICIO Fornecer os dados da impressora fiscal. A

utilizao desta constante deve ser feita na transao de dbito, num estado de
coleta
TC_COLETA_DADOS_ECF.
Informaes
adicionais
na
seo
"Fornecendo informaes extras para a transao"
StructField: dados fornecidos pela aplicao, cujo formato para a constante utilizada na
tabela abaixo.
Posio
Formato
001-040
ans40
Descrio
Nmero de srie de fabricao do ECF
(alinhado esquerda com brancos direita)
041-044
n4
Nmero do PDV atribudo ao ECF

(alinhado direita com zeros esquerda)
170
045-064
n20
Nmero do documento fiscal

(alinhado esquerda com brancos direita)
065-072
n8
Data de emisso do documento fiscal no formato AAAAMMDD.
Dados da Lista de Mercadorias Consumidas

Na transao de compra online (dbito Voucher) necessrio enviar dados da Lista de
Mercadorias Consumidas pela Aplicao. O SCOPE retorna, no modo coleta, o estado de coleta
TC_COLETA_LISTA_MERCADORIAS (FCCBh) e a automao deve invocar a funo
ScopeForneceCampo(char TypeField, void *StructField), com os seguintes parmetros:

o
SCOPE_DADOS_LISTA_MERCADORIAS Fornecer os dados da Lista de

Mercadorias Consumidas. A utilizao desta constante deve ser feita na
transao de dbito, no estado de coleta TC_COLETA_LISTA_MERCADORIAS.
Informaes adicionais na seo "Fornecendo informaes extras para a
transao"
tabela abaixo.
Posio
Formato
Descrio
001-004
an4
Header ("LM01") - Identificador do layout da lista
005-005
n1
Quantidade de Casas Decimais para Valor Unitrio das mercadorias.

Enviado no ID126 (Compreendido entre 0 e 7, inclusive)
006-006
n1
Quantidade de Casas Decimais para Quantidade das mercadorias.

Enviado no ID145 (Compreendido entre 0 e 8, inclusive)
007-008
n2
Ramo Atividade "01" (Posto de Combust.)

Cdigo do Ramo de Atividade do Checkout.
(alinhado a direita e preenchidos com zeros esquerda, caso necessrio)
009-013
an5
ID - "SC101"
Contm identificador do formato do registro que ser passado
014-016
n3
Qtd. Registros - Todos os registros a seguir devero ser do mesmo formato

(SC101):
017-106
ans90
Registro SC101 - Conforme descrio do formato.
107-196
ans90
Registro SC101 - Conforme descrio do formato.
...
A consulta aos cdigos das mercadorias est descrita posteriormente no tem Cdigo das
Mercadorias
171
Descrio do formato do registro "SC101":

O formato deste registro foi baseado no formato do registro ID101 da especificao
TicketCar, com o acrscimo da informao da descrio da automao para formatar o
registro ID161 da TicketCar.
Posio
Formato
001-040
an40
041-045
n5
Descrio
Descrio da Mercadoria da Automao Comercial.
Cdigo da Mercadoria consumida (Cdigo TicketCar).
045-052
n8
Quantidade de Mercadoria consumida.

053-061
n9
Valor da Transao para a mercadoria consumida.

062-070
n9
Valor unitrio ou valor unitrio teto da mercadoria consumida (zerado, se

transao for OFF-LINE).
071-079
n9
Valor da Transao para a mercadoria consumida (com desconto).

080-088
n9
Valor do desconto ($ ou %)
Se (%) dever ser enviado (x 100).
Exemplo: 10,15% 000001015
Se ($) dever utilizar expoente de moeda da transao.
Exemplo (expoente = 2): $ 15,66 000001566
089-089
n1
Significado do campo "Valor do desconto (moeda ou percentual)".

0 = Valor ($) dado como desconto
1 = Valor (%) dado como desconto
Observao: Repetir este bloco tantas quantas forem as mercadorias que os preos foram atualizados.
Dados da Lista de Atualizao de Preos de Mercadorias

Na transao de Atualizao de Preos de Mercadorias necessrio enviar dados da Lista de
Atualizao de Preos de Mercadorias. O SCOPE retorna, no modo coleta, o estado de coleta
TC_COLETA_LISTA_PRECOS
(FCCAh)
automao
deve
invocar
funo
ScopeForneceCampo com os seguintes parmetros:

o
SCOPE_DADOS_LISTA_PRECOS Fornecer os dados da Lista de Atualizao

de Preos de Mercadorias. A utilizao desta constante deve ser feita na
transao de Atualizao de Preos de Mercadorias, no estado de coleta
TC_COLETA_LISTA_MERCADORIAS.
Informaes
adicionais
na
seo
"Fornecendo informaes extras para a transao"

172
tabela abaixo.
Posio
Formato
Descrio
001-004
an4
"LP01" Identificador do layout da lista
005-009
an5
"ID504" Contm identificador do formato do registro que ser passado:
010-012
n3
013-044
ans32
Qtd. Registros - Todos os registros a seguir devero ser do mesmo formato

(ID504).
Registro ID504 - Conforme descrio do formato.
045-076
ans32
Registro ID504 - Conforme descrio do formato.
...
Descrio do formato do registro "ID504":

Posio
Formato
Descrio
001-008
n8
Data da atualizao de preo (Formato AAAAMMDD)
009-014
n6
Hora da atualizao de preo (Formato HHMMSS)
015-019
n5
020-031
n12
032-032
n1
Cdigo da mercadoria
Valor do preo unitrio
Nmero de casas decimais para o valor unitrio da mercadoria
Observao: Repetir este bloco tantas quantas forem as mercadorias que os preos foram atualizados.
A consulta aos cdigos das mercadorias est descrita posteriormente no tem Cdigo das
Mercadorias.
Comprovantes
Abaixo segue os comprovantes existentes para cada transao:
Transao
Coletas
Loja
Cliente
Estorno online
Consulta saldo
Reduzido
Atualizao de parmetros (Dados

Chip)
Atualizao de preos
Cdigo das Mercadorias

A Ticket Edenred envia Inicializao de Tabelas com as mercadorias e seus respectivos cdigos.
possvel consultar as mercadorias parametrizadas pela Ticket Edenred, atravs do ScopeCNF,
acessando o menu exibido a seguir:
173
Cielo Premia
O CIELO Premia um programa de premiao, atravs do qual, o comprador pode receber
prmios no momento da compra quando a TEF transacionada pela Cielo. Tambm conhecido
como Plataforma Promocional Online da Cielo, ou, abreviadamente PP Online.
Como a gesto da campanha?

Toda a gesto da campanha, inclusive sua temporalidade, controlada pela autorizadora, ou
seja, a Cielo quem ir definir o perodo de validade da promoo, quais brindes sero
oferecidos, regras de sorteio, cartes envolvidos, etc. As configuraes so internas da Cielo e/ou
Emissores e exigem uma atualizao de tabelas (Inicializao). A atualizao das tabelas feita
pelo SCOPE de forma online e automtica, mediante sinalizao da Cielo.
Quais tipos de prmios o comprador pode receber?

Esto previstos os seguintes tipos de prmios:
Brindes, a serem resgatados posteriormente atravs de transao especfica (Resgate de

Prmio); Chamado tambm de resgate no monetrio;
Desconto instantneo, a ser aplicado no momento da compra, sobre o produto comprado.

Chamado tambm de resgate monetrio;
174
Cupom eletrnico, que apenas uma notificao de que o cliente est participando de
uma campanha promocional. chamado tambm de e-cupom de participao.
IMPORTANTE: Todos os tipos de prmios podem ou no ocorrer simultaneamente em uma
mesma transao.
Que tipos de transaes podem receber os prmios?
Crdito;
Dbito;
Voucher Alimentao;
Voucher Refeio.
possvel restringir para tratar apenas prmios no monetrios, ou seja,

no permitir descontos?
Caso o segmento de atuao ou os estados do Brasil em que sua automao utilizada possuam
restries fiscais concesso de descontos monetrios, sugerimos consultar a empresa
certificadora da CIELO e validar de antemo o tratamento que o tratamento que se pretende fazer
na automao ser adequado para a certificao.
O que preciso configurar no SCOPE CNF?

necessrio habilitar o produto abaixo no Perfil de Servios.
Bem como a bandeira CIELO na tela de Contrato:
A Cielo precisa habilitar o Cielo Premia?

Sim, a Inicializao de Tabelas precisa contemplar tais produtos. O Lojista precisa entrar em
contato com a CIELO e negociar a implantao do Cielo Premia.
possvel integrar e testar atravs do SCOPE Autorizador?

Sim. No ScopeAut h uma Inicializao de Tabelas que contempla o Cielo Premia, chamada PP
OnLine, conforme mostrado abaixo:
175
IMPORTANTE:
1- Antes de iniciar os testes lembre-se de forar uma Inicializao para o estabelecimento
em questo para garantir que a carga PP OnLine seja carregada no banco de dados pelo
ScopeSRV.
2- Os prmios e cupons gerados pelo ScopeAUT possuem contedos fixos, e portanto, no
representam efetivamente o que ir ocorrer em produo.
possvel fazer um teste usuando o HotKey?

Sim. O HotKeyHLAPI, HotKeyColeta e TstColeta esto preparados, porm deve ser configurada
uma nova chave no SCOPE.INI do client, conforme exemplo abaixo (considerando empresa
0001 e filial 0001):
[00010001]
AutomacaoParticipaPPOnline=S
A Automao Comercial deve se adequar?

Sim. A Automao Comercial precisa informar que est preparada para o Cielo Premia, adequar
os fluxos de Crdito e Dbito e permitir o Resgate de Prmio.
O que a Automao Comercial precisa fazer para estar aderente?

Para habilitar o Cielo Premia, ou seja, configurar que est preparada:
Aps o ScopeOpen, chamar a funo ScopeForneceCampo passando como parmetros o
tipo de dado SCOPE_AUTOMACAO_PARTICIPA_PPONLINE e o contedo S ou 1 para
indicar que SIM, ou seja, a automao est preparada para participar da plataforma Cielo
Premia. Maiores detalhes sobre esta funo esto no Manual do Desenvolvedor.
Note que o default (se no executar a funo acima) no habilitado. Neste caso a CIELO
no ir retornar nenhum tipo de prmio e tudo deve funcionar como antes.
Tambm possvel chamar a mesma funo/dado passando N ou 0 para deixar o Cielo
Premia desabilitado.
Enquanto no executado o ScopeClose, o SCOPE mantm a informao se a AC est ou
no participando do Cielo Premia vlida para as prximas transaes.
Tambm possvel que a AC defina se participa ou no do Cielo Premia a cada transao.
Assim,
pode-se
chamar
ScopeForneceCampo
passando
SCOPE_AUTOMACAO_PARTICIPA_PPONLINE com SIM ou NO antes de cada

ScopeCompraCartaoCredito e ScopeCompraCartaoDebito.
Para saber se a Cielo premiou com desconto monetrio:

Tratar o novo cdigo de retorno 263 (0x107) retornado pela ScopeStatus para indicar que a
transao foi APROVADA COM DESCONTO. Caso o retorno da transao seja 000
176
(0x000), indica que a transao foi APROVADA (pode ou no ter recebido prmio no
monetrio), mas com certeza, no houve desconto. Importante notar que ambos os retornos
do ScopeStatus (000 e 263) indicam transao APROVADA.
No preciso esperar a finalizao da transao para saber se houve ou no o desconto.
Normalmente essa informao necessria ao receber o cupom de TEF, para decidir como
finalizar o cupom fiscal. A informao se houve ou no desconto e o valor do desconto
podem ser obtidas nos estados de coleta de impresso de cupom.
IMPORTANTE: Quando h desconto na transao, o valor com desconto ser exibido no
pinpad para o cliente visualizar o valor final. Mensagem VALOR COM DESCONTO.
Para saber o valor do desconto:
Para obter o valor do desconto, usar a funo ScopeObtemCampoExt2, mscara 3,
Informao do desconto do resgate monetrio (0x00000002). Esta informao pode ser
solicitada antes da impresso/solicitao do Cupom (ScopeGetCupomEx). Caso o valor
retornado seja zero, ento no houve desconto.
Como tratar o desconto no Cupom Fiscal:

Veja fluxo sugerido pela Cielo no documento FLUXO BASICO CIELO PREMIA.pdf.
Como saber se houve um prmio no monetrio (brinde) recebido durante

uma compra?
Se houve algum prmio no monetrio (um brinde), esta informao pode ser recuperada
atravs da funo ScopeObtemCampoExt2, mscara 3, Informaes sobre a quantidade e
e-cupons disponveis (0x00000001). A informao segue a seguinte estrutura:
typedef struct {
char QtdeOcorrenciasECupom[2];
char DadosResgate[3000];
} stPPResgateNaoMonetario
Esta informao pode ser solicitada antes da impresso/solicitao do Cupom

(ScopeGetCupomEx).
Os brindes sero acumulados pela Cielo atravs do nmero de carto, portanto, o cupom
da promoo apenas informativo, no necessrio para o resgate.
Note que, durante os fluxos de compra (crdito e dbito), a informao se ocorreu um
prmio no monetrio pode no ser relevante para automao, j que no h nenhum
tratamento a fazer.
IMPORTANTE: Para cupom de tamanho zero, descartar o prmio.
177
Como fazer um Resgate de Prmio?

O resgate feito no SCOPE atravs da funo ScopeMenu. Esta funo ir exibir os produtos
disponibilizados pela Cielo para o chamado Menu Outros e poder conter outras opes alm do
resgate de prmio.
O operador dever selecionar a opo correspondente, que ir acionar no SCOPE o servio
Consulta Resgate de Prmio.
O fluxo do Resgate de Prmio j prev uma consulta automtica Cielo para buscar os prmios
disponveis para um determinado carto, lido no incio do fluxo.
Para
obter
lista
de
brindes
disponveis,
AC
pode
tratar
estado
de
coleta
TC_EXIBE_MENU_RESGATE_PREMIO retornado pela funo ScopeStatus.

IMPORTANTE:
Para que a opo Resgate de Prmio esteja disponvel no Menu, a
inicializao de tabelas do estabelecimento em questo dever estar atualizada de forma a

contemplar o Cielo Premia.
Para os resgates no monetrios, deve ser seguido basicamente o fluxo:
1. Recuperar do SCOPE os dados dos prmios e exibir;
2. Coletar o prmio escolhido e a quantidade;
Para recuperar e exibir os dados dos prmios:
1. Tratar o estado TC_EXIBE_MENU_RESGATE_PREMIO;
2. Chamar a funo ScopeObtemCampoExt2 pedindo pelos dados de resgate no
monetrio;
3. Exibir sequencialmente os prmios de acordo com exemplo abaixo.
Exemplo:
char
aux[5000];
...
switch (RC)
{
case TC_EXIBE_MENU_RESGATE_PREMIO:
h = ScopeObtemHandle(0);
if (h > 0xFFFF)
{
ScopeObtemCampoExt2(h, 0x00, 0x00, Dados_Resgate_Nao_Monetario, '\0', aux);
demo_ExibeResgateNaoMonetario(aux);
}
...
}
Onde aux contm um buffer que contenha espao necessrio para ser armazenado o nmero de
prmios e os dados relativos aos prmios. O buffer ser preenchido com a seguinte estrutura:
typedef struct {
char QtdeOcorrenciasECupom[2];
char DadosResgate[3000];
} stPPResgateNaoMonetario
178
Os dois primeiros bytes do buffer correspondem quantidade de prmios e os bytes restantes

sero os dados dos prmios. Para cada prmio, ele ser prefixado com 2 bytes que representam
o tamanho do texto:
Posio
01-02
03-04
05-x
...
Formato
N2
N2
A(n)
...
Descrio
Nmero de E-cupons
Tamanho do 1 E-cupom
Ttulo do 1 Prmio, de tamanho n varivel definido nos 2 bytes anteriores
Obs. Repetem-se tamanho e ttulo para os N cupons
IMPORTANTE: A quantidade de prmios pode ser igual a zero e corresponde que no h

premiao.
Exemplo:
void demo_ExibeResgateNaoMonetario (char *aux)
{
stPPResgateNaoMonetario
sDadosResgateNaoMonetario;
short i, nTamanhoEcupom = 0, j = 0, nQuantidade = 0;
char sTamanhoEcupom[2+1], sNomeEcupom[99+1], sQuantidade[2+1];
memset (&sDadosResgateNaoMonetario, 0, sizeof(sDadosResgateNaoMonetario));
memset (&sNomeEcupom, 0, sizeof(sNomeEcupom));
memcpy(sQuantidade, aux, 2);
sQuantidade[2] = 0;
strcpy(sDadosResgateNaoMonetario.DadosResgate, &aux[2]);
nQuantidade = atoi(sQuantidade);
if (nQuantidade > 0)
{
printf ("\n\nPLATAFORMA PROMOCIONAL:\n\n");
}
else
{
printf ("\n\nNAO HA PREMIACAO, CONSULTE REGULAMENTO");
return;
}
for(i = 0; i < nQuantidade && i < 20; i++)
{
memcpy(sTamanhoEcupom, &sDadosResgateNaoMonetario.DadosResgate[j], 2);
sTamanhoEcupom[2] = 0;
nTamanhoEcupom = atoi(sTamanhoEcupom);
j += 2;
memcpy(sNomeEcupom, &sDadosResgateNaoMonetario.DadosResgate[j],
nTamanhoEcupom);
sNomeEcupom[nTamanhoEcupom] = 0;
j += nTamanhoEcupom;
printf ("%02d - %s", i + 1, sNomeEcupom);
printf ("\n");
}
printf ("\n\n");
return;
}
Aps a exibio dos prmios, a automao pode fazer:

A coleta do ndice/nmero do prmio escolhido pelo cliente (TC_NRO_RESGATE_PREMIO
0xFCA4)
179
A coleta de quantidade a ser resgatada (TC_CONFIRMA_OPCAO_RESGATE_PREMIO

0xFCA2)
IMPORTANTE: : A quantidade de prmios no repassada para a Automao Comercial,
somente exibida no display.
Existe uma forma de tratar os itens do Menu Dinmico pela aplicao de AC?
Sim. Os itens exibidos pela funo ScopeMenu podem ser manipulados pela AC. Para isso
existem as funes:
ScopeMenuRecuperaItens;
ScopeMenuSelecionaItem.
Atravs da funo ScopeMenuRecuperaItens a AC pode tratar o estado TC_EXIBE_MENU para

obter os itens de forma a exibi-los todos de uma s vez, ou ento, exibir apenas os que interesse
para a Automao Comercial.
A seleo tambm pode ser controlada atravs da ScopeMenuSelecionaItem. A Automao
Comercial pode usar essa funo aps a seleo do operador de caixa, ou ainda, selecionar um
item de forma automtica, sem exibir a lista ao operador.
Existe um cdigo exemplo?

Sim. Um cdigo em C de exemplo (TstColeta) acompanha este documento.
Qual a verso mnima do SCOPE que contempla Cielo Premia?

A verso mnima 2.27.23.02 (server e client), embora o recomendvel seja o uso da verso
mais recente.
Cielo Auto
Esta transao efetuada com cartes do tipo voucher que permitem o pagamento do
abastecimento de combustvel e outros servios prestados aos veculos automotivos em
estabelecimentos como postos de gasolina.
Na especificao CIELO Release 2014, corresponde ao Fluxo 32 -Transao Auto.
Transaes so suportadas apenas utilizando o chip do carto. A bandeira que ir tratar esta
transao ser:
278 - CIELO AUTO
As transaes disponveis no SCOPE que podem ser realizadas com este carto so:
Dbito Voucher;
Estorno Voucher;
Consulta saldo;
180
Atualizao de parmetros (Chip).
Lista de produtos e/ou servios principais Cielo Auto

Esta lista poder conter os seguintes ramos principais:
COMBUSTVEL
OUTROS PRODUTOS E SERVIOS
ESTACIONAMENTO
Esta lista ser exibida de acordo com as informaes enviadas na Carga de Tabelas da CIELO e
nas informaes habilitadas no chip do carto. O SCOPE disponibiliza os itens do Menu para a
aplicao de automao comercial para a melhor exibio dessas informaes. Esta lista
fornecida durante o fluxo de coleta atravs do estado abaixo:
TC_COLETA_RAMO_PRINC_CIELO_AUTO
0xFCD9
Coleta Ramo Principal Cielo Auto
Num fluxo de Compra com Cartao de Debito, recebendo o cdigo de coleta 64729
(TC_COLETA_RAMO_PRINC_CIELO_AUTO), a aplicao de PDV pode realizar o mesmo
tratamento do estado TC_EXIBE_MENU (que j existe hoje), ou seja, opcionalmente chamar a
funo ScopeMenuRecuperaItens do SCOPE para receber os itens do Menu a serem exibidos e
em seguida chamar a ScopeMenuSelecionaItem para indicar ao SCOPE qual item foi
selecionado.
Desta forma, o PDV poder, por exemplo:
Exibir todos os itens na mesma tela (hoje, pelo fluxo do SCOPE Client, apresentado um
item por vez);
Excluir algum item da lista que eventualmente no deva ser exibido ao operador;
Alterar a descrio de algum item para melhor entendimento do operador;
Fazer a seleo automtica de um determinado item sem apresent-lo ao operador;
Caso o aplicativo de automao comercial opte por no tratar este estado de coleta, o SCOPE
exibir os itens na forma de menu rotativo.
Vale ressaltar que este menu somente ser exibido se existir mais que um ramo principal a ser
selecionado. Caso exista apenas um item, o SCOPE assume-o automaticamente sem exibir o
menu.
Lista de produtos e/ou servios secundarios Cielo Auto

Cada ramo principal poder conter sua prpria lista de produtos e/ou servios secundrios que
atuam como mercadorias para automao comercial. Esta lista ser exibida de acordo com as
informaes enviadas na Carga de Tabelas da CIELO e nas informaes habilitadas no chip do
carto. Esta lista poder conter as seguintes mercadorias:
COMBUSTVEL
181
Gasolina comum
Etanol
Diesel
Gasolina Aditivada
Gasolina Premium
Etanol Aditivado
Diesel S50
Diesel Aditivado
GNV (m3)
Biodiesel
OUTROS PRODUTOS E SERVIOS
Lava-Rpido
Aditivos e Lubrificantes
Filtros
Borracharia
Manuteno Geral
Equipamentos eltricos
ESTACIONAMENTO
Estacionamento
Esta lista fornecida durante o fluxo de coleta atravs do estado abaixo:

TC_COLETA_COD_MERC_CIELO_AUTO
0xFCDA Coleta Codigo de Mercadoria Cielo Auto
Caso exista apenas uma mercadoria habilitada na Carga de Tabelas ou no carto, o SCOPE
assume automaticamente essa mercadoria.
Num fluxo de Compra com Cartao de Debito, recebendo o cdigo de coleta 64730
(TC_COLETA_COD_MERC_CIELO_AUTO), a aplicao de PDV dever obter a lista de
mercadorias disponveis, atravs da funo ScopeRecuperaBufTabela ().
Prottipo
LONG EXPORT ScopeRecuperaBufTabela (BYTE _TipoTabela,
char *Qtd,
char *ListaBuffer,
WORD TamLista)
182
Descrio
Esta rotina servir para disponibilizar para a aplicao de automao comercial,

uma lista de informaes a serem exibidas na tela para facilitar a seleo da
opo desejada.
Ela servir para facilitar futuras implementaes que atendam a mesma
finalidade.
O parmetro _TipoTabela indicar o formato dos dados que sero fornecidos.
Parmetros
[out]
String [2+1]
Qtd
Retorna a quantidade de elementos da lista.
[out]
String
ListaBuffer
Retorna os registros da lista.
[in]
WORD
TamLista
Tamanho, em bytes, do campo ListaBuffer
Retorno
Parmetro TipoTabela:
ID layout
Usar estrutura
Descrio
Contm os campos,
BUF_TAB_MERCADORIA_CIELOAUTO
(ID 3)
stREG_MERCADORIA_CIELOAUTO
conforme a transao
AUTO da especificao
CIELO .
Parmetro ListaBuffer:
O SCOPE est preparado para tratar MAX_MERCADORIA_CIELOAUTO=72 mercadorias
da CIELO AUTO.
A lista formada por registros stREG_MERCADORIA_CIELOAUTO com os seguintes
campos:
Posio
Formato
Descrio
01 a 02
char
Cdigo do Ramo Principal.
03 a 04
char
Cdigo da Mercadoria.
05 a 45
String
Descricao da Mercadoria.
Exemplo
int i = 0;
char qtd [2+1] = {0};
LONG lRet;
stREG_MERCADORIA_CIELOAUTO lista [MAX_MERCADORIA_CIELOAUTO] = {0};
lRet = ScopeRecuperaBufTabela (BUF_TAB_MERCADORIA_CIELOAUTO,
qtd,
(char*) lista,
sizeof (lista));
183
{
// Sucesso no recebimento da lista de mercadorias
for (i = 0; i < atoi(qtd); i++)
{
// exibe os membros das estruturas que estaro preenchidos
// lista[i].CodRamoPrinc,
// lista[i].CodMercadoria,
// lista[i].Descricao
}
}
else
// Erro ...
Informaes Adicionais Cielo Auto

Estas informaes sero exibidas para coleta de acordo com a parametrizao da Carga de
Tabelas da CIELO e de acordo com as informaes habilitadas no chip do carto.
Informaes Adicionais
Captura da placa
Hodmetro
Hormetro
Cdigo do Motorista
A aplicao de PDV no necessita realizar qualquer tratamento para a coleta desses campos pois
o SCOPE exibe de forma dinmica, tanto a mensagem quanto os dados coletados, dependendo
do carto utilizado.
SAVS
Esta seo trata da especificao das transaes com a rede SAVS (Sistema Autorizador de
Vouchers e Servios).
As transaes implementadas no SCOPE que podem ser realizadas com esta rede so:
Autorizao de Voucher;
Estorno de Autorizao Voucher;

Abaixo est uma tabela onde so relacionados os produtos da rede SAVS e as funes da API do
SCOPE que deve ser invocada para realizar a transao.
Produto SAVS
Autorizao de Voucher
Estorno

ScopeServicosGenericos
ScopeCancelamento
184
Autorizao de Vouchers e Servios

Para a transao de Autorizao de Vouchers e Servios a automao dever chamar a funo
ScopeServicosGenericos, passando como parmetro uma string contendo o cdigo de Servio e
uma string vazia.
Durante transao de Autorizao de Voucher, como a rede SAVS trabalha com Carga de
Tabelas, algumas coletas podem ocorrer, ou no, de acordo com a configurao enviada ao
SCOPE na Inicializao de Tabelas.
O SCOPE seleciona internamente o fluxo de coleta, de acordo com a configurao enviada pela
rede Autorizadora. Para facilitar o entendimento, seguem as coletas afetadas pela parametrizao
da Carga de Tabelas e a descrio dos Estados de Coleta que sero desviados pelo SCOPE:
Parametrizao de Fornecedor
De acordo com a parametrizao do Fornecedor selecionado, as coletas solicitadas esto

descritas na tabela a seguir:
Coleta de Fornecedor:
Parmetro da Carga
Quantidade de
Fornecedores
Disponveis no
Segmento
Selecionado
Coleta
1
>1
Seleciona automaticamente
o nico Fornecedor disponvel e pula para:
Coleta de Produto TC_COLETA_PRODUTO_SAV (0xFCD6)

Coleta de Fornecedor Estado TC_COLETA_FORNECEDOR_SAV (0xFCD5)
Coleta de cdigos, valor, quantidade e Cliente Preferencial:
185
Parmetro da Carga
Coleta
"0"
"1"
Tipo de coleta de
dados do Voucher
"2"
"3"
Cdigo do Produto - Estado

TC_COLETA_PRODUTO_SAV (0xFCD6)
Valor Estado
TC_COLETA_VALOR (0xFC34) ou
TC_INFO_AGU_CONF_OP(0xFCFF)
Quantidade Estado
TC_COLETA_QUANTIDADE (0xFCD7)
Cdigo EAN - Estado

Valor EstadoTC_COLETA_VALOR (0xFC34) ou

Cdigo do Produto - Estado


Nmero do Voucher Estado TC_COLETA_NRO_VOUCHER (0xFCA5)
Cdigo EAN - Estado


Nmero do Voucher
Estado TC_COLETA_NRO_VOUCHER (0xFCA5)
No solicita Coleta de
Cliente Preferencial
Cliente preferencial
Coleta: Cliente Preferencial?

(Sim/No) - Estado TC_COLETA_CLIENTE_PREFERENCIAL
(0xFCD8)
Para cada Segmento selecionado no Estado de Coleta TC_COLETA_SEGMENTO_SAV

(0xFCD4) podem estar disponveis alguns Fornecedores. A lista de Fornecedores associada ao
segmento selecionado, em passo anterior do fluxo de coleta, est descrita posteriormente neste
documento na seo Lista de Fornecedores.
Parametrizao de Produtos
De acordo com a parametrizao do Produto (Produto, Servio ou Cdigo EAN) selecionado

podem ser habilitados:
Coleta de dados dinmicos (Numrico, alfabtico, alfanumrico, menu de opes, Trilha

de Carto, Data, etc.) - Estado TC_COLETA_DADOS_ADICIONAIS (0xFC7C)
Exibio de valor sugerido - Estado TC_COLETA_VALOR (0xFC34)
186
Confirmao
do
Valor
Assumido
por
Parametrizao
Estado
TC_INFO_AGU_CONF_OP (0xFCFF)
Para cada Fornecedor selecionado no Estado de Coleta TC_COLETA_FORNECEDOR_SAV
(0xFCD5) podem estar disponveis alguns Produtos. A lista de Produtos associada ao Fornecedor
selecionado, em passo anterior do fluxo de coleta, est descrita posteriormente neste documento
na seo Lista de Produtos.
Estorno de Autorizao de Vouchers e Servios

Para estorno da transao de Autorizao de Vouchers e Servios a automao dever chamar a
funo ScopeCancelamento passando como parmetro o valor total da transao original.
Lista de Fornecedores
A lista de fornecedores pode ser retornada para a automao comercial no novo layout, como
descrito a seguir:
Num fluxo de Autorizao de Servios Voucher, recebendo o cdigo de coleta 64725
(TC_COLETA_FORNECEDOR_SAV), a aplicao dever obter a lista de fornecedores
disponveis, atravs da funo ScopeRecuperaBufTabela ().
Prottipo
char *Qtd,
char *ListaBuffer,
WORD TamLista)
Descrio

opo desejada.
finalidade.
Parmetros
[out]
String
Qtd
[out]
String
ListaBuffer
[in]
WORD
TamLista
Retorno
Parmetro TipoTabela:
187
ID layout
Usar estrutura
Descrio
Fornecedores SAVS.
BUF_TAB_FORNECEDORE
stREGISTRO_FORNECED
Contm os campos,
S_SAVS (ID 1)
ORES_SAVS
conforme a especificao
do Autorizador Voucher.
A lista formada por registros stREGISTRO_FORNECEDORES_SAVS com os seguintes
campos:
Posio
Formato
Descrio
01 a 04
String
Cdigo do Fornecedor.
05 a 25
String
Nome do Fornecedor.
26 a 27
String
Cdigo do Segmento de Mercado.
27 a 27
String
Quantidade mxima de produtos diferentes.
Exemplo
char sQtdFornec[3] = {0};
LONG lRet;
stREGISTRO_FORNECEDORES_SAVS lstFornecedores [20] = {0};
lRet = ScopeRecuperaBufTabela (BUF_TAB_FORNECEDORES_SAVS,
sQtdFornec,
(char*) lstFornecedores,
sizeof (lstFornecedores));
{
/* Sucesso no recebimento da lista de fornecedores,
}
else
// Erro ...
Lista de Produtos
A lista de produtos pode ser retornada para a automao comercial no novo layout, como descrito
a seguir:
Num
fluxo
de
Autorizao
de
Servios
Voucher,
recebendo
cdigo
de
coleta
TC_COLETA_PRODUTO_SAV (0xFCD6), a aplicao dever obter a lista de produtos

disponveis, atravs da funo ScopeRecuperaBufTabela.
Prottipo
char *Qtd,
char *ListaBuffer,
188
WORD TamLista)
Descrio

opo desejada.
finalidade.
Parmetros
[out]
String
Qtd
[out]
String
ListaBuffer
[in]
WORD
TamLista
Retorno
ID layout
Usar estrutura
Descrio
Produtos SAVS.
Contm os campos:
BUF_TAB_PRODUTOS_SAV
stREGISTRO_PRODUTOS
cdigo, descrio e
S (ID 2)
_SAVS
valores, conforme a
especificao do
Autorizador Voucher.
A lista formada por registros stREGISTRO_PRODUTOS_SAVS com os seguintes
campos:
Posio
Formato
Descrio
01 a 13
String
14 a 34
String
Descrio.
35 a 47
String
Valor mnimo
47 a 59
String
Valor mximo
59 a 71
String
Valor sugerido
Cdigo do Produto, Cdigo do Servio ou Cdigo

EAN.
Exemplo
char sQtdProd[3] = {0};
LONG lRet;
stREGISTRO_PRODUTOS_SAVS lstProdutos [50] = {0};
lRet = ScopeRecuperaBufTabela (BUF_TAB_PRODUTOS_SAVS,
sQtdProd, (char*) lstProdutos, sizeof (lstProdutos));
189
{
/* Sucesso no recebimento da lista de produtos,
}
else
// Erro ...
Cielo Transaes Sem Contato (Contactless)

So transaes realizadas atravs de leitura sem contato no PINPad. Atualmente a Cielo 4.1
R2014, tambm conhecida como Cielo Release 2014, a nica que permite realizar esse tipo de
transao.
Atualmente as bandeiras Visa, Visa Electron, Mastercard, Maestro e Amex so as nicas
certificadas a operar atravs de leitura sem contato.
Requisitos
Para que esse tipo de transao seja aceito, o estabelecimento precisa estar trabalhando com
Cielo 4.1 R2014. O PINPad precisa ser no mnimo 1.08a com mdulo Contactless instalado e
firmware atualizado. Em caso de dvida, consulte o fabricante do PINPad para saber se seu
PINPad est ou no preparado para aceitar Contactless.
Na inicializao de tabelas do estabelecimento em questo, a Cielo precisa habilitar e enviar na
carga AIDs com Contctless habilitado.
O valor da transao precisa estar dentro da faixa permitida para Contactless, dado que tambm
configurado atravs da inicializao de tabelas. A carga no PINPad precisa estar atualizada com
pelo menos um AID do grupo da transao em questo (Crdito ou Dbito) com Contactless
habilitado.
Funcionamento
A habilitao ou no da leitora Contactless feita de forma automtica, conforme tpicos
descritos acima. No necessria nehuma configurao no SCOPE.
Quando ocorre erro na leitura sem contato, dependendo do tipo de erro ocorrido, a prxima
tentativa pode desabilitar a leitura sem contato, de forma a evitar que o PINPAd leia novamente
por aproximao quando na verdade, o portador do carto deveria inserir o chip ou passar a tarja.
A leitura sem contato tambm desabilitada automaticamente pelo PINPad quando o valor da
trasao for acima do limite permitido para Contactless.
Existem dois tipos de carto sem contato: Chip EMV Sem Contato e Tarja Sem Contato.
Transaes de Tarja Sem Contato so equivalentes a uma transao Magntica.
Transaes de Chip EMV Sem Contato so equivalentes a uma transao de Chip EMV.
190
A leitura Sem Contato feita de forma nica, ou seja, somente necessrio aproximar o carto
do PINPad uma nica vez, mesmo quando se tratar do tipo Chip EMV Sem Contato.
191
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
Hexa
Decimal
decimal
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
64523
64524
64525
64526
64527
64528
64529
64530
64531
64532
64533
64534
64535
64536
64537
64538
64539
64540
64541
64542
64543
64544
64545
64546
Significado
Coletar 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 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 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 a forma de entrada
Coletar conta corrente
Coletar ltimos dgitos do carto
Coletar se deseja consultar parcelas
Imprime consulta
Coletar deciso de continuar
Coletar decide ltimo
Coletar nmero de cheque CDC
Coletar quantidade de dias
Coletar o nmero da pr-autorizao
Coletar dia do ms fechado
Imprime nota promissria
192
Cdigos Retorno
Hexa
Decimal
decimal
0xFC23
64547
0xFC24
64548
0xFC25
64549
0xFC26
64550
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
Significado
Coletar CEP
Coletar parte numrica do complemento
Coletar plano de pagamento (Fininvest)
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 dgito verificador do telefone
Coleta data (formato DDMMAA)
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
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
193
Cdigos Retorno
Hexa
Decimal
decimal
0xFC60
64608
0xFC61
64609
0xFC62
64610
0xFC63
64611
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
0xFC90
0xFC91
0xFC92
0xFC93
0xFC94
0xFC95
64656
64657
64658
64659
64660
64661
Significado
Coleta se continua aps verificar a conta
Coleta o cdigo da bandeira
Coleta se conta da fatura
Coleta o valor total
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
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 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 o DDD no PINPad
Coleta o nmero de telefone no PINPad
Coleta o nmero de telefone com o dgito verificador no PINPad
Coleta a redigitao da recarga no PINPad
Transao aprovada parcial
Coleta o valor das parcelas
194
Cdigos Retorno
Hexa
Decimal
decimal
0xFC96
64662
0xFC97
64663
0xFC98
64664
0xFC99
64665
0xFC9A
64666
0xFC9B
64667
0xFC9C
0xFC9D
64668
64669
0xFC9E
0xFC9F
0xFCA1
0xFCA2
0xFCA3
0xFCA4
0xFCA5
0xFCA6
0xFCA7
0xFCA8
0xFCA9
0xFCAA
0xFCAB
0XFCAC
0XFCAD
0XFCAE
0xFCAF
0xFCB0
0xFCB1
0xFCB2
0xFCB3
0xFCB4
0xFCB5
0xFCB6
0xFCB7
0xFCB8
64670
64671
64673
64674
64675
64676
64677
64678
64679
64680
64681
64682
64683
64684
64685
64686
64687
64688
64689
64690
64691
64692
64693
64694
64695
64696
0xFCB9
0xFCBA
0xFCBB
0xFCBC
0xFCBD
0xFCBE
0XFCC1
64697
64698
64699
64700
64701
64702
64705
0xFCC6
0xFCCA
0xFCCB
0xFCCC
0xFCCD
0xFCD4
0xFCD5
0xFCD6
0xFCD7
64710
64714
64715
64716
64717
64724
64725
64726
64727
Significado
Coleta se a primeira parcela para 30 ou 60 dias
Uso interno do SCOPE e no retornado para a aplicao
Coleta o Nmero do Carto (para a TEF Externa)
Coleta o cdigo de servio do posto (transao de convnio combustvel
Banrisul).
Coleta a matrcula (transao de convnio combustvel Banrisul)
Coleta a quantidade do servio (transao de convnio combustvel
Banrisul)
Coleta o hodmetro (transao de convnio combustvel Banrisul)
Coleta a placa do veculo (transao de convnio combustvel Banrisul)
Coleta o nmero do resgate de prmio
Opo de resgate de prmio selecionada
Solicitao a confirmao do resgate
Coleta o nmero do resgate prmio
Decide entre DARF e GPS
Decide entre DARF Preto e Simples
Coleta o cdigo de receita
Coleta o nmero de referncia
Coleta o valor juros
Coleta o CPF do portador
Coleta o CNPJ
Coleta o percentual
Coleta competncia
Coleta o nmero identificador
Coleta o valor INSS
Coleta a receita bruta
Coleta a opo do operador para continuar, alterar ou cancelar
Coleta o valor de acrscimo
Coleta o valor de deduo
Coleta redigitao do DDD
Coleta os 8 primeiros dgitos do carto no Pin Pad
Coleta os 8 dgitos finais do carto no Pin Pad
Coleta tipo da consulta (transao de Consulta Saldo Credito Infocards,
sendo: 1=Saldo, 2=Dados Cadastrais)
Confirma o nmero do carto digitado no Pin Pad
Coleta validao do saque
Coleta saque em andamento
Coleta DDD + Telefone no PIN Pad
Redigita DDD + Telefone no PIN Pad
Coleta dados ECF
Coleta opo de pagamento de carn para GetnetLAC no servio de
dbito a vista para bandeira ELECTRON (0=No para pagamento de
carn, 1=Sim para pagamento de carn).
Coletar dados carto presente
Coleta da Lista de Mercadorias Consumidas
Coleta de Hormetro
Coleta de Carto Magntico
Coleta de Segmento de Mercado
Coleta de Cdigo de Fornecedor de Produto ou Servio
Coleta de Cdigo de Produto, Cdigo de Servio ou Cdigo EAN
Coleta de Quantidade
195
Cdigos Retorno
Hexa
Decimal
decimal
0xFCD8
64728
0xFCD9
64729
0xFCDA
64730
0xFCFC
64764
0xFCFD
64765
0xFCFE
64766
0xFCFF
64767
Significado
Coleta de Confirmao de Cliente Preferencial
Coleta Ramo Principal Cielo Auto
Coleta Codigo de Mercadoria Cielo Auto
Coleta carto em andamento
Coleta em andamento
Autorizadoras
Abaixo se encontram relacionados os cdigos devolvidos pelas redes autorizadoras na
mensagem 0210 e entregue para a aplicao atravs da funo ScopeStatus().
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
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 frequncia 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
196
Cdigos Retorno
Hexadeci Decimal
mal
0x005A
90
0x005B
91
0x0100
256
0x0101
0x0102
0x0103
0x0104
0x0105
0x0106
0x0107
257
258
259
260
261
262
263
Significado
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
Informao de transao aprovada com prmio
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.
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
65032
Significado
Parmetro 1 invlido
Parmetro 2 invlido
Parmetro 3 invlido
Parmetro 4 invlido
Parmetro 5 invlido
Erro na montagem do servio pela API
Erro ao montar mensagem
Erro no arquivo de controle da TEF
Erro no contexto do arquivo de TEF (no mais utilizado)
Erro no arquivo de controle utilizado finalizao no ciclo multi-TEF
No salvou a mensagem de confirmao para o SAB
No salvou a mensagem de desfazimento para o SAB
SCOPE API j foi inicializada corretamente
Existe transao suspensa
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
197
Cdigos Retorno
Hexadeci Decimal
mal
0xFE09
65033
0xFE0A
65034
0xFE0B
65035
0xFE0C
65036
0xFE0D
0xFF00
65037
65280
0xFF01
0xFF02
65281
65282
0xFF03
0xFF04
0xFF05
0xFF06
0xFF07
0xFF08
0xFF09
0xFF0A
0xFF0B
0xFF0C
0xFF0D
0xFF0E
0xFF0F
0xFF10
0xFF11
0xFF12
65283
65284
65285
65286
65287
65288
65289
65290
65291
65292
65293
65294
65295
65296
65297
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
65310
65311
65312
65313
65314
65315
65316
65317
65318
65319
Significado
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.
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
Transao abortada pelo aplicativo
Handle invlido (ver Obtendo handle)
Taxa de servio invlida
Taxa de servio excede limite
Dado invlido
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
198
Cdigos Retorno
Hexadeci Decimal
mal
0xFF28
65320
0xFF29
65321
0xFF2A
65322
0xFF2B
65323
0xFF2C
65324
0xFF2D
65325
0xFF2E
65326
0xFF30
65328
0xFF31
65329
0xFF32
65330
0xFF33
65331
0xFF34
65332
0xFF35
65333
0xFF36
65334
0xFF37
65335
0xFF38
0xFF39
0xFF3A
0xFF3B
0xFF3C
0xFF3D
0xFF3E
0xFF3F
0xFF40
0xFF41
0xFF42
0xFF43
0xFF44
0xFF45
0xFF46
0xFF47
0xFF48
0xFF49
0xFF50
0xFF51
0xFF52
0xFF53
0xFF54
0xFF55
65336
65337
65338
65339
65340
65341
65342
65343
65344
65345
65346
65347
65348
65349
65350
65351
65352
65353
65360
65361
65362
65363
65364
65365
0xFF56
65366
0xFF57
65367
0xFF58
0xFF59
0xFF5A
0xFF5B
65368
65369
65370
65371
0xFF5C
65372
0xFF5D
0xFF5E
65373
65374
Significado
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
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)
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 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
199
Cdigos Retorno
Hexadeci Decimal
mal
0xFF5F
65375
0xFF60
65376
0xFF61
65377
0xFF62
65378
0xFF63
65379
0xFF64
65380
0xFF65
65381
0xFF66
65382
0xFF67
65383
0xFF68
65384
0xFF69
65385
0xFF6A
65386
0xFF6B
65387
0xFF6F
0xFFFF
-
65391
65535
-5000
-5001
-5002
-5003
-5004
-5005
Significado
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
Transao permite somente digitado
No Encontrado (para quando no veio menu dinmico na carga de
tabelas).
Erro ao acessar arquivo de contexto da PBM.
Erro genrico
Erro desmontando o pacote recebido
No achou a Master Key referente
Ocorreu timeout do pacote
Erro configurando o registrador
Parmetro lib incorreto
Erro Leitura Cartao/Trilha
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
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
Significado
Operao OK
Operao em processamento
Pressionada a tecla de funo #1
Pressionada a tecla Limpar/Clear
Parmetro invlido
Time-out esgotado o tempo de resposta
Operao cancelada
PIN-Pad j 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)
200
Cdigos Retorno
Hexadeci Decimal
mal
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
0x0047
71
0x0048
72
0x0049
73
0x004A
0x004B
0x004C
74
75
76
0x0050
80
Significado
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.
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).
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.
Carto ainda no efetivo (data de ativao posterior atual)
Moeda invlida (carto moedeiro)
Erro de alto nvel no carto EMV que passvel de
fallback para tarja magntica.
Mais de um carto sem contato foi apresentado ao leitor (este cdigo
de retorno opcional e depende da capacidade do equipamento em
detectar esta situao).
201
Cdigos Retorno
Hexadeci Decimal
mal
0x0051
81
0x0052
0x0053
82
83
0x0054
84
0x0055
85
0x00C8
0x00C9
0x00CA
0x00CB
0x00CC
0x00CD
0x00CE
0x00CF
0x00D0
0x00D1
0x00D2
0x00D3
0x00D4
0x00D5
0x00D6
0X00D7
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
Significado
Erro de comunicao entre o terminal (antena) e o carto com chip
sem contato.
Carto foi invalidado (seleo de aplicao retornou status 6A81).
Carto com problemas. Esse status vlido para muitas ocorrncias
no processamento de cartes sem contato em que o carto no se
comporta conforme o esperado e a transao deve ser finalizada.
Carto sem nenhuma aplicao disponvel para as condies pedidas
(nenhum AID encontrado).
A aplicao selecionada no pode ser utilizada (o Get Processing
Options retornou status 6985 ou houve erro no comando Select
final), e no h outra aplicao compatvel na lista de candidatas.
Transao negada na funo PP_GoOnChip()
Transao negada na funo 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 o Estado de coleta no PIN-Pad
Dado no chip no encontrado
Comanda Vazia
Comanda Invlida
Cdigos de Retorno de Pr-TEF

Os cdigos abaixo podem ser retornados pelo ScopeSRV ao ScopeAPI quando ocorre erro em
uma Pr-TEF. Embora sejam erros internos ao SCOPE podem ser teis para identificar e ajudar
na anlise de logs para identificao de problemas:
Cdigo de Retorno
Descrio
(Decimal)
00
Sucesso
01
Rede Offline
02
Erro na consulta ao BD
03
Timeout na consulta ao BD
04
BD no conectado
05
Transao no localizada no BD
06
BIN ou Servio no configurado
07
PDV j logado
08
PDV no cadastrado
09
Taxa de servio invlida
202
10
Taxa de servio excede limite
11
Digitao no permitida
12
Protocolo no suportado
13
No h PDVs disponveis
14
Protocolo incompatvel
15
Inserir carto chip
16
BIN ou servio no configurado pela rede adquirente
17
Conta no permitida
18
Servio invertido (Crdito por Dbito ou vice-versa)
19
Identificao de PDV inconsistente (recebeu um buffer invlido)
20
Erro na leitura do carto
21
Dados no encontrados
22
Rede invlida ou no suportada pelo PINPad desse PDV
23
Dados de recarga no encontrados
24
Verso do BD incompatvel
25
Chip no habilitado pela rede
26
Servio no permitido para chip
27
Chip sem dados adicionais (pode indicar falha na carga de tabelas)
28
Carto com Service Code invlido
29
Rede exige uso de PINPad compartilhado
30
PINPad compartilhado no opera com rede VISANET 2000.01
31
Estorno fora do prazo permitido
32
Estorno parcial no permitido (valor deve ser o total)
33
Estorno excede valor mximo permitido
34
Estorno com valor acima do total original no permitido
35
Estorno com valor acima do total original excede limite permitido
36
Estorno com valor zerado no permitido
37
Estorno com valor original zerado no permitido
38
Estorno j realizado
39
Cupom no encontrado
40
Prompts Adicionais no encontrados (pode indicar falha na carga de

tabelas)
41
Contrato suspenso
42
Carto invlido
43
Modo invlido
44
Leitor inativo
45
Erro nas chaves de criptografia
46
Erro na parametrizao de trilhas da rede REDE (pode indicar falha

na inicializao de tabelas)
203
47
Erro na leitura da tarja do carto (Trilhas inconsistentes ou fora do

padro. Pode indicar falha de leitura, carto corrompido ou fraudado)
48
Falha na configurao da confirmao positiva da rede adquirente

GetNetLac
49
Transao por celular no habilitada no contrato
50
Transao por celular exige que a rede habilite transao digitada
51
A rede est em processo de inicializao. Tente novamente.
52
PINPad no suportado em modo Multi-Bandeira Estendido
53
No representa erro. Uso interno em modo Multi-Bandeira

Estendido.
54
Erro de leitura. PAN excede tamanho mximo.
55
Erro de leitura. Trilha1 excede tamanho mximo.
56
Erro de leitura. Trilha2 excede tamanho mximo.
57
Contactless no habilitado na carga de tabelas
58
Chip Contactless sem dados adicionais (pode indicar falha na carga

de tabelas)
59
Contactless sem produto habilitado na carga de tabelas
60
Excede valor limite definido para Contactless
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
204
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
da estrutura stPARAM_COLETA, aps a chamada funo ScopeGetParam(). O valor deste
campo a combinao binria (bitwise) de:
Cdigos Formato
Significado
Hexadeci Decimal
mal
0x0001
01
Tecla cancela habilitada
0x0002
02
Tecla prximo habilitada
0x0004
04
Tecla retorna habilitada
Ele dever ser verificado a cada iterao, logo aps a chamada funo (ver Obtendo os
parmetros da transao)
Cdigos de Fluxo
Num determinado momento, coletado o dado ou no, a aplicao dever informar ao SCOPE qual
ao que ele dever tomar (ver Passando o dado da coleta ao SCOPE Client). Esta ao est
associada s opes que o usurio pode tomar: avanar para o prximo estado, retornar para o
estado anterior ou cancelar a transao. Cada ao tem um cdigo amarrado a ela que se
encontra na tabela que segue.
Cdigos Formato
Hexadeci Decimal
mal
0x0000
00
0x0001
01
0x0002
02
0x0003
03
Significado
Prximo estado
Estado anterior
Cancelar
Erro na coleta de dados
Estados para interrupo

Na tabela abaixo esto relacionados os cdigos referentes aos estados de coleta, nos quais o
SCOPE poder ser suspenso (ver Suspendendo a transao).
ndice
0
1
2
3
Exit Point
Coleta do carto
Coleta da data de validade do carto
Montagem e envio da mensagem
Exibio de mensagens de no autorizao
205
4
5
6
7
8
9
10
11
12
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
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
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
206
65
66
67
68
69
70
71
72
73
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
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
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
207
125
126
127
128
129
130
131
132
133
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
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
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
208
183
184
185
186
187
188
189
190
191
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
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
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
209
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
314
315
316
317
318
319
320
Coleta NSU da transao original

Exibe dados de cancelamento
Decide as vias de reimpresso
Exibe mensagem rotativa
Coleta do DDD no PINPad
Coleta do nmero do telefone no PINPad
Coleta do nmero do telefone e dgito verificador no PINPad
Coleta de redigitao no PINPad
Transao aprovada parcial
Coleta valor das parcelas
Coleta 30 ou 60 dias para a cobrana da primeira parcela
Verifica se CDC ou Parcele Mais
Coleta se vista com juros
Transao cancelada por fallback invlido
Coleta a utilizao do saldo restante do carto voucher
Critica o valor na transao de Troco Surpresa
Consulta para transao de Vale-Gs
Verifica se deve coletar o cdigo de ativao do celular
Coleta o cdigo de ativao do celular
TEF Externa: Coleta Nmero do Carto
Coleta cdigo de servio do posto
Coleta matrcula
Coleta a quantidade do servio do posto prestado
Coleta hodmetro do veculo
Coleta a placa do veculo
Coleta o valor de deduo
Coleta o valor de acrscimo
Crtica o valor da transao
Mostra o valor
Mostra o vencimento
Coleta o valor para o Bradesco
Decide entre DARF e GPS
Decide o tipo de DARF
Coleta o cdigo de receita
Coleta o nmero de referncia
Coleta o valor juros
Coleta o CPF do portador
Exibe a mensagem de erro de valor do Bradesco
Coleta o CNPJ
Coleta o percentual
Coleta o ms de competncia do GPS
Coleta o nmero do identificador
Coleta o valor de INSS
Coleta a receita bruta
Coleta a opo do operador, para confirmar, alterar e cancelar.
Coleta o valor do saque no PIN-pad
Scope valida o valor do saque
Automao valida o valor do saque
Confirma valor do saque no PIN-pad
Saque PIN-pad em andamento
Coleta DDD + Nmero de Telefone no PIN Pad
Redigita DDD + Nmero de Telefone no PIN Pad
Coleta dados ECF
Verifica se o carto Ticket Car benefcio ou gesto de frotas
Verifica se h transao off-line gravada no chip do carto Ticket Car
Monta a transao off-line gravada no chip do carto Ticket Car
Apaga a transao off-line gravada no chip do carto Ticket Car
210
339
340
357
358
359
360
361
362
363
364
365
366
368
369
370
371
372
373
374
Verifica se dbito a vista ou pagamento de carn para GetnetLAC.

Coleta dados carto presente
Coleta da Lista de Mercadorias Consumidas
Decide se deve ser coletada Lista de Mercadorias
Decide se devem ser coletados Dados do Veculo
Decide se devem ser coletados Dados do Motorista
Decide se deve ser coletado Hodmetro do Veculo
Decide se deve ser coletado Hormetro do Veculo
Coleta Hormetro do Veculo
Decide se deve ser coletada a Placa do Veculo
Coleta de Carto Magntico
Coleta de Segmento (SAV)
Coleta de Fornecedor (SAV)
Coleta de Produto/ Servio/ Cdigo EAN (SAV)
Coleta de Quantidade
Recupera Dados
Coleta de Cliente Preferencial
Exibe Mensagem
Cdigo das redes

Abaixo se encontram as redes suportadas pelo SCOPE e seus respectivos cdigos.
Cdigos Rede
Decimal
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
Significado
SCOPE
Tecban
Ita
Visanet especificao 2000.01
Bradesco
Redecard
Fininvest
Serasa
Teledata
Banrisul
Ticket
Associao Comercial de So Paulo - ACSP
BrasilCard (Antiga CNS)
Sysdata
Redecard especificao L0102
Visanet especificao 1998.10
CBD
Lojista
CSU
Parati
Bem
Tokor
MaxiCred
Zogbi
ACC Card
Sorocred
Coopercred
Telesp
Policard
Via Varejo
Cdigo SAT
Decimal
999
31
999
999
999
25
999
999
999
999
32
999
999
999
25
999
999
999
999
999
999
999
999
999
999
30
999
999
23
999
211
Cdigos Rede
Decimal
30
31
32
33
34
35
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
74
75
76
77
78
79
80
81
82
83
84
85
Significado
SAB
E-Pharma
Vidalink
PrevSade
Hipercard
Interchange
Tecban especificao 2.0
Nutricash
Losango
GoodCard
Cetelem
Bnus
American Express (AMEX) especificao 01
Banco do Brasil GCB
Sonae
Incomm (reutilizao do cdigo da rede BankBoston)
Portal Card
Valecard
Telenet
Evanglico
Funcional Card
Ediguay
CheckCheck
Banktec
Big
Big Card
SuperCard
Banese
TR Centre
TRN Card
Infocards
Valecash
Premium
CredSystem
Redecard especificao L02.05
E-Capture
Check Express
Conductor
ChequePre
Visanet 4.1
American Express especificao 03.00
ECX Card
Ultragaz
GetNet
CentralCard
Orbitall
Recarga de Celular especificao Itautec
IBI
DATASUS
Comprocard
Framaseg
Intellisys
Somar
Solucard
Obo
Da Casa
Cdigo SAT
Decimal
999
999
999
999
19
999
31
999
999
999
11
999
3
999
999
999
999
999
999
999
18
999
999
999
999
8
999
999
999
999
999
999
999
999
25
999
999
999
999
999
3
14
999
999
999
999
999
999
999
999
999
999
999
999
999
999
212
Cdigos Rede
Decimal
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
102
103
104
105
109
112
113
114
116
117
118
121
123
124
125
126
127
128
129
133
134
Significado
Valeshop
Fidelize
UtilCard
RV Tec
GW Cel
U-Paid
Redecard especificao L0401
Banpar
Neus
CredShop
Banco HSBC
Banco do Brasil ISO-GCB
Pharma Link
Banrisul EMV
Banestes
Cielo
Redecard especificao L05.00
Diamante
RedeSoftnex
Usecred
DMCARD
Siscred
Epay
Orgcard
SAVS
TENDENCIA
RVTECNOLOGIA
GIVEX
CREDITEM
FOXWIN
BIN
TOPCARD
ELAVON
VR
PBM PADRAO
CONDUCTOR-PL especificao V02.05
Cdigo SAT
Decimal
999
999
999
999
999
999
25
999
999
999
999
999
999
999
999
12
25
999
999
999
999
999
999
999
999
999
999
999
999
999
999
999
999
31
999
999
213
Cdigo de especificao das redes

Abaixo se encontram as redes que possuem mais que uma especificao suportada pelo SCOPE.
Cdigo
Rede
13
66
73
77
89
90
91
102
103
118
Cdigo
Especificao
1
2
1
2
1
2
1
2
2
1
2
1
2
0
1
1
2
3
1
2
Significado
SYSDATA
CHECKEXPRESS
GETNET-6.0
IBI
RVTEC
GWCEL
UPAID
CIELO
REDECARD
TENDENCIA
V1.XX
V2.00
V1.XX
V2.00
V01.00
V02.00
V1.XX
XSAB 1.28a
V2.00
V0003
V0005
V1.XX
V2.00
4.1.0
4.1R2014
V5.00
V5.01
V5.02
V1.XX
V2.00
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
Significado
SCOPE
Visa
Mastercard
Amex
Lojista
Dinners
Sollo
Cheque Eletrnico
Mastercard Maestro (conhecido tambm como Redeshop)
Ita
214
Cdigos Bandeira
Hexadeci Decimal
mal
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
0x0026
0x0027
0x0028
0x0029
0x002A
0x002B
0x002C
0x002D
0x002E
0x002F
023
024
025
026
027
028
029
030
031
032
033
034
035
036
037
038
039
040
041
042
043
044
045
046
047
0x0030
0x0031
0x0032
0x0033
0x0034
0x0035
0x0036
0x0037
0x0038
0x0039
0x003A
0x003B
0x003C
0x003D
0x003E
048
049
050
051
052
053
054
055
056
057
058
059
060
061
062
Significado
Bradesco
Fidelidade
Serasa
Telecheque
Sodexo Alimentacao
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
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
215
Cdigos Bandeira
Hexadeci Decimal
mal
0x003F
063
0x0040
064
0x0041
065
0x0042
066
0x0043
067
0x0044
068
0x0045
069
0x0046
070
0x0047
071
0x0048
072
0x0049
073
0x004A
074
0x004B
075
0x004C
076
0x004D
077
0x004E
078
0x004F
079
0x0050
080
0x0051
081
0x0052
082
0x0053
083
0x0054
084
0x0055
085
0x0056
086
0x0057
087
0x0058
088
0x0059
089
0x005A
090
0x005B
091
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
Significado
Correspondente bancrio Banco do Brasil
Colaborador (carto de crdito do SONAE)
Incomm (reutilizao do cdigo da bandeira CB-BankBoston)
Portal Card
Vale Card
Personal Card
Green Card (no mais utilizada)
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
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
Cielo
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
216
Cdigos Bandeira
Hexadeci Decimal
mal
0x0076
118
0x0077
119
0x0078
120
0x0079
121
0x007A
122
0x007B
123
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
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
0x00A1
161
0x00A2
162
0x00A3
163
0x00A4
164
0x00A5
165
0x00A6
166
0x00A7
167
0x00A8
168
0x00A9
169
0x00AA
170
0x00AB
171
0x00AC
172
Significado
Verde Card
Rossi
Somar
Solucard
Banquet Smart
VEGAS CARD SENHA
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)
RedeSoftnex Com senha
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
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
BANCRED SENHA
Credi-Shop
Sapore
CB-HSBC
Verocheque
Getnet
Pharmalink PBM
Aura FNAC
Aura BERGAMAIS
Com Voc
BANESCARD
Nokia
217
Cdigos Bandeira
Hexadeci Decimal
mal
0x00AD
173
0x00B0
176
0x00B1
177
0x00B2
178
0x00B3
179
0x00B4
180
0x00B5
181
0x00B6
182
0x00B7
183
0x00B9
185
0x00BA
186
0x00BB
187
0x00BC
188
0x00BD
189
0x00BE
190
0x00BF
191
0x00C0
192
0x00C2
194
0x00C3
195
0x00C4
196
0x00C7
199
0x00C8
200
0x00C9
201
0x00CA
202
0x00CB
203
0x00CC
204
0x00CF
207
0x00D0
208
0x00D1
209
0x00D2
210
0x00D3
211
0x00D4
212
0x00D5
213
0x00D6
214
0x00D7
215
0x00D8
216
0x00D9
217
0x00DA
218
0x00DB
219
0x00DC
220
0x00DD
221
0x00E0
224
0x00E1
225
0x00E2
226
0x00E4
228
0x00E5
229
0x00E6
230
0x00E9
233
0X00F1
241
0x00F2
242
0x00F4
244
0x00F5
245
0x00F8
248
0x00FA
250
0x00FB
251
Significado
Fala Fcil (Nexus)
BRASIL CONVENIOS
AMCARD
Rede MED
GPA
PAT sem senha
PAT com senha
FAN CARD
BANRICOMPRAS
Banrisul - Refeisul Alimentao / Refeio
Banrisul - Refeisul Combustvel
TIM ON-LINE
BNB Clube
NEUS Senha
Diamante
MinasCred
Nutricash
ELO Debito
ELO Credito
Goodcard Senha
USECRED sem senha
USECRED com senha
SOROCRED Crdito
SICREDI Crdito
SICREDI Dbito
BrasilCard com senha
PL GETNET VISA
DMCARD
PLANVALE com senha
SISCRED sem senha
SISCRED com senha
DMCARD com senha
RedeSoftnex Convnio
RedeSoftnex
Claro Off-line
Oi Fixa
Oi Off-line
Vivo off-line
Telesp Super 15
Embratel Livre Online
Epay
Orgcard dbito
Orgcard crdito
Orgcard crdito DV,CS
Ticket Car
PL GETNET MASTER
SAVS
POLICARD SENHA
GIVEX
CREDITEM SENHA
MURY
ABRAPETITE
Sodexo Refeicao
TOPCARD com senha
TOPCARD sem senha
218
Cdigos Bandeira
Hexadeci Decimal
mal
0x00FC
252
0x00FD
253
0x00FE
254
0x00FF
255
0x0100
256
0x0101
257
0x0102
258
0x0103
259
0x0104
260
0x0105
261
0x0106
262
0x0107
263
0x0108
264
0x0109
265
0x010A
266
0x010B
267
0x010C
268
0x010D
269
0x0112
274
0x0116
278
0x0125
293
0x0126
294
Significado
Elavon
VR ALIMENTACAO
VR AUTO
VR CULTURA
VR REFEICAO
MULTIBENEFICIO
MULTIALIMENTACAO BEN
MULTICESTABASICA
CARTAO MAMAE
MULTICASH
CARTAO BRINQUEDO
CARTAO NATAL
MULTICHEQUE BEN
MULTIEMPRESARIAL
MULTICOMBUSTIVEL
MULTICULTURA
MULTIFARMA
MULTIREFEICAO
FORTBRASIL
ELO AUTO
BAHAMAS CRDITO
BAHAMAS ALIMENTAO
Dados disponveis das transaes

Abaixo est a relao dos campos disponveis que podem ser obtidos das transaes pelas
funes ScopeObtemCampoExt() e ScopeObtemCampoExt2().
Mscara 1
CAMPO DE DADOS
PAN Personal Account Number (nmero do carto)
Valor da transao
NSU (Nmero Sequencial 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
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
219
Mscara 2
Mscara 3
Nome da bandeira
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
Logo do PAN
Cdigo da Empresa
Cdigo de Autenticao
Dados do pagamento
UsoRes_63
Nmero do PDV
Informaes sobre a quantidade e os e-cupons disponveis ao
cliente
Informao do desconto do resgate monetrio
Informaes sobre a coleta de dados realizada na transao
(BIT 48).
Modo de Entrada (Entry Mode)
Valor do Saque
Resposta da consulta Infocards (bit 62 da 0110)
0x00800000
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
0x04000000
0x08000000
0x10000000
0x20000000
0x40000000
0x80000000
0x00000001
0x00000002
0x00000004
0x00000008
0x00000010
0x00000020
220
Dados da resposta de Consulta da EPAY. Os dados

retornados consistem em 3 valores de concatenados:
1. Valor Mnimo ( 12 dgitos )
2. Valor Mximo ( 12 dgitos )
3. Saldo Disponvel ( 12 dgitos )
0x00000040
Maximo de mercadorias permitidas para uma transacao

TicketCar
O dado retornado um campo de 2 digitos.
Cdigo SAT (ver cdigos em Cdigo das redes)
Verso corrente de Carga de Tabelas do Host Formato: 10
dgitos (Preenchido com zeros a esquerda, caso necessrio).
Disponvel em transaes com as seguintes Redes:
SAVS
CNPJ da rede credenciadora - SAT
0x00000100
0x00000200
0x00000400
0x00002000
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
0x0013
019
0x0014
020
0x0017
023
Significado
Carto de dbito
Carto de crdito
Consulta a cheques
Controle SCOPE/Autorizador
Controle API/Server
PAT
CDC
Garantia de desconto de cheques
Resumo de vendas
IATA para companhias areas
Fidelidade
Recarga de celular
Transao financeira
Investimento
Medicamento
Pagamento de conta
Tcnico
Administrativo
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
Descrio
Compra com carto de dbito vista
Compra com carto de crdito vista
Pr-Autorizao com carto de crdito
Consulta de cheques a vista
221
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
076
077
078
079
080
081
082
083
084
085
086
087
088
089
090
091
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
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
222
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
121
122
123
124
125
126
127
128
133
134
136
142
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)
Consulta Resgate de Prmios
Pagamento de DARF
Pagamento de GPS
Injeo de chaves
Dbito parcelado pela administradora
Envio de off-line
Atualizao de chip
Autorizao de Voucher
Simulao Credirio
Credirio
Atualizao de preos
Cancelamento de Autorizao de Voucher
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
0x0009
0009
Significado
E-Pharma
Vidalink
PrevSaude
Funcional Card
GoodCard
Novartis
FlexMed
DataSUS
FarmaSeg
223
Cdigos do Convnio
Hexadeci
Decimal
mal
0x000A
0010
0x000B
0011
Significado
Pharmalink
PBM Padro
224
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 PIN-Pads tero seu firmware atualizado. Os PIN-Pads atualizados
so denominados PIN-Pads compartilhados. Este novo firmware compatvel com as verses
atuais, ou seja, tambm suporta as funes antigas de acesso ao PIN-Pads 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 PIN-Pads compartilhado, o acesso ao
PIN-Pads 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
225
pagamento da despesa. Atualmente somente hotis e locadoras so autorizados para

utilizao da Pr-Autorizao.
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.
226
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.
227
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.
SCOPE
tambm
disponibilizar
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.
228
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
229
SCOPEJAVA.JAR
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
230
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 11, simples.
Basta clicar no PDV cuja verso do SCOPE Client deseja-se consultar, e clicar no boto PDV:
<empresa>/<filial>/<PDV>.
Figura 11: janela principal do servidor SCOPE

A janela similar a da Figura 12 ser apresentada. Alm de outras informaes, nela est a verso
do SCOPE Client representado no campo ScopeAPI (neste exemplo vemos 2.27.02.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.
231
Figura 12: 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 13. No campo Verso do
arquivo: encontra-se a verso do SCOPE Client (no exemplo vemos 2.27.2.1, que a mesma
do exemplo da sesso anterior).
232
Figura 13: 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.
233
Um exemplo da sada gerada por esse comando est na Figura 14. No exemplo, apresentada a
verso 2.25.07.01.
Figura 14: visualizando a verso do SCOPE Client na linha de comando do Linux
234
Apndice F Formato do Cdigo de Barras InComm

_____________________________________________________________________________________________________
Este apndice tem como objetivo documentar o formato do cdigo de barras da bandeira
InComm.
O nmero do carto para identificao da bandeira InComm pelo SCOPE pode ser obtido por
meio de carto magntico ou por cdigo de barras.
O leitura e o tratamento do cdigo de barras da InComm ser realizado pela automao
comercial, a qual enviar o nmero do PAN j formatado para o SCOPE. O layout do cdigo de
barras possui, sequencialmente, 11 dgitos refententes ao cdigo do produto e 19 dgitos
referentes ao nmero do carto (PAN), o qual deve ser justificado direita e preenchido com
zeros esquerda se for menor que 19 dgitos,como podemos observar na figura 12.
Figura 15: leiaute do cdigo de barras da InComm

Aps o cdigo de barras ser lido e tratado pela automao, o PAN formatado ser enviado para o
SCOPE que ir entender o modo de entrada como carto digitado.
235
Apndice G - 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
empresa
transaes
que
TEF
concentra
de
diversos
estabelecimentos, e as autoriza atravs de um sistema

autorizador. Exemplos: Visanet, Redecard, TecBan.
dgitos do carto.
E
S
236
SCOPE:
SCOPE
soluo
Itautec
para
pagamentos eletrnicos
ScopeCNF (SCOPE Configurador):
carto de crdito vista, compra com carto de crdito

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

base de dados com as respectivas redes, garantindo
tambm o fluxo de transaes com estas redes
Servio: o termo servio no contexto do SCOPE define
TSR: abreviao do termo em ingls Terminate and
o objetivo de uma transao. Exemplos: compra com
Stay Resident. Veja Mdulo residente.
237
2014
Este documento de propriedade da OKI Brasil Indstria e Comrcio de Produtos e Tecnologia em Automao
S/A. Todos os direitos reservados.
As informaes aqui contidas tm carter tcnico/informativo e no podero ser copiadas, fotocopiadas, reproduzidas,
traduzidas ou reduzidas a qualquer meio eletrnico ou forma legvel por mquina sem a autorizao prvia da OKI
Brasil Indstria e Comrcio de Produtos e Tecnologia em Automao S/A.
Esta se reserva, por outro lado, o direito de alterar seu contedo e forma, sem qualquer aviso prvio.
Produzido no Brasil.
238

Manual Desenvolvedor

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Manual Desenvolvedor

Uploaded by

Copyright:

Available Formats

SCOPE

Leia antes de utilizar o software:

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

Equipe Desenv. SCOPE

Equipe Desenv. SCOPE

Incluso de tabela com cdigo das redes.

FacTI Tiago Valrio

sesso Funes diversas - obtendo os campos, incluso do

Paulo dos Santos

Atualizao da tabela de bandeiras.

Atualizao da tabela de bandeiras.

Atualizao da seo Configuraes gerais e Tratando

Paulo dos Santos

Paulo dos Santos

FacTI Daniel Alves

Atualizao da tabela de bandeiras.

Incluso da Rede Siscred / Bandeiras Siscred e Planvale.

FacTI Juliana Bersi

Atualizao da tabela de redes e bandeiras.

FacTI Rafael D. Tardivo

ScopeObtemCampoExt2 para uso em configuraes de

Nova coleta: TC_COLETA_TIPO_CONSULTA (0xFCB8)

FacTI Juliana Bersi

0xFCB7, 0xFCB9), para quando for solicitado o carto

Facti Felipe M. Schaden

Facti Tiago F. Valrio

Incluso dos estados de coleta 0xFCBA e 0xFCBB para o

Incluso do detalhamento sobre as configuraes de

Facti Rafael D. Tardivo

registro do SCOPE no WoW64

Facti Rafael D. Tardivo

Incluso da nova estrutura de Dados de Recarga de

Facti Felipe M. Schaden

Incluso da Bandeira POLICARD SENHA

Facti Felipe M. Schaden

Facti Tiago F. Valerio

Facti Tiago F. Valerio

Facti Felipe M. Schaden

Facti Rafael D. Tardivo

Facti Tiago F. Valerio

Facti Felipe M. Schaden

Incluso da bandeira ABRAPETITE

Acrscimo da seo ArqControlPath no scope.ini

Facti Camila M. Dutra

Facti - Felipe M. Schaden

Incluso da funo ScopeVersao

Incluso da rede e bandeira TOPCARD

Facti Juliana Bersi

Facti Felipe M. Schaden

Facti - Felipe M. Schaden

Facti Felipe M. Schaden

Facti Felipe M. Schaden

Facti Felipe M. Schaden

Incluso da mscara da funo ScopeObtemCampoExt2

Facti Felipe M. Schaden

Facti Felipe M. Schaden

Facti Felipe M. Schaden

Incluso de seo especifica para detalhamento da rede

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

Configurao do registro do MS-Windows ................................................................................................. 27

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

Funes de configurao de ambiente.......................................................................... 38

Funes especficas das interfaces ............................................................................... 41

Obtendo os parmetros da transao ...................................................................................................... 43