Gestion des Points de Vente (Cashpoints)

Vue d'ensemble

Cette section présente l'ensemble des endpoints dédiés à la gestion complète des points de vente (cashpoints) dans le système. Elle permet aux utilisateurs et administrateurs de gérer efficacement les points physiques où les transactions financières sont effectuées.

Fonctionnalités couvertes

Notre API de gestion des cashpoints offre une solution complète pour :

Gestion des points de vente

Création de nouveaux points de vente par les administrateurs
Mise à jour des informations existantes (coordonnées, contact, métadonnées)
Consultation et recherche géolocalisée des points disponibles
Suppression administrative des points de vente

Recherche et géolocalisation

Recherche par ville et pays
Filtrage par coordonnées géographiques (latitude, longitude)
Recherche dans un rayon défini (par défaut 2km)
Support des points mobiles et fixes

Gestion des transactions

Consultation des transactions associées à chaque point de vente
Historique détaillé des opérations effectuées
Intégration avec les sessions de paiement et plateformes

Architecture de l'API

L'API suit une architecture RESTful avec deux niveaux d'accès :

Endpoints utilisateur (/api/v1/cashpoint) : consultation et mise à jour des points de vente
Endpoints administrateur (/api/v1/admin/cashpoint) : création, consultation détaillée et suppression

Chaque point de vente est identifié par un slug unique et contient des informations complètes : coordonnées géographiques, informations de contact, devise supportée et métadonnées personnalisables.ciées.

| Action | Endpoint | |---|---| | GET | /api/v1/cashpoint | | PUT | /api/v1/cashpoint | | POST | /api/v1/admin/cashpoint | | GET | /api/v1/cashpoint/transaction | | GET | /api/v1/cashpoint/by-account-slug/{slug} | | GET | /api/v1/admin/cashpoint/by-slug/{slug} | | DELETE | /api/v1/admin/cashpoint/by-slug/{slug} |

Lister les points de vente

Endpoint: GET /api/v1/cashpoint

Liste tous les points de vente disponibles.

Paramètres de la requête

city : Nom de la ville (optionnel)
country : Nom du pays (optionnel)
lat : Latitude (optionnel)
lng : Longitude (optionnel)
radius : Rayon de recherche en kilomètres (optionnel, valeur par défaut : 2)

Réponse

{
  "message": "success message",
  "body": [
    {
      "id": 0,
      "slug": "Ru3344-554432-0009944",
      "cashPointId": "234-554432-0009944",
      "name": "Cash Point Name",
      "city": "City Name",
      "address": "123 Main St, City Name",
      "email": "cashpoint@example.com",
      "country": "Country Name",
      "longitude": 0,
      "latitude": 0,
      "phone": "123-456-7890",
      "isMobile": "true",
      "currency": "CFA",
      "metaData": "Additional information",
      "notifyBy": "SMS"
    }
  ]
}

Mettre à jour un point de vente

Endpoint: PUT /api/v1/cashpoint

Met à jour les informations d'un point de vente existant.

Corps de la requête

{
  "slug": "Ru3344-554432-0009944",
  "name": "Cash Ouagadougou",
  "city": "Ouagadougou",
  "address": "123 Main St, Ouagadougou",
  "email": "cashouaga@example.com",
  "country": "Burkina Faso",
  "longitude": 0,
  "latitude": 0,
  "phone": "123-456-7890",
  "isMobile": "true",
  "currency": "CFA",
  "metaData": "Additional information",
  "notifyBy": "SMS"
}

Réponse

{
  "message": "Point de vente mis à jour avec succès",
  "body": {
    "id": 0,
    "slug": "Ru3344-554432-0009944",
    "cashPointId": "234-554432-0009944",
    "name": "Cash Ouagadougou",
    "city": "Ouagadougou",
    "address": "123 Main St, Ouagadougou",
    "email": "cashouaga@example.com",
    "country": "Burkina Faso",
    "longitude": 0,
    "latitude": 0,
    "phone": "123-456-7890",
    "isMobile": "true",
    "currency": "CFA",
    "metaData": "Additional information",
    "notifyBy": "SMS"
  }
}

Créer un point de vente

Endpoint: POST /api/v1/admin/cashpoint

Crée un nouveau point de vente.

Corps de la requête

{
  "name": "Cash Point Name",
  "city": "City Name",
  "address": "123 Main St, City Name",
  "email": "    cashpoint@example.com",
  "country": "Country Name",
  "longitude": 0,
  "latitude": 0,
  "phone": "123-456-7890",
  "isMobile": "true",
  "currency": "CFA",
  "metaData": "Additional information",
  "notifyBy": "SMS",
  "accountSlug": "334567-554432-0009944"
}

