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, 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 :

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

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 et Obtenir une vente specifique pour les differences.

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 :

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

# 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?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"

Rechercher des ventes

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

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

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

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 :

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

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

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.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&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);

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

Livraison post-achat

Téléchargements de fichiers

Licences

Instructions personnalisées

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

​Livraison post-achat

​Téléchargements de fichiers

​Licences

​Instructions personnalisées

​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

Livraison post-achat

Téléchargements de fichiers

Licences

Instructions personnalisées

Cas d’utilisation courants

Informations de règlement

Suivi des téléchargements

Ressources associées