TT - DOCUMENTAÇÃO - Especificação Clisitef

Dúvida

Como consultar a Especificação Clisitef

Ambiente

TOTVS TEF - SiTef Express

Solução

Para solucionar essa dúvida, realize os seguintes passos:

Introdução

As bibliotecas CliSiTefI e CliSiTef oferecem aos desenvolvedores de automações comerciais um conjunto de rotinas (API´s) para integração com o servidor SiTef.

O servidor SiTef, por sua vez, oferece um amplo leque de serviços de pagamentos com os mais diversos autorizadores.

As bibliotecas CliSiTefI e CliSiTef estão disponíveis para uma série de plataformas, normalmente sob a forma de bibliotecas dinâmicas.

Ela possui pontos de entrada pelos quais a automação comercial a configura, solicita um pagamento, solicita uma função gerencial ou o pagamento de uma conta.

Os pontos de entrada estão na CliSiTefI e é essa que deve ser carregada pela aplicação do usuário.

A CliSiTef é de uso exclusivo da CliSiTefI e não pode ser carregada ou chamada diretamente sob risco de, eventualmente, desestabilizar o ambiente. Neste documento, qualquer referência a CliSiTef deve ser entendida como o conjunto destas duas bibliotecas.

Público-Alvo

Desenvolvedores de automação comercial com CliSiTef.

Objetivos

Apresentar a descrição da biblioteca que efetua a interface com os serviços de meio de pagamento disponíveis no SiTef.

Apresentação

A CliSiTef propicia um meio rápido e simples de disponibilizar as funcionalidades do SiTef para aplicativos em geral. Suas principais características são:

• Não intrusiva pois é a própria automação que gerencia suas telas. Não ocorre sobreposição de telas da própria interface que, se existisse, na maioria das vezes não seria compatível com a diagramação visual da aplicação principal do cliente;
• Permite que a aplicação de automação restrinja as transações disponíveis para determinado pagamento uma vez que, na vida prática, ocorre a negociação com o cliente e uma vez fechado o meio de pagamento, quantidade de parcelas, etc, não devem ser modificados por engano na hora da execução do TEF;
• Permite total liberdade na inclusão de novos produtos e meios de pagamento, acompanhando a evolução do SiTef, sem que seja necessário fazer nenhuma alteração na automação ou, se ela for imprescindível (por exemplo pela inclusão de novos periféricos de acesso tais como leitor de códigos em barra), que ela seja mínima.

Nota: a CliSiTef possui, para cada funcionalidade, dois pontos de entrada (rotinas). A escolha de qual das interfaces será utilizada pela aplicação depende do gosto pessoal do programador e de se o ambiente utilizado por ele para o desenvolvimento impõe algum tipo de restrição na chamada a CliSiTef. Em particular, estamos nos referindo ao tipo de dado manipulado pelo ambiente de programação. Se ele aceitar somente dados em ASCII, necessariamente deve ser utilizada a interface batizada a seguir nesse documento como “A”.

Funcionamento básico

Passo inicial

Inicialmente a Automação Comercial deve executar o comando ConfiguraIntSiTefInterativo, passando as informações necessárias para que o Terminal de Vendas possa se comunicar com o SiTef, como Endereço IP do SiTef, Código da Empresa (no SiTef Demonstração este código é 00000000) e a identificação do terminal.

A rotina retorna um valor indicando se a configuração ocorreu com sucesso ou não. Caso retorne 0 (zero) o processo ocorreu de forma correta.

Transação propriamente dita

O próximo passo é, então, chamar a função IniciaFuncaoSiTefInterativo, passando os parâmetros descritos para ela.

No retorno, a ela devolve o valor 10000 para continuar a transação ou outro valor para encerrar.

Se o retorno for 10000, deve-se chamar a função ContinuaFuncaoSiTefInterativo, com os parâmetros também descritos para ela nós próximos tópicos.

Enquanto a CliSiTef retornar na chamada dessa função o valor 10000, a automação deve ficar repetindo a chamada a essa função tantas vezes quanto for necessário até que o valor de retorno da função seja 0 (zero), indicando que ocorreu tudo bem, ou diferente de 0 e de 10000 indicando que ocorreu alguma interrupção anormal.
 

Confirmação (ou não-confirmação) da transação

Se o retorno foi 0 (zero), a automação encerra o laço e se houve impressão de cupom TEF a automação deve imprimi-los e chamar uma outra função, a FinalizaFuncaoSiTefInterativo, confirmando ou não a transação dependendo, respectivamente, se o cupom foi impresso corretamente ou não.

Se o retorno foi diferente de 10000 e de 0 então a automação simplesmente sai do laço e, por opção do programador, pode ou não exibir uma mensagem de acordo com o retorno da função chamada. Por exemplo, se retornou -2, significa que a transação foi cancelada pelo operador. Estes retornos negativos estão descritos neste documento.

Exemplificando graficamente o fluxo descrito neste tópico, teríamos o seguinte:

API - Rotinas disponíveis na CliSiTef

Neste capítulo, apresentaremos as funções disponíveis na clisitef. Para tanto, serão adotadas as seguintes convenções:

Campo vazio ou não fornecido – na versão padrão é um campo contendo apenas o delimitador (zero binário). Na versão ASCII, se for um campo fixo ele contém espaços. Se for um campo variável ele contém apenas o delimitador de início e final de campo.

Tamanho do campo – no caso de campo de tamanho fixo, quando esse valor for fornecido, indica qual o tamanho mínimo a ser reservado pela aplicação para receber uma resposta do SiTef.

Tipo de parâmetros da função – dividiremos em dois grupos:

1. Quanto ao fluxo de informações: o parâmetro pode ser de entrada ou saída.
2. Quando à passagem: o parâmetro pode ser passado por valor ou por referência. 

Cada rotina descrita neste capítulo, normalmente, possui duas versões/interfaces: 

Interface padrão – tradicional, permite parâmetros com dados binários

Interface ASCII – para interface com linguagens de programação, cujos parâmetros trabalham somente em ASCII.

O que diferencia a versão ASCII da versão padrão é o acréscimo do sufixo A no nome das funções, e a forma / tipo de passagem dos parâmetros.

Interface padrão

Esta interface pode ser utilizada por aplicações escritas nas mais variáveis linguagens de programação que aceitam campos binários. Dentre elas citamos: Delphi, Visual Basic, Visual C.

No caso de comprovantes, o caractere 0x0a (\n em linguagem C) indica o final de uma linha.

Todas as rotinas chamadas pelo aplicativo de automação devem ser do tipo stdcall, ou seja, os parâmetros são empilhados da direita para a esquerda e a rotina chamada é responsável por removê-los da pilha. A convenção dos parâmetros é a seguinte:

Tabela 1: Tipos e convenção de parâmetros

Interface ASCII

Esta interface pode ser utilizada por aplicações escritas em qualquer linguagem de programação, inclusive as que não que aceitam campos binários, tais como o ambiente Forms da Oracle.

Nela todos os parâmetros são passados em ASCII e podem ser de tamanho fixo e variável.

Os campos numéricos são passados sempre com tamanho fixo e alinhados a direita, com zeros a esquerda. Em particular, o campo cujo conteúdo seja um valor negativo, possui um sinal “-“ na posição mais a esquerda do número (p/ex: -0001 para um campo de 5 posições cujo conteúdo é o valor –1).

Os de tamanho variável são construídos de forma que o primeiro caractere indique qual o valor escolhido para ser o delimitador daquele campo ou seja, o campo é delimitado pelo caractere escolhido ou o seu complementar no caso dos pares “( )”, “[ ]”, “{ }” e “< >”.

Exemplos de construções válidas são: (1234), [1234], {1234}, <1234>, $1234$, %1234%, |1234|, etc. 

Exemplos NÃO VÁLIDOS são os seguintes: $12$34$, .1.234,56., etc.

O critério para escolha do delimitador deve ser o de que ele não exista como caractere válido no campo em questão. Nas passagens de dados da aplicação para a CliSiTef, como estes sempre são conhecidos, a aplicação pode definir um caractere padrão e sempre utilizá-lo em todas as passagens de dados. Já no retorno, como qualquer caractere é valido (por exemplo em um comprovante), a regra acima deve ser utilizada na interpretação do resultado devolvido pela CliSiTef uma vez que esta irá escolher o caractere que melhor se adapta a resposta que está sendo gerada.

Finalizando, existe um caractere especial que é utilizado nos textos direcionados para uma impressora. O “\” (barra reversa) indica o final de uma linha e deve ser utilizado pelo aplicativo instruir a impressora para fechar a linha corrente e se posicionar na seguinte.

Configuração da biblioteca

Esta deve ser a primeira chamada para a biblioteca CliSiTef. Ela tem por objetivo configurar os parâmetros de conexão com o servidor SiTef, e com a própria Automação Comercial.

int ConfiguraIntSiTefInterativo (IPSiTef, IdLoja, IdTerminal, Reservado)

int ConfiguraIntSiTefInterativoEx (IPSiTef, IdLoja, IdTerminal, Reservado, ParametrosAdicionais)

Interface ASCII

ConfiguraIntSiTefInterativoA (Resultado, IPSiTef, IdLoja, IdTerminal, Reservado)

ConfiguraIntSiTefInterativoExA (Resultado, IPSiTef, IdLoja, IdTerminal, Reservado, ParâmetrosAdicionais)

As rotinas de configuração retornam um dos seguintes valores:

Tabela 2 - Códigos de retorno das funções de configuração

Configurações especiais gerais

Determinadas configurações gerais (válidas para todas as transações) da CliSiTef podem ser passadas através do parâmetro “ParametrosAdicionais” da rotina ConfiguraIntSiTefInterativoEx. O formato deste campo é o seguinte:

[<Funcionalidade >;<Funcionalidade >;...]

A seguir, descrevemos as funcionalidades previstas neste campo.

Informações adicionais da Automação/Estabelecimento

A configuração ParmsClient permite que a automação comercial possa configurar informações comuns a todas as transações trocadas com o servidor SiTef.

Formato:

[ParmsClient=Id1=Valor1;Id2=Valor2;Id3=Valor3;...;IdN=ValorN]

onde:

<ParmsClient=> = Prefixo identificador dos dados.

<Id_N> = Identificador do campo, conforme definida a tabela abaixo.

<Valor_N> = Valor do campo.

Tabela 3 Códigos de campos disponíveis para ParmsClient.

Exemplo de como enviar dos dados para a CliSiTef:

[ParmsClient=1=31406434895111;2=12523654185985]

Onde:

• 1 (CNPJ do Estabelecimento) com o valor 31406434895111.
• 2 (CNPJ da empresa de automação comercial) com o valor 12523654185985.

