Pesquisar artigos na Base de Dados de Conhecimento

CONNECTTEF – API LOCAL SMART POS (CONSULTAR OPERAÇÃO).

Resumo do que será ensinado

Neste documento será explicado, passo a passo, como consultar uma operação TEF criada na API Local Smart POS do ConnectTEF, verificando se ela já foi concluída ou ainda está em processamento. Você aprenderá qual endpoint utilizar, quais parâmetros enviar, e como interpretar as respostas de em andamento, falha e sucesso (pagamento e estorno).

Segue um Vídeo explicativo do processo

Detalhamento do uso correto

Com este guia, você deve ser capaz de configurar o seu sistema Desktop ou automação comercial para acompanhar operações TEF criadas no Smart POS, fazendo consultas periódicas até que a operação seja concluída e utilizando os dados retornados para finalizar vendas, estornos e impressão de comprovantes.

Segue o detalhamento de como Consultar Operação na API Local Smart POS

Entender o objetivo da funcionalidade “Consultar operação”
- A rota Consultar operação é usada para acompanhar o status de uma operação TEF que já foi criada anteriormente via Criar operação.
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
- Ela permite saber:
  - Se a operação ainda está em andamento.
  - Se a operação foi concluída com sucesso (pagamento ou estorno aprovado).
  - Se a operação falhou ou foi cancelada.
    Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
Ponto importante
- Criar operação inicia o processo; Consultar operação é o que informa o resultado final que seu sistema deve usar para fechar a venda ou registrar o estorno.
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Endpoint e método HTTP utilizados
- Endpoint Local:
  - http://localhost:3000/api/v1/operacao.
    Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
- Método HTTP:
  - GET (consulta o status de uma operação existente).
    Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
Ponto importante
- Assim como em Criar operação, este endpoint é local, ou seja, seu sistema fala diretamente com o serviço do POS na máquina/rede do cliente.
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Cabeçalho (Header) obrigatório

Na requisição GET, é obrigatório enviar o cabeçalho:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
- Content-Type: application/json
Ponto de atenção
- Mesmo em uma requisição GET, o serviço exige esse Content-Type para manter o padrão de comunicação em JSON.
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Parâmetro de Query obrigatório (Query Params)

Para consultar uma operação específica, é necessário informar o identificador da transação que foi usado ao criar a operação:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
- Campo: identificacao
- Tipo: string
- Obrigatório: Sim
- Descrição: ID único da transação no seu sistema (mesmo valor enviado na criação da operação).
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
Exemplo de chamada:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
- GET http://localhost:3000/api/v1/operacao?identificacao=abc123
Pontos de atenção
- Se identificacao for informado incorretamente ou não existir, a resposta não corresponderá à operação desejada.
- Mantenha esse identificador armazenado no seu sistema para cada operação criada, garantindo rastreabilidade.
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Exemplo de resposta “Em andamento”

Quando a operação ainda não foi concluída, a API retorna um JSON indicando que está em processamento:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

   {
     "executada": false,
     "textoEspecialOperador": "PROCESSANDO..."
   }

Interpretação:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
- executada: false → A operação ainda não terminou; está aguardando ação no POS.
- textoEspecialOperador: "PROCESSANDO..." → Mensagem de status para o operador.
Ponto importante
Com executada = false, seu sistema deve continuar consultando a operação (fazer polling) até que executada se torne true.

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
.

Exemplo de resposta com falha

Se a operação foi concluída mas não aprovada, o retorno traz executada = true com um código de erro e mensagem:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

   {
     "executada": true,
     "statusTransacao": "1001",
     "textoEspecialOperador": "Cartão inválido"
   }

Interpretação:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
- executada: true → A operação foi concluída (não está mais em andamento).
- statusTransacao: "1001" → Código de status indicando falha na transação.
- textoEspecialOperador: "Cartão inválido" → Motivo da falha, exibido para o operador.
Pontos de atenção
Seu sistema deve tratar esses casos como pagamento/estorno não realizado.
É recomendável:
- Registrar o código e mensagem.
- Permitir tentar outro pagamento ou outra forma de cobrança.
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .

