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

# Ventes

> Apprenez à récupérer et gérer les données de ventes via l'API Chariow

Les ventes représentent les transactions d'achat dans votre boutique, qu'elles soient terminées, en attente, abandonnées, échouées ou réglées. Chaque vente contient des informations complètes sur le produit, le client, les détails de paiement, les remises appliquées, les informations d'expédition et l'accès post-achat.

## Comprendre les ventes

L'API Ventes de Chariow fournit un accès programmatique à toutes les données de transaction de votre boutique. Vous pouvez :

* Récupérer une liste de toutes les ventes avec des options de filtrage
* Obtenir des informations détaillées sur des ventes spécifiques
* Suivre le statut de paiement et les détails de règlement
* Accéder à l'historique d'achat des clients
* Surveiller les statistiques de téléchargement
* Consulter les remises appliquées et les campagnes marketing

## Objet Vente

L'objet vente détaillé (renvoyé par le point de terminaison de vente unique) contient des informations complètes sur l'achat avec la structure suivante :

```json theme={null}
{
  "id": "sal_abc123xyz",
  "status": "completed",
  "channel": {
    "value": "store",
    "label": "Store",
    "description": "Sale made through the store checkout"
  },
  "original_amount": {
    "value": 99,
    "formatted": "$99.00",
    "short": "99",
    "currency": "USD"
  },
  "amount": {
    "value": 79.20,
    "formatted": "$79.20",
    "short": "79",
    "currency": "USD"
  },
  "discount_amount": {
    "value": 19.80,
    "formatted": "$19.80",
    "short": "20",
    "currency": "USD"
  },
  "settlement": {
    "amount": {
      "value": 75.24,
      "formatted": "$75.24",
      "short": "75",
      "currency": "USD"
    },
    "due_at": "2025-02-01T00:00:00+00:00",
    "done_at": "2025-02-01T10:15:00+00:00",
    "service_fee": {
      "value": 3.96,
      "formatted": "$3.96",
      "short": "4",
      "currency": "USD"
    }
  },
  "download": {
    "total": 3,
    "last_at": "2025-01-20T14:30:00+00:00"
  },
  "invoice_download_url": "https://api.chariow.com/invoices/sal_abc123xyz.pdf",
  "payment": {
    "status": "success",
    "transaction_id": "txn_moneroo_xyz789",
    "gateway": "moneroo",
    "method": {
      "name": "Credit/Debit Card",
      "icon_url": "https://assets.cdn.moneroo.io/icons/circle/card.svg"
    },
    "amount": {
      "value": 79.20,
      "formatted": "$79.20",
      "short": "79",
      "currency": "USD"
    },
    "fee": {
      "value": 2.37,
      "formatted": "$2.37",
      "short": "2",
      "currency": "USD"
    },
    "fee_rate": "3%",
    "interchange": {
      "rate": "1.5%",
      "fee": {
        "value": 1.19,
        "formatted": "$1.19",
        "short": "1",
        "currency": "USD"
      }
    },
    "exchange_rate": {
      "value": 1.0,
      "formatted": "$1.00",
      "short": "1",
      "currency": "USD"
    },
    "failure_error": null
  },
  "shipping": {
    "address": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "country": {
      "name": "United States",
      "code": "US",
      "alpha_3_code": "USA",
      "dial_code": "+1",
      "currency": "USD",
      "flag": "🇺🇸"
    },
    "zip": "10001"
  },
  "context": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
    "ip_address": "203.0.113.42",
    "country": {
      "name": "United States",
      "code": "US",
      "alpha_3_code": "USA",
      "dial_code": "+1",
      "currency": "USD",
      "flag": "🇺🇸"
    },
    "device_type": "desktop",
    "locale": "en_US"
  },
  "custom_fields_values": null,
  "campaign": {
    "id": "cmp_pqr678",
    "name": "Black Friday Campaign"
  },
  "rating": {
    "id": "rat_mno345",
    "is_thumbs_up": true,
    "comment": "Excellent product!",
    "created_at": "2025-01-18T09:00:00+00:00"
  },
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store",
    "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
    "url": "https://mystore.mychariow.com"
  },
  "product": {
    "id": "prd_def456",
    "name": "Premium Course",
    "type": "course",
    "pictures": {
      "thumbnail": "https://cdn.chariow.com/products/thumb.jpg",
      "cover": "https://cdn.chariow.com/products/cover.jpg"
    },
    "category": {
      "value": "education_and_learning",
      "label": "Education and Learning"
    },
    "pricing": {
      "type": "one_time",
      "price": {
        "value": 99,
        "formatted": "$99.00",
        "short": "99",
        "currency": "USD"
      },
      "effective": {
        "value": 79.20,
        "formatted": "$79.20",
        "short": "79",
        "currency": "USD"
      }
    },
    "bundle": null,
    "metadata": null
  },
  "customer": {
    "id": "cus_ghi789",
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@example.com",
    "avatar_url": null
  },
  "discount": {
    "id": "dis_jkl012",
    "name": "Save 20%",
    "code": "SAVE20"
  },
  "store_affiliate": null,
  "affiliate_commission": null,
  "is_reconciled": true,
  "last_reconciled_at": "2025-02-01T10:15:00+00:00",
  "failed_at": null,
  "awaiting_payment_at": "2025-01-15T10:30:00+00:00",
  "abandoned_at": null,
  "completed_at": "2025-01-15T10:32:00+00:00",
  "created_at": "2025-01-15T10:30:00+00:00",
  "updated_at": "2025-01-15T10:32:00+00:00"
}
```