Ponto flutuante

Como a automação informa à CliSiTef que sabe tratar campos com ponto flutuante

O tratamento de campos com Ponto Flutuante requer um procedimento executado em conjunto com a automação.

Para que a Clisitef efetue este procedimento que será descrito adiante, é necessário que a automação informe à Clisitef que está apta a tratá-lo. Para isso, a automação deve passar a string abaixo no parâmetro “ParametrosAdicionais” na execução da função ConfiguraIntSiTefInterativoEx.

[TrataPontoFlutuante=1]

Se este parâmetro for omitido e o SiTef solicitar a coleta de campo com Ponto Flutuante, a CliSiTef solicitará à automação, a exibição da mensagem: "Ponto Flutuante nao Suportado pelo PDV".

Procedimento em “operação casada” com a automação

Se foi informado na Configuração, suportar o recurso de Ponto Flutuante, conforme descrito acima, a CliSiTef através do Comando 0 em conjunto com o TipoCampo 2470, informa à Automação a quantidade de casas decimais no parâmetro Buffer, para que esta possa formatar suas telas antes de exibi-las ao operador (Vide Exemplos de Telas na próxima página). Somente após este “pacto” com a Automação, a CliSiTef enviará o comando de coleta do campo com ponto flutuante (através dos comandos 34 ou 30) conforme exemplos abaixo.

• No exemplo onde a quantidade de casas decimais informada foi 2, logo após, a CliSitef solicitará o comando 30:

• No exemplo onde a quantidade de casas decimais informada foi 3, logo após, a CliSitef solicitará o comando 34:

Início da transação de Pagamento ou Gerencial

As rotinas a seguir são as recomendadas para iniciar uma transação na CliSiTef.

O que diferencia a transação a ser executada é o código de Função passado por parâmetro. (Vide Tabela 5.2.2)

As diversas transações iniciadas pela automação comercial ficam agrupadas pelos dados fiscais, que é o par (CupomFiscal, DataFiscal) e com esses dados são realizados os controles de transações pendentes de confirmações da CliSiTef.

A HoraFiscal é importante para validações de segurança de alguns fabricantes de pinpad (com o objetivo de evitar ataques e fraudes).

int IniciaFuncaoSiTefInterativo (Funcao, Valor, CupomFiscal, DataFiscal, HoraFiscal, Operador, ParamAdic)

Interface ASCII

IniciaFuncaoSiTefInterativoA (Resultado, Funcao, Valor, CupomFiscal, DataFiscal, HoraFiscal, Operador, ParamAdic)

int IniciaFuncaoAASiTefInterativo (Funcao, Valor, CupomFiscal, DataFiscal, HoraFiscal, Operador, ParamAdic, Produtos)

Interface ASCII

IniciaFuncaoAASiTefInterativoA (Resultado, Funcao, Valor, CupomFiscal, DataFiscal, HoraDiscal, Operador, ParamAdic, Produtos)

Tabela de códigos de retorno

Tabela de códigos de funções

Os seguintes códigos estão disponíveis para serem usados no parâmetro Funcao descrita acima.

Consulte documentos de produtos específicos para outros códigos de função

Parâmetros Adicionais

Parâmetros adicionais, válidos para a transação corrente, podem ser passadas para CliSiTef através do parâmetro ParamAdic da rotina IniciaFuncaoSiTefInterativo e suas variantes.

Para atender a necessidade de algumas redes “Autorizadoras”, que necessitam de informações sobre o Documento Fiscal Eletrônico emitido pelas “Automações Comerciais”, foram definidas 2 “funcionalidades” para passar os dados necessários no parâmetro ParamAdic (ver detalhes no item Habilitação de configurações especiais por transação).

Consulte o item - Carga de Tabelas no PinPad para maiores informações.

Consulte o item - Informações do PinPad para maiores informações.

Continuação do processo de coleta iterativo

Esta função deve ser chamada de forma contínua até não existam mais informações para serem trocadas entre a aplicação e a CliSiTef (isto é, enquanto seu retorno for igual a 10000), conforme descrito nos resultados devolvidos por ela. O formato de ativação é o seguinte:

int ContinuaFuncaoSiTefInterativo (Comando, TipoCampo, TamMinimo, TamMaximo, Buffer, TamBuffer, Continua)

Interface ASCII

ContinuaFuncaoSiTefInterativoA (Resultado, Comando, TipoCampo, TamMinimo, TamMaximo, Buffer, TamBuffer, Continua)

Obs.: Como nem sempre o campo solicitado pela rotina precisa ser lido no momento da solicitação a rotina aceita o valor 10000 para indicar que o campo não foi coletado naquele momento mas sim previamente, no momento do fechamento da venda.

Um exemplo típico desta situação ocorre quando a automação já fechou com o cliente uma forma de pagamento parcelado com cartão de crédito. Neste caso a automação pode, no momento que a coleta campo for solicitada para ler o número de parcelas, já devolver o número previamente combinado sem capturar esse dado do usuário.

Notar que nessa forma de uso é imprescindível que o dado seja apresentado para o operador que deverá confirmar veracidade dele antes da rotina devolver o mesmo para a CliSiTef.

Notar também que esta forma de uso não é obrigatória, podendo a automação sempre capturar os dados da tela. O uso desta característica poderá alterar o fluxo de coleta ou qualquer regra definida pelas bandeiras, por isso antes de sua utilização realizar consulta a departamento de Suporte da Software Express que verificará a necessidade de autorização prévia pelas bandeiras.

No retorno a rotina devolve os mesmos valores da rotina de Pagamento. Adicionalmente a estes valores, a função devolve o valor 0 (Zero) para indicar que a função solicitada foi concluída com sucesso (p/ex: se for um pagamento, ele foi aprovado pela administradora).

É importante salientar que a chamada que inicia o processo iterativo (aquela que é feita após ter sido recebido o valor 10000 na chamada de uma função de Pagamento, Gerencial, etc...) deve ser feita com Comando, TipoCampo, TamMinimo, TamMaximo e Continua contendo o valor 0 (zero).

Notar também que a automação comercial deve ficar em laço chamando a rotina aqui descrita até que ela receba um resultado diferente de 10000 ou que a própria automação desista de continuar o processo, conforme mostrado a seguir:

Caso a automação deseje encerrar o processo de coleta ela deve, necessariamente, chamar a rotina ContinuaFuncaoSiTefInterativo passando –1 (menos um) no campo Continua. Caso o processo de coleta deva continuar, ela não deve modificar nenhum dos campos preenchidos pela CliSiTef a não ser o Buffer que, na nova chamada, deve conter o resultado da coleta (se Comando diferente de 0) ou o dado original se Comando veio com 0. Notar ainda que mesmo que o Buffer contenha um campo coletado pela automação, o seu tamanho deve ser o recomendado por esse documento pois irá conter, no retorno, novos dados fornecidos pela rotina.

Notar que o campo Buffer pode ter sido preenchido pela rotina com algum dado para ser memorizado, apresentado no visor ou outro motivo, segundo o que está especificado na descrição de cada comando que o aplicativo de automação deve tratar.

Tabela de códigos de Comando

A seguir apresentamos os valores possíveis para o parâmetro Comando e a ação que a aplicação deve executar ao recebê-lo. É importante que a automação comercial trate todos os comandos desta tabela.

Vide Verificação da integridade de um código em barras para maiores informações.

Tabela de valores para TipoCampo

A seguir apresentamos os valores possíveis para o campo TipoCampo e respectivos significados: 

Os campos marcados com * indicam que são utilizados em um ou mais produtos.

Note que nem todos os campos são retornados em todas as transações. Além disso, existem campos que somente são retornados se a transação foi aprovada.

Consulte documentos de produtos específicos para outros códigos de campo.

Tabela de Eventos, retornados também em TipoCampo

Durante a transação, a CliSiTef pode informar a ocorrência de determinados eventos.

Estes eventos são retornados no parâmetro TipoCampo da rotina ContinuaFuncaoSiTefInterativo ou ContinuaFuncaoSiTefInterativoA, conforme a tabela abaixo.

Confirmação ou não do Pagamento

Rotina chamada pelo aplicativo para fechar o ciclo transacional. Ela deve ser acionada no momento que o comprovante Fiscal for fechado e recebe como parâmetros um indicador de se a transação foi concretizada ou se deve ser estornada. Recebe também os campos que permitem identificar a transação que está sendo finalizada.

Esta função também deve ser utilizada para desfazer uma transação interrompida por uma queda de energia ou qualquer outro problema no aplicativo.

Essa rotina confirma ou cancela TODOS os pagamentos vinculados ao mesmo Número do Cupom Fiscal e mesma Data Fiscal passados como parâmetro.

void FinalizaFuncaoSiTefInterativo (Confirma, CupomFiscal, DataFiscal, HoraFiscal, ParamAdic);

Interface ASCII

void FinalizaFuncaoSiTefInterativoA (Confirma, CupomFiscal, DataFiscal, HoraFiscal, ParamAdic);

Exemplo: Uma venda realizada pela função IniciaFuncaoSiTefInterativo, passando como parâmetros Funcao 0, Valor 10,00, Cupom Fiscal 12345, Data Fiscal 20150101, Hora Fiscal 121500. Na confirmação da transação, a função

*O parâmetro HoraFiscal não é usado como “chave” para um documento fiscal.

FinalizaFuncaoSiTefInterativo deve ser chamada utilizando os seguintes parâmetros: Confirma 1, Cupom Fiscal 12345, Data Fiscal 20150101, Hora Fiscal 121500, ParamAdic como vazio/NULL, já que não há dados adicionais.

O parâmetro ParamAdic pode ser usado nas situações abaixo:

Finalização de pagamentos individuais em um mesmo cupom fiscal

Para cada pagamento, a CliSiTef retorna no TipoCampo 161 (Número do pagamento no cupom) um índice/contador correspondente ao pagamento.

Para fazer a (não-) confirmação de um pagamento específico dentro de um cupom fiscal, a automação deve informar este valor à rotina FinalizaFuncaoSiTefInterativo como um parâmetro adicional:

{NumeroPagamentoCupom=XXX}

onde XXX é o número do pagamento, retornado anteriormente no TipoCampo 161.

Finalização de pagamentos de uma determinada rede em um mesmo cupom fiscal

Para fazer a (não) confirmação de pagamentos referentes a uma determinada rede autorizadora, deve-se passar na rotina FinalizaFuncaoSiTefInterativo o seguinte parâmetro adicional:

{RedeConfirmacao=XXX}

onde XXX é o número da rede autorizadora.

Anexar dados referentes às formas de pagamento de uma transação (NFPAG)

