Pesquisar artigos na Base de Dados de Conhecimento

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

Resumo do que será ensinado

Neste documento será explicado, de forma detalhada e em linguagem acessível, como criar uma operação TEF pela API Local Smart POS do ConnectTEF, a partir de um sistema Desktop ou automação comercial. Você verá o endpoint correto, parâmetros obrigatórios e opcionais, tipos de operação possíveis (pagamento, estorno, impressão), exemplos de requisição e como interpretar os campos de retorno, principalmente o indicador executada. 

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

Segue um Vídeo explicativo do processo

Detalhamento do uso correto

Com este guia, você deve ser capaz de configurar o seu sistema para enviar operações de pagamento, estorno ou impressão ao Smart POS, via API local, entendendo claramente como montar a requisição HTTP POST, quais campos precisam ser informados em cada tipo de operação e como usar o retorno para iniciar o fluxo de consulta da operação até sua conclusão. 

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

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

  1. Entender o objetivo da funcionalidade “Criar operação”

    • A rota Criar operação da API Local Smart POS é utilizada para iniciar uma operação TEF no terminal, podendo ser:
      • Pagamento (cobrar um valor do cliente).
      • Estorno (reverter uma transação anterior).
      • Impressão (imprimir comprovante ou outro conteúdo via POS). 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • Esta chamada não conclui a transação por si só. Ela:
      • Cria a operação.
      • Retorna um primeiro estado (normalmente com executada = false).
      • A partir daí, o sistema integra deve consultar a operação até ela ser finalizada (fluxo visto na Introdução/Consultar operação). 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

    Ponto importante

    • Tenha em mente que Criar operação é o primeiro passo. Para saber se a transação foi aprovada ou cancelada, será necessário usar depois o endpoint de Consultar operação. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  2. Endpoint e método HTTP utilizados

    • Endpoint Local:
      • http://localhost:3000/api/v1/operacao. 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • Método HTTP:
      • POST (envia uma nova operação ao POS). 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • O POS (Smart POS) e o serviço local do ConnectTEF devem estar rodando na máquina ou rede do cliente para que o endereço localhost:3000 seja alcançável. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

    Ponto importante

    • Este endpoint é local, ou seja, a comunicação ocorre entre o seu sistema e o serviço do POS na mesma máquina/rede, sem depender diretamente da API em nuvem. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  3. Cabeçalho (Header) obrigatório

    • Na requisição POST é obrigatório enviar o seguinte cabeçalho: 

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

      • Content-Type: application/json

    • Isso informa ao serviço que o corpo da requisição será um JSON, formato padrão usado pela API Local Smart POS. 

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

    Ponto de atenção

    • Sem o Content-Type correto, o serviço pode não interpretar o JSON adequadamente, gerando erros de operação. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  4. Parâmetros de Query (Query Params)

    Ao criar uma operação, é obrigatório informar o tipo de operação por meio de um parâmetro na URL: 

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

    • Parâmetro: tipoOperacao
    • Tipo: int
    • Função: Indica qual operação TEF será executada pelo POS. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

    Valores possíveis para tipoOperacao: 

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

    • 0 – Pagamento
    • 1 – Estorno
    • 2 – Impressão

    Exemplo de uso na URL: 

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

    • Pagamento:
      • POST http://localhost:3000/api/v1/operacao?tipoOperacao=0

    Pontos de atenção

    • Se tipoOperacao não for informado ou estiver com valor inválido, o serviço não saberá qual fluxo aplicar (pagamento, estorno ou impressão), causando falha na operação. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  5. Parâmetros de Corpo (Body Params) – visão geral

    O corpo da requisição (Body) é enviado em formato JSON e contém os dados específicos da operação. Os principais campos descritos na documentação são: 

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

    • identificacao (string) – Obrigatório para Pagamento e Estorno
    • valorTotal (decimal) – Obrigatório para Pagamento e Estorno
    • tipoTransacao (string) – Obrigatório para Estorno
    • quantidadeParcelas (string) – Opcional
    • imprimirComprovante (bool) – Opcional
    • numeroTransacao (string) – Obrigatório para Estorno
    • finalizacao (string) – Obrigatório para Estorno

    A seguir, cada campo é explicado separadamente.

  6. Campo identificacao

    • Tipo: string
    • Obrigatório em: Pagamento, Estorno. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • Descrição: ID único da transação no seu sistema (ERP/PDV).
      • Serve para correlacionar a operação TEF com o registro interno de venda.
      • Exemplo: código da venda, número do pedido, ID do carrinho, etc.

    Ponto de atenção

    • É recomendável que este ID seja verdadeiramente único para evitar confusão na conciliação de operações. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  7. Campo valorTotal

    • Tipo: decimal
    • Obrigatório em: Pagamento, Estorno. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • Descrição: Valor total da venda ou do estorno, em formato decimal.
      • Exemplo: 29.9 para representar R$ 29,90. 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

    Ponto de atenção

    • Certifique-se de utilizar ponto como separador decimal, seguindo o padrão da API (29.9 e não 29,9). 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  8. Campo tipoTransacao (para Estorno)

    • Tipo: string
    • Obrigatório em: Estorno. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • Descrição: Código do tipo de transação que será estornada (crédito, débito, PIX, etc.).

    Tabela de códigos disponíveis (tipoTransacao): 

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

    • 10 – Crédito à Vista
    • 11 – Crédito Parcelado (Estabelecimento)
    • 12 – Crédito Parcelado (Cliente)
    • 20 – Débito
    • 30 – PIX / Carteira Digital
    • 60 – Voucher / PAT

    Ponto de atenção

    • Use o mesmo código de transação da venda original que está sendo estornada, para que o POS e a adquirente reconheçam o tipo correto. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  9. Campo quantidadeParcelas

    • Tipo: string
    • Obrigatório: Não (Opcional). 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • Descrição: Número de parcelas, utilizado em transações de crédito parcelado.
      • Exemplo: "1" para uma parcela única, "3" para três parcelas, etc. 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

    Ponto de atenção

    • Deve ser compatível com as regras da adquirente e do estabelecimento (ex.: máximo de parcelas permitidas). 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  10. Campo imprimirComprovante

    • Tipo: bool (booleano).
    • Obrigatório: Não (Opcional). 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • Descrição: Indica se o POS deve imprimir comprovante automaticamente após a operação.
      • true – imprime comprovante.
      • false – não imprime. 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

    Ponto de atenção

    • Ajuste este campo conforme o fluxo do seu estabelecimento (impressão sempre, apenas em determinados casos, etc.). 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  11. Campos numeroTransacao e finalizacao (Estorno)

    • numeroTransacao

      • Tipo: string
      • Obrigatório em: Estorno. 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      • Descrição: Número único da transação fornecido pela adquirente na venda original.
      • Serve para identificar exatamente qual pagamento será estornado.

    • finalizacao

      • Tipo: string
      • Obrigatório em: Estorno. 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      • Descrição: Valor de finalização obtido na resposta ao realizar o pagamento.
      • Representa o “código interno” de conclusão da transação, usado depois para estorno. 
        Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

    Pontos de atenção

    • Guarde numeroTransacao e finalizacao na base de dados no momento do pagamento para poder utilizá-los corretamente em um eventual estorno. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  12. Exemplo de chamada de Pagamento (tipoOperacao = 0)

    • URL: 

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

      • POST http://localhost:3000/api/v1/operacao?tipoOperacao=0

    • Body Request (JSON): 

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

      {
    "identificacao": "abc123",
    "valorTotal": "100"
  }

    Nesse exemplo: 

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

    • identificacao = "abc123" (ID da transação no seu sistema).
    • valorTotal = "100" (R$ 100,00).

    Ponto de atenção

    • Note que o corpo mínimo para um pagamento exige apenas identificacao e valorTotal. Campos adicionais (parcelas, impressões) podem ser acrescentados conforme necessidade. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  13. Exemplo de sucesso ao criar operação

    • Exemplo de resposta de sucesso da API ao criar uma operação: 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      {
    "textoEspecialOperador": "Aguarde...",
    "identificacao": "abc123",
    "executada": false
  }
    • Campos retornados: 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

      • textoEspecialOperador: mensagem para o operador, neste caso "Aguarde...".
      • identificacao: repete o ID enviado, confirmando qual operação foi registrada.
      • executada: false indica que a operação ainda não foi concluída.

    Ponto importante

    • Quando executada = false, o próximo passo é consultar a operação (via endpoint de consulta) até que executada se torne true e os demais dados estejam disponíveis. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  14. Exemplo de falha ao criar operação

    • Exemplo de resposta de falha: 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      {
    "textoEspecialOperador": "OPERAÇÃO CANCELADA",
    "identificacao": "abc123",
    "statusTransacao": "1",
    "executada": true
  }
    • Interpretação: 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

      • textoEspecialOperador: "OPERAÇÃO CANCELADA" – indica o motivo ou resumo da falha.
      • identificacao: ID da transação no seu sistema.
      • statusTransacao: "1" – código de status da transação (não aprovada).
      • executada: true – embora tenha falhado/cancelado, a operação já foi concluída.

    Pontos de atenção

    • Quando executada = true, a operação não está mais em andamento.
    • Use statusTransacao e textoEspecialOperador para entender o motivo e decidir o próximo passo (repetir pagamento, registrar falha, etc.). 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

  15. Relação com o fluxo “Consultar operação”

    • Depois de Criar operação, seu sistema deve: 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

      • Guardar o identificacao da operação.
      • Realizar consultas periódicas à operação usando o endpoint de Consultar operação.
      • Verificar o campo executada até que se torne true.
      • Quando concluída, ler todos os demais campos (status, valores, códigos de autorização) para atualizar a venda ou estorno.

    Ponto importante

    • A documentação reforça que Criar operação não substitui a consulta; os dois endpoints fazem parte de um mesmo fluxo de integração. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
      .

