Standard interface (not released yet)

Introduction

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

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

HttpMethod	POST
Description	return the certifcate associated to "device_signer"
Path	/rest/enquiry/certificate
Request	request-enquiry-certificate { "credentials": { "username": "device_signer" } }
Response	return the byte array of certificate associated to device_signer

ENQUIRY: signatures

HttpMethod	POST
Description	return the numer of signatures apposed from "device_signer"
Path	/rest/enquiry/signatures
Request	request-enquiry-signatures { "credentials": { "username": "device_signer" } }
Response	Number of signatures apposed

ENQUIRY: signatures-available

HttpMethod	POST
Description	return the number of signatures which "device_signer" can apply
Path	/rest/enquiry/signatures-available
Request	request-enquiry-signatures-available { "credentials": { "username": "device_signer" } }
Response	Number of signatures available

ENQUIRY: otps

HttpMethod	POST
Description	return the otp list associated to "device_signer"
Path	/rest/enquiry/otps
Request	request-enquiry-otps { "credentials": { "username": "device_signer" } }
Response	response-enquiry-otps [ { "idOtp": number, "serialNumber": "string", "type": "otp-type-enum" }, { "idOtp": number, "serialNumber": "string", "type": "otp-type-enum" } ]

ENQUIRY: timestamps-available

HttpMethod	POST
Description	return the numeber of timestamp available (valid only for Namirial TSA account)
Path	/rest/enquiry/timestamps-available
Request	request-enquiry-timestamps-available { "timestampUrl": "timestamp-namirial-enquiry-url", "timestampUsername": "tsa-username", "timestampPassword": "tsa-password" }
Response	Number of timestamps available

ENQUIRY: errors

HttpMethod	POST
Description	return the error description associated to error code
Path	/rest/enquiry/errors
Request	request-enquiry-errors { "error_code": integer, "lang": "COUNTRY-CODE-2DIGIT" }
Response	response-enquiry-errors [ { "errorCode": integer, "errorLanguage": "CONUNTRY-CODE-2DIGIT", "errorLanguage2": "COUNTRY-CODE-3DIGIT", "errorText": "Description error in language" } ]

Admin

ADMIN: remove-certificate-from-cache

HttpMethod	PUT
Description	remove the certificate from cache of SWS
Path	/rest/admin/remove-certificate-from-cache
Request	request-enquiry-remove-certificate-from-cache { "error_code": integer, "lang": "COUNTRY-CODE-2DIGIT" }
Response

Timestamps

TIMESTAMPS: apply

HttpMethod	POST
Description	permits to apply timestamp on specified file
Path	/rest/timestamps/apply
Request
timeStampPreferences	request-timestamps-apply { "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/user/change-password
Request (for remote device signer)	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)	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	request-sign-openSession { "credentials": { "idOtp": -1, "otp": "775351", "password": "12345678", "username": "RHIP22021116852552" } }
Response	String with the session

SIGN: getRemainingTimeForSession

HttpMethod	POST
Description	permits to obtain the time until the session is valid
Path	/rest/sign/getRemainingTimeForSession
Request	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

HttpMethod	POST
Description	permits to destroy the session before will expire
Path	/rest/sign/closeSession
Request	request-sign-closeSession { "credentials": { "sessionKey": "zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==", "username": "RHIP22021116852552" } }
Response

SIGN: sendOtpBySMS

HttpMethod	POST
Description	permits to destroy the session before will expire
Path	/rest/sign/sendOtpBySMS
Request	request-sign-closeSession { "credentials": { "username": "RHIP22021116852552" } }
Response

SIGN: signCades

HttpMethod	POST
Description	permits to apply the cades signature
Path	/rest/sign/signCades
Request
credentials	request-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	request-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 }
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	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	request-signPades-padesPreferences { "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": boolean, "location": "string", "reason": "string", "scaled": true, "signerName": "string", "textPosition": "enum", "textVisible": boolean, "width": int, "height":int, "x": int, "y": int }, "signerImageReference": "string", "withSignatureField": boolean }
content	file to sign
Response	byte array of signed files