# TRATATIVA DE ERROS
TRATATIVA DE ERROS
# GSURF - DICAS E TRATATIVAS
Existem cenários com restrições de permissões (firewall e/ou políticas de usuários com restrições de acesso) que podem resultar em erros durante o processo de instalação e/ou utilização do módulo TEF/PIX.
**Objetivo deste artigo é fornecer base para algumas tratativas destes cenários e fornecer dados para acionamento de suporte do time GSURF.**
---
##### **1. Boas práticas:**
O cenário ideal para utilização do **GSURF LISTNER - Serviço de VPN** necessário para utilização do módulo de TEF deverá ser validado com as boas práticas descritas abaixo:
- Verificação de Requisitos sem apresentação de erros
- Perfil Administrador do Sistema Operacional (não de nosso ERP)
- Firewalls desabilitados
---
##### **2. Cenários de erros:**
- - Execução do **VERIFICADOR DE REQUISITOS - GSURF** - Veja o print abaixo:
- [](https://manual.cplug.com.br/uploads/images/gallery/2023-12/t3XJKnuntDIwjuFK-gusurf_requisitos.PNG)
- No print acima são exibidos o **status OK em verde**, se forem apresentados erros em vermelho parecidos com os alistados abaixo:
- - - Erros relacionados a coleta FINGERPRINT
- Erros de comunicação relacionados a DNS / CDP / UDP / TCP
- Erros relacionados a comunicação com GSURF
- **Políticas de segurança e restrições de firewall:** Se nosso cliente possuir politicas de segurança de usuários e/ou restrições de firewall, isso pode ocasionar **erros de comunicação com SITEF e/ou GSURF**
---
##### **3. Verificações relacionadas a permissão de acesso GSURF**
- Permissão total de gravação e leitura da **pasta CLISITEF**
- **Porta TCP 4096** liberada e não sendo utilizada por outro sistema de VPN:
- - Para validar a liberação da porta acima, utilize o aplicativo [**TCP VIEW - Clique aqui para realizar o download!**](https://download.sysinternals.com/files/TCPView.zip)
**[](https://manual.cplug.com.br/uploads/images/gallery/2023-12/jtvWVcMYVxfUZl2A-gusurf_tcp_view.PNG)**
- **Print acima demonstra a utilização do TCP VIEW:**
- No campo de pesquise, insira a **porta 4096,** o cenário ideal é que nenhum aplicativo e/ou serviço esteja utilizando esta porta, o resultado da pesquisa não pode retornar nenhum resultado
- Se nosso cliente possuir POLÍTICAS DE SEGURANÇA **o time de TI de nosso cliente deverá validar as seguintes liberações:**
- - **Endereço IP e Máscara de Sub-rede:**
- Endereço IP: 18.231.194.64
- Máscara de sub-rede: /26 (Isso significa que o intervalo de IPs vai de 18.231.194.64 a 18.231.194.127)
- **Portas de Liberação TCP:**
- - 4096
- 443
- 55844
- 55845
- **Portas de Liberação UDP:**
- - 18.231.194/26 443
- DNS Local 53 UDP (consultas em gsurfnet.com)
- **Permissões de Usuário Instalação:**
- - Usuário que realiza a instalação do **GSURF LISTNER** e instalação da TEF no terminal precisa ser de **perfil ADMINISTRADOR (do sistema operacional e não de nosso ERP)**
- **Permissões de Usuário OPERADOR PDV:**
- - Usuário com permissão de **validação FINGERPRINT**
- **Serviço GSURF LISTNER utiliza metodologia TLS**
---
##### **4. Acionamento time GSURF**
- As verificações e orientações ao cliente acima, devem ser realizadas nos cenários de erro pelo analista que realiza a instalação do módulo de TEF.
- Em alguns cenários de erro de comunicação com SITEF, o time de **SUPORTE SITEF** pode sinalizar a necessidade de verificações adicionais pelo time de **SUPORTE GSURF, neste caso o analista deverá acionar o time GSURF pelos contatos abaixo:**
- - **Time SUPORTE GSURF: Telefones: (48) 3254-8700 / (48) 3181-0033**
# COLETA DE EVIDÊNCIAS
No cenário de erros de transações, após validação do time de PPI, pode ser necessário abertura de chamado junto a SITEF ou outras tratativas internas.
**Quando houver esta necessidade, será obrigatório a abertura de ticket relacionado ao respectivo caso, alistamos abaixo informações obrigatórias que devem constar neste chamado:**
- ##### **Dados do Cliente:**
- - SCHEMA
- CNPJ
- Razão Social
- Equipamentos utilizados:
- - Modelo do PINPAD
- Versão do PDV/TOTEM
---
- ##### **Identificação da Adquirente:**
---
- ##### **Tipo da Transação:**
- - Inserção
- Aproximação Cartão
- Bandeira do Cartão
- Aproximação Smartphone: Atenção aos dados abaixo:
- - Modelo Iphone ou Android
- ##### **Qual aplicativo utilizado:**
- - ApplePay
- GooglePay
- AndroidPay
- ##### **Qual Banco utilizado?**
- ##### **04 primeiros números do cartão que foi utilizado na transação:**
- Estes números (também identificados com BIN) são obrigatórios para que a FISERV possa ter acesso detalhado a transação.
- ##### **É realizado debito e estorno de maneira automática no respectivo banco ou cartão do cliente final?**
- ##### **Dados da Transação:**
- - Data e Hora da transação
- Valor da Transação
- Se cliente utilizar mais de um PDV/TOTEM, qual PDV/TOTEM origem da transação
- ##### **Evidências do Erro**
- - Vídeo do erro, mostrando tentativa e erro
- DMP do respectivo PDV/TOTEM - Arquivo dentro da pasta CLISITEF
- Se totem enviar LOG
# RETORNO DE ERRO: DADOS LÓGICOS - SOLICITAÇÕES TEF
##### **O retorno de dados lógicos inválidos pode se dar pelas seguintes razões:**
- Erro de digitação nos dados lógicos
- Dados lógicos não vinculados ao CNPJ do cliente em questão
- Dados lógicos expirados ou ainda não validados pela adquirente
##### **Tratativas de solução:**
- Compartilhar com cliente o print enviado no retorno de erro
- Orientar o cliente a acionar a adquirente e solicitar novos dados lógicos ou a confirmação da liberação dos mesmos dados lógicos, para o respectivo **CNPJ: ATENÇÃO PARA CENÁRIO MULTI-EMPRESA** é comum haver divergência entre dados lógicos e CNPJs das filiais.
- **Obrigatório coletar a evidencia desta tratativa entre cliente e adquirente:** um PRINT que conste os dados do cliente (CNPJ e Razão Social) e dados lógicos informados pela adquirente. **O print se faz necessário para eliminar a possibilidade de erros de digitação.**
- Responda no ticket em questão **as informações acima, principalmente com o PRINT como evidência.**
- **Observação importante:** Nenhum analista da CPLUG tem autonomia para acionar uma adquirente e validar dados lógicos de qualquer cliente. **Tratam-se de dados sensíveis e de responsabilidade total entre cliente e adquirente.**
# RETORNO DE ERRO: FALHA NAS CREDENCIAIS - SOLICITAÇÕES PIX
##### **O retorno de falha nas credenciais pode se dar pelas seguintes razões:**
- Falta de vínculo com respectivo Bankline ou portal do respectivo banco:
- Cenários onde existe mais de uma chave pix cadastrada, **alguns bancos exigem vínculo com a chave pix correta**
- Erro de digitação das credenciais:
- Em casos de credenciais com **CLIENT ID e CLIENT SECRET** a possibilidade de erro de digitação é grande
##### **Tratativas de solução:**
- Compartilhar com cliente o print enviado no retorno de erro
- Validar com cliente processo de vínculo com Bankline ou portal do respectivo banco. [**Utilize os artigos desta seção para consulta - Clique aqui!**](https://manual.cplug.com.br/books/tef/chapter/solicita%C3%A7%C3%B5es-de-pix "Solicitações de PIX")
- **Obrigatório coletar a evidencia do vínculo com Bankline ou portal do respectivo banco:** um PRINT que conste as respectivas credenciais. **O print se faz necessário para eliminar a possibilidade de erros de digitação.**
- Orientar o cliente a acionar o banco e solicitar novas credenciais ou a confirmação da liberação das mesmas credenciais.
- **Obrigatório coletar a evidencia desta tratativa entre cliente e banco:** um PRINT que conste os dados do cliente (CNPJ e Razão Social) e credenciais informadas pelo banco. **O print se faz necessário para eliminar a possibilidade de erros de digitação.**
- Responda o ticket **com as informações acima, principalmente com o PRINT como evidência.**
- **Observação importante:** Nenhum analista da CPLUG tem autonomia para acionar um banco e validar credenciais de qualquer cliente. **Tratam-se de dados sensíveis e de responsabilidade total entre cliente e banco.**
# RETORNO DE ERRO: CNPJ EXISTENTE NA FISERV - SOLICITAÇÕES TEF
##### **Informações importantes sobre o erro de CNPJ EXISTENTE NA FISERV:**
- Cenário onde o respectivo cliente já utilizava outra Software House ou Integradora de TEF pela FISERV (utilizando SITEF EXPRESS, SkyTef ou outra integradora que utilize a base ou serviços vinculados a FISERV)
- O credenciamento na base de dados da CPLUG via SITEF EXPRESS de um cliente no perfil acima **só é possivel se forem atendidas uma das alternativas abaixo:**
- **Exclusão completa do cadastro:** Opção mais indicada e de menor complexidade
- **Duplicação de CNPJ feita pelo time FISERV:** Importante destacar que a duplicação a solicitação junto a FISERV, deve ser feita entre CPLUG e FISERV. Veja detalhes abaixo, de como o cliente deve solicitar isso para CPLUG.
---
##### **Tratativas de solução:**
**1. Exclusão completa de cadastro:**
**1.1** Antiga Software House ou Integradora precisa **EXCLUIR COMPLETAMENTE** cadastro na FISERV/SITEF EXPRESS/SKYTEF, após exclusão é necessário **reiniciar módulo GERPDV** no respectivo ambiente FISERV/SITEF EXPRESS/SKYTEF.
**1.2 Evidência que formalize e confirme a exclusão:** **um print de um email que conste** dados do cliente (CNPJ e Razão Social, Dados da antiga Software House ou Integradora e confirme a **EXCLUSÃO** do cadastro e reset do módulo GERPDV.
**1.3** **Obrigatório que o analista envie um print deste email em resposta ao retorno de erro.**
**1.4 SLA desta solicitação dependerá de atuação time Nlógicos e time FISERV:** não deve ser informado o prazo de 24 horas úteis, o time NLOGICOS retornará assim que finalizada a ocorrência.
**2. Duplicação de Cadastro na FISERV:**
**2.1 Caso a antiga Software House ou Integradora não forneça a evidência acima ou dificulte o processo:** O cliente deve enviar **para o analista que esta tratando a solicitação) no seguinte padrão:**
- - - **Titulo do email:** Solicitação de Migração de Parceiro - FISERV
- **Corpo do email:**
- - Dados da Empresa: CNPJ e Razão social
- Formalizo o interesse de migrar de parceiro, **passarei a utilizar a CONNECT PLUG como integradora na FISERV e desejo que meu cadastro seja duplicado no ambiente FISERV**, para que a ConnectPlug possa me credenciar como seu cliente, em sua base de dados na FISERV.
- **2.2 Obrigatório que o analista envie um print deste email em resposta ao retorno de erro, no respectivo ticket,**
- **2.3 SLA desta solicitação dependerá de atuação time Nlógicos e time FISERV:** não deve ser informado o prazo de 24 horas úteis, o time NLOGICOS retornará assim que finalizada a ocorrência.
# RETORNO DE ERRO NO RELATÓRIO DE TRANSAÇÕES - PIX - NEGADA (AH)
#### O que significa?
O status **Negada (AH)** indica que a transação Pix não foi autorizada devido a uma inconsistência na configuração ou nas credenciais utilizadas para comunicação com o banco.
#### Como resolver?
Para solucionar o cenário, valide os seguintes pontos:
1. **Vínculo com o Bankline**
Verifique se a conta está corretamente vinculada ao **Bankline** utilizado para as transações Pix.
2. **Credenciais de acesso**
Confirme se as credenciais cadastradas estão corretas:
- **ID**
- **Secret**
3. **Validação das credenciais**
Caso as informações estejam incorretas ou tenham sido alteradas, **o cliente deverá acionar o suporte. O suporte deverá abrir um ticket para o time de PPI, que será responsável pela atualização das credenciais.**
#### Resolução
**Validar o vínculo com o Bankline e conferir as credenciais (ID e Secret) cadastradas para a integração Pix.**
#### Exemplo no relatório
No relatório de transações, o erro será apresentado na coluna **Estado Transação** como:
**Negada (AH)**
[](https://manual.cplug.com.br/uploads/images/gallery/2026-09/AdtPuawBJsYT5Rrd-image.png)
# RETORNO DE ERRO NO RELATÓRIO DE TRANSAÇÕES - PIX - NEGADA (03)
#### O que significa?
O status **Negada (03)** indica que a transação Pix não foi concluída. Esse retorno pode ocorrer devido a uma **falha na leitura ou no processamento do QR Code**, ao **tempo excedido para conclusão da transação** ou a uma **indisponibilidade momentânea do banco**.
#### Como resolver?
Para solucionar o cenário, valide os seguintes pontos:
1. **Leitura do QR Code**
Verifique se o QR Code foi apresentado corretamente para leitura e se não houve falha durante o processo.
2. **Tempo da transação**
Oriente o cliente a realizar uma nova tentativa, garantindo que o pagamento seja concluído dentro do tempo esperado.
3. **Disponibilidade do banco**
Verifique se não há uma indisponibilidade momentânea nos serviços do banco responsável pela transação.
4. **Nova tentativa**
Caso o cenário tenha ocorrido de forma pontual, realize uma nova tentativa de pagamento. Se a transação for concluída normalmente, o retorno pode estar relacionado a uma indisponibilidade momentânea ou falha no processamento anterior.
#### Resolução
**Orientar uma nova tentativa de pagamento e validar a leitura do QR Code. Caso o erro persista, verificar a disponibilidade dos serviços do banco e, se necessário, acionar o suporte para análise.**
#### Exemplo no relatório
No relatório de transações, o erro será apresentado na coluna **Estado Transação** como:
**Negada (03)**
[](https://manual.cplug.com.br/uploads/images/gallery/2026-09/nNqAui4LnEWSaxqb-image.png)
# RETORNO DE ERRO NO RELATÓRIO DE TRANSAÇÕES - PIX - NEGADA ZA
#### **O que significa?**
De acordo com a validação da Fiserv (Software Express), o código de retorno **Negada(ZA)** indica uma falha na validação de segurança na API do banco.
Esta falha de comunicação entre o sistema de pagamentos e a instituição financeira ocorre, geralmente, por dois motivos principais:
1. **Instabilidade Sistêmica:** Uma indisponibilidade momentânea nos serviços ou na API do próprio banco.
2. **Falha de Configuração da Chave Pix:** Ocorre quando existe um problema, bloqueio ou falta de vinculação correta da chave Pix do cliente junto ao banco. (Esta é a causa mais provável caso outras filiais ou lojas do mesmo cliente estejam transacionando normalmente).
#### **Como resolver?**
Quando confirmamos que não se trata de uma instabilidade geral e que as vendas estão ocorrendo normalmente em outros terminais, a ação deve ser direcionada para a configuração bancária do cliente.
O cliente possui três alternativas para solucionar este bloqueio:
1. **Validar o vínculo da Chave Pix:** O cliente deve acessar o seu *bankline* e confirmar se a sua chave Pix está corretamente vinculada à Fiserv (Software Express).
2. **Gerar uma nova Chave Pix:** Caso o vínculo anterior esteja corrompido, o cliente deverá gerar uma nova chave Pix no *bankline* e realizar novamente o processo de vinculação à Fiserv, conforme mencionado acima.
3. **Contatar o Suporte Bancário:** Se as validações anteriores não surtirem efeito, o cliente deverá entrar em contato direto com o suporte técnico do seu banco para verificar o motivo da recusa "ZA" (Falha de segurança na API).
#### **Exemplo no relatório:**
No painel de Relatórios do SiTef, as tentativas de pagamento via Pix apresentam o status final de **Negada(ZA)** na coluna correspondente, impedindo a conclusão das vendas.
**Negada (ZA)**
[](https://manual.cplug.com.br/uploads/images/gallery/2026-10/0Iw8v6CX1iB1gn3z-image.png)
# TRANSAÇÕES SIMULTÂNEAS EM MAIS DE UM COMPUTADOR: ERRO “SEM COMUNICAÇÃO COM O SITEF” OU TRANSAÇÃO DE UM CAIXA INTERFERINDO NA DO OUTRO
##### **O que aconteceu?**
A mensagem "sem comunicação com o SiTef" é exibida em um dos caixas. A transação de um caixa "roubou" a do outro (o segundo pagamento iniciado sobrescreve a tela que estava em andamento no primeiro).
##### **É possível transacionar em mais de um computador ao mesmo tempo?**
Sim. O sistema CPlug permite transações Pix e TEF simultâneas em quantos computadores o estabelecimento tiver. Esse erro não é uma limitação do sistema.
##### **Causa**
O problema acontece quando dois ou mais computadores estão instalados com o mesmo Ponto de Captura. O Ponto de Captura é o código que identifica cada computador perante o SiTef. Quando dois computadores usam o mesmo código, o SiTef entende que as duas transações vêm do mesmo terminal e, ao receber a segunda, interrompe a primeira.
##### **Como identificar**
Para confirmar se esse é o problema, é necessário comparar a quantidade de computadores da loja com os terminais que estão transacionando.
1. **Acesse o relatório de transações do SiTef:** Verifique as últimas operações realizadas.
2. **Avalie o número de terminais:** Compare o número de computadores físicos que o cliente possui com o número de terminais distintos que aparecem transacionando no relatório. *(Exemplo: Se o cliente tem 3 computadores, mas no relatório apenas aparecem 2 "Pontos de Captura" realizando vendas, sabemos que um computador está "roubando" o terminal do outro e usando um código duplicado).*
No *print* abaixo, vemos onde é possível identificar no relatório de transações da SiTef quais são os terminais que estão transacionando:
[](https://manual.cplug.com.br/uploads/images/gallery/2026-10/d4oRGtxxIra9bowT-image.png)
Para identificar qual o "Ponto de Captura" (Terminal) exato de cada venda, você pode clicar nos detalhes da transação. O *print* a seguir mostra um exemplo de como identificar o código do Ponto de Captura (PDV) utilizado em uma transação específica:
[](https://manual.cplug.com.br/uploads/images/gallery/2026-10/XotELT1xBs5e3nRQ-image.png)
##### **Como resolver**
Depois de ter identificado quantos computadores o cliente tem e validado que o problema é de fato a duplicação do Ponto de Captura (através da análise do relatório do SiTef), você deve reconfigurar cada computador.
No computador que está com o Ponto de Captura duplicado:
1. Acesse **Operações TEF > Instalação**, comparando o campo **Ponto de Captura** com os dos demais computadores do estabelecimento.
2. Clique em **Desinstalar**.
3. Refaça a instalação do TEF colocando no Ponto de Captura um código diferente dos demais computadores do estabelecimento. *(Exemplo: Caixa 1 com 00000010; Caixa 2 com 00000011; Caixa 3 com 00000012).*
*[](https://manual.cplug.com.br/uploads/images/gallery/2026-10/9axpABWhVR0MfZOd-image.png)*
Após efetuar a reconfiguração, faça uma transação de teste em cada computador e confirme no relatório do SiTef que cada caixa tem o seu Ponto de Captura individualizado.
**Importante:** Em toda instalação de TEF, cada computador deve ter o seu próprio Ponto de Captura. Ao adicionar um novo computador à loja, anote e instale em um número novo antes de colocar a loja para operar.