Universign Guide 8.8

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 28

DownloadUniversign-guide-8.8
Open PDF In BrowserView PDF
Universign Signature
Signature Service Guide

REF: SIGNATURE-GUIDE

DIFFUSION: RESTRICTED

VERSION: 8.8

SIGNATURE-GUIDE

VERSION: 8.8

c 2003-2017, Universign. All rights reserved.

This document is the exclusive property of Universign and is protected by
its copyrights, branding, patents and any other intellectual or industrial property
rights granted to it in accordance with the laws in force. Except as expressly authorized by Universign, none of the information provided in this document can be
copied, reproduced, published, displayed, posted or transmitted in any form or by
any means.
Any total or partial reproduction of this document, without prior express authorisation from Universign, would constitute an infringement punishable under
French law.
Universign is a registered trademark of Cryptolog International SAS.

This is a technical document, it has no legal binding value.

Universign
5-7 rue du Faubourg Poissonnière
F-75009 Paris
France
Tel: +33 1 44 08 73 00
Fax: +33 1 43 56 50 42
https://www.universign.com
U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 2 / 28

Contents
1

Introduction

4

2

General Information
2.1 Signature modes . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.1 Document signature (server side) . . . . . . . . . . .
2.1.2 Contract signature (client side) . . . . . . . . . . . . .
2.1.3 Contract signature (client side) with signer registration
2.2 Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Authentication and confidentiality . . . . . . . . . . . . . . .
2.4 Signature format and standard . . . . . . . . . . . . . . . . .
2.5 Services pre-configuration . . . . . . . . . . . . . . . . . . .
2.6 Documents retention policy and documents retrieval . . . . . .

5
5
5
5
5
7
8
8
8
9

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

3

Signature service API

10

4

Data objects
4.1 SignOptions . . . . . . . . . .
4.2 TransactionRequest . . . . . .
4.3 TransactionSigner . . . . . . .
4.4 RegistrationRequest . . . . . .
4.5 TransactionDocument . . . . .
4.6 SignatureField . . . . . . . . .
4.7 SEPAData . . . . . . . . . . .
4.8 SEPAThirdParty . . . . . . . .
4.9 TransactionResponse . . . . .
4.10 TransactionInfo . . . . . . . .
4.11 SignerInfo . . . . . . . . . . .
4.12 InitiatorInfo . . . . . . . . . .
4.13 CertificateInfo . . . . . . . . .
4.14 TransactionFilter . . . . . . .
4.15 StandaloneRegistrationRequest

12
12
13
16
19
19
20
21
21
22
22
23
25
25
25
26

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

SIGNATURE-GUIDE

1

VERSION: 8.8

Introduction

This document explains general functionalities of the U NIVERSIGN Signature Service and how to integrate it with existing applications.
This document is structured as follows:
• section 2 introduces the functionalities of the service;
• section 3 is a guide to the API used to configure and use the service;
• the appendices contain more detailed references to technicals details such
as error code meaning.
While great care has been taken to make integration as simple as possible, the
reader is assumed to be familiar with programming concepts in the language used
for integration.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 4 / 28

SIGNATURE-GUIDE

2

VERSION: 8.8

General Information

2.1

Signature modes

The U NIVERSIGN signature service proposes three modes of signature.
2.1.1

Document signature (server side)

This mode allows a U NIVERSIGN user to perform a signature on a PDF document,
using our web-service API. In practice, it consists in a single remote procedure call
which returns the signed PDF synchronously.
The used private key has to be previously uploaded to U NIVERSIGN by the
user, using http://universign.com website.
2.1.2

Contract signature (client side)

This mode allows one or more people to sign a list of documents. It implies the
intervention of two kinds of actors:
• a single requester, who is a U NIVERSIGN user and creates a transaction
with the documents to sign, a list of signers and some options;
• one or more signers, who are invited one after another to sign the documents
using a user-friendly web interface.
The creation of the transaction, the retrieval of the signed documents and the
retrieval of information on the status of a transaction are made through the U NI VERSIGN Web Service API by the requester. The requester also chooses which
certificate types are allowed for the signers to use.
The selection of the private key to use, the approval of the terms of the documents and the launching of signature process are made by the signer. Each signer
reaches the signature web interface via an URL containing a unique id. Each
signer receives his URL by mail, except possibly the first if the requester chooses
to.
Those interactions are depicted with a very simple example on figure 1.
This mode has an extension which is described in the following section.
2.1.3

