Ventes

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 et les informations d’expédition.

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 :

{
  "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/...signed-invoice-url...",
  "payment": {
    "status": "success",
    "transaction_id": "txn_xyz789",
    "gateway": "orqex",
    "method": {
      "name": "Orange Money Senegal",
      "icon_url": "https://assets.example.com/icons/orange_money.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",
    "phone": {
      "number": "+1 234 567 890",
      "country": {
        "name": "United States",
        "code": "US",
        "alpha_3_code": "USA",
        "dial_code": "+1",
        "currency": "USD",
        "flag": "🇺🇸"
      }
    },
    "avatar_url": null
  },
  "buyer": {
    "first_name": "John",
    "last_name": "Doe"
  },
  "discount": {
    "id": "dis_jkl012",
    "name": "Save 20%",
    "code": "SAVE20"
  },
  "is_access_revoked": false,
  "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"
}

Le point de terminaison de liste renvoie une version simplifiée de l’objet vente, tandis que le point de terminaison de vente unique renvoie l’objet détaillé complet présenté ci-dessus. Consultez les sections Lister les ventes et Obtenir une vente spécifique pour les différences. buyer conserve le nom saisi au moment de l’achat, alors que customer reflète le profil actuel du client. Un objet gift (recipient, message) est ajouté pour les achats cadeaux.

Statuts des ventes

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

Statut	Description
`initiated`	Vente créée, paiement pas encore démarré
`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

failed et abandoned ne sont pas toujours définitifs. Lorsque la passerelle de paiement indique ensuite que l’acheteur a bien payé (par exemple un paiement finalisé après l’expiration du checkout), la vente est rouverte en awaiting_payment, son failed_at ou abandoned_at est effacé, puis elle passe à completed. Écoutez les événements de vente via les Pulses plutôt que de considérer ces statuts comme définitifs.

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 :

curl -X GET "https://api.chariow.com/v1/sales" \
  -H "Authorization: Bearer sk_live_your_api_key"

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

const result = await response.json();

import requests

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

sales = response.json()['data']

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 (1 à 100, défaut 10)
`cursor`	string	Curseur pour la pagination (depuis `next_cursor` ou `prev_cursor`)
`status`	string	Filtrer par statut de vente (`initiated`, `awaiting_payment`, `completed`, `failed`, `abandoned`, `settled`)
`customer_id`	string	Filtrer par ID public du client (ex : `cus_abc123xyz`)
`search`	string	Rechercher par ID de vente ou ID de transaction de paiement
`from`	string	Ventes créées à partir de cette date incluse (format : `Y-m-d`, ex : `2025-01-01`)
`to`	string	Ventes créées jusqu’à cette date incluse (format : `Y-m-d`, ex : `2025-01-31`)
`period`	string	Raccourci de plage de dates, à la place de `from` et `to` : `today`, `yesterday`, `last7days`, `last30days`, `thisWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `thisYear`, `lastYear`

start_date et end_date ne sont pas pris en charge et sont ignorés sans erreur, ce qui renvoie les ventes de toutes les dates. Utilisez from et to.

Filtrer par statut

# 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

# 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

# Obtenir les ventes de janvier 2025
curl -X GET "https://api.chariow.com/v1/sales?from=2025-01-01&to=2025-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"

Rechercher des ventes

# Rechercher par ID de vente ou ID de transaction de paiement
curl -X GET "https://api.chariow.com/v1/sales?search=sal_abc123xyz" \
  -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 :

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 :

{
  "data": [
    {
      "id": "sal_abc123xyz",
      "status": "completed",
      "tracking": {
        "event_id": "sal_abc123xyz",
        "currency": "USD",
        "value": 79.2
      },
      "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/...signed-invoice-url...",
      "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",
        "phone": {
          "number": "+1 234 567 890",
          "country": {
            "name": "United States",
            "code": "US",
            "alpha_3_code": "USA",
            "dial_code": "+1",
            "currency": "USD",
            "flag": "🇺🇸"
          }
        },
        "avatar_url": null
      },
      "buyer": {
        "first_name": "John",
        "last_name": "Doe"
      },
      "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"
      }
    }
  ],
  "pagination": {
    "per_page": 10,
    "next_cursor": "eyJpZCI6NTB9",
    "prev_cursor": null,
    "has_more_pages": true
  }
}

Obtenir une vente spécifique

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

curl -X GET "https://api.chariow.com/v1/sales/sal_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

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();

Cas d’utilisation courants

Rapports de revenus

Calculez le revenu total pour une période spécifique :

const response = await fetch(
  'https://api.chariow.com/v1/sales?status=completed&from=2025-01-01&to=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}`);

Traitement des commandes

Traitez les commandes nécessitant une expédition physique :

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

Historique d'achat client

Consultez l’historique d’achat complet d’un client :

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

Récupération des paiements échoués

Identifiez et traitez les paiements échoués :

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.code} (${sale.payment.failure_error.customer_message})`);
    // Agir en fonction du code d'erreur
  }
});

Analyse des performances des remises

Analysez l’utilisation et l’efficacité des codes de remise :

const response = await fetch(
  'https://api.chariow.com/v1/sales?status=completed&from=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);

Informations de règlement

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

{
  "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 :

{
  "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

Guide de paiement

Apprenez à créer des ventes

Pulses

Soyez notifié des nouvelles ventes

API Ventes

Consultez la référence complète de l’API Ventes

Introduction

Guides

Intégration MCP

Intégration n8n

Resources

Comprendre les ventes

Objet Vente

Statuts des ventes

Statuts de paiement

Canaux de vente

Lister les ventes

Paramètres de requête

Filtrer par statut

Filtrer par client

Filtrer par plage de dates

Rechercher des ventes

Exemple de réponse

Obtenir une vente spécifique

Cas d’utilisation courants

Informations de règlement

Suivi des téléchargements

Ressources associées

Guide de paiement

Pulses

API Ventes

​Comprendre les ventes

​Objet Vente

​Statuts des ventes

​Statuts de paiement

​Canaux de vente

​Lister les ventes

​Paramètres de requête

​Filtrer par statut

​Filtrer par client

​Filtrer par plage de dates

​Rechercher des ventes

​Pagination

​Exemple de réponse

​Obtenir une vente spécifique

​Cas d’utilisation courants

​Informations de règlement

​Suivi des téléchargements

​Ressources associées

Guide de paiement

Pulses

API Ventes

Comprendre les ventes

Objet Vente

Statuts des ventes

Statuts de paiement

Canaux de vente

Lister les ventes

Paramètres de requête

Filtrer par statut

Filtrer par client

Filtrer par plage de dates

Rechercher des ventes

Pagination

Exemple de réponse

Obtenir une vente spécifique

Cas d’utilisation courants

Informations de règlement

Suivi des téléchargements

Ressources associées