Versions Compared

Version Old Version 47 New Version 48
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 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:

Image Removed

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:

Image Removed

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

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 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:

Image Added


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:

Image Added

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













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/certificatesignatures-available
Request


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


ResponseNumber of signatures available



ENQUIRY: otps


Descriptionreturn the byte array of certificate otp list associated to "device_signer

ENQUIRY: signatures

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


Expand
titlerequest-enquiry-otps
{
  "credentials": {
    "username": "device_signer"
Request
  }
POST
Path
/rest/enquiry/signatures
}


Response


Expand
titlerequestresponse-enquiry-signaturesotps

[
    {


  "credentials": {
    "username": "device_signer"
  }
}
ResponseNumber of signatures apposed
ENQUIRY: signatures


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




ENQUIRY: timestamps-available


Descriptionreturn the number of signatures which "device_signer" can applynumeber of timestamp available (valid only for Namirial TSA account)
HttpMethodPOST
Path
/rest/enquiry/signaturestimestamps-available
Request


Expand
titlerequest-enquiry-signaturestimestamps-available

{
  "

credentials

timestampUrl":

{
    "username

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

device_signer"
  }

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


ResponseNumber of signatures timestamps available


ENQUIRY:

otps

errors


Descriptionreturn the otp list error description associated to "device_signer"error code
HttpMethodPOST
Path
/rest/enquiry/otpserrors
RequestDescriptionreturn the numeber of timestamp available (valid only for Namirial TSA account)


Expand
titlerequest-enquiry-otpserrors

{
  

"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

"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/admin/remove-certificate-from-cache
Request


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

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


Response


Timestamps

TIMESTAMPS: apply

Descriptionpermits to apply timestamp on specified file
HttpMethodPOST
Path
/rest/enquirytimestamps/timestamps-availableapply
Request
timeStampPreferencesDescriptionreturn the error description associated to error code


Expand
titlerequest-enquiry-timestamps-availableapply

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

ResponseNumber of timestamps available

ENQUIRY: errors


  "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/errorschange-password

ADMIN: remove-certificate-from-cache

Descriptionremove the certificate from cache of SWS
HttpMethodPUT
Path
/rest/admin/remove-certificate-from-cache
Request (for remote device signer)
Request


Expand
titlerequest-user-change-enquirypassword-errorsremote

{
  "error_codecredentials": integer, {
      "langidOtp":  "COUNTRY-CODE-2DIGIT"
}

Response
Expand
titleresponse-enquiry-errors

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

Admin

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
titlerequest-enquiryuser-removechange-certificatepassword-from-cacheautomatic

{
  "error_code": integer"credentials": {
    "securityCode": "securityCode associate to automatic device signer",
    "password": "old-password-of-device-signer-automatic",
    "username": "device-signer-automatic"
  },
  "lang": "COUNTRY-CODE-2DIGITnewPassword": "new-password-of-device-signer-automatic"
}


ResponsePassword update succesfully


Timestamps

Sign

TIMESTAMPS

SIGN:

apply

openSession


Descriptionpermits to apply timestamp on specified fileopen the sessione for apply multiple sign with remote device
HttpMethodPOST
Path
/rest/timestampssign/applyopenSession
RequesttimeStampPreferences

USER: change-password

Descriptionpermits to change the password associated to device signer


Expand
titlerequest-timestampssign-applyopenSession

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

contentfile to apply timestamp
Response

User

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


ResponseString with the session


SIGN: getRemainingTimeForSession


Descriptionpermits to obtain the time until the session is valid
HttpMethodPOST
Path
/rest/usersign/change-passwordgetRemainingTimeForSession
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-getRemainingTimeForSession

{
  "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)

}
}


ResponseSeconds until the session is valid


SIGN: closeSession


Descriptionpermits to destroy the session before will expire
HttpMethodPOST
Path
/rest/sign/closeSession
Request


Expand
titlerequest-user-change-password-automaticsign-closeSession

{
  "credentials": {
    "securityCode": "securityCode associate to automatic device signer",
    "passwordsessionKey": "old-password-of-device-signer-automaticzZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==",
    "username": "device-signer-automaticRHIP22021116852552"
  },
  "newPassword": "new-password-of-device-signer-automatic"
}


ResponsePassword update succesfully

Sign



SIGN:

openSession

sendOtpBySMS


Descriptionpermits to open the sessione for apply multiple sign with remote devicedestroy the session before will expire
HttpMethodPOST
Path
/rest/sign/openSessionsendOtpBySMS
Request


{
  "credentials": {
    "idOtp": -1,
    "otp": "775351",
    "password": "12345678",
Expand
titlerequest-sign-openSession
closeSession

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


ResponseString with the session


SIGN:

getRemainingTimeForSession

signCades


Descriptionpermits to obtain the time until the session is validapply the cades signature
HttpMethodPOST
Path
/rest/sign/getRemainingTimeForSessionsignCades
Request
credentials


Expand
titlerequest-signsignCades-getRemainingTimeForSessioncredentials

{  

"credentialsusername": {
    "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 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"
  }
}

ResponseSIGN: signCades

"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": "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 cades pades signature
HttpMethodPOST
Path
/rest/sign/signCadessignPades
Request
credentials


Expand
titlerequest-signCadessignPades-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"

}


cadesPreferencespadesPreferences


Expand
titlerequest-signCadessignPades-cadesPreferncespadesPreferences

{
  "filenameInTSD": "string",
  "outputAsPDF": boolean,
  "outputAsTSD": boolean,
  "outputBase64Encoded": boolean,
  "timestampHashAlgo": "string",
  "timestampPassword": "string",
  "timestampUrl": "string",
  "timestampUsername": "string",
  "hashAlgorithmoutputAsPDF": "string"boolean,
  "leveloutputAsTSD": "enum"boolean,
  "withTimestampoutputBase64Encoded": boolean,
  "counterSignaturetimestampHashAlgo": true"string",
  "counterSignatureIndextimestampPassword": 0"string",
  "detached": boolean
}

contentfile to sign
Responsebyte array of signed files

SIGN: signPades

Descriptionpermits to apply the pades signature
HttpMethodPOST
Path
/rest/sign/signPades
Requestcredentials
Expand
titlerequest-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
titlerequest-signPades-padesPreferences

{
  "filenameInTSD": "string",
  "outputAsPDFtimestampUrl": "string",
  "timestampUsername": "string",
  "hashAlgorithm": "string",
  "level": "enum",
  "withTimestamp": boolean,
  "encryptInAnyCase": boolean,
  "encryptionPassword": "string",
  "lockFields": [
    "string"
  ],
  "needAppearanceDisabled": boolean,
  "outputAsTSDpage": boolean0,
  "outputBase64EncodedsignerImage": boolean,{
    "timestampHashAlgofieldName": "string",
    "timestampPasswordfontName": "string",
    "timestampUrlfontSize": "string"0,
    "timestampUsernameimage": "string",
    "hashAlgorithmimageFilename": "string",
    "levelimageURL": "enumstring",
    "withTimestampimageVisible": boolean,
  "encryptInAnyCase": boolean,
  "encryptionPasswordlocation": "string",
    "lockFieldsreason": [
    "string",
  ],
  "needAppearanceDisabledscaled": booleantrue,
    "pagesignerName": 0,
  "signerImagestring": {,
    "fieldNametextPosition": "stringenum",
    "fontNametextVisible": "string"boolean,
    "fontSizewidth": 0int,

     "imageheight":int,
    "stringx": int,
    "imageFilenamey": "string"int
  },
    "imageURLsignerImageReference": "string",
    "imageVisible": boolean,
    "location": "string",
    "reason": "string",
    "scaled": true,
    "signerName": "string",
    "textPosition": "enum",
    "textVisible": boolean,
    "width": int,     "height":int,
    "x": int,
    "y": int
  },
  "signerImageReferencewithSignatureField": boolean
}


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


SIGN: signXades

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


Expand
titlerequest-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
titlerequest-signPades-padesPreferences

{
  "filenameInTSD": "string",
  "withSignatureFieldoutputAsPDF": boolean
}

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

SIGN: signXades

Descriptionpermits to apply the pades signature
HttpMethodPOST
Path
/rest/sign/signXades
Requestcredentials
Expand
titlerequest-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"

}

xadesPreferencesXML file
Expand
titlerequest-signPades-padesPreferences

{
  "filenameInTSD,
  "outputAsTSD": boolean,
  "outputBase64Encoded": boolean,
  "timestampHashAlgo": "string",
  "timestampPassword": "string",
  "timestampUrl": "string",
  "timestampUsername": "string",
  "hashAlgorithm": "string",
  "level": "enum",
  "withTimestamp": boolean,
  "detached": boolean,
  "detachedReferenceURI": "string",
  "outputAsPDFsignElement": boolean"string",
  "outputAsTSDsignatureId": boolean"string",
  "outputBase64EncodedwithoutSignatureExclusion": boolean,
  "timestampHashAlgoxPathQuery": "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"
}

content


}


contentXML file to signResponsebyte array of signed files


SIGN: signPKCS1

Descriptionpermits to apply the raw signature (PKCS1)
HttpMethodPOST
Path
/rest/sign/signPKCS1
Request
credentials


Expand
titlerequest-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"

}


signPreferences


Expand
titlerequest-signPKCS1-signPreferences

{
    "hashAlgorithm": "enum"
}


bufferhash to sign
Responsebyte array of signed files
SIGN: signPKCS1
associated to hash signed


Verify

Verify signatures

VERIFY: signatures

VERIFY: signPKCS1
Descriptionpermits to
apply the raw signature (PKCS1)
verify the signatures
HttpMethodPOST
Path
/rest/
sign
verify/
signPKCS1
signatures
Request
signedContentfile to verify
credentials


Expand
titlerequest-signPades-credentials

{
  "

username

detachedContent": "

device signer name",

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

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

"otp":"otp code",

"sessionKey

string",
  "language": "COUNTRY_CODE_2_DIGIT" (es: IT),
  "pdfEncryptionPassword": "string

with sessionKey

"

}

signPreferences
Expand
titlerequest-signPKCS1-signPreferences

{
    "hashAlgorithm": "enum"
}

bufferhash to signResponsebyte array associated to hash signed

Verify

,
  "recursive": true,
  "verifyOnDate": "YYYY-mm-dd" (for example: 2022-10-24)
}


ResponseReport with verify, this is a complex object: "SignedDocumentReportBean"


VERIFY: signatures

Descriptionpermits to verify the signaturesignatures
HttpMethodPOST
Path
/rest/verify/signatures
Request
signedContentfile to verify
credentials


Expand
titlerequest-signPades-credentials

{
  "checkByteRange": boolean,
  "detachedContent": "string",
  "language": "COUNTRY_CODE_2_DIGIT" (es: IT)",
  "pdfEncryptionPassword": "string",
  "recursive": true,
  "validBehaviourOnDateverifyOnDate": "SPECIFIEDTIME",
  "verifyOnDate": "YYYY-mm-dd" (for example: 2022-10-24",)
}

signPreferences
Expand
titlerequest-signPKCS1-signPreferences

{
    "hashAlgorithm": "enum"
}

bufferhash to sign


Responsebyte array associated to hash signedResponseReport with verify, this is a complex object: "SignedDocumentReportBean"


Tools for integrate


At this link you can download the collection Postman and at this link the files used to make a test REST request.


...