Contract signature (client side) with signer registration

It’s important to note that Universign is also a Registration Authority (RA), a
signer can register himself in order to obtain a certificate issued from Universign. This will make his identity certified by Universign and allow him to sign

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 5 / 28

SIGNATURE-GUIDE

VERSION: 8.8

a certified signature. In order to register his identity, a user should send his ID
documents to Universign RA, this can be done in two ways:
• By using the API: when requesting a transaction, the ID documents of a
signer can be sent to Universign RA using the requester.requestTransaction
service and setting the idDocuments key of the TransactionSigner data
object.
The API also allows a standalone registration of the signer using
requester.requestRegistration or requester.requestTwoStepsRegistration
• By using the web interface: if a transaction was requested to use the
certified signature and if the current signer is not yet certified by Universign, then when he will proceed to sign the transaction he will be requested
to provide his ID documents.
The ID documents that can be used to register a user are:
• French ID card.
• French Passport.
• Residence Permit.
• European Driving License (New Format, issued since September 2013).
When registering his identity, a user will follow these steps:
• Check his identity information by indicating his birth date and confirming it
and his phone number. The birth date may was already indicated when the
transaction was requested with setting the birthDate key of the
TransactionSigner data object.
• Provide his ID documents. If they were sent when requesting the transaction, then they will be displayed and locked so that the user cannot edit
them.
• Validate his identity by agreeing to use Universign service by reading the
Universign Services Subscription Form document, which contains the
user information and indications about the subscriber commitment, and then
signing it.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 6 / 28

SIGNATURE-GUIDE

VERSION: 8.8

Figure 1: Contract signature interactions

2.2

Protocol

In order to allow integration from many different platforms and languages, U NI VERSIGN has chosen to provide a Web Services type API, under the form of
XML-RPC (Remote Procedure Call). XML-RPC protocol allows the consistent
transmission of parameters from any platform and has built-in support in many
languages. For language with no support of this protocol, or if you wish to reimplement an XML-RPC library, the XML-RPC language specification is available at http://www.xmlrpc.com/.
The following conventions are in use with the U NIVERSIGN signature service:
• The URL for XML-RPC requests is: https://ws.universign.eu/sign/rpc/
• All strings must be encoded in UTF-8.
• For readability reason, we shall write byte[] in this document to denote
binary data, instead of the XML-RPC base64 type.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 7 / 28

SIGNATURE-GUIDE

VERSION: 8.8

• In the API, all parameters which are not XML-RPC predefined types are
XML-RPC structs (e.g. hashtables or maps or dictionaries depending on
your programming language). All keys in XML-RPC structs are case sensitive.
• In the API, all methods for which the return value is not specified return the
integer 0.
• In case of failure while producing a signature the server returns an XMLRPC fault message with an error code and a string message describing the
cause of failure. The error code list can be found in the appendixes.

2.3

Authentication and confidentiality

All U NIVERSIGN signature services communications are over HTTPS to guarantee the confidentiality of the data and the authentication of the server.
It is based on basic access authentication, with user name and password, as
defined in the RFC 2617[2] and is supported by a wide range of HTTP implementations in most languages. The confidentiality of passwords is guaranteed by the
SSL layer.

2.4

Signature format and standard

The U NIVERSIGN signature service API supports the creation of signed PDF document according to PAdES signature profiles as described in [1].
The PAdES signature service does not produce PDF document but adds approval signatures (also called ordinary signatures or document signatures) to existing PDF documents.
Note that the performed signatures include a timestamp.

2.5

Services pre-configuration

As exposed in the API documentation 3, the U NIVERSIGN user has a great choice
of options and configuration parameters at request time. However, as to enable
or personnalize some features, the U NIVERSIGN teams are in charge of a part of
the configuration of the services, prior to their uses. The features that need such
activation or configuration are presented below.
The signature field needs to be activated and personnalized in size and content
to be used. The content can be a composition of images and texts.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 8 / 28

SIGNATURE-GUIDE

VERSION: 8.8