Para anexar dados referentes às formas de pagamento de uma transação, devem-se capturar os campos: 161 (Número do pagamento no cupom), 730 (Número máximo de formas de pagamento), 731 (Tipos de pagamento habilitados) e 732 (Dados a serem coletados para o tipo de pagamento), retornados no fluxo da transação, e repassá-lo à rotina FinalizaFuncaoSiTefInterativo através dos parâmetros adicionais NumeroPagamentoNFPAG e NFPAG.

{NumeroPagamentoNFPAG=X}{NFPAG=Y}

Onde:

X = Número do pagamento no cupom (Campo 161)

Y = Dados referentes às formas de pagamento (Ver descrição abaixo)

Observação: Neste caso, todos os pagamentos em um mesmo cupom fiscal serão todos confirmados ou não confirmados.

Descrição do parâmetro NFPAG:

{NFPAG=FPAG1;FPAG2; FPAG3;...;FPAGn;}

Onde FPAGn tem o seguinte conteúdo:

=> TipoN: indica a forma de pagamento utilizada (Campo 731, conforme tabela abaixo)

=> ValorN: indica o valor utilizado com esta forma de pagamento, com duas casas decimais, sem a vírgula

=> IDColetaNn: indica o ID do campo que foi coletado pelo PDV (Campo 732, conforme tabela abaixo)

=> DadoColetaNn: indica o conteúdo coletado pelo PDV para este campo

Observação: A consistência dos valores (soma das várias formas de pagamento utilizadas, totalizando o valor da transação realizada) deve ser feita pelo PDV.

Exemplo:

Ao final de uma transação no valor de R$ 50,00, retornando o campo 730 igual a 2 e os campos 731 e 732 indicando que aceita as seguintes formas de pagamento: Dinheiro (sem dados a serem coletados); TEF Débito (precisa enviar a Rede Destino, o NSU do Host, a Data do Host e o Código de Origem da transação de TEF) e TEF Crédito. O campo 730 igual a 2, indica que no parâmetro NFPAG podem ser enviados no máximo 2 formas de pagamento.

O PDV, por sua vez, na confirmação da transação, enviará as formas de pagamento que foram efetivamente utilizadas: R$ 30,00 foram pagos em dinheiro e R$ 20,00 foram pagos com cartão de débito da Redecard (Rede Destino = 5; NSU do Host = 123456789; Data do Host = 15/12/2008; Código de Origem = 000000000000001).

{NFPAG=00:3000;02:2000:03:5-07:123456789-08:15122008-09:000000000000001;}

Observação: Todas as formas de pagamento devem ser separadas por ; (ponto-e-vírgula), inclusive o último deve ser finalizado por ;

O campo de ID 13, diferente dos demais, não indica um campo que deve ser coletado, ele funciona apenas como um complemento para o campo de ID 03, enviando a lista de Redes Destino permitidas, no seguinte formato:

IDColetaNn(Rede1,Rede2,...,RedeN)

Ou seja, caso apenas o campo de ID 03 esteja presente, deve ser coletada a Rede Destino, sem nenhuma restrição quanto as Redes que podem pagar a Recarga. No entanto, caso estejam presentes os campos de ID 03 e 13, o primeiro indica que deve ser coletada a Rede Destino, enquanto o segundo indica quais as Redes Destino que são permitidas para o pagamento da Recarga.

Além disso, como a coleta foi indicada pelo ID 03, o PDV deve enviar a Rede Destino ao Sit também por meio deste ID (e não pelo ID 13).

Consulta de transações pendentes de confirmação no terminal

Em caso de queda de energia, pode ocorrer situações em que a automação precise consultar transações que estejam pendentes de confirmação. Isto é, transações que precisam ser confirmadas (ou não) via FinalizaFuncaoSiTefInterativo.

Quantidade de transações pendentes de confirmação no terminal

Esta função é utilizada pelo terminal para saber quantas transações foram realizadas em caso de queda de energia e que estão pendentes de uma ação da automação, via chamada da função FinalizaFuncaoSiTefInterativo.

int ObtemQuantidadeTransacoesPendentes (DataFiscal, CupomFiscal)

Interface ASCII

ObtemQuantidadeTransacoesPendentesA (Resultado, DataFiscal, CupomFiscal)

A rotina retorna a quantidade de transações pendentes para o documento fiscal informado, ou -13 caso não tenha sido encontrado o documento fiscal.

Consulta a transações pendentes no terminal

É possível consultar todas as informações de pendências de confirmação do terminal.

Essa funcionalidade é iniciada através da função IniciaFuncaoSiTefInterativo com o parâmetro Funcao (primeiro parâmetro de entrada da rotina) assumindo o valor 130 e os demais parâmetros com seus valores usuais.

Em particular, esta função irá desconsiderar os parâmetros relativos ao documento fiscal.

Os campos a seguir serão retornados para a automação.

Consulta a transações pendentes em um documento fiscal específico

De forma análoga ao item anterior, é possível consultar os dados referentes a um único documento fiscal.

Para tanto, utilize a função IniciaFuncaoSiTefInterativo passando no parâmetro Funcao o valor 131 e os demais parâmetros com seus valores usuais. Neste caso, serão considerados os parâmetros relativos ao documento fiscal.

Os campos retornados são idênticos ao item anterior.

Funções de PinPad

Teste da presença de PinPad

É possível verificar a presença do dispositivo PinPad e se ele está operacional. Para tanto, são enviados comandos lógicos de abertura e fechamento do canal de comunicação.

São duas as funções para esta finalidade. A função original tem o seguinte formato:

int VerificaPresencaPinPad (void)

A partir da versão 4.0.114.4, foi criada uma segunda função, onde são enviados menos comandos para o pinpad, e sem que o visor do pinpad ligue/desligue.

int KeepAlivePinPad (void)

Ambas rotinas não possuem parâmetros de entrada, e podem retornar os seguintes valores: 

1 - Existe um PinPad operacional conectado ao micro;

0 - Não existe um PinPad conectado ao micro;

-1 - biblioteca de acesso ao PinPad não encontrada;

outro número - erros detectados internamente pela rotina ou pela biblioteca de acesso ao PinPad

Define mensagem permanente para o PinPad

Permite que seja definida uma mensagem permanente para ser apresentada no PinPad durante o tempo que ele não está em uso. O formato de ativação da rotina é o seguinte:

int EscreveMensagemPermanentePinPad (Mensagem)

Interface ASCII

EscreveMensagemPermanentePinPadA (Resultado, Mensagem)

Para apagar a mensagem e deixar o visor em branco, basta chamar essa função passando o campo Mensagem vazio.

A aplicação, se desejar, pode incluir o caractere ‘|’ (Barra vertical) para indicar uma mudança de linha.

Leitura da trilha 3 do cartão

Esta função permite que o aplicativo capture uma trilha 3 magnética genérica. 

Note que o PinPad deve ter suporte para a leitura da trilha 3.

Não deve ser utilizada para tratamento das transações de pagamento mas apenas para leitura de cartões internos do estabelecimento comercial (p/ex. cartão de supervisor). O formato de ativação é o seguinte:

int LeTrilha3 (Mensagem)

No retorno, a rotina devolve os mesmos valores que a rotina de pagamento. O aplicativo obtém as trilhas através da chamada a função de continuação do processo iterativo.

Leitura do cartão - rotinas de captura segura

Os rotinas seguintes têm seu funcionamento condicionado a dois pré-requisitos:

1. Configuração do arquivo de chaves .cha no servidor SiTef. Caso a configuração não esteja feita, essas funções retornam o erro 12 (MODO SEGURO NÃO ATIVO).
2. Após a instalação do arquivo de chaves .cha no servidor SiTef, a Automação deve, pelo menos uma vez, se comunicar com o servidor SiTef. Isto é necessário para que a estação PDV faça a baixa dos dados que permitem a execução das rotinas de Leitura do cartão seguro). Para isso, execute um Teste de Comunicação ou uma transação financeira.

int LeCartaoSeguro (Mensagem)

Interface ASCII

LeCartaoSeguroA (Resultado, Mensagem)

No retorno a rotina devolve os mesmos valores que a rotina de pagamento. O aplicativo obtém as trilhas através da chamada a função de continuação do processo iterativo.

Os campos retornados no processo iterativo são os referentes aos campos sensíveis (2021 a 2046). 

Observação:

Estas funções não estão disponíveis para ambientes Mobile. Devido a dificuldades de utilização de entrypoints de funções, e visando facilitar a sua implementação, foi disponibilizada a “Função” 430 que é uma alternativa para utilizar a função “LeCartaoSeguro”.

Esta “Função” segue o fluxo de uma transação “Gerencial” e é acessada através de IniciaFuncaoSiTefInterativo(Ver item “5.2 - Início da transação de Pagamento ou Gerencial”).

• Para utilização da “Função” 430, o parâmetro “Mensagem” a ser exibida no display do pinpad, será solicitada à Automação Comercial no fluxo da transação através do comando 29 (Ver item “5.3.1 - Tabela de códigos de Comando”). Caso não seja fornecida pela Automação, será exibida a mensagem default “PASSE O CARTAO”.
• Para leitura do cartão através da função 430, foi incluído o parâmetro adicional “SementeHash”(não utilizada quando a função LeCartaoSeguro é chamada diretamente) que é opcional e será solicitado no fluxo da transação. Se parâmetro “SementeHash” for utilizado, opcionalmente poderá ser fornecida através do parâmetro “ParamAdic” na chamada da função IniciaFuncaoSiTefInterativo, neste caso, não será solicitado no fluxo da transação.

Se solicitado no fluxo da transação através do comando 29 e o parâmetro não é utilizado, retornar o campo vazio.

Caso este parâmetro seja utilizado, os dados retornados para a Automação Comercial serão hash geradas a partir da semente informada (Campo tipo 203x. Ver tabela “Campos que podem ser retornados” abaixo).

Formato do parâmetro em “ParamAdic”:

{SementeHash=XX...XX}

Onde: XX...XX: Máximo 64 caracteres.

int LeCartaoDiretoSeguro (Mensagem, TipoCampoTrilha1, Trilha1, TipoCampoTrilha2, Trilha2, Timeout, TestaCancelamento)

Interface ASCII

LeCartaoDiretoSeguroA (Resultado, Mensagem, TipoCampoTrilha1, Trilha1, TipoCampoTrilha2, Trilha2, Timeout)

No retorno a rotina devolve o valor 0 (zero) caso tenha sido executada corretamente e um valor diferente de zero em caso de erro ou interrupção.

Para esta rotina específica, os códigos de erro retornados são:

