Versions Compared

Version Old Version 27 New Version 28
Changes made by

Lorenzo Cardinali

Lorenzo Cardinali

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Introduction

The REST interface offered by SWS is exposed at the path:

Code Block
http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/

This path is composed by other sub-path for every of purpose:

  • admin: method for sws like remove certificate from cache
  • enquiry: contain the method for obtain the information like signatures available, signer certificate, timestamps available ecc...
  • sign: this is the principal path of SWS and contain the methods for apply the signature
  • timestamps: methods for apply the timestamp on every type of file

And in this guid will be described how manage the error generated by the REST interface.

Enquiry

ENQUIRY: certificate

Descriptionreturn the certifcate associated to "device_signer"

Table of Contents

Introduction


The REST interface offered by SWS is exposed at the path:

Code Block
http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/


This path is composed by other sub-path for every of purpose:


  • admin: method for sws like remove certificate from cache
  • enquiry: contain the method for obtain the information like signatures available, signer certificate, timestamps available ecc...
  • sign: this is the principal path of SWS and contain the methods for apply the signature
  • timestamps: methods for apply the timestamp on every type of file

And in this guid will be described how manage the error generated by the REST interface.


Enquiry

ENQUIRY: certificate


Descriptionreturn the certifcate associated to "device_signer"
HttpMethodPOST
Path
/rest/enquiry/certificate
Request


Expand
titlerequest-enquiry-certificate
{
  "credentials": {
    "username": "device_signer"
  }
}


Responsereturn the byte array of certificate associated to device_signer


ENQUIRY: signatures


Descriptionreturn the numer of signatures apposed from "device_signer"
HttpMethodPOST
Path
/rest/enquiry/signatures
Request


Expand
titlerequest-enquiry-signatures
{
  "credentials": {
    "username": "device_signer"
  }
}


ResponseNumber of signatures apposed



ENQUIRY: signatures-available


Descriptionreturn the number of signatures which "device_signer" can apply
HttpMethodPOST
Path
/rest/enquiry/signatures-available
Request


Expand
titlerequest-enquiry-signatures-available
{
  "credentials": {
    "username": "device_signer"
  }
}


ResponseNumber of signatures available



ENQUIRY: otps


Descriptionreturn the otp list associated to "device_signer"
HttpMethodPOST
Path
/rest/enquiry/otps
Request


Expand
titlerequest-enquiry-otps
{
  "credentials": {
    "username": "device_signer"
  }
}


Response


Expand
titleresponse-enquiry-otps

[
    {
        "idOtp": number,
        "serialNumber": "string",
        "type": "otp-type-enum"
    },
   {
        "idOtp": number,
        "serialNumber": "string",
        "type": "otp-type-enum"
    }
]




ENQUIRY: timestamps-available


Descriptionreturn the numeber of timestamp available (valid only for Namirial TSA account)
HttpMethodPOST
Path
/rest/enquiry/timestamps-available
Request


Expand
titlerequest-enquiry-timestamps-available

{
  "timestampUrl": "timestamp-namirial-enquiry-url",
  "timestampUsername": "tsa-username",
  "timestampPassword": "tsa-password"
}


ResponseNumber of timestamps available


ENQUIRY: errors


POST
Descriptionreturn the error description associated to error code
HttpMethodPOST
Path
/rest/enquiry/certificateerrors
Request
Descriptionreturn the numer of signatures apposed from "device_signer"
HttpMethod


Expand
titlerequest-enquiry-certificate
{
  "credentials": {
    "username": "device_signer"
  }
}
Responsereturn the byte array of certificate associated to device_signer

ENQUIRY: signatures

-enquiry-errors

{
  "error_code": integer,
  "lang": "COUNTRY-CODE-2DIGIT"
}


Response


Expand
titleresponse-enquiry-errors

[
    {
        "errorCode": integer,
        "errorLanguage": "CONUNTRY-CODE-2DIGIT",
        "errorLanguage2": "COUNTRY-CODE-3DIGIT",
        "errorText": "Description error in language"
    }
]



Admin

ADMIN: remove-certificate-from-cache


Descriptionremove the certificate from cache of SWS
HttpMethodPUT
Path
/rest/enquiry/signaturesadmin/remove-certificate-from-cache
Request


Expand
titlerequest-enquiry-signaturesremove-certificate-from-cache

{
  "

credentials

error_code":

{

 integer,

    

  "

username

lang": "

device_signer"
  }

COUNTRY-CODE-2DIGIT"
}


ResponseNumber of signatures apposed

ENQUIRY: signatures-available

Descriptionreturn the number of signatures which "device_signer" can apply


Timestamps

TIMESTAMPS: apply

Descriptionpermits to apply timestamp on specified file
HttpMethodPOST
Path
/rest/enquirytimestamps/signatures-availableapply
Request
timeStampPreferencesDescriptionreturn the otp list associated to "device_signer"


