CONNECTTEF – ESTORNO VIA API (INTEGRAÇÃO WEB/SAAS).

Resumo do que será ensinado

Este documento explica, passo a passo, como realizar estorno (cancelamento) de transações de pagamento via API ConnectTEF em um POS já vinculado ao seu sistema. Você verá os pré-requisitos, os campos da requisição, o fluxo completo de estorno e como interpretar o retorno enviado via Webhook, seguindo o padrão de integração usado em Pagamento. 

Segue um Vídeo explicativo do processo

Detalhamento do uso correto

Com este guia, você deve ser capaz de configurar seu sistema (PDV/ERP/WEB/SaaS) para solicitar estornos ao POS vinculado, usar corretamente os identificadores da transação original, receber e tratar o retorno do Webhook e registrar o estorno de forma segura e rastreável. 

Segue o detalhamento de como realizar Estorno via API ConnectTEF

1. Pré-requisitos antes de usar o endpoint de Estorno

   • Ter o POS (SmartPOS) vinculado ao PDV/ERP, com:
     • numeroSerie já definido (ex.: caixa001).
     • CPFCNPJ do estabelecimento obtido na vinculação.
     • Webhook configurado e funcional.
   • Ter o certificado digital de cliente X.509 válido configurado (mTLS), pois o estorno usa a mesma infraestrutura segura da API.
   • Ter os dados da transação original de pagamento que será estornada (como numeroTransacao, identificacao ou outro identificador usado na venda).

   Pontos de atenção

   • Estorno só deve ser solicitado para transações que já foram autorizadas.
   • As regras de estorno devem respeitar as políticas da adquirente e da empresa (prazos, valores, motivos).

2. Objetivo do endpoint de Estorno

   • O endpoint de Estorno tem por objetivo reverter uma transação de pagamento já executada no POS. 
     Testando via Postman | Conecte seu sistema a múltiplas adquirentes com facilidade
   • Ao chamar esse endpoint:
     • Seu sistema informa qual transação deve ser estornada.
     • A API ConnectTEF envia o pedido de estorno ao POS e à adquirente.
     • Após processamento, o resultado do estorno é encaminhado ao seu Webhook, assim como ocorre em Pagamento. 
       Testando via Postman | Conecte seu sistema a múltiplas adquirentes com facilidade

   Ponto importante

   • Estorno segue o mesmo modelo assíncrono de Pagamento: a resposta final não vem na chamada inicial, e sim via Webhook. 
     Testando via Postman | Conecte seu sistema a múltiplas adquirentes com facilidade

3. Fluxo geral do Estorno (visão passo a passo)

   1. Seu sistema chama o endpoint de Estorno informando os dados da transação original.
   2. A API ConnectTEF:
      • Valida o certificado mTLS.
      • Confere numeroSerie e CPFCNPJ.
      • Encaminha o pedido para o POS e a adquirente responsável pela transação.
   3. O POS/adquirente:
      • Processa o estorno conforme regras da adquirente (prazo, autorização, valor).
   4. Ao finalizar:
      • O ConnectTEF envia um callback HTTP ao seu Webhook com o resultado do estorno (aprovado ou rejeitado), contendo campos semelhantes aos de pagamento. 
        Testando via Postman | Conecte seu sistema a múltiplas adquirentes com facilidade

   Pontos de atenção

   • Seu sistema deve vincular o estorno à transação original (por exemplo, usando numeroTransacao da venda) para manter rastreabilidade financeira.

4. Configuração básica da requisição de Estorno

   • Método HTTP: normalmente POST (padrão similar ao Pagamento).
   • Endpoint (integração via API – Estorno):
     
     • https://apitef.pdvpos.com.br/api/v1/web-service/estorno (seguindo padrão da API ConnectTEF).
   • Header obrigatório:
     
     • Content-Type: application/json.
   • Query Params obrigatórios:
     
     • numeroSerie: mesmo identificador de automação usado na vinculação/Pagamento.
     • CPFCNPJ: CPF/CNPJ do estabelecimento vinculado.

   Pontos de atenção

   • Use sempre os mesmos numeroSerie e CPFCNPJ da transação original, garantindo que o estorno seja direcionado ao POS correto. 
     Testando via Postman | Conecte seu sistema a múltiplas adquirentes com facilidade

