openapi: 3.0.0
info:
  title: Invoice OCR API
  description: API for processing invoices, receipts, and Romanian ID cards using OCR technology
  version: 1.0.0
  contact:
    name: Support
    email: office@hypen.ro

servers:
  - url: /api/v1
    description: API v1 endpoint

paths:
  /ocr:
    post:
      summary: Process document with OCR
      description: Upload a document (image or PDF) for OCR processing
      operationId: processDocument
      tags:
        - OCR
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The document file to process (PDF, JPG, or PNG)
                language:
                  type: string
                  enum: [en, de, ro]
                  default: en
                  description: The language to use for OCR processing
              required:
                - file
      responses:
        '200':
          description: Successful OCR processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [success]
                  data:
                    type: object
                    properties:
                      text:
                        type: string
                        description: The extracted text from the document
                      language:
                        type: string
                        description: The language used for processing
        '400':
          $ref: '#/components/responses/Error400'
        '405':
          $ref: '#/components/responses/Error405'
        '500':
          $ref: '#/components/responses/Error500'

  /parse/id:
    post:
      summary: Parse Romanian ID card OCR text
      description: Processes OCR text from Romanian ID cards and extracts structured information
      operationId: parseIdCard
      tags:
        - ID Parser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: ['raw_text']
              properties:
                raw_text:
                  type: string
                  description: Raw OCR text from the ID card
                  example: "ROMÂNIA\nCARTE DE IDENTITATE\nNume/Nom/Last name\nPOPESCU"
      responses:
        '200':
          description: Successful parsing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDParseResult'
        '400':
          $ref: '#/components/responses/Error400'
        '405':
          $ref: '#/components/responses/Error405'
        '500':
          $ref: '#/components/responses/Error500'

  /process/id:
    post:
      summary: Complete ID card processing
      description: Processes an ID card image with OCR and extracts structured information in one step
      operationId: processIdCard
      tags:
        - ID Processing
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The ID card image file (JPG or PNG)
              required:
                - file
      responses:
        '200':
          description: Successful processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [success]
                  data:
                    type: object
                    properties:
                      ocr_text:
                        type: string
                        description: The raw OCR text extracted from the image
                      parsed_data:
                        $ref: '#/components/schemas/IDParseData'
        '400':
          $ref: '#/components/responses/Error400'
        '405':
          $ref: '#/components/responses/Error405'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/Error500'

  /parse/receipt:
    post:
      summary: Parse Romanian receipt OCR text
      description: Processes OCR text from receipts and extracts structured information with SAGA XML format
      operationId: parseReceipt
      tags:
        - Receipt Parser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: ['raw_text']
              properties:
                raw_text:
                  type: string
                  description: Raw OCR text from the receipt
                  example: "BON FISCAL\nC.I.F.: R011201891\nNumar: 0198-00033"
      responses:
        '200':
          description: Successful parsing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiptParseResult'
        '400':
          $ref: '#/components/responses/Error400'
        '405':
          $ref: '#/components/responses/Error405'
        '500':
          $ref: '#/components/responses/Error500'

  /process/receipt:
    post:
      summary: Complete receipt processing
      description: Processes a receipt image with OCR and extracts structured information with SAGA XML in one step
      operationId: processReceipt
      tags:
        - Receipt Processing
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The receipt image file (JPG, PNG, or PDF)
              required:
                - file
      responses:
        '200':
          description: Successful processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [success]
                  data:
                    type: object
                    properties:
                      ocr_text:
                        type: array
                        items:
                          type: string
                        description: The raw OCR text lines extracted from the image
                      parsed_data:
                        $ref: '#/components/schemas/ReceiptData'
                      saga_xml:
                        type: string
                        description: SAGA-compatible XML format for direct import
                        example: |
                          <?xml version="1.0" encoding="UTF-8"?>
                          <ImportNIR Version="1.0">
                            <Header>
                              <Data>26.03.2024</Data>
                              <TipDoc>FACTURA</TipDoc>
                              <SimbolDoc>0198</SimbolDoc>
                              <NumarDoc>00033</NumarDoc>
                              <Gestiune>PRINCIPAL</Gestiune>
                              <Moneda>RON</Moneda>
                              <Curs>1.0000</Curs>
                            </Header>
                            <Furnizor>
                              <CodFiscal>11201891</CodFiscal>
                              <Denumire>OMV</Denumire>
                              <Reg_com></Reg_com>
                              <Analitic>401.00</Analitic>
                            </Furnizor>
                          </ImportNIR>
        '400':
          $ref: '#/components/responses/Error400'
        '405':
          $ref: '#/components/responses/Error405'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/Error500'

