View
258
Download
9
Category
Preview:
DESCRIPTION
Manual Desenvolvedor
Citation preview
SCOPE
Manual do Desenvolvedor
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 2
Informaes Gerais
Leia antes de utilizar o software:
imprescindvel a leitura deste material para o correto procedimento de instalao, configurao e
administrao deste produto.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 3
Reviso Data Responsvel Histrico
1.0 13/04/2010 Equipe Desenv. SCOPE Verso Inicial.
1.1 30/04/2010 Equipe Desenv. SCOPE Reviso do texto e incluso de novos retornos e tipos de
dados.
1.2 01/07/2010 FacTI Vinicius
Peracini Incluso de tabela com cdigo das redes.
1.3 31/08/2010 Paulo dos Santos Incluso da mscara Logo_PAN (usada na
ScopeObtemCampoExt).
1.4 04/10/2010
FacTI Tiago Valrio
Frederico C. Goulart
Jailton da S. C. Santana
Incluso dos cdigos de retorno (coleta de dados), da
descrio do novo tipo de dado, incluso da nova funo na
- 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 Atualizao da tabela de bandeiras.
1.7 16/02/2011 Jailton da S. C. Santana
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
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 Atualizao da tabela de bandeiras.
1.9 18/03/2011 Paulo dos Santos Incluso das Mscaras DescResgateMonetario e
Tipo_Cartao para uso na funo ScopeObtemCampoExt2.
1.10 19/04/2011 FacTI Daniel Alves
Paraiso Atualizao da tabela de redes e bandeiras.
1.12 26/04/2011 FacTI Rafael D. Tardivo Incluso de Rede / Bandeira DMCARD em suas respectivas
tabelas.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 4
1.13 29/04/2011 FacTI Felipe M.
Schaden Incluso da Rede Siscred / Bandeiras Siscred e Planvale.
1.14 04/05/2011 FacTI Vinicius Peracini Atualizao da tabela de cdigos de erro.
1.15 11/05/2011 FacTI Felipe M.
Schaden Incluso da Bandeira DMCARD SENHA.
1.16 07/06/2011 FacTI Vinicius Peracini Atualizao da tabela de redes e bandeiras.
1.17 02/08/2011 FacTI Juliana Bersi
Atualizao da tabela de cdigos de erro com o erro
0xFF6B.
Incluso do prottipo das funes:
ScopeMenuSelecionaItem e ScopeMenuRecuperaItens.
1.18 09/08/2011 Frederico C. Goulart Atualizao da tabela de redes e bandeiras.
1.19 23/08/2011 FacTI Rafael D. Tardivo
Coleta/Confirmao do valor do saque pelo PIN-pad.
Incluso de ndices/mscaras nas funes
ScopeForneceCampo, ScopeSuspend, ScopeConfigura e
ScopeObtemCampoExt2 para uso em configuraes de
coleta/validao do saque.
configurvel por
chave no .INI ou REGISTRY.
1.20 12/09/2011 Marcelo Dionysio da
Fonseca
Consulta Crdito Infocards.
Nova coleta: TC_COLETA_TIPO_CONSULTA (0xFCB8)
Novo campo da Mascara 3 do ObtemCampo:
Resposta_Consulta_Infocards (0x00000020) 0x0000002
1.21 15/09/2011 FacTI Juliana Bersi
Incluso dos trs novos estados de coleta (0xFCB6,
0xFCB7, 0xFCB9), para quando for solicitado o carto
digitado no Pin Pad.
1.22 04/11/2011 Edison Ogata Incluso dos estados de coleta 0xFCBA e 0xFCBB para o
Troco Visa
1.23 29/11/2011 Douglas Sebastiani
Bucciolli
Incluso dos tpicos Plataformas Compatveis, Requisitos de HW e Requisitos de SW
Atualizao do glossrio.
1.24 5/01/2012 Facti Rafael D. Tardivo Incluso dos cdigos de coleta de Coleta DDD + Telefone no PIN Pad e Redigita DDD + Telefone no PIN Pad
1.25 20/01/2012
FacTI Srgio R. A.
Assuno
Jailton da S. C. Santana
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
1.26 05/03/2012 Facti Felipe M. Schaden
Facti Tiago F. Valrio
Alterao da bandeira PL-COSAN para PL GETNET
VISA.
Incluso da Bandeira PL GETNET MASTER.
1.27 23/03/2012 Edison Ogata Incluso da seo PINPAD no arquivo scope.ini
1.28 16/04/2012 Facti Tiago F. Valrio Incluso da rede TENDENCIA.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 5
1.29 26/04/2012 Facti Rafael D. Tardivo
Incluso do detalhamento sobre as configuraes de
registro do SCOPE no WoW64
1.30 11/05/2012 Facti Rafael D. Tardivo Incluso da nova estrutura de Dados de Recarga de
1.31 22/05/2012 Facti Felipe M. Schaden Incluso da Bandeira POLICARD SENHA
1.32 20/06/2012 Edison Ogata Incluso da funo ScopeVersao
1.33 21/06/2012 Facti Felipe M. Schaden Incluso da rede RVTECNOLOGIA.
1.34 03/07/2012 Edison Ogata Incluso da funo ScopeObtemDadosTotalTEFEx() e atualizao dos tipos de layouts que podem ser utilizados
por ela.
1.35 08/08/2012 Marcelo D. Fonseca Nova funo: Simulao Credirio;
Novos servios: Credirio e Simulao Credirio.
1.36 10/08/2012 Facti Tiago F. Valerio Incluso da funo adicional e nova lista de medicamentos na sesso sobre PBM.
Incluido novo cdigo na lista de cdigos de erro do Scope.
1.37 30/08/2012 Facti Tiago F. Valerio Incluso de novo estado de coleta de dados TC_DECIDE_PGTO_CARNE e estado para interrupo EC_DECIDE_PGTO_CARNE.
1.38 13/09/2012 Edison Ogata
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().
1.39 19/09/2012 Facti Felipe M. Schaden Incluso da rede CREDITEM e bandeira CREDITEM SENHA.
1.40 21/09/2012 Edison Ogata Atualizao das tabelas de redes e bandeiras.
1.41 15/10/2012 Facti Rafael D. Tardivo Incluso do ID para obteno dos valores retornados na resposta de consulta de saldo da EPAY na mscara 3 da funo ScopeObtemCampo
1.42 17/10/2012 Facti Tiago F. Valerio Incluso da rede GIVEX, bandeira GIVEX, atualizao das sesses Estados para interrupo e Coleta de dados.
1.43 03/01/2013 Edison Ogata
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.
1.44 04/01/2013 Facti Felipe M. Schaden Incluso da bandeira Sodexo Refeicao
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 Facti Henrique de O.
Buzachero Incluso da rede e bandeira TOPCARD
1.48 18/04/2013 Edison Ogata Incluso do parmetro MascararDados
1.49 07/05/2013 Facti Henrique de O.
Buzachero Incluso da rede VR e bandeiras da VR
1.50 25/06/2013 Facti Camila M. Dutra
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.
1.51 01/07/2013 Facti - Felipe M. Schaden Incluso da descrio de novas funcionalidades de Atualizao de Preos e Fornecimento de Lista de Mercadorias para a Ticket Car
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 6
1.52 01/07/2013 Regina M. N. Sato Incluso da mscara da funo ScopeObtemCampoExt2 para obteno do Maximo de Mercadorias permitidas para transao TicketCar.
1.53 06/08/2013 Facti Juliana Bersi Incluso da rede e bandeira ELAVON
1.54 11/10/2013 Facti Camila M. Dutra
Facti - Felipe M. Schaden Incluso das bandeiras Bancred Senha e Vegas Card Senha
1.55 14/10/2013 Facti Felipe M. Schaden Incluso da rede VR e das bandeiras VR e Multibeneficios
Descrio do ForneceCampo SCOPE_DADOS_APLIC_CBD
1.56 13/01/2014 Jovelina M. de Jesus
Incluso de rede e bandeira PharmaSystem; funes: Elegibilidade, Pr-Autorizao, Cancelamento de Pr-Autorizao; layouts de lista de medicamentos; funo para recuperao de lista de projetos.
1.57 11/02/2014 Jovelina M. de Jesus Incluso das rotinas de PIN-Pad para leitura e limpeza de comanda. Insero de dois cdigos de retorno de erro para PIN-Pad compartilhado.
1.58 21/03/14 Jailton da S. C. Santana Descrio da funcionalidade de transao POS
Incluso da configurao do scope.ini para a transao POS
1.59 25/03/2014 Edison Ogata Incluso da bandeira FORTBRASIL
1.60 02/06/2014 Facti Felipe M. Schaden
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.
1.61 04/07/2014 Facti-Camila M. Dutra
Incluso de cdigos de Convnio, Rede e Bandeira da PBM PADRO
respeito do funcionamento do layout 5
Atualizao da sesso "Lista de medicamentos Ex"
1.62 07/07/2014 Facti Felipe M. Schaden
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.
1.63 07/07/2014 Facti Felipe M. Schaden
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.
1.64 08/07/2014 Alcimar Joaquim
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.
1.65 14/07/2014 Alcimar Joaquim
Redes com tratamentos especficos
funcionalidades do Cielo Premia.
1.66 30/07/2014 Alcimar Joaquim
Incluso da funo ScopeObtemOperadorasRecCelOffTEF
Incluso da funo ScopeRecuperaValoresRecCelOffTEF
1.67 26/08/2014 Marcelo Dionysio da
Fonseca Incluso da rede Bin
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 7
1.68 27/08/2014 Facti Felipe M. Schaden
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
1.69 28/08/2014 Edison M. Ogata Incluso da rede CONDUCTOR-PL
Incluso da bandeira BAHAMAS CRDITO
Incluso da bandeira BAHAMAS ALIMENTAO
1.70 23/09/2014 Facti Felipe M. Schaden Correo de nome da funo ScopeRecuperaBufTabelaGen e de parmetro da funo ScopeRecuperaBufTabela
1.71 19/12/2014 Regina Megumi Incluso de informaes sobre Cielo Auto
1.72 22/12/2014 Marcelo Dionysio da
Fonseca
Atualizao para Transaes Sem Contato (Contactless)
Incluso d Cdigos de Retorno de Pr-TEFApndice A.
1.73 27/01/2015 Edison Ogata Acrscimo da bandeira CABAL VOUCHER na lista de bandeiras.
1.74 19/02/2015 Edison Ogata Reitrada da bandeira CABAL VOUCHER da lista de bandeiras, pois j existe uma bandeira semelhante: CABAL VALE
1.75 27/02/2015 Facti Felipe M. Schaden Incluso da mscara da funo ScopeObtemCampoExt2, na tabela Dados Disponveis, para obteno do cdigo SAT e CNPJ da rede credenciadora da transao.
1.76 12/03/2015 Jailton Santana Incluso do parmetro GenTiemout
Formatao
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 8
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 [] ....................................................................................................................... 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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 9
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 10
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 11
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 Associao dos produtos e as funes do SCOPE ................................................................................ 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 Associao dos produtos e as funes do SCOPE ................................................................................ 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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 12
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 13
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 14
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.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 15
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.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 16
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 tra
configuraes possveis para o tratamento de servio de crdito, o prximo estado poder ser
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
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 17
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 de
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:
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 18
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 ()
{
\
}
Para compatibilidade das funes entre diversas linguagens e plataformas, algumas convenes
de tipos devem ser adotadas, conforme a tabela a seguir:
Definio de Tipo:
Tipo Tamanho Descrio
BYTE 1 byte Valor sem sinal de 0 a 255
WORD 2 bytes Valor sem sinal de 0 a 65.535
SHORT 2 bytes Valor com sinal de -32.768 a 32.767
LONG 4 bytes Valor com sinal de -2.147.483.648 a 2.147.483.647
Analogamente, como recurso de portabilidade, algumas constantes devem ser criadas e definidas
diferentemente em cada plataforma, com o objetivo de utilizar os mesmos prottipos de funes
conforme a tabela a seguir:
Constantes:
Tipo Descrio
EXPORT Usada nos prottipos das funes que so exportadas
CALLBACK Funo cujo endereo de entrada fornecido a outras funes, de modo que estas possam utilizar internamente da primeira
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 19
Legenda de Abreviaes
Formato Atributo
a Caracteres alfabticos.
n Caracteres numricos.
an Caracteres alfabticos e numricos.
ans Caracteres alfabticos, numricos e especiais.
MM Ms.
DD Dia.
AA Ano.
hh Hora.
mm Minuto.
ss Segundo.
LLvar Tamanho de um campo varivel. -
LLLvar Tamanho de um campo varivel. -
10 Tamanho fixo de 10 caracteres.
..10 Tamanho varivel de at 10 caracteres.
b Representao binria dos dados.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 20
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- \
Instalao do SCOPE Client para Linux
Para a instalao do SCOPE Client em ambiente Linux, disponibilizado um arquivo no formato
RPM. Este arquivo um pacote do sistema RPM (Red Hat Package Manager), utilizado em vrias
distribuies Linux. O nome do arquivo liberado segue o padro:
itautec - scope - - 1.i386.rpm
Onde: representa a verso e o release do SCOPE Client. Para a sua instalao execute
o comando:
$ rpm i itautec - scope - - 1.i386.rpm
Este comando instalar as bibliotecas na pasta /usr/lib .
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 21
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- - vh
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 22
Configurao
Configurao do arquivo scope.ini
O arquivo scope.ini responsvel por parte da configurao da aplicao. Ele deve estar
disponvel com o SCOPE Client, independente do sistema operacional que a aplicao executa.
Sesso []
Esta sesso a nica obrigatria para que o SCOPE Client possa se conectar ao ScopeSRV.
Dentro dos colchetes deve haver uma 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 Significado Valor
Name Endereo ou nome da mquina em que est o
ScopeSRV.
I.P. ou nome da mquina do
ScopeSRV
Port Porta de conexo do ScopeSRV. Valor numrico (o padro
2046).
AtualizaDataHora
Parmetro que decide se o SCOPE Client
dever alterar a data e a hora da mquina para
sincronizar com o ScopeSRV no momento da
conexo.
N se no deve sincronizar
(padro).
S caso deseja-se que
sincronize.
MsgOperReduzida
Controla o tamanho mximo de colunas das
mensagens que o SCOPE Client enviar para a
aplicao para que esta exiba no teclado do
operador ou display com esta finalidade.
N 40 colunas (padro)
s 20 colunas
m 16 colunas
ShowCupom Configura a exibio do cupom na tela. Utilizado
apenas na interface HLAPI.
n No exibe
s Exibe (padro)
TimeOutLogon
Configura o tempo, em segundos, de espera
para a conexo do SCOPE Client com o
ScopeSRV.
Valor numrico entre 10 e 60
(padro 10).
TimeOutAdm Configura o tempo, em segundos, de espera da
resposta da autorizadora em cada transao.
Valor numrico entre 15 e 180
(padro 30).
CupomReduzido Configura se deve exibir o cupom reduzido na
tela. Utilizado apenas na interface HLAPI.
n No exibir
s Exibir
VersaoAutomacao Verso da automao passada pela rea de
certificao da Visanet.
Sequncia de caracteres no
formato RRAAAACCCC, sendo
que:
RR release de certificao do
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 23
TEF
AAAA Nome da automao
CCCC Cdigo do memorando
xxx
WKPAN Configura se deve habilitar a Comunicao
Segura com o PIN Pad.
n No habilitar
s Habilitar
ScopeValidaSaque
Configura se o Scope deve consistir o valor do
saque digitado com os valores configurados nos
limites de saque do produto, localizados no
ScopeCnf.
n No habilitar
s Habilitar
MascararDados Indica como o valor do PAN deve ser enviado
para a aplicao.
n Nenhum carto
mascarado.
s Todos os cartes sero
mascarados com zeros.
s(0) Todos os cartes sero
mascarados com zeros.
s(*)
Todos os cartes sero
mascarados com
asteriscos.
p
Todos os cartes que
seguem o padro PCI DSS
sero mascarados com
zeros.
p(0)
Todos os cartes que
seguem o padro PCI DSS
sero mascarados com
zeros.
p(*)
Todos os cartes que
seguem o padro PCI DSS
sero mascarados com
asteriscos.
GenTimeout
Define um tempo mximo, em segundo,
para o SCOPE Client gerar as chaves de
criptogr afia utilizado na conexo.
Valor numrio de 1 99 que
representa o tempo em
segundos. Se no tiver
configurado ou o valor estiver
invlido, ser assumido o
valor padro de 99
segundos. Neste caso, ser
praticamente impossvel
alcanar esse tempo e a
cha ve ideal ser gerada
sempre.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 24
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
Sesso [SCOPEAPI]
Esta sesso no obrigatria e define os parmetros abaixo relacionados ao ambiente:
Chave Significado Valor
SaveCupom Diretrio para salvar o cupom
TracePin
Habilita o log do PIN-pad compartilhado. Em
MS- \
sistemas, no diretrio corrente da aplicao, o
circular, assim quando o tamanho desse
arquivo for 1 MB, ele ser renomeado para
criado.
n No habilita (padro)
s Habilita
ArqControlPath
Diretrio para salvar os arquivos de controle do
Scope Client. Somente vlido para o sistema
operacional Windows
\
Sesso [PPCOMP]
Aqui, configuram-se itens relacionados ao PIN-Pad compartilhado
Chave Significado Valor
NaoAbrirDigitado
Configura para no abrir o digitado se
cancelada a leitura do carto no PIN-Pad
compartilhado.
n no abre digitao (padro)
s abre digitao
Configurao de porta serial para Linux
Atualmente, o SCOPE Client preparado para trabalhar apenas com PIN-Pad conectados porta
serial. No entanto, para ambiente Linux, possvel conectar um PIN-Pad serial numa porta USB,
utilizando um conversor Serial USB. 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.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 25
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 Serial USB, 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/t tyUSB1 ; 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 Significado Valor
TamMinDados Tamanho mnimo de entrada de dados
permitidos pelo PIN-Pad.
Valor numrico acima de 1 (o
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.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 26
Chave Significado Valor
DigitacaoCodigo
Configura se d a opo de outra rede.
ATENO: essa chave ignorada se a
chave Complementar existir.
n no pergunta se outra rede
s pergunta se outra e coleta o
cdigo da rede e da bandeira
Complementar
Configura se acrescenta rede tabela
padro ou as substitui.
ATENO: a existncia dessa chave
desconsidera a configurao chave
DigitacaoCodigo, pois ela prioritria.
n substitui as tabelas padro pelas
que esto configuradas
s
acrescenta a configurao de redes
e bandeiras que esto no arquivo a
listagem padro
Redes Lista de at 7 cdigos de redes distintas
para perguntar no fluxo
Nmeros de at 3 dgitos cada,
separados por vrgula
Bandeiras Lista de at 14 cdigos de bandeiras
distintas para perguntar no fluxo
Nmeros de at 3 dgitos cada,
separados por vrgula
NomeBandeiraYYY
Nome da bandeira YYY que ser exibida no
fluxo, onde YYY uma das bandeiras
listadas na chave Bandeiras.
ATENO: se faltar a chave para alguma
das bandeiras, ser exibido cdigo da
bandeira para o operador.
String de at 20 caracteres
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
Bandeiras
Lista de bandeiras associadas a esta rede. A
bandeira deve existir na chave Bandeiras da
seo [SCOPEAPIPOS].
Nmeros de at 3 dgitos cada,
separados por vrgula
ServicoBXXX
Lista de cdigos de servios permitidos para
essa bandeira, associada a essa rede, onde XXX
o cdigo com 3 dgitos (zeros esquerda) de
uma das bandeiras listada no campo Bandeiras.
Se houver bandeiras sem configurao de
servio, sero associados todos os servios
previstos.
Nmeros de at 3 dgitos cada,
separados por vrgula
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 27
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 Wo Instalao do SCOPE em
Sistemas Operacionais Microsoft Windows de 64-Bits Manual de
Relacionado na tabela abaixo, esto as chaves do scope.ini com o registro do MS-Windows.
Chave do arquivo
scope.ini
Localizao no editor do registro
AtualizaDataHora HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\AtualizaDataHora
CupomReduzido HKEY_LOCAL_MACHINE\SOFTWARE\Scope\SCOPEAPI\CupomReduzido
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 28
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 sess Instalao do SCOPE em
Sistemas Operacionais Microsoft Windows de 64-Bits Manual de
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 29
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
[]).
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] String (constante
Modo Modo de operao
[in] String com quatro dgitos
Empresa Cdigo de identificao da empresa conforme cadastrado no ScopeCNF
[in] String com quatro dgitos
Filial Cdigo de identificao da filial conforme cadastrado no ScopeCNF
[in] String com trs dgitos
PDV Nmero do PDV conforme cadastrado no ScopeCNF
Retorno Ver tabela de cdigo de retorno.
Possveis Retornos de Erros
Cdigos Retorno
Significado Hexadecimal
Decimal
0xFA01 64001 Parmetro 1 invlido
0xFA02 64002 Parmetro 2 invlido
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 30
Cdigos Retorno Significado Hexadeci
mal Decimal
0xFA03 64003 Parmetro 3 invlido
0xFE02 65026 SCOPE API j foi inicializada corretamente
0xFE09 65033 Servidor no configurado no arquivo scope.ini
Exemplo ...
...
esa, filial, pdv);
if (retorno != 0)
{
exit(0);
}
...
Desconexo
Encerra o SCOPE Client, procedendo liberao de todos os recursos alocados. Essa funo
dever ser executada uma nica vez no trmino do aplicativo usurio.
Prottipo LONG EXPORT ScopeClose (void)
Parmetros No h parmetro.
Retorno Ver tabela de cdigo de retorno.
Possveis Retornos de Erros
Cdigos Retorno
Significado Hexadecimal
Decimal
0xFE01 65025 SCOPE API no foi inicializada corretamente
0xFE00 65024 A transao em andamento a aplicao deve aguardar
Exemplo ...
retorno = ScopeClose ();
...
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 31
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.
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 32
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 Ver tabela de cdigo de retorno.
Possveis Retornos de Erros
Cdigos Retorno
Significado Hexadecimal
Decimal
0xFE01 65025 SCOPE API no foi inicializada corretamente
0xFE00 65024 A transao em andamento a aplicao deve aguardar
Exemplo ...
// Conecta ao servidor do SCOPE
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 33
...
// 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)
Acao Informa o SCOPE para confirmar ou desfazer a(s) transao(s) da sesso de TEF atual
[out] Ponteiro para byte
DesfezTEFAposQueda Retorna se a(s) transao(s) da sesso de TEF foram desfeitas aps uma queda de energia.
Retorno Caso retorne sucesso (0x0000), significa que o SCOPE conseguiu com xito confirmar ou
desfazer a(s) transao(s) de uma sesso de TEF. Caso contrrio, ocorreu algum problema
na confirmao ou desfazimento da(s) transao(s). Para maiores detalhes dos cdigos
relacionados, ver tabela de cdigo de retorno.
Possveis Retornos de Erros
Cdigos Retorno
Significado Hexadecimal
Decimal
0xFB08 64264 Erro no arquivo de controle utilizado finalizao no ciclo multi-TEF
0xFE00 65024 A transao em andamento a aplicao deve aguardar
0xFE01 65025 SCOPE API no foi inicializada corretamente
Exemplo BYTE acao, defez;
...
// Realiza a(s) transao(s) desejada(s)
...
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 34
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
, e se possvel, acionar
um supervisor para verificar a situao.
Exemplo ...
BYTE acao, defez;
...
// Conecta ao servidor do SCOPE
...
ScopeFechaSessaoTEF(acao, &defez);
if (d esfez)
{
\
}
...
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27 35
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:
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.
Possveis Retornos de Erros
Cdigos Retorno Significado Hexadeci
mal Decimal
0xFE00 65024 A transao em andamento a aplicao deve aguardar
0xFE01 65025 SCOPE API no foi inicializada corretamente
Exemplo ...
BYTE acao, defez;
...
// Conecta ao servidor do SCOPE
...
ScopeMTEFOnOff(1); // deixa pende nte
ScopeFechaSessaoTEF(acao, &defez);
if (desfez)
{
\
}
...
Manual do desenvolvedor
SCOPE Soluo Completa para Pagamento Eletrnico 2.27
Recommended