Os campos TipoCampoTrilha1 e TipoCampoTrilha2 indicam o tipo de campo retornado, respeitando o valor estabelecido para os campos sensíveis, com 202x para campos abertos mascarados, 203x para o Hash dos campos, 204x para campos criptografados e 205x.

Campos que podem ser retornados:

* As novas implementações devem utilizar o campo 203x, pois o campo 205x devolve um hash criptografado utilizando a chave de criptografia inserida pelo cliente no arquivo .cha. Essa forma de uso (205x) existe apenas por compatibilidade, pois o ideal é utilizar o Hash com Salt (Semente - 203x) uma vez que a informação utilizada para gerar o hash fica escondida apenas dentro das aplicações que o utilizam, tornando o processo de reversão do hash até obter o dado original praticamente impossível de ser executado pela força bruta.

int LeCartaoDiretoSeguroEx (Mensagem, DadosOut, TamDadosOut, Timeout, TestaCancelamento)

Interface ASCII

LeCartaoDiretoSeguroExA (Resultado, Mensagem, DadosOut, TamDadosOut, Timeout)

int LeTrilhaChipInterativo (Modalidade) 
LeTrilhaChipInterativoEx (Modalidade, ParamAdic)

Interface ASCII

LeTrilhaChipInterativoA (Resultado, Modalidade)

Essas funções funcionam da mesma maneira das LeCartaoSeguro/LeCartaoSeguroA, com a diferença que estas aceitam cartões com chip.

Observação:

Estas funções, “LeTrilhaChipInterativo”, “LeTrilhaChipInterativoEx” e “LeTrilhaChipInterativoA” não são exportadas para ambiente Mobile. Devido a dificuldades de utilização de entrypoints de funções, neste ambiente, e visando facilitar a sua implementação, foi disponibilizada a “Função” 431 para acesso à função “LeTrilhaChipInterativoEx”. Esta “Função” segue o fluxo de uma transação “Gerencial” e é acessada através de IniciaFuncaoSiTefInterativo(Ver item “3.2 Início da transação de Pagamento ou Gerencial”).

• Para utilização da “Função” 431, o parâmetro “Modalidade”(Tipo do pagamento) e “ParamAdic”(SementeHash), serão solicitados à Automação Comercial no fluxo da transação através do comando 29 (Ver item 3.3.1 Tabela de códigos de Comando).
• Se parâmetro “SementeHash” for utilizado, opcionalmente poderá ser fornecida através do parâmetro “ParamAdic” na chamada da função IniciaFuncaoSiTefInterativo, neste caso, não será solicitado no fluxo da transação. Se solicitado no fluxo da transação através do comando 29 e o parâmetro não é utilizado, retornar o campo vazio.

Caso este parâmetro seja utilizado, os dados retornados para a Automação Comercial serão hash geradas a partir da semente informada (Campo tipo 203x. Ver tabela “Campos que podem ser retornados” acima).

Leitura de senha

Esta função permite que o aplicativo capture no PinPad uma senha de um cliente de cartão do próprio estabelecimento comercial (cartão proprietário). Não deve, em nenhuma hipótese, ser utilizada para captura de senhas dos cartões tradicionais. Para maiores detalhes, consulte o documento “Acesso a Senha do Cliente para Cartão Proprietário CliSiTef.doc”.

int LeSenhaInterativo (ChaveSeguranca)

Interface ASCII

LeSenhaInterativoA (Resultado, ChaveSeguranca)

No retorno a rotina devolve os mesmos valores que a rotina de pagamento. O aplicativo obtém a senha através da chamada a função de continuação do processo iterativo.

int LeSenhaDireto (ChaveSeguranca, SenhaCliente)

Interface ASCII

LeSenhaDiretoA (Resultado, ChaveSeguranca, SenhaCliente)

No retorno a rotina devolve o valor 0 (zero) caso tenha sido executada corretamente e um valor diferente de zero em caso de erro ou cancelamento pelo usuário.

Leitura de Confirmação pelo Cliente no PinPad

Estas funções permitem que o aplicativo solicite uma confirmação no PinPad. O formato de ativação é o seguinte:

int LeSimNaoPinPad (Mensagem)

Interface ASCII

LeSimNaoPinPadA (Resultado, Mensagem)

No retorno a rotina devolve 0 se o cliente pressionou a tecla de Cancelamento, 1 se ele pressionou a tecla de Confirmação e outro valor em caso de erro no acesso ao PinPad.

Notar que essa função não é iterativa ou seja, o controle de execução somente volta para a aplicação após o pressionamento da tecla.

Define uma mensagem momentânea para o PinPad

Permite que seja definida uma mensagem momentânea para ser apresentada no display do PinPad. O formato de ativação da rotina é:

int EscreveMensagemPinPad (Mensagem)

Para apagar a mensagem e deixar o visor em branco, basta chamar essa função passando o campo Mensagem vazio.

A aplicação, se desejar, pode incluir o caractere ‘\r’ (carriage return) para indicar uma mudança de linha.

Leitura de teclas especiais do PinPad

Essa função é utilizada para aguardar o pressionamento de uma tecla no pinpad, retornando seu código correspondente. O formato de ativação da rotina é:

int LeTeclaPinPad (void)

No retorno a rotina devolve:

Por questão de segurança, este comando não retorna teclas numéricas, sendo que o pressionamento destas teclas é simplesmente ignorado pelo pinpad durante a execução do comando.

Notar que essa função não é iterativa ou seja, o controle de execução somente volta para a aplicação após o pressionamento de uma tecla.

Observação sobre o uso desta função para obter as teclas F1, F2, F3 e F4: há alguns pinpads no mercado que não possuem as teclas F1, F2, F3 e F4. Portanto ao utilizar esta função, deve-se deixar um plano B para estes casos.

Remover cartão inserido no PinPad

Essa função é utilizada para solicitar a retirada do cartão inserido no pinpad. É utilizada em conjunto com o parâmetro “AdiaRemocaoCartao” (Ver documento CliSiTef - Lista de parâmetros adicionais – 1.17.pdf, item 4.3 Função IniciaFuncaoSiTefInterativo).

int RemoveCartaoPinPad (short (CALLBACK *pTestaCancelamento) (void *lpvParam), void
*lpvParam);

A função retorna OK (0) após a retirada do cartão do pinpad ou se não existir cartão inserido

Correspondente Bancário (Pagamento de Contas)

Esta função permite que o aplicativo de automação aceite o pagamento de contas diversas de acordo com o contrato firmado entre ele e um Banco Correspondente. O formato de ativação desta funcionalidade é o seguinte:

int CorrespondenteBancarioSiTefInterativo (CupomFiscal, DataFiscal, Horario, Operador, ParamAdic)

Interface ASCII

CorrespondenteBancarioSiTefInterativoA (Resultado, CupomFiscal, DataFiscal, Horario, Operador, ParamAdic)

Onde os parâmetros possuem a mesma função já descrita para o Pagamento.

A lógica de funcionamento desta função é a mesma no pagamento de uma compra feita pelo cliente ou seja, deve-se chamar a função ContinuaFuncaoSiTefInterativo até que o resultado seja diferente de 10000.

Essa função, dada a diversidade de produtos ofertados pelos Bancos Correspondentes pode, inclusive, executar uma operação de TEF para concretizar o pagamento de uma conta.

Notar que os campos de retorno 600 a 604 retornam diversas vezes, uma para cada título ou convênio pago, no caso de pagamento em lote. O campo 607 indica qual o índice (seqüência) de pagamento ao qual se referem os campos 600 a 604 que virão a seguir.

No ParamAdic pode ser passado: {PortaPinPadCB=<porta>}, em que <porta> indica a porta em que está conectado o pinpad especifico para transações de Correspondente Bancário: consulta saldo, saque e recarga celular Bradesco.

Verificação da integridade de um código em barras

Permite, na coleta manual dos campos presentes em um código em barras, que o aplicativo faça a validação a medida que os campos estão sendo digitados, de forma a alertar o operador antecipadamente e permitir que ele corrija o erro. O formato de ativação da rotina é o seguinte:

int ValidaCampoCodigoEmBarras (Dados, Tipo)

Interface ASCII

ValidaCampoCodigoEmBarrasA (Resultado, Dados, Tipo)

Recomendação:

É recomendável que aplicação do terminal, uma vez identificado que o documento será digitado, abra campos de coleta simulares aos presentes nos documentos a serem pagos. Para isso ela precisará identificar se é uma Ficha de Compensação/Titulo/Bloqueto ou Ficha de Arrecadação/Tributos. Essa identificação pode ser feita mediante uma pergunta ao operador ou através da rotina aqui descrita.

Se o usuário optar pelo reconhecimento automático ele deve abrir um campo como se fosse de Arrecadação e, a cada digito fornecido pelo operador, passar os dígitos já fornecidos para a rotina. Esse procedimento deve ser feito até o momento que a rotina devolver se o documento em questão é um Título ou Arrecadação. Nesse momento a aplicação não precisa mais chamar a rotina a cada dígito fornecido e deve, se necessário, modificar a formatação dos campos para captura.

Além da identificação do tipo do documento a rotina faz a consistência dos dígitos verificadores, retornando para aplicação se existe um erro e onde ele está localizado. A aplicação pode chamar a rotina passando os campos à medida que eles forem sendo coletados ou no final da coleta, onde será feita uma análise global do conteúdo digitado. Se a chamada for durante a digitação, os pontos corretos são:

• Arrecadação: a cada um dos 4 blocos de digitação
• Títulos: a cada grupo de dois blocos de digitação

No retorno a rotina devolve 0 se tudo estiver correto até o momento, -1 se for um código em barras não reconhecido ou um número de 1 a 4 indicando qual o campo está incorreto ou ainda o valor 5 para indicar que o número como um todo não está correto.

Exemplificamos a seguir como a aplicação do terminal deveria proceder, na forma mais genérica possível hoje em dia, para coletar um documento. No exemplo utilizaremos um título e deixaremos a automação ser informada que é esse tipo de documento. O documento que será utilizado é o seguinte:

23790.09505.91211.369656.04025.039209.1.17690000005625

Campo aberto pela automação

Após a digitação do primeiro número chama a rotina passando “2” como parâmetro. No retorno a rotina devolveu o resultado 0 e Tipo = 0 (fictício pois nesse momento, para a configuração atual de códigos em barra, ela já teria feito a identificação)

Após a digitação do primeiro número chama a rotina passando “23” como parâmetro. No retorno a rotina devolveu o resultado 0 e Tipo = 1

A automação reapresenta os campos já sabendo que é um título. Somente após a digitação do primeiro grupo de números ela chama a rotina passando “2379009505” como parâmetro. No retorno a rotina continua a devolver Tipo = 1. Já o resultado poderá ser 0, indicando que o bloco está correto ou 1 indicando que ele está errado.

