Extend Signature API
An Access Token is required to authorize all API requests, as explained at the following link:
DIGITAL EXTEND SIGNATURE REQUEST
REST service specs:
Method: POST
URL: {viafirma_fortress_url}/api/v1/signature/extend
Security:
Authorization: Bearer {access_token}
Where:
viafirma_fortress_url
: URL of the Fortress implementation, for example https://sandbox.viafirma.com/fortress or https://fortress.viafirma.com/fortress
Sample Request
Method: POST
URL: {viafirma_fortress_url}/api/v1/signature/extend
Security Header: Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42
Request Params
The request body contains information such as signature format, document to be signed, etc.
application/json
format is used:
{
"extendSignatureConfigurations": [
{
"document": {
"bytesB64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQ...",
"name": "contract.pdf"
},
"signatureType": "PADES_LTA",
"signatureAlgorithm": "RSA_SHA256",
"packaging": "ENVELOPED",
"padesConfiguration": {
"stamper": {
"csvPath": "http://<someURL>/v#",
"logoB64": "iVBORw0KGgoAAAANSUhEUgAAAWYAAABsCAYAAABZyhj...",
"page": 1,
"type": "QR_BARCODE128",
"xAxis": 80,
"yAxis": 700
}
},
"tsa": {
"type": "URL",
"url": "https://testservices.viafirma.com/via-tsa/tsa"
}
}
]
}
Note: params for padesConfiguration
, xadesConfiguration
, tsa
and policy
are described later.
Where:
Param | Type | Desc |
---|---|---|
userCode | string | OPTIONAL, used to to specify the signer user. If null, user will be requested to authenticate before signing. |
document/bytesB64 | string | Document to be signed (Base64) |
signatureType | string | Signature format: - CADES_T - CADES_LT - CADES_LTA - PADES_T - PADES_LT - PADES_LTA - XADES_T - XADES_LT - XADES_LTA - PKCS1 |
signatureAlgorithm | string | signature algorithm: - RSA_SHA1 - RSA_SHA224 - RSA_SHA256 - RSA_SHA384 - RSA_SHA512 |
packaging | string | signature type: - ENVELOPED - ENVELOPING - DETACHED |
PAdES Configuration
Params only applicable to signatureType
PAdES (PAdES T, PAdES LT, PAdES LTA).
"padesConfiguration": {
"stamper": { }
}
The stamper object is optional, and it defines a visual stamp associated with the signature PAdES.
{
"stamper": {
"csvPath": "https://sandbox.viafirma.com/fortress/v#",
"imageB64": "JVBERi0xLjMKJcTl8uXlRU9GC...",
"logoB64": "JVBERi0xLjMKJcTl8uXlRU9GC...",
"page": 1,
"rotation": "ROTATE_90",
"textLine1": "Sample line 1",
"textLine2": "Sample line 2",
"textLine3": "Sample line 3",
"type": "QR_BARCODE128",
"xAxis": 100,
"yAxis": 100
}
}
Param | Type | Desc |
---|---|---|
stamper/csvPath | string | public URL for validating signed documents |
stamper/xAxis | int | Stamper position on PDF; X-coordinates |
stamper/yAxis | int | Stamper position on PDF; Y-coordinates |
stamper/imageB64 | string | Stamper watermark (Base64) |
stamper/imageUrl | string | Stamper watermark (URL) |
stamper/logoB64 | string | Logo to be printed (Base64) |
stamper/page | int | Page number where stamper will be embedded. Value -1 for last page, 0 for all pages. |
stamper/rotation | string | OPTIONAL. Rotation degrees: - ROTATE_90 - ROTATE_270 |
stamper/textLine1 | string | OPTIONAL. Text included in the stamper (line 1). |
stamper/textLine2 | string | OPTIONAL. Text included in the stamper (line 2). |
stamper/textLine3 | string | OPTIONAL. Text included in the stamper (line 3). |
stamper/type | string | Stamper type: - PDF417 - QR_BARCODE128 - QR - BARCODE128 - IMAGE - TEXT - QR_NO_TEXT - QR_SCALED - CUSTOM_TEXT - QR_REDUCED - CSV - CSV_QR - IMAGE_TEXT - DEFAULT |
stamper/timeZoneId | string | Set the Time Zone. for stamper date to be printed |
XAdES Configuration
Params only applicable to signatureType
XAdES (XAdES B, XAdES T, XAdES LT, XAdES LTA)
{
"signedInfoCanonicalizationMethod": "http://www.w3.org/TR/2001/REC-xml-c14n-20010315",
"signedPropertiesCanonicalizationMethod": "http://www.w3.org/TR/2001/REC-xml-c14n-20010315",
"xPathLocationString": "//book[@id='bk101-1']",
"claimedSignerRoles": [
"role1",
"role2"
],
"transformAlgorithms": [
"http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
],
"dssReferenceUri": "http://dsa-reference.example.com/"
}
Where:
Param | Type | Desc |
---|---|---|
signedInfoCanonicalizationMethod | string | Canonicalization Method of node signedInfo |
signedPropertiesCanonicalizationMethod | string | Canonicalization Method of node signedProperties |
xPathLocationString | string | XPath of ID node (XML) to be signed |
claimedSignerRoles | array | Signer role |
transformAlgorithms | array | Transform Algorithm of signed node: - "http://www.w3.org/TR/2001/REC-xml-c14n-20010315" - "http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments" - "http://www.w3.org/2001/10/xml-exc-c14n#" - "http://www.w3.org/2001/10/xml-exc-c14n#WithComments" - "http://www.w3.org/2006/12/xml-c14n11" - "http://www.w3.org/2006/12/xml-c14n11#WithComments" - "http://santuario.apache.org/c14n/physical" |
dssReferenceUri | string | ID node (XML) to be signed |
TSA Configuration
TSA configuration is mandatory if a signature format that requires timestamp is used:
{
"url": "http://tsa.example.com/",
"user": "tsa_user",
"password": "tsa_pass",
"type": "USER",
"certificateCode": "tsa_certificate_code"
}
Param | Type | Desc |
---|---|---|
type | string | Authentication type: USER CERTIFICATE CERTIFICATE_TLS of URL (if authentication is not required) |
user | string | OPTIONAL. Only when USER type is used |
password | string | OPTIONAL. Only when USER or CERTIFICATE or CERTIFICATE_TLS type is used |
url | string | TSA url |
certificateCode | string | OPTIONAL. Only when CERTIFICATE or CERTIFICATE_TLS type is used |
POLICIES Configuration
Only applicable to XAdES EPES format; a Signature Policy can be defined:
{
"id": "102039485-10283757-102837575",
"description": "Sample policy",
"digestAlgorithm": "SHA256",
"digestValueB64": "JVBERi0xLjMKJcTl8uXlRU9GC",
"contentHintsDescription": "Lorem ipsum dolor sit amet",
"contentHintsType": "Lorem ipsum dolor sit amet"
}
Param | Type | Desc |
---|---|---|
id | string | Policy id |
description | string | Policy description |
digestAlgorithm | string | Cipher Algorithm: - SHA1 - SHA224 - SHA256 - SHA384 - SHA512 - RIPEMD160 - MD2 - MD5 |
digestValueB64 | string | Policy Digest value (Base64) |
contentHintsDescription | string | Help Description |
contentHintsType | string | Help content type |
Response
Response in application/json
format:
{
"ref": "d8e3d98dc20e46188fd067df28048934",
"bytesB64": "MIMBKM8GCSqGSIb3DQEHAqCDASi/MIMBKLoCAQUxDzANBglghkgBZQMEAgEFADCC1QsGCSqGSIb3DQEHAaCC1PwEgtT4JVBERi0xLjMKJcTl8uXrp..."
}
Where:
Param | Type | Desc |
---|---|---|
ref | string | reference code |
bytesB64 | string | Extend signed document (Base64) |
API Errors
Errors are returned using application/json
format:
{
"error": "error_code",
"error_description": "error_description"
}
Where:
Param | Type | Desc |
---|---|---|
error | string | Error code |
error_description | string | Error description |
Errors:
Error code | Error desc |
---|---|
invalid_request | Bad request. Incorrect of insufficient request params. (HTTP Status: 400) |
invalid_token | Invalid access_token (HTTP Status: 401) |
user_not_found | Incorrect or inactive user (HTTP Status: 404) |
results matching ""
No results matching ""