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

# Suivre une Vente

> Créer un événement de conversion vente

## Endpoint

```
POST https://track.taap.it/api/events/sale
```

## Authentification

<Tabs>
  <Tab title="Côté serveur (Recommandé)">
    Utilisez votre clé API secrète :

    ```bash theme={null}
    Authorization: Bearer taapit_sk_xxxxxxxxxxxx
    ```
  </Tab>

  <Tab title="Côté client">
    Utilisez votre clé publique :

    ```bash theme={null}
    X-Publishable-Key: taapit_pk_xxxxxxxxxxxx
    ```
  </Tab>
</Tabs>

## Corps de la requête

| Champ                  | Type   | Requis | Description                                   |
| ---------------------- | ------ | ------ | --------------------------------------------- |
| `trackingId`           | string | ✓      | Le `ta_tid` du cookie ou paramètre URL        |
| `customer`             | object | ✓      | Informations client                           |
| `customer.externalId`  | string | ✓      | Votre ID utilisateur/client interne           |
| `customer.email`       | string |        | Adresse email du client                       |
| `customer.firstname`   | string |        | Prénom du client                              |
| `customer.lastname`    | string |        | Nom du client                                 |
| `customer.phoneNumber` | string |        | Numéro de téléphone du client                 |
| `customer.avatarUrl`   | string |        | URL de l'avatar du client                     |
| `amount`               | number | ✓      | Montant en unités de devise (pas en centimes) |
| `currency`             | string | ✓      | Code devise ISO 4217 (ex: `eur`, `usd`)       |
| `metadata`             | object |        | Données personnalisées (paires clé-valeur)    |

<Warning>
  **Format du montant** : Utilisez les unités de devise, pas les centimes.

  * ✅ `29.99` pour 29,99 €
  * ❌ `2999` serait interprété comme 2999 €
</Warning>

## Exemples

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://track.taap.it/api/events/sale \
      -H "Authorization: Bearer taapit_sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "trackingId": "rLnWe1uz9t282v7g",
        "customer": {
          "externalId": "user_123",
          "email": "john@example.com"
        },
        "amount": 99.99,
        "currency": "eur",
        "metadata": {
          "orderId": "order_456",
          "plan": "pro"
        }
      }'
    ```
  </Tab>

  <Tab title="SDK Node.js">
    ```typescript theme={null}
    import { Taapit } from 'taapit-sdk';

    const taapit = new Taapit({
      apiKey: process.env.TAAPIT_API_KEY,
    });

    await taapit.track.sale({
      trackingId: 'rLnWe1uz9t282v7g',
      customer: {
        externalId: 'user_123',
        email: 'john@example.com',
      },
      amount: 99.99,
      currency: 'eur',
      metadata: {
        orderId: 'order_456',
        plan: 'pro',
      },
    });
    ```
  </Tab>

  <Tab title="Hook React">
    ```tsx theme={null}
    import { useTaapitAnalytics } from 'taapit-sdk/react';

    function CheckoutButton({ order }) {
      const { trackSale } = useTaapitAnalytics();

      const handlePurchase = async () => {
        trackSale({
          customer: {
            externalId: order.userId,
            email: order.email,
          },
          amount: order.total,
          currency: 'eur',
          metadata: {
            orderId: order.id,
            plan: order.plan,
          },
        });
      };
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```html theme={null}
    <script src="https://taap.it/api/sdk" data-publishable-key="taapit_pk_xxx"></script>

    <script>
      taapit.trackSale({
        customer: {
          externalId: 'user_123',
          email: 'john@example.com',
        },
        amount: 99.99,
        currency: 'eur',
        metadata: {
          orderId: 'order_456',
        },
      });
    </script>
    ```
  </Tab>
</Tabs>

## Réponse

<Tabs>
  <Tab title="200 OK">
    ```json theme={null}
    {
      "ok": true
    }
    ```
  </Tab>

  <Tab title="400 Bad Request">
    ```json theme={null}
    {
      "error": "Invalid payload",
      "details": [
        {
          "path": ["amount"],
          "message": "Required"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="401 Unauthorized">
    ```json theme={null}
    {
      "error": "Invalid API key"
    }
    ```
  </Tab>

  <Tab title="404 Not Found">
    ```json theme={null}
    {
      "error": "Click not found for this trackingId"
    }
    ```
  </Tab>
</Tabs>

## Codes de devise

Utilisez les codes [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard :

| Devise            | Code  |
| ----------------- | ----- |
| Euro              | `eur` |
| Dollar US         | `usd` |
| Livre Sterling    | `gbp` |
| Yen Japonais      | `jpy` |
| Franc Suisse      | `chf` |
| Dollar Canadien   | `cad` |
| Dollar Australien | `aud` |

## Codes d'erreur

| Code HTTP | Erreur                                         | Description                                |
| --------- | ---------------------------------------------- | ------------------------------------------ |
| 400       | `Invalid payload`                              | Validation du corps de requête échouée     |
| 400       | `Missing customer.externalId`                  | Champ requis non fourni                    |
| 401       | `Invalid API key`                              | Clé API invalide ou révoquée               |
| 401       | `Hostname not in allowed list`                 | Origine non autorisée (côté client)        |
| 403       | `This click does not belong to your workspace` | trackingId appartient à un autre workspace |
| 404       | `Click not found for this trackingId`          | trackingId n'existe pas ou a expiré        |