openapi: 3.0.3
info:
  title: Epic-Charging Server Application Report API
  description: >

    # Epic-Charging API


    Welcome to the Epic-Charging API documentation. This API gives you full
    control over your EV charging infrastructure, allowing you to manage
    chargers, monitor sessions, and generate reports.


    ## Getting Started


    To use the Epic-Charging API, you'll need:

    - An API Key (see the Authentication section)

    - A basic understanding of the resources available through the API


    ## Base URL


    All API URLs referenced in this documentation are relative to:

    ```

    https://{{tenant}}.epiccharging.com/api/external/v1/

    ```


    ## Authentication


    The Epic-Charging API uses API keys for authentication. Include your API key
    in all requests using the `Token-Authorization` header:


    ```bash

    curl -X GET https://{{tenant}}.epiccharging.com/api/external/v1/charger/ \
      -H "Token-Authorization: your_api_key_here"
    ```


    Your API key carries privileges, so keep it secure. Do not share it in
    publicly accessible areas such as GitHub, client-side code, or public
    forums.


    ## Rate Limiting


    API requests may be subject to rate limiting. If you exceed the rate limit,
    the API will respond with a `429 Too Many Requests` status code.


    ## Error Responses


    The API uses standard HTTP response codes to indicate success or failure:

    - 2xx: Success

    - 4xx: Client errors (invalid request, unauthorized, etc.)

    - 5xx: Server errors


    Error responses include a JSON body with details about the error.
  version: v1
servers:
  - url: https://{tenant}.epiccharging.com/api/external/v1
    description: Server
    variables:
      tenant:
        default: demo
        enum:
          - demo
          - gsspower
          - anothercustomer
tags:
  - name: Charger Port
    description: >
      Charger Ports represent the individual connector points where vehicles can
      be connected for charging.


      Use these endpoints to:

      - List all available charger ports across your network

      - Get detailed information about specific ports

      - Update port settings and configurations

      - Reserve ports for future use

      - Start and stop charging sessions

      - Cancel reservations


      Each charger port belongs to a parent charger and can have different
      connector types (J1772, CCS, CHADEMO, etc.)

      and power capacities. Ports also maintain status information about current
      charging activities.
  - name: Charger
    description: >
      Chargers are the physical stations containing one or more charging ports.


      These endpoints allow you to:

      - List all chargers in your network with their current statuses

      - Get detailed information about specific chargers

      - View power, connectivity, and location information

      - See all ports associated with a charger


      Chargers contain important metadata about locations, payment types, power
      capabilities, 

      and operating temperatures. A single charger typically houses multiple
      charging ports.
  - name: Report
    description: >
      The reporting API provides comprehensive data and metrics about your
      charging network.


      Use these endpoints to:

      - Get real-time status information for all chargers

      - Generate comprehensive charger reports

      - View detailed charging session history

      - Analyze fault data and error conditions

      - Track energy usage and transactions


      These endpoints support filtering by date ranges, chargers, and other
      parameters to help

      you generate specific reports for business intelligence, maintenance
      planning, and usage analytics.
  - name: User
    description: >
      The User API allows you to manage and retrieve information about system
      users.


      These endpoints enable you to:

      - List all users with access to your charging network

      - View user details including attached ID tags and accessible chargers

      - See authorization levels and access rights


      User management is essential for controlling access to chargers and
      tracking

      usage patterns across your charging infrastructure.
security:
  - BearerAuth: []