<Note>
  Le point de terminaison de liste renvoie une version simplifiee de l'objet vente (utilisant `SalePublicResource`), tandis que le point de terminaison de vente unique renvoie l'objet detaille complet (utilisant `SaleResource`). Consultez les sections [Lister les ventes](#lister-les-ventes) et [Obtenir une vente specifique](#obtenir-une-vente-specifique) pour les differences.
</Note>

## Statuts des ventes

Les ventes peuvent avoir les statuts suivants tout au long de leur cycle de vie :

| Statut             | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `awaiting_payment` | Paiement initié, en attente de confirmation du paiement |
| `completed`        | Paiement réussi, accès au produit accordé au client     |
| `failed`           | Paiement échoué ou refusé                               |
| `abandoned`        | Client a abandonné le processus de paiement             |
| `settled`          | Fonds réglés sur le compte du marchand                  |

## Statuts de paiement

Le statut de paiement suit la transaction de la passerelle de paiement séparément du statut de vente :

| Statut de paiement | Description                                              |
| ------------------ | -------------------------------------------------------- |
| `initiated`        | Le processus de paiement a démarré                       |
| `pending`          | Le paiement est en cours de traitement par la passerelle |
| `success`          | Le paiement a été traité avec succès                     |
| `failed`           | Le paiement a échoué ou a été refusé                     |
| `cancelled`        | Le paiement a été annulé par le client ou le système     |

## Canaux de vente

Les ventes peuvent provenir de différents canaux :

| Canal       | Description                                        |
| ----------- | -------------------------------------------------- |
| `store`     | Vente directe via le paiement de votre boutique    |
| `affiliate` | Vente effectuée via un lien d'affiliation          |
| `discover`  | Vente provenant de la marketplace Chariow Discover |
| `widget`    | Vente via un widget de paiement intégré            |
| `api`       | Vente créée via l'API publique                     |

## Lister les ventes

Récupérez toutes les ventes de votre boutique :

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/sales" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.chariow.com/v1/sales', {
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key'
    }
  });

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.chariow.com/v1/sales',
      headers={'Authorization': 'Bearer sk_live_your_api_key'}
  )

  sales = response.json()['data']
  ```
</CodeGroup>

### Paramètres de requête

Vous pouvez filtrer et paginer les ventes en utilisant les paramètres suivants :

| Paramètre     | Type    | Description                                                                                     |
| ------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `per_page`    | integer | Nombre de ventes par page (max 100, défaut 15)                                                  |
| `cursor`      | string  | Curseur pour la pagination (depuis `next_cursor` ou `prev_cursor`)                              |
| `status`      | string  | Filtrer par statut de vente (`awaiting_payment`, `completed`, `failed`, `abandoned`, `settled`) |
| `customer_id` | string  | Filtrer par ID public du client (ex : `cus_abc123xyz`)                                          |
| `search`      | string  | Rechercher par référence de vente ou email du client                                            |
| `start_date`  | string  | Filtrer les ventes à partir de cette date (format : `Y-m-d`, ex : `2025-01-01`)                 |
| `end_date`    | string  | Filtrer les ventes jusqu'à cette date (format : `Y-m-d`, ex : `2025-01-31`)                     |

### Filtrer par statut

```bash theme={null}
# Obtenir uniquement les ventes terminées
curl -X GET "https://api.chariow.com/v1/sales?status=completed" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Filtrer par client

