Bonnes pratiques

Suivez ces bonnes pratiques pour construire des intégrations robustes, sécurisées et fiables avec l’API Chariow, en particulier lors de la gestion des flux de paiement.

Bonnes pratiques de l’API Checkout

Toujours gérer tous les états de réponse

L’API checkout renvoie différents états qui nécessitent différents traitements. Ne supposez jamais qu’un checkout nécessitera toujours un paiement.

async function handleCheckout(checkoutData) {
  const response = await fetch('https://api.chariow.com/v1/checkout', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(checkoutData)
  });

  const result = await response.json();

  switch (result.data.step) {
    case 'payment':
      // Redirection vers le paiement - cas le plus courant
      return { action: 'redirect', url: result.data.payment.checkout_url };

    case 'completed':
      // Produit gratuit - vente finalisée immédiatement
      return { action: 'success', saleId: result.data.purchase.id };

    case 'already_purchased':
      // Le client possède déjà ce produit
      return { action: 'already_owned', message: result.data.message };

    default:
      // Gérer les états inattendus gracieusement
      console.error('État de checkout inattendu :', result.data.step);
      return { action: 'error', message: 'Réponse inattendue du système de paiement' };
  }
}

Valider les données avant soumission

Réduisez les échecs de paiement en validant les données client de votre côté avant d’appeler l’API.

function validateCheckoutData(data) {
  const errors = [];

  // Validation de l'email
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!data.email || !emailRegex.test(data.email)) {
    errors.push('Un email valide est requis');
  }

  // Validation du nom
  if (!data.first_name || data.first_name.length > 50) {
    errors.push('Le prénom est requis (max 50 caractères)');
  }
  if (!data.last_name || data.last_name.length > 50) {
    errors.push('Le nom est requis (max 50 caractères)');
  }

  // Validation du téléphone - numérique uniquement
  const phoneNumber = data.phone?.number?.replace(/\D/g, '');
  if (!phoneNumber || phoneNumber.length < 6) {
    errors.push('Un numéro de téléphone valide est requis');
  }

  // Validation du code pays
  const validCountryCodes = ['US', 'CA', 'GB', 'FR', 'DE', 'ES', 'IT', /* ... */];
  if (!data.phone?.country_code || !validCountryCodes.includes(data.phone.country_code)) {
    errors.push('Un code pays valide est requis');
  }

  return {
    valid: errors.length === 0,
    errors
  };
}

Stocker les IDs de vente immédiatement

Persistez toujours l’ID de vente dès que vous le recevez. C’est crucial pour le support client, les remboursements et le suivi des commandes.

async function processCheckout(checkoutData, orderId) {
  const result = await initiateCheckout(checkoutData);

  if (result.data.purchase?.id) {
    // Stocker immédiatement - avant toute redirection
    await database.orders.update(orderId, {
      chariow_sale_id: result.data.purchase.id,
      checkout_initiated_at: new Date()
    });
  }

  return result;
}

Utiliser les Pulses pour une confirmation de vente fiable

Ne vous fiez jamais uniquement aux URL de redirection pour confirmer les achats. Les pages de paiement peuvent être fermées, les redirections peuvent échouer et les clients peuvent ne pas revenir sur votre site.

La redirect_url est uniquement pour l’expérience utilisateur. Utilisez toujours les Pulses (webhooks) pour une confirmation de vente fiable.

// Configurer un endpoint Pulse pour la confirmation de vente
app.post('/webhooks/chariow', async (req, res) => {
  const signature = req.headers['x-chariow-signature'];

  // Vérifier la signature du webhook
  if (!verifySignature(req.body, signature)) {
    return res.status(401).send('Signature invalide');
  }

  const { event, data } = req.body;

  switch (event) {
    case 'sale.completed':
      await fulfillOrder(data.id);
      await sendConfirmationEmail(data.customer.email);
      break;

    case 'sale.refunded':
      await revokeAccess(data.id);
      await sendRefundEmail(data.customer.email);
      break;
  }

  res.status(200).send('OK');
});