An URL for status push in the client signature mode. A GET HTTP request will
be performed on this optional property each time a signature step is completed (i.e. each time a signer succeeds, fails or cancels its signature).Three
parameters are set to the request:
id : the id of the transaction
signer : the number of the signer who performed the last action on the
transaction. The count of the signers is 0-based.
status : the status of the transaction. It can be 0 for ready (waiting for the
next signer), 1 for expired (created but not completed after 14 days),
2 when completed (all signers signed), 3 when canceled by a signer, 4
when failed, 5 when pending a validation by U NIVERSIGN Registration Authority.
Elements for the web interface personnalization : a logo and a company name
that will be displayed on the signature web page.
Configuring those items is made on request by the U NIVERSIGN teams. All
these properties and options are stored in properties set called profiles.

2.6

Documents retention policy and documents retrieval

In the case of server-side signatures, neither the original or the signed document
are saved by U NIVERSIGN and the signed document is synchronously returned:
this section does not apply.
For client-side signatures, the documents of a transaction are kept by U NI VERSIGN for 30 days after the transaction creation date. During this period and as
soon as the transaction is completed (i.e. all signers signed), the documents can
be retrieved using the API.
Afterward, and for an unlimited time, the documents are archived. At this
point, their retrieval is no more guaranteed to be synchronous, as a de-archival
process may be necessary. In this case, a first request for the documents will send
an error. A further request, once the de-archival process has finished, will return
the documents. A de-archival process can take up to few hours.
If a U NIVERSIGN user does not want its documents to be archived, he must
request it to the U NIVERSIGN teams, as part of the services configuration, as
exposed in section 2.5. In this case, 30 days after the transaction creation, the
documents are deleted from U NIVERSIGN.
In the particular cases of out-dated, canceled or failed transaction, the documents are immediately deleted from U NIVERSIGN.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 9 / 28

SIGNATURE-GUIDE

3

VERSION: 8.8

Signature service API
• byte[] signer.sign(byte[] document)
Signs a document, using the default signature profile and options.
• byte[] signer.signWithOptions(byte[] document, SignOptions options)
Signs a document, using a set of options.
• TransactionResponse requester.requestTransaction(TransactionRequest
request)
Requests a new transaction for the client signature service. Sends the document to be signed and other parameters and returns an URL where the end
user should be redirected to. A transaction must be completed whithin 14
days after its request.
• TransactionDocument[] requester.getDocuments(String transactionId)
Requests signed and viewed documents (after their transaction is completed)
by their transaction id. See section 2.6.
• TransactionDocument[] requester.getDocumentsByCustomId(String customId)
Requests signed and viewed documents (after their transaction is finished)
by their custom id. This method is very similar to requester.getDocuments(String
transactionId). It can be used if you do not want to store an external ID.
• TransactionInfo requester.getTransactionInfo(String transactionId)
Requests information about the status of the transaction with this id.
• TransactionInfo requester.getTransactionInfoByCustomId(String customId)
Requests information about the status of the transaction with this id. This
method is very similar to the previous one. It can be used if you do not want
to store an external ID.
• requester.relaunchTransaction(String transactionId)
Refreshes the creation date for the transaction. The invitation email is sent
again if the parameters allow it (chainingMode equals email and in the case
of the first signer, mustContactFirstSigner equals true). This method can
be used to postpone the expiration date of the transaction.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 10 / 28

SIGNATURE-GUIDE

VERSION: 8.8

• requester.cancelTransaction(String transactionId)
Cancel a transaction in progress with this id.
• string[] requester.listTransactions(TransactionFilter filter)
Requests the list of transactions matching the given filter. At most 1000
results are returned: to have more results, use multiple requests and ranges
in TransactionFilter.
• TransactionResponse requester.requestRegistration(
StandaloneRegistrationRequest request)
Requests the standalone registration of the signer. Sends the signer identity
to be certified and returns an URL where the signer should be redirected
to. The registration process is similar to the transaction one but without
documents to sign.
• requester.requestTwoStepsRegistration(
StandaloneRegistrationRequest request)
Since 8.4
Requests a two steps standalone registration of the signer. This service
should be called by an operator after a face-to-face meeting with the signer.
It sends the signer’s identity to be certified including his identity documents.
Once the identity documents are validated by Universign, an email will be
sent to the signer with an URL where he can review his identity information
and agree to the Universign Services Subscription Form. This registration
process is similar to the transaction one but without documents to sign.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 11 / 28