paths:
  /charger-port/:
    get:
      operationId: charger-port_list
      summary: List Charger Ports
      description: >
        Retrieves a list of all charger ports with their current status and
        connector information.


        This endpoint supports filtering by parameters like status and charger.


        ## Permissions


        Requires a valid API key with read permissions for charger ports.
      parameters:
        - name: charger__payment_type
          in: query
          description: Filter by payment type (Paid or Free)
          required: false
          schema:
            type: string
            enum:
              - Paid
              - Free
        - name: charger
          in: query
          description: Filter by specific charger UUID
          required: false
          schema:
            type: string
        - name: status__in
          in: query
          description: Filter by charger port status (comma-separated list)
          required: false
          schema:
            type: string
            enum:
              - DISABLED
              - AVAILABLE
              - STANDBY
              - CHARGING
              - OFFLINE
              - FAULTED
              - RESERVED
              - UNAVAILABLE
              - UNDEFINED
              - NOT_CHARGING
              - COMPLETE
              - ASLEEP
              - STARTING
              - STOPPING
              - WAITING_CHARGER
              - WAITING_VEHICLE
              - IN_PROGRESS
              - FAILED_START
              - FAILED_STOP
              - NO_SESSION
              - PREPARING
              - SUSPENDED_EV
              - SUSPENDED_EVSE
              - UNPLUGGED
              - UNPLUGGED_NOT_CHARGING
              - UNPLUGGED_CHARGING
              - PLUGGED_IN_NOT_CHARGING
              - PLUGGED_IN_SUSPENDED_EV
              - PLUGGED_IN_CHARGING
              - CHARGING_COMPLETE
              - CUSTOM_CHARGER
              - CUSTOM_VEHICLE
              - FINISHING
        - name: location__in
          in: query
          description: Filter by location (comma-separated list)
          required: false
          schema:
            type: string
        - name: ordering
          in: query
          description: Field to order results by (prefix with - for descending order)
          required: false
          schema:
            type: string
            enum:
              - created_at
              - '-created_at'
              - custom_id
              - '-custom_id'
              - status
              - '-status'
              - parking_lot
              - '-parking_lot'
              - temperature
              - '-temperature'
              - max_power
              - '-max_power'
              - current_kilowatt_hour
              - '-current_kilowatt_hour'
              - start_charging_at
              - '-start_charging_at'
              - end_charging_at
              - '-end_charging_at'
              - charger_point_id
              - '-charger_point_id'
              - location_name
              - '-location_name'
        - name: search
          in: query
          description: A search term.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The initial index from which to return the results.
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - results
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChargerPortList'
              example:
                count: 2
                next: null
                previous: null
                results:
                  - id: 123e4567-e89b-12d3-a456-426614174000
                    max_power: 22
                    charging_speed: 11
                    power: 11
                    connector_type: J1772
                    status:
                      key: AVAILABLE
                      value: Available
                    charger: 223e4567-e89b-12d3-a456-426614174003
      tags:
        - Charger Port
  /charger-port/{id}/:
    parameters:
      - name: id
        in: path
        description: A UUID string identifying this Charger Port.
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: charger-port_read
      summary: Get Charger Port Details
      description: >-
        Gets detailed information about a specific charger port by ID, including
        connector specifications and active session details. Requires a valid
        API key.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargerPort'
      tags:
        - Charger Port
    patch:
      operationId: charger-port_partial_update
      summary: Update Charger Port
      description: >-
        Updates specific fields of a charger port, such as status or
        configuration settings. Requires a valid API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargerPortUpdate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargerPortUpdate'
      tags:
        - Charger Port
  /charger-port/{id}/cancel_reservation/:
    parameters:
      - name: id
        in: path
        description: A UUID string identifying this Charger Port.
        required: true
        schema:
          type: string
          format: uuid
    patch:
      operationId: charger-port_cancel_reservation
      summary: Cancel Reservation
      description: >-
        Cancels the reservation for charger port. The reservation_id must be
        provided.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reservation_id
              properties:
                reservation_id:
                  type: integer
                  description: Reservation identifier.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
      tags:
        - Charger Port
  /charger-port/{id}/reserve_now/:
    parameters:
      - name: id
        in: path
        description: A UUID string identifying this Charger Port.
        required: true
        schema:
          type: string
          format: uuid
    patch:
      operationId: charger-port_reserve_now
      summary: Reserve Charger Port
      description: >-
        Reserves a charger port. The fields expiry_date_time, id_tag, and
        reservation_id must be included in the request body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - expiry_date_time
                - id_tag
                - reservation_id
              properties:
                expiry_date_time:
                  type: string
                  format: date-time
                  description: Reservation expiry time in UTC format.
                id_tag:
                  type: string
                  description: Identification tag.
                parent_id_tag:
                  type: string
                  description: Parent Identification tag.
                  default: SYS00TEM
                reservation_id:
                  type: integer
                  description: Reservation ID.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
      tags:
        - Charger Port
  /charger-port/{id}/start/:
    parameters:
      - name: id
        in: path
        description: A UUID string identifying this Charger Port.
        required: true
        schema:
          type: string
          format: uuid
    patch:
      operationId: charger-port_start
      summary: Start Charging
      description: Start a charger port to begin charging.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
      tags:
        - Charger Port
  /charger-port/{id}/stop/:
    parameters:
      - name: id
        in: path
        description: A UUID string identifying this Charger Port.
        required: true
        schema:
          type: string
          format: uuid
    patch:
      operationId: charger-port_stop
      summary: Stop Charging
      description: Stop a charger port to end charging.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
      tags:
        - Charger Port
  /charger/:
    get:
      operationId: charger_list
      summary: List Chargers
      description: >-
        Retrieves a list of all available chargers with their current status and
        locations. Requires a valid API key.
      parameters:
        - name: created_at
          in: query
          description: Filter by creation date
          required: false
          schema:
            type: string
        - name: is_active
          in: query
          description: Filter by active status
          required: false
          schema:
            type: string
        - name: location
          in: query
          description: Filter by location
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Filter by charger status
          required: false
          schema:
            type: string
            enum:
              - DISABLED
              - AVAILABLE
              - STANDBY
              - CHARGING
              - OFFLINE
              - FAULTED
              - RESERVED
              - UNAVAILABLE
        - name: number_phases
          in: query
          description: Filter by number of phases
          required: false
          schema:
            type: string
            enum:
              - '1'
              - '3'
        - name: current_type
          in: query
          description: Filter by current type
          required: false
          schema:
            type: string
            enum:
              - AC
              - DC
              - NACS
        - name: limit
          in: query
          description: Number of results to return per page
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The initial index from which to return the results
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - results
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChargerList'
      tags:
        - Charger
  /charger/{id}/:
    parameters:
      - name: id
        in: path
        description: A UUID string identifying this Charger.
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: charger_read
      summary: Get Charger Details
      description: >-
        Gets detailed information about a specific charger by ID, including
        technical specifications and current operational status. Requires a
        valid API key.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargerRetrieve'
      tags:
        - Charger
  /report/charger-status/:
    get:
      operationId: report_charger-status_list
      summary: List Charger Statuses
      description: >-
        Retrieves the current operational status of all chargers with detailed
        port information. Includes counts of chargers in each status category.
      parameters:
        - name: charger
          in: query
          description: Filter by charger UUID
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of results to return per page
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The initial index from which to return the results
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - results
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExternalAPIReportChargerStatus'
      tags:
        - Report
  /report/charger-status/{id}/:
    parameters:
      - name: id
        in: path
        description: A UUID string identifying this Charger.
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: report_charger-status_read
      summary: Get Charger Status
      description: >-
        Gets the current operational status of a specific charger by ID,
        including charger health and detailed port information.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAPIReportChargerStatus'
      tags:
        - Report
  /report/charger/:
    get:
      operationId: report_charger_list
      summary: List Charger Reports
      description: >-
        Generates a comprehensive report of all chargers with detailed
        information including location, owner, commission date, and total power
        usage. Supports pagination with a default limit of 100 records.
      parameters:
        - name: limit
          in: query
          description: Number of results to return per page
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The initial index from which to return the results
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - results
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportCharger'
      tags:
        - Report
  /report/charging-session/:
    get:
      operationId: report_charging-session_list
      summary: List Charging Sessions
      description: >-
        Provides a detailed report of all completed charging sessions including
        timestamps, energy delivered, and associated costs. Supports filtering
        by date ranges and pagination.
      parameters:
        - name: plug_in_start_datetime__gte
          in: query
          description: Filter by plug-in start time (minimum)
          required: false
          schema:
            type: string
        - name: plug_in_start_datetime__lte
          in: query
          description: Filter by plug-in start time (maximum)
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of results to return per page
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The initial index from which to return the results
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - results
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportChargingSession'
      tags:
        - Report
  /report/faults/:
    get:
      operationId: report_faults_list
      summary: List Faults
      description: >-
        Lists all system fault events with detailed error information,
        categorized by charger. Supports filtering by charger ID and date range,
        with pagination.
      parameters:
        - name: created_at__range
          in: query
          description: Filter by creation date range
          required: false
          schema:
            type: string
        - name: created_at__gte
          in: query
          description: Filter by creation date (minimum)
          required: false
          schema:
            type: string
        - name: created_at__lte
          in: query
          description: Filter by creation date (maximum)
          required: false
          schema:
            type: string
        - name: charger
          in: query
          description: Filter by charger UUID
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of results to return per page
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The initial index from which to return the results
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - results
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportFaults'
      tags:
        - Report
  /report/transaction/:
    get:
      operationId: report_transaction_list
      summary: List Transactions
      description: >-
        Generates a transaction report with detailed charging session
        information including timestamps, energy usage, and charging duration.
        Supports filtering by charger, date range, and timestamps.
      parameters:
        - name: start_datetime__gte
          in: query
          description: Filter by start date (minimum)
          required: false
          schema:
            type: string
        - name: start_datetime__lte
          in: query
          description: Filter by start date (maximum)
          required: false
          schema:
            type: string
        - name: stop_datetime__gte
          in: query
          description: Filter by stop date (minimum)
          required: false
          schema:
            type: string
        - name: stop_datetime__lte
          in: query
          description: Filter by stop date (maximum)
          required: false
          schema:
            type: string
        - name: charger__in
          in: query
          description: Filter by charger UUID (comma-separated list)
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of results to return per page
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The initial index from which to return the results
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - results
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportTransaction'
      tags:
        - Report
  /user/:
    get:
      operationId: user_list
      summary: List Users
      description: >-
        Retrieves a list of users with their attached ID tags and chargers. Only
        accessible with a valid API key.
      parameters:
        - name: limit
          in: query
          description: Number of results to return per page
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The initial index from which to return the results
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - results
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExternalAPIUser'
      tags:
        - User
  /user/{uuid}/:
    parameters:
      - name: uuid
        in: path
        description: UUID of the user
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: user_read
      summary: Get User Details
      description: >-
        Gets detailed information about a specific user by UUID, including
        personal information, attached ID tags and assigned chargers. Requires a
        valid API key.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAPIUser'
      tags:
        - User