Exemplo de resposta com sucesso (Pagamento aprovado)

Quando um pagamento é aprovado, o retorno traz uma estrutura completa com todos os dados da transação:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

   {
     "identificacao": "abc123",
     "valorTotal": "100",
     "statusTransacao": "0",
     "nomeRede": "PINBANK",
     "tipoTransacao": "20",
     "numeroTransacao": "119",
     "codigoAutorizacaoTransacao": "695499",
     "timestampTransacaoHost": "1607175018",
     "quantidadeParcelas": "1",
     "dataTransacaoComprovante": "16072025",
     "horaTransacaoComprovante": "175018",
     "finalizacao": "2117132|695499|695499",
     "quantidadeLinhasComprovante": "14",
     "numeroSerieTerminal": "PBF923CC70331",
     "comprovante": "\"-----------------------------------------\"\n\" VIA CLIENTE \"\n\"-----------------------------------------\"\n\"VALOR 1,00\"\n\"FORMA PAGAMENTO Débito à vista\"\n\"CARTAO 550209****9039\"\n\"REDE PINBANK\"\n\"TERMINAL PBF923CC70331\"\n\"NSU 119\"\n\"AUT 695499\"\n\"CODE 695499\"\n\"-----------------------------------------\"\n\" PDVPOS - CONNECT TEF \"\n\" 16/07/2025 17:50:18 \"\n",
     "executada": true,
     "cnpj": "42407441000152",
     "bandeiraCartao": "MASTERCARD"
   }

Campos principais:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
- identificacao – ID da operação (igual ao enviado na criação).
- valorTotal – valor efetivamente cobrado.
- statusTransacao: "0" – indica sucesso na transação.
- nomeRede – nome da rede adquirente (ex.: PINBANK).
- tipoTransacao – tipo de transação (código conforme tabela de tipos).
- numeroTransacao – NSU/identificador da transação no adquirente.
- codigoAutorizacaoTransacao – código de autorização da transação.
- timestampTransacaoHost – momento em que o host processou a operação.
- quantidadeParcelas – número de parcelas.
- dataTransacaoComprovante e horaTransacaoComprovante – data e hora exibidas no comprovante.
- finalizacao – string técnica usada para conciliação.
- quantidadeLinhasComprovante – quantidade de linhas do texto do comprovante.
- numeroSerieTerminal – número de série do POS.
- comprovante – texto completo do comprovante (via cliente).
- cnpj – CNPJ do estabelecimento.
- bandeiraCartao – bandeira do cartão (ex.: MASTERCARD).
- executada: true – a operação está concluída.
Pontos de atenção
Com essa resposta, seu sistema pode:
- Fechar a venda (baixar estoque, emitir documento fiscal).
- Armazenar numeroTransacao, codigoAutorizacaoTransacao e finalizacao para conciliação financeira.
- Imprimir ou exibir o comprovante ao cliente.
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .

Exemplo de resposta com sucesso (Estorno aprovado)

Em um estorno aprovado, a estrutura é semelhante, mas com campos adicionais relacionados à transação cancelada:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

   {
     "identificacao": "abc123",
     "valorTotal": "100",
     "statusTransacao": "0",
     "nomeRede": "PINBANK",
     "tipoTransacao": "20",
     "numeroTransacao": "119",
     "codigoAutorizacaoTransacao": "695499",
     "timestampTransacaoHost": "1607175018",
     "quantidadeParcelas": "1",
     "dataTransacaoComprovante": "16072025",
     "horaTransacaoComprovante": "175018",
     "numeroTransacaoCancelada": "119",
     "timestampTransacaoCancelada": "1607175018",
     "finalizacao": "2117132|695499|695499",
     "quantidadeLinhasComprovante": "000",
     "numeroSerieTerminal": "PBF923CC70331",
     "comprovante": "\"-----------------------------------------\"\n\" VIA CLIENTE \"\n\"-----------------------------------------\"\n\"VALOR 1,00\"\n\"FORMA PAGAMENTO Débito à vista\"\n\"CARTAO 550209****9039\"\n\"REDE PINBANK\"\n\"TERMINAL PBF923CC70331\"\n\"NSU 119\"\n\"AUT 695499\"\n\"CODE 695499\"\n\"-----------------------------------------\"\n\" PDVPOS - CONNECT TEF \"\n\" 16/07/2025 17:50:18 \"\n",
     "executada": true,
     "cnpj": "42407441000152",
     "bandeiraCartao": "MASTERCARD"
   }

