openapi: 3.0.3

info:
  title: LTA
  description: >-
    Post-signing PAdES-LTA extension. Adds a qualified timestamp and all relevant
    validation material to already-signed PDFs. Supports documents signed by BankID
    and by EU Qualified Trust Service Providers (QTSPs) from Norway and Sweden.
    Signatures from non-qualified or unsupported trust service providers will be rejected.
    If you need support for additional EU QTSPs, contact BankID support.
  version: 1.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/qtsa: Add Timestamp to signed PDF

  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-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
    C-404:
      description: Sign order was not found. This could be caused by timeout or an invalid sign_id.

security:
  - bearerAuth: []

paths:
  /v1/timestamp/pades/lta:
    post:
      summary: Upload signed PDFs for LTA extension
      operationId: post-lta
      description: >-
        Accepts one or more signed PDFs and extends them to PAdES-B-LTA by adding
        a qualified timestamp and embedded validation material (certificate chain,
        OCSP responses / CRLs). The PDF signatures must have been created by a
        trusted signer — either BankID or an EU Qualified Trust Service Provider
        (QTSP) from Norway or Sweden. Signatures from other providers are not
        supported and will result in an error. Contact BankID support if you need
        support for additional EU QTSPs.
      security:
        - bearerAuth: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              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: 15
              items:
                type: object
                properties:
                  pdf:
                    type: string
                    description: Base64 encoded PDF
                    # 10 MB
                    maxLength: 10485760
                required:
                  - pdf
      responses:
        "201":
          description: Successfully uploaded sign order
          content:
            application/json:
              schema:
                type: object
                required:
                  - signId
                properties:
                  signId:
                    type: string
                    description: sign_id
                  errors:
                    type: array
                    items:
                      type: string
                      description: Array of error messages describing the reason of failure.
        "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
                required:
                  - errors
                properties:
                  signId:
                    type: string
                    description: sign_id
                  errors:
                    type: array
                    items:
                      type: string
                      description: Array of error messages describing the reason of failure.
        "403":
          $ref: "#/components/responses/C-403"

    get:
      summary: Check status of sign order
      operationId: get-lta
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/signId"
      responses:
        "200":
          description: Sign order was found. Returns the order state.
          content:
            application/json:
              schema:
                type: object
                required:
                  - orderState
                properties:
                  orderState:
                    type: string
                    enum:
                      - ORDER_RECEIVED
                      - LTA_SIGNING
                      - FAILED
                      - LTA_COMPLETED
        "400":
          $ref: "#/components/responses/C-400-Easy"
        "403":
          $ref: "#/components/responses/C-403"
        "404":
          $ref: "#/components/responses/C-404"

    delete:
      summary: Delete sign order and download signing results
      operationId: delete-lta
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/signId"
      responses:
        "200":
          description: Sign order was found. The extended documents will be in the signingResults-array. If order is not completed, i.e. order state is not SIGN_COMPLETED, the signingResults will be an empty array.
          content:
            application/json:
              schema:
                type: object
                required:
                  - signId
                  - orderState
                properties:
                  signingResults:
                    type: array
                    items:
                      type: string
                      description: The extended signed pdf as a base64 encoded text string. In case of errors (orderState = FAILED) this will be empty.
                  signId:
                    type: string
                    description: The sign_id reference
                  orderState:
                    type: string
                    description: The current order state
                  errorMessage:
                    type: string
                    description: In case of errors (orderState = FAILED) this will contain an error message describing the problem and pointing to the index of the document that caused the error.
        "400":
          $ref: "#/components/responses/C-400-Easy"
        "403":
          $ref: "#/components/responses/C-403"
        "404":
          $ref: "#/components/responses/C-404"