manual desenvolvedor

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.



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.



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.



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



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


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"


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.

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.


Redes com tratamentos especficos

funcionalidades do Cielo Premia.


Incluso da funo ScopeObtemOperadorasRecCelOffTEF

Incluso da funo ScopeRecuperaValoresRecCelOffTEF


Fonseca Incluso da rede Bin




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


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



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



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



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



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



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



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

distribuda, adequando-se necessidade do cliente.

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

operacionais e gerenciais.

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

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

bancos.

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

contingncia.



Conceitos

Transaes

O SCOPE prov loja diversos tipos de transaes (exemplo: compra com carto de crdito,

compra com carto de dbito, recarga de celular, pagamento de contas e de fatura de cartes,

etc.). Numa transao, o SCOPE Client comunica-se com o SCOPE Server baseado em

mensagens, as quais seguem a norma ISO 8583 que especifica o protocolo de mensagens para

transaes financeiras com carto. As mensagens bsicas e as suas 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.



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



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:



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



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.



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 .



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



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



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


sero mascarados com

zeros.

p(*)

Todos os cartes que


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.



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:


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


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.




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.


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.




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



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.


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



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.





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



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



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




Cdigos Retorno Significado Hexadeci

mal Decimal


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.



Cdigos Retorno


Decimal

0xFE01 65025 SCOPE API no foi inicializada corretamente

0xFE00 65024 A transao em andamento a aplicao deve aguardar

Exemplo ...

retorno = ScopeClose ();

...



Sesso de transao

Sesso de TEF O conceito de sesso de TEF existe para garantir a integridade de uma operao. Desta forma,

entre a abertura e encerramento da sesso, todas as atividades includas na respectiva operao

(autorizao da transao, impresso de comprovante) devero ser completamente realizadas.

Este mecanismo permite que em caso de falha (queda de energia), a operao possa ser

desfeita. Isso corresponde a imprimir corretamente o cupom de TEF e garantir que a falha

ocorrida no atrapalhe no funcionamento da aplicao.

Sendo multi-TEF, o SCOPE implementa o conceito de sesso de TEF com o intuito de garantir

que todas as transaes numa mesma sesso sero aprovadas ou desfeitas. Com isto, o cliente

pode efetuar o pagamento parcialmente de diversas maneiras (exemplo: 40% do valor da venda

sero pagos em dbito e o restante com o carto de crdito), e para validar a venda, todas as

transaes devero ser aprovadas, caso contrrio, as transaes no podem ser concludas (no

tem sentido que a venda seja considerada concluda apenas com a aprovao de parte do valor

da compra).

Em cada venda realizada, a aplicao deve abrir a sesso, realizar as diversas transaes e

finalmente fechar a sesso, confirmando ou desfazendo todas as transaes desta venda. A

estrutura do fluxo bsico de funcionamento do SCOPE Client encontra-se na figura 4.

IMPORTANTE: numa sesso de multi-TEF em que h vrias transaes, no possvel

desfazer uma ou outra transao. Para isso, o operador dever cancelar todas daquela

sesso ou confirm-las.



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



Cdigos Retorno


Decimal



Exemplo ...

// Conecta ao servidor do SCOPE



...

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


Cdigos Retorno


Decimal

0xFB08 64264 Erro no arquivo de controle utilizado finalizao no ciclo multi-TEF



Exemplo BYTE acao, defez;

...

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

...



acao = 1; // confirmar

retorno = ScopeFechaSessaoTEF(acao, &defez);

if (retorno != 0)

{

// Erro no encerramento da sesso

}

...

Tratando queda de energia

A funo que encerra a sesso tambm utilizada para desfazer as transaes pendentes de

uma sesso de TEF aps uma queda de energia no PDV. 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;

...


...

ScopeFechaSessaoTEF(acao, &defez);

if (d esfez)

{

\

}

...



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.


Cdigos Retorno Significado Hexadeci

mal Decimal



Exemplo ...

BYTE acao, defez;

...


...

ScopeMTEFOnOff(1); // deixa pende nte

ScopeFechaSessaoTEF(acao, &defez);

if (desfez)

{

\

}

...


SCOPE Soluo Completa para Pagamento Eletrnico 2.27

manual desenvolvedor

Documents