TEF Cloud - Instalação/Configuração

1. Visão Geral
O TEF Cloud no TryERP utiliza o ControlPay (PayGo) como intermediador de pagamentos, com comunicação via API REST e execução local através do PayGo Windows.
Essa documentação tem como objetivo orientar o time de suporte na configuração correta e resolução de problemas.

2. Instalação do PayGo Windows
Para o funcionamento do TEF Cloud, é obrigatório instalar o PayGo Windows em cada estação (caixa/PDV) que receberá pagamentos.

📥 Download
👉 https://paygodev.readme.io/docs/kit-de-integração-1

Acessar a página do link acima

Localizar Kit de Integração

Clicar em “Clique aqui” para baixar

💻 Instalação

Executar o instalador baixado

Informar o CPF ou CNPJ da empresa

Inserir o ID de instalação recebido

Inserir a Senha recebida
Clicar em Ativar
Quando solicitar a Porta USB do PIN PAD, digite 0 (zero) e tecle ENTER

▶️ Execução

O PayGo será executado e ficará disponível ao lado do relógio do Windows (bandeja do sistema)

⚙️ Configuração inicial
Após a instalação:

Abrir o PayGo (ícone na bandeja)

Acessar Configurações

Validar:

Comunicação com PIN Pad

Configuração de impressão (se aplicável)

⚠️ Importante

O PayGo deve estar em execução para que o TEF funcione

Deve ser instalado em todas as máquinas de caixa

O PIN Pad deve estar corretamente conectado e reconhecido

Sem o PayGo, nenhuma transação será iniciada

🧪 Teste recomendado
Após instalar:

Acessar a opção Testar conexão com PIN Pad dentro do PayGo

Garantir que o dispositivo responde corretamente

3. Configuração no Painel ControlPay
O ControlPay possui configurações essenciais que impactam diretamente o funcionamento do ERP.

3.1 Geração da Chave de Integração
⚠️ IMPORTANTE
O botão “Login / Obter Chave” do ERP NÃO deve ser utilizado, pois gera uma chave com validade (expira).

✅ Procedimento correto:

Acessar o painel ControlPay

Ir em:Integrações / Config → Aba Chaves de Integração

Clicar em Nova chave

Preencher:

Nome: tryerp (ou outro identificador)

Não informar data de expiração

Salvar

Copiar a chave gerada para o ERP

3.2 Configuração de Terminais
📍 Menu: Terminais

Regras:

Cada PDV = 1 terminal

Código será usado no ERP

Não compartilhar entre caixas

4. Configuração do TEF Cloud no ERP (Por Filial)
📍 Configurações → Configurações Adicionais → Aba TEF Cloud

Campos
Filial

Configuração independente por empresa

Provedor

ControlPay

URL da API

Ambiente
URL

Sandbox
https://sandbox.controlpay.com.br/webapi

Produção
https://api.controlpay.com.br

Senha ControlPay

❌ Não utilizar

Chave de Integração

Deve ser gerada no ControlPay

❗ Sem expiração

Terminal Padrão

Terminal fallback (informar o número do terminal padrão a ser utilizado, caso não seja definido na sessão, ou logado com sessão incorreta). Atenção a essa configuração, o terminal do Operador precisa ser utilizado no mesmo Caixa para onde foi configurado, pois existe um "vínculo" da instalação do ControlPay na máquina com o terminal configurado para o Operador. Em resumo, imagine o sistema executando na nuvem, ao iniciar a transação envia um comando para a api do PayGo onde é enviado o terminal, e a api vai se localizar e se comunicar com o app instalado na máquina. Se possuir 2 caixas e inverter os Operadores, o PayGo será exibido no PDV incorreto.

Senha Técnica

Usada para cancelamento

Deve coincidir com ControlPay

Timeout

Padrão: 120s

Polling

Padrão: 3s

Produção

Marca ambiente real

Ativo

Habilita TEF

Botões

❌ Login / Obter Chave → não usar

✔️ Testar Conexão → validar integração

✔️ Salvar

⚠️ Erros comuns

Chave expirada

URL incorreta

Integração inativa

5. Configuração por Operador (Sessão)
📍 Configurações → Configurar Sessão

Campo obrigatório

Terminal TEF Cloud

Regras

Cada operador = 1 terminal

Deve existir no ControlPay

Define o PIN Pad utilizado

6. Senha Técnica (Cancelamento)
A senha técnica é utilizada para realizar estornos.

📍 Onde obter:
ControlPay → Integrações / Config → Aba Opções da Venda

📌 Configuração:

Copiar a senha técnica

Informar no ERP em:

Configuração TEF Cloud (por filial)

⚠️ Regra importante:

O cancelamento só pode ser feito pelo mesmo terminal que realizou a venda

7. Cancelamento de Transações
Regras:

Cancelamento depende da senha técnica correta

Deve ser feito pelo mesmo terminal

Pode ser feito:

Pela tela de transações TEF

Pelo cancelamento da venda (NFe/NFCe/Movimento)

8. Configuração do PayGo Windows (Impressão)
O PayGo pode ser responsável pela impressão dos comprovantes.

