openapi.yaml

openapi: 3.0.3
info:
  title: Verso-Backend API
  description: |
    REST API for the Verso-Backend sovereign business operating system.
    
    ## Authentication
    
    All API endpoints require Bearer token authentication. Include your API key in the Authorization header:
    
    ```
    Authorization: Bearer sk_live_your_api_key_here
    ```
    
    ## Rate Limiting
    
    API requests are rate limited to:
    - 100 requests per minute for read operations
    - 30 requests per minute for write operations
    
    Rate limit headers are included in responses:
    - `X-RateLimit-Limit`: Maximum requests allowed
    - `X-RateLimit-Remaining`: Requests remaining in window
    - `X-RateLimit-Reset`: Timestamp when limit resets
    
    ## Pagination
    
    List endpoints support pagination via query parameters:
    - `page`: Page number (default: 1)
    - `per_page`: Items per page (default: 25, max: 100)
    
    Paginated responses include a `pagination` object with total count and page info.
    
    ## Errors
    
    Errors return appropriate HTTP status codes with JSON body:
    ```json
    {
      "error": "Error message description"
    }
    ```
    
  version: 1.0.0
  contact:
    name: Verso Industries
    url: https://versoindustries.com
    email: support@versoindustries.com
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.en.html

servers:
  - url: https://your-domain.com/api/v1
    description: Production server
  - url: http://localhost:5000/api/v1
    description: Development server

tags:
  - name: Leads
    description: Contact form submissions and lead management
  - name: Orders
    description: E-commerce orders
  - name: Products
    description: Product catalog management
  - name: Webhooks
    description: Outbound webhook configuration

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from Admin Dashboard → Manage API Keys

  schemas:
    Lead:
      type: object
      properties:
        id:
          type: integer
          example: 1
        first_name:
          type: string
          example: "John"
        last_name:
          type: string
          example: "Doe"
        email:
          type: string
          format: email
          example: "john@example.com"
        phone:
          type: string
          example: "+1-555-123-4567"
        message:
          type: string
          example: "I'm interested in your services"
        status:
          type: string
          enum: [New, Contacted, Qualified, Proposal, Won, Lost]
          example: "New"
        source:
          type: string
          example: "website"
        notes:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
          example: ["enterprise", "urgent"]
        submitted_at:
          type: string
          format: date-time
          example: "2024-12-01T10:30:00Z"

    LeadCreate:
      type: object
      required:
        - first_name
        - last_name
        - email
        - phone
        - message
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        message:
          type: string
        status:
          type: string
          default: "New"
        source:
          type: string
          default: "api"
        notes:
          type: string
        tags:
          type: array
          items:
            type: string

    LeadUpdate:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        message:
          type: string
        status:
          type: string
        notes:
          type: string
        tags:
          type: array
          items:
            type: string

    Order:
      type: object
      properties:
        id:
          type: integer
          example: 101
        status:
          type: string
          enum: [pending, paid, shipped, delivered, cancelled, refunded]
          example: "paid"
        total_amount:
          type: integer
          description: Total in cents
          example: 2999
        currency:
          type: string
          example: "usd"
        tracking_number:
          type: string
          nullable: true
          example: "1Z999AA10123456784"
        email:
          type: string
          format: email
          example: "customer@example.com"
        created_at:
          type: string
          format: date-time
        items_count:
          type: integer
          example: 2

    OrderDetail:
      allOf:
        - $ref: '#/components/schemas/Order'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/OrderItem'

    OrderItem:
      type: object
      properties:
        id:
          type: integer
        product_id:
          type: integer
        product_name:
          type: string
        quantity:
          type: integer
        unit_price:
          type: integer
          description: Price per unit in cents

    OrderUpdate:
      type: object
      properties:
        status:
          type: string
          enum: [pending, paid, shipped, delivered, cancelled, refunded]
        fulfillment_status:
          type: string
        tracking_number:
          type: string

    Product:
      type: object
      properties:
        id:
          type: integer
          example: 10
        name:
          type: string
          example: "Premium Widget"
        description:
          type: string
          example: "A high-quality widget for professionals"
        price:
          type: integer
          description: Price in cents
          example: 4999
        inventory_count:
          type: integer
          example: 50
        is_digital:
          type: boolean
          example: false

    ProductCreate:
      type: object
      required:
        - name
        - price
      properties:
        name:
          type: string
        description:
          type: string
        price:
          type: integer
          description: Price in cents
        inventory_count:
          type: integer
          default: 0
        is_digital:
          type: boolean
          default: false

    ProductUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        price:
          type: integer
        inventory_count:
          type: integer
        is_digital:
          type: boolean

    Webhook:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          example: "Order notifications"
        url:
          type: string
          format: uri
          example: "https://your-server.com/webhooks/verso"
        events:
          type: array
          items:
            type: string
          example: ["order.created", "order.updated"]
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time

    WebhookCreate:
      type: object
      required:
        - name
        - url
        - events
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            enum:
              - lead.created
              - lead.updated
              - order.created
              - order.updated
              - product.created
        secret:
          type: string
          description: Optional HMAC signing secret
        is_active:
          type: boolean
          default: true

    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 25
        total:
          type: integer
          example: 150
        pages:
          type: integer
          example: 6

    Error:
      type: object
      properties:
        error:
          type: string
          example: "Error message"