A automação continua a coletar os dígitos e somente após a digitação do segundo grupo de números ela chama a rotina passando “237900950591211369656” como parâmetro. No retorno a rotina continua a devolver Tipo = 1. Já o resultado poderá ser 0, indicando que os blocos estão corretos ou 1 ou 2 indicando que o primeiro ou o segundo bloco está errado.

A automação continua a coletar os dígitos chamando a rotina no final do terceiro bloco com os dados 237900950591211369656 e no final do quarto bloco com todos os dados digitados. No retorno a rotina continua a devolver Tipo = 1 e o resultado refletirá a situação de erro ou não dos blocos passados como parâmetro. Em particular, se retornar o código 5 é porque existe algum dos blocos (não é possível identificar qual deles) com erro.

Finalizando, a automação também pode para efeito de consistência do código em barras optar por conferi-los apenas no final da digitação de todos os campos. Nesse caso, a rotina devolverá 1, 2, 3 ou 4 nessa ordem de prioridade caso encontre um ou mais blocos com erro e 5 na situação dos blocos internos estarem certos, mas o número como um todo possui algum erro.

Obtendo Versão

Esta função é utilizada pelo terminal para obter as versões da CliSiTef e CliSiTefI.

int ObtemVersao (VersaoCliSiTef, VersaoCliSiTefI)

Interface ASCII

ObtemVersaoA (Resultado, VersaoCliSiTef, VersaoCliSiTefI)

No retorno a rotina devolve 0 quando foi executada com sucesso e diferente no caso de erro.

Enviando mensagens pendentes

Em situações de falha de comunicação com o servidor SiTef, a CliSiTef enviará automaticamente eventuais dados remanescentes (por exemplo, dados de confirmação, não-confirmação e desfazimento) somente na próxima transação do PDV.

Porém, pode levar algum tempo até que a próxima transação seja iniciada na estação.

Nos momentos em que o PDV está no estado repouso ou “idle”, a automação pode utilizar a seguinte rotina para forçar a biblioteca a descarregar mensagens de confirmação, não confirmação e desfazimento para o servidor SiTef.

int DescarregaMensagens (void)

No retorno a rotina devolve 0 se conseguiu descarregar todas as mensagens e diferente de zero caso ocorra algum erro impossibilitando o envio das mesmas.

Informações do PinPad

Existem duas formas para obter informações básicas do PinPad conectado no PDV, tais como número de série, modelo, etc.

ObtemInformacoesPinPad – função direta.

Através de código de função passada à IniciaFuncaoSiTefInterativo, e consequente processo iterativo. 

A primeira forma é utilizando a função abaixo.

int ObtemInformacoesPinPad (InfoPinPad)

Em caso de sucesso, os dados serão retornados no seguinte formato: 

2 caracteres numéricos que indicam a informação obtida sendo:

1. para o Nome do fabricante,
2. para o Modelo / versão do hardware,
3. para a Versão do software básico/firmware, 04 Versão da especificação compartilhada
4. para a Versão da aplicação básica,
5. para o Número de série.

3 caracteres numéricos que indicam o tamanho em caracteres da informação. 

N (conforme tamanho acima) caracteres alfanuméricos com a informação.

Exemplo:

01006GERTEC02010PPC900;3MB030190077_0071_0080_0106040041.0605013001.23

100820060160450805232030714

Nome do fabricante : GERTEC

Modelo / versão do hardware : PPC900;3MB

Versão do software básico/firmware : 0077_0071_0080_0106 

Versão da especificação : 1.06

Versão da aplicação básica : 001.23 100820 

Número de série : 0450805232030714

Já na segunda forma, a automação deve passar o código de função 775 para a IniciaFuncaoSiTefInterativo, e prosseguir no fluxo de coleta como se fosse uma transação.

Durante o fluxo de coleta, os seguintes campos serão retornados para a automação, normalmente pelo comando 0 (zero).

Carga de Tabelas no PinPad

Denomina-se carga de tabelas no pinpad o processo onde é feito a carga de informações de aplicações e parâmetros de chip no pinpad.

Este processo viabiliza a leitura de um cartão com chip durante as transações.

Normalmente a CliSiTef faz esta operação automaticamente, sob demanda, ao perceber que é necessária uma nova carga de parâmetros. Existem vários motivos para isso, por exemplo a troca de pinpad no PDV, ou então uma alteração de parâmetros do estabelecimento no lado do autorizador.

A automação pode comandar uma nova carga de tabelas no pinpad. Por exemplo, para reduzir a chance de uma carga na primeira venda do dia, a automação pode iniciar uma carga quando estiver em estado de repouso (idle) e, desta forma, diminuir o tempo no primeiro atendimento.

Note que, se houver uma alteração de parâmetros por parte do autorizador, esta mudança refletirá uma nova carga de tabelas durante o dia.

Com alteração na Automação

Para que a automação comande a carga de tabelas no pinpad, são oferecidos três códigos de função que devem ser usadas na IniciaFuncaoSiTefInterativo.

A função 770 realiza a carga de tabelas no pinpad caso seja necessário. Isto é, se os dados do servidor SiTef já estiverem carregados no pinpad, nenhuma carga será feita.

A função 771 força a carga de tabelas no pinpad de acordo com as tabelas baixadas previamente do servidor SiTef e que estão armazenadas localmente no PDV.

Já a função 772 faz com que a clisitef apague os dados locais do PDV, baixando do SiTef uma nova fotografia destes parâmetros, e a seguir faz a carga de tabelas no pinpad.

Sem alteração na Automação

Para que a automação se beneficie da carga de tabelas sem ter que programar as chamadas da IniciaFuncaoSiTefInterativo com os três códigos de função 770, 771 e 772, foram incluídas no menu Administrativo da CliSiTef, três transações equivalentes.

No exemplo acima,

• a opção 11 equivale à Funcao 770;
• a opção 12 equivale à Funcao 771;
• a opção 13 equivale à Funcao 772.

Para habilitar a transação de Carga de tabelas no pinpad, é necessário incluir na seção [Geral] a chave TransacoesAdicionaisHabilitadas o valor 3624.

Para habilitar a transação de Carga forcada de tabelas no pinpad (Local), é necessário incluir na seção [Geral] a chave TransacoesAdicionaisHabilitadas o valor 3625.

A transação de Carga forcada de tabelas no pinpad (SiTef) está habilitada de forma padrão, com o valor 3626.

[Geral] TransacoesAdicionaisHabilitadas=3624;3625

Tratamento para Múltiplos Pagamentos

Transações que envolvem o pagamento de uma compra com mais de um pagamento TEF caracteriza-se como Pagamento com Múltiplos TEFs.

Para que tudo ocorra bem neste processo, o PDV deverá seguir as seguintes recomendações:

1. – Para todas as transações TEF que forem realizadas, deve-se utilizar no comando IniciaFuncaoSiTefInterativo sempre o parâmetro CupomFiscal com o mesmo número, vinculando-as ao cupom fiscal vigente, referente à compra que está sendo paga com mais de um TEF; além do mesmo CupomFiscal, o parâmetro DataFiscal também deve ser o mesmo usado em todas as compras, pois os parâmetros para a FinalizaFuncaoSiTefInterativo fazer corretamente a confirmação ou não confirmação de todos os TEFs vinculados, são CupomFiscal e DataFiscal.
2. – Ao realizar o pagamento, se tudo foi OK, a transação devolverá um Cupom TEF a ser impresso pela automação comercial. Esse cupom deve ser mantido em memória e a venda ficará pendente.
3. – Efetuar N pagamentos TEF até que o valor final da venda esteja completamente pago.
4. – Caso ocorra alguma falha no pagamento TEF como:

• O autorizador não respondeu (time-out)
• Deu algum erro de validação na CliSiTef ou no SiTef
• A transação foi negada pelo autorizador
• O operador abortou a transação

A transação se encerra, com o fluxo da ContinuaFuncaoSiTefInterativo finalizando com o retorno diferente de 0 (zero), e nenhuma ação mais deverá ser efetuada pelo PDV naquele momento, referente à transação TEF vigente. Ou seja, o fluxo daquela venda se encerrou, sem que fosse efetuado o TEF. Para tanto, o PDV deverá efetuar mais TEF(s) ou completar a diferença faltante com outra forma de pagamento.

1. – Quando o valor da transação de compra estiver completamente pago, basta o envio da FinalizaFuncaoSiTefInterativo com o parâmetro Confirma com valor 1 e com os parâmetros CupomFiscal e DataFiscal idênticos aos usados nas vendas TEF e o fluxo de Múltiplos Pagamentos (TEF) terá sido encerrado com sucesso; ou seja, todas as transações que estavam pendentes e vinculadas àquele CupomFiscal e DataFiscal ficarão com o Status de EFETUADA no relatório do SiTef.
2. – Se porventura:

• o cliente desistiu da compra; ou
• ocorreu queda de energia; ou
• acabou o papel da impressora no meio da impressão do(s) cupom(ns) TEF;

ou por algum outro motivo qualquer em que a compra não foi concluída e o cliente não levou a mercadoria, o PDV deverá enviar a não confirmação da transação (comando FinalizaFuncaoSiTefInterativo com o parâmetro Confrma igual a 0 e os parâmetros CupomFiscal e DataFiscal idênticos aos usados nas vendas TEF), não confirmando desta forma todas as transações TEF que foram realizadas com aquele CupomFiscal e DataFiscal.

E então o PDV terá encerrado o fluxo de Múltiplos Pagamentos com insucesso, fazendo com que todas as transações que estavam pendentes referentes àqueles CupomFiscal e DataFiscal sejam canceladas (não confirmadas). O Status das transações TEF que estavam pendentes no relatório ficará como CANC.PDV.

1. – Tratamento para Múltiplos Pagamentos que possam ocorrer em uma virada de dia:

Caso ocorra de um ou mais TEFs iniciem em um dia (DD) e outro(s) sejam feitos no dia seguinte (DD + 1), haverá a necessidade de se realizar duas confirmações / não confirmações, porque as confirmações e não confirmações são amarradas pelos parâmetros: CupomFiscal e DataFiscal.

Caso fosse realizada uma venda em dia DD + 1, e usada a data DD para DataFiscal, o pinpad poderia apresentar problemas em seu funcionamento, ocasionando efeitos colaterais.

O ideal para este caso é que:

