SignBuilder: API Rest
- Armando Carratala
Usage
The following section describes the REST interface.
Any future version can be found in this link: Next PDFSign Builder REST Interface.
API REST v2
The latest available interface documentation can be reached following this link: PDFSign Builder V2 REST interface.
Pre-Sign (phase one)
Phase one
POST /signer/v2/server/phase-one
This function allows generating a HASH string to be signed. This value is used to generate the signature.
Parameter
{
"hashAlgo": {{hash_algorithm}},
"reason": {{signature_reason}},
"certificateChain":"MIIDTDCCAjSgAwIBA...I6an6ss=",
"location": {{signature_location}},
"position": {{position}}
}
Field | Type | Req | Description |
|---|---|---|---|
hashAlgo | string | ✔ | Random string to identify the uploaded file. This value must be used to request the signature. Posible values: "SHA1", "SHA256", "SHA368", "SHA512". |
reason | string |
| String indicanting the reason of the signature. Some examples are: "I'm the author of the document", "I approve this document". |
certificateChain | string | ✔ | Certificate Chain (P7B) as a Base64 string. A single string is required. Strip endlines or any special character. |
location | string |
| Indicates the location (Country, State, City) where the signature is done. |
position | JSON |
| JSON structure to indicate the position of the signature. { "page": (one of the possible values = first, last or new), "positionOnPage" : (one of the possible values = footer or header) } If the field position is not present, then an invisible signature is used. |
Response:
Upload-File response
{
"id": {{file-id}}
"hash": {{file-hash}}
}
Field | Values | Description |
|---|---|---|
id | string | Random string to identify the uploaded file. This value must be used to request the Post-sign service. |
hash | string | Hash to be used to generate the signature. |
.
API REST v1 - legacy
(this interface will be remover since version 3.x)
Healtcheck
GET /signer/v1/healthcheck
The response returned on the HTTP / HTTPS connection will be a HTTP 200 code.
Below is the definition of the JSON response returned.
Response:
HealthCheck response
{
"code": 0,
"version": "1.0.6.0",
"description": {{description}},
"instance_id": {{randon-value}}
}Field | Values | Description |
|---|---|---|
code | integer | Status of the docker instance. No error == 0. |
version | x.y.z | The current version of the service. |
description | string | Error description or an empty string. |
instance | string | The identity number of the docker instance. |
.
Upload File
POST /signer/v1/upload-file
This function can be used to upload a PDF or image file.
Parameter
Response:
Upload-File response
Field | Values | Description |
|---|---|---|
file-id | string | Random string to identify the uploaded file. This value must be used to request the signature. |
.
Pre-Sign
POST /signer/v1/{file-id}/pre-sign
This function allows generating a HASH string to be signed. This value is used to generate the signature.
Parameter
Field | Type | Req | Description |
|---|---|---|---|
hashAlgo | string | ✔ | Random string to identify the uploaded file. This value must be used to request the signature. Posible values: "SHA1", "SHA256", "SHA368", "SHA512". |
reason | string | String indicanting the reason of the signature. Some examples are: "I'm the author of the document", "I approve this document". | |
certificateChain | string | ✔ | Certificate Chain (P7B) as a Base64 string. A single string is required. Strip endlines or any special character. |
location | string | Indicates the location (Country, State, City) where the signature is done. | |
position | JSON | JSON structure to indicate the position of the signature. { "page": (one of the possible values = first, last or new), "positionOnPage" : (one of the possible values = footer or header) } If the field position is not present, then an invisible signature is used. |
Response:
Upload-File response
Field | Values | Description |
|---|---|---|
id | string | Random string to identify the uploaded file. This value must be used to request the Post-sign service. |
hash | string | Hash to be used to generate the signature. |
.
Post-Sign
POST /signer/v1/{pre-sign-id}/post-sign
This function is used to inform the signature and compose the final signed file.
Parameter
Field | Type | Req | Description |
|---|---|---|---|
signedHash | B64 | ✔ | String in base64 format with the signature of the hash generated on the previous step. |
Response: