{
  "openapi": "3.1.0",
  "info": {
    "title": "VeriFactura Stateless Normative Verification & MCP API",
    "version": "0.2.0",
    "summary": "Zero-custody Pure-Rust European e-invoice verification API (EN 16931, Factur-X, ZUGFeRD 2.2, XRechnung 3.0.2, UBL 2.1, PDF/A-3b) and Streamable HTTP MCP server.",
    "description": "Stateless HTTP REST and Model Context Protocol (MCP) endpoints powered by pure-Rust W3C XSD 1.1, fixed-point EN 16931-1, XPath 3.1 ISO Schematron (CEN, Factur-X, France AFNOR XP Z12-012, Germany KoSIT XRechnung 3.0.2), and binary ISO 19005-3 PDF/A-3b inspection. All uploaded bytes are evaluated strictly in volatile RAM and discarded immediately upon response serialization.",
    "contact": {
      "name": "OpenEuroTech",
      "url": "https://verifactura.eu/api"
    },
    "license": {
      "name": "Proprietary Free Public Utility (EUR 0, Zero Registration)",
      "url": "https://verifactura.eu/privacy"
    }
  },
  "servers": [
    {
      "url": "https://verifactura.eu",
      "description": "Production Stateless Verification Server"
    },
    {
      "url": "http://127.0.0.1:3001",
      "description": "Local Self-Hosted Companion Server (./run.sh)"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check server liveness and advertised API/MCP endpoints",
        "tags": [
          "System"
        ],
        "responses": {
          "200": {
            "description": "Server is healthy and ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/engines": {
      "get": {
        "operationId": "listNormativeEngines",
        "summary": "List active Rust verification engines, schema versions, and upload limits",
        "tags": [
          "Verification"
        ],
        "responses": {
          "200": {
            "description": "Active verification engine catalog and embedded schema counts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnginesCatalogResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/verify": {
      "post": {
        "operationId": "verifyDocument",
        "summary": "Verify a hybrid PDF/A-3 e-invoice or raw CII/UBL XML document in volatile RAM",
        "description": "Accepts either `multipart/form-data` (field `file`, `document`, or `invoice`) or raw binary/XML request bodies (`application/pdf`, `application/xml`, `text/xml`, `application/octet-stream`) up to 15 MiB. Never writes uploaded documents to disk.",
        "tags": [
          "Verification"
        ],
        "parameters": [
          {
            "name": "checks",
            "in": "query",
            "required": false,
            "description": "Comma-separated engine filter (`all`, `xsd`, `en16931`, `cen`, `facturx`, `fr`, `de`, `pdfa3`). Defaults to automatic profile-aware selection; pass `all` to force French XP Z12-012 and German XRechnung 3.0.2 CIUS checks simultaneously.",
            "schema": {
              "type": "string",
              "example": "all"
            }
          },
          {
            "name": "includeSvrl",
            "in": "query",
            "required": false,
            "description": "When `true`, includes an OASIS Schematron Validation Report Language (`svrlXml`) document in the response.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "X-File-Name",
            "in": "header",
            "required": false,
            "description": "Optional original filename hint when posting raw binary or XML payloads without multipart form-data.",
            "schema": {
              "type": "string",
              "example": "factur-x.pdf"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Hybrid PDF/A-3 invoice or raw CII/UBL XML file (max 15 MiB)."
                  }
                }
              }
            },
            "application/xml": {
              "schema": {
                "type": "string",
                "description": "Raw UN/CEFACT CII D16B or OASIS UBL 2.1 XML invoice."
              }
            },
            "text/xml": {
              "schema": {
                "type": "string"
              }
            },
            "application/pdf": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normative verification completed (check `isValid` and `status` in response payload).",
            "headers": {
              "X-Data-Custody": {
                "schema": {
                  "type": "string",
                  "const": "stateless-in-memory-discarded"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store, no-cache, must-revalidate"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NormativeAuditResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request, empty payload, or unknown `checks` selector.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Uploaded file exceeds the 15 MiB maximum payload limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Sliding-window rate limit (60 requests/minute/IP) exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the next verification slot becomes available.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "get": {
        "operationId": "getMcpDiscovery",
        "summary": "Discover MCP server capabilities and available tools",
        "tags": [
          "MCP"
        ],
        "responses": {
          "200": {
            "description": "Stateless MCP server metadata and tool summary.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postMcpJsonRpc",
        "summary": "Model Context Protocol (MCP) Streamable HTTP JSON-RPC 2.0 endpoint",
        "description": "Supports MCP JSON-RPC 2.0 methods `initialize`, `notifications/initialized`, `ping`, `tools/list`, and `tools/call` (`verify_einvoice`, `list_normative_engines`).",
        "tags": [
          "MCP"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response.",
            "headers": {
              "X-Data-Custody": {
                "schema": {
                  "type": "string",
                  "const": "stateless-in-memory-discarded"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "202": {
            "description": "JSON-RPC 2.0 notification accepted with no response body."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "required": [
          "status",
          "app",
          "version",
          "protocol",
          "normativeApi",
          "enginesApi",
          "mcpEndpoint",
          "openApiSpec"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "ok"
          },
          "app": {
            "type": "string",
            "example": "VeriFactura"
          },
          "version": {
            "type": "string",
            "example": "0.1.0"
          },
          "protocol": {
            "type": "integer",
            "example": 1
          },
          "origin": {
            "type": "string"
          },
          "normativeApi": {
            "type": "string",
            "example": "/api/v1/verify"
          },
          "enginesApi": {
            "type": "string",
            "example": "/api/v1/engines"
          },
          "mcpEndpoint": {
            "type": "string",
            "example": "/mcp"
          },
          "openApiSpec": {
            "type": "string",
            "example": "/openapi.json"
          }
        }
      },
      "EnginesCatalogResponse": {
        "type": "object",
        "required": [
          "app",
          "serverVersion",
          "custodyPolicy",
          "maxUploadBytes",
          "rateLimitPerMinute",
          "embeddedSchemaFiles",
          "engines"
        ],
        "properties": {
          "app": {
            "type": "string"
          },
          "serverVersion": {
            "type": "string"
          },
          "custodyPolicy": {
            "type": "string"
          },
          "maxUploadBytes": {
            "type": "integer",
            "example": 15728640
          },
          "rateLimitPerMinute": {
            "type": "integer",
            "example": 60
          },
          "embeddedSchemaFiles": {
            "type": "integer"
          },
          "engines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EngineDescriptor"
            }
          }
        }
      },
      "EngineDescriptor": {
        "type": "object",
        "required": [
          "id",
          "name",
          "standard",
          "version",
          "implementation"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "standard": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "implementation": {
            "type": "string"
          }
        }
      },
      "NormativeAuditResponse": {
        "type": "object",
        "required": [
          "isValid",
          "recommendation",
          "sha256",
          "byteLength",
          "durationMs",
          "inspectedAt",
          "custodyPolicy",
          "attribution",
          "containerType",
          "engines",
          "violations"
        ],
        "properties": {
          "isValid": {
            "type": "boolean"
          },
          "recommendation": {
            "type": "string",
            "enum": [
              "ACCEPT",
              "ACCEPT_WITH_WARNINGS",
              "REJECT"
            ]
          },
          "sha256": {
            "type": "string"
          },
          "fileName": {
            "type": [
              "string",
              "null"
            ]
          },
          "byteLength": {
            "type": "integer"
          },
          "durationMs": {
            "type": "integer"
          },
          "inspectedAt": {
            "type": "string",
            "format": "date-time"
          },
          "custodyPolicy": {
            "type": "string",
            "example": "stateless-in-memory-discarded"
          },
          "attribution": {
            "type": "string"
          },
          "containerType": {
            "type": "string"
          },
          "detectedSyntax": {
            "type": [
              "string",
              "null"
            ]
          },
          "detectedProfile": {
            "type": [
              "string",
              "null"
            ]
          },
          "identity": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "invoiceNumber": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "issueDate": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sellerName": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "engines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EngineResult"
            }
          },
          "violations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NormativeViolation"
            }
          },
          "svrlXml": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "EngineResult": {
        "type": "object",
        "required": [
          "id",
          "name",
          "version",
          "status",
          "rulesEvaluated",
          "passedCount",
          "failedCount",
          "warningCount",
          "durationMs"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PASSED",
              "FAILED",
              "SKIPPED"
            ]
          },
          "rulesEvaluated": {
            "type": "integer"
          },
          "passedCount": {
            "type": "integer"
          },
          "failedCount": {
            "type": "integer"
          },
          "warningCount": {
            "type": "integer"
          },
          "durationMs": {
            "type": "integer"
          },
          "skipReason": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "NormativeViolation": {
        "type": "object",
        "required": [
          "code",
          "engine",
          "severity",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "engine": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "FATAL",
              "WARNING",
              "INFO"
            ]
          },
          "clauseOrTerm": {
            "type": [
              "string",
              "null"
            ]
          },
          "message": {
            "type": "string"
          },
          "location": {
            "type": [
              "string",
              "null"
            ]
          },
          "expected": {
            "type": [
              "string",
              "null"
            ]
          },
          "actual": {
            "type": [
              "string",
              "null"
            ]
          },
          "hint": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ApiErrorResponse": {
        "type": "object",
        "required": [
          "error",
          "custodyPolicy"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "status"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "status": {
                "type": "integer"
              }
            }
          },
          "custodyPolicy": {
            "type": "string"
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ]
          },
          "method": {
            "type": "string",
            "example": "tools/call"
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ]
          },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "error": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  }
}