• para o caso de sucesso nos Múltiplos TEFs sejam enviadas duas confirmações (função FinalizaFuncaoSiTefInterativo com o parâmetro Confirma com valor 1): uma com CupomFiscal e DataFiscal do dia DD e outra com o número de CupomFiscal e DataFiscal da data DD + 1.
• em caso de insucesso sejam enviadas duas não confirmações (função FinalizaFuncaoSiTefInterativo com o parâmetro Confirma com valor 0): uma com CupomFiscal e DataFiscal do dia DD e outra com o número de CupomFiscal e DataFiscal da data DD + 1.
• Não há a necessidade de se manter o número do CupomFiscal quando há a virada do dia.
• Verificar se ao final, tanto de sucesso, quanto de insucesso, se as transações envolvidas no processo mudaram o Status para diferente de PENDENTE.

TEF (Crédito ou Débito) para Pagamento de Carnê

Alguns adquirentes fornecem aos estabelecimentos taxas diferenciadas para pagamento de boletos/contas ou para pagamento da fatura do cartão de crédito. Para que o adquirente que possui essas taxas diferenciadas possa distinguir um TEF “normal” de um TEF para pagamento de Carnê, deve-se informar pela CliSiTef uma modalidade diferenciada para informar aos módulos do SiTef que trata-se de um TEF para pagamento de contas ou pagamento de fatura de cartão de crédito.

Débito para Pagamento de Carnê

Na CliSiTef deve-se chamar a função/modalidade: 16

Caso o módulo em questão trate a funcionalidade Débito para Pagamento de Carnê, a CliSiTef devolve o campo 2361 com o valor 1, informando que aquela transação foi acatada como Débito para Pagamento de Carnê; caso o campo não retorne ou retorne com o valor 0, a transação foi realizada como Débito normal.

OBSERVAÇÃO: Cabe à automação comercial fazer o tratamento correto deste campo 2361 para aceitar a transação ou não em caso do seu não retorno ou retorno do campo com o valor 0, pois a CliSiTef não irá barrr a transação pelo fato do módulo não aceitar a transação de Crédito para Pagamento de Carnê, ocasionando então a realização de uma transação de Débito normal, sem a taxa diferenciada.

Crédito para Pagamento de Carnê

Na CliSiTef deve-se chamar a função/modalidade: 17

Caso o módulo em questão trate a funcionalidade Crédito para Pagamento de Carnê, a CliSiTef devolve o campo 2363 com o valor 1, informando que aquela transação foi acatada como Crédito para Pagamento de Carnê; caso o campo não retorne ou retorne com o valor 0, a transação foi realizada como Crédito normal.

OBSERVAÇÃO: Cabe à automação comercial fazer o tratamento correto deste campo 2363 para aceitar a transação ou não em caso do seu não retorno ou retorno do campo com o valor 0, pois a CliSiTef não irá barrá-la pelo fato do módulo não aceitar a transação de Crédito para Pagamento de Carnê, ocasionando então a realização de uma transação de Crédito normal, sem a taxa diferenciada.

Arquivo de configurações CliSiTef.ini ou CLSIT

A CliSiTef utiliza um arquivo no formato .ini, de modo a definir previamente determinadas configurações na estação.

Este arquivo se chama CliSiTef.ini, e deve ser colocado na mesma pasta da biblioteca CliSiTef.

Em equipamentos POS e plataformas mobile (Android e IOS), o arquivo de configuração utilizado é CLSIT. Ao longo deste documento, todas as menções para CliSiTef.ini devem ser entendidas como CLSIT quando se tratar destes ambientes.

A seguir descreveremos algumas funcionalidades macro presentes neste arquivo.

Configuração do PinPad

 Configuração da porta

A porta serial/usb do PinPad é configurada na seção PinPadCompartilhado, campo Porta.

[PinPadCompartilhado] 
Porta=<PORT>

No Windows, deve-se usar informar o número da porta serial/usb. Por exemplo: 12

No Linux, deve-se indicar o caminho completo do device. Por exemplo: /dev/ttyS1 ou /dev/ttyACM0

A partir da CliSiTef versão 4.0.111.3 para Windows e 4.0.111.18 para Linux, é possível usar o valor ‘AUTO_USB’ para identificar automaticamente a porta de um pinpad USB.

[PinPadCompartilhado] 
Porta=AUTO_USB

Pinpads que suportam a configuração AUTO_USB em ambiente WINDOWS:

Pinpads que suportam a configuração AUTO_USB em ambiente LINUX:

Nota: Pinpads de novos fabricantes ou novos modelos poderão ser incluídos nas listas acima, futuramente.

Configuração quando a Automação não utilizar pinpad

A CliSiTef, por padrão, assume que a automação possui um PinPad, e tenta até 3 vezes abrir a porta.

Nos casos em que a automação não possui/utiliza um PinPad (p/ex. somente transações digitadas), deve-se configurar o item Porta, na seção PinPadCompartilhado, com o valor NENHUM.

[PinPadCompartilhado] 
Porta=NENHUM

Configuração de um segundo pinpad

Conforme mencionado em Correspondente Bancário (Pagamento de Contas), transações de Pagamento de Contas requerem pinpad especifico do banco. Geralmente, existe um setor do estabelecimento comercial somente para este tipo de atendimento.

Se a Automação precisar atender às transações de TEF no mesmo check-out que atende as transações de Pagamento de Contas, é possível configurar um segundo pinpad especifico do Banco, de forma que, o pinpad principal será usado exclusivamente nas transações de TEF.

Definição da mensagem padrão

É possível inicializar o PinPad com uma mensagem de até 16 caracteres. Esta mensagem é configurada na seção PinPad, campo MensagemPadrao.

[PinPad] 
MensagemPadrao=<MENSAGEM>

É possível quebrar em duas linhas, utilizando o separador ‘|’.

Habilitando confirmação do valor no pinpad

Esta configuração habilita a confirmação do valor da transação no pinpad no caso de transações sem coleta de senha pelo pinpad, visto que na coleta de senha já é apresentado o valor. Até o momento ela só é válida para transações de recarga pré-pago e bônus.

Para habilitar esta configuração basta adicionar as seguintes configurações ao arquivo “CliSiTef.ini”:

[Geral] 
ConfirmarValorPinPad=1

Configuração de conexão com o servidor SiTef

 Configuração de endereços IP adicionais

No arquivo de configuração é possível adicionar endereços alternativos para o servidor SiTef. Estes endereços são complementares aos informados na função de configuração. São permitidos no máximo 4 endereços a partir da CliSiTef 6.1.114.59 r3 e anteriormente 3, considerando a soma dos enviados na função de configuração e arquivo CliSiTef.ini.

[SiTef] 
EnderecoIP=IP1;IP2;IP3;IP4

Também é possível informar a porta do servidor, no formato IP:Porta. 

Por exemplo:

EnderecoIP=127.0.0.1:4096;192.168.0.1:5096

Configuração da porta do servidor SiTef

Em raras situações, pode ser necessário alterar a porta de comunicação com o servidor SiTef. Por exemplo, alguma restrição de segurança na rede do cliente.

A porta padrão do servidor SiTef é 4096. Para especificar uma nova porta, deve-se incluir na seção SiTef o campo PortaSiTef.

[SiTef] 
PortaSiTef=<porta>

Obrigatoriedade de conexão

Por padrão, as transações na CliSiTef tentam avançar ao máximo, mesmo sem a conexão com o SiTef.

Para retirar este comportamento, e exigir a obrigatoriedade de conexão, inclua na seção SiTef o parâmetro ConexaoObrigatoria com valor um (1). Neste caso, não havendo conexão com o SiTef a transação será encerrada com erro -5.

[SiTef] 
ConexaoObrigatoria=1

Mantendo conexão ativa

Por padrão, a característica da CliSiTef ao fazer uma transação com o servidor SiTef é: realizar a conexão, efetuar a troca de mensagens e desconectar ao final da transação.

Caso haja necessidade de manter a conexão com o SiTef sempre ativa, deve-se incluir na seção SiTef o parâmetro MantemConexaoAtiva com valor 1 (um).

[SiTef] 
MantemConexaoAtiva=1

Configuração do mostrador de comunicação

Por padrão, a CliSiTef envia para a automação o comando 3 com uma mensagem do tipo “Aguarde, em processamento...”.

Para    desabilitar    o    mostrador    de    comunicação,    basta    incluir    na    seção    Geral    o    campo MostradorComunicacaoHabilitado com valor zero.

[Geral] 
MostradorComunicacaoHabilitado=0

Alterando parâmetros de temporizações (timeout)

Tempo para timeout de conexão com o servidor SiTef

O tempo padrão de espera para que a CliSiTef consiga se conectar com o servidor SiTef é de 6 segundos. Para aumentar ou diminuir este tempo de espera, configure na seção SiTef o campo TempoEsperaConexao com o novo valor, em segundos.

[SiTef]
TempoEsperaConexao=<tempo para timeout, em segundos>

Tempo adicional para timeout da transação

Normalmente a CliSiTef recebe parâmetros de timeout com o servidor SiTef. A CliSiTef leva em consideração estes valores, acrescentando ainda uma margem de segurança sobre eventuais tempos gastos na transmissão.

Em situações de autorizador indisponível, e dependendo do canal de comunicação entre o servidor SiTef e a CliSiTef, esta margem pode ser insuficiente, podendo ocorrer erros do tipo “Sem conexão com o servidor SiTef”, quando o correto seria “Serviço do autorizador indisponível”.

Para incluir um tempo adicional em segundos, basta incluir o item TempoAdicionalEspera na seção SiTef.

[SiTef]
TempoAdicionalEspera=<tempo adicional para timeout, em segundos>

Tempo para espera de desfazimento

O tempo padrão de espera (timeout) para que a CliSiTef consiga receber a resposta à uma mensagem de desfazimento enviada ao servidor SiTef é de 6 segundos. Para alterar este valor, configure na seção SiTef o campo TempoEsperaDesfazimento o novo valor, em segundos.

[SiTef]
TempoEsperaDesfazimento=<tempo para timeout, em segundos>

Tempo para espera de confirmação

O tempo padrão de espera (timeout) para que a CliSiTef consiga receber a resposta à uma mensagem de confirmação/não-confirmação enviada ao servidor SiTef é de 6 segundos. Para alterar este valor, configure na seção SiTef o campo TempoEsperaConfirmacao o novo valor, em segundos.

[SiTef]
TempoEsperaConfirmacao=<tempo para timeout, em segundos>

Como passar um novo valor da compra da transação na CliSiTef

Na seção [Geral] acrescente a chave PermiteAlterarValorPagamento=1, conforme abaixo:

[Geral] 
PermiteAlterarValorPagamento=1

Durante o fluxo da transação, a CliSiTef solicitará "Forneca o novo valor do pagamento", através do campo 154.