Bonnes pratiques de sécurité

Ne jamais exposer les clés API dans le code client

Les clés API ne doivent être utilisées que côté serveur. Ne les incluez jamais dans les bundles JavaScript, les applications mobiles ou tout code exposé au client.

Correct
Incorrect

// Côté serveur (Node.js)
const API_KEY = process.env.CHARIOW_API_KEY;

app.post('/api/checkout', async (req, res) => {
  const response = await fetch('https://api.chariow.com/v1/checkout', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(req.body)
  });

  res.json(await response.json());
});

// Côté client - NE JAMAIS FAIRE CELA
const API_KEY = 'sk_live_abc123'; // EXPOSÉ !

fetch('https://api.chariow.com/v1/checkout', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

Valider les signatures des webhooks

Vérifiez toujours que les webhooks entrants proviennent réellement de Chariow en vérifiant la signature.

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Utiliser les variables d’environnement

Stockez toute configuration sensible dans les variables d’environnement, jamais dans le code.

# Fichier .env (ne jamais commiter)
CHARIOW_API_KEY=sk_live_your_api_key
CHARIOW_WEBHOOK_SECRET=whsec_your_webhook_secret

// Charger depuis l'environnement
const config = {
  apiKey: process.env.CHARIOW_API_KEY,
  webhookSecret: process.env.CHARIOW_WEBHOOK_SECRET
};

Bonnes pratiques de gestion des erreurs

Implémenter une gestion d’erreurs complète

Gérez tous les scénarios d’erreur possibles gracieusement pour offrir une bonne expérience utilisateur.

async function safeCheckout(checkoutData) {
  try {
    const response = await fetch('https://api.chariow.com/v1/checkout', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(checkoutData)
    });

    // Gérer les erreurs HTTP
    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 401:
          console.error('Clé API invalide');
          return { error: 'Erreur de configuration du système de paiement' };

        case 404:
          return { error: 'Produit non trouvé ou indisponible' };

        case 422:
          // Erreurs de validation - retourner les messages spécifiques aux champs
          return { error: 'Échec de validation', fields: error.errors };

        case 429:
          return { error: 'Trop de requêtes. Veuillez réessayer dans un moment.' };

        default:
          return { error: 'Système de paiement indisponible. Veuillez réessayer.' };
      }
    }

    return await response.json();

  } catch (networkError) {
    // Gérer les échecs réseau
    console.error('Erreur réseau :', networkError);
    return { error: 'Impossible de se connecter au système de paiement. Vérifiez votre connexion.' };
  }
}

Afficher des messages d’erreur conviviaux

Mappez les erreurs API vers des messages utiles qui guident les utilisateurs pour corriger les problèmes.

const errorMessages = {
  'email': 'Veuillez entrer une adresse email valide',
  'phone.number': 'Veuillez entrer un numéro de téléphone valide (chiffres uniquement)',
  'phone.country_code': 'Veuillez sélectionner votre pays',
  'address': 'Veuillez entrer votre adresse de livraison',
  'city': 'Veuillez entrer votre ville',
  'state': 'Veuillez entrer votre état ou région',
  'country': 'Veuillez sélectionner votre pays',
  'zip': 'Veuillez entrer votre code postal',
  'discount_code': 'Ce code de réduction est invalide ou a expiré'
};

function getFieldError(fieldName, apiErrors) {
  if (apiErrors[fieldName]) {
    return errorMessages[fieldName] || apiErrors[fieldName][0];
  }
  return null;
}

Journaliser les erreurs pour le débogage

Maintenez des logs détaillés pour le dépannage tout en gardant les données sensibles sécurisées.

