Standard interface

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 guide will be described how manage the error generated by the REST interface.

NOTE: this interface is available from SWS version: 2.5.52

Convention (manage the response)

SWS rest interface use this convention for create the response

Request is CORRECT, will return response code 200 with response body (if present) . Like in this example:

Request NOT-CORRECT with error managed, will return response code 400 and the header will have the field "errorMsg" with error description (in Italian) and field "errorCode" with code error. Like in this example:

NOTE: if you want the "errorMsg" in a specified language, you can use the method "enquiry/errors" will be described in the next section.

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": boolean, "outputAsTSD": boolean, "outputBase64Encoded": boolean, "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 }
buffer	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, "scaledText": boolean, "width": int, "height":int, "x": int, "y": int }, "signerImageReference": "string", "withSignatureField": boolean }
image	file with image (of appereance)
buffer	PDF file to sign
Response	byte array of signed files

SIGN: signXades

HttpMethod	POST
Description	permits to apply the xades signature
Path	/rest/sign/signXades
Request
credentials	request-signXades-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	request-signXades-xadesPreferences { "filenameInTSD": "string", "outputAsPDF": boolean, "outputAsTSD": boolean, "outputBase64Encoded": boolean, "timestampHashAlgo": "string", "timestampPassword": "string", "timestampUrl": "string", "timestampUsername": "string", "hashAlgorithm": "string", "level": "enum", "withTimestamp": boolean, "detached": boolean, "detachedReferenceURI": "string", "signElement": "string", "signatureId": "string", "withoutSignatureExclusion": boolean, "xPathQuery": "string" }
buffer	XML file to sign
Response	byte array of signed files

SIGN: signPKCS1

HttpMethod	POST
Description	permits to apply the raw signature (PKCS1)
Path	/rest/sign/signPKCS1
Request
credentials	request-signPkcs1-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" }
signPreferences	request-signPKCS1-signPreferences { "hashAlgorithm": "enum" }
buffer	hash to sign
Response	byte array associated to hash signed

Verify

VERIFY: signatures

HttpMethod	POST
Description	permits to verify the signatures
Path	/rest/verify/signatures
Request
signedContent	file to verify
preferences	request-verify-signatures { "detachedContent": "string", "language": "COUNTRY_CODE_2_DIGIT" (es: IT), "pdfEncryptionPassword": "string", "recursive": true, "verifyOnDate": "YYYY-mm-dd" (for example: 2022-10-24) }
Response	Report with verify, this is a complex object: "SignedDocumentReportBean"

Verify timestamp

With SWS is possible to verify TSD and TSR, below will be described the REST request.

VERIFY: tsd

HttpMethod	POST
Description	permits to verify the signatures
Path	/rest/verify/timestamps/tsd
Request
tsd	file to verify
Response	Return a list of complex objects: "TimestampReportBean"

VERIFY: tsr

HttpMethod	POST
Description	permits to verify the signatures
Path	/rest/verify/timestamps/tsr
Request
tsd	file to verify
content	file original, where timestamp has ben applied
Response	Return a complex object "TimestampReportBean"

Page tree