components:
  schemas:
    Error:
      type: object
      properties:
        status:
          type: string
          enum: [error]
        message:
          type: string

    IDParseData:
      type: object
      properties:
        surname:
          type: string
          nullable: true
          description: Last name from the ID
          example: "POPESCU"
        name:
          type: string
          nullable: true
          description: First name from the ID
          example: "IOAN"
        identity_number:
          type: string
          nullable: true
          description: CNP (Personal Numerical Code)
          example: "1880101334455"
        ci_series:
          type: string
          nullable: true
          description: ID card series
          example: "RT"
        ci_number:
          type: string
          nullable: true
          description: ID card number
          example: "123456"
        address:
          type: string
          nullable: true
          description: Address from the ID
          example: "Jud.BV Mun.Brașov Str.Lunga nr.1"
        expiry_date:
          type: string
          nullable: true
          description: ID card expiry date
          example: "21.06.2028"
        issued_by:
          type: string
          nullable: true
          description: Authority that issued the ID
          example: "SPCLEP Brașov"
        issued_date:
          type: string
          nullable: true
          description: Date when the ID was issued
          example: "13.07.21"
        missing_fields:
          type: array
          items:
            type: string
          description: List of fields that couldn't be parsed
          example: []

    IDParseResult:
      type: object
      properties:
        status:
          type: string
          enum: [success]
        data:
          $ref: '#/components/schemas/IDParseData'

    ReceiptData:
      type: object
      properties:
        vendor:
          type: object
          properties:
            fiscal_code:
              type: string
              description: Vendor's fiscal code (CUI/CIF)
              example: "11201891"
            name:
              type: string
              description: Vendor's name
              example: "OMV"
        client:
          type: object
          properties:
            fiscal_code:
              type: string
              description: Client's fiscal code
              example: "39449294"
            details:
              type: string
              description: Additional client details
              example: "B239AKZ"
        items:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Product name
                example: "OMV DIESEL"
              quantity:
                type: number
                description: Quantity purchased
                example: 2.0
              unit_price:
                type: number
                description: Price per unit
                example: 7.49
              total_price:
                type: number
                description: Total price for this item
                example: 468.80
              vat_rate:
                type: integer
                description: VAT rate percentage
                example: 19
        totals:
          type: object
          properties:
            subtotal:
              type: number
              description: Total without VAT
              example: 393.95
            vat_amount:
              type: number
              description: VAT amount
              example: 74.85
            total:
              type: number
              description: Final total
              example: 468.80
        payment:
          type: object
          properties:
            method:
              type: string
              description: Payment method used
              example: "card"
            details:
              type: string
              description: Additional payment details
              example: "MASTERCARD"
        receipt:
          type: object
          properties:
            number:
              type: string
              description: Receipt number
              example: "0198-00033"
            date:
              type: string
              description: Receipt date
              example: "26.03.2024"
            time:
              type: string
              description: Receipt time
              example: "22:33:07"

    ReceiptParseResult:
      type: object
      properties:
        status:
          type: string
          enum: [success]
        data:
          $ref: '#/components/schemas/ReceiptData'
        saga_xml:
          type: string
          description: SAGA-compatible XML format for direct import
          example: |
            <?xml version="1.0" encoding="UTF-8"?>
            <ImportNIR Version="1.0">
              <Header>
                <Data>26.03.2024</Data>
                <TipDoc>FACTURA</TipDoc>
                <SimbolDoc>0198</SimbolDoc>
                <NumarDoc>00033</NumarDoc>
                <Gestiune>PRINCIPAL</Gestiune>
                <Moneda>RON</Moneda>
                <Curs>1.0000</Curs>
              </Header>
              <Furnizor>
                <CodFiscal>11201891</CodFiscal>
                <Denumire>OMV</Denumire>
                <Reg_com></Reg_com>
                <Analitic>401.00</Analitic>
              </Furnizor>
            </ImportNIR>

  responses:
    Error400:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error405:
      description: Method not allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

