Soluo Completa de Pagamento Eletrnico

Interface com Automao Comercial

Por Troca de Arquivos

Especificao Tcnica Verso 01.00

Reviso: 03

Data: 02/01/2012

Responsvel: Marcelo D. Fonseca
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 2


Informaes Gerais

Leia antes de iniciar o desenvolvimento:

imprescindvel a leitura deste material para o entendimento do fluxo das transaes e processos
envolvidos na troca de arquivos entre o SCOPE e Automao Comercial.
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 3











Reviso Data Responsvel Histrico
00 24/11/2011 Marcelo D. Fonseca Verso Preliminar
01 02/12/2011 Marcelo D. Fonseca
Reviso segundo necessidades da Eletropaulo
e melhorias gerais
02 05/12/2011 Marcelo D. Fonseca Definio arquivos Estorno e melhorias gerais
03 02/01/2012 Marcelo D. Fonseca
Formalizao nmero seqencial de 3 dgitos.
Descrio do FAPI.
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 4

ndice
________________________________________________________________________________________________

Prefcio...............................................................................................................................5
A quem se destina.......................................................................................................................................... 5
Descrio do Produto..................................................................................................................................... 5
Objetivo ....................................................................................................................................................... 5
Definio ..................................................................................................................................................... 5
Benefcios.................................................................................................................................................... 5
Maiores Informaes................................................................................................................................... 5
Referncias .................................................................................................................................................... 6
Regras Gerais ....................................................................................................................7
Organizao dos Diretrios............................................................................................................................ 7
Nomenclatura dos Arquivos ........................................................................................................................... 7
Fluxo da Troca de Arquivos ........................................................................................................................... 8
Viso Geral ..................................................................................................................................................... 9
Fluxos de Mensagens de uma TEF ............................................................................................................. 10
Estrutura dos Arquivos ................................................................................................................................. 11
Padres adotados neste documento............................................................................................................ 12
Legenda de Abreviaes .......................................................................................................................... 12
Campos Previstos ........................................................................................................................................ 12
Composio dos Arquivos .............................................................................................14
Solicitao de TEF ....................................................................................................................................... 14
Resposta da TEF.......................................................................................................................................... 14
Confirmar ou Desfazer TEF ......................................................................................................................... 15
Estorno de TEF ............................................................................................................................................ 16
Solicitao de Estorno.................................................................................................................................. 16
Resposta do Estorno.................................................................................................................................... 16
Confirmar ou Desfazer Estorno.................................................................................................................... 17
FAPI...................................................................................................................................18
Instalao ..................................................................................................................................................... 18
Configurao ................................................................................................................................................ 18
Execuo...................................................................................................................................................... 18
Operao...................................................................................................................................................... 19
Apndice A Exemplos de Arquivos.............................................................................20
Apndice B Cdigos de Resposta das Redes............................................................23
Apndice C Cdigos de Resposta do SCOPE............................................................25
Apndice D Glossrio...................................................................................................29

Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 5



Prefcio
_____________________________________________________________________________________________________


A quem se destina
Este documento se destina aos clientes ou parceiros da Itautec que desejam integrar seu sistema
de Automao Comercial com o SCOPE atravs da interface de Troca de Arquivos.

Existem situaes no mercado em que a integrao de um sistema de Automao Comercial
atravs de chamadas de funes do SCOPE Client invivel.

Para estas situaes o SCOPE pretende oferecer a alternativa de integrao atravs de troca de
arquivos.

Descrio do Produto
Objetivo
O sistema SCOPE Soluo Completa para Pagamento Eletrnico permite ao software de
PDV (Automao Comercial) 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, multiempresa, multifilial, 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.

Maiores Informaes
Podem ser obtidas atravs dos documentos do produto SCOPE, conforme relao descrita nas
Referncias abaixo. Voc pode solicit-los ao seu representante comercial Itautec.
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 6


Referncias
International Standard Financial Transaction Card Originated Messages
ISO8583
Interchange Message Specification
2
nd
Edition 15/12/2003

American National Standard for Financial Services
X9.82003
BANKING - PERSONAL IDENTIFICATION NUMBER MANAGEMENT AND SECURITY
Part 1: PIN protection principles and techniques for online PIN verification in ATM & POS systems

Documentos SCOPE
SCOPE Manual Desenvolvedor
SCOPE Manual de Instalao e Configurao
SCOPE Manual de Administrao
SCOPE Guia de Codificao Segura
SCOPE Guia de Implementao PA-DSS
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 7


Regras Gerais
_____________________________________________________________________________________________________

Toda interao entre Automao Comercial e SCOPE feita atravs de Troca de Arquivos.
Abaixo esto descritas as regras de organizao, nomenclatura, manipulao e estrutura destes
arquivos.

Organizao dos Diretrios
Devem existir dois diretrios configurveis, um de entrada e outro de sada, usando o SCOPE
como referncia. Por exemplo:

Diretrio Caminho
Entrada C:\SCOPE\IN
Sada C:\SCOPE\OUT

A Automao Comercial (AC) deve sempre gravar no diretrio de Entrada do SCOPE.
O SCOPE deve sempre gravar no diretrio de Sada.

Para evitar conflitos, as gravaes dos arquivos devem necessariamente seguir os passos abaixo:
Criar o arquivo com nome temporrio;
Gravar os dados do arquivo;
Forar a gravao imediata atravs de comando do tipo flush.
Fechar o arquivo;
Renomear o arquivo para o nome definitivo.

Estas regras devem ser seguidas tanto pela AC quanto pelo SCOPE.

Aps leitura com sucesso do arquivo, o mesmo deve ser eliminado do diretrio. Portanto, a
responsabilidade de eliminar os arquivos do diretrio de Entrada do SCOPE. Analogamente, a
responsabilidade por eliminar os arquivos do diretrio de Sada da AC.


