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

9.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 pinpad ou digitados.
PWDAT_PPENTRY	5	Informação digitada pelo Cliente no pinpad.
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 pinpad.
PWDAT_CARDONL	10	Dados resultantes do processamento on-line do cartão com chip, obtidos do pinpad.
PWDAT_PPCONF	11	Confirmação pelo Cliente de uma informação no pinpad.
PWDAT_BARCODE	12	Código de barras, lido ou digitado
PWDAT_PPREMCRD	13	Remoção do cartão do pinpad
PWDAT_PPGENCMD	14	Comando proprietário de rede no pinpad.
PWDAT_PPDATAPOSCNF	16	Confirmação positiva de dados no pinpad.
PWDAT_USERAUTH	17	Validação de senha.
PWDAT_DSPCHECKOUT	18	Mensagem a ser exibida no checkout.
PWDAT_TSTKEY	19	Teste de chaves presentes no pinpad.
PWDAT_DSPQRCODE	20	QR Code, a ser exibido no checkout.

9.2 Processamento

Para cada item na Estrutura PW_GetData, a Automação deve primeiramente identificar o tipo de captura (campo bTipoDeDado) e, de acordo com o valor deste, realizar os tratamentos abaixo descritos.

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

➝ Caso bNumOpcoesMenu informe que existe apenas uma opção e bItemInicial tenha o índice zero, a automação pode adicionar automaticamente o dado disponível. Caso contrário, o menu deve ser exibido para que a opção seja confirmada.

Após a seleção da opção, a Automação deve informar esta ao PayGo, chamando a função PW_iAddParam com os seguintes parâmetros:

➝ wParam = campo wIdentificador;
➝ pszValue = campo vszValorMenu.

9.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 PayGo, chamando a função PW_iAddParam com os seguintes parâmetros:

➝ wParam = campo wIdentificador;
➝ pszValue = dado digitado, sem formatação.

9.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 PayGo.

Após a captura, a Automação deve informar o código de barras ao PayGo 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).

9.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 “5.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 pinpad (de acordo com o fluxo ilustrado em “5.2.Captura de dados”) antes de prosseguir.
Caso a captura seja realizada pelo pinpad, 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 pinpad 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 pinpad.

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

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

9.2.6 Exibição de uma mensagem no checkout (PWDAT_DSPCHECKOUT)

Quando a Automação receber PWDAT_DSPCHECKOUT, deve apresentar a mensagem presente em szPrompt. Isso permite manter o usuário informado da situação de processamento da transação.

Para sinalizar para a biblioteca o sucesso no tratamento desta informação, a Automação deve chamar PW_iAddParam utilizando o wIdentificador recebido na estrutura de captura e o valor “” (string vazia).

🚧

Importante:

por motivo de compatibilidade com versões anteriores, este tipo de captura somente ocorrerá caso a Automação indique a capacidade correspondente através de PWINFO_AUTCAP.

9.2.7 Exibição de QR Code (PWDAT_DSPQRCODE)

Quando o tipo de dado PWDAT_ DSPQRCODE for recebido, a Automação deve, simultaneamente:

➝ Apresentar a mensagem presente em szPrompt; e
➝ Apresentar um QR Code em uma tela direcionada para o Cliente, para captura pelo seu dispositivo móvel.

Devido à particularidade desta captura, o conteúdo do QR Code não é retornado na estrutura PW_GetData. A Automação deve recuperar o conteúdo através de PW_iGetResult (PWINFO_AUTHPOSQRCODE).

Para sinalizar para a biblioteca o sucesso no tratamento desta informação, a Automação deve chamar PW_iAddParam utilizando o wIdentificador recebido na estrutura de captura e o valor “” (string vazia).

🚧

Importante:

Por motivo de compatibilidade com versões anteriores, este tipo de captura somente ocorrerá caso a Automação indique a capacidade correspondente através de PWINFO_AUTCAP.

➝ É retornado apenas o conteúdo do QR Code. Cabe à Automação transformá-lo em uma imagem, de acordo com as capacidades de seu display. Alternativamente o conteúdo também pode ser impresso.

➝ Existe a possibilidade de que vários retornos PWDAT_DSPQRCODE sejam recebidos pela automação, sem que o valor de PWINFO_AUTHPOSQRCODE tenha sido alterado, somente para a atualização da mensagem szPrompt a ser exibida na tela. Nesse caso, é recomendado que o QR code seja mantido na tela e somente a mensagem seja atualizada.

9.2.8 Outras capturas no pinpad

Para outras capturas realizadas no pinpad, a Automação deve chamar a função correspondente de acordo com o fluxo ilustrado em “5.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_PPGENCMD: PW_iPPGenericCMD
➝ PWDAT_PPDATAPOSCNF: PW_iPPPositiveConfirmation
➝ PWDAT_PPREMCRD: PW_iPPRemoveCard
➝ PWDAT_TSTKEY: PW_iPPTestKey

Para estes tipos de dado, não há necessidade de chamar a função PW_iAddParam. A biblioteca automaticamente obtém do pinpad os dados necessários.

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

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

9.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, PWDAT_DSPCHECKOUT 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”, página 8).
(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	Indica a possibilidade de digitar caracteres não numéricos: 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 a captura/coleta do dado é obrigatória ou opcional, mesmo com bTamanhoMinimo>0. Quando retornado: 0: Captura do dado é obrigatória pela automação. Neste caso o dado capturado deve ser informado via PW_iAddParam. 1: Captura do dado é opcional. Quando a automação/usuário não coletar o dado, é necessário sinalizar para a biblioteca o sucesso no tratamento desta informação, chamando PW_iAddParam utilizando o wIdentificador recebido na estrutura de captura e o valor “” (string vazia).
(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”, página 8).
(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”, página 8).
(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”, página 8).
(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”, página 8).
(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 pinpad 3: no pinpad 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.