Estorno de Pedidos: Total, Parcial e Regras de Negócio

Este artigo detalha como realizar o estorno de valores de um pedido via API e as regras de comportamento do sistema para diferentes cenários de pagamento.

POST https://api.fbits.net/pedidos/estorno/{pedidoId}

1.Cenários Suportados via API

A. Pagamento Único via Gateway

O estorno automatizado via API funciona integralmente para pedidos realizados com apenas uma forma de pagamento externa.

Estorno Total: Valor enviado no JSON = 100% do valor do pedido.
Estorno Parcial: Valor enviado no JSON < valor total do pedido.

📘
Conectores Compatíveis: Wake Gateway, Adyen, Pagar.me 2.0, Pagamento Customizado, Maxipago By Rede, Cielo, Braintree, Pagbank, KOIN, Pagaleve e Paypal BCDC.

B. Pedidos com Saldo de Conta Corrente (Crédito Interno)

O Saldo de Conta Corrente é tratado como um crédito da loja e é compatível com a API pública, mesmo quando combinado com um Gateway. Se a configuração “Devolver saldo de conta corrente em estornos de pedidos” estiver ativa, o sistema segue esta ordem de prioridade:

Prioridade 1: O valor é devolvido primeiro para o saldo de conta corrente do cliente na loja.
Prioridade 2: Caso o valor a ser estornado seja maior que o saldo utilizado, o restante é estornado via Gateway (Cartão/PIX).

Exemplo Prático:

Pedido: R$ 300,00 (R$ 100,00 Saldo Interno + R$ 200,00 Cartão)
Ação: Solicitação de estorno de R$ 250,00 via API.
Resultado: R$ 100,00 retornam para a conta corrente e R$ 150,00 são estornados no cartão.

2.Limitações e Cenários Não Suportados (Manual)

⚠️ Múltiplas Formas de Pagamento Externas

A API Pública não permite o estorno de pedidos que combinem mais de uma forma de pagamento externa via Gateway Wake. Combinações que exigem estorno manual:

Cartão + PIX;
Cartão + Carteira de Crédito;
Dois Cartões de Crédito;

Ação Necessária: Para estes casos, o estorno deve ser realizado diretamente no portal da adquirente ou do gateway. A tentativa via API resultará em erro ou processamento incompleto. Nota Técnica (Clearsale): Atualmente, pedidos que utilizam combos de pagamento (ex: Cartão + PIX) com análise Clearsale podem apresentar limitações no estorno automático. Recomendamos a conferência manual nestes cenários.

3.Estorno Automático em Falhas de Checkout

O sistema possui regras nativas para devolução de valores em transações que não foram concluídas com sucesso (antes do faturamento):

Cenário de Erro	Comportamento do Sistema
Dois Cartões: 1º capturado, 2º recusado	Devolve automaticamente o valor capturado no 1º cartão.
Cartão + PIX: Cartão aprovado, PIX não pago	O valor do cartão é devolvido após a expiração do PIX.
Cartão + Carteira: Falha na retentativa	O valor da Carteira de Crédito é devolvido ao saldo interno.
PIX + Carteira: PIX não pago	O valor da Carteira de Crédito é devolvido ao saldo interno.

4.Estrutura da Requisição

Request Body

{
  "contaCorrente": {
    "referencia": "ID_CONCILIACAO_123"
  },
  "valor": 100.00
}

Parâmetros

valor (Obrigatório): Valor decimal (ex: 100.00). Deve ser igual ou menor que o saldo disponível para estorno no pedido.
contaCorrente.referencia (Opcional): Texto alfanumérico para identificação na conciliação financeira quando há saldo interno envolvido.

Importante: Após ativar configurações de saldo de conta corrente, aguarde até 10 minutos para a atualização do cache antes de processar novos estornos.