Integração de Pagamentos para Storefront 1.0 e 2.0

A principal diferença técnica entre o SF 1.0 e o SF 2.0 é a estrutura do HTML. No SF 1.0, os elementos da página de checkout são, em grande parte, fixos e previsíveis. No SF 2.0, a estrutura é dinâmica e pode variar, o que significa que os scripts dos conectores não devem depender de seletores de elementos HTML (IDs ou classes) que não foram inseridos por eles mesmos.

## Integração Autocontida via /payment-details

Para garantir a compatibilidade, a integração do conector deve ser autocontida. Isso é alcançado através da resposta da requisição POST /payment-details, que é executada sempre que um cliente seleciona um método de pagamento no checkout.
Nesta chamada, o conector deve retornar um objeto JSON contendo o HTML dos campos de pagamento e as URLs dos scripts necessários para o seu funcionamento.

Modelo da Resposta da API /payment-details

A resposta da sua API deve seguir a estrutura abaixo. O html será injetado na tela de checkout, e os scriptUrls serão carregados em seguida.

Modelo da Resposta da API /payment-details

{
    "html": "<div id=\"meu-conector-container\">...</div>",
    "scriptUrls": ["https://seu-dominio.com/seu-script.js"],
    "cartoesSugeridos": [
        {
            "chave": "1234567",
            "nome": "JOAO SILVA",
            "numero": "411111XXXXXX1111",
            "bandeira": "visa"
        }
    ],
    "parcelamento": [{
        "parcelas": 6,
        "valor": 20.0,
        "ajuste": 0.0
    }]
}

Recomendação: Utilize seletores (IDs ou atributos data-) dentro do seu próprio html para manipulação via JavaScript. Por exemplo, use um container principal como <div id="meu-conector-container"> para garantir que seus scripts operem apenas dentro deste escopo.

Implementando o Script de Pagamento com Fbits.Gateway

Uma vez que o html é renderizado e os scriptUrls são carregados, o script do conector deve se registrar no nosso orquestrador de pagamentos, o Fbits.Gateway.

Estrutura do Fbits.Gateway

O objeto global Fbits.Gateway possui a seguinte estrutura principal para registro de pagamentos:

Fbits.Gateway = {
    Pagamento: {
        Adicionar: (id, callbackDeValidacao, callbackDePagamento, callbackDeCarregado) => {
            // Lógica interna 
        }
    },
    // ... outros métodos
};

Registrando seu Conector

Seu script deve chamar o método Fbits.Gateway.Pagamento.Adicionar para registrar os callbacks de validação, pagamento e carregamento.
O ID do pagamento pode ser obtido a partir da URL do script, que a plataforma anexa automaticamente.

Exemplo de registro:

// Obtém o ID do pagamento a partir dos parâmetros da URL do script
const idPagamento = Fbits.Gateway.Utils.GetParameterByName('pagamento', document.currentScript.src);

// Registra os callbacks para o ID de pagamento específico
Fbits.Gateway.Pagamento.Adicionar(
    idPagamento,
    callbackDeValidacao, // Função que valida os dados
    callbackDePagamento,  // Função que processa o pagamento
    callbackDeCarregado   // Função executada após os scripts de pagamento carregarem
);

async function callbackDeValidacao() {
    // Sua lógica de validação aqui
    // Ex: verificar se os campos do cartão estão preenchidos e tokenizar os dados do cartão
    console.log('Executando validação para o pagamento ' + idPagamento);
    const numeroCartao = document.querySelector('#meu-conector-container input[name="cardNumber"]').value;
    if (!numeroCartao) {
        alert('Por favor, preencha o número do cartão.');
        return false; // Retorna false se a validação falhar
    }
    return true; // Retorna true se a validação for bem-sucedida
}

async function callbackDePagamento() {
    // Sua lógica para preparar os dados finais do pagamento.
    console.log('Executando o pagamento para ' + idPagamento);
    // Este callback não precisa retornar um valor, mas pode executar operações assíncronas.
}

function callbackDeCarregado() {
    // Sua lógica a ser executada logo após os scripts de pagamento serem carregados
    console.log('Script do pagamento ' + idPagamento + ' carregado e pronto.');
    const inputCartao = document.querySelector('#meu-conector-container input[name="cardNumber"]');
}