Nomenclatura dos Arquivos
Os arquivos trocados entre AC e SCOPE devem seguir as seguintes regras de nomenclatura:

Arquivo Diretrio Criado por Nome Temporrio Nome Definitivo Eliminado por
Solicitao Entrada AC REQT<nnnn>.tmp REQT<nnnn>.sc_ SCOPE
Resposta Sada SCOPE RESP<nnnn>.tmp RESP<nnnn>.ac_ AC
Confirmao/
Desfazimento
Entrada AC COMP<nnnn>.tmp COMP<nnnn>.sc_ SCOPE

Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 8

Sendo que <nnnn> representa um nmero seqencial (entre 0001 e 9999) que deve ser mantido
constante ao longo do ciclo de vida da transao, ou seja, deve ser o mesmo nos trs arquivos.

Embora no haja tratamento de transaes simultneas, este nmero seqencial uma garantia
de que os trs arquivos referem-se a uma mesma transao.

Este nmero controlado pela AC e pode ser reiniciado diariamente ou no, a critrio da AC.

Fluxo da Troca de Arquivos
A figura abaixo representa o fluxo da troca de arquivos entre AC e SCOPE:



Considerando <nnnn> como 0001, o ciclo de vida de uma transao aprovada representado pelo
diagrama acima seria:
1. AC grava arquivo REQT0001.sc_ com solicitao da TEF no diretrio de entrada;
2. SCOPE l arquivo REQT0001.sc_ e efetua a TEF;
3. SCOPE grava arquivo RESP0001.ac_ com resposta da TEF no diretrio de sada;
4. AC l arquivo RESP0001.ac_ e imprime comprovante de TEF;
5. AC grava arquivo COMP0001.sc_ confirmando (ou desfazendo em caso de erro no
tratamento da resposta) a TEF;
6. SCOPE l arquivo COMP0001.sc_ e envia confirmao (ou desfazimento) da TEF;

O arquivo de resposta sempre gerado pelo SCOPE, mesmo em casos de erro, como nos
exemplos abaixo:
A transao foi negada pela rede autorizadora;
O SCOPE no recebeu resposta da rede (timeout);
A transao foi abortada pelo operador;
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 9

Os dados recebidos so invlidos ou insuficientes;
Ocorreu um erro interno inesperado;

Viso Geral
No diagrama abaixo est representada uma viso geral do processo:


Descrio do Diagrama:
A troca de arquivos ocorre no PDV, onde esto sendo executados:
Automao Comercial;
Mdulo SCOPE gerenciador da interface de Troca de Arquivos, integrado ao SCOPE
Client;
O SCOPE Client interage com o SCOPE Server para consultar a configurao e solicitar a TEF;
O SCOPE Server responsvel por interagir com os PDVs, armazenar as transaes em Banco de
Dados e interagir com o SCOPE Gateway (que pode estar instalado na mesma mquina do SCOPE
Server);
O SCOPE Gateway gerencia as conexes com as redes autorizadoras, geralmente atravs de X.25,
repassando as solicitaes do SCOPE Server para as redes e as respostas das redes
autorizadoras ao SCOPE Server.

Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 10


Fluxos de Mensagens de uma TEF
Para facilitar o entendimento de todo o processo envolvido na TEF, abaixo est descrito como
funciona a troca de mensagens entre o SCOPE e a rede autorizadora:

Transao Aprovada e Confirmada
Considerando um fluxo bsico de sucesso, temos:

O arquivo de solicitao interpretado pelo SCOPE e uma perna ISO8583 cujo cdigo de
mensagem 0200 (primeira perna) enviada rede autorizadora. Esta por sua vez responde
solicitao com uma mensagem 0210 (segunda perna) aprovando ou negando a TEF. Caso a
transao tenha sido aprovada, o SCOPE precisa enviar uma 0202 (terceira perna) para informar
rede que a transao deve ser confirmada. Para algumas redes, a 0202 enviada tambm para
transaes negadas.

Desfazimento
Em caso de timeout (a 0210 no chegou ao SCOPE em tempo hbil) ou falha na AC no
tratamento da resposta, a perna de confirmao substituda por uma perna de solicitao de
desfazimento:


O desfazimento pode ocorrer um duas situaes:
S SC CO OP PE E A Au ut to or ri iz za ad do or r
0 02 21 10 0
0 04 42 20 0
0 02 20 00 0
0 04 43 30 0
S SC CO OP PE E A Au ut to or ri iz za ad do or r
0 02 21 10 0
0 02 20 02 2
0 02 20 00 0
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 11

A resposta 0210 foi recebida e a transao foi aprovada, porm a AC sinalizou falha na
impresso do comprovante e/ou tratamento da resposta. Neste caso o envio da 0420
depende da gerao do arquivo COMP<nnnn>.sc_, que de responsabilidade da AC.
Caso no gerado, a transao ficar pendente.
A resposta 0210 no foi recebida, ou seja, ocorreu timeout. Neste caso a 0420 enviada
automaticamente pelo SCOPE e um arquivo RESP<nnnn>.ac_ gerado para informar
erro AC. Neste caso no necessrio gerar o arquivo COMP<nnnn>.sc_.

Outro ponto importante a ser comentado que a 0430 no imprescindvel, pois a transao j
considerada desfeita no SCOPE. Podem existir situaes em que a rede no est recebendo
nenhuma perna, por exemplo, quando h problemas no provedor X.25. Neste caso o motivo do
timeout pode ser o no recebimento da perna 0200 pela rede e, portanto, provavelmente a
mesma no ir receber a 0420 nem responder com 0430.

Estrutura dos Arquivos
Todos os arquivos trocados tero do tipo texto, mltiplas linhas, cada linha finalizada com CRLF
(carriage return e line feed), ou seja, 0x0D e 0x0A.

A estrutura interna dos arquivos segue o seguinte formato:

CCC . NNN : DDD..D CRLF

Sendo:

Campo Tamanho Descrio
CCC 3 Cdigo do campo
. 1 Caractere . (ponto)
NNN 3 Nmero seqencial da linha do campo.
000 - Se campo de linha nica;
001 at nnn - Se campo de vrias linhas
: 1 Caractere : (dois pontos)
DDD..D varivel Dados do campo
CRLF 2 carriage return e line feed (0x0D e 0x0A)


Obrigatoriamente todos os arquivos devero conter pelo menos 3 linhas, sendo:

Header
Ao
Linhas de Dados
(se existir)
Finalizador


Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 12

Padres adotados neste documento
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.
Ex. Se o contedo do campo = AB1234CD, teremos para represent-lo: 08
AB1234CD .
LLLvar Tamanho de um campo varivel.
Ex. Se o contedo do campo = AB1234CD, teremos para represent-lo: 008
AB1234CD .
10 Tamanho fixo de 10 caracteres.
..10 Tamanho varivel de at 10 caracteres.
b Representao binria dos dados.



Campos Previstos
Abaixo a relao de campos previstos:

Campo Tamanho Descrio Formato
000 an3 Header SCOPEvvv, Sendo:
vvv = verso, atualmente fixo em 001
001 a3 Ao CCC, Sendo:
TEF Solicitar TEF;
CNF Confirmar TEF;
DSF Desfazer TEF;
CAN Cancelar TEF;
IMP Imprimir Cupom;
EXB Exibir Negada;
ERR Tratar Erro;
002 n3 Cdigo do Grupo de
Servio
GGG, Sendo:
001 Dbito;
002 Crdito;
003 n3 Cdigo do Servio SSS, Sendo:
006 Dbito vista;
009 Crdito vista;
027 Crdito parcelado Adm;
028 Crdito parcelado Loja;
031 Estorno Dbito;
032 Estorno Crdito;
050 Dbito Voucher;
051 Estorno Voucher;
004 n12 Valor da Venda 999999999999 em centavos de Real, por
exemplo: 000000001050 significa R$10,50.
005 n12 Taxa de Servio 999999999999
006 n12 Taxa de Embarque 999999999999
007 n12 Valor do Saque 999999999999
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 13

008 n3 Qtd de Parcelas 999
009 an8 Identificao da AC XXXXXXXX
010 an8 Verso do Software da
AC
XXXXXXXX
011 n5 Cdigo de Resposta do
SCOPE

012 an3 Cdigo de Resposta da
Rede

013 ans40 Mensagem Final
014 n12 Valor Total Final 999999999999
015 n3 Cdigo da Rede
016 ans40 Nome da Rede
017 n3 Cdigo da Bandeira
018 ans40 Nome da Bandeira
019 ans22 Nmero do Carto
Mascarado

020 n4 Validade do Carto AAMM
021 ans40 Nome do Cliente
022 n8 Data da Transao DDMMAAAA
023 n6 Hora da Transao hhmmss
024 n6 NSU NNNNNN
025 ans12 NSU Host NNNNNNNNNNNN
026 n6 Cdigo da Autorizao NNNNNN
027 n11 Controle NNNNNNNNNNN
028 an15 Cdigo do
Estabelecimento

029 n4 Cdigo da Empresa EEEE
030 n4 Cdigo da Filial FFFF
031 n3 Cdigo do PDV PPP
032 n4 Tamanho Total do
Cupom via
Estabelecimento
LLLL
033 LLvar Cupom via
Estabelecimento
Linha do Cupom via Estabelecimento
034 n4 Tamanho Total do
Cupom via Cliente
LLLL
035 LLvar Cupom via Cliente Linha do Cupom via Cliente
036 n4 Tamanho Total do
Cupom via Reduzida
LLLL
037 LLvar Cupom via Reduzida Linha do Cupom via Reduzida
038 LLLvar Atributo da Aplicao LLLDDD...D Sendo:
LLL tamanho dos dados a seguir;
DDD...D dados
039 LLvar Identificador da venda Campo identificador da venda ou pedido
gerado pela AC e fornecido no arquivo de
solicitao a ser ecoado no arquivo de
resposta
999 a3 Finalizador FIM


Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 14

Composio dos Arquivos
_____________________________________________________________________________________________________

Nesta sesso esto descritos os campos por arquivo, mandatrios, opcionais, ecoados ou
condicionais, sendo:
M = Mandatrio;
O = Opcional;
E = Ecoado;
C1 = Condicional, se aprovada;
C2 = Condicional, se negada;
C3 = Condicional, se aprovada ou negada;
C4 = Condicional, se existir;
C5 = Condicional, se aprovada e se existir.

Solicitao de TEF

Campo Presena Descrio Contedo
000 M Header SCOPE001
001 M Ao TEF
002 M Cdigo do Grupo de
Servio
001 Dbito;
002 Crdito;
003 O Cdigo do Servio Opcional. Se no fornecido e configurao
permitir a deciso ser do operador.
004 M Valor da Venda 999999999999
005 O Taxa de Servio 999999999999
006 O Taxa de Embarque 999999999999
007 O Valor do Saque 999999999999
008 O Qtd de Parcelas 999
009 M Identificao da AC XXXXXXXX
010 M Verso do Software da
AC
XXXXXXXX
038 O Atributo da Aplicao LLLD...D
039 O Identificador da venda LLD...D
999 M Finalizador FIM


Resposta da TEF
Campo Presena Descrio Contedo
000 M Header SCOPE001
001 M Ao IMP Imprimir Cupom;
EXB Exibir Negada;
ERR Tratar Erro.
002 E Cdigo do Grupo de
Servio
001 Dbito;
002 Crdito;
003 M Cdigo do Servio 006 Dbito vista;
009 Crdito vista;
027 Crdito parcelado Adm;
028 Crdito parcelado Loja;
004 E Valor da Venda 999999999999
005 O Taxa de Servio 999999999999
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 15

