Pular para o conteúdo principal

Orquestração de Recargas

O microsserviço de Recargas atua como o maestro entre o Gateway Financeiro (Pagar.me V5) e o Gateway OCPP de hardware.

Implementamos o padrão de Pré-Autorização com Captura Tardia (Auth and Capture), garantindo que o condutor apenas paga pelo valor da energia (kWh) efetivamente transferida para o veículo elétrico.

Iniciar Sessão de Carregamento​

Inicia o fluxo de autorização financeira. A API suporta métodos tradicionais e Wallets (Apple Pay e Google Pay) para máxima segurança (PCI-DSS).

POST /charge/start

Corpo da Requisição (StartChargeDto)
{
    "stationId": 10,
    "chargePointId": "EVSE-001",
    "connectorId": 1,
    "method": "CREDIT_CARD",
    "amount": 5000,
    "email": "condutor@empresa.com",
    "cpf": "12345678900",
    "cardToken": "tok_123456789",
    "saveCard": true,
    "charger": {
      "price": 1.50,
      "fixed_connection_cost": 2.00
    }
  }

Detalhes do Payload​

  • chargePointId: Identificador único do equipamento (ex: EVSE-001).
  • method: PIX, CREDIT_CARD, WALLET, VIP, GOOGLE_PAY ou APPLE_PAY.
  • amount: Valor da pré-autorização em centavos (ex: 5000 = R$ 50,00).
  • networkToken: Payload criptografado retornado pela Apple Pay / Google Pay.
Resposta de Sucesso (200 OK)
{
    "success": true,
    "sessionId": "abc123xyz-firestore-id",
    "paymentData": {
      "orderId": "or_12345",
      "chargeId": "ch_12345",
      "status": "pending",
      "pixQrCode": null,
      "pixExpiresAt": null
    }
  }

Parar Sessão de Carregamento​

Se o carregamento estiver em curso (CHARGING), o comando é roteado para o hardware via OCPP. Se estiver na pré-autorização, a ordem financeira é cancelada imediatamente (Void).

POST /charge/stop

Corpo da Requisição
{
    "sessionId": "abc123xyz-firestore-id"
  }

Fluxo Financeiro Assíncrono​

A arquitetura garante precisão financeira através de rotinas geridas pelo BullMQ:

  1. Captura Dinâmica: No fim da recarga, se o consumo for inferior à pré-autorização, solicita-se captura parcial.
  2. Refunds Queue: Em caso de erro, efetua tentativas progressivas para garantir o estorno.
  3. Receipts Queue: Gera e envia o recibo fiscal detalhado por e-mail.