{
  "openapi": "3.1.0",
  "info": {
    "title": "Documiner API",
    "version": "1.0.0",
    "description": "Document extraction and e-invoice generation API. Send a business document as base64-encoded content, receive typed structured JSON.\n\nBase URL: `https://documentminer.eu.jetveo.io`\n\nAll data is processed on EU infrastructure. Documents are not stored after processing.",
    "contact": { "email": "info@alfaveo.com" }
  },
  "servers": [
    { "url": "https://documentminer.eu.jetveo.io", "description": "Production (EU)" }
  ],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Extraction", "description": "Document data extraction endpoints" },
    { "name": "Generation", "description": "E-invoice generation endpoints" },
    { "name": "Utility", "description": "Utility endpoints" }
  ],
  "paths": {
    "/api/parse-documents-sync": {
      "post": {
        "tags": ["Extraction"],
        "summary": "Extract data from a business document",
        "description": "Accepts a business document (invoice, quote, purchase order, delivery note, etc.) as base64-encoded content and returns an array of typed document objects. Supports PDF, images, ISDOC, and ZUGFeRD formats.\n\nISDoc and ZUGFeRD are processed by native parsers (100% accuracy). All other formats are processed by AI extraction.",
        "operationId": "parseDocumentsSync",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentInput"
              },
              "example": {
                "FileName": "invoice.pdf",
                "Content": "<base64-encoded file content>"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully extracted document data. Returns an array of typed document objects.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ExtractedDocument"
                  }
                },
                "example": [
                  {
                    "$type": "Invoice",
                    "InvoiceNumber": "2024-0042",
                    "IssueDate": "2024-01-15",
                    "DueDate": "2024-02-15",
                    "Vendor": {
                      "Name": "ACME s.r.o.",
                      "RegistrationNumber": "12345678",
                      "VatId": "CZ12345678",
                      "Address": "Wenceslas Square 1, Prague"
                    },
                    "Buyer": {
                      "Name": "Buyer Corp a.s.",
                      "VatId": "CZ87654321"
                    },
                    "LineItems": [
                      {
                        "Description": "Software License Q1",
                        "Quantity": 1,
                        "UnitPrice": 45000,
                        "VatRate": 21,
                        "Total": 54450
                      }
                    ],
                    "Totals": {
                      "Subtotal": 45000,
                      "Vat": 9450,
                      "Total": 54450,
                      "Currency": "CZK"
                    }
                  }
                ]
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "422": { "$ref": "#/components/responses/UnprocessableEntity" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/parse-communication-sync": {
      "post": {
        "tags": ["Extraction"],
        "summary": "Extract data from email or communication",
        "description": "Extracts structured information from email messages and other communication documents.",
        "operationId": "parseCommunicationSync",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DocumentInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully extracted communication data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "type": "object" }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/UnprocessableEntity" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/generate-isdoc": {
      "post": {
        "tags": ["Generation"],
        "summary": "Generate ISDOC e-invoice",
        "description": "Generates an ISDOC XML e-invoice from structured invoice data. ISDOC is the Czech national e-invoice standard.",
        "operationId": "generateIsdoc",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/InvoiceData" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ISDOC XML file content.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DocumentOutput" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/generate-zugferd": {
      "post": {
        "tags": ["Generation"],
        "summary": "Generate ZUGFeRD / Factur-X e-invoice",
        "description": "Generates a ZUGFeRD / Factur-X compliant XML e-invoice from structured invoice data.",
        "operationId": "generateZugferd",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/InvoiceData" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ZUGFeRD XML file content.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DocumentOutput" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/generate-embed-isdoc": {
      "post": {
        "tags": ["Generation"],
        "summary": "Embed ISDOC XML into PDF",
        "description": "Embeds an ISDOC XML file into an existing PDF, creating an ISDOCX hybrid document.",
        "operationId": "generateEmbedIsdoc",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EmbedInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PDF with embedded ISDOC XML.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DocumentOutput" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/generate-embed-zugferd": {
      "post": {
        "tags": ["Generation"],
        "summary": "Embed ZUGFeRD XML into PDF",
        "description": "Embeds a ZUGFeRD / Factur-X XML file into an existing PDF, creating a hybrid e-invoice.",
        "operationId": "generateEmbedZugferd",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EmbedInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PDF with embedded ZUGFeRD XML.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DocumentOutput" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/assign-ledger-account": {
      "post": {
        "tags": ["Utility"],
        "summary": "Assign ledger accounts to line items",
        "description": "Automatically assigns accounting ledger accounts to invoice line items based on description and category.",
        "operationId": "assignLedgerAccount",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LedgerAssignInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Line items with assigned ledger accounts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/LedgerAssignResult" }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/ping": {
      "post": {
        "tags": ["Utility"],
        "summary": "Health check",
        "description": "Returns service status. Use to verify connectivity and token validity.",
        "operationId": "ping",
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API token issued by Documiner. Include as `Authorization: Bearer YOUR_API_TOKEN`."
      }
    },
    "schemas": {
      "DocumentInput": {
        "type": "object",
        "required": ["FileName", "Content"],
        "properties": {
          "FileName": {
            "type": "string",
            "description": "Original filename including extension. Used to determine the file type.",
            "example": "invoice.pdf"
          },
          "Content": {
            "type": "string",
            "format": "byte",
            "description": "Base64-encoded file content. Supported formats: PDF, JPEG, PNG, TIFF, WebP, ISDOC, ISDOCX, ZUGFeRD XML."
          }
        }
      },
      "EmbedInput": {
        "type": "object",
        "required": ["PdfFileName", "PdfContent", "XmlContent"],
        "properties": {
          "PdfFileName": {
            "type": "string",
            "description": "Original PDF filename.",
            "example": "invoice.pdf"
          },
          "PdfContent": {
            "type": "string",
            "format": "byte",
            "description": "Base64-encoded PDF file content."
          },
          "XmlContent": {
            "type": "string",
            "format": "byte",
            "description": "Base64-encoded XML (ISDOC or ZUGFeRD) file content to embed."
          }
        }
      },
      "DocumentOutput": {
        "type": "object",
        "properties": {
          "FileName": {
            "type": "string",
            "description": "Output filename.",
            "example": "invoice.isdocx"
          },
          "Content": {
            "type": "string",
            "format": "byte",
            "description": "Base64-encoded output file content."
          }
        }
      },
      "InvoiceData": {
        "type": "object",
        "description": "Structured invoice data for e-invoice generation.",
        "properties": {
          "InvoiceNumber": { "type": "string", "example": "2024-0042" },
          "IssueDate": { "type": "string", "format": "date", "example": "2024-01-15" },
          "DueDate": { "type": "string", "format": "date", "example": "2024-02-15" },
          "Vendor": { "$ref": "#/components/schemas/Party" },
          "Buyer": { "$ref": "#/components/schemas/Party" },
          "LineItems": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/LineItem" }
          },
          "Totals": { "$ref": "#/components/schemas/Totals" }
        }
      },
      "LedgerAssignInput": {
        "type": "object",
        "properties": {
          "LineItems": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/LineItem" }
          }
        }
      },
      "LedgerAssignResult": {
        "type": "object",
        "properties": {
          "Description": { "type": "string" },
          "LedgerAccount": { "type": "string", "example": "518" },
          "LedgerAccountName": { "type": "string", "example": "Other services" }
        }
      },
      "ExtractedDocument": {
        "type": "object",
        "description": "A typed extracted document. The $type discriminator indicates the document type.",
        "properties": {
          "$type": {
            "type": "string",
            "enum": ["Invoice", "Quote", "PurchaseOrder", "Inquiry", "DeliveryNote", "Contract"],
            "description": "Discriminator indicating the document type."
          },
          "InvoiceNumber": { "type": "string" },
          "IssueDate": { "type": "string", "format": "date" },
          "DueDate": { "type": "string", "format": "date" },
          "Vendor": { "$ref": "#/components/schemas/Party" },
          "Buyer": { "$ref": "#/components/schemas/Party" },
          "LineItems": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/LineItem" }
          },
          "Totals": { "$ref": "#/components/schemas/Totals" }
        }
      },
      "Party": {
        "type": "object",
        "properties": {
          "Name": { "type": "string", "example": "ACME s.r.o." },
          "RegistrationNumber": { "type": "string", "example": "12345678" },
          "VatId": { "type": "string", "example": "CZ12345678" },
          "Address": { "type": "string", "example": "Wenceslas Square 1, Prague" }
        }
      },
      "LineItem": {
        "type": "object",
        "properties": {
          "Description": { "type": "string", "example": "Software License Q1" },
          "Quantity": { "type": "number", "example": 1 },
          "UnitPrice": { "type": "number", "example": 45000 },
          "VatRate": { "type": "number", "example": 21 },
          "Total": { "type": "number", "example": 54450 }
        }
      },
      "Totals": {
        "type": "object",
        "properties": {
          "Subtotal": { "type": "number", "example": 45000 },
          "Vat": { "type": "number", "example": 9450 },
          "Total": { "type": "number", "example": 54450 },
          "Currency": { "type": "string", "example": "CZK" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "unauthorized" },
          "message": { "type": "string", "example": "API token is missing or invalid." }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request — check that FileName and Content are provided and non-empty.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized — API token is missing or invalid.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "PaymentRequired": {
        "description": "Payment required — account credits depleted. Top up to continue.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "UnprocessableEntity": {
        "description": "Unprocessable entity — file is valid but document could not be parsed.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "InternalServerError": {
        "description": "Internal server error — transient error, retry with backoff.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      }
    }
  }
}