O Ciclo de Vida dos Callbacks

É fundamental entender quando cada callback é executado para garantir o fluxo correto do checkout.

1. Callback de Carregado

• Quando é executado? Uma única vez, logo após o seu script e todos os outros scripts de pagamento terem sido carregados na página.
• Propósito: Ideal para inicializações, como adicionar máscaras a campos de input, anexar event listeners a botões ou campos dentro do seu HTML injetado.
• Retorno: Não possui retorno.

Exemplo de uso:

function meuCallbackLoaded() {
    // Garante que seu HTML está na página antes de tentar manipulá-lo
    const container = document.getElementById('meu-conector-container');
    if (container) {
        const inputCpf = container.querySelector('.cpf-input');
        // Aplica uma máscara de CPF
    }
}

Fbits.Gateway.Pagamento.Adicionar(idPagamento, null, null, meuCallbackLoaded);

2. Callback de Validação

• Quando é executado? Quando o cliente clica no botão "Finalizar Compra". Este callback é o primeiro passo no processo de fechamento.
• Propósito: Validar todos os dados inseridos pelo usuário no seu formulário de pagamento. Isso inclui verificar se campos obrigatórios estão preenchidos, se os dados do cartão são válidos, gerar um token de pagamento (ex: com a API do seu gateway) e armazená-lo em um campo hidden que será enviado para a API de finalização de compra da Wake.
• Retorno: Deve retornar um boolean.
• true: A validação passou. O fluxo de checkout prossegue para o callback Pay.
• false: A validação falhou. O fluxo é interrompido, e o cliente permanece na página de checkout para corrigir os dados.

Exemplo de uso:

async function meuCallbackValidate() {
    const container = document.getElementById('meu-conector-container');
    const nomeTitular = container.querySelector('input[name="cardHolderName"]').value;

    if (!nomeTitular || nomeTitular.trim().length < 3) {
        // Você pode exibir uma mensagem de erro para o usuário aqui
        console.error('Nome do titular é inválido.');
        return false;
    }

    // Exemplo de como gerar um token e armazená-lo (a lógica real depende do seu gateway)
    try {
        // const token = await seuGateway.gerarToken(...);
        // const tokenInput = container.querySelector('input[name="paymentToken"]');
        // tokenInput.value = token;
    } catch (error) {
        console.error('Erro ao gerar token:', error);
        return false; // Falha a validação se o token não puder ser gerado
    }

    return true;
}

Fbits.Gateway.Pagamento.Adicionar(idPagamento, meuCallbackValidate, null, null);

3. Callback de Pagamento

• Quando é executado? Imediatamente após o callback de validação retornar true para todos os pagamentos selecionados.
• Propósito: Executar a lógica final de preparação do pagamento antes do fechamento do pedido.
• Retorno: Não possui retorno (void).

Exemplo de uso:

async function meuCallbackPay() {
    // Neste ponto, a validação já foi concluída com sucesso no callback de validação.
    // Este callback pode ser usado para qualquer lógica final de preparação
    // antes que os dados do formulário sejam coletados e finalize a compra.
    // Ex.: remover os dados sensíveis do cartão
    console.log("Callback de pagamento executado. Preparando para finalizar.");
}

Fbits.Gateway.Pagamento.Adicionar(idPagamento, meuCallbackValidate, meuCallbackPay, meuCallbackLoaded);

Resumo do Fluxo de Execução no Checkout

1. Cliente seleciona o método de pagamento.
2. A Wake faz uma requisição POST /payment-details ao seu conector.
3. Seu conector responde com { "html": "...", "scriptUrls": ["..."] }.
4. A Wake insere o html no DOM e carrega os scripts de scriptUrls.
5. Seu script é executado e chama Fbits.Gateway.Pagamento.Adicionar(...) para registrar os callbacks de carregado, validação e pagamento.
6. A Wake executa o callback de carregado.
7. O cliente preenche os dados e clica em "Finalizar Compra".
8. A Wake executa o callback de validação do seu conector.

• Se false, o processo para.
• Se true, o processo continua.

9. A Wake executa o callback de pagamento do seu conector.
10. A Wake coleta os dados dos formulários de pagamento e finaliza a compra.