openapi: 3.0.3 info: title: BankID Signing Pades V0 description: BankID Signing Pades V0 version: 0.0.0 servers: - url: "https://api.preprod.esign-stoetest.cloud" description: "Public testing environment" - url: "https://api.esign-stoe.cloud" description: "Production" components: securitySchemes: bearerAuth: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.current.bankid.no/auth/realms/current/protocol/openid-connect/token scopes: esign: Standard "umbrella” scope that can cover qualified + TSA esign/qualified: Qualified signatures esign/nnin: Norwegian National Identity Number signdoc/read_write: Grants API Access parameters: signId: name: sign_id description: The sign_id that was return when uploading the signing order. in: query required: true schema: type: string maxLength: 50 responses: C-204: description: Sign order was not found. This could be caused by timeout or an invalid sign_id. C-400-Easy: description: The query parameter sign_id was not provided. content: application/json: schema: type: string C-403: description: Access token is invalid or missing. content: application/json: schema: type: string security: - bearerAuth: [] paths: /signdoc/pades: post: summary: Upload sign order to BankID Signing resource server operationId: post-pades security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: signProperties: type: object properties: orderName: type: string description: Order name. maxLength: 50 documentDisplayMode: type: string description: Must be "interior", "window" or "overlay". PLEASE NOTE - This parameter will be phased out and is not evaluated anymore! deprecated: true default: "interior" enum: - interior - window - overlay showConfirmation: type: boolean description: Show "Signing completed" in client after signing. PLEASE NOTE - This parameter will be phased out and is not evaluated anymore! deprecated: true default: true showUnderstanding: type: boolean description: Show box for "Content is understood" in client. PLEASE NOTE - This parameter will be phased out and is not evaluated anymore! deprecated: true default: true timeoutSeconds: type: integer description: Timeout in seconds for end user signing. Sign order will be deleted after expiry. default: 1800 required: - orderName padesSignProperties: type: object properties: addVisualSeals: type: boolean description: If true, add visual signature seals to PDF. required: - addVisualSeals documents: type: array description: JSON array of documents to be signed (minimum one). Be aware that very large PDF files, typically files with a large number of images, might give a less than optimal user experience due to the document processing time. minItems: 1 maxItems: 30 items: type: object properties: description: type: string description: Description of document. Displayed to end user in client. If not specified, orderName from signProperties will be used combined with a number, i.e. "My order name - 1" for the first document. maxLength: 100 pdf: type: string description: Base64 encoded PDF # 40 MB maxLength: 41943040 endUserOnly: type: boolean description: Set to true if only the end user signature is desired. default: false merchantSealPos: type: object description: Specifies the position of signature seal in PDF. The seal will be positioned according to the x and y coordinates (in points) with origin in the upper left corner. PLEASE NOTE - This parameter will be phased out and is not evaluated anymore! deprecated: true properties: x: type: number description: Horizontal positioning of seal. y: type: number description: Vertical positioning of seal. page: type: integer description: Page number to place seal. endUserSealPos: type: object description: Specifies the position of signature seal in PDF. The seal will be positioned according to the x and y coordinates (in points) with origin in the upper left corner. properties: x: type: number description: Horizontal positioning of seal. y: type: number description: Vertical positioning of seal. page: type: integer description: Page number to place seal. pdfSpec: type: string description: Validates and if necessary converts the document (pdf) to specified PDF/A version and conformance level. Currently only PDFA_2B is currently supported and conversion is only active in production. enum: - PDFA_2B required: - pdf resultContent: type: array description: JSON array of string. Must contain at either padesSignedPdf, or padesAppendix, or both. The string values will determine the content result when retrieving a completed sign order later. PLEASE NOTE - This parameter will be phased out and is not evaluated anymore! deprecated: true minItems: 1 items: type: string enum: - padesSignedPdf - documentHash - padesAppendix required: - signProperties - padesSignProperties - documents - resultContent responses: "201": description: Successfully uploaded PAdES sign order content: application/json: schema: type: object properties: sign_id: type: string conversionResults: type: array description: Response if pdfSpec is used items: type: object properties: conversionId: type: string description: type: string converted: type: boolean conversionErrors: type: array items: type: string conversionWarnings: type: array items: type: string "400": description: Could not create order due to error in request. See the "errors"-array in the response for details. Note - 400-responses created because of syntactical errors can be in string-only format. content: application/json: schema: type: object properties: errors: type: array items: type: string conversionResults: type: array description: Response if pdfSpec is used items: type: object properties: conversionId: type: string description: type: string converted: type: boolean conversionErrors: type: array items: type: string conversionWarnings: type: array items: type: string "403": $ref: "#/components/responses/C-403" get: summary: Check status of sign order operationId: get-pades security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/signId" responses: "200": description: Sign order was found. Returns the order state. content: application/json: schema: type: object properties: orderState: type: string enum: - ORDER_RECEIVED - USER_SIGNING - FAILED - CANCELLED - SIGN_COMPLETED "204": $ref: "#/components/responses/C-204" "400": $ref: "#/components/responses/C-400-Easy" "403": $ref: "#/components/responses/C-403" delete: summary: Delete sign order and download signing results operationId: delete-pades security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/signId" responses: "200": description: Sign order was found. The claims returned in the signing results depends on the values pass to the resultContent array when creating the order. If order is not completed, i.e. order state is not SIGN_COMPLETED, the signing results will be an empty array. content: application/json: schema: type: object properties: signingResults: type: array items: type: object properties: signedDocumentSha256: type: string description: Hash over the signed document (base64 encoded). Set by documentHash in resultContent. padesSignedPdf: type: string description: The signed pdf as a base64 encoded text string. Set by padesSignedPdf in resultContent. padesAppendix: type: string description: The signature data added to the original PDF represented as base64. Set by padesAppendix in resultContent. PLEASE NOTE - This parameter will be phased out and is not evaluated anymore! deprecated: true description: type: string description: Description of the document unsignedDocumentSha256: type: string description: Hash (Hex-encoded) over the original document (base64 encoded form). Set by documentHash in resultContent. signId: type: string description: The sign_id reference orderName: type: string description: Name of the order orderState: type: string description: The current order state "204": $ref: "#/components/responses/C-204" "400": $ref: "#/components/responses/C-400-Easy" "403": $ref: "#/components/responses/C-403"