Content Comparison

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

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

Description

return the certifcate associated to "device_signer"

HttpMethod

POST

Path

/rest/enquiry/certificate

Request

Expand

title	request-enquiry-certificate

{
  "credentials": {
    "username": "device_signer"
  }
}

Response

return the byte array of certificate associated to device_signer

ENQUIRY: signatures

Description

return the numer of signatures apposed from "device_signer"

HttpMethod

POST

Path

/rest/enquiry/signatures

Request

Expand

title	request-enquiry-signatures

{
  "credentials": {
    "username": "device_signer"
  }
}

Response

Number of signatures apposed

ENQUIRY: signatures-available

Description

return the number of signatures which "device_signer" can apply

HttpMethod

POST

Path

/rest/enquiry/signatures-available

Request

Expand

title	request-enquiry-signatures-available

{
  "credentials": {
    "username": "device_signer"
  }
}

Response

Number of signatures available

ENQUIRY: otps

Description

return the otp list associated to "device_signer"

HttpMethod

POST

Path

/rest/enquiry/certificateotps

Request

Expand

title	request-enquiry-certificateotps

{
  "credentials": {
    "username": "device_signer"
  }
}

Response

return the byte array of certificate associated to device_signer

ENQUIRY: signatures

Descriptionreturn the numer of signatures apposed from "device_signer"HttpMethodPOSTPath

/rest/enquiry/signatures

Request

Expand

title	request-enquiry-signatures

{
  "credentials": {
    "username": "device_signer"
  }
}

ResponseNumber of signatures apposedENQUIRY: signatures

Expand

title	response-enquiry-otps

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

ENQUIRY: timestamps-available

Description

return the number of signatures which "device_signer" can applynumeber of timestamp available (valid only for Namirial TSA account)

HttpMethod

POST

Path

/rest/enquiry/signaturestimestamps-available

Request

Expand

title	request-enquiry-signaturestimestamps-available

{
"

credentials

timestampUrl":

{
"username

"timestamp-namirial-enquiry-url",
"timestampUsername": "

device_signer"
}

tsa-username",
"timestampPassword": "tsa-password"
}

Response

Number of signatures timestamps available

ENQUIRY:

otps

errors

Description

return the otp list associated to "device_signer"

HttpMethod

POST

Path

/rest/enquiry/otps

Requesterror description associated to error code

HttpMethod

POST

Path

/rest/enquiry/errors

Request

Expand

title	request-enquiry-errors

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

Response

Description

return the numeber of timestamp available (valid only for Namirial TSA account)

Expand

title	requestresponse-enquiry-otpserrors