components:
  securitySchemes:
    BearerAuth:
      type: apiKey
      name: Token-Authorization
      in: header
      description: API key must be provided in the Token-Authorization header
  schemas:
    ParkingLotLookup:
      type: object
      required:
        - value
      properties:
        id:
          type: integer
          readOnly: true
          description: Unique identifier for the parking lot
        value:
          type: string
          minLength: 1
          description: Name or identifier of the parking lot
    ChargingScheduleManyGet:
      type: object
      required:
        - weekday
        - start_at
        - end_at
      properties:
        id:
          type: integer
          readOnly: true
          description: Unique identifier for the charging schedule
        weekday:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
          description: Day of the week (0 = Sunday, 6 = Saturday)
        start_at:
          type: string
          description: Time when charging starts (format HH:MM)
        end_at:
          type: string
          description: Time when charging ends (format HH:MM)
        timezone:
          type: string
          description: Timezone for the schedule
    ChargerPortList:
      type: object
      required:
        - max_power
        - power
        - charger
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the charger port
        max_power:
          type: number
          description: Maximum power output in kW
        charging_speed:
          type: number
          readOnly: true
          description: Current charging speed
        custom_id:
          type: string
          readOnly: true
          description: Custom identifier for the port
        power:
          type: number
          nullable: true
          description: Current power output
        manufacturer:
          type: object
          readOnly: true
          properties:
            custom_id:
              type: string
              description: Manufacturer custom ID
            value:
              type: string
              description: Manufacturer name
        model:
          type: object
          readOnly: true
          properties:
            custom_id:
              type: string
              description: Model custom ID
            value:
              type: string
              description: Model name
            port_count:
              type: integer
              description: Number of ports on this model
        status:
          type: object
          readOnly: true
          properties:
            key:
              type: string
              description: Status code
            value:
              type: string
              description: Human-readable status
        parking_lot:
          $ref: '#/components/schemas/ParkingLotLookup'
        connector_type:
          type: string
          enum:
            - J1772
            - CCS
            - CHADEMO
            - NACS
            - SHUKO
            - TYPE_2
          description: Type of connector
        current_ampere:
          type: number
          description: Current in amperes
        current_kilowatt_hour:
          type: number
          description: Current in kilowatt-hours
        start_charging_at:
          type: string
          format: date-time
          nullable: true
          description: When charging started
        end_charging_at:
          type: string
          format: date-time
          nullable: true
          description: When charging ended
        charger:
          type: string
          format: uuid
          nullable: true
          description: Associated charger UUID
    ChargerPort:
      type: object
      required:
        - max_power
        - power
        - charger
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the charger port
        max_power:
          type: number
          description: Maximum power output in kW
        charging_speed:
          type: number
          readOnly: true
          description: Current charging speed
        custom_id:
          type: string
          readOnly: true
          description: Custom identifier for the port
        power:
          type: number
          nullable: true
          description: Current power output
        manufacturer:
          type: object
          readOnly: true
          properties:
            custom_id:
              type: string
            value:
              type: string
        model:
          type: object
          readOnly: true
          properties:
            custom_id:
              type: string
            value:
              type: string
            port_count:
              type: integer
        status:
          type: object
          readOnly: true
          properties:
            key:
              type: string
            value:
              type: string
        parking_lot:
          $ref: '#/components/schemas/ParkingLotLookup'
        connector_type:
          type: string
          enum:
            - J1772
            - CCS
            - CHADEMO
            - NACS
            - SHUKO
            - TYPE_2
        charger:
          type: string
          format: uuid
          nullable: true
          description: Associated charger UUID
    ChargerPortUpdate:
      type: object
      required:
        - charging_speed
        - max_power
      properties:
        charging_speed:
          type: number
          description: Charging speed to set
        custom_id:
          type: string
          maxLength: 255
          nullable: true
          description: Custom identifier for the port
        max_power:
          type: number
          description: Maximum power output
        is_deleted:
          type: boolean
          description: Whether the port is deleted
    ChargerChargerPort:
      type: object
      required:
        - max_power
        - charge_current_kilowatt_hour
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the port
        connector_id:
          type: integer
          nullable: true
          description: Connector ID for OCPP
        status:
          type: object
          readOnly: true
          properties:
            key:
              type: string
            value:
              type: string
        max_power:
          type: number
          description: Maximum power output
        charge_current_kilowatt_hour:
          type: number
          nullable: true
          description: Current charge rate in kWh
        charging_start_at:
          type: string
          format: date-time
          description: When charging started
    ChargerList:
      type: object
      required:
        - location_name
        - customer_qr_code
        - ports
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the charger
        custom_id:
          type: string
          maxLength: 255
          nullable: true
          description: Custom identifier for the charger
        charger_point_id:
          type: string
          maxLength: 255
          description: Charger point identifier
        status:
          type: object
          readOnly: true
          properties:
            key:
              type: string
            value:
              type: string
        location_name:
          type: string
          minLength: 1
          nullable: true
          description: Name of the location where charger is installed
        temperature:
          type: number
          description: Current temperature of the charger
        payment_type:
          type: string
          enum:
            - Paid
            - Free
          description: Whether charging is paid or free
        id_tag_required:
          type: boolean
          description: Whether ID tag is required to use this charger
        customer_qr_code:
          type: string
          minLength: 1
          nullable: true
          description: QR code for customer access
        ports:
          type: array
          items:
            $ref: '#/components/schemas/ChargerChargerPort'
          description: List of ports on this charger
        charger_group:
          type: string
          format: uuid
          nullable: true
          description: Group this charger belongs to
    ChargerChargerPortRetrieve:
      type: object
      required:
        - max_power
        - charging_speed
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the port
        connector_id:
          type: integer
          nullable: true
          description: Connector ID for OCPP
        max_power:
          type: number
          description: Maximum power output
        power:
          type: number
          description: Current power output
        max_current:
          type: string
          readOnly: true
          description: Maximum current
        current:
          type: string
          readOnly: true
          description: Current output
        charging_speed:
          type: number
          description: Current charging speed
        connector_type:
          type: object
          readOnly: true
          properties:
            key:
              type: string
            value:
              type: string
          description: Type of connector
        charging_start_at:
          type: string
          format: date-time
          description: When charging started
    ChargerRetrieve:
      type: object
      required:
        - location_name
        - customer_qr_code
        - ports
        - location_id
        - rfid_required
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the charger
        custom_id:
          type: string
          maxLength: 255
          nullable: true
          description: Custom identifier for the charger
        charger_point_id:
          type: string
          maxLength: 255
          description: Charger point identifier
        status:
          type: object
          readOnly: true
          properties:
            key:
              type: string
            value:
              type: string
          description: Current status of the charger
        location_name:
          type: string
          minLength: 1
          nullable: true
          description: Name of the location
        temperature:
          type: number
          description: Current temperature of the charger
        payment_type:
          type: string
          enum:
            - Paid
            - Free
          description: Whether charging is paid or free
        customer_qr_code:
          type: string
          minLength: 1
          nullable: true
          description: QR code for customer access
        ports:
          type: array
          items:
            $ref: '#/components/schemas/ChargerChargerPortRetrieve'
          description: List of ports on this charger
        manufacturer:
          type: object
          readOnly: true
          properties:
            custom_id:
              type: string
            value:
              type: string
          description: Manufacturer information
        model:
          type: object
          readOnly: true
          properties:
            custom_id:
              type: string
            value:
              type: string
            port_count:
              type: integer
          description: Model information
        location_id:
          type: string
          format: uuid
          nullable: true
          description: Location identifier
        location_coordinates:
          type: array
          readOnly: true
          items:
            type: number
          format: double
          description: Geographic coordinates of the location
        rfid_required:
          type: boolean
          nullable: true
          description: Whether RFID is required to use this charger
        number_phases:
          type: integer
          enum:
            - 1
            - 3
          description: Number of electrical phases
    ExternalAPIReportChargerPort:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the port
        connector_id:
          type: integer
          nullable: true
          description: Connector ID for OCPP
        status:
          type: string
          enum:
            - DISABLED
            - AVAILABLE
            - STANDBY
            - CHARGING
            - OFFLINE
            - FAULTED
            - RESERVED
            - UNAVAILABLE
            - UNDEFINED
            - NOT_CHARGING
            - COMPLETE
            - ASLEEP
            - STARTING
            - STOPPING
            - WAITING_CHARGER
            - WAITING_VEHICLE
            - IN_PROGRESS
            - FAILED_START
            - FAILED_STOP
            - NO_SESSION
            - PREPARING
            - SUSPENDED_EV
            - SUSPENDED_EVSE
            - UNPLUGGED
            - UNPLUGGED_NOT_CHARGING
            - UNPLUGGED_CHARGING
            - PLUGGED_IN_NOT_CHARGING
            - PLUGGED_IN_SUSPENDED_EV
            - PLUGGED_IN_CHARGING
            - CHARGING_COMPLETE
            - CUSTOM_CHARGER
            - CUSTOM_VEHICLE
            - FINISHING
          description: Current status of the port
    ExternalAPIReportChargerStatus:
      type: object
      required:
        - location
        - meter_type
        - ports
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the charger
        charger_health:
          type: string
          readOnly: true
          description: Health status of the charger
        ocpp_protocol_version:
          type: string
          readOnly: true
          description: Version of the OCPP protocol
        operating_voltages:
          type: number
          readOnly: true
          description: Operating voltage
        location:
          type: string
          minLength: 1
          nullable: true
          description: Location name
        meter_type:
          type: string
          minLength: 1
          description: Type of meter
        status:
          type: string
          enum:
            - DISABLED
            - AVAILABLE
            - STANDBY
            - CHARGING
            - OFFLINE
            - FAULTED
            - RESERVED
            - UNAVAILABLE
            - UNDEFINED
            - NOT_CHARGING
            - COMPLETE
            - ASLEEP
            - STARTING
            - STOPPING
            - WAITING_CHARGER
            - WAITING_VEHICLE
            - IN_PROGRESS
            - FAILED_START
            - FAILED_STOP
            - NO_SESSION
            - PREPARING
            - SUSPENDED_EV
            - SUSPENDED_EVSE
            - UNPLUGGED
            - UNPLUGGED_NOT_CHARGING
            - UNPLUGGED_CHARGING
            - PLUGGED_IN_NOT_CHARGING
            - PLUGGED_IN_SUSPENDED_EV
            - PLUGGED_IN_CHARGING
            - CHARGING_COMPLETE
            - CUSTOM_CHARGER
            - CUSTOM_VEHICLE
            - FINISHING
          description: Current status of the charger
        ports:
          type: array
          items:
            $ref: '#/components/schemas/ExternalAPIReportChargerPort'
          description: List of ports on this charger
    ReportCharger:
      type: object
      required:
        - tenant
        - charger_id
        - charger_name
        - site_name
        - commission_date
        - report_date
        - driver_emails
      properties:
        tenant:
          type: string
          minLength: 1
          description: Tenant name
        charger_id:
          type: string
          minLength: 1
          description: Charger identifier
        charger_name:
          type: string
          minLength: 1
          description: Name of the charger
        site_name:
          type: string
          minLength: 1
          description: Name of the site
        address:
          type: string
          readOnly: true
          description: Physical address
        city:
          type: string
          readOnly: true
          description: City
        state:
          type: string
          readOnly: true
          description: State or province
        zip:
          type: string
          readOnly: true
          description: ZIP or postal code
        country:
          type: string
          readOnly: true
          description: Country
        owner:
          type: string
          readOnly: true
          description: Owner of the charger
        utility:
          type: string
          readOnly: true
          description: Utility provider
        commission_date:
          type: string
          format: date-time
          description: Date when the charger was commissioned
        operating_status:
          type: string
          readOnly: true
          description: Current operating status
        total_power:
          type: number
          readOnly: true
          description: Total power consumption
        report_date:
          type: string
          format: date-time
          description: Date of the report
        driver_emails:
          type: array
          items:
            type: string
            format: email
            minLength: 1
          description: Email addresses of drivers
    ReportChargingSession:
      type: object
      required:
        - tenant
        - session_id
        - plug_in_start_datetime
        - plug_in_end_datetime
        - charging_start_datetime
        - charging_end_datetime
        - driver_emails
      properties:
        tenant:
          type: string
          minLength: 1
          description: Tenant name
        session_id:
          type: string
          minLength: 1
          description: Unique identifier for the session
        charger_id:
          type: string
          readOnly: true
          description: Charger identifier
        port_id:
          type: string
          readOnly: true
          description: Port identifier
        charger_manufacturer:
          type: string
          readOnly: true
          description: Manufacturer of the charger
        charger_model:
          type: string
          readOnly: true
          description: Model of the charger
        charger_name:
          type: string
          readOnly: true
          description: Name of the charger
        plug_in_start_datetime:
          type: string
          format: date-time
          description: When vehicle was plugged in
        plug_in_end_datetime:
          type: string
          format: date-time
          description: When vehicle was unplugged
        charging_start_datetime:
          type: string
          format: date-time
          description: When charging started
        charging_end_datetime:
          type: string
          format: date-time
          description: When charging ended
        charging_time:
          type: integer
          readOnly: true
          description: Duration of charging in minutes
        energy_delivered_to_electric_vehicle_kwh:
          type: number
          readOnly: true
          description: Energy delivered in kWh
        cost_per_session_usd:
          type: number
          readOnly: true
          description: Cost of the session in USD
        driver_emails:
          type: array
          items:
            type: string
            format: email
            minLength: 1
          description: Email addresses of drivers
    ReportFaults:
      type: object
      properties:
        charger:
          type: string
          readOnly: true
          description: Charger identifier
        charger_id:
          type: string
          readOnly: true
          description: Charger ID
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: When the fault was created
        error_code:
          type: string
          readOnly: true
          description: Error code
        error_info:
          type: string
          readOnly: true
          description: Detailed error information
        status:
          type: string
          readOnly: true
          description: Current status
    ReportTransaction:
      type: object
      required:
        - charger
        - charger_name
        - charger_id
        - plug_in_datetime
        - start_datetime
        - stop_datetime
        - timezone
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the transaction
        charger:
          type: string
          format: uuid
          description: Charger UUID
        charger_name:
          type: string
          minLength: 1
          description: Name of the charger
        charger_id:
          type: string
          minLength: 1
          description: Charger identifier
        plug_in_datetime:
          type: string
          format: date-time
          description: When vehicle was plugged in
        start_datetime:
          type: string
          format: date-time
          description: When charging started
        stop_datetime:
          type: string
          format: date-time
          description: When charging stopped
        timezone:
          type: string
          minLength: 1
          description: Timezone
        total_energy_imported:
          type: number
          readOnly: true
          description: Total energy imported in kWh
        power_units:
          type: string
          readOnly: true
          description: Units of power measurement
    ExternalAPIUser:
      type: object
      required:
        - email
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the user
        email:
          type: string
          format: email
          minLength: 1
          description: Email address
        first_name:
          type: string
          readOnly: true
          minLength: 1
          description: First name
        last_name:
          type: string
          readOnly: true
          minLength: 1
          description: Last name
        attached_id_tags:
          type: array
          items:
            type: string
          readOnly: true
          description: RFID tags attached to this user
        attached_chargers:
          type: array
          items:
            type: string
          readOnly: true
          description: Chargers accessible to this user
