Pesquisar artigos na Base de Dados de Conhecimento

CONNECTTEF – INTEGRAÇÃO VIA API (INTRODUÇÃO E VINCULAÇÃO).

Resumo do que será ensinado

Este documento explica, em linguagem acessível, como funciona a integração via API do ConnectTEF e detalha passo a passo o processo de Vinculação do POS (SmartPOS) ao seu sistema (PDV/ERP). Você verá os conceitos de segurança (mTLS, token), o fluxo assíncrono com Webhook, e o passo a passo da requisição de QR Code, leitura pelo POS e recebimento dos dados de vinculação.

Segue um Vídeo explicativo do processo

Detalhamento do uso correto

Com este guia, você deve ser capaz de preparar seu sistema para integrar com o ConnectTEF via API, configurar o fluxo de vinculação de forma correta e segura, e entender quais dados são retornados pelo Webhook para uso nas transações futuras.

Segue o detalhamento de como usar a Introdução da Integração via API e a Vinculação

Entender o contexto: integração via API ConnectTEF
- A integração via API permite que seu sistema (PDV/ERP, WEB ou SaaS) se comunique diretamente com os terminais POS (SmartPOS) usando a infraestrutura do ConnectTEF.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
- O modelo é seguro e assíncrono:
  - Segurança garantida por mTLS (mutual TLS), exigindo certificado digital de cliente válido.
  - Respostas finais de operações (como pagamento) são enviadas ao seu Webhook, e não na mesma chamada que inicia a transação.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
- Antes de qualquer pagamento, o POS precisa estar vinculado ao seu sistema, e é exatamente isso que o processo de Vinculação resolve.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos importantes
- Sem vinculação, o POS não está associado ao seu PDV/ERP, e você não terá os dados necessários (como uuidTerminal) para operar.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
O que é “Vinculação” e por que é obrigatória
- Vinculação é o processo que associa o POS (SmartPOS) ao seu ponto de venda (PDV ou sistema ERP).
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
- Durante esse processo são definidos:
  - Qual POS está ligado a qual PDV.
  - Qual Webhook receberá os eventos (dados da vinculação, pagamentos etc.).
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
- A partir da vinculação, você passa a ter:
  - Identificador único do terminal (uuidTerminal).
  - Dados como IP local, MAC Address e CNPJ da empresa, que podem ser usados em regras internas.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos importantes
- A vinculação é pré-requisito para qualquer transação: sem ela não há como iniciar pagamentos com aquele POS.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Fluxo geral da Vinculação (visão passo a passo)

O fluxo completo de vinculação funciona assim:

Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
1. Seu sistema solicita um QR Code ao ConnectTEF via API.
2. Seu sistema exibe esse QR Code na tela (por exemplo, na tela de configuração de PDV).
3. O operador usa o aplicativo embarcado no POS para escanear o QR Code.
4. Após leitura com sucesso, o ConnectTEF envia os dados da vinculação para o Webhook informado na requisição (callbackUrl).
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos importantes
- O QR Code não é estático; ele é gerado pela API para aquele PDV/numeroSerie e aquele callbackUrl específicos.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Preparar seu sistema para fazer a requisição de QR Code
- Antes da chamada, garanta que seu sistema tenha:
  - Um identificador único da automação, que será usado como numeroSerie (por exemplo: caixa001).
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Um endpoint Webhook público, que será usado como callbackUrl e poderá receber as informações de vinculação.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Opcionalmente, um token para proteger seu Webhook (campo callbackToken).
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
- A requisição de QR Code é feita via HTTP com os seguintes parâmetros:
  
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Método: GET.
  - Endpoint: https://apitef.pdvpos.com.br/api/v1/web-service/qrcode.
  - Query Params obrigatórios:
  - numeroSerie: identificação do PDV ou automação (ex.: caixa001).
  - callbackUrl: URL do seu Webhook que receberá os dados da vinculação.
  - Query Param opcional:
  - callbackToken: token que será enviado no header token do Webhook.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Exemplo de chamada (modelo)

Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
- GET /api/v1/web-service/qrcode?numeroSerie=caixa001&callbackUrl=https://webhook.com.br/response&callbackToken=abc1234
Pontos de atenção
- numeroSerie deve ser estável e único para cada PDV (não use valores aleatórios), pois será utilizado também nas transações futuras.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Tratar a resposta de sucesso (dados do QR Code)
- Em caso de sucesso, a API devolve um JSON como:
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
```
 {
   "qrCode": "9512aad025a1ae..."
 }
```
- Passos no seu sistema:
  - Ler o campo qrCode retornado.
  - Gerar a imagem de QR Code a partir desse texto (usando sua biblioteca de QR favorita).
  - Exibir essa imagem na tela para o operador do PDV.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos de atenção
