{ "openapi": "3.1.0", "info": { "title": "Factur-X Engine", "description": "Production-ready REST API for Factur-X (ZUGFeRD 2.4) conversions and data extraction.", "version": "1.7.0" }, "paths": { "/v1/convert": { "post": { "tags": [ "Advanced Integration" ], "summary": "Convert To Facturx", "description": "Attach Factur-X/CII XML to an existing standard PDF invoice (BYOPDF).\n\nThe input must be a valid PDF file (max upload size is controlled by MAX_UPLOAD_SIZE_MB, default 10MB). The API generates XML from metadata and embeds it into the PDF to create a Factur-X document. Use /v1/validate to verify final PDF/A status when needed.", "operationId": "convert_to_facturx_v1_convert_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_convert_to_facturx_v1_convert_post" } } }, "required": true }, "responses": { "200": { "description": "Factur-X PDF successfully generated from provided PDF" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/xml": { "post": { "tags": [ "Core Workflows" ], "summary": "Generate Facturx Xml", "description": "Generate the Factur-X/CII XML content directly from JSON metadata.\n\nThis endpoint returns raw XML (Cross Industry Invoice D22B) \nwithout the PDF wrapper.", "operationId": "generate_facturx_xml_v1_xml_post", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Body_generate_facturx_xml_v1_xml_post" } } }, "required": true }, "responses": { "200": { "description": "Factur-X/CII XML successfully generated" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/validate": { "post": { "tags": [ "Core Workflows" ], "summary": "Validate Facturx", "description": "Validate a Factur-X PDF or XML file against EN 16931 standards.\n\nReturns a validation report with detected format, flavor, and any errors.\n\n**Pro Edition**: Smart Diagnostics with actionable human-readable fixes.\n**Community Edition**: Full raw validation report (Standard EN16931 error codes).", "operationId": "validate_facturx_v1_validate_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_validate_facturx_v1_validate_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationResult" }, { "$ref": "#/components/schemas/ProValidationResult" } ], "title": "Response Validate Facturx V1 Validate Post" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/extract": { "post": { "tags": [ "Core Workflows" ], "summary": "Extract Facturx", "description": "Extract Factur-X XML from a PDF and return heuristic best-effort invoice JSON.\n\nThis endpoint is designed for invoice reception workflows:\n1. Detects if the PDF contains embedded Factur-X/ZUGFeRD XML\n2. Extracts and parses the XML\n3. Returns structured invoice data (parties, totals, line items)\n\nUse cases:\n- Automated invoice reception\n- ERP integration\n- Invoice validation before processing", "operationId": "extract_facturx_v1_extract_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_extract_facturx_v1_extract_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionResult" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/serialize": { "post": { "tags": [ "Advanced Integration" ], "summary": "Serialize Facturx", "description": "Business-Ready JSON Serialization (Pro Feature).\n\nTransforms XML data into normalized ERP integration JSON with fallback transparency.\n\n**Community Mode**: Not available - returns 403 with a link to obtain a license key.", "operationId": "serialize_facturx_v1_serialize_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_serialize_facturx_v1_serialize_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerializationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/merge": { "post": { "tags": [ "Core Workflows" ], "summary": "Merge Facturx", "description": "Embed an existing XML (Factur-X/ZUGFeRD/XRechnung) into a PDF container.\n\n**Community endpoint** - no license required.\n\nThis endpoint validates input constraints, but does not prove final PDF/A compliance of the produced file.\nUse /v1/validate on the output when PDF/A evidence is required.\n\nErrors:\n- **400** Bad file (not PDF or not XML)\n- **409** PDF already contains embedded Factur-X XML\n- **422** Input PDF is not declared PDF/A-3b, or XML fails EN 16931 validation", "operationId": "merge_facturx_v1_merge_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_merge_facturx_v1_merge_post" } } }, "required": true }, "responses": { "200": { "description": "Factur-X PDF with embedded XML (final PDF/A status not asserted)" }, "400": { "description": "Invalid file type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "PDF already contains Factur-X XML", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Input not PDF/A-3b or invalid XML", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/diagnostics": { "get": { "tags": [ "Operations" ], "summary": "Get Diagnostics", "description": "Get comprehensive system diagnostics.\n\nReturns detailed information about:\n- Application version and build info\n- Dependency versions\n- Runtime configuration\n- Environment details\n- Memory usage\n- Enabled features\n\nUsed for support and troubleshooting.", "operationId": "get_diagnostics_diagnostics_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnosticsResponse" } } } }, "401": { "description": "Missing or invalid diagnostics token" }, "403": { "description": "Diagnostics endpoint disabled or forbidden" } } } }, "/health": { "get": { "tags": [ "Operations" ], "summary": "Health Check", "description": "Liveness probe (Kubernetes).\n\nReturns 200 OK immediately if the HTTP server is responsive.\nThis endpoint is intentionally lightweight \u2014 no subprocess calls,\nno disk I/O \u2014 so it can be polled frequently without overhead.\n\nUse `/healthz` for a deeper readiness check.", "operationId": "health_check_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/healthz": { "get": { "tags": [ "Operations" ], "summary": "Readiness Check", "description": "Readiness probe (Kubernetes).\n\nReturns the status of each critical subsystem:\n- API process (always healthy if this responds)\n- VeraPDF / Saxon / custom JRE (present and executable)", "operationId": "readiness_check_healthz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/metrics": { "get": { "tags": [ "Operations" ], "summary": "Metrics Endpoint", "description": "Prometheus-compatible metrics endpoint.\n\nSecurity:\n- Community Edition: Disabled (HTTP 403).\n- Pro Edition: Disabled by default. Requires METRICS_ENABLED=true and METRICS_TOKEN=.", "operationId": "metrics_endpoint_metrics_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } } }, "components": { "schemas": { "AddressSchema": { "properties": { "line1": { "type": "string", "title": "Line1" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Line2" }, "city": { "type": "string", "title": "City" }, "postcode": { "type": "string", "title": "Postcode" }, "country_code": { "type": "string", "title": "Country Code" } }, "type": "object", "required": [ "line1", "city", "postcode", "country_code" ], "title": "AddressSchema", "description": "Normalized physical address." }, "Body_convert_to_facturx_v1_convert_post": { "properties": { "pdf": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Pdf", "description": "Original PDF invoice (Bring Your Own PDF)" }, "metadata": { "type": "string", "title": "Metadata", "description": "Invoice metadata as JSON" } }, "type": "object", "required": [ "pdf", "metadata" ], "title": "Body_convert_to_facturx_v1_convert_post" }, "Body_extract_facturx_v1_extract_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File", "description": "Factur-X PDF file to extract data from" } }, "type": "object", "required": [ "file" ], "title": "Body_extract_facturx_v1_extract_post" }, "Body_generate_facturx_xml_v1_xml_post": { "properties": { "metadata": { "type": "string", "title": "Metadata", "description": "Invoice metadata as JSON" } }, "type": "object", "required": [ "metadata" ], "title": "Body_generate_facturx_xml_v1_xml_post" }, "Body_merge_facturx_v1_merge_post": { "properties": { "pdf": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Pdf", "description": "PDF/A-3b input (without embedded XML)" }, "xml": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Xml", "description": "Factur-X/ZUGFeRD/XRechnung XML to embed" }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Format", "description": "Optional format override: factur-x, zugferd, or xrechnung" } }, "type": "object", "required": [ "pdf", "xml" ], "title": "Body_merge_facturx_v1_merge_post" }, "Body_serialize_facturx_v1_serialize_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File", "description": "Factur-X PDF or XML file to serialize" } }, "type": "object", "required": [ "file" ], "title": "Body_serialize_facturx_v1_serialize_post" }, "Body_validate_facturx_v1_validate_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File", "description": "Factur-X PDF or XML file to validate" }, "validate_pdfa": { "type": "boolean", "title": "Validate Pdfa", "description": "Run PDF/A-3b validation (VeraPDF). Allows bypassing for speed if PDF structure is already trusted. Pro only.", "default": true } }, "type": "object", "required": [ "file" ], "title": "Body_validate_facturx_v1_validate_post" }, "BusinessReadyInvoice": { "properties": { "invoice_number": { "type": "string", "title": "Invoice Number" }, "invoice_date": { "type": "string", "format": "date", "title": "Invoice Date" }, "due_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Due Date" }, "currency": { "type": "string", "title": "Currency", "default": "EUR" }, "buyer_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Buyer Reference", "description": "Buyer reference (BT-10)" }, "contract_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contract Reference", "description": "Contract reference (BT-12)" }, "seller": { "$ref": "#/components/schemas/PartySchema" }, "buyer": { "$ref": "#/components/schemas/PartySchema" }, "line_items": { "items": { "$ref": "#/components/schemas/LineItemSchema" }, "type": "array", "title": "Line Items" }, "tax_breakdown": { "items": { "$ref": "#/components/schemas/TaxBreakdownSchema" }, "type": "array", "title": "Tax Breakdown" }, "total_net_amount": { "type": "string", "title": "Total Net Amount" }, "total_tax_amount": { "type": "string", "title": "Total Tax Amount" }, "total_gross_amount": { "type": "string", "title": "Total Gross Amount" }, "amount_due": { "type": "string", "title": "Amount Due" }, "format": { "type": "string", "title": "Format", "description": "factur-x / zugferd / xrechnung / ubl" }, "profile": { "type": "string", "title": "Profile", "description": "minimum / basic / en16931 / extended / xrechnung_3.0" } }, "type": "object", "required": [ "invoice_number", "invoice_date", "seller", "buyer", "line_items", "tax_breakdown", "total_net_amount", "total_tax_amount", "total_gross_amount", "amount_due", "format", "profile" ], "title": "BusinessReadyInvoice", "description": "The 'Killer Feature' Pro Schema.\nFlattened, typed, and normalized for direct ERP consumption." }, "Buyer": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "registration_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registration Id" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Line1" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "postcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postcode" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "vat_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vat Number" } }, "type": "object", "title": "Buyer" }, "DependencyVersion": { "properties": { "name": { "type": "string", "title": "Name" }, "version": { "type": "string", "title": "Version" } }, "type": "object", "required": [ "name", "version" ], "title": "DependencyVersion", "description": "Dependency version info." }, "DiagnosticDetail": { "properties": { "rule_id": { "type": "string", "title": "Rule Id", "description": "EN 16931 rule ID (e.g., BR-CO-10)" }, "severity": { "type": "string", "title": "Severity", "description": "Severity: error, warning, info" }, "title": { "type": "string", "title": "Title", "description": "Short, actionable title" }, "explanation": { "type": "string", "title": "Explanation", "description": "Detailed explanation of the issue" }, "suggestion": { "type": "string", "title": "Suggestion", "description": "How to fix this issue" }, "context": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Context", "description": "Extracted values for debugging" } }, "type": "object", "required": [ "rule_id", "severity", "title", "explanation", "suggestion" ], "title": "DiagnosticDetail", "description": "A single diagnostic with human-readable explanation (Pro Feature)." }, "DiagnosticsResponse": { "properties": { "version": { "type": "string", "title": "Version", "description": "Application version (SemVer)" }, "git_hash": { "type": "string", "title": "Git Hash", "description": "Git commit hash" }, "build_date": { "type": "string", "title": "Build Date", "description": "Build date" }, "python_version": { "type": "string", "title": "Python Version", "description": "Python version" }, "dependencies": { "items": { "$ref": "#/components/schemas/DependencyVersion" }, "type": "array", "title": "Dependencies", "description": "Key dependency versions" }, "runtime_config": { "$ref": "#/components/schemas/RuntimeConfig", "description": "Runtime configuration" }, "environment": { "$ref": "#/components/schemas/EnvironmentInfo", "description": "Environment information" }, "memory_status": { "$ref": "#/components/schemas/MemoryStatus", "description": "Memory usage" }, "features_enabled": { "items": { "type": "string" }, "type": "array", "title": "Features Enabled", "description": "Enabled features" }, "uptime_seconds": { "type": "number", "title": "Uptime Seconds", "description": "Application uptime in seconds" } }, "type": "object", "required": [ "version", "git_hash", "build_date", "python_version", "dependencies", "runtime_config", "environment", "memory_status", "features_enabled", "uptime_seconds" ], "title": "DiagnosticsResponse", "description": "Complete diagnostics response." }, "EnvironmentInfo": { "properties": { "os": { "type": "string", "title": "Os", "description": "Operating system" }, "architecture": { "type": "string", "title": "Architecture", "description": "CPU architecture" }, "python_version": { "type": "string", "title": "Python Version", "description": "Python version" }, "hostname": { "type": "string", "title": "Hostname", "description": "Host machine name" } }, "type": "object", "required": [ "os", "architecture", "python_version", "hostname" ], "title": "EnvironmentInfo", "description": "Environment fingerprint." }, "ErrorDetail": { "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "code", "message" ], "title": "ErrorDetail" }, "ExtractionResult": { "properties": { "format_detected": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Format Detected" }, "profile_detected": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Profile Detected" }, "xml_extracted": { "type": "boolean", "title": "Xml Extracted" }, "invoice_json": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceJson" }, { "type": "null" } ] }, "errors": { "items": { "$ref": "#/components/schemas/ErrorDetail" }, "type": "array", "title": "Errors", "default": [] } }, "type": "object", "required": [ "xml_extracted" ], "title": "ExtractionResult" }, "FallbackApplied": { "properties": { "field": { "type": "string", "title": "Field", "description": "Stable invoice dot-path (for example: invoice.seller.address.country_code)" }, "fallback_type": { "type": "string", "enum": [ "default_value", "placeholder_value", "derived_value", "coercion", "xml_parser_recovery", "line_skipped", "line_truncated" ], "title": "Fallback Type" }, "original_state": { "type": "string", "enum": [ "missing", "invalid", "malformed", "unparseable", "truncated" ], "title": "Original State" }, "applied_value": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "title": "Applied Value", "description": "Applied scalar value (or null when no value was injected)." } }, "type": "object", "required": [ "field", "fallback_type", "original_state" ], "title": "FallbackApplied", "description": "Single fallback operation applied during /serialize processing." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InvoiceJson": { "properties": { "invoice_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invoice Number" }, "invoice_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invoice Date" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due Date" }, "document_type_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Type Code" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "buyer_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Buyer Reference" }, "contract_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contract Reference" }, "seller": { "anyOf": [ { "$ref": "#/components/schemas/Seller" }, { "type": "null" } ] }, "buyer": { "anyOf": [ { "$ref": "#/components/schemas/Buyer" }, { "type": "null" } ] }, "totals": { "anyOf": [ { "$ref": "#/components/schemas/Totals" }, { "type": "null" } ] }, "tax_breakdown": { "items": { "$ref": "#/components/schemas/TaxBreakdownItem" }, "type": "array", "title": "Tax Breakdown", "default": [] }, "line_items": { "items": { "$ref": "#/components/schemas/LineItem" }, "type": "array", "title": "Line Items", "default": [] } }, "additionalProperties": true, "type": "object", "title": "InvoiceJson" }, "LineItem": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "quantity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quantity" }, "unit_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unit Code" }, "unit_price": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unit Price" }, "vat_rate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vat Rate" }, "line_total": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Line Total" } }, "type": "object", "title": "LineItem" }, "LineItemSchema": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "quantity": { "type": "string", "title": "Quantity" }, "unit_code": { "type": "string", "title": "Unit Code", "description": "UN/ECE Rec 20 unit code (e.g., C62, HUR)" }, "unit_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unit Label", "description": "Human readable unit (e.g., piece, hour)" }, "net_price": { "type": "string", "title": "Net Price", "description": "Net unit price" }, "line_total": { "type": "string", "title": "Line Total", "description": "Net line total (Qty * Price)" }, "vat_rate": { "type": "string", "title": "Vat Rate", "description": "VAT percentage (e.g., 20.00)" }, "vat_category": { "type": "string", "title": "Vat Category", "description": "VAT category code (EN 16931)", "default": "S" } }, "type": "object", "required": [ "name", "quantity", "unit_code", "net_price", "line_total", "vat_rate" ], "title": "LineItemSchema", "description": "High-precision invoice line item." }, "MemoryStatus": { "properties": { "total_mb": { "type": "number", "title": "Total Mb", "description": "Total system memory in MB" }, "available_mb": { "type": "number", "title": "Available Mb", "description": "Available memory in MB" }, "process_mb": { "type": "number", "title": "Process Mb", "description": "Current process memory in MB" }, "percent_used": { "type": "number", "title": "Percent Used", "description": "System memory usage percentage" } }, "type": "object", "required": [ "total_mb", "available_mb", "process_mb", "percent_used" ], "title": "MemoryStatus", "description": "Memory usage approximation." }, "PartySchema": { "properties": { "name": { "type": "string", "title": "Name", "description": "Legal company name" }, "vat_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vat Number", "description": "VAT ID with country prefix" }, "registration_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registration Id", "description": "Trade registration number" }, "address": { "anyOf": [ { "$ref": "#/components/schemas/AddressSchema" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" } }, "type": "object", "required": [ "name" ], "title": "PartySchema", "description": "Normalized party (Seller/Buyer) representation." }, "ProValidationResult": { "properties": { "valid": { "type": "boolean", "title": "Valid", "description": "Whether the file is valid" }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Format", "description": "Detected format" }, "flavor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flavor", "description": "Detected profile" }, "error_count": { "type": "integer", "title": "Error Count", "description": "Total number of errors" }, "warning_count": { "type": "integer", "title": "Warning Count", "description": "Total number of warnings", "default": 0 }, "diagnostics": { "items": { "$ref": "#/components/schemas/DiagnosticDetail" }, "type": "array", "title": "Diagnostics", "description": "Smart diagnostics with explanations" }, "validation_mode": { "type": "string", "title": "Validation Mode", "description": "Always 'pro_diagnostics' for this response type", "default": "pro_diagnostics" }, "pdfa_valid": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pdfa Valid", "description": "PDF/A-3b compliance (null if input was raw XML or VeraPDF unavailable)" }, "validation_completeness": { "type": "string", "title": "Validation Completeness", "description": "full if all applicable layers ran, partial if some were skipped", "default": "full" }, "layers_executed": { "items": { "type": "string" }, "type": "array", "title": "Layers Executed", "description": "Validation layers that actually ran" }, "layers_skipped": { "items": { "$ref": "#/components/schemas/SkippedLayer" }, "type": "array", "title": "Layers Skipped", "description": "Validation layers that were skipped with reasons" } }, "type": "object", "required": [ "valid", "error_count" ], "title": "ProValidationResult", "description": "Enhanced validation result with Smart Diagnostics (Pro Feature)." }, "ProblemDetails": { "properties": { "type": { "type": "string", "title": "Type", "description": "A URI reference that identifies the problem type.", "default": "about:blank" }, "title": { "type": "string", "title": "Title", "description": "A short, human-readable summary of the problem type." }, "status": { "type": "integer", "title": "Status", "description": "The HTTP status code generated by the origin server for this occurrence of the problem." }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail", "description": "A human-readable explanation specific to this occurrence of the problem." }, "instance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instance", "description": "A URI reference that identifies the specific occurrence of the problem." }, "extensions": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Extensions", "description": "Additional problem details specific to the API." } }, "type": "object", "required": [ "title", "status" ], "title": "ProblemDetails", "description": "RFC 9457 standard error response format.\nhttps://www.rfc-editor.org/rfc/rfc9457.html" }, "RuntimeConfig": { "properties": { "mode": { "type": "string", "title": "Mode", "description": "Runtime mode (development/production)" }, "workers": { "type": "integer", "title": "Workers", "description": "Number of worker processes", "default": 1 }, "max_upload_size_mb": { "type": "integer", "title": "Max Upload Size Mb", "description": "Maximum upload size in MB", "default": 10 } }, "type": "object", "required": [ "mode" ], "title": "RuntimeConfig", "description": "Runtime configuration." }, "Seller": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "registration_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registration Id" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Line1" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "postcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postcode" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "vat_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vat Number" } }, "type": "object", "title": "Seller" }, "SerializationResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "schema_version": { "type": "string", "title": "Schema Version", "description": "Semantic version of the BusinessReadyInvoice schema. Minor bumps = new optional fields. Major bumps = breaking changes.", "default": "1.0.0" }, "engine_version": { "type": "string", "title": "Engine Version", "description": "Factur-X Engine version that produced this response.", "default": "0.0.0" }, "invoice": { "anyOf": [ { "$ref": "#/components/schemas/BusinessReadyInvoice" }, { "type": "null" } ] }, "xml_recovery_applied": { "type": "boolean", "title": "Xml Recovery Applied", "description": "True when XML parser recovery mode had to repair malformed XML.", "default": false }, "fallbacks_applied": { "items": { "$ref": "#/components/schemas/FallbackApplied" }, "type": "array", "title": "Fallbacks Applied", "description": "Transparent list of fallback operations applied during serialization." }, "errors": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array", "title": "Errors" } }, "type": "object", "required": [ "success" ], "title": "SerializationResponse", "description": "Response model for the /serialize endpoint." }, "SkippedLayer": { "properties": { "layer": { "type": "string", "title": "Layer", "description": "Layer name (xsd, schematron, pdfa3b, br_fr_ctc)" }, "reason": { "type": "string", "title": "Reason", "description": "Why this layer was skipped (e.g. tool_missing:saxon_jar)" } }, "type": "object", "required": [ "layer", "reason" ], "title": "SkippedLayer", "description": "A validation layer that was skipped, with the reason why." }, "TaxBreakdownItem": { "properties": { "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "vat_rate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vat Rate" }, "basis_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Basis Amount" }, "tax_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tax Amount" } }, "type": "object", "title": "TaxBreakdownItem" }, "TaxBreakdownSchema": { "properties": { "category": { "type": "string", "title": "Category" }, "rate": { "type": "string", "title": "Rate" }, "basis_amount": { "type": "string", "title": "Basis Amount" }, "tax_amount": { "type": "string", "title": "Tax Amount" } }, "type": "object", "required": [ "category", "rate", "basis_amount", "tax_amount" ], "title": "TaxBreakdownSchema", "description": "Normalized tax breakdown per category/rate." }, "Totals": { "properties": { "net_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Amount" }, "tax_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tax Amount" }, "gross_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gross Amount" }, "payable_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payable Amount" } }, "type": "object", "title": "Totals" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ValidationErrorDetail": { "properties": { "rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rule Id", "description": "Rule identifier (e.g. BR-CO-10)" }, "message": { "type": "string", "title": "Message", "description": "Error message" }, "severity": { "type": "string", "title": "Severity", "description": "error or warning", "default": "error" } }, "type": "object", "required": [ "message" ], "title": "ValidationErrorDetail", "description": "Structured validation error for Community Edition." }, "ValidationResult": { "properties": { "valid": { "type": "boolean", "title": "Valid", "description": "Whether the file is valid" }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Format", "description": "Detected format (factur-x, zugferd, ubl)" }, "flavor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flavor", "description": "Detected flavor/level" }, "errors": { "items": { "$ref": "#/components/schemas/ValidationErrorDetail" }, "type": "array", "title": "Errors", "description": "List of validation errors" }, "validation_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Validation Mode", "description": "Validation mode" }, "pdfa_valid": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pdfa Valid", "description": "PDF/A-3b compliance (null if input was raw XML or VeraPDF unavailable)" }, "validation_completeness": { "type": "string", "title": "Validation Completeness", "description": "full if all applicable layers ran, partial if some were skipped", "default": "full" }, "layers_executed": { "items": { "type": "string" }, "type": "array", "title": "Layers Executed", "description": "Validation layers that actually ran (xsd, schematron, pdfa3b, br_fr_ctc)" }, "layers_skipped": { "items": { "$ref": "#/components/schemas/SkippedLayer" }, "type": "array", "title": "Layers Skipped", "description": "Validation layers that were skipped with reasons" } }, "type": "object", "required": [ "valid" ], "title": "ValidationResult", "description": "Validation result response." } } }, "tags": [ { "name": "Core Workflows", "description": "The four primary e-invoicing operations: validate, generate XML, merge PDF+XML, and extract data from received invoices." }, { "name": "Advanced Integration", "description": "ERP serialization (Pro) and convenience conversion shortcuts for advanced integrations." }, { "name": "Operations", "description": "Health probes, readiness checks, diagnostics, and Prometheus metrics." } ] }