SIGNATURE-GUIDE

4

VERSION: 8.8

Data objects

In this section are presented the structure of the data objects used in the API.
All data structures are XML-RPC structs (i.e. dictionaries). The first column
contains the key and a letter which can be:
M if the key is mandatory and must be affected a none-null value;
O if the key is optionnal.
The second column is the type of the corresponding value. The third column
contains additional information about the parameter such as the optionality, details
about the data format. . .

4.1

SignOptions

The SignOptions data structure contains options for a document signature and
allows to specify a signature profile to use.
Key
profile [O]

Type
string

signatureField [O]

SignatureField

reason [O]
location [O]
signatureFormat [O]

string
string
string

Comments
The name of the signature profile to use. A signature profile contains a private key and a signature
field. Signature profiles are set up by the U NIVER SIGN team. The default value is "default".
A description of a visible PDF signature field. If none
is provided, no signature field will be produced on the
signed document.
The reason for the digital signature.
The signer’s location.
The signature format. The available values are:
PADES The signature follows the format defined in
ETSI TS 102 778-3 PAdES Part 3: PAdES
Enhanced - PAdES-BES.
PADES-COMP The signature follows the format
defined in ISO 32000-1 with the signing certificate attribute. This format is a compatibility mode with PAdES (same semantic than
PAdES with the ISO 32000-1 format).
ISO-32000-1 The default value. The signature follows the format defined in ETSI TS 102 7782 PAdES Part 2: CMS Profile based on ISO
32000-1.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 12 / 28

SIGNATURE-GUIDE

Key
language [O]

VERSION: 8.8

Type
string

Comments
The language for this transaction. The valid values are:
bg for Bulgarian
ca for Catalan
de for German
en for English (default value)
es for Spanish
fr for French
it for Italian
nl for Dutch
pl for Polish
pt for Portuguese
ro for Romanian

patternName [O]

4.2

string

The name of the pattern for the signature field.

TransactionRequest

The TransactionRequest data structure contains informations and options for a
Signature transaction creation.
Key
profile [O]

Type
string

customId [O]

string

signers [M]

TransactionSigner[]

documents [M]

TransactionDocument[]

U NIVERSIGN

Comments
The name of the signature profile to use. Signature profiles mainly differ by the displayed company name and logo, and the pre-configured signature field stored within. Signature profiles are
set up by the U NIVERSIGN team. The default
value is "default".
A requester-set unique id that can be used to identify this transaction. If not unique, a fault will be
thrown. Note that U NIVERSIGN generate its own
unique id for each transaction and return it to the
requester.
The signers that will have to take part to the transaction. Must contain at least one element.
The documents to be signed. Must contain at
least one element. The size limit of each document is set to 10Mo.

DIFFUSION: RESTRICTED

PAGE: 13 / 28

SIGNATURE-GUIDE

VERSION: 8.8

Key
mustContactFirstSigner [O]

Type
boolean

finalDocSent [O]

boolean

finalDocRequesterSent [O]

boolean

finalDocObserverSent [O]

boolean

description [O]
certificateType [O]

string
string

Comments
If set to True, the first signer will receive an invitation to sign the document(s) by e-mail as soon as the
transaction is requested. False by default.
Tells whether each signer must receive the signed
documents by e-mail when the transaction is completed. False by default.
Tells whether the requester must receive the signed
documents via e-mail when the transaction is completed. False by default.
Tells whether the observers must receive the signed
documents via e-mail when the transaction is completed. It takes the finalDocSent value by default.
Description or title of the signature.
This option is used to indicate which certificate type
will be used to perform the signature and therefore
which type of signature will be performed. The
available values are:
certified Allows signers to perform a certified signature.
advanced Allows signers to perform an advanced
signature which requires the same options as
a certified signature.
simple Allows signers to perform a simple signature. The default value.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 14 / 28

SIGNATURE-GUIDE

VERSION: 8.8

Key
language [O]

Type
string

Comments
The interface language for this transaction. The
valid values are:
bg for Bulgarian
ca for Catalan
de for German
en for English (default value)
es for Spanish
fr for French
it for Italian
nl for Dutch
pl for Polish
pt for Portuguese
ro for Romanian

handwrittenSignatureMode [O]

int

