📡 Guide API - Endpoints et Intégrations

Cette page détaille tous les endpoints disponibles pour les équipes SAV, e-commerce et magasins.

🗂️ Structure générale

L'API est organisée en deux espaces principaux :

• /api/publique : Endpoints accessibles sans authentification (intégration e-commerce, consultation publique)
• /api/private : Endpoints pour les intégrations internes et l'interface web

💳 Paiements

Pour l'e-commerce : Interface de paiement

POST /api/publique/paiement/interface-paiement

Usage : Générer un lien vers l'interface de paiement pour vos clients

{
  "client": {
    "id": "CLI22222",
    "nom": "Dupont",
    "prenom": "Jean",
    "email": "jean.dupont@example.com",
    "adresse": "123 Rue de Rivoli",
    "ville": "Paris",
    "pays": "France",
    "civilite": 1,
    "telephoneMobile": 601234567,
    "clientFideliseId": 12345
  },
  "amount": 125.5,
  "currency": "EUR",
  "orderId": "CMD-2024-001234",
  "source": "ecommerce-website",
  "returnUrl": "https://monsite.com/payment-success"
}

Réponse :

{
  "redirectUrl": "https://paiement.ubsi.fr/paiement?token=abc123...",
  "message": "Interface générée avec succès"
}

💡 Cas d'usage :

• Sites e-commerce souhaitant rediriger vers l'interface UBSI
• Intégration iframe pour expérience transparente
• Génération de liens de paiement par email

---

Pour l'interface web : Création de paiement

POST /api/private/create_paiement

Usage : Créer un paiement depuis l'interface web UBSI

{
  "client": {
    "id": "CLI123",
    "nom": "Martin",
    "email": "martin@example.com"
  },
  "montant": 99.99,
  "devise": "EUR",
  "orderId": "CMD-456",
  "typePaiement": "achat",
  "moyenPaiement": {
    "type": "carte_bancaire",
    "cb": {
      "cardNumber": "4242424242424242",
      "expirationDate": "12/27",
      "cardHolderName": "Jean Martin"
    }
  },
  "occurence_credit": 0,
  "differe": null,
  "fidelise": 1,
  "savePaymentMethod": true
}

Réponse :

{
  "response": {
    "transactionId": 12345,
    "status": "accepte",
    "clientId": "CLI123",
    "message": "Paiement accepté avec succès",
    "authorizationId": "auth_abc123"
  },
  "returnUrl": "https://example.com/payment-return?orderId=CMD-456&status=accepte"
}

---

Paiements en espèces (Magasins)

POST /api/publique/paiement/create-cash-payment

Usage : Créer une demande de paiement en espèces

{
  "clientId": "CLI789",
  "montant": 150.0,
  "devise": "EUR",
  "orderId": "CMD-CASH-001",
  "magasinId": "MAG001"
}

💡 Cas d'usage :

• Bornes de paiement en magasin
• Paiement en espèces chez partenaires
• Alternative pour clients sans carte

---

Remboursements (SAV)

POST /api/publique/paiement/refund

Usage : Effectuer un remboursement

{
  "clientId": "CLI123",
  "transactionId": 12345,
  "montant": 99.99,
  "motif": "Article défectueux",
  "source": "sav"
}

---

🧾 Transactions

Consultation pour le SAV

GET /api/publique/transactions/client/:clientId

Usage : Récupérer toutes les transactions d'un client

curl "https://paiement.ubsi.fr/api/publique/transactions/client/CLI123"

Réponse :

[
  {
    "id": 12345,
    "montant": 99.99,
    "devise": "EUR",
    "status": "accepte",
    "typePaiement": "achat",
    "createdAt": "2024-11-07T10:30:00Z",
    "orderId": "CMD-456"
  }
]

GET /api/publique/transactions/:id

Usage : Consulter une transaction spécifique

GET /api/publique/transaction-status/:transactionId

Usage : Vérifier le statut en temps réel (utilisé par le système de récupération)

---

Gestion interne (API Privée)

GET /api/private/transactions

POST /api/private/transactions

GET /api/private/transactions/:id

Endpoints identiques mais pour usage interne de la plateforme.

---

💾 Moyens de paiement sauvegardés

Pour les clients fidèles

GET /api/private/clients-card/:clientId

Usage : Récupérer les cartes sauvegardées d'un client

Réponse :

[
  {
    "id": 1,
    "clientFideliseId": "CLI123",
    "type": "carte_bancaire",
    "details": {
      "last4": "4242",
      "expirationDate": "12/27",
      "cardHolderName": "Jean Martin",
      "brand": "Visa"
    }
  }
]

DELETE /api/private/clients-card/:id

Usage : Supprimer une carte sauvegardée

---

🍎 Stripe & Digital Wallets

Création d'un Payment Intent

POST /api/private/stripe/create-payment-intent

Usage : Créer un Payment Intent pour Apple Pay / Google Pay

{
  "amount": 1999,
  "currency": "EUR",
  "clientId": "CLI123",
  "orderId": "CMD-456"
}

Simulation

POST /api/publique/stripe/card-payment

Usage : Simuler un paiement par carte pour les tests

{
  "cardNumber": "4242424242424242",
  "amount": 1999,
  "currency": "EUR"
}

Cartes de test :

• ✅ Succès : 4242424242424242
• ❌ Échec : 4000000000009995

---

🔧 Intégration

Option 1 : Redirection complète

1. Appeler POST /api/publique/paiement/interface-paiement
2. Rediriger l'utilisateur vers redirectUrl
3. L'utilisateur revient sur votre returnUrl avec les paramètres

Option 2 : Iframe intégrée

<iframe
  src="https://paiement.ubsi.fr/paiement?token=abc123..."
  width="100%"
  height="600px"
  frameborder="0"
>
</iframe>

Option 3 : API directe (avancé)

1. Intégrer les composants React fournis
2. Utiliser directement POST /api/private/create_paiement
3. Gérer les états et la récupération côté client

---

⚡ Webhooks & Événements

RabbitMQ

Le système publie automatiquement des messages sur la queue paiement.expedition-commande lors de :

• Confirmation de paiement
• Changement de statut
• Remboursement effectué

Format des messages

{
  "transactionId": 12345,
  "orderId": "CMD-456",
  "status": "accepte",
  "clientId": "CLI123",
  "timestamp": "2024-11-07T10:30:00Z"
}

---

🆘 Support & Tests

Environnements

• Production : https://paiement.ubsi.fr
• Staging : https://paiement.staging.ubsi.fr

Tests recommandés

1. Paiement réussi : Utiliser la carte 4242424242424242
2. Paiement échoué : Utiliser la carte 4000000000009995
3. Interruption : Fermer le navigateur pendant un paiement, rouvrir → modal de récupération
4. Clients fidèles : Tester paiement en 3x et différé

Codes d'erreur courants

Code	Message	Solution
400	Données client invalides	Vérifier format email, téléphone
402	Paiement refusé	Utiliser une carte de test valide
404	Transaction introuvable	Vérifier l'ID de transaction
500	Erreur serveur	Contacter le support technique

---

🔐 Sécurité

• Toutes les cartes sont tokenisées via Stripe
• CVV non stocké en base
• Chiffrement des données sensibles
• Validation côté serveur de tous les montants
• Protection CSRF sur l'interface web