8. Captura de dados
Sempre que a função PW_iExecTransac retornar PW_MOREDATA, significa que ainda não foram
capturados todos os dados necessários para executar uma transação. O vetor de estruturas
PW_GetData retornado por esta função inclui todas as informações necessárias para captura dos
dados faltantes.
8.1. Tipos de captura
Existem vários tipos de dados que podem ser solicitados através deste mecanismo, conforme tabela
abaixo:
Nome | Valor | Descrição |
---|---|---|
PWDAT_MENU | 1 | Menu de opções. |
PWDAT_TYPED | 2 | Entrada digitada. |
PWDAT_CARDINF | 3 | Dados do cartão, obtidos do PIN-pad ou digitados. |
PWDAT_PPENTRY | 5 | Informação digitada pelo Cliente no PIN-pad. |
PWDAT_PPENCPIN | 6 | Senha ou outro dado criptografado digitado pelo Cliente no PINpad. |
PWDAT_CARDOFF | 9 | Dados resultantes do processamento off-line do cartão com chip, obtidos do PIN-pad. |
PWDAT_CARDONL | 10 | Dados resultantes do processamento on-line do cartão com chip, obtidos do PIN-pad. |
PWDAT_PPCONF | 11 | Confirmação pelo Cliente de uma informação no PIN-pad. |
PWDAT_BARCODE | 12 | Código de barras, lido ou digitado. |
PWDAT_PPREMCRD | 13 | Remoção do cartão do PIN-pad. |
PWDAT_USERAUTH | 17 | Validação de senha. |
8.2. Processamento
Para cada item na Estrutura PW_GetData (página 67), a Automação deve primeiramente identificar o
tipo de captura (campo bTipoDeDado) e, de acordo com o valor deste, realizar os tratamentos
abaixo descritos.
8.2.1. Menu (PWDAT_MENU)
Para capturar um dado deste tipo, a Automação deve apresentar ao operador uma lista de opções
para seleção de uma única opção. Fica a critério da Automação escolher o formato de apresentação
do menu e o mecanismo de navegação deste pelo operador, sempre respeitando as regras aqui
descritas:
• A quantidade de opções possíveis é informada pelo campo bNumOpcoesMenu, e o descritivo de
cada opção no campo vszTextoMenu.
• O campo szPrompt contém uma mensagem descrevendo a informação solicitada e que deve ser
apresentada ao operador junto com a lista de opções (por exemplo: “ESCOLHA O PRODUTO:”).
Caso esta mensagem esteja vazia (szPrompt[0] = 0), esta não deve ser apresentada.
• Caso o Ponto de Captura possua um teclado numérico e o campo bTeclasDeAtalho seja igual a 1,
a Automação deve acrescentar na frente do descritivo de cada opção um dígito numérico
correspondendo à posição (iniciada em 1) da opção na lista. Caso o operador pressione uma tecla
numérica, fica imediatamente selecionada a opção correspondente, sem necessidade de
confirmação. Caso o campo bTeclasDeAtalho tenha um valor diferente de 1, a Automação não
deve habilitar este recurso.
• O campo bItemInicial contém o índice (iniciado em 0) da opção padrão, que deve ser realçada e
selecionada caso o operador pressione a tecla de confirmação ([Enter] ou [OK]). Caso o valor
deste campo não corresponda a uma opção do menu (caso seja maior ou igual à quantidade de
opções), não existe nenhuma opção padrão e o pressionamento da tecla de confirmação não
deve ter nenhum efeito se o operador não tiver antes selecionado uma opção.
Após a seleção da opção, a Automação deve informar esta ao Pay&Go Web, chamando a função
PW_iAddParam com os seguintes parâmetros:
• wParam = campo wIdentificador;
• pszValue = campo vszValorMenu.
8.2.2. Entrada digitada (PWDAT_TYPED)
Para capturar um dado deste tipo, a Automação deve abrir uma caixa de edição para o operador
digitar a informação solicitada, com as seguintes características:
• O campo szPrompt contém uma mensagem descrevendo a informação solicitada e que deve ser
apresentada ao operador acima da caixa de edição (por exemplo: “QTDE PARCELAS:”).
• O campo szMascaraDeCaptura, caso não vazio (szMascaraDeCaptura[0] ≠ 0), define uma
máscara para formatação do dado durante a digitação.
• O campo bOcultarDadosDigitados indica se os caracteres digitados devem ser apresentados
(ecoados) na interface com o usuário, ou se devem ser mascarados (tipicamente, substituídos
pelo caractere asterisco, como para uma senha de acesso).
• O campo bTiposEntradaPermitidos informa quais tipos de caracteres são aceitos. A Automação
deve utilizar esta informação para restringir o uso do teclado pelo operador. (Teclas que
correspondem a caracteres não aceitos não devem ter efeito.)
• O campo szValorInicial contém o valor do dado a ser apresentado na abertura da caixa de
edição, podendo ser editado ou confirmado pelo operador.
• Os campos bTamanhoMinimo e bTamanhoMaximo indicam respectivamente os tamanhos
(quantidade de caracteres) mínimo e máximo do dado capturado (sem considerar a eventual
máscara de formatação). A Automação não deve aceitar a entrada do operador caso a dado
digitado não atenda este requerimento.
• Para dados exclusivamente numéricos (de acordo com bTiposEntradaPermitidos):
→ Os campos ulValorMinimo e ulValorMaximo indicam respectivamente os valores mínimo e
máximo do dado capturado. A Automação não deve aceitar a entrada do operador caso a
dado digitado não atenda este requerimento.
→ As mensagens szMsgDadoMenor e szMsgDadoMaior devem ser apresentadas brevemente
pela Automação (3 segundos ou até o operador pressionar uma tecla) para o operador caso
seja informado um dado respectivamente abaixo de ulValorMinimo ou acima de ulValorMaximo. Após isso, a Automação deve aguardar que o operador corrija o dado até que cumpra os requerimentos.
• O campo bValidacaoDado indica se a Automação deve realizar algum tipo de validação adicional
do dado.
→ Caso a validação falhe, a Automação deve apresentar ao operador a mensagem
szMsgValidacao (durante 3 segundos ou até que o operador pressione uma tecla) e
aguardar que o operador corrija o dado até que cumpra os requerimentos.
→ No caso da digitação dupla do dado (bValidacaoDado = 6), a Automação deve solicitar duas
vezes a digitação do dado (em ambos os casos iniciando com szValorInicial), e verificar que
ambos os dados digitados são iguais. Na segunda solicitação, a Automação deve substituir a
mensagem szPrompt por szMsgConfirmacao.
Após a digitação e validação da informação digitada, a Automação deve informar esta ao Pay&Go
Web, chamando a função PW_iAddParam com os seguintes parâmetros:
• wParam = campo wIdentificador;
• pszValue = dado digitado, sem formatação.
8.2.3. Código de barras (PWDAT_BARCODE)
Para capturar um dado deste tipo, a Automação deve solicitar ao operador a digitação de um código
de barras ou a leitura deste através de um dispositivo conectado ao Ponto de Captura, com as
seguintes características:
• O campo szPrompt contém uma mensagem descrevendo a informação solicitada e que deve ser
apresentada ao operador acima da caixa de edição (por exemplo: “CODIGO DO BOLETO:”).
• O campo bTipoEntradaCodigoBarras indica quais meios de captura são permitidos (digitado, lido
ou ambos).
• É recomendado que a Automação valide o código de barras digitado, corrigindo localmente
eventuais erros de digitação antes da submissão à infraestrutura Pay&Go Web.
Após a captura, a Automação deve informar o código de barras ao Pay&Go Web através de duas
chamadas à função PW_iAddParam, com os seguintes parâmetros:
• Uma primeira vez com wParam = PWINFO_BARCODE e pszValue contendo o código de barras:
→ Se digitado, incluindo todos os dígitos verificadores;
→ Se lido, sem caracteres de controle/protocolo eventualmente acrescentados pelo leitor.
• Uma segunda vez com wParam = PWINFO_BARCODENTMODE e pszValue informando o tipo de
captura (1 = digitado ou 2 = lido).
8.2.4. Dados do cartão (PWDAT_CARDINF)
Para capturar um dado deste tipo, a Automação deve verificar o valor do campo ulTipoEntradaCartao:
• Se igual a 1, solicitar a digitação do número do cartão;
• Se igual a 2, chamar a função PW_iPPGetCard de acordo com o fluxo ilustrado em “4.2.Captura
de dados”.
• Se igual a 3, chamar a função PW_iPPGetCard, e também permitir que o operador digite o
número do cartão. Caso o operador opte pela digitação, a Automação deve interromper o
processamento do PIN-pad (de acordo com o fluxo ilustrado em “4.2.Captura de dados”) antes de prosseguir.
Caso a captura seja realizada pelo PIN-pad, a Automação deve verificar o retorno final da função
PW_iPPEventLoop:
• Se igual a PWRET_OK, a captura está realizada, não há necessidade de chamar a função
PW_iAddParam. A biblioteca automaticamente obtém do PIN-pad os dados necessários.
• Se igual a PWRET_FALLBACK, a Automação deve abrir a possibilidade de o operador passar a
digitar o número do cartão (independentemente do valor de ulTipoEntradaCartao), mantendo a
opção de ler novamente o cartão no PIN-pad.
• Para outros retornos, a Automação deve interromper a transação com o erro correspondente.
Caso o número do cartão seja digitado, a Automação deve:
• Chamar PW_iAddParam com wParam igual a PWINFO_CARDFULLPAN e pszValue igual ao
número digitado;
• Se o campo bCapturarDataVencCartao for igual a 0, também solicitar a digitação da data de
vencimento do cartão:
→ Com máscara “@@/@@”;
→ Com validação “MMAA” (validação de data válida, não de vencimento);
→ Chamar PW_iAddParam com wParam igual a PWINFO_CARDEXPDATE e pszValue contendo
os quatro dígitos informados pelo operador.
8.2.5. Senha (PWDAT_USERAUTH)
Quando solicitado um dado deste tipo, a automação deve fazer uma validação de senha, esta senha
pode ser:
• A senha do lojista, neste caso o campo wIdentificador será PWINFO_AUTHMNGTUSER.
• A senha técnica, neste caso o campo wIdentificador será PWINFO_AUTHTECHUSER.
Caso a senha tenha sido validada corretamente, a automação deve chamar PW_iAddParam com
wParam igual ao campo wIdentificador e pszValue contendo um identificador para usuário validado.
Importante: Caso a validação da senha já tenha sido feita previamente pela automação, é possível
chamar a função PW_iAddParam logo após o início da transação (PW_iNewTransac), utilizando
wParam igual a PWINFO_AUTHxxxUSER e pszValue contendo um identificador para usuário
validado. Caso isso seja feito, a biblioteca não irá solicitar a validação novamente.
8.2.6. Outras capturas no PIN-pad
Para outras capturas realizadas no PIN-pad, a Automação deve chamar a função correspondente de
acordo com o fluxo ilustrado em “4.2.Captura de dados”.
A função a ser chamada para cada tipo de dado é:
• PWDAT_PPENTREY: PW_iPPGetData
• PWDAT_PPENCPIN: PW_iPPGetPIN
• PWDAT_CARDOFF: PW_iPPGoOnChip
• PWDAT_CARDONL: PW_iPPFinishChip
• PWDAT_PPCONF: PW_iPPConfirmData
• PWDAT_PPREMCRD: PW_iPPRemoveCard
Para estes tipos de dado, não há necessidade de chamar a função PW_iAddParam. A biblioteca
automaticamente obtém do PIN-pad os dados necessários.
8.2.7. Múltiplas entradas
Caso o campo bNumeroCapturas seja maior que 1, a Automação deve repetir a captura do dado
(com as mesmas características) a quantidade de vezes correspondente e, quando relevante para o
tipo de dado, chamar PW_iAddParam a mesma quantidade de vezes, com o mesmo valor de
wParam, variando pszValue de acordo com a informação capturada.
8.2.8. Mensagem de aviso
Caso o campo szMsgPrevia não esteja vazio (szMsgPrevia[0] ≠ 0), a Automação deve apresentar
brevemente (durante 3 segundos ou até que o operador pressione uma tecla) a mensagem
correspondente antes de solicitar a captura do dado.
8.3. Estrutura PW_GetData
A tabela abaixo descreve cada membro da estrutura PW_GetData:
Nome | Relevância | Descrição |
---|---|---|
(Byte) bTipoDeDado | Sempre | PWDAT_xxx (ver tabela acima). |
(Word) wIdentificador | bTipoDeDado = PWDAT_MENU, PWDAT_TYPED ou PWDAT_BARCODE | Identificador do dado, a ser utilizado como parâmetro wParam da função PW_iAddParam. |
(char[]) szPrompt | bTipoDeDado = PWDAT_MENU, PWDAT_TYPED, PWDAT_CARDINF ou PWDAT_BARCODE | Mensagem a ser apresentada ao operador durante a captura do dado, descrevendo a informação solicitada (conforme “4.3.Interface com o usuário”). |
(Byte) bNumOpcoes Menu | bTipoDeDado = PWDAT_MENU | Quantidade de opções do menu. |
(char[][]) vszTextoMenu | bTipoDeDado = PWDAT_MENU | Vetor (bNumOpcoesMenu itens) com o texto a ser exibido para cada opção de menu. |
(char[][]) vszValorMenu | bTipoDeDado = PWDAT_MENU | Vetor (bNumOpcoesMenu itens) com o valor a ser utilizado como parâmetro pszValue da função PW_iAddParam para a opção de menu que for selecionada |
(char[]) szMascara DeCaptura | bTipoDeDado = PWDAT_TYPED | Máscara para apresentação do dado enquanto é digitado, onde cada caractere ‘@’ identifica a posição de um caractere útil. Exemplo: “@@@.@@@.@@@-@@” para CPF. Se string vazia, não deve ser utilizada máscara para captura do dado. |
(Byte) bTiposEntrada Permitidos | bTipoDeDado = PWDAT_TYPED | 0: deve exibir o dado contido em szValorInicial, sem permitir a edição do mesmo; 1: somente numéricos; 2: somente alfabéticos; 3: numéricos e alfabéticos; 7: numéricos, alfabéticos e especiais |
(Byte) bTamanho Minimo | bTipoDeDado = PWDAT_TYPED | Quantidade mínima de caracteres para o dado. |
(Byte) bTamanho Maximo | bTipoDeDado = PWDAT_TYPED | Quantidade máxima de caracteres para o dado. |
(Uint32) ulValor Minimo | bTipoDeDado = PWDAT_TYPED e bTipoEntrada Permitidos = 1 | Valor mínimo do dado numérico a ser capturado (validar somente se diferente de zero). |
(Uint32) ulValor Maximo | bTipoDeDado = PWDAT_TYPED e bTipoEntrada Permitidos = 1 | Valor máximo do dado numérico a ser capturado (validar somente se diferente de zero). |
(Byte) bOcultar Dados Digitados | bTipoDeDado = PWDAT_TYPED | Indica se o dado deve ser mascarado (com asteriscos) durante sua digitação: 0: mostrar o dado enquanto é digitado; 1: mascarar o dado. |
(Byte) bValidacao Dado | bTipoDeDado = PWDAT_TYPED | Indica se o dado capturado deve passar por algum tipo de validação: 0: sem validação 1: o dado não pode ser vazio 2: (último) dígito verificador, algoritmo módulo 10 3: CPF ou CNPJ 4: data no formato “MMAA” 5: data no formato “DDMMAA” 6: solicitar a digitação duas vezes iguais (confirmação) |
(Byte) bAceitaNulo | bTipoDeDado = PWDAT_TYPED | Indica se o dado aceita nulo durante sua digitação, mesmo com bTamanhoMinimo>0. 0: exige a digitação; 1: aceita. No caso deste valor ser 1 e o usuário entrar com um dado nulo, o valor “” deve ser utilizado como parâmetro wParam da função PW_iAddParam. |
(char[]) szValorInicial | bTipoDeDado = PWDAT_TYPED | Valor inicial a ser exibido para que o usuário o edite. Se não houver valor iniciar, é uma string vazia. |
(Byte) bTeclasDe Atalho | bTipoDeDado = PWDAT_MENU | Indica se devem ou não ser exibidas/aceitas teclas de atalho (numéricas, iniciadas em 1) para as opções de menu. 0: Não utiliza teclas de atalho. 1: Utiliza as teclas de atalho |
(char[]) szMsg Validacao | bTipoDeDado = PWDAT_TYPED | Mensagem a ser apresentada ao operador caso a validação do dado falhe (de acordo com bValidacaoDado e “4.3.Interface com o usuário”. |
(char[]) szMsg Confirmacao | bTipoDeDado = PWDAT_TYPED e bValidacaoDado = 6 | Mensagem a ser apresentada ao operador no momento da confirmação do dado (conforme “4.3.Interface com o usuário” |
(char[]) szMsgDado Maior | bTipoDeDado = PWDAT_TYPED | Mensagem a ser apresentada ao operador caso o valor digitado seja maior do que o informado em ulValorMaximo (conforme “4.3.Interface com o usuário". |
(char[]) szMsgDado Menor | bTipoDeDado = PWDAT_TYPED | Mensagem a ser apresentada ao operador caso o valor digitado seja menor do que o informado em ulValorMinimo (conforme “4.3.Interface com o usuário”. |
(Byte) bItemInicial | bTipoDeDado = PWDAT_MENU | Índice (iniciado em 0) da opção que deve ser pré-selecionado quando o menu for apresentado. Se o operador pressionar [Enter], esta opção será escolhida. |
(Byte) bCapturarData VencCartao | bTipoDeDado = PWDAT_CARDINF | Indica se a data de vencimento do cartão deve ser capturada, caso o número do cartão for digitado: 0: Capturar 1: Não capturar |
(Uint32) ulTipoEntrada Cartao | bTipoDeDado = PWDAT_CARDINF | Modos de entrada do cartão permitidos: 1: somente digitado 2: somente no PIN-pad 3: no PIN-pad ou digitado |
(Byte) bNumero Capturas | Sempre | Quantidade de dados que devem ser capturados com estas mesmas características. |
(char[]) szMsgPrevia | Sempre | Mensagem a ser exibida ao usuário antes da captura do dado. |
(Byte) bTipoEntrada CodigoBarras | bTipoDeDado = PWDAT_BARCODE | Tipos de entrada permitidos para o código de barras (soma dos valores abaixo): 1: Digitado 2: Lido através de dispositivo eletrônico |
(Byte) bOmitAlert Message | bTipoDeDado = PWDAT_TYPED | Indica se uma mensagem de alerta deve ser exibida, caso o operador digite um dado inválido para uma captura digitada: 0: exibe a mensagem de alerta e captura o dado novamente 1: fica na tela de captura até que um dado válido seja digitado |
(Byte) bStartFromLeft | bTipoDeDado = PWDAT_TYPED | Indica se o dado a ser capturado, digitado pelo operador, será preenchido na tela a partir da esquerda ou da direita: 0: a partir da direita (default); 1: a partir da esquerda |
Updated over 3 years ago