5. Campos do corpo da requisição (Body JSON)

   O corpo segue padrão similar ao de Pagamento, porém focado na transação que será estornada. Estrutura recomendada:

   • identificacao (string, obrigatório):

     • Identificador da operação de estorno no seu sistema.
     • Pode ser o mesmo da venda original ou um novo código interno, desde que você consiga relacioná-los.

   • identificacaoTransacaoOriginal ou numeroTransacao (string, obrigatório):

     • Código único da transação original, recebido no Webhook de pagamento (por exemplo, numeroTransacao).
     • Essencial para localizar e estornar a venda correta.

   • valorTotal (number, obrigatório ou opcional conforme regra):

     • Valor total a ser estornado.
     • Em muitos cenários, deve ser igual ao valor da transação original.

   • callbackUrl (string, obrigatório):

     • URL do seu Webhook para receber o resultado do estorno.

   • callbackToken (string, opcional):

     • Token que será enviado no header token do Webhook para autenticação da chamada.

   • Demais campos podem espelhar informações da transação original, conforme modelo da documentação (como dados de comanda, se necessários). 

     Testando via Postman | Conecte seu sistema a múltiplas adquirentes com facilidade

   Pontos de atenção

   • É fundamental salvar, na venda original, o numeroTransacao e outros dados da adquirente, para usar como referência na requisição de estorno.

6. Exemplo de chamada de Estorno

   • URL (exemplo):
     POST https://apitef.pdvpos.com.br/api/v1/web-service/estorno?numeroSerie=caixa001&CPFCNPJ=42580012000182

   • Body JSON (exemplo):

   [
     {
       "identificacao": "estorno-abc123",
       "identificacaoTransacaoOriginal": "abc123",
       "valorTotal": 29.90,
       "callbackUrl": "https://webhook.com.br/response",
       "callbackToken": "abc1234"
     }
   ]

Pontos de atenção

• Note que o corpo também é um array de objetos, permitindo estornar mais de uma transação em lote, se o modelo de negócio exigir. 
  Testando via Postman | Conecte seu sistema a múltiplas adquirentes com facilidade

1. Resposta imediata da API (síncrona)

   • Assim como em Pagamento, a API devolve uma resposta imediata indicando que o pedido de estorno foi encaminhado:

   {
     "status": "estorno_enviado",
     "mensagem": "Pedido de estorno enviado ao POS",
     "referencia": "estorno-abc123"
   }

• Campos principais:

  • status: ex.: "estorno_enviado".
  • mensagem: texto informativo.
  • referencia: valor de identificacao, para correlação interna.

  Pontos de atenção

• Essa resposta não confirma se o estorno foi efetivamente realizado; apenas que o pedido foi enviado ao POS/adquirente.

1. Retorno via Webhook após processamento do Estorno

   • Quando o estorno é processado, o ConnectTEF envia um POST ao seu Webhook com um JSON contendo informações similares às de pagamento, incluindo:

   • executada: true se o pedido de estorno foi processado no POS/adquirente.

   • statusTransacao:

     • "0" = estorno aprovado.
     • Outros códigos = estorno não aprovado (erro ou regra da adquirente).

   • textoEspecialOperador: mensagem explicando o resultado (ex.: “Estorno autorizado”, “Prazo para estorno excedido”).

   • identificacao: identificador da operação de estorno.

   • identificacaoTransacaoOriginal ou numeroTransacaoOriginal: referência à venda estornada.

   • valorTotal: valor estornado.

   • numeroTransacao: número da operação de estorno na adquirente (pode diferir da transação original).

   • codigoAutorizacaoTransacao: código de autorização do estorno.

   • Demais campos de contexto (timestamp, CNPJ, razão social, etc.), conforme padrão de retorno da API. 

     Testando via Postman | Conecte seu sistema a múltiplas adquirentes com facilidade

   Pontos de atenção

   • Use statusTransacao e textoEspecialOperador para decidir se o estorno foi efetivado.
   • Registre numeroTransacao e codigoAutorizacaoTransacao do estorno para conciliação e auditoria.

