Pular para o conteúdo principal

​
Introdução

O DataFast é uma ferramenta de análise focada em receita que ajuda você a descobrir quais canais de marketing geram clientes pagantes. Ao integrar o Dodo Payments com o DataFast, você pode atribuir receita às suas fontes de tráfego, identificar segmentos de clientes de alto valor e tomar decisões baseadas em dados para crescer seu negócio.
Esta integração exige sua chave de API do DataFast, que você pode obter no seu painel do DataFast.

​
Como Funciona

O DataFast rastreia visitantes através de um ID de visitante único armazenado em um cookie. Para atribuir receita a canais de marketing, você precisa:
  1. Capture o ID do visitante do DataFast do cookie datafast_visitor_id ao criar sessões de checkout
  2. Armazene o ID do visitante nos metadados do pagamento
  3. Envie os dados do pagamento ao DataFast quando os pagamentos forem bem-sucedidos usando a API de Pagamentos deles
Isso permite que o DataFast associe pagamentos bem-sucedidos à fonte de tráfego original, fornecendo a você uma atribuição de receita completa.

​
Começando

1

Install DataFast Script

Primeiro, instale o script de rastreamento do DataFast no seu site. Isso cria o cookie datafast_visitor_id que rastreia os visitantes.Consulte a documentação do DataFast para obter instruções de instalação específicas da sua plataforma.
2

Get Your API Key

Faça login no seu painel do DataFast e navegue até as configurações do seu site para obter sua chave de API.
Mantenha sua chave de API segura e nunca a exponha em código do lado do cliente.
3

Capture Visitor ID in Checkout

Ao criar uma sessão de checkout, capture o ID do visitante do DataFast do cookie e adicione-o aos metadados do pagamento.
4

Send Payment Data via Webhook

Configure um webhook para enviar dados de pagamento à API de Pagamentos do DataFast quando os pagamentos forem bem-sucedidos.
5

Done!

🎉 Os dados de receita agora aparecerão no seu painel do DataFast com atribuição completa aos canais de marketing.

​
Guia de Implementação

​
Passo 1: Adicionar ID do Visitante aos Metadados do Checkout

Ao criar uma sessão de checkout, capture o ID do visitante do DataFast do cookie e inclua-o em seus metadados de pagamento. 
import { cookies } from 'next/headers';
import { dodopayments } from '@/lib/dodopayments';

export async function createCheckout(productId: string) {
  // Capture DataFast visitor ID from cookie
  const datafastVisitorId = cookies().get('datafast_visitor_id')?.value;

  const payment = await dodopayments.payments.create({
    product_id: productId,
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });

  return payment;
}

​
Passo 2: Enviar Dados de Pagamento para o DataFast

Configure um endpoint de webhook para enviar dados de pagamento para a API de Pagamento do DataFast quando os pagamentos forem bem-sucedidos.
1

Open the Webhook Section

No painel do Dodo Payments, vá para Webhooks → + Add Endpoint e expanda o menu suspenso de integrações.
Add Endpoint and integrations dropdown
2

Select DataFast

Escolha o cartão de integração DataFast.
3

Enter API Key

Informe sua chave de API do DataFast no campo de configuração.
Add API Key
4

Configure Transformation

Edite o código de transformação para formatar os dados de pagamento para a API de Pagamentos do DataFast.
5

Test & Create

Teste com cargas úteis de exemplo e clique em Create para ativar a integração.

​
Exemplos de Código de Transformação

​
Atribuição Básica de Pagamento

basic_payment.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Only send to DataFast if visitor ID exists in metadata
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100, // Convert from cents to dollars
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
Lidar com Moedas sem Casas Decimais

Algumas moedas (como JPY) não usam casas decimais. Ajuste o cálculo do valor conforme necessário:
zero_decimal.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      // Zero decimal currencies: JPY, KRW, CLP, etc.
      const zeroDecimalCurrencies = ['JPY', 'KRW', 'CLP', 'VND', 'UGX', 'MGA'];
      const isZeroDecimal = zeroDecimalCurrencies.includes(payment.currency);
      
      webhook.payload = {
        amount: isZeroDecimal 
          ? payment.total_amount // Use amount as-is for zero decimal currencies
          : payment.total_amount / 100, // Convert from cents for other currencies
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
Pagamentos de Assinatura

Para pagamentos de assinatura recorrentes, você pode rastrear cada pagamento:
subscription_payment.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Check if this is a subscription payment
    const isSubscription = payment.subscription_id !== null;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100,
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
        // Optional: Add subscription context
        ...(isSubscription && {
          subscription_id: payment.subscription_id,
        }),
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
Melhores Práticas

Capture o ID do visitante cedo: Armazene o ID do visitante do DataFast o mais rápido possível no fluxo do checkout para garantir atribuição precisa, mesmo que o usuário saia e retorne depois.
  • Sempre inclua o ID do visitante nos metadados: Sem o ID do visitante, o DataFast não pode atribuir receita aos canais de marketing
  • Lide com moedas sem casas decimais: Algumas moedas (JPY, KRW, etc.) não usam casas decimais—ajuste seu cálculo de valor conforme necessário
  • Teste com pagamentos de exemplo: Verifique se a integração funciona corretamente antes de entrar em produção
  • Monitore seu painel do DataFast: Verifique se os pagamentos estão aparecendo corretamente com a atribuição adequada
  • Use tentativas de webhook: A API de Pagamento do DataFast é idempotente, então as tentativas são seguras se um webhook falhar

​
Solução de Problemas

  • Verifique se sua chave de API do DataFast está correta e ativa
  • Confirme se o datafast_visitor_id está sendo capturado e armazenado nos metadados do pagamento
  • Garanta que a transformação do webhook esteja formatando corretamente a carga útil
  • Verifique se o webhook está sendo acionado nos eventos payment.succeeded
  • Confira o painel do DataFast para mensagens de erro ou logs da API
  • Confirme se o script de rastreamento do DataFast está instalado e funcionando no seu site
  • Verifique se o cookie datafast_visitor_id está sendo definido corretamente
  • Confira se os IDs dos visitantes batem entre a criação do checkout e a conclusão do pagamento
  • Certifique-se de capturar o ID do visitante antes de criar a sessão de checkout
  • Revise a documentação da API de Pagamentos do DataFast para obter orientações adicionais
  • Valide se a estrutura JSON corresponde ao formato da API de Pagamentos do DataFast
  • Verifique se todos os campos obrigatórios (amount, currency, transaction_id, datafast_visitor_id) estão presentes
  • Certifique-se de que o valor está sendo convertido corretamente (divida por 100 na maioria das moedas, exceto moedas com zero casas decimais)
  • Verifique se a URL do endpoint da API está correta: https://datafa.st/api/v1/payments
  • Teste a transformação com cargas úteis de webhook de exemplo
  • Para moedas com zero casas decimais (JPY, KRW, CLP, VND, UGX, MGA), envie o valor conforme recebido, sem dividir por 100
  • Para todas as outras moedas, divida o valor por 100 para converter de centavos para a unidade base
  • Confira se o código da moeda corresponde ao formato ISO 4217 (por exemplo, “USD”, “EUR”, “JPY”)

​
Recursos Adicionais

DataFast Documentation

Saiba mais sobre a API de Pagamentos do DataFast e os recursos de atribuição de receita.

DataFast Dashboard

Acesse seu painel do DataFast para visualizar análises de receita e dados de atribuição.
Precisa de ajuda? Entre em contato com o suporte do Dodo Payments em support@dodopayments.com para obter assistência com a integração.