The mode to enable the handwritten
signature. There are three modes:
• "0": disables the hand-written signature
• "1": enables the hand-written signature
• "2": enables the hand-written signature if
only it is a touch interface
If handwritten signature is enabled, the signer
is prompted to draw a signature on the web interface and the SignatureField bean becomes mandatory for each of the TransactionSigners. This signature is added in his signature field, as an image
would be.
HandwrittenSignatureMode can not be enabled
against a transaction containing only document for
presentation.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 15 / 28

SIGNATURE-GUIDE

VERSION: 8.8

Key
chainingMode [O]

Type
string

Comments
This option indicates how the signers are chained during the signing process. The valid values are:
none No invitation email is sent in this mode. Each
signer is redirected to the successURL after
signing. It is up to the requester to contact each
of the signers.
email The default value. The signers receive the
invitation email (except for the first one,
see mustContactFirstSigner) and are redirected to the successURL.
web Enables the linked signature mode. In this
mode, all signers are physically at the same
place. After a signer completed its signature,
he will be redirected to the next signer’s signature page instead of being returned to the
successURL and the next signer will not receive an invitation mail. The last signer will be
redirected to the successURL.

4.3

finalDocCCeMails [O]

String[]

twoStepsRegistration [O]

boolean

This option allows to send a copy of the final signed
documents to a list of email addresses. This copy is
send as cc for every final signed documents email addressed to a signer. For this option to be taken into account, the option finalDocSent must be sent to True.
This option allows registration of signers via a two
steps registration process. When activated, the RegistrationRequest bean becomes mandatory for each of the
unregistered TransactionSigners, the certicateType
must be set to advanced, the phoneNumber and the
birthDate must be set.
Default value is False.

TransactionSigner

A TransactionSigner describes and contains options for a document signer.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 16 / 28

SIGNATURE-GUIDE

Key
firstname [O]

Type
string

lastname [O]

string

organization [O]
profile [O]

string
string

emailAddress [O]

string

phoneNum [O]

string

language[O]

String

VERSION: 8.8

Comments
This signer’s firstname. Note that this field is mandatory for a
self-signed certificate.
When using validationSessionId, it must be set to the same value
than the one used in the validation request.
This signer’s lastname. Note that this field is mandatory for a
self-signed certificate.
When using validationSessionId, it must be set to the same value
than the one used in the validation request.
This signer’s organization.
The name of the signer profile to use for some customizations. It
is set up by the U NIVERSIGN team.
This signer’s e-mail address. Note that all users except the first
must have an email address set. The first user must have one
if he has to be contacted by e-mail, e.g. for authentication or
if the mustContactFirstSigner parameter of TransactionRequest is set to true.
This signer’s mobile phone number that should be written in the
international format: the country code followed by the phone
number (for example, in France 33 XXXXXXXXX).
The language for the signer’s transaction. The valid values are:
bg for Bulgarian
ca for Catalan
de for German
en for English (default value)
es for Spanish
fr for French
it for Italian
nl for Dutch
pl for Polish
pt for Portuguese
ro for Romanian

role [O]

string

The role of this transaction actor
signer (default) This actor is a signer and he will be able to view
the documents and sign them.
observer This actor is an observer and he will be able only to
view the documents.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 17 / 28

SIGNATURE-GUIDE

VERSION: 8.8

Key
birthDate [O]

Type
date

universignId [O]

string

successURL [O]

string

cancelURL [O]

string

failURL [O]

string

certificateType [O]

string

Comments
This signer’s birth date. This is an option for
the certified signature, if it’s set, the user won’t
be asked to provide it’s birth date during the RA
workflow.
When using validationSessionId, it must be set to
the same value than the one used in the validation
request.
An external identifier given by the organization
that indicates this signer.
The url to where the signer will be redirected,
after the signatures are completed. If it is null it takes the value of
TransactionRequest.successURL. If it is
also null, it takes the default Universign success
URL.
The url to where the signer will be
redirected, after the signatures are canceled.
If it is null it takes the value of
TransactionRequest.cancelURL. If it is
also null, it takes the value of successURL. If it
is also null, it takes the default Universign cancel
URL.
The url to where the signer will be redirected, after the signatures are failed. If it is null it takes
the value of TransactionRequest.failURL. If
it is also null, it takes the value of cancelURL. If
it is also null, it takes the default Universign failure URL.
Indicates which certificate type will be used to
perform the signature and therefore which type
of signature will be performed by this signer. The
available values are:
certified Allows signers to perform a certified
signature.
advanced Allows signers to perform an advanced signature which requires the same
options as a certified signature.
simple Allows signers to perform a simple signature. The default value.