Campos adicionais relevantes:

Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
- numeroTransacaoCancelada – NSU da transação original que foi estornada.
- timestampTransacaoCancelada – momento da transação original.
- quantidadeLinhasComprovante: "000" – pode indicar diferença na forma de emissão do comprovante de estorno.
Pontos de atenção
Vincule o estorno à transação original usando numeroTransacaoCancelada.
Ajuste o status financeiro da venda apenas quando statusTransacao = "0".

Fluxo recomendado de uso pelo seu sistema
- Passo 1 – Criar operação
  - Chamar POST /api/v1/operacao?tipoOperacao=0/1/2 com identificacao e dados da operação.
- Passo 2 – Armazenar identificacao
  - Guardar esse ID no banco de dados ou contexto da venda.
- Passo 3 – Consultar operação (Polling)
  - Chamar GET /api/v1/operacao?identificacao=... em intervalos regulares.
    Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Se executada = false → continuar consultando.
  - Se executada = true → analisar statusTransacao e demais campos.
- Passo 4 – Atualizar venda/estorno
  - Sucesso (statusTransacao = "0"): concluir venda ou registrar estorno.
  - Falha: registrar motivo e permitir nova tentativa ou outro meio de pagamento.
Ponto importante
- Não finalize processos internos (como emissão de NF ou baixa definitiva de estoque) antes de receber uma resposta com executada = true e interpretar o statusTransacao.
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  .

Informações Importantes

Função de “Consultar operação”: acompanhar operações TEF iniciadas via Criar operação, indicando se estão em andamento ou concluídas, com sucesso ou falha.
Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
Endpoint e parâmetros:
- Endpoint: http://localhost:3000/api/v1/operacao.
- Método: GET.
- Header obrigatório: Content-Type: application/json.
- Query obrigatória: identificacao (ID único da transação).
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
Campo crítico:
- executada:
- false → operação em processamento.
- true → operação concluída (sucesso ou falha).
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
Exemplos de retorno:
- Em andamento: apenas executada = false e mensagem de processamento.
- Falha: executada = true, statusTransacao ≠ "0", mensagem explicando o erro.
- Sucesso (pagamento/estorno): conjunto completo de campos (valorTotal, numeroTransacao, codigoAutorizacaoTransacao, comprovante, etc.).
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
Benefícios de seguir corretamente o procedimento:
- Garantia de que seu sistema só conclui vendas/estornos com base em dados confirmados pelo POS.
- Melhora a rastreadilidade e conciliação financeira, usando NSU, códigos de autorização e finalização.
- Reduz erros causados por considerar operações como concluídas antes do retorno final.
  Consultar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
Recomendações gerais:
- Utilize este documento na sua base de conhecimento para treinar desenvolvedores e suporte.
- Implemente um mecanismo de polling com intervalos adequados à experiência do usuário.
- Logue todas as chamadas de consulta e respostas para facilitar auditoria e resolução de problemas.

Este texto está pronto para ser copiado em um documento Word da sua base de conhecimento. Aplique o padrão visual indicado: título com fonte 34, demais cabeçalhos (Resumo, Vídeo, Detalhamento, Informações Importantes) com fonte 18, e o corpo em fonte menor, mantendo os pontos essenciais 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 – API LOCAL SMART POS (CONSULTAR OPERAÇÃ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.