Réponse

{
  "message": "Point de vente créé avec succès",
  "body": {
    "id": 0,
    "slug": "Ru3344-554432-0009944",
    "cashPointId": "234-554432-0009944",
    "name": "Cash Point Name",
    "city": "City Name",
    "address": "123 Main St, City Name",
    "email": "    cashpoint@example.com",
    "country": "Country Name",
    "longitude": 0,
    "latitude": 0,
    "phone": "123-456-7890",
    "isMobile": "true",
    "currency": "CFA",
    "metaData": "Additional information",
    "notifyBy": "SMS"
  }
}

Lister les transactions d'un point de vente

Endpoint: GET /api/v1/cashpoint/transacton/{slug}

Récupère une transactions associées à un point de vente spécifique.

Paramètres de la requête

slug : Slug du point de vente

Réponse

{
  "message": "Transaction recuperer",
  "body": [
    {
      "transactionId": "PGDB-0095-5678-9101",
      "slug": "AO0-3344-54432-0009944",
      "inputCode": "inputCode123",
      "transactionStatus": "PENDING",
      "balanceTransferStatus": "REJECTED",
      "paymentGatewayFee": 0,
      "globalFee": 0,
      "amount": 0,
      "netAmount": 0,
      "metaData": "string",
      "cashPointDTO": {
        "id": 0,
        "slug": "PPO-3344-554432-0009944",
        "cashPointId": "234-554432-0009944",
        "name": "Cash Point Name",
        "city": "City Name",
        "address": "123 Main St, City Name",
        "email": "cashpoint@example.com",
        "country": "Country Name",
        "longitude": 0,
        "latitude": 0,
        "phone": "123-456-7890",
        "isMobile": "true",
        "currency": "CFA",
        "metaData": "Additional information",
        "notifyBy": "SMS"
      },
      "paymentSessionDTO": {
        "paymentSessionOrderSlug": "099ee-3344-554432-0009944",
        "sessionId": "343354432-0009944",
        "platformReference": "NKOOML",
        "platformSlug": "33456-44224-0009944",
        "platformName": "Platform Name",
        "userEmail": "user@example.com",
        "userPhoneNumber": "+1234567890",
      }
    }
  ]
}

Retourner un cashœpoint par slug d'un compte

Endpoint: GET /api/v1/cashpoint/by-account-slug/{slug}

Récupère les transactions associées à un point de vente spécifique par le slug du compte.

Paramètres de la requête

slug : Slug du point de vente

Réponse

{
  "message": "Transactions récupérées avec succès",
  "body": [
    {
      "transactionId": "zkj-1234-5678-9101",
      "slug": "PPO-3344-554432-0009944",
      "inputCode": "inputCode123",
      "transactionStatus": "PENDING",
      "balanceTransferStatus": "REJECTED",
      "paymentGatewayFee": 0,
      "globalFee": 0,
      "amount": 0,
      "netAmount": 0,
      "metaData": "Transaction metadata",
      "cashPointDTO": {
        "id": 0,
        "slug": "PPO-33-0009944",
        "cashPointId": "234-554432-0009944",
        "name": "Cash Point Name",
        "city": "City Name",
        "address": "123 Main St, City Name",
        "email": "cashpoint@example.com",
        "country": "Country Name",
        "longitude": 0,
        "latitude": 0,
        "phone": "123-456-7890",
        "isMobile": true,
        "currency": "CFA"
      }
    }
  ]
}

Obtenir les détails d'un point de vente par slug

Endpoint: GET /api/v1/admin/cashpoint/by-slug/{slug}

Récupère les détails d'un point de vente spécifique par admin à partir de son slug.

Paramètres de la requête

slug : Slug du point de vente

Réponse

{
  "message": "Détails du point de vente récupérés avec succès",
  "body": {
    "id": 0,
    "slug": "Ru3344-554432-0009944",
    "cashPointId": "234-554432-0009944",
    "name": "Cash Point Name",
    "city": "City Name",
    "address": "123 Main St, City Name",
    "email": "cashpoint@example.com",
    "country": "Country Name",
    "longitude": 0,
    "latitude": 0,
    "phone": "123-456-7890",
    "isMobile": "true",
    "currency": "CFA",
    "metaData": "Additional information",
    "notifyBy": "SMS"
  }
}

Supprimer un point de vente par slug

Endpoint: DELETE /api/v1/admin/cashpoint/by-slug/{slug}

Supprime un point de vente spécifique par son slug.

Paramètres de la requête

slug : Slug du point de vente

Réponse

{
  "message": "Point de vente supprimé avec succès",
  "body": {}
}

Transactions