006 O Taxa de Embarque 999999999999
007 O Valor do Saque 999999999999
008 O Qtd de Parcelas 999
011 M Cdigo de Resposta do
SCOPE

012 M Cdigo de Resposta da
Rede

013 M Mensagem Final
014 M Valor Total Final
015 M Cdigo da Rede
016 M Nome da Rede
017 M Cdigo da Bandeira
018 M Nome da Bandeira
019 O Nmero do Carto
Mascarado

020 O Validade do Carto AAMM
021 O Nome do Cliente
022 C3 Data da Transao DDMMAAAA
023 C3 Hora da Transao hhmmss
024 C1 NSU NNNNNN
025 C4 NSU Host NNNNNNNNNNNN
026 C4 Cdigo da Autorizao NNNNNN
027 C1 Controle NNNNNNNNNNN
028 C3 Cdigo do
Estabelecimento

029 O Cdigo da Empresa EEEE
030 O Cdigo da Filial FFFF
031 O Cdigo do PDV PPP
032 C1 Tamanho Total do
Cupom via
Estabelecimento
LLLL
033 C1 Cupom via
Estabelecimento
Linha do Cupom via Estabelecimento
034 C1 Tamanho Total do
Cupom via Cliente
LLLL
035 C1 Cupom via Cliente Linha do Cupom via Cliente
036 C5 Tamanho Total do
Cupom via Reduzida
LLLL
037 C5 Cupom via Reduzida Linha do Cupom via Reduzida
039 E Identificador da venda LLD...D
999 M Finalizador FIM

Confirmar ou Desfazer TEF
Somente se recebido o arquivo de resposta com ao IMP.
Campo Presena Descrio Contedo
000 M Header SCOPE001
001 M Ao CNF Confirmar;
DSF Desfazer.
015 E Cdigo da Rede
017 E Cdigo da Bandeira
022 E Data da Transao DDMMAAAA
023 E Hora da Transao hhmmss
024 E NSU NNNNNN
028 E Cdigo do
Estabelecimento

039 E Identificador da venda LLD...D
999 M Finalizador FIM
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 16

Estorno de TEF
Abaixo esto descritos os arquivos envolvidos em um Estorno (Cancelamento) de TEF.
Solicitao de Estorno

Campo Presena Descrio Contedo
000 M Header SCOPE001
001 M Ao CAN
004 M Valor 999999999999
009 M Identificao da AC XXXXXXXX
010 M Verso do Software da
AC
XXXXXXXX
027 M Controle NNNNNNNNNNN
Identifica a transao a ser cancelada
999 M Finalizador FIM


Resposta do Estorno
Campo Presena Descrio Contedo
000 M Header SCOPE001
001 M Ao IMP Imprimir Cupom;
EXB Exibir Negada;
ERR Tratar Erro.
002 M Cdigo do Grupo de
Servio
Cdigo do Grupo de Servio da transao
original
003 M Cdigo do Servio Cdigo do Servio da transao original
004 M Valor 999999999999
011 M Cdigo de Resposta do
SCOPE

012 M Cdigo de Resposta da
Rede

013 M Mensagem Final
015 M Cdigo da Rede
016 M Nome da Rede
017 M Cdigo da Bandeira
018 M Nome da Bandeira
022 C3 Data da Transao DDMMAAAA
023 C3 Hora da Transao hhmmss
024 C1 NSU NNNNNN
025 C4 NSU Host NNNNNNNNNNNN
026 C4 Cdigo da Autorizao NNNNNN
028 C3 Cdigo do
Estabelecimento

032 C1 Tamanho Total do
Cupom via
Estabelecimento
LLLL
033 C1 Cupom via
Estabelecimento
Linha do Cupom via Estabelecimento
034 C1 Tamanho Total do
Cupom via Cliente
LLLL
035 C1 Cupom via Cliente Linha do Cupom via Cliente
999 M Finalizador FIM


Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 17

Confirmar ou Desfazer Estorno
Somente se recebido o arquivo de resposta com ao IMP.
Campo Presena Descrio Contedo
000 M Header SCOPE001
001 M Ao CNF Confirmar;
DSF Desfazer.
015 E Cdigo da Rede
017 E Cdigo da Bandeira
022 E Data da Transao DDMMAAAA
023 E Hora da Transao hhmmss
024 E NSU NNNNNN
028 E Cdigo do
Estabelecimento

999 M Finalizador FIM


IMPORTANTE: Algumas redes autorizadoras no permitem o desfazimento do estorno.
Portanto, o recomendvel que a AC sempre solicite a confirmao do mesmo.
Caso a AC solicite o desfazimento de um estorno para uma rede que no possua este
recurso, pode ser necessrio um ajuste na conciliao.
Alm disso, as regras de quanto tempo um estorno pode ser executado varia de rede para
rede. Normalmente o estorno somente possvel no dia em que a transao foi realizada.

Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 18

FAPI
_____________________________________________________________________________________________________

Nesta sesso esto descritas as regras de instalao e configurao do mdulo
FAPI File Application Programming Interface.

Instalao
A instalao feita atravs de cpia simples dos arquivos abaixo para o mesmo diretrio onde
est instalado o SCOPE Client, em ambiente Windows 32 bits.
FAPI.EXE
FAPI.INI

Configurao
A configurao feita atravs do arquivo FAPI.INI, conforme exemplo abaixo:
[FAPI]
ArquivoCaminhoEntrada=C:\SCOPE\IN
ArquivoCaminhoSaida=C:\SCOPE\OUT
ScopeEmpresa=0001
ScopeFilial=0001
ScopePdv=001
LogoCliente=c:\meulogo.wmf

Sendo:
ArquivoCaminhoEntrada Caminho completo do diretrio de entrada
ArquivoCaminhoSaida Caminho completo do diretrio de sada
ScopeEmpresa Cdigo da Empresa deste PDV (4 dgitos)
ScopeFilial Cdigo da Filial deste PDV (4 dgitos)
ScopePdv Cdigo deste PDV (3 dgitos)
LogoCliente Logotipo do cliente (opcional)
Formato bmp, gif, jpg, wmf, emf ou ico