- Exiba o QR Code de forma legível (tamanho adequado) para que o POS possa escanear sem falhas.
Leitura do QR Code pelo POS
- Com o QR Code na tela:
  - O operador acessa o aplicativo do ConnectTEF no POS.
  - Escolhe a opção de vinculação (conforme orientações do manual do POS).
  - Aponta a câmera do POS para o QR Code exibido na tela do seu sistema.
- Se a leitura for bem-sucedida:
  - O ConnectTEF processa os dados.
  - Em seguida, envia as informações de vinculação para o seu Webhook (callbackUrl).
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos de atenção
- Oriente o operador a aguardar a confirmação, pois a vinculação só se completa após o envio ao Webhook e o processamento pelo seu sistema.
Receber e tratar o Webhook de vinculação
- Após a leitura do QR Code, o ConnectTEF envia para o callbackUrl informado um JSON com dados da vinculação:
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
```
 {
   "uuidTerminal": "abc123",
   "rede": "Mercado Pago",
   "numeroSerieTerminal": "abc123",
   "ipLocal": "192.168.0.25",
   "macAddress": "74:F7:F...",
   "cnpjEmpresa": "42580012000182"
 }
```
- Headers da chamada ao Webhook:
  
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - token: abc1234 (se você tiver informado callbackToken na requisição do QR Code).
- Dentro do seu Webhook você deve:
  - Ler o corpo da requisição.
  - Gravar os dados de vinculação em sua base, associando:
  - uuidTerminal ao numeroSerie do PDV.
  - cnpjEmpresa ao cliente/empresa correspondente.
  - rede (ex.: Mercado Pago) ao terminal.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos de atenção
- O token recebido no header deve ser validado para confirmar que a chamada veio do ConnectTEF, caso você tenha usado callbackToken.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Regras importantes após a vinculação
- A documentação destaca algumas regras essenciais:
  
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Toda requisição futura (pagamento, estorno etc.) deve usar:
  - O mesmo CPF/CNPJ obtido na vinculação.
  - O mesmo numeroSerie utilizado na requisição do QR Code.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Um POS pode ser atribuído a vários PDVs.
  - Um PDV pode ser atribuído a vários POSs.
  - O token é opcional, mas fortemente recomendado para validar as chamadas ao Webhook.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos de atenção
- Planeje sua modelagem de dados para permitir múltiplos POS por PDV e múltiplos PDVs por POS, se o seu negócio exigir essa flexibilidade.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Integração via API – segurança e fluxo assíncrono (resumo)
- Segurança (mTLS):
  - Toda chamada à API ConnectTEF usa mTLS, exigindo certificado digital de cliente X.509 válido.
  - Certificados inválidos ou expirados resultam em HTTP 403 – Forbidden.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
- Fluxo assíncrono via Webhook:
  - A criação de operações (como pagamento) é feita via chamada à API.
  - O resultado final (autorizado, cancelado, erro) não é devolvido nessa mesma chamada, mas sim via Webhook.
  - O uso de token no header reforça a autenticação das chamadas ao seu Webhook.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos de atenção
