Aller au contenu principal

Orchestration des Recharges

Le microservice de Recharges agit comme le chef d'orchestre entre la Passerelle Financière (Pagar.me V5) et la Passerelle matérielle OCPP. Nous avons implémenté le modèle de Pré-autorisation avec Capture Tardive (Auth and Capture), garantissant que le conducteur ne paie que pour la valeur de l'énergie (kWh) effectivement transférée au véhicule électrique.

Démarrer la Session de Charge​

Initie le flux d'autorisation financière. L'API prend en charge les méthodes traditionnelles et les Wallets (Apple Pay et Google Pay) pour une sécurité maximale (PCI-DSS).

POST /charge/start

Corps de la Requête (StartChargeDto)
{
  "stationId": 10,
  "chargePointId": "EVSE-001",
  "connectorId": 1,
  "method": "CREDIT_CARD",
  "amount": 5000,
  "email": "conducteur@entreprise.com",
  "cpf": "12345678900",
  "cardToken": "tok_123456789",
  "saveCard": true,
  "charger": {
    "price": 1.50,
    "fixed_connection_cost": 2.00
  }
}

Détails du Payload​

  • chargePointId : Identifiant unique de l'équipement (ex : EVSE-001).
  • method : PIX, CREDIT_CARD, WALLET, VIP, GOOGLE_PAY ou APPLE_PAY.
  • amount : Montant de la pré-autorisation en centimes (ex : 5000 = R$ 50,00).
  • networkToken : Payload crypté renvoyé par Apple Pay / Google Pay.
Réponse de Succès (200 OK)
{
  "success": true,
  "sessionId": "abc123xyz-firestore-id",
  "paymentData": {
    "orderId": "or_12345",
    "chargeId": "ch_12345",
    "status": "pending",
    "pixQrCode": null,
    "pixExpiresAt": null
  }
}

Arrêter la Session de Charge​

Si la charge est en cours (CHARGING), la commande est acheminée vers le matériel via OCPP. Si elle est en pré-autorisation, l'ordre financier est annulé immédiatement (Void).

POST /charge/stop

Corps de la Requête
{
  "sessionId": "abc123xyz-firestore-id"
}

Flux Financier Asynchrone​

L'architecture garantit la précision financière grâce à des routines gérées par BullMQ :

  1. Capture Dynamique : À la fin de la recharge, si la consommation est inférieure à la pré-autorisation, une capture partielle est demandée.
  2. File d'attente des Remboursements (Refunds Queue) : En cas d'erreur, effectue des tentatives progressives pour garantir le remboursement.
  3. File d'attente des Reçus (Receipts Queue) : Génère et envoie le reçu fiscal détaillé par e-mail.