Informações Importantes

  • Função de “Criar operação”: iniciar operações TEF (pagamento, estorno, impressão) no POS via API Local Smart POS, utilizando o endpoint POST /api/v1/operacao com tipoOperacao na Query. 
    Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  • Campos críticos:
    • tipoOperacao: define se a operação é pagamento (0), estorno (1) ou impressão (2). 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • identificacao: ID único da transação no seu sistema, fundamental para rastreabilidade. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • valorTotal: valor da venda ou estorno, em decimal. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • numeroTransacao e finalizacao: essenciais para estorno, pois identificam a transação original junto à adquirente. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • executada: campo de retorno que indica se a operação já foi concluída (true) ou ainda está em andamento (false). 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  • Tipos de transação (tipoTransacao):
    • Códigos de 10 a 60, cobrindo Crédito à vista, Crédito parcelado (estabelecimento/cliente), Débito, PIX/Carteira Digital, Voucher/PAT. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
  • Boas práticas:
    • Sempre armazenar identificacao, valorTotal, statusTransacao, numeroTransacao e finalizacao para conciliação futura.
    • Tratar executada = false como “em andamento” e usar o endpoint de consulta para acompanhar até a conclusão. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade
    • Validar e registrar mensagens em textoEspecialOperador para auxiliar suporte e operadores.
  • Benefícios de seguir corretamente o procedimento:
    • Integração local com Smart POS estável, previsível e rastreável.
    • Redução de erros de comunicação entre sistema Desktop e POS.
    • Maior controle sobre o fluxo de pagamento e estorno, com base na documentação oficial do ConnectTEF. 
      Criar operação | Conecte seu sistema a múltiplas adquirentes com facilidade

Este texto está pronto para ser copiado em um documento Word da sua base de conhecimento. Aplique o padrão visual definido: título com fonte 34, demais cabeçalhos (Resumo, Vídeo, Detalhamento, Informações Importantes) com fonte 18, e o corpo do texto em fonte menor, mantendo os pontos essenciais em negrito para facilitar a leitura por usuários iniciantes.

Você achou esse artigo útil?

Artigos relacionados