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:

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: