openapi: 3.1.0
info:
  title: Evolve Energy Documentation
  version: v1
servers:
- url: /
paths:
  /api/v1/charging-station/update-transaction:
    post:
      tags:
      - OCPP Broker
      summary: Inform about the transaction updates
      description: Called by the OCPP Broker once a charging transaction has been
        started, to inform the Evolve backend of the assigned transaction ID.
      operationId: updateTransaction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTransactionRequest'
        required: true
      responses:
        '200':
          description: Transaction updated successfully
          content: {}
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error
  /api/v1/charging-station/stop-transaction:
    post:
      tags:
      - OCPP Broker
      summary: Provide the consumption data of a completed charging session
      description: Called by the OCPP Broker when charging has finished. Sends detailed
        transaction data to the Evolve backend for processing and CDR creation.
      operationId: stopTransaction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StopTransactionRequest'
        required: true
      responses:
        '200':
          description: Stop transaction acknowledged
          content: {}
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error
  /api/v1/charging-station/status:
    post:
      tags:
      - OCPP Broker
      summary: Send charge point status update
      description: Called by the OCPP Broker to send the latest operational status
        and error information of a charge point or connector to the Evolve backend.
      operationId: updateStatus
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusUpdateRequest'
        required: true
      responses:
        '200':
          description: Status update acknowledged
          content: {}
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error
  /api/v1/charging-station/configuration-update:
    post:
      tags:
      - OCPP Broker
      summary: Send charging station configuration details
      description: Called by the OCPP Broker to send the latest configuration status
        of a charging station to the Evolve backend so that Evolve can pair it with
        the digital twin.
      operationId: updateConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigurationUpdateRequest'
        required: true
      responses:
        '200':
          description: Chargepoint configuration update acknowledged
          content: {}
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error
  /api/v1/charging-station/authorize-transaction:
    post:
      tags:
      - OCPP Broker
      summary: Authorize a charging session request at a station
      description: Called by the OCPP Broker when a user wants to start a charging
        session. The Evolve backend decides whether charging is allowed and, if approved,
        returns the mapped token from the CPMS.
      operationId: authorizeTransaction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeTransactionRequest'
        required: true
      responses:
        '200':
          description: Start transaction decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeTransactionResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error
