openapi: 3.0.3
info:
  title: Kontomatik PDF Parsing API
  version: 1.0.0
  description: |
    Extracts structured data from Polish bank statement and transaction
    confirmation PDFs. Supports standard mode (strict verification, rejects on
    inconsistencies) and trusted mode (returns data even when verifications
    fail).
  contact:
    name: Kontomatik Support
    email: support@kontomatik.com
    url: https://developer.kontomatik.com/
servers:
- url: https://api.kontomatik.com/v1
  description: Production
- url: https://test.api.kontomatik.com/v1
  description: Test
security:
- ApiKeyAuth: []
tags:
- name: Statements
  description: Bank statement PDF parsing
- name: Confirmations
  description: Transaction confirmation PDF parsing
- name: Catalog
  description: Coverage catalog
paths:
  /pdf/statement:
    post:
      tags: [Statements]
      summary: Parse Statement (Standard)
      description: Parses a bank statement PDF and returns structured data. Rejects with errors if verification inconsistencies are detected.
      operationId: parseStatement
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [pdf]
              properties:
                pdf:
                  type: string
                  format: binary
                ownerExternalId: {type: string}
                password: {type: string}
      responses:
        '200':
          description: Statement parsed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementResult'
        '400':
          description: Verification failures detected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationFailure'
  /pdf/statement-trusted:
    post:
      tags: [Statements]
      summary: Parse Statement (Trusted)
      description: Parses a bank statement PDF and returns data even when verification fails. Use when the source is trusted.
      operationId: parseStatementTrusted
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [pdf]
              properties:
                pdf:
                  type: string
                  format: binary
                ownerExternalId: {type: string}
                password: {type: string}
      responses:
        '200':
          description: Statement parsed (possibly with verification warnings)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementResult'
  /pdf/statements:
    get:
      tags: [Statements]
      summary: List Parsed Statements
      description: Lists previously parsed statement documents for a given owner.
      operationId: listStatements
      parameters:
      - name: ownerExternalId
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: Statements listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  statements:
                    type: array
                    items: {$ref: '#/components/schemas/StatementSummary'}
  /pdf/confirmation:
    post:
      tags: [Confirmations]
      summary: Parse Confirmation (Standard)
      description: Parses a single-transaction confirmation PDF and returns structured data.
      operationId: parseConfirmation
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [pdf]
              properties:
                pdf: {type: string, format: binary}
                ownerExternalId: {type: string}
      responses:
        '200':
          description: Confirmation parsed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmationResult'
  /pdf/confirmation-trusted:
    post:
      tags: [Confirmations]
      summary: Parse Confirmation (Trusted)
      description: Parses a confirmation PDF in trusted mode, returning data even on failed verification checks.
      operationId: parseConfirmationTrusted
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [pdf]
              properties:
                pdf: {type: string, format: binary}
                ownerExternalId: {type: string}
      responses:
        '200':
          description: Confirmation parsed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmationResult'
  /pdf-catalog:
    get:
      tags: [Catalog]
      summary: List PDF Coverage Catalog
      description: Returns the list of Polish banks supported for PDF statement parsing.
      operationId: getPdfCatalog
      responses:
        '200':
          description: Catalog returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfCatalog'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  schemas:
    StatementResult:
      type: object
      properties:
        statementId: {type: string}
        bank: {type: string}
        owners:
          type: array
          items:
            type: object
            properties:
              name: {type: string}
              nationalId: {type: string}
              address: {type: string}
        accounts:
          type: array
          items:
            type: object
            properties:
              number: {type: string}
              currency: {type: string}
              transactions:
                type: array
                items: {$ref: '#/components/schemas/StatementTransaction'}
        failedVerifications:
          type: array
          items: {type: string}
    StatementTransaction:
      type: object
      properties:
        date: {type: string, format: date}
        amount: {type: number, format: double}
        currency: {type: string}
        description: {type: string}
    StatementSummary:
      type: object
      properties:
        statementId: {type: string}
        ownerExternalId: {type: string}
        bank: {type: string}
        parsedAt: {type: string, format: date-time}
    ConfirmationResult:
      type: object
      properties:
        confirmationId: {type: string}
        bank: {type: string}
        amount: {type: number, format: double}
        currency: {type: string}
        date: {type: string, format: date}
        sender: {type: string}
        receiver: {type: string}
        description: {type: string}
    VerificationFailure:
      type: object
      properties:
        code: {type: string}
        message: {type: string}
        failedVerifications:
          type: array
          items: {type: string}
    PdfCatalog:
      type: object
      properties:
        banks:
          type: array
          items:
            type: object
            properties:
              id: {type: string}
              name: {type: string}
              country: {type: string, example: PL}