[
{

  "credentials": {
    "username": "device_signer"
  }
}

Response

Expand

title	response-enquiry-otps

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

ENQUIRY: timestamps-available

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

Admin

ADMIN: remove-certificate-from-cache

Description

remove the certificate from cache of SWS

HttpMethod

PUT

Path

/rest/admin/remove-certificate-from-cache

Request

Expand

title	request-enquiry-remove-certificate-from-cache

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

Response

Timestamps

TIMESTAMPS: apply

Description

permits to apply timestamp on specified file

HttpMethod

POST

Path

/rest/enquirytimestamps/timestamps-availableapply

Request

timeStampPreferences

Description

return the error description associated to error code

Expand

title	request-enquiry-timestamps-availableapply

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

Response

Number of timestamps available

ENQUIRY: errors

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

content

file to apply timestamp

Response

User

USER: change-password

HttpMethod	POST
Description	permits to change the password associated to device signer
Path	/rest/enquiry/errors	Request

Expand

title	request-enquiry-errors

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

Response

Expand

title	response-enquiry-errors

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

Admin

ADMIN: remove-certificate-from-cache

Description

remove the certificate from cache of SWS

HttpMethod

PUT

Path

/rest/admin/remove-certificate-from-cacheuser/change-password

Request (for remote device signer)

Expand

title	request-user-change-password-remote

{
  "credentials": {
    "idOtp": idOtp or -1,
    "otp": "otpCode",
    "password": "old-password-of-device-signer-remote",
    "username": "device-signer-remote"
  },
  "newPassword": "new-password-of-device-signer-remote"
}

Request (for automatic device signer)

Expand

title	request-user-change-password-automatic

{
  "credentials": {
"securityCode": "securityCode associate to automatic device signer",
    "password": "old-password-of-device-signer-automatic",
    "username": "device-signer-automatic"
  },
  "newPassword": "new-password-of-device-signer-automatic"
}

Response

Password update succesfully

Sign

SIGN: openSession

HttpMethod	POST
Description	permits to open the sessione for apply multiple sign with remote device
Path	/rest/sign/openSession
Request

TIMESTAMPS: apply

Description

permits to apply timestamp on specified file

Expand

title	request-enquiry-remove-certificate-from-cache

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

Response

Timestamps

sign-openSession

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

Response

String with the session

SIGN: getRemainingTimeForSession

USER: change-password

HttpMethod	POST
Description	permits to obtain the time until the session is valid
Path	/rest/timestampssign/applygetRemainingTimeForSession
Request	timeStampPreferences

Expand

title	request-timestamps-apply

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

contentfile to apply timestampResponse

User

Description

permits to change the password associated to device signer

Expand

title	request-sign-getRemainingTimeForSession

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

Response

Seconds until the session is valid

SIGN: closeSession

Description

permits to destroy the session before will expire

HttpMethod

POST

Path

/rest/usersign/change-passwordcloseSession

Request (for remote device signer)

{
  "credentials": {
    "idOtp": idOtp or -1,
    "otp": "otpCode",
    "password": "old-password-of-device-signer-remote

Expand

title	request-user-change-password-remote

sign-closeSession

{
  "credentials": {
    "sessionKey": "zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==",
    "username": "device-signer-remoteRHIP22021116852552"
  },
  "newPassword": "new-password-of-device-signer-remote"
}

Request (for automatic device signer)

}
}

Response

SIGN: sendOtpBySMS

Description

permits to destroy the session before will expire

HttpMethod

POST

Path

/rest/sign/sendOtpBySMS

Request

Expand

title	request-user-change-password-automaticsign-closeSession

{
  "credentials": {
"securityCode": "securityCode associate to automatic device signer",
    "password": "old-password-of-device-signer-automatic","credentials": {
    "username": "device-signer-automaticRHIP22021116852552"
  },
  "newPassword": "new-password-of-device-signer-automatic"
}

Response

Password update succesfully

Sign

SIGN:

openSession

signCades

Description

permits to open the sessione for apply multiple sign with remote deviceapply the cades signature

HttpMethod

POST

Path

/rest/sign/openSessionsignCades

Request

Description

permits to obtain the time until the session is valid

HttpMethod

POST

Path

/rest/sign/getRemainingTimeForSession

credentials

Request

Expand

title	request-signsignCades-openSessioncredentials

{ "credentials": {

"username":"device signer name",

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

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

"otp": "775351otp code",

"passwordsessionKey": "12345678",
"username": "RHIP22021116852552"
}
}

Response

String with the session

SIGN: getRemainingTimeForSession

"string with sessionKey"

}

cadesPreferences

Response

SIGN: sendOtpBySMS

Description

permits to destroy the session before will expire

Expand

title	request-signsignCades-getRemainingTimeForSessioncadesPrefernces

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

Response

Seconds until the session is valid

SIGN: closeSession

Descriptionpermits to destroy the session before will expireHttpMethodPOSTPath

/rest/sign/closeSession

Request

Expand

title	request-sign-closeSession

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

"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
}

content

file to sign

Response

byte array of signed files

SIGN: signPades

Description

permits to apply the pades signature

HttpMethod

POST

Path

/rest/sign/sendOtpBySMSsignPades

Request

credentials

Description

permits to apply the cades signature

HttpMethod

POST

Path

/rest/sign/signCades

Request

credentials

Expand

title	request-signsignPades-closeSessioncredentials