Expand
titlerequest-enquirytimestamps-signatures-available
{
  "credentials": {
    "username": "device_signer"
  }
}
ResponseNumber of signatures available

ENQUIRY: otps

apply

{
  "filenameInTSD": "string",
  "outputAsPDF": true,
  "outputAsTSD": true,
  "outputBase64Encoded": true,
  "timestampHashAlgo": "string",
  "timestampPassword": "string",
  "timestampUrl": "string",
  "timestampUsername": "string"
}


contentfile to apply timestamp


Response


User

USER: change-password

Descriptionpermits to change the password associated to device signer
HttpMethodPOST
Path
/rest/enquiryuser/otps
Request
Expand
titlerequest-enquiry-otps
{
  "credentials": {
    "username": "device_signer"
  }
}
Response
change-password
Request (for remote device signer)


[
    {
        
Expand
titleresponse-enquiry-otps
request-user-change-password-remote

{
  "credentials": {
    "idOtp": numberidOtp or -1,
            "serialNumberotp": "stringotpCode",
            "typepassword": "otp-type-enum"
    },
   {
        "idOtp": number,
        "serialNumberold-password-of-device-signer-remote",
    "username": "string"device-signer-remote"
  },
          "typenewPassword": "otp-type-enumnew-password-of-device-signer-remote"
    }]

ENQUIRY: timestamps-available


Descriptionreturn the numeber of timestamp available (valid only for Namirial TSA account)
HttpMethodPOST
Path
/rest/enquiry/timestamps-available
RequestRequest (for automatic device signer)


Expand
titlerequest-user-enquirychange-timestampspassword-availableautomatic

{
  "timestampUrlcredentials": {
    "securityCode": "securityCode associate to automatic device signer",
    "password": "timestamp-namirial-enquiry-urlold-password-of-device-signer-automatic",
      "timestampUsernameusername": "tsadevice-signer-usernameautomatic"
  },
  "timestampPasswordnewPassword": "tsanew-password-of-device-signer-automatic"
}


ResponseNumber of timestamps available
ENQUIRY: errors
Password update succesfully


Sign

SIGN: openSession


Descriptionreturn the error description associated to error codepermits to open the sessione for apply multiple sign with remote device
HttpMethodPOST
Path
/rest/enquiry/errors
Request
Expand
titlerequest-enquiry-errors

{
  "error_code": integer,
  "lang": "COUNTRY-CODE-2DIGIT"
}

Response
sign/openSession
Request


Expand
titleresponserequest-enquirysign-errorsopenSession

[
    {
  "credentials": {
            "errorCodeidOtp": integer-1,
            "errorLanguageotp": "CONUNTRY-CODE-2DIGIT775351",
            "errorLanguage2password": "COUNTRY-CODE-3DIGIT12345678",
            "errorTextusername": "Description error in languageRHIP22021116852552"
      }
}]

Admin


ADMIN: remove-certificate-from-cache

PUT
Descriptionremove the certificate from cache of SWS
HttpMethodResponseString with the session


SIGN: getRemainingTimeForSession


Descriptionpermits to obtain the time until the session is valid
HttpMethodPOST
Path
/rest/admin/remove-certificate-from-cachesign/getRemainingTimeForSession
Request

TIMESTAMPS: apply

Descriptionpermits to apply timestamp on specified file


Expand
titlerequest-enquiry-remove-certificate-from-cache

{
  "error_code": integer,
  "lang": "COUNTRY-CODE-2DIGIT"
}

Response

Timestamps

sign-getRemainingTimeForSession

{
  "credentials": {
    "sessionKey": "zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==",
    "username": "RHIP22021116852552"
  }
}


ResponseSeconds until the session is valid


SIGN: closeSession


Descriptionpermits to destroy the session before will expire
HttpMethodPOST
Path
/rest/timestampssign/applycloseSession
RequesttimeStampPreferences

USER: change-password

Descriptionpermits to change the password associated to device signer


Expand
titlerequest-timestamps-apply

{
  "filenameInTSD": "string",
  "outputAsPDF": true,
  "outputAsTSD": true,
  "outputBase64Encoded": true,
  "timestampHashAlgo": "string",
  "timestampPassword": "string",
  "timestampUrl": "string",
  "timestampUsername": "string"
}

contentfile to apply timestamp
Response

User

request-sign-closeSession

{
  "credentials": {
    "sessionKey": "zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==",
    "username": "RHIP22021116852552"
  }
}


Response


SIGN: sendOtpBySMS


Descriptionpermits to destroy the session before will expire
HttpMethodPOST
Path
/rest/usersign/change-passwordsendOtpBySMS
Request (for remote device signer)


{
  "credentials": {
    "idOtp": idOtp or -1,
    "otp": "otpCode",
    "password": "old-password-of-device-signer-remote",
Expand
titlerequest-user-change-password-remote
sign-closeSession

{
  "credentials": {
    "username": "device-signer-remoteRHIP22021116852552"
  },
  "newPassword": "new-password-of-device-signer-remote"
}

Request (for automatic device signer)


}


Response


SIGN: signCades


Descriptionpermits to apply the cades signature
HttpMethodPOST
Path
/rest/sign/signCades
Request
credentials


Expand
titlerequest-user-change-password-automaticsignCades-credentials

{

  "credentials": {
    "securityCode"username":"securityCode associate to automatic device signer name",    

"password": "old-password-PIN of - device - signer -automaticname",    

"usernameidOtp": "associated to device - signer -automatic"
  },
  "newPassword": "new-password-of-device-signer-automaticor -1,

"otp":"otp code",

"sessionKey":"string with sessionKey"

}


ResponsecadesPreferencesPassword update succesfully

SIGN: openSession

Descriptionpermits to open the sessione for apply multiple sign with remote deviceHttpMethodPOSTPath
/rest/sign/openSession
Request
Expand
titlerequest-sign-openSession

{
  "credentials": {
    "idOtp": -1,
    "otp": "775351",
    "password": "12345678",
    "username": "RHIP22021116852552"
  }
}

ResponseString with the session

SIGN: getRemainingTimeForSession

Descriptionpermits to obtain the time until the session is valid


Expand

Sign

titlerequest-signCades-cadesPrefernces

{
  "filenameInTSD": "string",
  "outputAsPDF": boolean,
  "outputAsTSD": boolean,
  "outputBase64Encoded": boolean,
  "timestampHashAlgo": "string",
  "timestampPassword": "string",
  "timestampUrl": "string",
  "timestampUsername": "string",
  "hashAlgorithm": "string",
  "level": "enum",
  "withTimestamp": boolean,
  "counterSignature": true,
  "counterSignatureIndex": 0,
  "detached": boolean
}


contentfile to sign
Responsebyte array of signed files


SIGN: signPades

Descriptionpermits to apply the pades signature
HttpMethodPOST
Path
/rest/sign/getRemainingTimeForSessionsignPades
Request
credentials


{
  "credentials": 
Expand
titlerequest-sign-getRemainingTimeForSession
signPades-credentials

{    

"sessionKeyusername": "zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw=="device signer name",    

"usernamepassword": "RHIP22021116852552PIN of device signer name"
  }
}

ResponseSeconds until the session is valid

SIGN: closeSession

Descriptionpermits to destroy the session before will expireHttpMethodPOSTPath
/rest/sign/closeSession
Request
Expand
titlerequest-sign-closeSession

{
  "credentials": {
    "sessionKey": "zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==",
    "username": "RHIP22021116852552"
  }
}

Response

SIGN: sendOtpBySMS

Descriptionpermits to destroy the session before will expireHttpMethodPOSTPath
/rest/sign/sendOtpBySMS
Request
Expand
titlerequest-sign-closeSession

{
  "credentials": {
    "username": "RHIP22021116852552"
  }
}

Response

SIGN: signCades

Descriptionpermits to apply the cades signature
HttpMethodPOST
Path
/rest/sign/signCades
Requestcredentials
Expand
titlerequest-signCades-credentials

{

"username":"device signer name",

"password":"PIN of device signer name",

"idOtp":associated to device signer or -1,

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

cadesPreferences
Expand
titlerequest-signCades-cadesPrefernces

{
  "filenameInTSD": "string",
  "outputAsPDF": boolean,
  "outputAsTSD": boolean,
  "outputBase64Encoded": boolean,
  "timestampHashAlgo,

"idOtp":associated to device signer or -1,

"otp":"otp code",

"sessionKey":"string with sessionKey"

}


padesPreferences


Expand
titlerequest-signPades-padesPrefernces

{
  "filenameInTSD": "string",
  "outputAsPDF": boolean,
  "outputAsTSD": boolean,
  "outputBase64Encoded": boolean,
  "timestampHashAlgo": "string",
  "timestampPassword": "string",
  "timestampUrl": "string",
  "timestampUsername": "string",
  "hashAlgorithm": "string",
  "level": "enum",
  "withTimestamp": boolean,
  "encryptInAnyCase": boolean,
  "encryptionPassword": "string",
  "lockFields": [
    "string"
  ],
  "needAppearanceDisabled": boolean,
  "page": 0,
  "signerImage": {
    "fieldName": "string",
    "fontName": "string",
    "fontSize": 0,
    "image": "string",
    "imageFilename": "string",
    "imageURL": "string",
    "imageVisible": true,
    "location": "string",
    "reason": "string",
    "timestampPasswordscaled": "string"true,
    "timestampUrlsignerName": "string",
    "timestampUsernametextPosition": "stringenum",
    "hashAlgorithmtextVisible": boolean,
    "stringwidth": int,

     "levelheight": "enum"int,
    "withTimestampx": booleanint,
    "counterSignaturey": trueint
  },
  "counterSignatureIndexsignerImageReference": 0"string",
  "detachedwithSignatureField": boolean
}


content contentfile to signResponsebyte array of signed files



...