```bash theme={null}
# Obtenir les ventes d'un client spécifique
curl -X GET "https://api.chariow.com/v1/sales?customer_id=cus_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Filtrer par plage de dates

```bash theme={null}
# Obtenir les ventes de janvier 2025
curl -X GET "https://api.chariow.com/v1/sales?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Rechercher des ventes

```bash theme={null}
# Rechercher par email du client ou référence de vente
curl -X GET "https://api.chariow.com/v1/sales?search=customer@example.com" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Pagination

L'API utilise une pagination basée sur les curseurs. Utilisez le `next_cursor` de la réponse pour récupérer la page suivante :

```javascript theme={null}
let cursor = null;
let allSales = [];

do {
  const url = cursor
    ? `https://api.chariow.com/v1/sales?cursor=${cursor}`
    : 'https://api.chariow.com/v1/sales';

  const response = await fetch(url, {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  });

  const result = await response.json();
  allSales = [...allSales, ...result.data];
  cursor = result.pagination.next_cursor;
} while (cursor);
```

### Exemple de réponse

Le point de terminaison de liste renvoie un objet vente simplifié par élément :

```json theme={null}
{
  "data": [
    {
      "id": "sal_abc123xyz",
      "status": "completed",
      "original_amount": {
        "value": 99,
        "formatted": "$99.00",
        "short": "99",
        "currency": "USD"
      },
      "amount": {
        "value": 79.20,
        "formatted": "$79.20",
        "short": "79",
        "currency": "USD"
      },
      "discount_amount": {
        "value": 19.80,
        "formatted": "$19.80",
        "short": "20",
        "currency": "USD"
      },
      "payment": {
        "amount": {
          "value": 79.20,
          "formatted": "$79.20",
          "short": "79",
          "currency": "USD"
        },
        "status": "success",
        "exchange_rate": {
          "value": 1.0,
          "formatted": "$1.00",
          "short": "1",
          "currency": "USD"
        },
        "failure_error": null
      },
      "shipping": {
        "address": "123 Main Street",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "zip": "10001"
      },
      "invoice_download_url": "https://api.chariow.com/invoices/sal_abc123xyz.pdf",
      "created_at": "2025-01-15T10:30:00+00:00",
      "completed_at": "2025-01-15T10:32:00+00:00",
      "store": {
        "id": "str_ghi789",
        "name": "My Digital Store",
        "logo_url": "https://cdn.chariow.com/stores/ghi789/logo.png",
        "url": "https://mystore.mychariow.com"
      },
      "product": {
        "id": "prd_def456",
        "name": "Premium Course",
        "type": "course",
        "pictures": {
          "thumbnail": "https://cdn.chariow.com/products/thumb.jpg",
          "cover": "https://cdn.chariow.com/products/cover.jpg"
        },
        "category": {
          "value": "education_and_learning",
          "label": "Education and Learning"
        },
        "pricing": {
          "type": "one_time",
          "price": {
            "value": 99,
            "formatted": "$99.00",
            "short": "99",
            "currency": "USD"
          },
          "effective": {
            "value": 79.20,
            "formatted": "$79.20",
            "short": "79",
            "currency": "USD"
          }
        },
        "bundle": null,
        "metadata": null
      },
      "customer": {
        "id": "cus_xyz789",
        "name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "email": "customer@example.com",
        "avatar_url": null
      },
      "discount": {
        "id": "dis_jkl012",
        "name": "Save 20%",
        "code": "SAVE20"
      },
      "rate": {
        "id": "rat_mno345",
        "is_thumbs_up": true,
        "comment": "Excellent product!",
        "created_at": "2025-01-18T09:00:00+00:00"
      },
      "fulfillment": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6NTB9",
    "prev_cursor": null,
    "has_more": true
  }
}
```

## Obtenir une vente spécifique

Récupérez une vente spécifique par son ID public :

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/sales/sal_abc123" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.chariow.com/v1/sales/sal_abc123', {
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key'
    }
  });

  const result = await response.json();
  ```
</CodeGroup>

## Livraison post-achat

Les ventes terminées peuvent inclure des données de livraison contenant les éléments livrables en fonction du type de produit. Le champ `fulfillment` est présent dans la réponse du point de terminaison de liste lorsqu'il est rempli :

```json theme={null}
{
  "fulfillment": {
    "files": [
      {
        "id": "fil_abc123",
        "name": "course-materials.zip",
        "size": 15728640,
        "type": "application/zip",
        "download_url": "https://cdn.chariow.com/downloads/...",
        "expires_at": "2025-01-20T10:30:00+00:00"
      }
    ],
    "licences": [
      {
        "id": "lic_def456",
        "licence_key": "ABC-123-XYZ-789",
        "status": "active",
        "activations": 2,
        "max_activations": 5,
        "expires_at": null
      }
    ],
    "instructions": "Merci pour votre achat ! Voici comment démarrer avec vos supports de cours..."
  }
}
```

### Téléchargements de fichiers

Pour les produits avec des fichiers téléchargeables, le tableau `files` contient :

* `id` - Identifiant unique du fichier
* `name` - Nom du fichier original
* `size` - Taille du fichier en octets
* `type` - Type MIME
* `download_url` - URL de téléchargement signée temporaire
* `expires_at` - Date d'expiration du lien de téléchargement

### Licences

Pour les produits avec des clés de licence, le tableau `licences` contient :

* `id` - Identifiant unique de la licence
* `licence_key` - La chaîne de la clé de licence
* `status` - Statut de la licence (`active`, `inactive`, `expired`)
* `activations` - Nombre actuel d'activations
* `max_activations` - Nombre maximum d'activations autorisées
* `expires_at` - Date d'expiration (null pour les licences à vie)

### Instructions personnalisées

Le champ `instructions` contient les instructions post-achat personnalisées configurées pour le produit.

## Cas d'utilisation courants

<AccordionGroup>
  <Accordion title="Rapports de revenus" icon="chart-line">
    Calculez le revenu total pour une période spécifique :

    ```javascript theme={null}
    const response = await fetch(
      'https://api.chariow.com/v1/sales?status=completed&start_date=2025-01-01&end_date=2025-01-31',
      { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
    );

    const result = await response.json();
    const totalRevenue = result.data.reduce(
      (sum, sale) => sum + sale.amount.value,
      0
    );

    console.log(`Revenu total : ${totalRevenue}`);
    ```
  </Accordion>

  <Accordion title="Traitement des commandes" icon="truck">
    Traitez les commandes nécessitant une expédition physique :

    ```javascript theme={null}
    // Obtenir les ventes terminées avec adresses d'expédition
    const response = await fetch(
      'https://api.chariow.com/v1/sales?status=completed',
      { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
    );

    const result = await response.json();
    const ordersToShip = result.data.filter(
      sale => sale.shipping && sale.shipping.address
    );

    // Traiter chaque commande
    ordersToShip.forEach(sale => {
      console.log(`Expédier à : ${sale.shipping.address}, ${sale.shipping.city}`);
    });
    ```
  </Accordion>

  <Accordion title="Historique d'achat client" icon="clock-rotate-left">
    Consultez l'historique d'achat complet d'un client :

    ```bash theme={null}
    curl -X GET "https://api.chariow.com/v1/sales?customer_id=cus_abc123xyz" \
      -H "Authorization: Bearer sk_live_your_api_key"
    ```

    Cela renvoie toutes les ventes pour le client spécifié, incluant :

    * Dates et montants d'achat
    * Produits achetés
    * Remises appliquées
    * Statut d'accès actuel
  </Accordion>

  <Accordion title="Récupération des paiements échoués" icon="credit-card">
    Identifiez et traitez les paiements échoués :

    ```javascript theme={null}
    const response = await fetch(
      'https://api.chariow.com/v1/sales?status=failed',
      { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
    );

    const result = await response.json();

    // Examiner les ventes échouées et les détails d'erreur de paiement
    result.data.forEach(sale => {
      if (sale.payment.failure_error) {
        console.log(`Vente échouée ${sale.id} : ${sale.payment.failure_error.message}`);
        // Agir en fonction du code d'erreur
      }
    });
    ```
  </Accordion>

  <Accordion title="Analyse des performances des remises" icon="tag">
    Analysez l'utilisation et l'efficacité des codes de remise :

    ```javascript theme={null}
    const response = await fetch(
      'https://api.chariow.com/v1/sales?status=completed&start_date=2025-01-01',
      { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
    );

    const result = await response.json();

    // Regrouper par code de remise
    const discountStats = result.data
      .filter(sale => sale.discount)
      .reduce((acc, sale) => {
        const code = sale.discount.code;
        if (!acc[code]) {
          acc[code] = { uses: 0, revenue: 0, discountGiven: 0 };
        }
        acc[code].uses++;
        acc[code].revenue += sale.amount.value;
        acc[code].discountGiven += sale.discount_amount.value;
        return acc;
      }, {});

    console.log(discountStats);
    ```
  </Accordion>
</AccordionGroup>

## Informations de règlement

Pour les ventes terminées, l'objet `settlement` fournit des détails sur les paiements au marchand :

```json theme={null}
{
  "settlement": {
    "amount": {
      "value": 75.24,
      "formatted": "$75.24",
      "short": "75",
      "currency": "USD"
    },
    "due_at": "2025-02-01T00:00:00+00:00",
    "done_at": "2025-02-01T10:15:00+00:00",
    "service_fee": {
      "value": 3.96,
      "formatted": "$3.96",
      "short": "4",
      "currency": "USD"
    }
  }
}
```

* `amount` - Montant net à payer au marchand (après frais)
* `due_at` - Date prévue du règlement
* `done_at` - Date de réalisation du règlement (null si en attente)
* `service_fee` - Frais de service de la plateforme Chariow

## Suivi des téléchargements

Surveillez l'activité de téléchargement des clients :

```json theme={null}
{
  "download": {
    "total": 3,
    "last_at": "2025-01-20T14:30:00+00:00"
  }
}
```

Cela vous permet de :

* Suivre l'engagement avec le produit
* Identifier les clients qui n'ont pas accédé à leur achat
* Surveiller les modèles de téléchargement inhabituels

## Ressources associées

<CardGroup cols={2}>
  <Card title="Guide de paiement" icon="shopping-cart" href="/fr/guides/checkout">
    Apprenez à créer des ventes
  </Card>

  <Card title="Pulses" icon="webhook" href="/fr/guides/pulses">
    Soyez notifié des nouvelles ventes
  </Card>

  <Card title="API Ventes" icon="code" href="/api-reference/sales/list-sales">
    Consultez la référence complète de l'API Ventes
  </Card>
</CardGroup>