openapi: 3.0.3
info:
  title: skeemrr API
  description: Multi-format e-invoice Schematron validation service
  version: 1.9.0
  contact:
    name: SkeeterLab
    email: hello@skeeterlab.com
    url: https://skeemrr.skeeterlab.com

servers:
  - url: https://api.skeemrr.skeeterlab.com
    description: Production

security:
  - ApiKeyAuth: []
  - BearerAuth: []

paths:
  /validate:
    post:
      summary: Validate an e-invoice
      description: Validates an XML invoice payload against Schematron business rules. Auto-detects format from 21 supported standards.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [payload]
              properties:
                payload:
                  type: string
                  description: XML invoice string (max 512KB)
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '400':
          description: Invalid request (MISSING_PAYLOAD, INVALID_JSON, PARSE_ERROR)
        '401':
          description: Authentication required
        '413':
          description: Payload too large (max 512KB)
        '415':
          description: Content-Type must be application/json

  /validate-batch:
    post:
      summary: Validate multiple invoices
      description: Validates up to 20 invoices in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [payloads]
              properties:
                payloads:
                  type: array
                  items:
                    type: string
                  maxItems: 20
      responses:
        '200':
          description: Array of validation results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ValidationResult'

  /analytics:
    get:
      summary: Anonymized validation analytics
      description: Aggregate statistics from the last 90 days. Public — no authentication required.
      security: []
      responses:
        '200':
          description: Analytics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'

  /health:
    get:
      summary: Health check
      description: Returns service status and list of supported formats.
      security: []
      responses:
        '200':
          description: Service healthy

  /api-keys:
    post:
      summary: Create an API key
      description: Generate a new API key (max 3 per user). Key is shown only once. Requires JWT auth.
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  description: Human-readable label
      responses:
        '201':
          description: API key created
    get:
      summary: List API keys
      description: Returns active API keys (prefixes only, not full keys).
      security:
        - BearerAuth: []
      responses:
        '200':
          description: List of API keys

  /api-keys/{id}:
    delete:
      summary: Revoke an API key
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Key revoked

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

  schemas:
    ValidationResult:
      type: object
      properties:
        validationId:
          type: string
        valid:
          type: boolean
        format:
          type: string
        formatDisplayName:
          type: string
        invoiceType:
          type: string
        rulesetVersion:
          type: string
        errors:
          type: integer
        warnings:
          type: integer
        successes:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'

    ValidationError:
      type: object
      properties:
        severity:
          type: string
          enum: [error, warning, success]
        ruleId:
          type: string
        location:
          type: string
        message:
          type: string

    AnalyticsResponse:
      type: object
      properties:
        period:
          type: string
        totalValidations:
          type: integer
        formatBreakdown:
          type: object
          additionalProperties:
            type: integer
        passRate:
          type: object
          properties:
            total: { type: integer }
            passed: { type: integer }
            failed: { type: integer }
            rate: { type: integer }
        topErrors:
          type: array
          items:
            type: object
            properties:
              ruleId: { type: string }
              count: { type: integer }
