Cashback - Raba7ni Developer API

API Produit: Ces points de terminaison font partie de l'API Cashback. Tous les points de terminaison commencent par: /api/v1/cashback/

Gagner du Cashback

POST Gagner du Cashback

cashback_write

/api/v1/cashback/cashback/earn

Calculer et créditer le cashback à un membre basé sur un montant d'achat.

Comment ça Marche

Configurer la Carte

La carte de cashback a un pourcentage de cashback configuré (ex: 5% de retour).

Envoyer la Transaction

Envoyez card_id, member_id et le purchase_amount pour calculer le cashback.

Créditer le Solde

Le cashback est automatiquement crédité sur le solde du membre.

Corps de la Requête

{
  "card_id": 10,
  "member_id": 123,
  "purchase_amount": 50.00,
  "reference": "ORDER-12345",
  "metadata": {
    "store_location": "Downtown",
    "cashier_id": "EMP-001"
  }
}

Réponse

{
  "success": true,
  "data": {
    "transaction_id": 456,
    "purchase_amount": 50.00,
    "cashback_percentage": 5,
    "cashback_earned": 2.50,
    "new_balance": 12.50,
    "member_id": 123,
    "card_id": 10,
    "earned_at": "2025-01-15T10:30:00Z"
  }
}

Retirer du Cashback

POST Retirer du Cashback

cashback_write Authentification Membre Requise

/api/v1/cashback/cashback/redeem

Retirer du cashback du solde du membre pour une réduction ou un remboursement.

Authentification Requise: Ce point de terminaison nécessite l'en-tête X-Member-Token pour protéger les fonds du membre.

Étape par Étape

Authentifier le Membre

Le membre doit être authentifié via OTP avec X-Member-Token.

Vérifier le Solde

Le système vérifie que le membre a suffisamment de cashback disponible.

Traiter le Retrait

Le montant est débité du solde de cashback du membre.

En-têtes

X-App-Id: app_abc123...
X-Api-Key: test_xyz789...
X-Member-Token: eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json

Corps de la Requête

{
  "card_id": 10,
  "amount": 5.00,
  "pin": "1234",
  "reference": "REFUND-ORDER-12345"
}

card_id (entier, requis) - ID de la carte de cashback
amount (nombre, requis) - Montant à retirer
pin (chaîne, optionnel) - PIN pour vérification supplémentaire
reference (chaîne, optionnel) - Référence de transaction personnalisée

Réponse

{
  "success": true,
  "data": {
    "transaction_id": 457,
    "amount_redeemed": 5.00,
    "new_balance": 7.50,
    "member_id": 123,
    "card_id": 10,
    "redeemed_at": "2025-01-15T11:00:00Z"
  }
}

Obtenir le Solde de Cashback

GET Obtenir le Solde

cashback_read

/api/v1/cashback/cashback/balance

Récupérer le solde de cashback actuel d'un membre sur une carte spécifique.

Paramètres de Requête

GET /api/v1/cashback/cashback/balance?card_id=10&member_id=123

card_id (entier, requis) - ID de la carte de cashback
member_id (entier, requis) - ID du membre

Réponse

{
  "success": true,
  "data": {
    "card_id": 10,
    "member_id": 123,
    "cashback_balance": 12.50,
    "cashback_percentage": 5,
    "reward_system": "cashback",
    "queried_at": "2025-01-15T10:30:00Z"
  }
}

Historique des Transactions

GET Historique

cashback_read

/api/v1/cashback/cashback/history

Récupérer l'historique des transactions de cashback d'un membre avec pagination.

Paramètres de Requête

GET /api/v1/cashback/cashback/history?card_id=10&member_id=123&limit=20&offset=0

Réponse

{
  "success": true,
  "data": {
    "card_id": 10,
    "member_id": 123,
    "transactions": [
      {
        "id": 456,
        "type": "earning",
        "amount": 2.50,
        "points": 0,
        "event": "cashback_earned",
        "created_at": "2025-01-15T10:30:00Z"
      },
      {
        "id": 457,
        "type": "redemption",
        "amount": -5.00,
        "points": 0,
        "event": "cashback_redeemed",
        "created_at": "2025-01-15T11:00:00Z"
      }
    ],
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 45,
      "has_more": true
    }
  }
}

Rembourser du Cashback

POST Rembourser du Cashback

cashback_write

/api/v1/cashback/cashback/refund

Annuler/déduire du cashback précédemment gagné lors d'un remboursement de commande.

Note: Le système calculera automatiquement le cashback à déduire basé sur le montant remboursé, ou vous pouvez spécifier un montant explicite.

Corps de la Requête

{
  "card_id": 10,
  "member_id": 123,
  "refund_amount": 25.00,
  "reference": "REFUND-ORDER-12345"
}

card_id (entier, requis) - ID de la carte de cashback
member_id (entier, conditionnel) - ID du membre
email (chaîne, conditionnel) - Email du membre (alternative à member_id)
phone (chaîne, conditionnel) - Téléphone du membre (alternative à member_id)
refund_amount (nombre, requis) - Montant remboursé
cashback_to_deduct (nombre, optionnel) - Cashback explicite à déduire
reference (chaîne, optionnel) - Référence de transaction

Réponse

{
  "success": true,
  "data": {
    "transaction_id": 459,
    "cashback_deducted": 1.25,
    "refund_amount": 25.00,
    "previous_balance": 12.50,
    "new_balance": 11.25,
    "currency": "TND",
    "member_id": 123,
    "card_id": 10,
    "reference": "REFUND-ORDER-12345",
    "balance_warning": null,
    "refunded_at": "2025-01-15T12:00:00Z"
  }
}

Cartes de Cashback

Les points de terminaison de cartes permettent de lister et de récupérer des détails sur les cartes de cashback disponibles.

GET Lister les Cartes

card_read

/api/v1/cashback/cards

Lister toutes les cartes de cashback disponibles pour votre application.

Réponse

{
  "success": true,
  "data": {
    "cards": [
      {
        "id": 10,
        "unique_identifier": "CASH-001",
        "name": "Carte Cashback Premium",
        "description": "5% de cashback sur tous les achats",
        "reward_system": "cashback",
        "cashback_config": {
          "cashback_percentage": 5.0,
          "cashback_min_amount": 10.0,
          "cashback_max_amount": 1000.0,
          "allows_pin_redemption": true
        }
      }
    ],
    "total": 1
  }
}