idDocuments [O]

U NIVERSIGN

RegistrationRequest

The ID documents to use in this signer registration. This is an option for the certified signature,
if it’s set, the user won’t be prompted to provide
its ID documents in the RA workflow.

DIFFUSION: RESTRICTED

PAGE: 18 / 28

SIGNATURE-GUIDE

Key
validationSessionId

4.4

VERSION: 8.8

Type
String

Comments
The ID of a valid ID Validation Session retrieved from a validation request (see universign-guide-8.8-ra.pdf). The documents
in this ID Validation session will be used and no need to provide idDocuments.

RegistrationRequest

The RegistrationRequest data structure contains information for the signer
registration.
Key
documents

Type
byte[][]

type

String

Comments
List of ID documents to use to register the signer. The number of these
documents is indicated in the following comment.
The type of the provided ID documents.
id_card_fr French ID card. Two ID documents should be provided.
passport_eu French Passport. Only one ID document should be provided.
titre_sejour Residence Permit. Two ID documents should be provided.
drive_license European Driving License (New Format, issued since
September 2013). Two ID documents should be provided.

4.5

TransactionDocument

The TransactionDocument data structure contains information about a transaction document.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 19 / 28

SIGNATURE-GUIDE

Key
documentType [O]

VERSION: 8.8

Type
string

Comments
This TransactionDocument type. Valid values
are:
pdf The default value.
Makes all
TransactionDocument
members
relevant, except for SEPAData
pdf-for-presentation This value marks the
document as view only.
sepa Using this value, no PDF document is provided, but U NIVERSIGN creates a SEPA
mandate from data sent in SEPAData,
which becomes the single relevant member.

content [O]

byte[]

url [O]

string

fileName
signatureFields [O]
checkBoxTexts [O]

string
DocSignatureField[]
String[]

metaData [O]

Struct

title [O]
SEPAData [O]

String
SEPAData

4.6

The raw content of the PDF document. You can
provide the document using the url field, otherwise this field is mandatory.
The URL to download the PDF document. Note
that this field is mandatory if the content is not
set.
The file name of this document.
A description of a visible PDF signature field.
Texts of the agreement checkboxes. The last one
should be the text of the checkbox related to signature fields labels agreement.
This attribute should not be used with documents of the type "pdf-for-presentation". Since
agreement for "pdf-for-presentation" is not customisable.
This structure can only contain simple types like
integer, string or date.
A title to be used for display purpose.
A structure containing data to create a SEPA
mandate PDF.

SignatureField

The SignatureField data structure describes the content of a PDF visible signature field. A default Pattern of signature is provided by Universign. This pattern
is customizable (see 2.5).

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 20 / 28

SIGNATURE-GUIDE

Key
name [O]

Type
string

page [M]

int

x [M]
y [M]

int
int

VERSION: 8.8

Comments
The name of the field. If the PDF already contains a named signature
field, you can use this parameter instead of giving the coordinates (which
will be ignored). If the name of this field does not exist in the document,
the given coordinates will be used instead.
The page on which the field must appear (starting at ’1’ for the first page).
Pages are enumerated starting at 1. The value ’-1’ points at the last page.
The field horizontal coordinate on the page.
The field vertical coordinate on the page.

A DocSignatureField structure have the same data of the SignatureField
structure plus the following:
Key
signerIndex [M]

Type
int

patternName [O]

string

label [O]

string

4.7

Comments
The index of the signer which uses this field. Signers are enumerated starting at 0.
The name of the pattern. May be used if more than one pattern
is set. The default value is "default". The magic value "invisible"
means that the field will not be visible in the PDF.
A label which defines the signature field. This label will be printed
in the signature page if set. If a signer has more than one field on
the same document, label becomes mandatory.

SEPAData

The SEPAData data structure contains information needed to create a SEPA mandate PDF.
Key
rum [M]
ics [M]
iban [M]
bic [M]
recurring [M]

Type
string
string
string
string
boolean

debtor [M]
creditor [M]