Execuo
Para realizar uma TEF, o sistema SCOPE deve estar em execuo no servidor, com as devidas
redes configuradas e em operao.

No PDV, o mdulo FAPI.EXE tambm deve estar em execuo. Este mdulo, enquanto est a
espera por arquivos, no apresenta nenhuma tela. Pode-se perceber que o mesmo est em
execuo devido ao cone na barra de tarefas, no canto inferior direito da tela, como mostrado
no exemplo abaixo:

Este mdulo no finalizado a cada TEF. O mesmo permanece sempre em operao a espera
pelo prximo arquivo.
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 19

Se necessrio, o FAPI pode ser finalizado clicando-se neste cone com o boto direito do mouse e
selecionando-se Sair.

Operao
Quando o FAPI percebe que um arquivo de solicitao foi gravado no diretrio de entrada, a tela
abaixo apresentada para permitir a coleta das informaes necessrias para a execuo da
TEF:


O operador do PDV deve ento realizar o passo-a-passo do fluxo de coleta da TEF at a
concluso da mesma.

No passo mostrado acima, o SCOPE est solicitado a leitura do carto, que pode ser digitado, por
tarja magntica ou chip. Nos dois ltimos casos necessrio que esteja conectado e configurado
um PINPad compatvel.

NOTA: Durante a execuo da TEF recomenda-se que a Automao Comercial garanta
que no seja possvel iniciar nova TEF at que a que est em execuo seja finalizada.
Caso necessrio, a Automao Comercial poder apresentar informaes complementares
em outra tela, como por exemplo, valor total dos produtos, valor da TEF que est em
andamento, etc.

Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 20


Apndice A Exemplos de Arquivos
_____________________________________________________________________________________________________

Os arquivos abaixo devem ser usados apenas como exemplos de formato. As transaes representadas
pelos mesmos foram realizadas atravs do ScopeAUT e portanto so simuladas. Alguns campos,
principalmente os cupons, podem possuir diferenas de formatao do contedo. No recomendada a
extrao de contedo diretamente dos cupons formatados, j que os mesmos podem ter sido montados
diretamente pela Rede Autorizadora e, portanto, seu contedo pode sofrer alteraes sem aviso prvio.

Exemplo de um arquivo de solicitao de TEF de crdito de R$1,00 deixando-se a seleo do servio
a cargo do Operador de TEF:
000.000:SCOPE001
001.000:TEF
002.000:002
004.000:000000000100
009.000:AC001
010.000:1.0
999.000:FIM

Exemplo de um arquivo de solicitao de TEF de crdito parcelado loja de R$100,00 em 3 parcelas:
000.000:SCOPE001
001.000:TEF
002.000:002
003.000:028
004.000:000000010000
008.000:3
009.000:AC001
010.000:1.0
999.000:FIM

Exemplo de um arquivo de solicitao de TEF de crdito vista de R$32,53:
000.000:SCOPE001
001.000:TEF
002.000:002
003.000:009
004.000:000000003253
009.000:AC001
010.000:1.0
999.000:FIM

Exemplo de um arquivo de solicitao de TEF de dbito vista de R$20,00:
000.000:SCOPE001
001.000:TEF
002.000:001
003.000:006
004.000:000000002000
009.000:AC001
010.000:1.0
999.000:FIM

Exemplo de um arquivo de resposta:
000.000:SCOPE001
001.000:IMP
002.000:002
003.000:009
004.000:000000005000
011.000:00000
012.000:000
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 21

013.001:AUTORIZADO
013.002:Controle 01200181000
014.000:000000005000
015.000:103
016.000:REDECARD-L0500
017.000:002
018.000:MASTERCARD
019.000:548826XXXXXX0000
020.000:0316
022.000:0102
023.000:145459
024.000:001081
025.000:SIMULADOR
026.000:001081
027.000:01200181000
028.000:000100010000103
029.000:0001
030.000:0001
031.000:001
032.000:680
033.001:38 REDECARD
033.002:00
033.003:38 MASTERCARD
033.004:00
033.005:00
033.006:38COMPR:123456789 VALOR: 9.999,99
033.007:00
033.008:38ESTAB:013932594 SCOPE TESTE SIMULADO
033.009:38DD.MM.AA-HH:MM:SS TERM:PV123456/pppnnn
033.010:24CARTAO: 548826XXXXXX0000
033.011:38AUTORIZACAO: 123456
033.012:38 RECONHECO E PAGAREI A DIVIDA
033.013:38 AQUI REPRESENTADA
033.014:00
033.015:38**************************************
033.016:38 D E M O N S T R A C A O
033.017:38 Transacao sem validade para reembolso
033.018:38 Autorizacao gerada por simulador
033.019:38**************************************
033.020:00
033.021:38 ____________________________
033.022:38
033.023:00
033.024:00
033.025:00
033.026:00
033.027:00
033.028:15AAAAA 111 AAAAA
033.029:15BBBBB 222 BBBBB
033.030:00
033.031:38CONTROLE 01200181000 ITAUTEC SCOPE
034.000:680
035.001:38 REDECARD
035.002:00
035.003:38 MASTERCARD
035.004:00
035.005:00
035.006:38COMPR:123456789 VALOR: 9.999,99
035.007:00
035.008:38ESTAB:013932594 SCOPE TESTE SIMULADO
035.009:38DD.MM.AA-HH:MM:SS TERM:PV123456/pppnnn
035.010:24CARTAO: 548826XXXXXX0000
035.011:38AUTORIZACAO: 123456
035.012:38 RECONHECO E PAGAREI A DIVIDA
035.013:38 AQUI REPRESENTADA
035.014:00
035.015:38**************************************
035.016:38 D E M O N S T R A C A O
035.017:38 Transacao sem validade para reembolso
035.018:38 Autorizacao gerada por simulador
035.019:38**************************************
035.020:00
035.021:38 ____________________________
035.022:38
035.023:00
035.024:00
035.025:00
035.026:00
035.027:00
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 22

