openapi: 3.0.3
info:
  title: Tampa Electric Account API
  description: >-
    The Tampa Electric Account API provides programmatic access to customer
    account management capabilities including billing, energy usage history,
    payment processing, service requests, and energy efficiency programs.
    Used by residential and commercial customers and authorized third-party
    applications through the Tampa Electric developer portal.
  version: 1.0.0
  contact:
    url: https://developer.tecoenergy.com/
  license:
    name: Proprietary
    url: https://www.tecoenergy.com/
servers:
  - url: https://api.tecoenergy.com/v1
    description: Tampa Electric API - Production
paths:
  /accounts/{accountNumber}:
    get:
      operationId: getAccount
      summary: Get Account Details
      description: Retrieve account information for a Tampa Electric customer account.
      tags:
        - Accounts
      parameters:
        - name: accountNumber
          in: path
          description: Customer account number.
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Account details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized.
        '404':
          description: Account not found.
  /accounts/{accountNumber}/usage:
    get:
      operationId: getUsageHistory
      summary: Get Energy Usage History
      description: Retrieve historical energy usage data for a customer account.
      tags:
        - Energy Usage
      parameters:
        - name: accountNumber
          in: path
          description: Customer account number.
          required: true
          schema:
            type: string
        - name: startDate
          in: query
          description: Start date for usage history (ISO 8601 format).
          required: false
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: End date for usage history (ISO 8601 format).
          required: false
          schema:
            type: string
            format: date
        - name: interval
          in: query
          description: Data interval granularity.
          required: false
          schema:
            type: string
            enum:
              - hourly
              - daily
              - monthly
            default: daily
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Energy usage history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accountNumber:
                    type: string
                  unit:
                    type: string
                    description: Unit of measurement (kWh).
                  interval:
                    type: string
                  usageData:
                    type: array
                    items:
                      $ref: '#/components/schemas/UsageRecord'
        '401':
          description: Unauthorized.
        '404':
          description: Account not found.
  /accounts/{accountNumber}/bills:
    get:
      operationId: listBills
      summary: List Bills
      description: Retrieve billing history for a customer account.
      tags:
        - Billing
      parameters:
        - name: accountNumber
          in: path
          description: Customer account number.
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of bills to return.
          required: false
          schema:
            type: integer
            default: 12
            maximum: 24
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of bills.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bill'
        '401':
          description: Unauthorized.
        '404':
          description: Account not found.
  /accounts/{accountNumber}/bills/{billId}:
    get:
      operationId: getBill
      summary: Get Bill Details
      description: Retrieve detailed information for a specific bill.
      tags:
        - Billing
      parameters:
        - name: accountNumber
          in: path
          description: Customer account number.
          required: true
          schema:
            type: string
        - name: billId
          in: path
          description: Unique bill identifier.
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Bill details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
        '404':
          description: Bill not found.
  /accounts/{accountNumber}/payments:
    post:
      operationId: makePayment
      summary: Make Payment
      description: Submit a payment for a Tampa Electric customer account.
      tags:
        - Billing
      parameters:
        - name: accountNumber
          in: path
          description: Customer account number.
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '201':
          description: Payment submitted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  confirmationNumber:
                    type: string
                  paymentDate:
                    type: string
                    format: date
                  amount:
                    type: number
                  status:
                    type: string
        '400':
          description: Invalid payment data.
        '401':
          description: Unauthorized.
  /accounts/{accountNumber}/service-requests:
    get:
      operationId: listServiceRequests
      summary: List Service Requests
      description: Retrieve open and historical service requests for a customer account.
      tags:
        - Service Requests
      parameters:
        - name: accountNumber
          in: path
          description: Customer account number.
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: Filter by service request status.
          required: false
          schema:
            type: string
            enum:
              - open
              - in-progress
              - completed
              - cancelled
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of service requests.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceRequest'
    post:
      operationId: createServiceRequest
      summary: Create Service Request
      description: Submit a new service request for a customer account.
      tags:
        - Service Requests
      parameters:
        - name: accountNumber
          in: path
          description: Customer account number.
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequestCreate'
      responses:
        '201':
          description: Service request created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRequest'
        '400':
          description: Invalid request data.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Account:
      type: object
      description: A Tampa Electric customer account.
      properties:
        accountNumber:
          type: string
          description: Unique customer account number.
        customerName:
          type: string
          description: Account holder name.
        serviceAddress:
          type: object
          properties:
            streetAddress:
              type: string
            city:
              type: string
            state:
              type: string
            zipCode:
              type: string
        accountType:
          type: string
          description: Type of account.
          enum:
            - residential
            - commercial
            - industrial
        serviceType:
          type: string
          description: Type of utility service.
          enum:
            - electric
            - gas
            - electric-and-gas
        status:
          type: string
          description: Account status.
          enum:
            - active
            - inactive
            - pending
        currentBalance:
          type: number
          format: double
          description: Current account balance in USD.
        dueDate:
          type: string
          format: date
          description: Payment due date for current balance.
        paperlessBilling:
          type: boolean
          description: Whether paperless billing is enabled.
    UsageRecord:
      type: object
      description: An energy usage record for a specific time interval.
      properties:
        startTime:
          type: string
          format: date-time
          description: Start of the measurement interval.
        endTime:
          type: string
          format: date-time
          description: End of the measurement interval.
        usage:
          type: number
          format: double
          description: Energy consumed in kWh during the interval.
        cost:
          type: number
          format: double
          description: Estimated cost for the interval in USD.
        temperature:
          type: number
          format: double
          description: Average outdoor temperature during the interval (Fahrenheit).
    Bill:
      type: object
      description: A Tampa Electric utility bill.
      properties:
        billId:
          type: string
          description: Unique bill identifier.
        billDate:
          type: string
          format: date
          description: Date the bill was issued.
        dueDate:
          type: string
          format: date
          description: Payment due date.
        billingPeriodStart:
          type: string
          format: date
          description: Start of the billing period.
        billingPeriodEnd:
          type: string
          format: date
          description: End of the billing period.
        totalAmount:
          type: number
          format: double
          description: Total amount due in USD.
        kwhUsed:
          type: number
          format: double
          description: Total kilowatt-hours consumed during the billing period.
        status:
          type: string
          enum:
            - unpaid
            - paid
            - overdue
            - partial
        charges:
          type: array
          description: Itemized charges on the bill.
          items:
            type: object
            properties:
              description:
                type: string
              amount:
                type: number
                format: double
    PaymentRequest:
      type: object
      required:
        - amount
        - paymentMethod
      properties:
        amount:
          type: number
          format: double
          description: Payment amount in USD.
        paymentMethod:
          type: string
          enum:
            - bank-account
            - credit-card
            - debit-card
        paymentDate:
          type: string
          format: date
          description: Date to process the payment. Defaults to today.
    ServiceRequest:
      type: object
      description: A service request for Tampa Electric customer operations.
      properties:
        requestId:
          type: string
          description: Unique service request ID.
        type:
          type: string
          description: Type of service request.
          enum:
            - start-service
            - stop-service
            - transfer-service
            - meter-read
            - tree-trimming
            - streetlight-repair
            - general-inquiry
        status:
          type: string
          enum:
            - open
            - in-progress
            - completed
            - cancelled
        createdDate:
          type: string
          format: date-time
        scheduledDate:
          type: string
          format: date
        completedDate:
          type: string
          format: date
        notes:
          type: string
          description: Additional notes or details about the request.
    ServiceRequestCreate:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - start-service
            - stop-service
            - transfer-service
            - meter-read
            - tree-trimming
            - streetlight-repair
            - general-inquiry
        preferredDate:
          type: string
          format: date
        notes:
          type: string