openapi: 3.0.3
info:
  title: Sunira LLC Barcode API
  description: |
    API for decoding PDF417 barcodes from driver's licenses and ID cards.
    
    ## Authentication
    All API requests require an API key passed in the `X-API-Key` header.
    Contact Sunira LLC to obtain your API credentials.
    
    ## Rate Limiting
    Rate limits are enforced per API key. Default limit is 100 requests per hour.
    When rate limited, you will receive a 429 status code.
    
    ## Environments
    - **Sandbox**: For testing and development
    - **Production**: For live applications
  version: 1.0.0
  contact:
    name: Sunira LLC API Support
    url: https://sunirallc.com/contact
  license:
    name: Proprietary
    url: https://sunirallc.com/terms

servers:
  - url: https://sunirallc.com
    description: Production server
  - url: https://sandbox.sunirallc.com
    description: Sandbox server (for testing)

security:
  - ApiKeyAuth: []

paths:
  /api/barcode/decode:
    post:
      tags:
        - Barcode
      summary: Decode a barcode from an image
      description: |
        Upload an image containing a PDF417 barcode (typically from a driver's license or ID card).
        The API will attempt to decode the barcode and parse the AAMVA-formatted data.
        
        Supported image formats: JPEG, PNG, GIF, BMP, WEBP
      operationId: decodeBarcode
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Image file containing the barcode to decode
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BarcodeDecodeResponse'
              examples:
                success:
                  summary: Barcode found and decoded
                  value:
                    success: true
                    barcode_found: true
                    barcode_type: PDF417
                    raw_data: "@\nANSI 636..."
                    parsed_data:
                      first_name: JOHN
                      middle_name: WILLIAM
                      last_name: DOE
                      date_of_birth: "1990-05-15"
                      expiration_date: "2028-05-15"
                      issue_date: "2020-05-15"
                      license_number: D12345678
                      address: 123 MAIN ST
                      city: ANYTOWN
                      state: TX
                      zip_code: "75001"
                      country: USA
                      gender: M
                      height: "511"
                      eye_color: BRN
                      document_type: DL
                no_barcode:
                  summary: No barcode found in image
                  value:
                    success: true
                    barcode_found: false
                    message: No barcode detected in the image
        '400':
          description: Bad request - missing or invalid file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: No file provided
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: Invalid or missing API key
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: Rate limit exceeded. Please try again later.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: An unexpected error occurred

  /api/barcode/health:
    get:
      tags:
        - Health
      summary: Check API health status
      description: Returns the health status of the barcode API service
      operationId: healthCheck
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: healthy
                service: barcode-api
                version: 1.0.0

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

  schemas:
    BarcodeDecodeResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the API call was successful
        barcode_found:
          type: boolean
          description: Whether a barcode was detected in the image
        barcode_type:
          type: string
          description: Type of barcode detected (e.g., PDF417)
        raw_data:
          type: string
          description: Raw barcode data before parsing
        parsed_data:
          $ref: '#/components/schemas/ParsedLicenseData'
        message:
          type: string
          description: Additional message (e.g., when no barcode found)

    ParsedLicenseData:
      type: object
      description: Parsed data from AAMVA-formatted license barcode
      properties:
        first_name:
          type: string
        middle_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        expiration_date:
          type: string
          format: date
        issue_date:
          type: string
          format: date
        license_number:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip_code:
          type: string
        country:
          type: string
        gender:
          type: string
          enum: [M, F, X]
        height:
          type: string
        eye_color:
          type: string
        hair_color:
          type: string
        document_type:
          type: string

    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum: [healthy, unhealthy]
        service:
          type: string
        version:
          type: string

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Error message describing what went wrong

tags:
  - name: Barcode
    description: Barcode decoding operations
  - name: Health
    description: Service health endpoints