035.028:15AAAAA 111 AAAAA
035.029:15BBBBB 222 BBBBB
035.030:00
035.031:38CONTROLE 01200181000 ITAUTEC SCOPE
036.000:171
037.001:38MASTERCARD 548826XXXXXX0000 03/16
037.002:35AUT:001081 NSU:001081 DOC:SIMULADOR
037.003:22VENDA CREDITO A VISTA
037.004:38VALOR: 50,00 CTR:01200181000
037.005:00
037.006:15AAAAA 111 AAAAA
999.000:FIM

Exemplo de um arquivo de confirmao:
000.000:SCOPE001
001.000:CNF
015.000:103
017.000:002
022.000:0102
023.000:145459
024.000:001081
028.000:000100010000103
999.000:FIM

Exemplo de um arquivo de desfazimento:
000.000:SCOPE001
001.000:DSF
015.000:103
017.000:002
022.000:0102
023.000:145459
024.000:001081
028.000:000100010000103
999.000:FIM

Exemplo de um arquivo de solicitao de estorno:
000.000:SCOPE001
001.000:CAN
004.000:000000005000
009.000:AC001
010.000:1.0
027.000:01200181000
999.000:FIM


Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 23


Apndice B Cdigos de Resposta das Redes
_____________________________________________________________________________________________________

Os cdigos de resposta abaixo so exemplos de contedo do campo 012 Cdigo de Resposta da Rede.
A AC deve sempre verificar o contedo deste campo no arquivo de resposta. Se 000 a transao foi
aprovada. Se diferente de 000 a transao foi negada.

Os cdigos de resposta de transaes negadas variam de rede para rede. O quadro abaixo deve ser
utilizado apenas como uma referncia bsica, pois no h garantias de que todas as redes seguem este
padro.

Para saber exatamente o significado de um cdigo, entre em contato com a rede para a qual a transao foi
enviada (Redecard, Cielo, Amex, etc).

Cdigo
Resposta

Descrio
000 Aprovada, transao executada.
003 Estabelecimento comercial invlido
006 Erro no processamento
009

Transao em andamento (somente para transao de consulta de status de transao).
012 Transao invlida
013 Valor da transao invlido
014 Carto invlido
015 Instituio no cadastrada
019 Refaa a transao
030 Erro de formato
031 Instituio no pertence rede
038 Excedido nmero de tentativas do PIN
041 Carto extraviado
043 Carto roubado
051 Saldo insuficiente
055 Senha incorreta
057 Transao no permitida a esse cliente
060 Entrar em contato com a instituio
061 Excedido limite de saque
065 Excedido frequncia de saque
076 Carto bloqueado
077 Pendente de confirmao
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 24

078 Transao cancelada
080 Transao no existe
083 Time-out
084 Log-on (terminal no aberto)
085 Problema rede local
086 Transao desfeita
091 Instituio temporariamente fora de operao

Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 25

Apndice C Cdigos de Resposta do SCOPE
_____________________________________________________________________________________________________

Os cdigos de resposta abaixo so exemplos de contedo do campo 011 Cdigo de Resposta do
SCOPE. A maioria destes erros nunca deve ocorrer, pois so situaes tratadas pelo mdulo gerenciador
de arquivos, j que este mdulo que est integrado ao SCOPE Client.

Porm, alguns destes erros podem ocorrer no dia-a-dia e no necessariamente representam um problema.
Exemplos:
65280 Indica que o servidor SCOPE no est disponvel. Pode ser problema de configurao (IP)
ou falha de conexo (rede);
65281 Instituio offline. A rede autorizadora est fora-do-ar no momento. Pode ser um problema
temporrio do autorizador e o restabelecimento ser automtico quanto o mesmo retornar a operar.
Pode ser tambm uma falha no provedor X.25.
65283 Servio ou BIN no configurado. O SCOPE no encontrou nenhum servio e/ou nenhuma
rede para rotear esse carto. Por exemplo, ocorre quando se tenta pagar com um carto de
bandeira que no est sendo contemplada por nenhuma rede com as quais o estabelecimento
possui contratos.

IMPORTANTE: Como o presente documento possui uma verso de especificao
independente da verso do SCOPE, a tabela abaixo pode estar desatualizada. A mesma
est sendo fornecida neste documento como um facilitador de entendimento, porm
recomenda-se usar a tabela presente no documento SCOPE - Manual Desenvolvedor
como referncia atualizada.


Cdigo
Resposta

Significado
65024 A transao em andamento a aplicao deve aguardar
65025 SCOPE API no foi inicializada corretamente
65026 SCOPE API j foi inicializada corretamente
65027 Existe transao suspensa
65028 No existe transao suspensa
65029 API ainda no fez nenhuma transao aps a inicializao. A
aplicao est tentando obter um handle sem ter feito nenhuma
transao desde ltima conexo com o ScopeSRV
65030 Logon duplicado
65031 Protocolo no suportado SCOPE Client com verso de protocolo
superior ao SCOPE Server
65032 POS no cadastrado
65033 Servidor no configurado no arquivo scope.ini
65034 No h mais PDVs disponveis. Erro retornado quando a aplicao
passa o caractere # como PDV para que o SCOPE Server lhe d
um nmero de PDV vlido, mas no h mais PDVs disponveis
65035 Protocolo incompatvel SCOPE Client com verso de protocolo
extremamente antigo (P00, P01 ou P02).
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 26

Cdigo
Resposta

