openapi: 3.0.1
info:
 title: DSS API
 version: 1.0.0
 description: |
    Document Signing Solution consists of a digital signing engine and Secured QR Code Module. Available in appliance-based or software-based (VM Environment), 
    this solution is specially customised to fulfil the requirements of any application that require document digital signing. 
    The appliance/application is capable to support digital signing on a different form of data/document including XML and PDF file. 
    The appliance/application can be integrated with any system and application using API or web service.
 
    Below are Open API Specification for DSS APIs for verifying roaming certificates, validating PINs, and signing PDFs using roaming individual certificates.
    
    Get in touch with our Sales Team today to request your sandbox account for testing

servers:
  - url: https://dss-sandbox.posdigicert.com.my/DSS/rest

components:
   securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  
security:
   - bearerAuth: []

paths:
  /roaming/verifyRoamingCert:
    post:
      summary: Verify roaming certificate existence
      description: Always returns HTTP 200. Result status is provided inside the response body.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [pCode, userId, orgId]
              properties:
                pCode:
                  type: string
                  maxLength: 45
                  description: "Mandatory. MYCRS Project Code. Will be provided once provisioned by MYCRS. Value for Staging and Production is different."
                  example: "MYCRS_QWERTY"
                userId:
                  type: string
                  maxLength: 20
                  description: "Mandatory. Identification Number. IC or Passport when applying for the roaming certificate."
                  example: "880305100545"
                orgId:
                  type: string
                  maxLength: 20
                  description: "Mandatory. Value set when applying the roaming certificate."
                  example: "880305100545"
      responses:
        '200':
          description: Certificate verification result
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    enum: ['901', '902', '903', '800', '805', '808', '811']
                    description: |
                      - 901: Success
                      - 902: Invalid Parameter
                      - 903: Internal Server Error
                      - 800: Operation Roaming Failed
                      - 805: User Not Exist
                      - 808: Certificate is Revoked
                      - 811: Certificate is Expired
                  certificate:
                    type: string
                    description: Certificate information (optional)

  /roaming/verifyRoamingPin:
    post:
      summary: Verify roaming certificate PIN
      description: Always returns HTTP 200. PIN verification result is in the response body.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [pCode, userId, orgId, pin]
              properties:
                pCode:
                  type: string
                  maxLength: 45
                  description: "Mandatory. MYCRS Project Code. Will be provided once provisioned by MYCRS. Value for Staging and Production is different."
                  example: "MYCRS_QWERTY"
                userId:
                  type: string
                  maxLength: 20
                  description: "Mandatory. Identification Number. IC or Passport when applying for the roaming certificate."
                  example: "880303100545"
                orgId:
                  type: string
                  maxLength: 20
                  description: "Mandatory. Value set when applying the roaming certificate."
                  example: "880303100545"
                pin:
                  type: string
                  maxLength: 20
                  description: "Mandatory. The certificate PIN (password)."
                  example: "Test@Passw0rd"
      responses:
        '200':
          description: PIN verification result
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    enum: ['901', '902', '800', '802', '804', '805', '808']
                    description: |
                      - 901: Success
                      - 902: Invalid Parameter
                      - 800: Operation Roaming Failed
                      - 802: PIN is Blocked
                      - 804: PIN Incorrect
                      - 805: User Not Exist
                      - 808: Certificate is Revoked
                  statusMessage:
                    type: string
                    example: Success

  /roaming/signPdf:
    post:
      summary: Sign PDF using roaming certificate
      description: Always returns HTTP 200. Signing status is provided in the response body.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - pCode
                - source
                - dest
                - signerXyPage
                - userId
                - orgId
                - pin
                - dtsFlag
                - fileServerId
              properties:
                pCode:
                  type: string
                  description: "Mandatory. MYCRS Project Code."
                  example: "MYCRS-PROD"
                source:
                  type: string
                  description: "Mandatory. Full path to the input PDF file on the DSS file server."
                  example: "/document.pdf"
                dest:
                  type: string
                  description: "Mandatory. Full path to save the signed PDF."
                  example: "/document_signed.pdf"
                signerXyPage:
                  type: string
                  description: "Mandatory. Signature position and page, format: X,Y,Width,Height,PageNo."
                  example: "100,200,150,50,1"
                signerImagePath:
                  type: string
                  description: "Optional. Path to signature image on the server."
                  example: "/signer.png"
                qrValue:
                  type: string
                  description: "Optional. Text/URL value encoded into the QR code."
                  example: "https://verify.example.com/tx/ABC123"
                qrPosition:
                  type: string
                  description: "Optional. Start position of QR code in format X,Y,Page."
                  example: "100,100,1"
                qrSize:
                  type: integer
                  description: "Optional. Size of the QR code (deprecated if qrPosition used)."
                  example: 80
                signerFontSize:
                  type: integer
                  description: "Optional. Font size for the signature text."
                  example: 5
                signerTextRow:
                  type: integer
                  description: "Optional. Number of lines in the signature text block."
                  example: 4
                customSignatureText:
                  type: string
                  description: "Optional. Custom signature text to display."
                  example: "Signed by John Doe-*"
                dtsFlag:
                  type: integer
                  description: "Mandatory. Must be set to 1 to enable digital timestamp and LTV."
                  example: 1
                userId:
                  type: string
                  description: "Mandatory. IC/Passport number of the signer."
                  example: "900101088888"
                orgId:
                  type: string
                  description: "Mandatory. Company or organization reference."
                  example: "S1234567"
                pin:
                  type: string
                  description: "Mandatory. The certificate PIN (password)."
                  example: "MySecureP@ss1"
                remark:
                  type: string
                  description: "Optional. Text remarks stored with the signing log."
                  example: "Initial contract signature"
                fileServerId:
                  type: string
                  description: "Mandatory. Identifier of the DSS file server."
                  example: "wiseai"
      responses:
        '200':
          description: PDF signing result
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    example: "TX-ABC123456"
                  statusCode:
                    type: string
                    enum: ['901', '902', '903', '904', '905', '907', '908', '912', '913', '800', '802', '804', '805', '808', '811']
                    description: |
                      - 901: Success
                      - 902: Invalid Parameter
                      - 903: Internal Server Error
                      - 904: File Access Error
                      - 905: Invalid Signing Page
                      - 907: Error QR Transaction
                      - 908: File is Locked
                      - 912: Error LTV Verification
                      - 913: Error LTV Process
                      - 800: Operation Roaming Failed
                      - 802: PIN is Blocked
                      - 804: PIN Incorrect
                      - 805: User Not Exist
                      - 808: Certificate is Revoked
                      - 811: Certificate is Expired
                      
  /roaming/signRoamingData:
    post:
      summary: Sign data using roaming certificate
      description: Always returns HTTP 200. Signing status is provided in the response body.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [pCode, userId, orgId, pin, data]
              properties:
                pCode:
                  type: string
                  maxLength: 45
                  description: "Mandatory. MYCRS Project Code. Will be provided once provisioned by MYCRS. Value for Staging and Production is different."
                  example: "MYCRS_QWERTY"
                userId:
                  type: string
                  maxLength: 20
                  description: "Mandatory. Identification Number. IC or Passport when applying for the roaming certificate."
                  example: "880303100545"
                orgId:
                  type: string
                  maxLength: 20
                  description: "Mandatory. Value set when applying the roaming certificate."
                  example: "880303100545"
                pin:
                  type: string
                  maxLength: 20
                  description: "Mandatory. The certificate PIN (password)."
                  example: "Test@Passw0rd"
                data:
                  type: string
                  description: "Mandatory. The data that need to be signed."
                  example: "ReceiptNo:ABCD1234|TransactionDate:20250702|signedBy:Ahmad Albab"
      responses:
        '200':
          description: Data signing result
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    enum: ['901', '902', '800', '802', '804', '805', '808']
                    description: |
                      - 901: Success
                      - 902: Invalid Parameter
                      - 800: Operation Roaming Failed
                      - 802: PIN is Blocked
                      - 804: PIN Incorrect
                      - 805: User Not Exist
                      - 808: Certificate is Revoked
                  statusMessage:
                    type: string
                    example: Success
                  signedData:
                    type: string
                    example: MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIIF4DCCA8igAwIBAgIQW
  /roaming/validateRoamingSignature:
    post:
      summary: Verify signed data
      description: Always returns HTTP 200. Verify status is provided in the response body.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [originalData, signedData]
              properties:
                originalData:
                  type: string
                  description: "Mandatory. The original data."
                  example: "ReceiptNo:ABCD1234|TransactionDate:20250702|signedBy:Ahmad Albab"
                signedData:
                  type: string
                  description: "Mandatory. The signed data."
                  example: "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIIF4DCCA8igAwIBAgIQW"
      responses:
        '200':
          description: Verify Signed Data result
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    enum: ['901', '0']
                    description: |
                      - 901: Success
                      - 0: Operation failed
                  statusMessage:
                    type: string
                    example: Success
  /files/upload:
    post:
      summary: Upload a file
      description: Uploads a PDF or image file to the server before performing PDF Signing.
      operationId: uploadFile
      requestBody:
       required: true
       content:
         multipart/form-data:
          schema:
            type: object
            required: [fileServerId, filename, file, forceWrite]
            properties:
              fileServerId:
                type: string
                description: Identifier for the file server.
                example: "wiseai"
              filename:
                type: string
                description: "Name to be set to the uploaded file. Example: abcdFile.pdf or signer1.png"
                example: "abcdFile.pdf"
              file:
                type: string
                format: binary
                description: The file to upload.
              forceWrite:
                type: string
                description: set to true or false to allow same file name to be overwritten.
                example: "true"
      responses:
        '200':
          description: Upload result
          content:
            application/json:
              schema:
                type: object
                required: [code, message]
                properties:
                  code:
                    type: string
                    enum: ['901', '904', '902', '944']
                    description: |
                      Response code:
                       - 901 : Success
                       - 904 : Invalid fileServerId
                       - 902 : Invalid Parameter
                       - 944 : File name duplicate
                  message:
                    type: string
                    description: Description of the result based on the response code.
  /files/download/{fileServerId}/{filename}:
    get:
      summary: Download a file
      description: Download a Signed PDF file from the server.
      parameters:
        - name: fileServerId
          in: path
          required: true
          schema:
            type: string
          description: Identifier for the file server.
        - name: filename
          in: path
          required: true
          schema:
            type: string
          description: The name of the file to download.
      operationId: downloadFile
          
      responses:
        '200':
          description: File or error response
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: object
                required:
                  - statusCode
                  - message
                properties:
                  statusCode:
                    type: string
                    enum: ['904', '902', '945']
                    description: Error response code
                  message:
                    type: string
                    description: Error message
  /trustmark/signTrustmark:
    post:
      summary: Sign PDF using organization certificate
      description: Always returns HTTP 200. Signing status is provided in the response body.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - trustmarkCode
                - source
                - dest
                - trustmarkXyPage
                - dtsFlag
                - fileServerId
              properties:
                trustmarkCode:
                  type: string
                  description: "Mandatory. Trustmark Code."
                  example: "TrustmarkCompanyA"
                source:
                  type: string
                  description: "Mandatory. Full path to the input PDF file on the DSS file server (start with slash /)."
                  example: "/document.pdf"
                dest:
                  type: string
                  description: "Mandatory. Full path to save the signed PDF (start with slash /)."
                  example: "/document_signed.pdf"
                trustmarkXyPage:
                  type: string
                  description: "Mandatory. Signature position and page, format: X,Y,Width,Height,PageNo."
                  example: "100,200,150,50,1"
                qrValue:
                  type: string
                  description: "Optional. Text/URL value encoded into the QR code."
                  example: "https://verify.example.com/tx/ABC123"
                qrPosition:
                  type: string
                  description: "Optional. Start position of QR code in format X,Y,Page."
                  example: "100,100,1"
                qrSize:
                  type: integer
                  description: "Optional. Size of the QR code (deprecated if qrPosition used)."
                  example: 80
                signerFontSize:
                  type: integer
                  description: "Optional. Font size for the signature text."
                  example: 5
                signerTextRow:
                  type: integer
                  description: "Optional. Number of lines in the signature text block."
                  example: 4
                dtsFlag:
                  type: integer
                  description: "Mandatory. Must be set to 1 to enable digital timestamp and LTV."
                  example: 1
                fileServerId:
                  type: string
                  description: "Mandatory. Identifier of the DSS file server."
                  example: "fileServerA"
      responses:
        '200':
          description: Trustmark signing result
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    example: "TX-ABC123456"
                  statusCode:
                    type: string
                    enum: ['901', '902', '903', '904', '905', '907', '908', '912', '913', '800', '802', '804', '805', '808', '811']
                    description: |
                      - 901: Success
                      - 902: Invalid Parameter
                      - 903: Internal Server Error
                      - 904: File Access Error
                      - 905: Invalid Signing Page
                      - 907: Error QR Transaction
                      - 908: File is Locked
                      - 912: Error LTV Verification
                      - 913: Error LTV Process
                      - 800: Operation Roaming Failed
                      - 802: PIN is Blocked
                      - 804: PIN Incorrect
                      - 805: User Not Exist
                      - 808: Certificate is Revoked
                      - 811: Certificate is Expired