SEPAThirdParty
SEPAThirdParty

4.8

Comments
A unique mandate identifier.
A unique creditor identifier.
The debtor International Bank Account Number.
The debtor Bank Identifier Code.
Whether this SEPA mandate describe a recurring payment
(true) or a single-shot payement (false).
Information on the debtor.
Information on the creaditor

SEPAThirdParty

The SEPAThirdParty data structure is used to define information on both the
debtor and the creditor of a SEPA mandate.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 21 / 28

SIGNATURE-GUIDE

Key
name [M]
address [M]
postalCode [M]
city [M]
country [M]

4.9

Type
string
string
string
string
string

VERSION: 8.8

Comments
The full name of this debtor/creditor.
The address of this debtor/creditor.
The postal code of this debtor/creditor.
The city of this debtor/creditor.
The country of this debtor/creditor.

TransactionResponse

The TransactionResponse data structure is the response sent after a request
for a transaction. This structure is used as a return value only, and will never be
instantiated by users.
Key
url
id

4.10

Type
string
string

Comments
The URL to the web interface for the first signer.
This transaction id.

TransactionInfo

The TransactionInfo data structure describes the status of a transaction. This
structure is used as a return value only, and will never be instantiated by users.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 22 / 28

SIGNATURE-GUIDE

Key
status

Type
string

VERSION: 8.8

Comments
The status of the transaction. The existing statuses are:
ready Signers can connect and sign.
expired The transaction has been requested more than 14
days ago. It will no more be available to signers.
canceled A signer has canceled the transaction. Signers will
no more be able to connect to the service.
failed An error occurred during a signature.
won’t be able to connect to the service.

The signers

completed All signers have successfully sign, the requester
can retrieve the documents.
signerInfos

SignerInfo

currentSigner

int

creationDate
description
initiatorInfo

date
String
InitiatorInfo

eachField

Boolean

customerId

String

transactionId

String

4.11

A list of bean containing information about the signers and
their progression in the signature process.
The index of current signer if the status of transaction is ready
or who ended the transactions for other status.
The creation date or last relaunch date of this transaction.
The description of the Transaction.
A bean containing information about the requester of a transaction.
whether the transaction was requested with requesting handwritten signature for each signature field or not.
This id can be specified when creating the transaction request
and is used as additional information to identify the transaction.
This id is generated when creating the transaction request and
is the unique identifier of this transaction.

SignerInfo

The SignerInfo data structure describes the status of a signer. This structure is
used as a return value only, and will never be instantiated by users.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 23 / 28

SIGNATURE-GUIDE

Key
status

VERSION: 8.8

Type
string

Comments
The status of the signer. The existing statuses are:
waiting The signer has not yet been invited to sign. Others
signers must sign prior to this user.
ready The signer has been invited to sign, but has not tried
yet.
accessed The signer has accessed the signature service.
code-sent The signer agreed to sign and has been sent an
OTP.
signed The signer has successfully signed.
pending-id-docs The signer has successfully signed and
should send the documents to complete his registration.
pending-validation The signer has successfully signed
and is pending RA validation.
canceled The signer refused to sign, or one of the previous
signers canceled or failed its signature.
failed An error occurred during the signature. In this case,
error is set.
The status of the observer. The existing statuses are:
waiting The observer has not yet been invited to access the
document(s). Others signers must sign prior to this
user.
ready The observer has been invited to access the document(s), but has not tried yet.
accessed The observer has accessed the document(s).

error
certificateInfo

string
CertificateInfo

url
email
firstName
lastName
actionDate
refusedDocs

string
string
string
string
date
Integer[]

U NIVERSIGN

The error message in case of failure.
A bean containing information about the certificate the
signer used (or attempt to) to sign. If the signer has not
signed yet or in some cases if an error occurs during the
signature, an empty struct will be set for his certificatei.
The URL of the signature page.
The signer’s email.
The signer’s firstname.
The signer’s lastname.
the action date (signature, cancel or other).
List of refused docs indexes.

DIFFUSION: RESTRICTED

PAGE: 24 / 28

SIGNATURE-GUIDE

4.12

VERSION: 8.8

InitiatorInfo

The InitiatorInfo data structure describes the requester of a transaction. This structure is used
as a return value only, and will never be instantiated by users.
Key
email
firstName
lastName