Significado
65036 No pode mais desfazer uma transao que j iniciou o ciclo de
finalizao situao que pode ocorrer apos queda de energia ou na
inicializao da aplicao.
65037 No h arquivo com dados da transao anterior salvo
65280 ScopeSrv off-line ou o IP configurado no arquivo scope.ini est
apontando para a mquina errada
65281 Instituio off-line
65282 Transao cancelada pelo operador ou no caso de um estorno via
REDECARD: estorno fora do prazo permitido, validade no confere.
65283 Servio ou BIN no configurado
65284 Transao j foi cancelada
65285 Transao no encontrada
65286 Transao no permite cancelamento
65287 Dados informados no conferem com a transao original
65288 Erro no acesso ao banco de dados
65289 Time-out no acesso ao banco de dados
65290 Banco de dados off-line
65291 Transao abortada pelo aplicativo
65292 Transao no implementada
65293 Handle invlido (ver Obtendo handle)
65294 Taxa de servio invlida
65295 Taxa de servio excede limite
65296 Dado invlido
65297 No existe cupom vlido
65298 rea reservada para o buffer insuficiente para o SCOPE Client
preencher com os dados solicitados
65299 Limite invlido inferior ao permitido
65300 Transao desfeita
65301 Digitao no permitida
65302 Memria insuficiente
65303 Service Code invlido
65304 Data invlida
65305 Carto vencido
65306 Carto invlido
65307 Desfazimento no disponvel
65308 Erro na impresso do cupom
65309 Sesso em andamento a transao solicitada deve ser nica numa
sesso de TEF, ou seja, no pode ser chamada se h transaes na
sesso de TEF atual
65310 Transao j efetuada
65311 Inserir chip do carto
65312 Controle obrigatrio
65313 Pr-autorizao obrigatria
65314 Servio no configurado
65315 Servio no definido
65316 Nmero de parcelas invlidas
65317 Valor invlido
65318 Servio ou BIN no configurado para Visanet
65319 Estado de coleta no definido
65320 Operao no permitida
65321 CNPJ/CPF invlido
65322 Primeiro bloco do cdigo de barras est invlido
65323 Segundo bloco do cdigo de barras est invlido
65324 Terceiro bloco do cdigo de barras est invlido
65325 Quarto bloco do cdigo de barras est invlido
65326 Dados adicionais AID do chip do carto inexistente
65328 Autorizador retornou dados invlidos
65329 Conta no permitida
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 27

Cdigo
Resposta

Significado
65330 Conta vencida
65331 No existe resumo
65332 Cdigo de barra invlido
65333 Erro na consistncia do DAC
65334 Erro no envio da confirmao ou desfazimento da transao anterior
65335 Servio invertido a aplicao est tentando fazer uma transao de
dbito com um carto de crdito ou vice-versa
65336 Carto no permitido
65337 Permitido somente a coleta do CPF consulta de cheque
65338 Erro interno na execuo da coleta
65339 Lista (de produtos, de medicamentos, etc.) no est disponvel.
65340 Erro de leitura do carto
65341 Controle invlido
65342 Erro ao enviar mensagem para o servidor
65343 Interface SAB no inicializada
65344 Erro: dados ainda no disponveis (SAB)
65345 Erro: dados indisponveis (SAB)
65346 Servidor SAB off-line
65347 Erro de conexo entre SCOPE e SAB
65348 Erro no NSU recebido
65349 Erro no logon do PDV
65350 Erro no processamento do chip
65351 Operadora invlida
65352 Dados, da recarga de celular, no encontrados.
65353 Transao cancelada pelo cliente
65360 Transao aprovada off-line
65361 Verso do banco de dados incompatvel
65362 Cancelamento fora do prazo permitido
65363 Mensagem invlida
65364 PIN-Pad no foi aberto
65365 PIN-Pad j foi aberto a aplicao abriu o PIN-Pad antes de conectar
ao ScopeSRV, mas no deveria ter-lo feito, pois no ScopeCNF est
configurado com uso exclusivo do SCOPE
65366 Estado invlido a aplicao est tentando obter os servios
disponveis num estado de coleta inadequado
65367 PIN-Pad compartilhado no est configurado, mas a rede exige que
seja compartilhado
65368 PIN-Pad compartilhado no trabalha com a verso 2000 da VISA
65369 Funo de uso exclusivo na interface coleta
65370 rea insuficiente para os atributos do servio
65371 O SCOPE est configurado para uso de PIN-Pad compartilhado, mas
a aplicao informou que est com o kit Visanet para PIN-Pad
65372 O SCOPE no est configurado para uso de PIN-Pad compartilhado,
mas a aplicao informou que est com PIN-Pad compartilhado
65373 Erro ao inicializar perifricos na interface HLAPI
65374 Erro ao desmontar a estrutura ISO
65375 Bandeira no est configurada
65376 Funo indisponvel
65377 Valor mnimo da parcela invlido
65378 Valor da consulta Vale Gs ainda no est disponvel
65379 Nmero de Telefone invlido
65380 DDD invlido
65381 Erro Rede Modelo 2
65382 Erro Rede Modelo 3
65383 Confirmao Positiva Inconsistente
65384 Transao Offline Permitido apenas reimpresso offline
65385 Contrato Suspenso
65386 Transao permite somente digitado
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 28

Cdigo
Resposta

Significado
65387 No Encontrado (para quando no veio menu dinmico na carga de
tabelas).
65535 Erro genrico

Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 29

Apndice D Glossrio
_____________________________________________________________________________________________________
A
Acquirer: veja Adquirente
Adquirente: a entidade ou associao de entidades
financeiras que a partir de transaes efetuadas com
cartes nos estabelecimentos comerciais (Merchant)
associados, estabelece o devido vnculo com as
entidades autorizadoras (authorizing agent) (VISA,
MasterCard, Amex).
Aplicao frente de caixa: software executado no
PDV com a finalidade de realizar a venda de produtos
da empresa.
Aplicao de PDV: veja Aplicao frente de caixa.
Authorizing agent: veja Autorizador
Autorizador: a organizao (VISA, MasterCard,
Amex) que gerencia e controla operaes com cartes
de crdito, passando informaes entre o Adquirente e
o Banco emissor.