Habilitando/desabilitando formas de pagamento

A CliSiTef permite duas maneiras de se configurar as formas de pagamento.

Uma delas ocorre em tempo de execução da transação, isto é, a automação comercial define as formas de pagamento que serão aplicadas para a transação corrente.

Caso a automação não defina estes valores, serão usadas as parametrizações padrões, podendo estar definidas no arquivo de configurações CliSiTef.ini da estação.

Restringindo formas de pagamento em tempo de execução

A CliSiTef permite que o aplicativo de automação restrinja as modalidades de pagamento disponíveis ao operador de caixa/cliente para uma determinada venda. Isso é feito através do parâmetro “ParamAdic” presente nas funções que inicial o processo de pagamento ou Correspondente Bancário (IniciaFuncaoSiTefInterativo e CorrespondenteBancarioSiTefInterativo). O formato desse campo é o seguinte:

[<Tipo do meio de pagamento>;<Tipo do meio de pagamento>;...];

onde cada um dos sub-campos contém um código numérico que identifica o item de menu que não se aplica à venda em questão. Por exemplo, se durante o processo de venda já foi negociado com o cliente que é uma venda para pagamento única e exclusivamente com cartão a vista, o valor do parâmetro deve ser:

[10;17;18;19;27;28;34;35;];

Consulte a Tabela de códigos de meios de pagamento, configurações e menus para a lista de códigos nesta configuração.

Definindo valores padrão para formas de pagamento

Neste caso o ambiente de vendas do cliente não comporta determinado tipo de modalidade de pagamento por não se aplicar ao seu ramo de negócio. Um exemplo disso é um estabelecimento comercial onde todas as vendas somente podem ser feitas à vista. Para esse tipo de aplicação é possível definir essa configuração no arquivo de parâmetros da CliSiTef de forma que, caso o lojista opte no futuro a aceitar outras modalidades de pagamento, basta alterar a configuração da CliSiTef, sem ser necessário alterar o aplicativo de automação. Essa configuração é feita através do parâmetro TransacoesHabilitadas a ser colocado na seção [Geral] do arquivo CliSiTef.ini.

O formato desse parâmetro é o seguinte:

[Geral]
TransacoesHabilitadas=<Tipo do meio de pagamento>;<Tipo do meio de pagamento>;...

onde cada um dos sub-campos possui a mesma descrição do item anterior.

Utilizando o mesmo exemplo do item anterior, para limitar as transações apenas as de pagamento à vista e sem cheque, a definição será:

[Geral] 
TransacoesHabilitadas=16;26

Habilitação de transações adicionais

Por questões de compatibilidade com versões anteriores da biblioteca e também pelo fato de algumas funcionalidades da mesma não serem de uso geral, existem algumas formas de pagamento que não estão habilitadas por padrão, sendo necessário que o cliente informe explicitamente que deseja utilizá-las. Isso é feito através do arquivo de configuração CliSiTef.ini pelo parâmetro TransacoesAdicionaisHabilitadas a ser incluído na seção [Geral]. O formato desse parâmetro é o seguinte:

[Geral]
TransacoesAdicionaisHabilitadas=<Tipo do meio de pagamento>;...

Onde cada um dos sub-campos possui a mesma descrição dos itens anteriores.

Consulte a Tabela de códigos de meios de pagamento, configurações e menus para a lista de códigos nesta configuração.

Os menus que hoje não estão habilitados por padrão são os seguintes: 

Cartão Refeição Eletrônico

Recarga de celular com cartões de débito ou crédito 

Pagamento de Benefícios e respectivo estorno

Leitora SmartNet para cartões SmartVR e Sodexho com chip 

Correspondente Bancário

Paggo

Débito Digitado 

Extrato CB 

Consulta Saldo CB

Saque e estorno de saque CB 

Depósito e estorno de depósito CB 

Recarga de Celular Bradesco 

Recarga de Celular Corban SE 

Extrato CB

Pagamento e Estorno de DARF

Pagamento e Estorno de GPS 

Empréstimo Pré-Aprovado 

Abertura de Conta

Troco Premiado (Surpresa) 

Vale Gás

Opção Administrativa Redecard 

Cartão Combustível

Cartão Presente

Exemplificando, para habilitar o menu de pagamento com cartão Refeição Eletrônico deve-se incluir a seguinte configuração em CliSiTef.ini:

[Geral] 
TransacoesAdicionaisHabilitadas=20

Desabilitando transações

De forma análoga às transações adicionais habilitadas do item anterior, é possível desabilitar algumas transações sem a necessidade de especificar todo o intervalo de operações como nas restrições.

Para tanto, inclua na seção Geral o campo TransacoesDesabilitadas, indicando as transações que serão desabilitadas ao longo do fluxo transacional.

[Geral]
TransacoesDesabilitadas=<Tipo do meio de pagamento>;...

Consulte a Tabela de códigos de meios de pagamento, configurações e menus para a lista de códigos nesta configuração.

Habilitação de transações de redes específicas

Existem algumas redes que, por não serem de uso generalizado, não estão automaticamente habilitadas na CliSiTef. Neste caso, para habilitá-las, existe a seção [Redes] no arquivo de configuração CliSiTef.ini e que deve conter o nome da variável correspondente a rede a ser habilitada com o valor 1.

Caso o estabelecimento trabalhe com mais de uma rede das descritas a seguir, deve ser incluída uma linha para cada rede.

[Redes] 
HabilitaRedexxxx=1

Onde xxxx pode ser, na presente versão da CliSiTef, um dos seguintes valores abaixo:

Note que é possível habilitar tantas redes quanto necessário, desde que elas estejam habilitadas no SiTef de forma compatível.

Tabela de códigos de meios de pagamento, configurações e menus

A seguir está a tabela que relaciona os tipos de meio de pagamento, configurações e menus, com os respectivos códigos, para serem utilizados nos itens anteriores^.

Habilitação de configurações especiais por transação

Em determinadas transações, é possível incluir novas funcionalidades e características ao fluxo transacional, permitindo maior flexibilidade de operação sem que estas funcionalidades não estejam vinculadas a um meio de pagamento específico.

Para tanto, basta acrescentar um novo campo ao parâmetro “ParamAdic”, presente nas funções que iniciam o processo de pagamento ou Correspondente Bancário (IniciaFuncaoSiTefInterativo e CorrespondenteBancarioSiTefInterativo). O formato deste campo é o seguinte:

{<Funcionalidade1>;<Funcionalidade2>;...;<Funcionalidaden>;};

Note que neste formato as funcionalidades estão entre chaves (‘{’ e ‘}’), ao passo que as restrições estão entre colchetes (‘[’ e ‘]’).

Exemplo: no processo de venda exemplificado no item 5.1, suponha que o valor da venda possa ser alterado durante o fluxo, e que o aplicativo da automação deseje fazer seu tratamento, então o valor do parâmetro “ParamAdic” deve ser:

[10;17;18;19;27;28;34;35;];{TrataPagamentoExtendido=1;}

A seguir, descrevemos as funcionalidades previstas neste campo.

Transações crédito/débito com cartão sem BIN

Em determinadas transações, em que o aplicativo da automação deseje utilizar um cartão especial (sem BIN definido), é necessário passar algumas restrições, e para isso existem duas formas:

Indicando a configuração “RedeDestino” no parâmetro “ParamAdic”, presente nas funções que iniciam o processo de pagamento (IniciaFuncaoSiTefInterativo) ou Correspondente Bancário (CorrespondenteBancarioSiTefInterativo), conforme exemplo a seguir:

{RedeDestino=nnnn}

Onde nnnn é o código da rede a qual pertence o cartão especial (vide tabela abaixo).

Indicando esta rede especial, a qual pertence o cartão especial, no arquivo de configuração da CliSiTef (“CliSiTef.ini”).

Para tanto, indique nas seções Debito, Credito, CartaoCombustivel, Gift, SaqueCredito ou SaqueDebito, os pares (Texto, Rede) correspondentes ao texto que será exibido e o código de rede.

[Debito] 
Texto1=SomarCard 
Rede1=172

Texto2= StarFiche 
Rede2=178

TextoN=MinhaRede 
RedeN=nnnn

[Credito]
Texto1=SomarCard 
Rede1=172

Texto2= StarFiche 
Rede2=178

Texton=MinhaRede 
Reden=nnnn

[CartaoCombustivel] 
Texto1=FitCard 
Rede1=263

[CartaoGift]
Texto1=Condor 
Rede1=174 
TextoN=MinhaRede 
RedeN=nnnn

[SaqueCredito] 
Texto1= Condor 
Rede1=174 
TextoN=MinhaRede 
RedeN=nnnn

[SaqueDebito] 
Texto1= Condor 
Rede1=174 
TextoN=MinhaRede 
RedeN=nnnn

Através do arquivo de configuração é permitido definir até 5 redes de débito, 5 redes de crédito crédito, 5 redes de combustível, 5 redes de gift, 5 redes de SaqueCrédito e 5 redes de SaqueDébito. Feito isso, quando a automação realizar uma transação com uma das modalidades descritas acima, a CliSiTef apresentará um menu com todas as redes definidas e com a opção de débito, crédito, combustível, gift, SaqueCredito ou SaqueDebito em que é realizada a consulta de bins.

Além disso, é necessário definir se a rede em questão permite a captura do cartão através do leitor magnético ou através de digitação, com a configuração das seguintes chaves:

• HabilitaDigitadoN = 1
• HabilitaMagneticoN = 1

Para a seção [CartaoCombustivel] também pode ser habilitada a leitura de código de barras através da configuração abaixo:

• HabilitaCodBarN = 1

Para as transações Gift efetuar as seguintes configurações abaixo para habilitar os seguintes modos de entrada:

• HabilitaDigitadoN: Habilitar o modo de entrada EAN 13.
• HabilitaCodUnitarioGiftN: Habilitar o modo de entrada EAN 128.
• HabilitaEgiftDigitadoGiftN: Essa coleta é utilizada quando o autorizador emitir um número virtual que pode ser um número enviado por email. Esse número será utilizado com o cartão, será solicitado a entrada do número do Egift.

Exemplo:

[Debito] 
Texto1=SomarCard 
Rede1=172

Texto2=StarFiche 
Rede2=178

Texto3=Libercard 
Rede3=196 
HabilitaDigitado3=1 
HabilitaMagnetico3=0

Texto4=VeroPay 
Rede4=21 
HabilitaDigitado4=1 
HabilitaMagnetico4=0

[Credito] 
Texto1=SomarCard 
Rede1=172

Texto2= StarFiche 
Rede2=178

Texto3=Libercard 
Rede3=196 
HabilitaDigitado3=1 
HabilitaMagnetico3=0