4.13

Type
string
string
string

Comments
The requester’s email.
The requester’s firstname.
The requester’s lastname.

CertificateInfo

The CertificateInfo struct contains information about a certificate. This structure is used as a
return value only, and will never be instantiated by users.
Key
subject
issuer
serial

4.14

Type
string
string
string

Comments
The certificate subject DN
The certificate issuer DN
The certificate serial number

TransactionFilter

Warning: this object has an experimental structure. While it is considered production quality, it is subject to change in future versions.
The TransactionFilter struct is a filter on transactions.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 25 / 28

SIGNATURE-GUIDE

VERSION: 8.8

Key
requesterEmail

Type
string

profile

string

notBefore

date

notAfter

date

startRange

int

stopRange

int

signerId

String

notBeforeCompletion

date

notAfterCompletion

date

status

int

Comments
The returned list will contains only transactions whose requester is the U NIVERSIGN user identified by this e-mail
address. If the current requester is not an admin, this field
will be defaulted to his own e-mail address (i.e. a nonadmin user can only list his own transactions).
The name of the profile used to create the matching transactions.
The matching transactions will have been created after this
date.
The matching transactions will have been created before
this date.
An index, used together with stopRange, to define which
subset of the result will be returned. Default value is 0.
An index, used together with startRange, to define which
subset of the result will be returned. Its default and maximum value is startRange + 1000.
The matching transactions will contain a signer whose id
matches this value.
The matching transactions that have been completed after
this date.
The matching transactions that have been completed before this date.
The matching transactions will contain one of those statuses. The existing statuses are:
0 Ready.
1 Expired.
2 Completed.
3 Canceled.
4 Failed.
5 Pending RA Validation.

withAffiliated

4.15

Boolean

The matched transactions of the affiliated organizations.
If this filter is set to true, the own transactions won’t be
listed.

StandaloneRegistrationRequest

The StandaloneRegistrationRequest data structure contains the information about the signer
to register and allows to specify a signature profile to use.

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 26 / 28

SIGNATURE-GUIDE

VERSION: 8.8

Key
profile [O]

Type
string

signer [M]

TransactionSigner

U NIVERSIGN

Comments
The name of the signature profile to use for the customization of the registration page. Signature profiles are set up by
the U NIVERSIGN team. The default value is "default".
The signer that will be registered.

DIFFUSION: RESTRICTED

PAGE: 27 / 28

SIGNATURE-GUIDE

VERSION: 8.8

Error codes
73002 An error occurred when signing the PDF document.
73004 An error occurred when retrieving a stored private key.
73010 The login and/or password are invalid.
73011 & 73013 The requesting user doesn’t have a valid signing account or its signing account
is inactive.
73014 When retrieving the document, the transaction id is missing or wrong.
73020 Malformed request. Typically, an invalid value has been set, the TransactionRequest
misses some mandatory elements or has some incompatible elements. The message attached to the RPC fault contain more accurate information.
73025 The used transaction id or custom id is invalid.
73027 Requesting an action on a transaction which status doesn’t allow this action (e.g requesting
the documents of an unfinished transaction).
73040 Internal server error.
73070 The requested document is being retrieved asynchronously from archival, it may take few
hours. A further request will return the document.

References
[1] Draft ETSI TS 102 778, PDF Advanced Electronic Signatures (PAdES), v0.0.17. Technical
Specification, May 2009.
[2] HTTP Authentication: Basic and Digest Access Authentication
http://www.ietf.org/rfc/rfc2617.txt
[3] Document Management - Portable Document Format - Part 1: PDF 1.7
http://www.adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf

U NIVERSIGN

DIFFUSION: RESTRICTED

PAGE: 28 / 28



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 28
Page Mode                       : UseOutlines
Author                          : 
Title                           : 
Subject                         : 
Creator                         : LaTeX with hyperref package
Producer                        : pdfTeX-1.40.15
Create Date                     : 2018:04:30 18:19:50+02:00
Modify Date                     : 2018:04:30 18:19:50+02:00
Trapped                         : False
PTEX Fullbanner                 : This is pdfTeX, Version 3.14159265-2.6-1.40.15 (TeX Live 2015/dev/Debian) kpathsea version 6.2.1dev
EXIF Metadata provided by EXIF.tools

Navigation menu