Guia de Integração
Sumário#
Novo TLS Software Express (TLSGWP)
Iniciando o m-SiTef através de outro app
Exemplos de chamada do m-SiTef por outro app
Resposta do m-SiTef para outro app
Exemplo de tratamento do retorno do m-SiTef
Introdução#
O m-SiTef é um aplicativo desenvolvido pela Software Express para a plataforma Android, tanto em celular ou tablet como em POS, que realiza transações (TEF) através do servidor SiTef.
Este aplicativo contém a biblioteca CliSiTef e possibilita ao integrador a facilidade de apenas interagir com as funcionalidades da CliSiTef, sem a necessidade de controlar o fluxo das transações.
Objetivo#
Ser um guia de referência para integração com o m-SiTef.
Público-Alvo#
Parceiros que desejam se integrar com o m-SiTef.
Requisitos mínimos#
O m-SiTef é compatível com o Android versão 4.4 ou superior.
m-SiTef#
Antes de apresentar as formas de integração, descreveremos neste capítulo as características gerais do m-SiTef.
Ele disponibiliza para o integrador as mesmas funcionalidades da CliSiTef que estão descritas no documento "SiTef - Interface Simplificada com a aplicação" na Tabela de códigos de funções.
Para executar as funções, é obrigatório enviar 4 parâmetros ao m-SiTef: empresaSitef, enderecoSitef, modalidade e CNPJ_CPF. Para a modalidade 0, também é obrigatório o parâmetro valor.
Importante: Todos esses parâmetros apresentados neste documento em trechos de códigos são apenas ilustrativos e devem ser substituídos por valores válidos.
A seguir, estão listados todos os parâmetros aceitos na aplicação.
Tabela 1 - parâmetros de entrada do m-SiTef#
| Parâmetro | Tipo | Descrição |
|---|---|---|
| empresaSitef | Obrigatório | Empresa SiTef. O tamanho é de 8 dígitos alfanuméricos. |
| enderecoSitef | Obrigatório | Endereço dos servidores do SiTef. O campo pode ser composto de 1 a 3 endereços separados por ‘;’. O formato do endereço pode ser: 1. IP, IP:PORTA; 2. Nome do servidor, NOME:PORTA. Quando a porta não é especificada, é assumida a porta padrão (4096). Não informar URL nesse campo. |
| terminalSitef | Opcional | Número de terminal SiTef. Se não informado o m-SiTef irá usar o número de série do APOS ou o UUID do aparelho Android |
| modalidade | Obrigatório | Funcionalidade da CliSiTef que deseja executar. Por exemplo: 0 – Pagamento 200 – Cancelamento 114 – Reimpressão A lista completa pode ser encontrada no documento “SiTef - Interface Simplificada com a aplicação” na Tabela de códigos de funções. |
| CNPJ_CPF | Obrigatório | CNPJ ou CPF do estabelecimento. Este campo não deve conter caracteres especiais e pode ser utilizado nos dados de subadquirência e no ParmsClient. |
| Valor | Obrigatório p/ pagamento | Valor da venda. O campo é numérico com tamanho até 12 algarismos, onde os dois últimos dígitos são decimais. |
| restricoes | Opcional | Opções de pagamento que não aparecerão no fluxo de coleta. O campo deve ter o seguinte formato:<Opção>;<Opção>; ....Os valores das opções estão no documento “SiTef - Interface Simplificada com a aplicação”, na Tabela de códigos de funções. Observação: a opção TransacoesHabilitadas=T1,T2 também pode ser passada nesse parametro e terá preferência sobre o parâmetro TransacoesHabilitadas |
| operador | Opcional | Código do operador. O campo é alfanumérico com tamanho até 20 caracteres. |
| Data | Opcional | Data fiscal no formato AAAAMMDD. |
| Hora | Opcional | Hora fiscal no formato HHMMSS. |
| numeroCupom | Opcional | Número do cupom fiscal correspondente à venda. O campo é alfanumérico com tamanho até 20 caracteres. |
| numParcelas | Opcional | Número de parcelas, em caso de compra parcelada. O campo é numérico e varia de acordo com o cartão utilizado. |
| Otp | Opcional | Código obrigatório quando é utilizada comunicação com TLS GSurf. |
| transacoesHabilitadas | Opcional | Opções de pagamento que serão habilitadas. O campo deve ter o seguinte formato { <Funcionalidade1>;<Funcionalidade2>;...}. Os valores das opções estão no documento “SiTef - Interface Simplificada com a aplicação”, na Tabela de códigos de funções. |
| pinpadMac | Opcional | Endereço MAC Address Bluetooth do Pinpad para o m-SiTef se conectar diretamente com o pinpad. Caso esse parâmetro não seja passado, o m-SiTef apresenta uma lista de dispositivos Bluetooth pareados com o aparelho para o usuário selecionar qual utilizar. Formato: 00:00:00:00:00:00 |
| comExterna | Obrigatório | Campo para definir qual serviço TLS será usado: 0 – Sem (apenas para SiTef dedicado) 1 – TLS Software Express 2 – TLS WNB Comnect 3 – TLS Gsurf |
| isDoubleValidation | Obrigatório p/TLS Software Express | Campo para definir qual tipo de validação será usado: 0 – Para validação simples 1 – Para validação dupla |
| cnpj_automacao | Opcional | CNPJ da empresa que desenvolveu a automação comercial. Dado utilizado no ParmsClient. |
| cnpj_facilitador | Opcional | CNPJ do Facilitador (Van). Dado utilizado no ParmsClient. |
| timeoutColeta | Opcional | Define o tempo de timeout para coletas e interações do fluxo da transação. O valor deve ser preenchido em “segundos” e se não for preenchido, o valor padrão é de 60 segundos. Caso seja definido como 0 ou números negativos, o timeout de coleta será inativado. O timeout é aplicado se o usuário não interagir com a coleta pelo número de segundos especificado. Nesse caso, a transação é automaticamente cancelada e a aplicação recebe o valor RESULT_CANCELED no parâmetro resultCode. Este timeout não se aplica à leitura de QRCode, à coleta do PIN e a retirada do cartão da leitora. |
| acessibilidadeVisual | Opcional | Campo para definir se a acessibilidade visual deve ser habilitada: 0 – Para desabilitar (valor padrão) 1 – Para habilitar A habilitação da acessibilidade visual consiste em algumas modificações visuais e sonoras. Caso este campo seja habilitado, o m-SiTef terá as seguintes alterações: · Fontes maiores para melhor visualização · Alto contraste nas cores para melhor visualização em caso de daltonismo · Ativação do text-to-speech (leitura de tela) durante todo o fluxo · Se for o caso, ativa a adaptação da tela para compatibilidade com a capa de acessibilidade na inserção da senha ou pin (aplicável em modelos pré-definidos). Observação: para que a leitura de tela seja realizada pelo módulo de text-to-speech, o sistema operacional precisa ter previamente instalado o pacote da língua correspondente. No caso do GPOS700, o pacote de linguagem PT-BR será disponibilizado pela Gertec. |
| tipoPinpad | Obrigatório p/ dispositivos USB. | ANDROID_USB – Tenta obter conexão apenas com pinpad´s USB. ANDROID_BT – Tenta obter conexão apenas com pinpad´s Bluetooth. |
| dadosSubAdqui | Opcional | Conjunto de informações complementares que permite que o lojista personalize o que será impresso na fatura do comprador. Formato: <id1><tam1><val1><id2><tam2></tam2><val2>...<idn><tamn></tamn><valn>Onde: Id - identificador do campo com 2 bytes, conforme valores definidos na tabela da especificação ”Informações de Sub-adquirência (Soft Descriptor) Bibliotecas CliSiTefI e CliSiTef” tam - tamanho do campo com 2 bytes. Val – valor do campo. Exemplo de envio: i.putExtra("dadosSubAdqui", "0022STL*SOFTWARE EXPRESS"); Para mais informações referente aos dados consultar a especificação: “Informações de Sub-adquirência (Soft Descriptor) Bibliotecas CliSiTefI e CliSiTef” |
| tipoCampos | Opcional | Permite informar valores pré-determinados para os campos que a CliSiTef solicita para a aplicação durante o fluxo da transação. Os campos e seus respectivos valores devem ser informados no formato JSON abaixo. Os valores sempre deverão ser informados com o valor do tipo String. E é importante observar que nesse formato, é possível definir apenas um valor por tipo de campo. Formato JSON: {"campo1":"val1", "campo2":"val2"..."campon":"valn"}Exemplos de envio: i.putExtra("tipoCampos","{\"147\":\"8000\", \"516\":\"99900021\"}"); i.putExtra("tipoCampos","{\"1025":\"Descricao do Produto\"}"); |
| habilitaColetaTaxaEmbarqueIATA | Opcional | Quando habilitado, indica que se trata de uma transação de venda a crédito IATA e será disponibilizado campo para coleta do valor da taxa de embarque. 0 – Para desabilitar (valor padrão) |
| habilitaColetaValorEntradaIATA | Opcional | Quando habilitado, indica a coleta do valor de entrada em caso de parcelamento da venda a crédito IATA. Esta coleta será permitida apenas para venda IATA, isto é, a habilitação deste item só terá efeito se habilitaColetaTaxaEmbarqueIATA=1. |
| clsit | Opcional | Para poder adicionar, atualizar e remover campos do arquivo de configuração CLSIT do pacote. Olhar seção Mudando o CLSIT. |
Integração utilizando TLS#
O m-SiTef é compatível com 4 provedores TLS: Software Express, GSurf, WNB Comnect e TLSGWP. Abaixo, será explicado como utilizar cada um deles.
TLS Software Express#
Integração TLS WNB Comnect#
Integração TLS Gsurf#
Novo TLS Software Express (TLSGWP)#
Alternativamente, o registro de terminal para usar o novo TLSGWP pode ser realizado através das modalidades 699 (Registro de terminal) ou 110 (menu administrativo). Neste caso, a CliSiTef irá abrir uma coleta para o token ser informado e a partir desse momento o terminal estará registrado e deverá informar nas próximas transações que o tipo de conexão será o TLSGWP informando o parâmetro comExterna = 4 como no exemplo a seguir.
Registro Manual (TLSGWP)#
Integração com outro app#
Iniciando o m-SiTef através de outro app#
O primeiro passo é instanciar um objeto Intent passando o nome da aplicação como argumento – neste caso, o nome é br.com.softwareexpress.sitef.msitef.ACTIVITY_CLISITEF. Através desta informação, o Android buscará automaticamente o m-SiTef entre os aplicativos instalados no dispositivo móvel. Em seguida, devem ser configurados quatro parâmetros obrigatórios através da função putExtra(String, String): empresaSitef, enderecoSitef, CNPJ_CPF e modalidade. Esses e outros parâmetros serão detalhados no item 5. Por fim, é executada a função nativa do Android startActivityForResult(Intent, int) passando como parâmetros o objeto Intent e um número inteiro arbitrário. Este número será utilizado como um ID para a recuperação de informações que o m-SiTef enviará, após encerrar o seu processamento, ao aplicativo que o acionou. Neste documento, utilizaremos o ID = 1234.
Exemplos de chamada do m-SiTef por outro app#
a) Pagamento
Ao ser acionado, o m-SiTef pode apresentar as seguintes telas:
b) Débito à vista
c) Crédito à vista
d) Crédito parcelado
e) Cancelamento
f) Reimpressão
g) Menu administrativo
Exemplo de chamada de Pix#
Para realizar o Pix a automação deve seguir o exemplo abaixo, escolhendo o menu de carteiras digitais. Importante: o campo “cnpj_automacao” é de extrema importância que seja enviado, pois é através dele que a Software Express será capaz de reconhecer o estabelecimento e assim fazer o repasse financeiro.
Se desejar, a automação pode chamar o Pix diretamente restringindo as opções de carteiras digitais e passando a modalidade 122 (Carteiras digitais), como mostra exemplo a seguir.
Resposta do m-SiTef para outro app#
Resposta do m-SiTef para outro app#
Após a execução do m-SiTef, o fluxo é retornado ao aplicativo que o acionou e são devolvidos alguns parâmetros. Através deles, o aplicativo conseguirá saber se o processamento da transação ocorreu com êxito e além de obter outras informações. Para receber estes dados, a aplicação deve implementar a função protected void onActivityResult( int requestCode, int resultCode, Intent data), que é executada pois o método startActivityForResult(Intent i, int requestCode) foi chamado para iniciar o m-SiTef. O argumento requestCode é usado para verificar a correspondência da chamada ao m-SiTef com o seu retorno. O resultCode mostra o status da execução do fluxo do m-SiTef (os valores pertencem ao Android RESULT_OK (-1) RESULT_CANCELED (0)). O argumento data é utilizado para recuperar os dados enviados pelo m-SiTef. A implementação do onActivityResult deve conter uma condição comparando se o requestCode é igual ao número passado no startActivityForResult e, dentro desta condição, é verificado se o m-SiTef foi executado com êxito e são recuperados os parâmetros enviados por ele através da função data.getExtras().getString().
O aplicativo integrado ao m-SiTef pode tratar apenas os parâmetros que precisar.
Tabela 2 - parâmetros de saída do m-SiTef#
| Parâmetro | Descrição |
|---|---|
| CODRESP | Código de resposta da transação realizada com o SiTef. Veja a tabela a seguir para maiores detalhes |
| COMP_DADOS_CONF | Dados que deverão ser passados para a CliSiTef, a fim de realizar a confirmação da transação realizada. |
| CODTRANS | Indica código da transação realizada. Possíveis valores: · ‘00’: Consulta Cheque · ‘01’: Cartão Débito · ‘02’: Cartão Crédito |
| TIPO_PARC | Valores possíveis: · “00”: À vista · “01”: Pré-Datado · “02”: Parcelado Estabelecimento · “03”: Parcelado Administradora |
| VLTROCO | Contém o valor aprovado para o troco em dinheiro. (Utilizado em compra com Saque disponível para algumas Redes). |
| REDE_AUT | Campo contendo a rede autorizadora da transação TEF realizada. Os códigos estão no documento "Especificação Técnica – Interface com os meios de pagamento do SiTef", na Tabela de Código das Redes Autorizadoras. |
| BANDEIRA | Campo contendo a bandeira da transação TEF realizada. Os códigos estão no documento "Especificação Técnica – Interface com os meios de pagamento do SiTef", na Tabela de Código da Bandeira. |
| NSU_SITEF | NSU do servidor SiTef. |
| NSU_HOST | NSU do Host Autorizador. |
| COD_AUTORIZACAO | Código de autorização da transação de crédito. (Presente somente em transações com cartão de crédito). |
| NUM_PARC | Campo contendo a quantidade de parcelas da transação. Caso ele esteja ausente, ou tiver valor “0” ou “1”, considerar venda à vista. |
| VIA_ESTABELECIMENTO | Cupom referente à via do estabelecimento. |
| VIA_CLIENTE | Cupom referente à via do cliente. |
| TIPO_CAMPOS | JsonObject contendo todos os campos da transação com a CliSiTef, incluindo os outros campos dessa tabela. Formato:{"Id TipoCampo N" : [ "valor 1", ....]}Os valores são sempre passados em JsonArray, mesmo ocorrendo somente uma ocorrência do campo pela CliSiTef. Para descobrir o significado de cada campo contido nessa lista favor olhar a tabela “Tabela de valores para TipoCampo” no documento SiTef - Interface Simplificada com a aplicação seção 5.3.2. Nem todos os parâmetros da tabela 5.3.2 podem estar presentes em todas as transações, alguns parâmetros podem não ser enviados dependendo da forma de pagamento ou se a transação não for concluída. |
Tabela 3 - Valores do CODRESP#
| CODRESP | Descrição |
|---|---|
| 0 | Sucesso na execução da função. |
| 1 | Endereço IP inválido ou não resolvido |
| 2 | Código da loja inválido |
| 3 | Código de terminal inválido |
| 6 | Erro na inicialização do Tcp/Ip |
| 7 | Falta de memória |
| 8 | Não encontrou a CliSiTef ou ela está com problemas |
| 9 | Configuração de servidores SiTef foi excedida. |
| 10 | Erro de acesso na pasta CliSiTef (possível falta de permissão para escrita) |
| 11 | Dados inválidos passados pela automação. |
| 12 | Modo seguro não ativo |
| 13 | Caminho DLL inválido (o caminho completo das bibliotecas está muito grande). |
| Outro valor positivo | Negada pelo autorizador. |
| -1 | Módulo não inicializado. O PDV tentou chamar alguma rotina sem antes executar a função configura. |
| -2 | Operação cancelada pelo operador. |
| -3 | O parâmetro função / modalidade é inexistente/inválido. |
| -4 | Falta de memória no PDV. |
| -5 | Sem comunicação com o SiTef. |
| -6 | Operação cancelada pelo usuário (no pinpad). |
| -9 | A automação chamou a rotina ContinuaFuncaoSiTefInterativo sem antes iniciar uma função iterativa. |
| -10 | Algum parâmetro obrigatório não foi passado pela automação comercial. |
| -12 | Erro na execução da rotina iterativa. Provavelmente o processo iterativo anterior não foi executado até o final (enquanto o retorno for igual a 10000). |
| -13 | Documento fiscal não encontrado nos registros da CliSiTef. Retornado em funções de consulta tais como ObtemQuantidadeTransaçõesPendentes. |
| -15 | Operação cancelada pela automação comercial. |
| -20 | Parâmetro inválido passado para a função. |
| -25 | Erro no Correspondente Bancário: Deve realizar sangria. |
| -30 | Erro de acesso ao arquivo. Certifique-se que o usuário que roda a aplicação tem direitos de leitura/escrita. |
| -40 | Transação negada pelo servidor SiTef. |
| -41 | Dados inválidos. |
| -43 | Problema na execução de alguma das rotinas no pinpad. |
| -50 | Transação não segura. |
| -100 | Erro interno do módulo. |
| Outro valor negativo | Erros detectados internamente pela rotina. |
Exemplo de tratamento do retorno do m-SiTef#
Mudando o CLSIT#
A partir da versão 3.167 é possível alterar o arquivo CLSIT. A alteração só pode ser feita uma vez, depois disso só será possível mudar o CLSIT mudando a empresa ou forçando a parada do aplicativo no menu de configuração do Android. O arquivo CLSIT possui o seguinte formato:
Veja abaixo exemplos de como usar essa funcionalidade e um modelo de CLSIT que será usado como base para os exemplos.
Alterando campos#
Veja no CLSIT abaixo que as chaves DiretorioTrace e TrancacoesHabilitadas foram atualizadas com os valores enviados pelo exemplo acima, importante ressaltar que caso a chave não exista ela será adicionada na seção enviada e se já existir seu valor será mesclado com os valores já existentes.
Adicionando campos#
Veja abaixo que as chaves HabilitaColetaTaxaEmbarque e ColetaValorEntradaIATA foram adicionadas a seção Geral e que a seção NovaSecao foi criada, pois ela ainda não existia.
Removendo campos#
Veja abaixo que a chave TamanhoTarceRotativo foi removida do CLSIT. Caso uma seção não contenha mais chaves ela será excluída também.
Importante: Para saber exatamente quais seções, chaves e valores devem ser passados para montagem do seu arquivo CLSIT, por favor consultar o nosso suporte. O m-SiTef possui um CLSIT padrão que será adotado caso nenhuma alteração especificada nesse capítulo seja feita. Segue a imagem dele:
Exemplo de integração utilizando o AndroidX#
Caso esteja realizando a integração com o m-SiTef utilizando as bibliotecas do AndroidX, os métodos startActivityForResult e onActivityResult estão depreciados. Abaixo segue um exemplo da chamada do m-SiTef utilizando o AndroidX
Definição do ActivityResultLauncher para realizar o tratamento do retorno do m-SiTef
Histórico de Alterações#
| Data | Doc | App | Descrição |
|---|---|---|---|
| 05/08/2019 | 1.00 | Versão inicial. | |
| 06/08/2019 | 1.01 | Inclusão da integração via URL. | |
| 09/08/2019 | 1.02 | Inclusão dos parâmetros de ativação do protocolo TLS. | |
| 22/08/2019 | 1.03 | Inclusão dos parâmetros “isDoubleValidation” e “caminhoCertificadoCliente”. | |
| 03/09/2019 | 1.04 | Inclusão dos parâmetros de entrada “cnpj_automacao” e “cnpj_facilitador”. | |
| 16/04/2020 | 1.05 | Alteração do campo modalidade de 9 para 0. Remoção da opção de exibir comprovante. Exclusão do caminho do certificado, pois esse ficará fixo. | |
| 21/07/2020 | 1.06 | Inclusão da modalidade de cancelamento. | |
| 20/08/2020 | 1.07 | Inclusão do campo terminal. | |
| 25/08/2020 | 1.08 | Remoção do modo TLS com dupla validação. Remoção do modo de entrada por URL. Trocado as referências “m-SiTef Client” para “m-SiTef” Removido menções sobre o “m-SiTef StandAlone” Formatação das tabelas Adição da tabela de valores do CODRESP Troca do nome do arquivo | |
| 19/10/2020 | 1.09 | Inclusão do tópico sobre o Pix. | |
| 20/11/2020 | 1.10 | Inclusão do campo de retorno “TIPO_CAMPOS” | |
| 01/12/2020 | 1.11 | 3.98 | Inclusão do campo “timeoutColeta”. |
| 05/03/2021 | 1.12 | 3.104 | Inclusão do campo “acessibilidadeVisual” e descrição do comportamento quando a acessibilidade visual é habilitada. Inclusão de observação de pré-requisito de instalação do pacote de linguagem de acessibilidade da Gertec. |
| 08/03/2021 | 1.13 | Adicionado a observação do endereço SiTef conforme sugestão da trac #53436 Remoção da resposta por URL | |
| 19/05/2021 | 1.14 | 3.114 | Adição do campo tipoPinpad. |
| 20/05/2021 | 1.15 | Remoção do valor ANDROID_AUTO para o campo tipoPinpad, pois ele não se aplica pro m-SiTef. | |
| 15/07/2021 | 1.16 | Adição de exemplo de chamada do menu administrativo e observação sobre parâmetros de exemplo | |
| 01/10/2021 | 1.17 | Modificação do documento para o padrão Fiserv. Inclusão do novo design do m-SiTef. | |
| 09/02/2022 | 1.18 | Inclusão do campo dadosSubAdqui | |
| 21/02/2022 | 1.19 | Inclusão do campo tipoCampos | |
| 29/08/2022 | 1.20 | 3.151 | Inclusão dos parâmetros habilitaColetaTaxaEmbarqueIATA e habilitaColetaValorEntradaIATA |
| 15/09/2022 | 1.21 | 3.167 | Capitulo "Mudando o CLSIT" |
| 04/01/2023 | 1.22 | Inclusão do tópico sobre a integração utilizando o AndroidX. |