openapi: 3.0.3
info:
  title: PartLogic Stock API
  description: |
    Secure, user-scoped access to stock data. External systems (Zapier, Excel, Postman, custom apps)
    connect via REST endpoints. Data is filtered by device permissions associated with your API key.
  version: 1.0.0
  contact:
    name: PartLogic.co.uk
    email: support@partlogic.co.uk
    url: 'https://partlogic.co.uk'
servers:
  - url: 'https://partlogic-api-stock-dwbbcthkhfb0ceca.ukwest-01.azurewebsites.net'
    description: REST endpoints (ping, stock)
tags:
  - name: Health
    description: API health and connectivity
  - name: Stock
    description: Stock data endpoints
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key from the PartLogic Integrations portal.
        Do not send as a query parameter—use the header only.
        https://portal.partlogic.co.uk/integrations
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: 'Error message (e.g. "missing api key", "invalid api key")'
    PingResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Indicates the API is reachable
        time:
          type: string
          format: date-time
          description: Server timestamp
    StockRow:
      type: object
      description: A single stock record
      properties:
        id:
          type: integer
          description: Unique record ID
        DeviceName:
          type: string
          description: Device/location identifier
        SKU:
          type: string
          description: Stock keeping unit
        GTIN:
          type: string
          description: Global Trade Item Number (barcode/GTIN-13, GTIN-14, etc.)
        DeviceList:
          type: string
          description: Comma-separated list of devices (when applicable)
        Description:
          type: string
          description: Product description
        MinQty:
          type: integer
          description: Minimum quantity (reorder level)
        MaxQty:
          type: integer
          description: Maximum quantity
        Physical:
          type: integer
          description: Current physical stock count
        Location:
          type: string
          description: Storage location code
        LocationAlias:
          type: string
          description: Human-readable location name
paths:
  /api/ping:
    get:
      tags:
        - Health
      summary: Health check
      description: Verifies the API is reachable. No authentication required.
      operationId: getPing
      security: []
      responses:
        '200':
          description: API is reachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
  /api/stock:
    get:
      tags:
        - Stock
      summary: List stock
      description: |
        Returns stock rows from PartLogic, filtered by devices assigned to your API key.
        Best for Postman, Excel, Zapier, and simple scripts.
      operationId: getStock
      security:
        - apiKey: []
      responses:
        '200':
          description: Array of stock rows
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/StockRow'
                  - type: object
                    properties:
                      rows:
                        type: array
                        items:
                          $ref: '#/components/schemas/StockRow'
                      count:
                        type: integer
                        description: Total record count (some deployments use envelope format)
        '401':
          description: 'Missing, invalid, or expired API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Valid key but insufficient permissions or IP not allowed
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