paths:
  /leads:
    get:
      tags:
        - Leads
      summary: List all leads
      description: Get all leads with optional filtering, sorting, and pagination.
      operationId: getLeads
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 25
            maximum: 100
        - name: sort
          in: query
          schema:
            type: string
            default: submitted_at
        - name: order
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: status
          in: query
          schema:
            type: string
        - name: created_after
          in: query
          schema:
            type: string
            format: date-time
        - name: created_before
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: List of leads
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []

    post:
      tags:
        - Leads
      summary: Create a lead
      description: Create a new lead in the CRM system.
      operationId: createLead
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadCreate'
      responses:
        '201':
          description: Lead created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  message:
                    type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []

  /leads/{leadId}:
    get:
      tags:
        - Leads
      summary: Get a lead
      description: Get a single lead by ID.
      operationId: getLead
      parameters:
        - name: leadId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Lead details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '404':
          description: Lead not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []

    patch:
      tags:
        - Leads
      summary: Update a lead
      description: Update an existing lead. Only provided fields will be updated.
      operationId: updateLead
      parameters:
        - name: leadId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadUpdate'
      responses:
        '200':
          description: Lead updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  message:
                    type: string
        '400':
          description: Invalid request
        '404':
          description: Lead not found
      security:
        - bearerAuth: []

  /orders:
    get:
      tags:
        - Orders
      summary: List all orders
      description: Get all orders with optional filtering, sorting, and pagination.
      operationId: getOrders
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 25
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, paid, shipped, delivered, cancelled, refunded]
        - name: created_after
          in: query
          schema:
            type: string
            format: date-time
        - name: created_before
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
      security:
        - bearerAuth: []

  /orders/{orderId}:
    get:
      tags:
        - Orders
      summary: Get an order
      description: Get a single order with full details including items.
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '404':
          description: Order not found
      security:
        - bearerAuth: []

    patch:
      tags:
        - Orders
      summary: Update an order
      description: Update order status or fulfillment details.
      operationId: updateOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdate'
      responses:
        '200':
          description: Order updated successfully
        '400':
          description: Invalid request
        '404':
          description: Order not found
      security:
        - bearerAuth: []

  /products:
    get:
      tags:
        - Products
      summary: List all products
      description: Get all products with optional filtering and pagination.
      operationId: getProducts
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 25
        - name: is_digital
          in: query
          schema:
            type: boolean
        - name: in_stock
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: List of products
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
      security:
        - bearerAuth: []

    post:
      tags:
        - Products
      summary: Create a product
      description: Create a new product in the catalog.
      operationId: createProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreate'
      responses:
        '201':
          description: Product created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  message:
                    type: string
        '400':
          description: Invalid request
      security:
        - bearerAuth: []

  /products/{productId}:
    get:
      tags:
        - Products
      summary: Get a product
      description: Get a single product by ID.
      operationId: getProduct
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found
      security:
        - bearerAuth: []

    patch:
      tags:
        - Products
      summary: Update a product
      description: Update an existing product.
      operationId: updateProduct
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUpdate'
      responses:
        '200':
          description: Product updated successfully
        '400':
          description: Invalid request
        '404':
          description: Product not found
      security:
        - bearerAuth: []

  /webhooks:
    get:
      tags:
        - Webhooks
      summary: List webhooks
      description: Get all configured outbound webhooks.
      operationId: getWebhooks
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
      security:
        - bearerAuth: []

    post:
      tags:
        - Webhooks
      summary: Create a webhook
      description: Create a new outbound webhook.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  secret:
                    type: string
                    description: HMAC signing secret (only returned once)
                  message:
                    type: string
        '400':
          description: Invalid request
      security:
        - bearerAuth: []

  /webhooks/{webhookId}:
    delete:
      tags:
        - Webhooks
      summary: Delete a webhook
      description: Delete an existing webhook.
      operationId: deleteWebhook
      parameters:
        - name: webhookId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Webhook deleted
        '404':
          description: Webhook not found
      security:
        - bearerAuth: []