- Monte sua lógica de negócio considerando esse modelo assíncrono: salve o ID da operação, aguarde o Webhook e só finalize a venda após receber o status final.
Próximos passos após a Vinculação
- Depois de implementar e validar a vinculação:
  - Avance na documentação para os próximos tópicos da integração via API:
  - Pagamento: como iniciar uma transação de venda usando o POS vinculado.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Estorno: como desfazer uma transação autorizada.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Testes via Postman (no caso de WEB/SaaS): como simular chamadas da API.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Garanta que todos os fluxos (pagamento, estorno) utilizem:
  - O CPF/CNPJ obtido na vinculação.
  - O mesmo numeroSerie usado na geração do QR Code.
    Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos de atenção
- Mantenha um registro claro de quais POS estão vinculados a quais PDVs, pois isso será fundamental para suporte, auditoria e expansão da operação.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .

Informações Importantes

Vinculação é obrigatória: sem vincular o POS ao PDV/ERP, não é possível realizar transações de pagamento com aquele terminal.
Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Fluxo de vinculação:
- Seu sistema solicita o QR Code (GET com numeroSerie, callbackUrl, callbackToken opcional).
- Exibe o QR Code para leitura pelo POS.
- Após leitura, o ConnectTEF envia os dados para o seu Webhook.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Dados recebidos no Webhook:
- uuidTerminal, rede, numeroSerieTerminal, ipLocal, macAddress, cnpjEmpresa e o header token (se utilizado).
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Regras pós-vinculação:
- Use sempre o mesmo CPF/CNPJ e numeroSerie para as requisições futuras.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
- POS e PDVs podem se relacionar em múltiplas combinações.
- O token é opcional, mas recomendado para validar as chamadas de Webhook.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Segurança na API:
- Todas as chamadas exigem certificado digital de cliente (mTLS).
- Certificados inválidos geram erro 403.
- Webhooks devem estar preparados para receber chamadas externas com token no header.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade
Benefícios de seguir corretamente o procedimento:
- Integração segura, com autenticação forte.
- Operação estável e rastreável, com POS claramente vinculados aos PDVs.
- Base sólida para implementar operações de pagamento, estorno e testes sem erros de vinculação.
  Vinculação | Conecte seu sistema a múltiplas adquirentes com facilidade

Este texto está preparado para ser colado diretamente em um documento Word da sua base de conhecimento. Aplique o padrão visual: título com fonte 34, demais cabeçalhos (Resumo, Vídeo, Detalhamento, Informações Importantes) com fonte 18, e corpo em fonte menor, mantendo os termos críticos em negrito para facilitar a leitura por iniciantes.

Você achou esse artigo útil?

Problema de Comunicação Constante no Conect TEF

Problema de Comunicação Constante no Conect TEF Descrição do Problema O sistema ...
Conect TEF fechando sozinho

Conect TEF fechando sozinho. Descrição do Problema Alguns clientes que utilizam o Co...
Como acessar e cadastrar gerenciador (NOME DO SISTEMA).

Resumo do que será ensinado Neste documento será apresentado, de forma detalhada e passo a...
CONNECTEF – MODELO DE IMPLANTAÇÃO AUTÔNOMO (SELF‑SERVICE).

Resumo do que será ensinado Neste documento você vai entender, de forma estruturada e simp...
CONNECTTEF – INTRODUÇÃO À PLATAFORMA.

Resumo do que será ensinado Neste documento você vai entender, de forma clara e estruturad...

Pesquisar artigos na Base de Dados de Conhecimento

CONNECTTEF – INTEGRAÇÃO VIA API (INTRODUÇÃO E VINCULAÇÃO).

Você achou esse artigo útil?

Artigos relacionados

Problema de Comunicação Constante no Conect TEF

Conect TEF fechando sozinho

Como acessar e cadastrar gerenciador (NOME DO SISTEMA).

CONNECTEF – MODELO DE IMPLANTAÇÃO AUTÔNOMO (SELF‑SERVICE).

CONNECTTEF – INTRODUÇÃO À PLATAFORMA.