2. Tratamento de sucesso e falha no estorno

   • Estorno aprovado (exemplo):

    "executada": true,
    "statusTransacao": "0",
    "textoEspecialOperador": "Estorno autorizado"
   

   • Significa que a adquirente aceitou e processou o estorno.

     • Estorno não autorizado (exemplo):

    "executada": true,
    "statusTransacao": "1002",
    "textoEspecialOperador": "Prazo para estorno excedido"
   

   • O estorno foi processado, mas não foi autorizado, geralmente por regra de prazo ou valor.

   Pontos de atenção

   • Seu sistema deve ajustar o status financeiro da venda apenas quando statusTransacao indicar sucesso.
   • Em caso de falha, pode ser necessário abrir processo interno (suporte, financeiro) ou orientar o operador.

3. Boas práticas de implementação de Estorno

   • Persistência de dados:

     • Relacionar estorno e venda original via identificacaoTransacaoOriginal/numeroTransacao.
     • Armazenar statusTransacao, textoEspecialOperador, valorTotal, numeroTransacao e codigoAutorizacaoTransacao do estorno.

   • Controle de fluxo:

     • Não permitir estorno de vendas que já foram estornadas anteriormente.
     • Definir regras internas (quem pode solicitar estorno, até quando, em que valores).

   • Segurança do Webhook:

     • Validar callbackToken enviado no header token.
     • Proteger o endpoint para aceitar apenas chamadas do ConnectTEF.

   • Logs e auditoria:

     • Registrar requisições de estorno e callbacks recebidos para consulta futura e suporte.

4. Relacionamento entre Pagamento e Estorno

   • Pagamento registra a entrada de receita.
   • Estorno registra a reversão dessa receita.
   • Ambos utilizam:
     • numeroSerie e CPFCNPJ da vinculação.
     • Fluxo assíncrono via Webhook.
     • Certificado mTLS para segurança. 
       Testando via Postman | Conecte seu sistema a múltiplas adquirentes com facilidade

   Pontos de atenção

   • Tenha modelos de dados que vinculem claramente cada estorno à transação original, evitando inconsistências financeiras.

Informações Importantes

• Estorno é complementar ao Pagamento: use apenas para desfazer transações já autorizadas, respeitando regras da adquirente e da empresa.
• Fluxo assíncrono:
  • Solicitação via API.
  • Resultado final via Webhook (como em Pagamento).
• Segurança:
  • Requisições usam mTLS com certificado de cliente.
  • Webhook pode usar callbackToken para validar origem.
• Campos críticos:
  • identificacaoTransacaoOriginal/numeroTransacao: vínculo com a venda original.
  • statusTransacao: "0" = estorno aprovado; demais códigos = falha.
  • textoEspecialOperador: motivo detalhado do resultado.
• Benefícios de seguir corretamente o procedimento:
  • Estornos registrados de forma segura, rastreável e alinhada com a documentação oficial.
  • Menos erros de reversão e maior confiança nos controles financeiros.
• Recomendações gerais:
  • Utilize este guia em treinamentos de equipe técnica e suporte.
  • Sempre implemente Pagamento e Estorno em conjunto, com foco em rastreabilidade.
  • Teste o fluxo em ambiente controlado (ex.: via Postman) antes de liberar para produção. 
    Testando via Postman | 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: 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 importantes em negrito.