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

> Attribuisci il fatturato ai canali di marketing con l'analisi di DataFast. Monitora quali fonti di traffico generano clienti paganti e ottimizza la tua crescita.

## Introduzione

DataFast è uno strumento di analisi focalizzato sul fatturato che ti aiuta a scoprire quali canali di marketing generano clienti paganti. Integrando Dodo Payments con DataFast, puoi attribuire il fatturato alle tue fonti di traffico, identificare segmenti di clienti ad alto valore e prendere decisioni basate sui dati per far crescere la tua attività.

<Info>
  Questa integrazione richiede la tua chiave API di DataFast, che puoi ottenere dal tuo [DataFast dashboard](https://datafa.st/).
</Info>

## Come Funziona

DataFast traccia i visitatori attraverso un ID visitatore unico memorizzato in un cookie. Per attribuire il fatturato ai canali di marketing, devi:

1. **Cattura l’ID visitatore di DataFast** dal cookie `datafast_visitor_id` quando crei sessioni di checkout
2. **Memorizza l’ID visitatore** nei metadati del pagamento
3. **Invia i dati di pagamento a DataFast** quando i pagamenti vanno a buon fine utilizzando la loro Payment API

Questo consente a DataFast di abbinare i pagamenti riusciti con la fonte di traffico originale, fornendoti un'attribuzione completa del fatturato.

## Iniziare

<Steps>
  <Step title="Install DataFast Script">
    Per prima cosa, installa lo script di tracciamento di DataFast sul tuo sito. Questo crea il cookie `datafast_visitor_id` che traccia i tuoi visitatori.

    Visita la [documentazione di DataFast](https://datafa.st/docs) per le istruzioni di installazione specifiche per la tua piattaforma.
  </Step>

  <Step title="Get Your API Key">
    Accedi al tuo [DataFast dashboard](https://datafa.st/) e vai alle impostazioni del sito per ottenere la tua chiave API.

    <Warning>
      Tieni la tua chiave API al sicuro e non esporla mai nel codice lato client.
    </Warning>
  </Step>

  <Step title="Capture Visitor ID in Checkout">
    Quando crei una sessione di checkout, cattura l’ID visitatore di DataFast dal cookie e aggiungilo ai metadati del pagamento.
  </Step>

  <Step title="Send Payment Data via Webhook">
    Configura un webhook per inviare i dati di pagamento alla Payment API di DataFast quando i pagamenti vanno a buon fine.
  </Step>

  <Step title="Done!">
    🎉 I dati di fatturato appariranno ora nel tuo dashboard di DataFast con piena attribuzione ai canali di marketing.
  </Step>
</Steps>

## Guida all'Implementazione

### Passo 1: Aggiungi l'ID Visitatore ai Metadati del Checkout

Quando crei una sessione di checkout, cattura l'ID visitatore di DataFast dal cookie e includilo nei tuoi metadati di 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: Invia Dati di Pagamento a DataFast

Configura un endpoint webhook per inviare i dati di pagamento all'API di pagamento di DataFast quando i pagamenti hanno successo.

<Steps>
  <Step title="Open the Webhook Section">
    Nel tuo dashboard Dodo Payments, vai a <b>Webhooks → + Aggiungi Endpoint</b> ed espandi il menu a tendina delle integrazioni.

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

  <Step title="Select DataFast">
    Scegli la scheda di integrazione <b>DataFast</b>.
  </Step>

  <Step title="Enter API Key">
    Fornisci la tua chiave API DataFast nel campo di configurazione.

    <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="Add API Key" style={{ maxHeight: '500px', width: 'auto' }} width="1740" height="882" data-path="images/integrations/datafast/api-key.png" />
    </Frame>
  </Step>

  <Step title="Configure Transformation">
    Modifica il codice di trasformazione per formattare i dati di pagamento per la Payment API di DataFast.
  </Step>

  <Step title="Test & Create">
    Testa con payload di esempio e clicca su <b>Crea</b> per attivare l’integrazione.
  </Step>
</Steps>

## Esempi di Codice di Trasformazione

### Attribuzione di Pagamento di Base

```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;
}
```

### Gestisci Valute Senza Decimali

Alcune valute (come JPY) non utilizzano i decimali. Regola di conseguenza il calcolo dell'importo:

```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;
}
```

### Pagamenti in Abbonamento

Per i pagamenti ricorrenti in abbonamento, puoi tracciare ogni 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;
}
```

## Migliori Pratiche

<Tip>
  **Cattura l’ID visitatore il prima possibile**: conserva l’ID visitatore di DataFast appena possibile nel tuo flusso di checkout per garantire un’attribuzione accurata, anche se l’utente lascia la pagina e torna più tardi.
</Tip>

* **Includi sempre l'ID visitatore nei metadati**: Senza l'ID visitatore, DataFast non può attribuire il fatturato ai canali di marketing
* **Gestisci le valute senza decimali**: Alcune valute (JPY, KRW, ecc.) non utilizzano i decimali: regola di conseguenza il calcolo dell'importo
* **Testa con pagamenti di esempio**: Verifica che l'integrazione funzioni correttamente prima di andare in produzione
* **Monitora il tuo dashboard di DataFast**: Controlla che i pagamenti appaiano correttamente con l'attribuzione adeguata
* **Utilizza i retry dei webhook**: L'API di pagamento di DataFast è idempotente, quindi i retry sono sicuri se un webhook fallisce

## Risoluzione dei Problemi

<AccordionGroup>
  <Accordion title="Payments not appearing in DataFast">
    * Verifica che la tua chiave API di DataFast sia corretta e attiva
    * Controlla che `datafast_visitor_id` venga catturato e memorizzato nei metadati del pagamento
    * Assicurati che la trasformazione del webhook stia formattando correttamente il payload
    * Verifica che il webhook si attivi sugli eventi `payment.succeeded`
    * Controlla il dashboard di DataFast per eventuali messaggi di errore o log delle API
  </Accordion>

  <Accordion title="Revenue attribution not working">
    * Conferma che lo script di tracciamento di DataFast sia installato e funzionante sul tuo sito
    * Verifica che il cookie `datafast_visitor_id` venga impostato correttamente
    * Controlla che gli ID visitatore corrispondano tra la creazione del checkout e il completamento del pagamento
    * Assicurati di catturare l’ID visitatore prima di creare la sessione di checkout
    * Consulta la [documentazione della Payment API di DataFast](https://datafa.st/docs/payments-api) per ulteriori indicazioni
  </Accordion>

  <Accordion title="Transformation errors">
    * Verifica che la struttura JSON corrisponda al formato della Payment API di DataFast
    * Controlla che tutti i campi obbligatori (`amount`, `currency`, `transaction_id`, `datafast_visitor_id`) siano presenti
    * Assicurati che l’importo sia correttamente convertito (dividi per 100 per la maggior parte delle valute, tranne quelle a zero decimali)
    * Verifica che l’URL dell’endpoint API sia corretto: `https://datafa.st/api/v1/payments`
    * Testa la trasformazione con payload di esempio del webhook
  </Accordion>

  <Accordion title="Currency conversion issues">
    * Per le valute a zero decimali (JPY, KRW, CLP, VND, UGX, MGA), invia l’importo così com’è senza dividere per 100
    * Per tutte le altre valute, dividi l’importo per 100 per convertire dai centesimi all’unità di base
    * Ricontrolla che il codice valuta corrisponda al formato ISO 4217 (ad esempio, "USD", "EUR", "JPY")
  </Accordion>
</AccordionGroup>

## Risorse Aggiuntive

<CardGroup cols={2}>
  <Card title="DataFast Documentation" icon="book" href="https://datafa.st/docs/payments-api">
    Scopri di più sulla Payment API di DataFast e sulle funzionalità di attribuzione del fatturato.
  </Card>

  <Card title="DataFast Dashboard" icon="chart-bar" href="https://datafa.st/">
    Accedi al tuo dashboard di DataFast per visualizzare l’analisi dei ricavi e i dati di attribuzione.
  </Card>
</CardGroup>

<Info>
  Hai bisogno di aiuto? Contatta l’assistenza di Dodo Payments all’indirizzo [support@dodopayments.com](mailto:support@dodopayments.com) per assistenza con l’integrazione.
</Info>