{
  "openapi": "3.0.3",
  "info": {
    "title": "SignBox",
    "version": "2.0",
    "description": "\nThis document describes the SignBox API interface that can be used by an external system to complete a Digital Signature.\nThe SignBox APIs are included into the remote signature server where is also installed the SmartUP component.\n\nTo use any of the functionalities described, it is needed to send a POST message to the resource: the input parameters\nof the function will be the POST input parameters.\n\nREST endpoint pattern:\n  `http://{SMARTSEC}/api/{resource}`\nwhere `SMARTSEC` is the SignBox domain name and `resource` is the API to call.\n\nPolling / result retrieval\n\nThe response to POST messages returns a job ID (for function `sign`). You can poll the operation progress status with:\n  `GET http://{SMARTSEC}/api/job/{jobId}`\n\nIf the response returns status `\"done\"`, for 60 seconds it is possible to get the operation results with:\n  `GET http://{SMARTSEC}/api/result/{jobId}`\n"
  },
  "servers": [
    {
      "url": "http://{SMARTSEC}",
      "description": "SignBox domain (HTTP)",
      "variables": {
        "SMARTSEC": {
          "default": "example.com",
          "description": "SignBox domain name"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Echo",
      "description": "Echo test function"
    },
    {
      "name": "Sign",
      "description": "Signature function"
    },
    {
      "name": "Jobs",
      "description": "Job status polling and result retrieval"
    }
  ],
  "paths": {
    "/api/echo": {
      "post": {
        "tags": [
          "Echo"
        ],
        "summary": "Echo test function",
        "description": "This function simply allows user to make a message be echoed from the SignBox for test purposes.\n\nURL: `http://{SMARTSEC}/api/echo`\nMETHOD: POST\nENCODING: multipart/form-data\n",
        "operationId": "echo",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/EchoRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Output Parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EchoResponse"
                },
                "examples": {
                  "message_received": {
                    "summary": "Success example",
                    "value": {
                      "message": "Message received"
                    }
                  },
                  "no_argument": {
                    "summary": "Called without any argument",
                    "value": {
                      "message": "TypeError: echo() takes exactly 1 argument (0 given)",
                      "exception": "TypeError"
                    }
                  },
                  "unexpected_keyword": {
                    "summary": "Called with unexpected keyword argument",
                    "value": {
                      "message": "TypeError: echo() got an unexpected keyword argument '&lt;argument&gt;'",
                      "exception": "TypeError"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sign": {
      "post": {
        "tags": [
          "Sign"
        ],
        "summary": "Sign: signature function",
        "description": "This function allows user to sign a document in any of the supported signature format.\n\nThe document to sign can be sent through an URL (parameter `url_in`) or through data stream (parameter `file_in`);\nonly one of the above methods can be used.\n\nThe signed file is sent to an URL (parameter `url_out`) or it can be retrieved through the result endpoint\n(for 60 seconds, see above).\n\nURL: `http://{SMARTSEC}/api/sign`\nMETHOD: POST\nENCODING: multipart/form-data\n",
        "operationId": "sign",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/SignRequest"
              },
              "encoding": {
                "file_in": {
                  "contentType": "application/octet-stream"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Output Parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignResponse"
                },
                "examples": {
                  "ok_job_id": {
                    "summary": "Job created",
                    "value": {
                      "id": "3.3"
                    }
                  },
                  "pades_not_pdf": {
                    "summary": "NoMatch (PAdES but input is not PDF)",
                    "value": {
                      "message": "NoMatch: attempt to sign in PAdES format a file which is not a pdf;",
                      "exception": "NoMatch"
                    }
                  },
                  "malformed_xml": {
                    "summary": "Malformed XML (XAdES input not well formed)",
                    "value": {
                      "message": "MalformedXMLError: The file you're trying to sign must be a well-formed XML document",
                      "exception": "MalformedXMLError"
                    }
                  },
                  "unsupported_format": {
                    "summary": "Unsupported signature format",
                    "value": {
                      "message": "ValueError: Unsupported signature format &lt;wrong_format&gt;",
                      "exception": "ValueError"
                    }
                  },
                  "resource_missing": {
                    "summary": "Resource does not exist",
                    "value": {
                      "message": "ProcessTerminated: process ended with exit code 1",
                      "exception": "ProcessTerminated"
                    }
                  },
                  "bad_url_scheme": {
                    "summary": "Bad scheme url (invalid url_in or url_out)",
                    "value": {
                      "message": "Exception: bad scheme url",
                      "exception": "Exception"
                    }
                  },
                  "no_targets": {
                    "summary": "No XML nodes match target_exp",
                    "value": {
                      "message": "ValueError: No targets provided",
                      "exception": "ValueError"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/job/{jobId}": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "summary": "Poll job status",
        "description": "Polling endpoint:\n  `http://{SMARTSEC}/api/job/{jobId}`\n\nIf the response returns status `\"done\"`, for 60 seconds it is possible to get the operation results from:\n  `GET /api/result/{jobId}`\n",
        "operationId": "getJobStatus",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Job ID returned by `/api/sign`"
          }
        ],
        "responses": {
          "200": {
            "description": "Job status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobStatus"
                },
                "examples": {
                  "done": {
                    "value": {
                      "status": "done"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/result/{jobId}": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "summary": "Retrieve operation result",
        "description": "Result retrieval endpoint (available for 60 seconds after status is `\"done\"`):\n  `http://{SMARTSEC}/api/result/{jobId}`\n",
        "operationId": "getJobResult",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Job ID returned by `/api/sign`"
          }
        ],
        "responses": {
          "200": {
            "description": "Operation result (signed document)",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EchoRequest": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Message to be echoed"
          }
        }
      },
      "EchoResponse": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "String with message echoed or error detail"
          },
          "exception": {
            "type": "string",
            "description": "Exception related to the error"
          }
        },
        "description": "Output Parameters:\n  - message (String): \"Message received\" OR\n    \"TypeError: echo() takes exactly 1 argument (0 given)\" OR\n    \"TypeError: echo() got an unexpected keyword argument '&lt;argument&gt;'\"\n  - exception (string): TypeError\n"
      },
      "SignRequest": {
        "type": "object",
        "description": "Input parameters for `/api/sign` (multipart/form-data).\n\nNote: the document to sign can be provided either with `url_in` OR with `file_in` (only one method can be used).\n",
        "properties": {
          "url_in": {
            "type": "string",
            "description": "URL with document to sign"
          },
          "url_out": {
            "type": "string",
            "description": "URL where the signed document is posted"
          },
          "urlback": {
            "type": "string",
            "description": "URL to which the response is sent"
          },
          "file_in": {
            "type": "string",
            "format": "binary",
            "description": "Document data stream to sign"
          },
          "username": {
            "type": "string",
            "description": "Username for the remote identity"
          },
          "password": {
            "type": "string",
            "description": "Password for the remote identity"
          },
          "pin": {
            "type": "string",
            "description": "PIN for the remote identity"
          },
          "otp": {
            "type": "string",
            "description": "OTP for the remote identity"
          },
          "check": {
            "type": "string",
            "description": "1 : the certificate will be checked before signature\n0 : the certificate will NOT be checked before signature\n"
          },
          "format": {
            "type": "string",
            "description": "pades, cades, xades (lower case). Default is pades"
          },
          "identifier": {
            "type": "string",
            "description": "Token identifier"
          },
          "tsa_bookmark": {
            "type": "string",
            "description": "The alias corresponding to the Timestamp authority to use.\nThe binding between alias and the Timestamping resource is managed by SignBox configuration.\n"
          },
          "target_exp": {
            "type": "string",
            "description": "XPath expression to sign selected nodes instead of the root node (default expression is '/*').\nIf this expression selects a XAdES signature node, it countersigns it.\n"
          },
          "reason": {
            "type": "string",
            "description": "The PAdES attribute for the reason"
          },
          "location": {
            "type": "string",
            "description": "The PAdES attribute for the location"
          },
          "level": {
            "type": "string",
            "description": "T, X, XL, BES, LTV"
          },
          "img_bookmark": {
            "type": "string",
            "description": "Bookmark for graphic signature placement (image + position).\nExample bookmarks: dn01, dn02, dn03, dn04.\n\nAliases onlydn01, onlydn02, onlydn03, onlydn04 print only the Subject DN.\nIf `img_bookmark` is set, the position parameter is discarded.\n"
          },
          "npage": {
            "type": "string",
            "description": "Page where the graphic signature is inserted. First page is 0.\nDefault value is 0.\n"
          }
        },
        "oneOf": [
          {
            "required": [
              "url_in"
            ]
          },
          {
            "required": [
              "file_in"
            ]
          }
        ]
      },
      "SignResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Job ID assigned to the call (example 3.3)"
          },
          "message": {
            "type": "string",
            "description": "String with the error detail"
          },
          "exception": {
            "type": "string",
            "description": "Exception related to the error"
          }
        },
        "description": "Output Parameters:\n  - id (string): job ID assigned to the call (Example: 3.3)\n  - message (string): possible values include:\n      * NoMatch: attempt to sign in PAdES format a file which is not a pdf;\n      * MalformedXMLError: The file you're trying to sign must be a well-formed XML document\n      * ValueError: Unsupported signature format &lt;wrong_format&gt;\n      * ProcessTerminated: process ended with exit code 1\n      * Exception: bad scheme url\n      * ValueError: No targets provided\n  - exception (string): possible values include:\n      * NoMatch\n      * MalformedXMLError\n      * ValueError\n"
      },
      "JobStatus": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "description": "Operation progress status.\nDocument explicitly mentions value \"done\".\n"
          }
        }
      }
    }
  }
}