> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DataFast

> Atribua receita a canais de marketing com a análise do DataFast. Acompanhe quais fontes de tráfego geram clientes pagantes e otimize seu crescimento.

## 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.

<Info>
  Esta integração exige sua chave de API do DataFast, que você pode obter no seu [painel do DataFast](https://datafa.st/).
</Info>

## 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

<Steps>
  <Step title="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](https://datafa.st/docs) para obter instruções de instalação específicas da sua plataforma.
  </Step>

  <Step title="Get Your API Key">
    Faça login no seu [painel do DataFast](https://datafa.st/) e navegue até as configurações do seu site para obter sua chave de API.

    <Warning>
      Mantenha sua chave de API segura e nunca a exponha em código do lado do cliente.
    </Warning>
  </Step>

  <Step title="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.
  </Step>

  <Step title="Send Payment Data via Webhook">
    Configure um webhook para enviar dados de pagamento à API de Pagamentos do DataFast quando os pagamentos forem bem-sucedidos.
  </Step>

  <Step title="Done!">
    🎉 Os dados de receita agora aparecerão no seu painel do DataFast com atribuição completa aos canais de marketing.
  </Step>
</Steps>

## 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.

<CodeGroup>
  ```typescript Next.js theme={null}
  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_cart: [{ product_id: productId, quantity: 1 }],
      // ... other payment configuration
      metadata: {
        datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
      },
    });

    return payment;
  }
  ```

  ```javascript Express.js theme={null}
  const express = require('express');
  const router = express.Router();

  router.post('/create-checkout', async (req, res) => {
    // Capture DataFast visitor ID from cookie
    const datafastVisitorId = req.cookies?.datafast_visitor_id;

    const payment = await dodopayments.payments.create({
      product_cart: [{ product_id: req.body.productId, quantity: 1 }],
      // ... other payment configuration
      metadata: {
        datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
      },
    });

    res.json({ payment });
  });
  ```

  ```javascript Other Frameworks theme={null}
  // Capture DataFast visitor ID from cookie
  const datafastVisitorId = getCookie('datafast_visitor_id'); // Use your framework's cookie method

  const payment = await dodopayments.payments.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });
  ```
</CodeGroup>

### 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.

<Steps>
  <Step title="Open the Webhook Section">
    No seu painel do Dodo Payments, navegue até <b>Webhooks → + Adicionar Endpoint</b> e expanda o menu suspenso de integrações.

    <Frame>
      <img src="https://mintcdn.com/dodopayments/VOF9xBBvs1EjN4xq/images/integrations/datafast/add.png?fit=max&auto=format&n=VOF9xBBvs1EjN4xq&q=85&s=3aec6c9e450d0616573a4a7dfe89f78e" alt="Adicionar Endpoint e menu suspenso de integrações" style={{ maxHeight: '500px', width: 'auto' }} width="1720" height="1192" data-path="images/integrations/datafast/add.png" />
    </Frame>
  </Step>

  <Step title="Select DataFast">
    Escolha o cartão de integração <b>DataFast</b>.
  </Step>

  <Step title="Enter API Key">
    Forneça sua chave API DataFast no campo de configuração.

    <Frame>
      <img src="https://mintcdn.com/dodopayments/VOF9xBBvs1EjN4xq/images/integrations/datafast/api-key.png?fit=max&auto=format&n=VOF9xBBvs1EjN4xq&q=85&s=25129c8ca64e38ef44a6960c2f3a2993" alt="Adicionar chave API" style={{ maxHeight: '500px', width: 'auto' }} width="1740" height="882" data-path="images/integrations/datafast/api-key.png" />
    </Frame>
  </Step>

  <Step title="Configure Transformation">
    Edite o código de transformação para formatar os dados de pagamento para a API de Pagamentos do DataFast.
  </Step>

  <Step title="Test & Create">
    Teste com cargas úteis de exemplo e clique em <b>Create</b> para ativar a integração.
  </Step>
</Steps>

## Exemplos de Código de Transformação

### Atribuição Básica de Pagamento

```javascript basic_payment.js icon="js" expandable theme={null}
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:

```javascript zero_decimal.js icon="js" expandable theme={null}
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:

```javascript subscription_payment.js icon="js" expandable theme={null}
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

<Tip>
  **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.
</Tip>

* **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

<AccordionGroup>
  <Accordion title="Payments not appearing in DataFast">
    * 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
  </Accordion>

  <Accordion title="Revenue attribution not working">
    * 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](https://datafa.st/docs/payments-api) do DataFast para obter orientações adicionais
  </Accordion>

  <Accordion title="Transformation errors">
    * 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
  </Accordion>

  <Accordion title="Currency conversion issues">
    * 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")
  </Accordion>
</AccordionGroup>

## Recursos Adicionais

<CardGroup cols={2}>
  <Card title="DataFast Documentation" icon="book" href="https://datafa.st/docs/payments-api">
    Saiba mais sobre a API de Pagamentos do DataFast e os recursos de atribuição de receita.
  </Card>

  <Card title="DataFast Dashboard" icon="chart-bar" href="https://datafa.st/">
    Acesse seu painel do DataFast para visualizar análises de receita e dados de atribuição.
  </Card>
</CardGroup>

<Info>
  Precisa de ajuda? Entre em contato com o suporte do Dodo Payments em [support@dodopayments.com](mailto:support@dodopayments.com) para obter assistência com a integração.
</Info>