openapi: 3.0.0
info:
  title: FASTPANEL billing
  description: API for managing licenses and license packs in the FASTPANEL Billing system.
  version: 1.0.0
servers:
  - url: https://cp.fastpanel.direct
tags:
  - name: Client
    description: Operations related to clients.
  - name: License Packs
    description: Operations related to license packs.
  - name: License
    description: Operations related to licenses.
paths:
  /api/v1/fp2/license:
    get:
      tags:
        - License
      summary: List licenses
      description: Retrieve all licenses available in the license pack.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: pagination[page]
          in: query
          description: Page number 
          required: true
          example: 1 
          schema:
            type: integer 
            format: int64 
        - name: pagination[limit]
          in: query
          description: Number of items on page 
          required: true
          example: 100
          schema:
            type: integer 
            format: int64 
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/License' 
    post:
      tags:
        - License
      summary: Create a license in a license pack
      description: Create a new license by specifying the license pack ID and IP address. 
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pack:
                  type: integer
                  description: License pack ID
                  example: 9
                ip:
                  type: string
                  format: ipv4
                  description: IP address 
                  example: "8.8.8.8"
              required:
                - pack
                - ip
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
        '400':
          description: Invalid request 
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Errors'
                  - $ref: '#/components/schemas/Error'
  /api/v1/fp2/license/{id}:
    delete:
      parameters:
        - name: id
          in: path
          description: 'License id'
          required: true
          schema:
            type: integer 
            format: int64 
      security:
        - ApiKeyAuth: []
      tags:
        - License
      summary: Delete license
      description: Delete an existing license by its ID.
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
  /api/v1/client:
    get:
      tags:
        - Client
      summary: Get current client
      description: Retrieve information about the currently authenticated client.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Client'
  /api/v1/fp2/license_packs:
    get:
      parameters:
        - name: pagination[page]
          in: query
          description: Page number 
          required: true
          example: 1 
          schema:
            type: integer 
            format: int64 
        - name: pagination[limit]
          in: query
          description: Number of items on page 
          required: true
          example: 100
          schema:
            type: integer 
            format: int64 
      tags:
        - License Packs
      summary: List license packs 
      description: Retrieve all license packs available in the system.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Id
                          example: 3
                        issued_license:
                          type: integer
                          description: Number of licenses issued.
                          example: 0
                        expiry:
                          type: string
                          format: date-time
                          description: Expiry date of the license pack.
                          example: "2038-01-01T00:00:00+00:00"
                        invoice_at:
                          type: string
                          format: date-time
                          description: Date and time of the next invoice.
                          example: "2024-11-13T16:37:51+00:00"
                        status:
                          type: string
                          description: License pack status.
                          example: "Active"
                        billcycle:
                          type: string
                          description: Billing type (e.g., "Free Account").
                          example: "Free Account"
                        plan:
                          type: object
                          properties:
                            id:
                              type: integer
                              description: Plan ID.
                              example: 2
                            name:
                              type: string
                              description: Plan name.
                              example: "Extended pack"
                            included_count:
                              type: integer
                              description: The number of licenses included in the plan.
                              example: 20
                            amount:
                              type: integer
                              description: Price
                              example: 60
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                        description: Current page number.
                        example: 1
                      limit:
                        type: integer
                        description: Number of items per page.
                        example: 20
                      total:
                        type: integer
                        description: Total number of licenses.
                        example: 1
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header 
      name: X-Auth-Key
  schemas: 
    Client: 
      type: object
      properties:
        id:
          type: integer
          description: Client ID.
          example: 1234
        email:
          type: string
          description: Email address. 
          example: "admin@example.com"
        billing:
          type: object
          properties:
            credit:
              type: integer
              description: Balance state.
              example: 0
            currency:
              type: object
              properties:
                code:
                  type: string
                  description: Currency code.
                  example: "EUR"
    License:
      type: object
      properties:
        id:
          type: integer
          description: License ID.
          example: 456331
        name:
          type: string
          description: License name.
          example: "FASTPANEL"
        type:
          type: string
          description: License type.
          example: "unlimited"
        status:
          type: string
          description: License status.
          example: "Active"
        ip:
          type: string
          format: ipv4
          description: IP address.
          example: "8.8.8.8"
        period:
          type: integer
          description: License period.
          example: 1
        due_at:
          type: string
          format: date-time
          description: Expiration date.
          example: "Fri, 01 Jan 2038 00:00:00 +0000"
        amount:
          type: integer
          description: Price.
          example: 0
        sites:
          type: integer
          description: Number of sites.
          example: 0
        key:
          type: string
          description: License key.
          example: "key value"
        key_created_at:
          type: string
          format: date-time
          description: Key creation date.
          example: "Wed, 13 Nov 2024 13:38:18 +0000"
        key_expires_at:
          type: string
          format: date-time
          description: Key expiration date.
          example: "Fri, 13 Dec 2024 13:38:18 +0000"
        key_already_used:
          type: boolean
          description: Indicates if the key has already been used.
          example: false
        plan:
          type: object
          properties:
            id:
              type: integer
              description: Plan ID.
              example: 9
            name:
              type: string
              description: Plan name.
              example: "FASTPANEL"
            type:
              type: string
              description: Plan type.
              example: "unlimited"
            amount:
              type: integer
              description: Price.
              example: 0
      required:
        - id
        - name
        - type
        - status
        - ip
        - period
        - due_at
        - amount
        - sites
        - key
        - key_created_at
        - key_expires_at
        - key_already_used
        - plan
    Error: 
      type: object
      properties: 
        error: 
          type: string 
    Errors:
      type: object
      properties:
        errors:
          type: object
          properties: 
            field_name: 
              type: array 
              items:
                type: string
      example: '{"errors": {"field_name": ["This value is not valid"]}}' 