function logCheckoutError(error, checkoutData) {
  // Supprimer les données sensibles avant la journalisation
  const safeData = {
    product_id: checkoutData.product_id,
    email: maskEmail(checkoutData.email),
    timestamp: new Date().toISOString(),
    error: error.message || error
  };

  console.error('Échec du checkout :', JSON.stringify(safeData));

  // Envoyer au service de monitoring
  monitoring.captureError(error, { context: safeData });
}

function maskEmail(email) {
  const [local, domain] = email.split('@');
  return `${local.slice(0, 2)}***@${domain}`;
}

Bonnes pratiques de performance

Implémenter des délais d’expiration

Ne laissez pas les appels API se bloquer indéfiniment. Définissez des délais raisonnables.

async function checkoutWithTimeout(checkoutData, timeoutMs = 30000) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);

  try {
    const response = await fetch('https://api.chariow.com/v1/checkout', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(checkoutData),
      signal: controller.signal
    });

    return await response.json();
  } finally {
    clearTimeout(timeout);
  }
}

Mettre en cache les données produit

Réduisez les appels API en mettant en cache les informations produit qui ne changent pas fréquemment.

const productCache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getProduct(productId) {
  const cached = productCache.get(productId);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const response = await fetch(`https://api.chariow.com/v1/products/${productId}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });

  const data = await response.json();

  productCache.set(productId, {
    data: data.data,
    timestamp: Date.now()
  });

  return data.data;
}

Respecter les limites de débit

Gérez la limitation de débit gracieusement avec un backoff exponentiel.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
      console.log(`Limite de débit atteinte. Nouvelle tentative après ${retryAfter}s`);
      await sleep(retryAfter * 1000);
      continue;
    }

    return response;
  }

  throw new Error('Nombre maximum de tentatives dépassé');
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Bonnes pratiques de test

Tester tous les scénarios de checkout

Créez des tests complets pour chaque résultat de checkout possible.

describe('Intégration Checkout', () => {
  test('gère le checkout de produit payant', async () => {
    const result = await handleCheckout({
      product_id: 'prd_paid_product',
      email: 'test@example.com',
      // ...
    });

    expect(result.action).toBe('redirect');
    expect(result.url).toContain('payment.chariow.com');
  });

  test('gère le checkout de produit gratuit', async () => {
    const result = await handleCheckout({
      product_id: 'prd_free_product',
      email: 'test@example.com',
      // ...
    });

    expect(result.action).toBe('success');
    expect(result.saleId).toBeDefined();
  });

  test('gère le produit déjà acheté', async () => {
    const result = await handleCheckout({
      product_id: 'prd_already_owned',
      email: 'existing@example.com',
      // ...
    });

    expect(result.action).toBe('already_owned');
  });

  test('gère gracieusement un produit invalide', async () => {
    const result = await handleCheckout({
      product_id: 'prd_nonexistent',
      email: 'test@example.com',
      // ...
    });

    expect(result.error).toBeDefined();
  });

  test('gère les produits nécessitant une livraison', async () => {
    const result = await handleCheckout({
      product_id: 'prd_physical',
      email: 'test@example.com',
      address: '123 Rue Principale',
      city: 'Paris',
      state: 'Île-de-France',
      country: 'FR',
      zip: '75001',
      // ...
    });

    expect(result.action).toBe('redirect');
  });
});

Utiliser l’environnement de staging pour les tests d’intégration

Testez toujours contre un environnement de staging avant de déployer en production.

const config = {
  development: {
    apiUrl: 'https://api.staging.chariow.com/v1',
    apiKey: process.env.CHARIOW_STAGING_KEY
  },
  production: {
    apiUrl: 'https://api.chariow.com/v1',
    apiKey: process.env.CHARIOW_LIVE_KEY
  }
};

const env = process.env.NODE_ENV || 'development';
const apiConfig = config[env];

Checklist pour la production

Avant la mise en production, assurez-vous d’avoir complété cette checklist :

Sécurité

Clés API stockées dans les variables d’environnement
Appels API effectués côté serveur uniquement
Signatures des webhooks vérifiées
HTTPS utilisé pour tous les endpoints
Données sensibles non journalisées

Gestion des erreurs

Tous les codes de statut HTTP gérés
Erreurs réseau interceptées
Messages d’erreur conviviaux affichés
Erreurs journalisées pour le débogage
Limitation de débit gérée gracieusement

Flux de checkout

Tous les états de checkout gérés (payment, completed, already_purchased)
IDs de vente stockés immédiatement
Pulses configurés pour la confirmation de vente
Données client validées avant soumission
Champs de livraison inclus si requis

Tests

Tests unitaires pour la logique de checkout
Tests d’intégration avec l’API de staging
Tous les types de produits testés
Scénarios d’erreur testés
Tests de charge effectués

Prochaines étapes

Cas d'utilisation

Explorez des exemples d’intégration concrets

Guide du paiement

Apprenez le flux de paiement complet

Pulses

Configurez les webhooks pour les notifications

Référence API

Explorez l’API complète

Cas d'utilisation

Introduction

Guides

Intégration MCP

Intégration n8n

Resources

Bonnes pratiques de l’API Checkout

Toujours gérer tous les états de réponse

Valider les données avant soumission

Stocker les IDs de vente immédiatement

Utiliser les Pulses pour une confirmation de vente fiable

Bonnes pratiques de sécurité

Ne jamais exposer les clés API dans le code client

Valider les signatures des webhooks

Utiliser les variables d’environnement

Bonnes pratiques de gestion des erreurs

Implémenter une gestion d’erreurs complète

Afficher des messages d’erreur conviviaux

Journaliser les erreurs pour le débogage

Bonnes pratiques de performance

Implémenter des délais d’expiration

Mettre en cache les données produit

Respecter les limites de débit

Bonnes pratiques de test

Tester tous les scénarios de checkout

Utiliser l’environnement de staging pour les tests d’intégration

Checklist pour la production

Prochaines étapes

Cas d'utilisation

Guide du paiement

Pulses

Référence API

​Bonnes pratiques de l’API Checkout

​Toujours gérer tous les états de réponse

​Valider les données avant soumission

​Stocker les IDs de vente immédiatement

​Utiliser les Pulses pour une confirmation de vente fiable

​Bonnes pratiques de sécurité

​Ne jamais exposer les clés API dans le code client

​Valider les signatures des webhooks

​Utiliser les variables d’environnement

​Bonnes pratiques de gestion des erreurs

​Implémenter une gestion d’erreurs complète

​Afficher des messages d’erreur conviviaux

​Journaliser les erreurs pour le débogage

​Bonnes pratiques de performance

​Implémenter des délais d’expiration

​Mettre en cache les données produit

​Respecter les limites de débit

​Bonnes pratiques de test

​Tester tous les scénarios de checkout

​Utiliser l’environnement de staging pour les tests d’intégration

​Checklist pour la production

​Prochaines étapes

Cas d'utilisation

Guide du paiement

Pulses

Référence API

Bonnes pratiques de l’API Checkout

Toujours gérer tous les états de réponse

Valider les données avant soumission

Stocker les IDs de vente immédiatement

Utiliser les Pulses pour une confirmation de vente fiable

Bonnes pratiques de sécurité

Ne jamais exposer les clés API dans le code client

Valider les signatures des webhooks

Utiliser les variables d’environnement

Bonnes pratiques de gestion des erreurs

Implémenter une gestion d’erreurs complète

Afficher des messages d’erreur conviviaux

Journaliser les erreurs pour le débogage

Bonnes pratiques de performance

Implémenter des délais d’expiration

Mettre en cache les données produit

Respecter les limites de débit

Bonnes pratiques de test

Tester tous les scénarios de checkout

Utiliser l’environnement de staging pour les tests d’intégration

Checklist pour la production

Prochaines étapes