openapi: 3.0.3

info:
  title: BankID Signing Convert V1
  description: BankID Signing Convert V1
  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: Standard "umbrella” scope that can cover qualified + TSA
            esign/qualified: Qualified signatures
            esign/nnin: Norwegian National Identity Number
            signdoc/read_write: Grants API Access

security:
  - bearerAuth: []

paths:
  /v1/signdoc/convert/pdf/specs:
    get:
      summary: Get supported PDF conversions
      operationId: get-convert
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Get supported PDF conversions
          content:
            application/json:
              schema:
                type: object
                properties:
                  pdfSpecs:
                    type: string
                    description: List of currently supported PDF conversions.
                    enum:
                      - PDFA_2B

  /v1/signdoc/convert:
    post:
      summary: Convert PDF documents
      operationId: post-convert
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: JSON array of documents to be converted (minimum one). The document to be converted is represented as a Base64 encoded string.
              minItems: 1
              maxItems: 15
              items:
                type: object
                properties:
                  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
                  pdf:
                    type: string
                    description: Base64 encoded PDF
                    maxLength: 5000000
                  allowSigned:
                    type: boolean
                    description: Signals the converter to allow PDFs that already contain a signature. Note that this signature will be removed in the conversion process!
                required:
                  - pdfSpec
                  - pdf

      responses:
        "200":
          description: Successfully uploaded and converted document. ConversionWarnings contains an array of warnings that occurred during the conversion.
          content:
            application/json:
              schema:
                # this looks weird in the API docs - not sure if it is correct
                type: array
                items:
                  type: object
                  properties:
                    conversionResult:
                      type: object
                      properties:
                        conversionId:
                          type: string
                        description:
                          type: string
                        converted:
                          type: boolean
                        conversionErrors:
                          type: array
                          items:
                            type: string
                        conversionWarnings:
                          type: array
                          items:
                            type: string
                    convertedDocument:
                      type: string
        "400":
          description: Could not convert order due to error in request. Documents that could not be converted will have a list of errors in  conversionErrors. Note - 400-responses created because of syntactical errors can be in string-only format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversionResults:
                    type: array
                    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":
          description: Access token is invalid or missing.
          content:
            application/json:
              schema:
                type: string