components:
  schemas:
    UpdateTransactionRequest:
      type: object
      description: Request body for informing about transaction updates.
      properties:
        stationId:
          type: string
          description: Unique identifier of the charging station
          example: CS-1001
        connectorId:
          type: integer
          format: int32
          description: The connector number used for the transaction.
          example: 1
        idToken:
          type: string
          description: The token used to authenticate the transaction.
          example: DF8A4C8931
        sessionStartTimestamp:
          type: string
          format: date-time
          description: Charging session start time in ISO 8601 UTC
          example: '2025-08-08T14:25:27Z'
        transactionId:
          type: string
          description: The unique identifier for the transaction.
          example: 1753911353
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the update in UTC
          example: '2025-08-08T14:25:27Z'
      required:
      - connectorId
      - idToken
      - sessionStartTimestamp
      - stationId
      - timestamp
      - transactionId
    StopTransactionRequest:
      type: object
      description: Request body for providing consumption data of a completed charging
        session.
      properties:
        stationId:
          type: string
          description: Unique identifier of the charging station
          example: CS-1001
        connectorId:
          type: integer
          format: int32
          description: The connector number at which the session took place.
          example: 1
        idToken:
          type: string
          description: The token used to authenticate the transaction.
          example: DF8A4C8931
        transactionId:
          type: string
          description: The unique identifier for the transaction.
          example: 1753911353
        sessionStartTimestamp:
          type: string
          format: date-time
          description: Charging session start time in ISO 8601 UTC
          example: '2025-08-08T14:25:27Z'
        sessionEndTimestamp:
          type: string
          format: date-time
          description: Charging session end time in ISO 8601 UTC
          example: '2025-08-08T15:40:12Z'
        meterStartWh:
          type: integer
          format: int32
          description: Meter value in Wh at the beginning of the transaction.
          example: 12
          minimum: 0
        meterStopWh:
          type: integer
          format: int32
          description: Energy meter value in Wh at the end of the transaction.
          example: 15
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the record was created at the broker
          example: '2025-08-08T14:25:27Z'
        stopReason:
          type: string
          description: Reason for stopping the transaction
          enum:
          - EVDisconnected
          - HardReset
          - Local
          - PowerLoss
          - Reboot
          - Remote
          - SoftReset
          - UnlockCommand
          - DeAuthorized
          example: EVDisconnected
      required:
      - connectorId
      - idToken
      - meterStartWh
      - meterStopWh
      - sessionEndTimestamp
      - sessionStartTimestamp
      - stationId
      - timestamp
      - transactionId
    StatusUpdateRequest:
      type: object
      description: Request body for sending a charge point status update.
      properties:
        stationId:
          type: string
          description: Unique identifier of the charging station
          example: CS-1001
        connectorId:
          type: integer
          format: int32
          description: If 0, represents the status of the charge point. Otherwise,
            the status of a specific connector.
          example: 2
        errorCode:
          type: string
          description: OCPP standard error code
          enum:
          - NoError
          - ConnectorLockFailure
          - EVCommunicationError
          - GroundFailure
          - HighTemperature
          - InternalError
          - LocalListConflict
          - OverCurrentFailure
          - PowerMeterFailure
          - PowerSwitchFailure
          - ReaderFailure
          - ResetFailure
          - UnderVoltage
          - OverVoltage
          - WeakSignal
          example: NoError
        status:
          type: string
          description: OCPP standard ChargePointStatus
          enum:
          - Available
          - Preparing
          - Charging
          - SuspendedEV
          - SuspendedEVSE
          - Finishing
          - Reserved
          - Unavailable
          - Faulted
          example: Charging
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the status update in UTC
          example: '2025-08-08T14:25:27Z'
      required:
      - connectorId
      - stationId
      - status
      - timestamp
    ConfigurationUpdateRequest:
      type: object
      description: Request body for sending charging station configuration details.
      properties:
        stationId:
          type: string
          description: Unique identifier of the charging station
          example: CS-1001
        manufacturer:
          type: string
          description: Manufacturer of the charging station
          example: Alfen BV
        model:
          type: string
          description: Model of the charging station
          example: NG920-61101
        serialNumber:
          type: string
          description: Serial number of the charging station
          example: ACE0474341
        firmwareVersion:
          type: string
          description: Firmware version of the charging station
          example: 6.6.2-4312
        numberOfConnectors:
          type: integer
          format: int32
          description: Number of connectors on the charging station
          example: 2
        supportedFeatureProfiles:
          type: string
          description: Supported feature profiles
          enum:
          - Core
          - FirmwareManagement
          - Reservation
          - LocalAuthListManagement
          - RemoteTrigger
          example: Core
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the configuration update in UTC
          example: '2025-08-08T14:25:27Z'
      required:
      - stationId
      - timestamp
    AuthorizeTransactionRequest:
      type: object
      description: Request body for authorizing a charging session.
      properties:
        stationId:
          type: string
          description: Unique identifier of the charging station
          example: TACW1144322G1740
        connectorId:
          type: integer
          format: int32
          description: (Optional) The connector number at which the user is authenticating
            (1-indexed).
          example: 1
        idToken:
          type: string
          description: The token (RFID card's UID) used to authenticate a charging
            transaction.
          example: DF8A4C8931
        timestamp:
          type: string
          format: date-time
          description: Timestamp in UTC
          example: '2025-08-08T14:25:27Z'
      required:
      - idToken
      - stationId
      - timestamp
    AuthorizeTransactionResponse:
      type: object
      description: Response to an authorize transaction request.
      properties:
        status:
          type: string
          description: The authorization status.
          enum:
          - APPROVED
          - BLOCKED
          - UNKNOWN
          example: APPROVED
        mappedToken:
          type: string
          description: The mapped token to be used by the broker for authorization
            with the CPMS. Only provided if status is APPROVED.
          example: DEPOTCHARGE_MASTERCARD
      required:
      - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