📍 Caminho:

Abrir o PayGo (ícone ao lado do relógio)

Acessar Configurações

⚙️ Configurar:

Habilitar:

Serviço de impressão automático

Tipo:

Windows

Selecionar impressora desejada

⚠️ Integração com ERP:
Se a impressão for feita pelo PayGo:
👉 No ERP (Configurar Sessão):

Marcar opção: Não imprimir TEF Cloud

🔁 Regra:

Situação
Configuração

Impressão via PayGo
ERP NÃO imprime

Impressão via ERP
PayGo NÃO imprime

9. Cadastro de Administradoras
Foram adicionados novos campos para otimizar o fluxo de pagamento.

Novos campos:

Adquirente Cartão

Adquirente PIX

Funcionamento:

Se preenchido:

O PayGo não solicita seleção

Fluxo direto para pagamento

Se não preenchido:

Operador precisa escolher a adquirente

📌 Quando usar:

Cliente possui múltiplas adquirentes

Deseja automatizar o fluxo

10. Cadastro de Produtos / Serviços
Para melhorar a automação no pagamento:

Configuração obrigatória:

Definir o Tipo de Cartão:

Crédito

Débito

PIX

Benefício:

PayGo já recebe a informação

Não exibe opções para o operador

Processo mais rápido e sem erros

11. Logs do Sistema
Os logs são essenciais para análise de problemas.

📁 Local:

{diretório do sistema}\logs

📄 Nome do arquivo:

TEFCloud_Terminal{codigo}_{ddMMyyyy}.log

📌 Exemplo:

TEFCloud_Terminal5453_18032026.log

📊 Conteúdo:

Envio de transações

Retornos da API

Status de processamento

Erros

🕒 Retenção:

Mantidos por 7 dias

Após isso, são removidos automaticamente

12. Log Detalhado (Debug)
Para análise avançada:

📍 Caminho:
👉 Configurações → Configurações Globais→ Financeiro → Configurações do Caixa

Opção:

Habilitar log detalhado do TEF Cloud

🔍 O que muda:

Salva JSON completo:

Requisição

Resposta da API

⚠️ Uso recomendado:

Apenas para suporte / diagnóstico

Pode gerar arquivos maiores

13. Boas Práticas de Suporte

Sempre validar:

Chave de integração (sem expiração)

Terminal configurado corretamente

Senha técnica válida

Conferir se o PayGo está aberto

Validar conexão com internet

Verificar logs antes de acionar terceiros

Desativar economia de energia USB

No gerenciador de dispositivos, em cada USB Root Hub, abra as propriedades e na aba Gerenciamento de Energia, desmaque a opção "O computador pode desligar...", após isso clique em OK para salvar.

14. Problemas Comuns
❌ Transação não inicia

Terminal não configurado

Chave inválida

PayGo não aberto

❌ Erro ao cancelar

Senha técnica incorreta

Tentativa em terminal diferente

❌ PIN Pad não responde

PayGo não está rodando

Problema de driver/conexão

❌ Impressão duplicada

PayGo e ERP imprimindo juntos

15. Checklist Rápido (Suporte)
Antes de escalar:

✔️ PayGo aberto

✔️ PIN Pad funcionando

✔️ Terminal configurado

✔️ Chave válida

✔️ Senha técnica correta

✔️ URL correta

✔️ Integração ativa

16. Considerações Finais
A maioria dos problemas está relacionada a:

Configuração incorreta de terminal

Uso de chave expirada

Falha na instalação/configuração do PayGo

17. Dados para Integração com PayGo (ACBr)
Para ativação do TEF Cloud junto ao PayGo, é necessário realizar um cadastro junto ao integrador (ACBr), que fará a validação dos dados com a adquirente.

📌 Dados obrigatórios
Devem ser informados os seguintes dados:

Estabelecimento

Lógico TEF (nem sempre irá existir essa informação)

Esses dados são utilizados para:

Identificar o cliente junto à adquirente
Validar o credenciamento
Liberar o uso do TEF Cloud no ambiente

🔄 Processo

O cliente fornece os dados ao suporte
O suporte envia para o ACBr
O ACBr realiza validação com a adquirente
Após validação, o ambiente é liberado para uso

🔍 Onde obter esses dados
🔹 1. Comprovante de venda (POS)
Se o cliente já possui uma maquininha (POS), os dados podem ser encontrados no comprovante impresso.
Exemplo:

ESTAB / EC → número do estabelecimento

Lógico TEF → número do terminal lógico

📌 Normalmente aparecem como:

ESTAB=XXXXXXXXXXXX

TERM=XXXXXXXX ou similar

🔹 2. E-mail da adquirente
Caso o cliente não possua POS:

Os dados são enviados por e-mail pela adquirente no momento do credenciamento

📌 O cliente deve:

Localizar o e-mail de credenciamento
Ou solicitar novamente junto à adquirente

💡 Orientação para suporte
Ao solicitar os dados ao cliente:

Pedir foto de um comprovante recente (se tiver POS)ou

Solicitar o e-mail de credenciamento da adquirente

Isso evita erro de digitação e acelera a liberação.