[CartaoCombustivel]
Texto1=FitCard 
Rede1=263 
HabilitaDigitado1=0 
HabilitaMagnetico1=1 
HabilitaCodBar1=0

[CartaoGift] 
Texto1=Condor 
Rede1=174 
HabilitaDigitado1=0 
HabilitaMagnetico1=1 
HabilitaCodBar1=0
HabilitaCodUnitarioGift1=0 
HabilitaEgiftDigitadoGift1=0

[SaqueCredito] 
Texto1= Condor 
Rede1=174
TextoN=MinhaRede 
RedeN=nnnn 
HabilitaDigitadoN=0 
HabilitaMagneticoN=1

[SaqueDebito] 
Texto1= Condor 
Rede1=174

TextoN=MinhaRede 
RedeN=nnnn 
HabilitaDigitadoN=0 
HabilitaMagneticoN=1

Também é possível definir as transações adicionais que serão capturadas pela rede em questão. O parâmetro que determina essa característica é o TransacoesAdicionaisn, sendo n o índice da rede. Os valores indicados são as funções do item 3.2.2 - Tabela de códigos de funções, separados por ponto-e-vírgula.

No momento, somente a transação 602 (Consulta Saldo Cartão de Crédito) foi implementada. 

Exemplo:

[Credito] 
Rede1=205 
Texto1=GoldenFarma
TransacoesAdicionais1=602;

A seguir, listamos o código das redes que possuem cartões nesta situação.

Habilitação de crédito parcelado quando em um pagamento vinculado

Por padrão da CliSiTef, uma transação de pagamento de contas/recarga/ativação de cartão Gift que tenha um pagamento vinculado não habilitará a opção de parcelamento por padrão.

No entanto, existe um parâmetro que, em conjunto com a habilitação no SiTef dessas transações, pode habilitar essa forma de pagamento na biblioteca. O parâmetro é o seguinte:

[Geral] 
ModalidadesPermitePagVinculadoCredParcAdm=XXX;
ModalidadesPermitePagVinculadoCredParcLoja=XXX;

Onde XXX é o código da função/modalidade que irá executar a transação. Então, se o desejado for habilitar o parcelamento na transação de ativação Gift, por exemplo, o código a ser usado seria o 265.

Lembrando que somente é possível habilitar o parcelamento para transações de crédito.

Arquivos de controle

A CliSiTef permite configurar o diretório onde serão gerados os seus arquivos de controle. Essa configuração deve ser feita pelo item DiretorioBase da seção SalvaEstado no arquivo CliSiTef.ini.

No Windows, a pasta padrão utilizada é C:\CliSiTef\ChavesCliSiTef. 

No Linux, a pasta padrão é /tmp/ChavesCliSiTef.

[SalvaEstado] 
DiretorioBase=<DIRETORIO>

Exemplo Windows:

[SalvaEstado] 
DiretorioBase=C:\Chaves

Exemplo Linux:

[SalvaEstado]
DiretorioBase =/home/usuario/chaves

Trace

A CliSiTef normalmente grava informações em um único arquivo diário, com mecanismo de rotação de logs. Ou seja, arquivos mais antigos são removidos automaticamente.

No Windows, o arquivo é gravado no padrão C:\CliSiTef\CliSiTef.<AAAAMMDD>.dmp. No Linux, o arquivo é gravado na pasta local, no padrão CliSiTef.<AAAAMMDD>.dmp. Em equipamentos POS, o arquivo é gravado na pasta local, no padrão TRACE.

Configurando histórico

No arquivo de configuração “CliSiTef.ini”, é possível configurar o número de dias durante os quais o trace será mantido. Por padrão o trace fica habilitado por cinco dias.

[GERAL]
NumeroDeDiasNoLog=n

onde é n é o número de dias. Zero grava indefinidamente.

Configuração de diretório

No Windows, a pasta padrão para gravação dos arquivos de trace é C:\CliSiTef. 

No Linux, é usada a pasta corrente.

A CliSiTef permite configurar os diretórios onde serão gerados os seus arquivos de trace. Para tanto, altere o arquivo CliSiTef.ini conforme mostrado abaixo:

[CliSiTef] 
DiretorioTrace=<DIRETORIO>

Exemplo Windows:

[CliSiTef] 
DiretorioTrace=C:\Trace

Exemplo Linux:

[CliSiTef] 
DiretorioTrace=/home/usuario/trace

Arquivos de trace por terminal

Para facilitar algumas análises, é possível configurar a CliSiTef para gerar arquivos de trace por terminal (parâmetro IdTerminal da função ConfiguraIntSiTefInterativo).

Além da geração de traces por terminal, também é possível alterar a geração do arquivos de trace do modo diário para o modo por hora, em que são gerados diversos arquivos de trace fragmentados por hora.

Ao habilitar o modo multi-terminal da CliSiTef, a geração de traces é automaticamente alterada para o modo por terminal. Para maiores informações sobre o modo multi-terminal, consulte o documento específico “CliSiTef - Configuração Multi-terminal.doc”.

Caso não esteja configurada no modo multi-terminal e ainda assim queira habilitar a geração de traces por terminal, basta adicionar o item TracePorTerminal na seção CliSiTef do arquivo “CliSiTef.ini”.

[CliSiTef] 
TracePorTerminal=1

Para habilitar a geração de traces por hora deve ser adicionada a seguinte configuração ao arquivo “CliSitef.ini”:

[CliSiTef] 
TracePorHora=1

Trace Rotativo

A partir da versão 4.0.112.45 da CliSiTef, é possível separar cada transação efetuada pela automação em um arquivo de trace próprio.

Entenda-se transação, ao conjunto de trocas de mensagens sob o mesmo cupom fiscal. Ou seja, cupom fiscal e data fiscal, passados como parâmetro na função IniciaFuncaoSiTefInterativo (hora fiscal não é considerada).

Por exemplo: uma transação de recarga de celular seguida de um TEF, no mesmo cupom fiscal, ficam armazenados no mesmo arquivo de trace.

Neste cenário, os arquivos são gravados na forma:

A cada nova transação, os arquivos são rotacionados (renomeados), e os arquivos mais antigos são removidos, mantendo a quantidade de arquivos desejada.

Esta opção permite também o envio destes arquivos para o servidor SiTef, desde que este esteja configurado com o módulo NServices.

Habilitando o trace rotativo

Para habilitar a geração de traces rotativos, deve-se indicar a quantidade de arquivos máxima a serem armazenados na seção CliSiTef, item TraceRotativo.

[CliSiTef] 
TraceRotativo=n

Exemplo: armazenar até 10 transações

[CliSiTef] 
TraceRotativo=10

Limitando o tamanho dos arquivos

Em situações onde há restrições de espaço em disco (POS, por exemplo), pode-se ainda limitar o tamanho do arquivo de trace. Neste caso, uma mesma transação pode ficar armazenada em um ou mais arquivos separados.

Para tanto, indique o tamanho (em bytes) do limite do arquivo na seção CliSiTef, item TamanhoTraceRotativo. 

Por exemplo, para limitar o tamanho de cada arquivo em cerca de 32Kb:

[CliSiTef] 
TraceRotativo=10 
TamanhoTraceRotativo=32768

Enviando arquivos de trace para o servidor SiTef

É possível submeter os arquivos de trace de uma estação PDV ou terminal POS para o servidor SiTef. Esta situação pode ser especialmente útil para análise de eventuais problemas em produção.

Ao habilitar a configuração de trace rotativo, automaticamente será disponibilizada no menu administrativo da clisitef (função 110) a opção “Envio de trace para o servidor SiTef”.

Caso a automação deseje desabilitar esta opção, restrinja o menu 3627. Para maiores informações, consulte “Restrição ou habilitação das formas de pagamento”.

Também  é  possível  comandar  esta  transação  através  da  função  121,  que  deve  ser  passada  na

IniciaFuncaoSiTefInterativo.

Em caso de queda na comunicação, a automação pode executar novamente a função 121 após o reestabelecimento do canal. Nesta situação, a clisitef confirmará se deseja continuar o envio anterior.

Ao submeter os arquivos de trace para o servidor SiTef, certifique-se que o mesmo tenha o módulo NServices devidamente configurado.

Processo de desenvolvimento/homologação

Arquivo de trace adicional durante a fase de desenvolvimento

A CliSiTefI possui um mecanismo de auxilio ao desenvolvedor da aplicação que interage com ela de forma a simplificar a busca por problemas durante a fase de desenvolvimento. Esse mecanismo, uma vez habilitado, faz com que seja gerado um arquivo de trace contendo os parâmetros trocados entre a CliSiTef e a aplicação. O arquivo fica localizado no diretório corrente ou em C:\CliSiTef, dependendo se o ambiente for Linux ou Windows, respectivamente. O nome do arquivo é CliSiTef.AAAAMMDD.txt.

Para habilitar essa característica, inclua o seguinte parâmetro no arquivo de configuração CliSiTef.ini:

[Geral] 
DataEmAmbienteDeDesenvolvimento=AAAAMMDD

Onde AAAAMMDD corresponde ao dia que o teste em laboratório está sendo feito.

Processo de homologação

Como descrito anteriormente, o fluxo descrito neste documento deve ser seguido a risca para que não ocorram erros estranhos durante a execução da CliSiTef. Para tanto, existe um parâmetro configurável que será utilizado pelos homologadores da Software Express para confirmar que o aplicativo de automação somente concretiza o processo de venda pela impressão de um comprovante ou pela chamada a função FinalizaFuncaoSiTefInterativo após o retorno final da ContinuaFuncaoSiTefInterativo. Esse parâmetro é o seguinte:

[Geral] 
EmAmbienteDeHomologacao=1

Por introduzir uma mensagem adicional no processo, ele jamais deverá ser utilizado em ambiente de produção.

Tradução de mensagens

É possível alterar parte das mensagens enviadas para a automação, para efeitos de tradução ou, em alguns casos, para reduzir as mensagens.

Para habilitar esta característica, basta incluir na seção TabTraducao da CliSiTef.ini o item NomeArqTraducao, indicando o nome do arquivo de tradução.

[TabTraducao] 
NomeArqTraducao=<Nome do arquivo>

As mensagens devem ficar em um arquivo no formato INI separado, sob a seção TabTraducao. 

Um exemplo deste arquivo seria:

[TabTraducao]
MsgNovoValor=Forneca o novo valor do pagamento 
MsgEmbosso=Forneca os 4 digitos finais do cartao
MsgCodigoSeguranca=Informe Cod. Seg, ou\n0 = inexistente\n1 = ilegivel

Tabelas

Código das Redes Autorizadoras