{
  "openapi": "3.0.3",
  "info": {
    "title": "VOL (On-Line Verifier) API",
    "version": "1.0",
    "description": "OpenAPI specification generated from the provided VOL documentation.\n\n**Authentication**\nAll endpoints are protected by token-based authentication via the `Authorization` header:\n`Authorization: token <token-value>`.\n\n**Base URL**\nAll paths below are relative to:\n`https://{address}/api`\n\n**Caching**\nUploaded documents are kept in cache for a configurable time window. After expiry, the document\nis deleted and must be uploaded again.\n"
  },
  "servers": [
    {
      "url": "https://{address}/api",
      "variables": {
        "address": {
          "default": "example.com",
          "description": "FQDN (or host:port) where VOL is deployed"
        }
      }
    }
  ],
  "security": [
    {
      "AuthToken": []
    }
  ],
  "tags": [
    {
      "name": "Documents",
      "description": "Upload and operate on signed documents"
    },
    {
      "name": "Administration",
      "description": "Admin-only operations (requires an administrator token)"
    }
  ],
  "paths": {
    "/documents/": {
      "post": {
        "tags": [
          "Documents"
        ],
        "summary": "Upload document",
        "description": "Upload a signed document to the system in order to run subsequent operations (signature report, verification, content extraction, etc.).\n\nYou can upload:\n* **a single signed file** (embedded signature), or\n* **two separate files**: the main document plus a **detached signature**.\n\nThe request must be `multipart/form-data`.\n\nNotes:\n* The optional `verification_date` fixes the verification date used by VOL; if omitted VOL chooses a date depending on the verification profile.\n",
        "operationId": "uploadDocument",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "document"
                ],
                "properties": {
                  "document": {
                    "type": "string",
                    "format": "binary",
                    "description": "Main document to upload (must be signed when using embedded signatures)"
                  },
                  "content": {
                    "type": "string",
                    "format": "binary",
                    "description": "Detached signature (optional). If omitted, VOL searches for the signature inside `document`."
                  },
                  "verification_date": {
                    "type": "string",
                    "description": "Verification date to be used by VOL.\nThe documentation describes this as a form field named `verification_date`.\n",
                    "example": "2017-12-20T11:46:36.862950"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Document uploaded successfully",
            "headers": {
              "location": {
                "description": "Relative URL of the uploaded document (contains the unique `document-id`)",
                "schema": {
                  "type": "string",
                  "example": "/documents/e4d13719410fae2f"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadDocumentResponse"
                },
                "examples": {
                  "ok": {
                    "value": {
                      "code": "201 Created",
                      "location": "/documents/e4d13719410fae2f"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request (multipart parsing / invalid boundary)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidBoundary": {
                    "value": {
                      "title": "Error parsing file",
                      "description": "Invalid boundary in multipart form:''"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "502": {
            "$ref": "#/components/responses/BadGatewayHtml"
          }
        }
      }
    },
    "/documents/{document-id}/": {
      "get": {
        "tags": [
          "Documents"
        ],
        "summary": "Get document",
        "description": "Retrieve the originally uploaded document content.\nThe returned content is **exactly** the same as the originally uploaded file.\n\nNote: On success, the server response does **not** include a filename header; the client must decide a filename.\n",
        "operationId": "getDocument",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentId"
          }
        ],
        "responses": {
          "200": {
            "description": "Original document bytes",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/documents/{document-id}/report": {
      "get": {
        "tags": [
          "Documents"
        ],
        "summary": "Get signature structure",
        "description": "Get the signature structure affixed to the uploaded document (**CAdES only**) as a JSON report.\n\nThe returned object includes:\n* `code`: HTTP status as string (e.g. `\"200 OK\"`)\n* `result.report`: the signature structure\n* `result.errors`: list of errors (empty array when none)\n\nSee the schemas section for a practical, navigable structure (kept permissive because the report can be large and varies by signature).\n",
        "operationId": "getSignatureReport",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentId"
          }
        ],
        "responses": {
          "200": {
            "description": "Signature structure report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignatureReportEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/BadGatewayHtml"
          }
        }
      }
    },
    "/documents/{document-id}/content": {
      "get": {
        "tags": [
          "Documents"
        ],
        "summary": "Get extracted content",
        "description": "Return the extracted (unsigned) content of a previously uploaded document.\n\nThe returned bytes depend on the signature type:\n* For **CAdES/XAdES**: returns the original document *without* the signature.\n* For **PAdES**: returns the uploaded signed PDF (as described by the documentation UI behavior).\n\n**Dependency**\nThis method must be invoked *after* running verification (`GET /documents/{document-id}/verify/report`),\nbecause VOL does not extract content until signature verification is performed.\n\nIf invoked before verification, VOL returns `502 Bad Gateway` with an HTML error page.\n",
        "operationId": "getDocumentContent",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentId"
          }
        ],
        "responses": {
          "200": {
            "description": "Extracted document content bytes",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/BadGatewayHtml"
          }
        }
      }
    },
    "/documents/{document-id}/verify/report": {
      "get": {
        "tags": [
          "Documents"
        ],
        "summary": "Verify document and get report",
        "description": "Verify a previously uploaded document and return a verification report.\n\nThe output depends on query parameters:\n* `type=json` and `template=report` → JSON report\n* `type=rml` and `template=report` → PDF report encoded as **base64**\n* `lang` → ISO 3166-1 alpha-2 country codes to choose the language (defaults to system language)\n\nNote: The documentation examples show that if parameters are omitted, the service may return an HTML report;\nthis spec models the documented JSON/base64 outputs and also allows `text/html` as a fallback.\n",
        "operationId": "verifyDocument",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentId"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Output type (e.g. `json`, `rml`)",
            "example": "json"
          },
          {
            "name": "template",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Report template (e.g. `report`)",
            "example": "report"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            },
            "description": "Language code (ISO 3166-1 alpha-2)",
            "example": "it"
          }
        ],
        "responses": {
          "200": {
            "description": "Verification report (JSON) or base64-encoded PDF (or HTML fallback)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationReport"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Base64-encoded PDF report (when `type=rml` and `template=report`)"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string",
                  "description": "HTML report (may be returned by the service depending on configuration/parameters)"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request (e.g. invalid language, unknown report type)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unknownType": {
                    "value": {
                      "code": "404 Not Found",
                      "description": "Unknow report type"
                    }
                  },
                  "invalidLanguage": {
                    "value": {
                      "message": "Invalid language. Languages supported are: [ 'it', 'en' ]"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/BadGatewayHtml"
          }
        }
      }
    },
    "/admin/certificates/": {
      "post": {
        "tags": [
          "Administration"
        ],
        "summary": "Upload CA certificate",
        "description": "Upload (add) a Certification Authority (CA) certificate to the system.\n\nThis operation is intended to add a CA that is not present among the trusted ones already configured.\nRequires a token with **administrator** privileges.\n\nBody is `application/json` and contains:\n* `certificate`: the certificate to add (typically base64 / PEM content as a string, per examples)\n* `tags` (optional): object with any of: `chain`, `trusted`, `tsa`\n",
        "operationId": "addCaCertificate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddCaCertificateRequest"
              },
              "examples": {
                "add": {
                  "value": {
                    "certificate": "MIIF...base64...",
                    "tags": {
                      "trusted": {},
                      "chain": {},
                      "tsa": {}
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CA certificate added successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CaCertificateAdditionReport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "502": {
            "$ref": "#/components/responses/BadGatewayHtml"
          }
        }
      },
      "get": {
        "tags": [
          "Administration"
        ],
        "summary": "Get CA certificates",
        "description": "Retrieve the CA certificates stored on the system as a paginated JSON report.\nRequires a token with **administrator** privileges.\n\nFiltering parameters are modeled as query parameters (the documentation lists them as \"in the request body\",\nbut for HTTP GET they are typically passed as query parameters).\n",
        "operationId": "listCaCertificates",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Page number (pagination)"
          },
          {
            "name": "where_subject",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by any string in the certificate Subject"
          },
          {
            "name": "where_issuer",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by any string in the certificate Issuer"
          },
          {
            "name": "where_cert_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by any string in the Certificate ID"
          },
          {
            "name": "where_serial_number",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by any string in the Certificate SerialNumber"
          },
          {
            "name": "where_not_before",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "ISO 8601 datetime (%Y-%m-%dT%H:%M:%S.%fZ)"
            },
            "description": "Minimum validity date (ISO 8601)",
            "example": "2013-06-05T17:35:47.000Z"
          },
          {
            "name": "where_not_after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Maximum validity date (ISO 8601)",
            "example": "2043-06-05T17:35:47.000Z"
          },
          {
            "name": "where_tags",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by tags associated with the certificate"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of CA certificates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CaCertificateRetrievalReport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "502": {
            "$ref": "#/components/responses/BadGatewayHtml"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AuthToken": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Token-based authentication header.\n\nExample:\n`Authorization: token 0540c6085962614ab245e07963d9aa68`\n"
      }
    },
    "parameters": {
      "DocumentId": {
        "name": "document-id",
        "in": "path",
        "required": true,
        "description": "Unique document identifier returned by upload (hexadecimal)",
        "schema": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]+$"
        },
        "example": "e4d13719410fae2f"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized (invalid or missing token)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidToken": {
                "value": {
                  "title": "401 Unauthorized",
                  "description": "Invalid Token"
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found (document expired/missing or wrong id)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/NotFoundResponse"
            },
            "examples": {
              "notFound": {
                "value": {
                  "code": "404 Not Found"
                }
              }
            }
          }
        }
      },
      "BadGatewayHtml": {
        "description": "Upstream/service error (HTML body)",
        "content": {
          "text/html": {
            "schema": {
              "type": "string",
              "description": "HTML error page"
            }
          }
        }
      }
    },
    "schemas": {
      "UploadDocumentResponse": {
        "type": "object",
        "required": [
          "code",
          "location"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "201 Created"
          },
          "location": {
            "type": "string",
            "description": "Relative URL to access the uploaded document (contains `document-id`)",
            "example": "/documents/e4d13719410fae2f"
          }
        }
      },
      "NotFoundResponse": {
        "type": "object",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "404 Not Found"
          },
          "description": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Generic error payload (shape varies by endpoint)",
        "additionalProperties": true,
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SignatureReportEnvelope": {
        "type": "object",
        "required": [
          "code",
          "result"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "200 OK"
          },
          "result": {
            "type": "object",
            "required": [
              "report",
              "errors"
            ],
            "properties": {
              "report": {
                "$ref": "#/components/schemas/SignatureStructure"
              },
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          }
        }
      },
      "SignatureStructure": {
        "type": "object",
        "description": "Signature structure for CAdES signatures (CMS SignedData-oriented).\nThe exact structure can be large and depends on the signature contents; the schema is permissive but documents key parts.\n",
        "additionalProperties": true,
        "properties": {
          "content_type": {
            "type": "string",
            "description": "OID of the content (e.g. SignedData OID)",
            "example": "1.2.840.113549.1.7.2"
          },
          "content_name": {
            "type": "string",
            "description": "Common name associated with the OID",
            "example": "signedData"
          },
          "content": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "where": {
            "type": "string",
            "description": "JSON path / identifier of where the error occurred"
          },
          "what": {
            "type": "string",
            "description": "Error identifier key (can be mapped via `messages` in verification report)"
          }
        }
      },
      "VerificationReport": {
        "type": "object",
        "description": "Verification report object returned by `GET /documents/{document-id}/verify/report` when `type=json`.\nThe documentation shows a rich structure with report metadata, validation results, profiles, and localized messages.\n",
        "additionalProperties": true,
        "properties": {
          "report": {
            "type": "object",
            "additionalProperties": true,
            "description": "High-level report info (e.g. now, type, document_uri, signed_data, ...)"
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            }
          },
          "content": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "Present for nested (matrioska) signatures"
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Upload/processing metadata (lang, upload_time, documentid, document_hash, ...)"
          },
          "messages": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Localized message map, keyed by error identifiers"
          },
          "validation": {
            "type": "object",
            "additionalProperties": true,
            "description": "Validation details (signatures[], timestamps[], ...)"
          }
        }
      },
      "AddCaCertificateRequest": {
        "type": "object",
        "required": [
          "certificate"
        ],
        "additionalProperties": false,
        "properties": {
          "certificate": {
            "type": "string",
            "description": "Certificate content (as string, e.g. base64/PEM as provided by clients)"
          },
          "tags": {
            "type": "object",
            "description": "Optional tags to classify the certificate",
            "additionalProperties": true,
            "properties": {
              "chain": {
                "type": "object",
                "additionalProperties": true
              },
              "trusted": {
                "type": "object",
                "additionalProperties": true
              },
              "tsa": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "CaCertificateAdditionReport": {
        "type": "object",
        "description": "Report returned after adding a CA certificate",
        "additionalProperties": true,
        "properties": {
          "data": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "hash": {
                "type": "string",
                "nullable": true
              },
              "certificate": {
                "type": "string"
              },
              "tags": {
                "type": "object",
                "additionalProperties": true
              },
              "not_before": {
                "$ref": "#/components/schemas/CertValidityTime"
              },
              "not_after": {
                "$ref": "#/components/schemas/CertValidityTime"
              },
              "cert_id": {
                "type": "string"
              },
              "serial_number": {
                "type": "string"
              },
              "subject": {
                "type": "string"
              },
              "issuer": {
                "type": "string"
              }
            }
          }
        }
      },
      "CaCertificateRetrievalReport": {
        "type": "object",
        "description": "Paginated report returned when listing CA certificates",
        "additionalProperties": true,
        "properties": {
          "pagination": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "count": {
                "type": "integer"
              },
              "next": {
                "type": "string",
                "nullable": true
              },
              "page": {
                "type": "integer"
              },
              "pages": {
                "type": "integer"
              },
              "previus": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "status": {
                "type": "string",
                "example": "200 OK"
              }
            }
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CaCertificateItem"
            }
          }
        }
      },
      "CaCertificateItem": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "hash": {
            "type": "string",
            "nullable": true
          },
          "certificate": {
            "type": "string"
          },
          "tags": {
            "type": "object",
            "additionalProperties": true
          },
          "not_before": {
            "$ref": "#/components/schemas/CertValidityTime"
          },
          "not_after": {
            "$ref": "#/components/schemas/CertValidityTime"
          },
          "cert_id": {
            "type": "string"
          },
          "serial_number": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "issuer": {
            "type": "string"
          }
        }
      },
      "CertValidityTime": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "option": {
            "type": "string",
            "description": "ASN.1 time option (GENERAL_TIME or UTC_TIME)",
            "example": "UTC_TIME"
          },
          "utc": {
            "type": "boolean",
            "description": "True if time is UTC-based"
          },
          "value": {
            "type": "string",
            "description": "ISO 8601 datetime",
            "example": "2043-06-05T17:35:47"
          }
        }
      }
    }
  }
}