B
Banco de dados: tambm conhecido como base de
dados, so arquivos ou sistemas com uma estrutura
regular que organizam informaes. Essas estruturas
podem ter a forma de uma tabela: cada tabela
composta por linhas e colunas. As informaes
utilizadas para um mesmo fim so agrupadas em uma
base de dados.
Bandeira: entidade detentora de marcas e logotipos
utilizados em cartes de crdito, dbito e outros meios
de pagamentos. Exemplos: Visa, Mastercard, American
Express, Visa Electron, Maestro, Cheque Eletrnico.
Banco emissor: a entidade financeira associada a
uma ou mais organizaes autorizadoras e que
responsvel pela emisso de cartes para seus
clientes.
BIN (Bank Identification Number): nmero de
identificao do banco representado pelos primeiros 6
dgitos do carto.




C
CHIP: tambm conhecido como Circuito Integrado ou
CI. Nos cartes usado como alternativa mais segura
s tradicionais tarjas magnticas.

E
EMV (Europay Mastercard Visa): norma estabelecida
por estas trs entidades para estabelecer regras de
autenticidade e segurana em TEF atravs de cartes
com chip.
Endereo IP (Internet Protocol): trata-se de uma
tecnologia que permite a comunicao padronizada
entre computadores, mesmo que estes sejam de
plataformas diferentes, cada mquina possui um
endereo IP que a diferencie das demais.
Estabelecimento: ou estabelecimento comercial a
entidade que aceita o carto (card acceptor) como
forma de pagamento referente comercializao de
um bem ou servio prestado ao portador do carto
(card holder).

F
FAPI (File Application Programming Interface):
Mdulo SCOPE gerenciador da interface de
programao atravs de arquivos.
Fatura: documento emitido pela administradora do
carto relacionando as compras realizadas no perodo
atravs do carto de crdito.

G
Grupo de servio: um servio no SCOPE pertence
sempre a um grupo, que pode definir a forma de
pagamento, ou ainda, a tecla finalizadora do PDV.
Exemplos: carto de crdito, carto de dbito, consulta
de cheque, recarga de celular, estorno. Ver Servio.
GUI: do ingls Graphic User Interface que a
interface grfica exibida para o usurio da aplicao.

Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 30

I
Issuer: Veja Banco emissor.

M
Mdulo residente: So aplicativos para DOS que
rodam e permanecem em memria voltil. uma forma
de diminuir o programa executvel para que a memria
convencional no ficasse carregada.

P
PDV: acrnimo para Ponto de Venda. Terminal
inteligente utilizado na operao de pagamento. Veja
tambm PoS.
PIN (Personal Identification Number): nmero de
identificao pessoal, senha do carto digitada em
PINPad.
PINPad: equipamento utilizado para ler um carto, via
tarja magntica ou chip. Possui um pequeno teclado
numrico para permitir a coleta da senha.
PoS: termo em ingls Point of Sale. Veja tambm
PDV.
Private Label: bandeira emitida por um
estabelecimento comercial, tambm conhecida como
Bandeira do Lojista.

R
Rede autorizadora: empresa que concentra o
recebimento de transaes TEF de diversos
estabelecimentos, e as autoriza atravs de um sistema
autorizador. Exemplos: Visanet, Redecard, TecBan.

S
SCOPE: O SCOPE a soluo Itautec para
pagamentos eletrnicos
ScopeADM (SCOPE Administrador): o mdulo
responsvel por realizar consultas operacionais e
gerenciais das transaes realizadas alm de permitir a
gerao de relatrios.
ScopeCNF (SCOPE Configurador): o mdulo
responsvel pela configurao e cadastramento de
parmetros para a soluo SCOPE.
SCOPE Client: conjunto de bibliotecas localizadas na
mquina em que a aplicao de frente de loja. O
conjunto de bibliotecas pode variar conforme o sistema
operacional e a linguagem de programao utilizada.
ScopeGW (SCOPE Gateway): funciona como um
roteador de mensagens entre um ou mais servidores
SCOPE e uma ou diversas redes.
ScopeSRV (SCOPE Server): o mdulo principal da
soluo SCOPE. responsvel por estabelecer o
contato inicial de todos os contratos cadastrados na
base de dados com as respectivas redes, garantindo
tambm o fluxo de transaes com estas redes
Servio: o termo servio no contexto do SCOPE define
o objetivo de uma transao. Exemplos: compra com
carto de crdito vista, compra com carto de crdito
parcelada pelo estabelecimento (sem juros), compra
com carto de crdito parcelada de administradora
(com juros), compra com carto de dbito vista,
compra com carto de dbito pr-datado, compra com
carto de dbito voucher, consulta cheque, estorno
crdito, estorno dbito.
Servidor: o computador que administra e fornece
programas e informaes para os outros computadores
conectados em rede.

T
TEF (Transferncia Eletrnica de Fundos): termo
utilizado para se referir a uma transao de
transferncia de fundos, como ocorre em uma compra
com carto de crdito ou dbito.
TSR: abreviao do termo em ingls Terminate and
Stay Resident. Veja Mdulo residente.
Interface com Automao Comercial por Troca de Arquivos
Soluo Completa para Pagamento Eletrnico 31



































2011
Esse documento propriedade da Itautec S.A. Grupo Itautec.
Tem carter tcnico/informativo. Todos os direitos so reservados.
No pode, no todo ou em parte, ser copiado, fotocopiado, reproduzido, traduzido ou reduzido a qualquer meio eletrnico
ou forma legvel por mquina, sem a autorizao escrita da I t a u t e c S . A. - Gr u p o I t a u t e c .

Esta se reserva, por outro lado, o direito de alterar seu contedo e forma, sem qualquer aviso prvio.

Produzido no Brasil.