Baara
ConnexionCommencer

Documentation API

Intégrez BAARA directement dans votre système de caisse ou votre site e-commerce.

Authentification

Méthode d'authentification
Toutes les routes API nécessitent une session Appwrite valide

Via Cookie (Web)

Lorsque vous êtes connecté sur la plateforme web, votre session est automatiquement gérée via un cookie.

Cookie: session=your_session_secret

Via Header (Mobile/API)

Pour les applications mobiles ou les intégrations externes, utilisez le header suivant :

X-Appwrite-Session: your_session_secret

🔐 Sécurité

La session est obtenue après connexion via /api/auth/signin(marchands) ou /api/auth/customer/signin (clients).

Endpoints API

POST/api/merchant/transactions/by-account-code
Créer une transaction de fidélité

Description

Enregistre une transaction et attribue des points au client. Supporte deux modes : simple (montant total) ou détaillé (lignes de produits).

Body

{
  "accountCode": "CUST-1234-5678",
  "mode": "simple", // ou "detailed"
  "purchaseAmount": 5000,
  "items": [ // Pour mode detailed
    {
      "productId": "prod_123",
      "quantity": 2,
      "price": 2500
    }
  ],
  "transactionId": "unique_id_for_idempotence",
  "usePoints": false,
  "applyPromotions": true
}

Response

{
  "success": true,
  "account": {
    "code": "CUST-1234-5678",
    "points": 150,
    "level": "silver"
  },
  "pointsAdded": 50,
  "discountAmount": 0,
  "finalAmount": 5000
}
GET/api/merchant/loyalty/accounts/by-code
Récupérer un compte de fidélité par code

Récupère les informations d'un compte de fidélité (points, niveau, historique) à partir de son code.

Query params

?code=CUST-1234-5678
GET/api/merchant/loyalty/rules
Liste des règles de fidélité

Récupère toutes les règles de fidélité actives de votre organisation.

GET/api/merchant/loyalty-levels
Configuration des niveaux de fidélité

Récupère la configuration des niveaux de fidélité (Bronze, Argent, Or, etc.) avec leurs critères et avantages.

Codes de réponse HTTP

200 - Succès

La requête a réussi. La réponse contient les données demandées.

400 - Erreur de validation

Les données envoyées sont invalides. Vérifiez le format et les valeurs requises.

401 - Non authentifié

Vous devez être connecté pour accéder à cette ressource. Vérifiez votre session.

403 - Accès refusé

Vous n'avez pas les permissions nécessaires ou avez atteint une limite de votre abonnement.

404 - Non trouvé

La ressource demandée n'existe pas ou n'est plus disponible.

500 - Erreur serveur

Une erreur interne s'est produite. Réessayez plus tard ou contactez le support.

Format de réponse

Structure standard

Réponse de succès

{
  "success": true,
  "data": {
    // Données de la réponse
  }
}

Réponse d'erreur

{
  "success": false,
  "error": "Message d'erreur descriptif",
  "code": "ERROR_CODE" // Optionnel
}

Limites et bonnes pratiques

Rate Limiting

Pour éviter la surcharge du serveur, certaines limites s'appliquent :

  • 100 requêtes par minute par défaut
  • Les en-têtes de réponse incluent votre utilisation
  • En cas de dépassement, attendez avant de réessayer
Idempotence

Pour les opérations critiques (transactions), utilisez un transactionId unique :

  • Évite les doublons en cas de retry
  • Génère un UUID côté client
  • Le serveur ignore les requêtes dupliquées
Gestion des erreurs

Toujours vérifier le code de statut HTTP et le champ success :

  • Gérer les erreurs réseau (timeout, connexion perdue)
  • Implémenter un système de retry avec backoff
  • Logger les erreurs pour le débogage
Performance

Optimisez vos appels API :

  • Utilisez la pagination pour les grandes listes
  • Mettez en cache les données statiques
  • Évitez les appels inutiles

Exemples d'intégration

Exemple : Transaction simple
// JavaScript/TypeScript
const response = await fetch('/api/merchant/transactions/by-account-code', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Appwrite-Session': sessionSecret
  },
  body: JSON.stringify({
    accountCode: 'CUST-1234-5678',
    mode: 'simple',
    purchaseAmount: 5000,
    transactionId: crypto.randomUUID(),
    usePoints: false,
    applyPromotions: true
  })
});

const result = await response.json();
if (result.success) {
  console.log('Points ajoutés:', result.data.pointsAdded);
  console.log('Nouveau solde:', result.data.account.points);
}

Besoin d'aide avec l'API ?

Pour plus d'informations ou en cas de problème :