{

"credentialsusername": {
"username"device signer name",

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

Response

SIGN: signCades

,

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

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

padesPreferences

Expand

title	request-signCadessignPades-credentialspadesPreferences

Expand

title	request-signCades-cadesPrefernces

{
"filenameInTSD": "string",
"usernameoutputAsPDF": "device signer name",

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

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

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

cadesPreferences

{
"filenameInTSDboolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
"timestampUsername": "string",
"hashAlgorithm": "string",
"outputAsPDFlevel": boolean"enum",
"outputAsTSDwithTimestamp": boolean,
"outputBase64EncodedencryptInAnyCase": boolean,
"timestampHashAlgoencryptionPassword": "string",
"timestampPasswordlockFields": [
"string"
],
"timestampUrlneedAppearanceDisabled": boolean,
"stringpage": 0,
"timestampUsername"signerImage": {
"fieldName": "string",
"hashAlgorithmfontName": "string",
"level "fontSize": 0,
"image": "enumstring",
"withTimestampimageFilename": boolean"string",
"counterSignatureimageURL": true,
"counterSignatureIndexstring": 0,
"detached": boolean
}

content

file to sign

Response

byte array of signed files

SIGN: signPades

HttpMethod	POST
Description	permits to apply the pades signature
Path	/rest/sign/signPades
Request	credentials

Expand

title	request-signPades-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"

}

padesPreferences

Expand

title	request-signPades-padesPreferences

{
"filenameInTSD": "string",
"outputAsPDF": boolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPasswordimageVisible": boolean,
"location": "string",
"reason": "string",
"scaled": true,
"signerName": "string",
"textPosition": "enum",
"textVisible": boolean,
"width": int,

"height":int,
"x": int,
"y": int
},
"signerImageReference": "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": boolean,
"locationwithSignatureField": boolean
}

imagefile with image (of appereance) contentPDF file to signResponsebyte array of signed files

SIGN: signXades

Description

permits to apply the pades signature

HttpMethod

POST

Path

/rest/sign/signXades

Request

credentials

Expand

title	request-signPades-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"

}

xadesPreferences

Expand

title	request-signPades-padesPreferences

{
"filenameInTSD": "string",
"outputAsPDF": boolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"reasontimestampUrl": "string",
"scaledtimestampUsername": true"string",
"signerNamehashAlgorithm": "string",
"textPositionlevel": "enum",
"textVisiblewithTimestamp": boolean,
"widthdetached": intboolean,
"heightdetachedReferenceURI": int"string",
"xsignElement": int"string",
"ysignatureId": int
}"string",
"signerImageReferencewithoutSignatureExclusion": "string"boolean,
"withSignatureFieldxPathQuery": boolean"string"
}

content

XML file to sign

Response

byte array of signed files

...

Version	Old Version 30	New Version 31
Changes made by	Lorenzo Cardinali	Lorenzo Cardinali
Saved on	Sept 01, 2022	Sept 01, 2022

Content Comparison

Versions Compared

Key

Introduction

Enquiry

ENQUIRY: certificate

Introduction

Enquiry

ENQUIRY: certificate

ENQUIRY: signatures

ENQUIRY: signatures-available

ENQUIRY: otps

ENQUIRY: signatures

ENQUIRY: timestamps-available

ENQUIRY:

errors

ENQUIRY: timestamps-available

Admin

ADMIN: remove-certificate-from-cache

Timestamps

TIMESTAMPS: apply

ENQUIRY: errors

User

USER: change-password

Admin

ADMIN: remove-certificate-from-cache

Sign

SIGN: openSession

TIMESTAMPS: apply

Timestamps

SIGN: getRemainingTimeForSession

USER: change-password

User

SIGN: closeSession

SIGN: sendOtpBySMS

Sign

SIGN:

signCades

SIGN: getRemainingTimeForSession

SIGN: sendOtpBySMS

SIGN: closeSession

SIGN: signPades

SIGN: signCades

SIGN: signPades

SIGN: signXades