–

NG TECHNOLOGIES
Building Trust with Next Generation Technologies

NGSign
Web Services Specifications

Identifier NGSIGN-WS
Product Version NGSign 2.20
Document Version 1.0
Description NGSign Web Services documentation.
Diffusion Internal / Clients (API Only)

© NG Technologies 2022
www.ng-sign.com
[email protected]
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 2/49

Change history

Version Date Editors Approving Object

NGSign 2.6 10/02/2019 Khadija Ferjani Khadija Ferjani Initial version
- 1.0 Aroua Souabni
NGSign 2.7 03/12/2019 Moez Ben MBarka Khadija Ferjani Various improvements and addition
- 1.0 of the list of error codes.
NGSign 2.8 20/01/2020 Moez Ben MBarka Khadija Ferjani Addition of the new transaction /
- 1.0 update web service.
NGSign 2.8 24/02/2020 Moez Ben MBarka Khadija Ferjani Correction of typos.
– 1.1 Aroua Souabni Full translation to English.
NGSign 2.8 08/03/2020 Khadija Ferjani Moez Ben Document the mixed mode
– 1.2 Mbarka configuration
NGSign 2.9 17/03/2020 Moez Ben MBarka Khadija Ferjani Added description of the new API
– 1.0 Aroua Souabni allowing to update signers’
configurations.
NGSign 2.9 18/03/2020 Khadija Ferjani Moez Ben Added new NGSign 2.9 API.
– 1.1 Aroua Souabni MBarka
NGSign 2.9 01/04/2020 Khadija Ferjani Moez Ben Correction of typos.
– 1.2 MBarka
NGSign 11/05/2020 Abir Ghoudi Moez Ben API NGSign 2.10 (new transaction
2.10 – 1.0 MBarka status: “REJECTED”).
NGSign 15/07/2020 Khadija Ferjani Moez Ben API NGSign 2.11 (signature XML,
2.11 Mbarka validation de signature)
NGSign 20/08/2020 Khadija Ferjani Moez Ben Plusieurs corrections et
2.12 MBarka amélioration.
NGSign 20/10/2020 Khadija Ferjani Moez Ben Nouvelles fonctionnalités :
2.13 Mbarka authorization Bearer, validation
NGSign 30/10/2020 Khadija Ferjani Moez Ben API de l’intégration native avec
2.14 Mbarka QRSecure.
NGSign 12/12/2020 Khadija Ferjani Moez Ben Documentation improvements.
2.14 MBarka
NGSign 03/03/2021 Khadija Ferjani Moez Ben Improve the explanation of the use
2.14 MBarka of authentication tokens (Using
bearer token)
Using Token Authentication in All
Examples.
NGSign 04/05/2021 Khadija Ferjani Moez Ben Add the Sample Integration
2.14 MBarka workflow appendix with the list of
services for easy integration.
NGSign 05/05/2021 Khadija Ferjani Moez Ben Added 2.16 API.
2.16 MBarka
NGSign 08/05/2021 Khadija Ferjani Moez Ben Added 2.17 API. This includes
2.17 MBarka Invoice signing API.
NGSign 19/05/2021 Khadija Ferjani Fixed typos in the WS Call
2.17 (Sending an Invoice to NGSign).
1.1
NGSign 27/09/2021 Fahmi elkamel, Khadija Ferjani - Added 2.18 API to check if a
2.18 Khadija Ferjani user has a DIGIGO or
1.1 NGCERT certificate;
- Fixed errors for QRSecure
usage.
NGSign 06/12/2021 Khadija Ferjani Khadija Ferjani - Image size (GET parameter) is
2.20 Jihen Fejjari now optional when calling
1.0 QRsecure web service.
- Added the new parameter
2
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 3/49

“message” to add a custom

message for invitation emails.

3
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 4/49

INDEX

1. INTRODUCTION 8

2. OPERATIONS 8

2.1. CREATION OF AN ELECTRONIC SIGNATURE TRANSACTION 8

2.1.1. CREATING A COMPLETE TRANSACTION 8
2.1.2. CREATING A TRANSACTION WITH INCOMPLETE CONFIGURATIONS 9
2.2. SIGNATURE PAGE 10
2.3. REDIRECTION TO THE SIGNATURE PAGE 12
2.4. LANDING PAGE POST SIGNATURE 13
2.4.1. USING A GET PARAMETER 13
2.4.2. USING THE SIGNER CONFIGURATION 13
2.5. SIGNATURE TYPES 13
2.6. ELECTRONIC INVOICE SIGNING 14

3. COMMON WEB SERVICES 15

3.1. GENERAL CONVENTIONS 16

3.2. AUTHENTICATION 16
3.3. VERIFICATION OF THE EXISTENCE OF A CERTIFICATE 17

4. PDF RELATED WEB SERVICES 17

4.1. UPLOAD OF PDF DOCUMENTS 17

4.2. CONFIGURATION AND LAUNCH 18
4.3. VISIBLE STAMPS PLACEMENT 18
4.4. RETRIEVING TRANSACTION INFORMATION 19
4.5. ADDING A QR-SECURE 19
4.6. RETRIEVING A DOCUMENT 20
4.7. PARTIAL CONFIGURATION 20
4.8. COMPLETING SIGNER CONFIGURATION 20

5. XML RELATED WEB SERVICES 20

5.1. UPLOAD OF XML DOCUMENTS 21

5.2. CONFIGURATION AND LAUNCH 21
5.3. RETRIEVING TRANSACTION INFORMATION 21
5.4. RETRIEVING A SIGNED DOCUMENT 21

6. INVOICES RELATED WEB SERVICES 22

6.1. SENDING INVOICE DATA TO NGSIGN 22

4
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 5/49

6.2. CHECKING THE STATUS OF AN INVOICE 22

6.3. DOWNLOADING SIGNED INVOICE 22

7. OBJETS JSON DE L’API 22

7.1. NGUSER 23
7.2. NGSIGNER 23
7.3. NGFILEUPLOAD 23
7.4. NGTRANSACTION 24
7.5. NGSIGNERCONFIGURATION 26
7.6. NGSIGNATURECONFIGURATION 26
7.7. NGDOCUMENT 27
7.8. NGDOCUMENTCONFIG 28
7.9. NGREDIRECTIONURL 28
7.10. VALUESWRAPPER 28
7.11. NGINVOICEUPLOAD 28
7.12. INVOICECONFIGURATION 29
7.13. TEIFINVOICE 29
7.14. PARTNERDETAILS 30
7.15. INVOICEITEM 30
7.16. NGINVOICE 31
7.17. CERTIFICATERESPONSE 31
7.18. ENUMERATIONS 32
7.18.1. USERS STATUS 32
7.18.2. TRANSACTIONS STATUS 32
7.18.3. SIGNATURE MODES 32
7.18.4. SIGNATURE TYPES 33
7.18.5. OTP MODES 33
7.18.6. MAIL RECEIVER MODES 33
7.18.7. INVOICE STATUS 33

8. ERROR CODES 34

9. EXAMPLES 35

9.1. AUTHENTICATION USING LOGIN/PASSWORD 35

9.1.1. 36
9.2. UPLOAD OF PDF DOCUMENTS 36
9.3. CONFIGURE AND LAUNCH 36
9.4. RETRIEVING TRANSACTION INFORMATION EXAMPLE 37
9.5. RETRIEVING A DOCUMENT 38
9.6. ADDING A QR-SECURE 38
9.7. CONFIGURING A TRANSACTION WITH TWO DOCUMENTS 39
9.7.1. UPLOADING TWO DOCUMENTS: 39
9.7.2. LAUNCHING THE TRANSACTION WITH TWO DOCUMENTS 40
9.8. SENDING AN INVOICE TO NGSIGN 43
9.9. CHECKING FOR THE EXISTENCE OF A CERTIFICATE 44
5
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 6/49

SAMPLE INTEGRATION WORKFLOW – SIGNING PDF DOCUMENT 46

SAMPLE INTEGRATION WORKFLOW – INVOICE SIGNING 49

6
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 7/49

FIGURES

Figure 1 : Creation of a signature transaction9

Figure 2 : Header of the Signature Page10
Figure 3: Footer of the Signature Page11
Figure 4 : Electronic Signature Panel11
Figure 5 : Redirection to the Signature Page/Landing Page12
Figure 6 : Panel in the Signature Page to select a signature type14
Figure 7: Invoice menu15
Figure 8: Invoice signing with NGSign15
Figure 9 : Génération du token API depuis l'interface Web17
Figure 10: Sample integration workflow46
Figure 11: Manual placement of the signature fields47
Figure 12: Invoice workflow49

7
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 8/49

1. INTRODUCTION
NGSign is a complete electronic signature platform. It offers a quick and easy way to sign
and have PDF documents signed electronically using various types of certificates.

This document presents NGSign API to create and configure signature transactions.

2. OPERATIONS
NGSign API allows to create signature transactions to sign and to have signed PDF
documents. The core service of NGSign is creating and configuring a transaction. A
transaction includes one (or more) document to sign, its creator ("creator"), signatories and
several configurations per signer and per document.

NGSign API allows as well to create signature transactions to sign and to have signed XML
documents. XML Signatures uses similar web services as below for PDF, except that all web
services are prefixed with “/xml”.

NGSign API supports as well native integration with:

• QRSecure: 2D-DOC stamps server (CEV – “Cachet Électronique Visible »);
• NGSign AlFatoora: invoice signing server with support of TTN (Tunisia Trade Net)
gateway.

2.1. Creation of an Electronic Signature Transaction

The simplest way to create a signature transaction with NGSign is to make a complete global
configuration (documents, signatories ...) and then launch the transaction (see Creating a
complete transaction below).

NGSign supports an advanced mode: create an incomplete transaction and complete the
configuration later (see Creating a transaction with incomplete configurations). For example,
this mode is useful when the creator of the transaction does not have the necessary
information for all the signers when creating the transaction. Missing information may be
completed later depending on the target workflow.

Prior to any WS call, a authentication token must be generated from the NGSign caller
account (see Using bearer token). This token, must be used in all WS calls (see the examples
at the end of the document).

2.1.1. Creating a complete transaction

Creating a signature transaction with NGSign requires the following steps and web services:

Step Description Web service to use

8
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 9/49

1 Upload of PDF files to be signed Upload of PDF documents

2 Configuration and launch of the transaction Configuration and launch
3 Redirection of the first signer to NGSign N/A
Signature Page (if the first signer has
FACE_TO_FACE mode). See Configuration and
launch

The first step is to upload the PDF documents to be signed. The next step is to configure the
transaction and launch the electronic signature. Depending on the signature mode of the first
signer (see Signature modes), an email invitation may be sent to the first signer or the creator
redirects the first signer to the Signature Page.

Figure 1 : Creation of a signature transaction

2.1.2. Creating a transaction with incomplete configurations

In this case, the signature transaction is created with at least two signers and the configuration
is incomplete for at least the second signer. The missing configuration can be given later. As
long as the configuration is not completed, the signer cannot access to the signature page.

Step Description Web service to use

1 Upload of PDF files to be signed Upload of PDF documents

2 Partial configuration (some information may be Partial configuration
missing for some signers). However, the
configuration of the first signer must be
compete.
3 Complete missing configuration for each signer Completing signer
partially configured. configuration
4 Redirection of a first signer to NGSign Signature N/A
Page (if the signer has FACE_TO_FACE or
BY_LINK mode)
9
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 10/49

Each time the configuration of a signer is completed, NGSign will try to continue the
transaction (e.g by sending the invitation email if the next signer has BY_MAIL mode).

2.2. Signature Page

NGSign Signature Page is the web page to which each person invited to sign is redirected. It
implements a secured signing area.
• Signer identification: the first name and last name of the signer are explicitly
displayed. The signer must verify their accuracy before signing.
• View of the entire document: before signing, the signer must read all the pages of
the PDF document to be signed.
• Collection of the signer's consent: the signer must explicitly indicate his agreement
for the content of the document before signing;
• Electronic signature: depending on the type of signature (token, time stamp with a
One Time Password, remote certificate on a Hardware Security Module), the signer is
invited to activate his electronic signature.

Some screenshots are below.

Figure 2 : Header of the Signature Page

10
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 11/49

Figure 3: Footer of the Signature Page

Figure 4 : Electronic Signature Panel

11
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 12/49

2.3. Redirection to the Signature Page

NGSign supports two redirection modes for the electronic signature page:
1 Face to Face signature: the signer is redirected to the signature page directly after the
creation of the transaction (e.g if the creator is also the first signer);
2 By link: the client application must redirect the signer to the signature page
3 Signature on invitation by email: the signer receives an email with an invitation link
for signature. The link redirects the signer to the signature page.

In the first case, the creation of the redirect URL and the redirection is the responsibility of
the calling platform.

Figure 5 : Redirection to the Signature Page/Landing Page

Building the redirect URL

The URL to the signature page is composed as follows:

https://{server}/pds/#/transaction/sign/{nextSigner}?uuid={transactionUuid}

• {server}: Base URL of NGSign plateform ;

• {transactionUuid} : transaction identifier ;
• {nextSigner }: nextSigner identifier. This identifier can be retrieved with the
transaction information (see Retrieving transaction information and NGTransaction).

Note: The Signature Page URL has been changed since version 2.9. The old URL
(https://{server}/web/transaction/sign/{nextSigner}) is still working but may be disabled in
the coming versions.

12
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 13/49

2.4. Landing page post signature

After signing, the signer is redirected to a default landing page configured at the server level.
The landing page can be configured using one of the following ways:

2.4.1. Using a GET parameter

To redirect the signer to a specific page, an "url" parameter can be added when redirecting the
signer to the signature page.

https://{server}/pds/#/transaction/sign/{signerUuid}?url=specificURL
URL

The caller can add additional information to specificURL for processing on the landing page.
Typically, the caller can put the transaction ID. When redirecting to the "specificURL" page,
the caller can make a call on NGSign with the transaction identifier to retrieve the final status
of the transaction Retrieving transaction information and the signed document Retrieving a
signed document.

2.4.2. Using the signer configuration

Since NGSign 2.9, it is possible to configure landing pages for each signer using
NGSignerConfiguration. Using this option, you can configure a successURL and a
failureURl using the API when creating the transaction.

2.5. Signature types

NGSign supports several signature types (see Signature Types). The signature type is related
to the signature level and signing certificate type.

The following signature types are supported:

• Simple Signature (a timestamp) ;
• Qualified Signature using Remote Trust (NG Technologies PKI solution) ;
• Qualified Signature using an SSCD (Secure Signature Creation Device), including
Tunisian US token issued by ANCE (Agence Nationale de Certification
Électronique);
• DigiGO (ANCE Key Management Solution).

The signature type must be configured when creating the signature transaction. It is possible
to set “LATER” at this stage. In this case, the signer will be asked to choose a signature type
in the Signature Page.

13
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 14/49

Figure 6 : Panel in the Signature Page to select a signature type

2.6. Electronic Invoice Signing

NGSign implements electronic invoice signing using the invoice format (TIEF) and protocols
specified by TTN (Tunisia Trade Net).

An Invoice signing module is available for NGSign users with the Organization option. If
this module is enabled, an “Invoice” menu is available from the dashboard:

14
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 15/49

Figure 7: Invoice menu

Invoice signing using NGSign:

Figure 8: Invoice signing with NGSign

See “0 Sample Integration workflow – Invoice signing” for more details.

3. COMMON WEB SERVICES

• NGSign API is based on REST web services;
• NGSign API has predictable URLs and uses HTTP response codes to indicate the
invocation status of web services;
• NGSign API uses HTTP verbs;
• All API responses are in JSON format.
15
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 16/49

3.1. General Conventions

All NGSign web services expect to receive POST or GET requests with JSON encoding for
parameters. The results are returned in JSON.

For each call, the server returns a response with one of the following two HTTP statuses:

• 200: the request has been executed successfully. The client must manage the
payload of the response;
• 400: problem in the request or server error. The response contains a code and a
detailed error message.

The JSON payload returned on success is always made up of:

• "object": the payload to be processed in case of success;
• "errorCode": the error code in case of an error;
• « message »: indicative message on the error.

Some calls to the server require to be authenticated beforehand; other calls can be made
without authentication:
• URLs preceded with "/ protected" require prior authentication; For these requests,
the header must include a “Cookie” with JSESSIONID returned by the
authentication call.
• The other URLs can be called without authentication.

3.2. Authentication

To access any /protected web services without a previous authentication and cookie. The user
must have a JWT previously generated from the web interface (NGSign Web App) then use
the generated token as a Bearer authorization token. See Examples.

16
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 17/49

Figure 9 : Génération du token API depuis l'interface Web

The token must be used in all WS calls:

curl --location --request POST 'https://app.ng-sign.com.tn/server/protected/[any URL] \

--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [Your token goes here]' \
--data-raw '{"values": “your object goes here”}'

3.3. Verification of the existence of a certificate

The purpose of this web service is to check if a person has a Digigo or NGCert certificate.

Service GET protected/certificate/{email}

Input The person email
Output An CertificateResponse object.
Since 2.18

4. PDF RELATED WEB SERVICES

4.1. Upload of PDF documents

To create a transaction, you must send the list of PDF files to sign in Base64 format.

Service POST /protected/transaction/pdfs

Input A list of NGFileUpload
17
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 18/49

Output An NGTransaction object with in particular:

• The status (CREATED);
• Transaction unique identifier NGSignerConfiguration.

See Upload of PDF documents example

The output will contain:

• The transactionUuid that must be used in the configuration call below
• The document identifier that must be used when configuring an NGDocumentConfig.

4.2. Configuration and launch

A signature transaction can be configured using an NGSignatureConfiguration object.

The call is made using the unique transaction identifier (transactionUuid) retrieved when
PDF files are loaded.

Service POST protected/transaction/{transactionUuid}/launch

Input A NGSignatureConfiguration object
Output An NGTransaction object updated with the given configuration. In particular:
• The transaction status becomes CONFIGURED;
• The nextSigner field:
o contains the identifier of the first signer if the first signer is
configured with a FACE_TO_FACE signature mode.
o has a null value if the first signer is configured with a
BY_MAIL signature mode.
See Signature modes

See Configure and launch example.

4.3. Visible stamps placement

NGSign supports a mixed transaction configuration. It is possible to create and configure a

transaction using the API, then to place the visible stamps manually using the web client.

To place the visual stamps manually while using the API for all other configuration (mixed
mode configuration), the caller must invoke a specific web service then access the front page
that will allow placing the visible stamps manually.

Service POST protected/transaction/{transactionUuid}/configure

Input A NGSignatureConfiguration object. At this level the signature position must not be set
Output An NGTransaction object updated with the given configuration. In particular:
• The puuid (private identifier) is filled. This private identifier must
be used next to access to configuration web page (see below).
18
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 19/49

• The transaction status becomes CONFIGURED;

• The nextSigner field:
o contains the identifier of the first signer if the first signer is
configured with a FACE_TO_FACE signature mode.
o has a null value if the first signer is configured with a
BY_MAIL signature mode.
See Signature modes

Then, access the visual stamps placement page at

/pds/#/configure/{puuid}/{uuid}/cachets/{docUuid} that will allow you to place the visible
stamps on the PDF.

The users are then invited to sign the document normally as in the standard workflow.

4.4. Retrieving transaction information

A GET call with the transaction unique identifier (transactionUuid) can be used to get the
current information and status of the given transaction.

Service GET /any/transaction/{transactionUuid}/

Input N/A
Output An NGTransaction object.

See Retrieving transaction information example.

4.5. Adding a QR-secure

A POST service that allows to:

• Generate a 2D-Doc
• Resize the 2D-Doc
• Insert the 2D-Doc into a PDF

This is a document specific web service. It can only apply on the documents with the flag
“withQrSecure” set to true when the document is first uploaded.

Service POST /protected /transaction/document

{documentUuid}/qrsecure/{template} ?size=[image size]
URL - template: the QRSecure template name
parameters - size: image size (optional)

Input values: ValuesWrapper

Output An NGFileUpload object.

19
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 20/49

See Adding a QR-Secure for an example.

4.6. Retrieving a document

To retrieve the signed file in binary form (PDF document), the transaction identifier
(transactionUuid) and the unique identifier of the file (documentUuid) must be used. The
document identifier can be retrieved from the NGTransaction object.

Service GET /{transactionUuid}/pdfs/{documentUuid}

Input N/A
Output The PDF document encoding as “application/pdf”.

See Retrieving a signed document example.

4.7. Partial configuration

Provide a partial configuration of signature transaction. Partial configuration means missing

information for one or more signer. In all cases, the first signer must have a complete
configuration.

The information (from NGSignerConfiguration) that can be omitted for some signers are:
• firstName;
• lastName;
• phoneNumber;
• email.

Service POST /transaction/{transactionUuid}/configure/partial

Input NGSignatureConfiguration
Output NGTransaction

4.8. Completing signer configuration

In the case some information have been omitted when configuration a signature transaction,
the configuration must be completed before redirecting the signer to the Signature Page.

Service PUT /transaction/{transactionUuid}/signer/{signerUuid}

Input NGUser
Output NGTransaction

5. XML RELATED WEB SERVICES

20
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 21/49

5.1. Upload of XML documents

To create a transaction, you must send the list of PDF files to sign in Base64 format.

Service POST /protected/transaction/xmls

Input A list of NGFileUpload
Output An NGTransaction object with in particular:
• The status (CREATED);
• Transaction unique identifier NGSignerConfiguration.

5.2. Configuration and launch

A signature transaction can be configured using an NGSignatureConfiguration object.

The call is made using the unique transaction identifier (transactionUuid) retrieved when
XML files are loaded.

Service POST protected/xml/transaction/{transactionUuid}/launch

Input A NGSignatureConfiguration object
Output An NGTransaction object updated with the given configuration. In particular:
• The transaction status becomes CONFIGURED;
• The nextSigner field:
o contains the identifier of the first signer if the first signer is
configured with a FACE_TO_FACE signature mode.
o has a null value if the first signer is configured with a
BY_MAIL signature mode.
See Signature modes

5.3. Retrieving transaction information

A GET call with the transaction unique identifier (transactionUuid) can be used to get the
current information and status of the given transaction.

Service GET /xml/{transactionUuid}/

Input N/A
Output A NGTransaction object

5.4. Retrieving a signed document

To retrieve the signed file in binary form (PDF document), the transaction identifier
(transactionUuid) and the unique identifier of the file (documentUuid) must be used. The
document identifier can be retrieved from the NGTransaction object.

21
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 22/49

Service GET /xml/any/text/{documentUuid}

Input N/A
Output A NGDocument object.

6. INVOICES RELATED WEB SERVICES

6.1. Sending invoice data to NGSign

Use this web service to send invoice data to NGSign. The invoice will be available from
NGSign dashboard to validate and sign.

See Sending an Invoice to NGSign.

Service POST protected/invoice

Input An NGInvoiceUpload object.
Output An NGInvoice object.

Since 2.17

6.2. Checking the status of an invoice

Use this web service to check the status of an invoice. The web service uses the unique
identifier (uuid) returned by the prepare call above.

Service POST protected/invoice/check/{uuid}

Input N/A
Output An NGInvoice object.
Since 2.17

6.3. Downloading signed invoice

Use this web service to download the invoice PDF file. The web service uses the unique
identifier (uuid) returned by the prepare call above.

Service POST protected/invoice/pdf/{uuid}

Input N/A
Output The PDF file encoding (Base64).
Since 2.17

7. OBJETS JSON DE L’API

22
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 23/49

This section lists all JSON objects used in the Rest API.

7.1. NGUser

Field Type Description

uuid String Unique identifier of the user.

email String User email.

firstName String User firstname.

lastName String User lastname.

phoneNumber String User phone number.

status String User status. See Users status.

tokensNumber Integer Remaining tokens number.

roles List<String> User roles.

7.2. NGSigner

Field Type Description

signer NGUser Signer personnel information.

status String The status of the signer in relation to the

Transaction

type String Signature type.

mode String Signature mode. See Signature modes

signingTime Date Signing date/time.

otp String Indicates whether the OTP (One Time

Password) validation is activated. See
NGSignerConfiguration.

7.3. NGFileUpload

23
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 24/49

Field Type Description Since

fileName String File name. 2.0

fileExtension String File extension. For the 2.0

moment, only « PDF » is
supported.

fileBase64 String File bytes encoded in 2.0

Base64.

withQRSecure boolean Default value: false 2.15

Indique si un QR Secure
peut être ajouté au
document

qrPositionX integer Default value: 0 2.15

The position of the 2D-

Doc starting from left in
pixels

qrPositionY integer Default value: 0 2.15

The position of the 2D-

Doc starting from bottom
in pixels

qrPage integer Default value: 0 2.15

The page index where the

the 2D-Doc will be
inserted. The first page is
the page 0.

7.4. NGTransaction

Field Type Description Since

uuid String Transaction Unique 1.0

Identifier.

puuid String Private Transaction Unique 1.0

Identifier. This identifier
allows to access the
“visible stamps”
24
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 25/49

configuration web page

without authentication.

This field is only filled in

some specific cases. See
Visible stamps placement.

creationDate Date Transaction creation date. 1.0

status String Transaction status. See 1.0

Transactions status.

signingTime Date Transaction singing date. 1.0

creator NGUser Transaction creator. 1.0

nextSigner String Unique identifier for the 1.0

next signer. Allows the
signer to access to the
signature page.

signers List<NGSigner > Signers list. 1.0

observers List<NGUser > Observers list. An observer 2.0

is an NGSign user who will
not sign the document but
will receive a copy of all
notifications.

pdfs List<NGDocument > PDF documents list. 1.0

parallelSignatures Boolean • True: the parallel 2.16

signatures mode is
enabled. All signers
will receive the
email invitation at
the same time. No
specific order for
signing.
• False: the parallel
signatures mode is
disabled. the
invitations will be
sent following the
signers order in the
configuration.

25
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 26/49

message String Custom message that will 2.20

be displayed in the
signature invitation email.

7.5. NGSignerConfiguration

Field Type Description Since

signer NGUser The signer information. 2.8

sigType String Signature type. See 2.8

Signature Types.

mode String Signature mode. See 2.8

Signature modes.

otp String Activation / 2.8

Deactivation of
authentication by an
OPT (One Time
Password) sent by
SMS. See OTP modes.

• “OTP” to

“NONE” for.

docsConfigs List<NGDocumentConfig Documents 2.8

> configurations.

receiveDocument Boolean Configure whether 2.9

NGSign must send the
final signed document
to this signer.

redirectionUrl NGRedirectionUrl Configure landing 2.9

pages redirections in
case of success or
failure.

7.6. NGSignatureConfiguration

Field Type Description Since

26
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 27/49

sigConf List<NGSignerConfiguration > List of signers’ 1.0

configurations.

observers List<NGUser > List of observers. 1.0

lang String The transaction 1.0

processing language
encoded in two characters
according to ISO 639-2.
The supported languages
are French ("fr") and
English ("en").

parallelSignatures Boolean • True: enables the 2.16

parallel signatures
mode. All signers
will receive the
email invitation at
the same time. No
specific order for
signing.
• False: the
invitations will be
sent following the
signers order in
the configuration.

message String This attribute allows to

send a personalized
message for all
signatories.
Constraints:
• Length: max 255
• Characters:
alphanumeric with
special characters
like: ?! -_.,

7.7. NGDocument

Field Type Description

name String Document name.

extension String Document extension.

27
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 28/49

identifier String Unique identifier of the document.

size long Document size.

7.8. NGDocumentConfig

Field Type Description

page Integer The page number on which the visual

electronic signature will be added. The
default value is 1 which corresponds to
the first page of the document.

xAxis Integer The horizontal coordinate of the

signature on the page. The default value
is 0.

yAxis Integer The vertical coordinate of the signature

on the page. The default value is 0.

identifier String Document identifier.

7.9. NGRedirectionUrl

Since 2.9.

Value Description
successUrl URL where signer will be redirected after acting signature
successfully.
failureUrl URL where signer will be redirected after acting signature
failure

7.10. ValuesWrapper

Since 2.14

Value Description
values An array of values to be inserted in the QRSecure.

7.11. NGInvoiceUpload

28
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 29/49

Since 2.17

Field Type Description

invoiceFileB64 String Invoice PDF file (encoded in Base64).
clientEmail String Client email.
configuration InvoiceConfiguration Invoice configuration.
invoiceTIEF TEIFInvoice Invoice raw information.

7.12. InvoiceConfiguration

Since 2.17

Field Type Description

qrPositionX int The X position of the 2D-Doc stamp. The 2D-
Doc is generated by TTN to validate the
invoice. 0 corresponds to the left of the page.
qrPositionY int The Y position of the 2D-Doc stamp. The 2D-
Doc is generated by TTN to validate the
invoice. 0 corresponds to the bottom of the
page.
qrPositionP int The page where the 2D-Doc stamp will be
inserted. 0 corresponds to the first page.
labelPositionX int The X position of the label generated by TTN.
0 corresponds to the left of the page.
labelPositionY int The Y position of the label generated by TTN.
0 corresponds to the bottom of the page.
labelPositionP int The page where the label generated by TTN
will be inserted. 0 corresponds to the first
page.

7.13. TEIFInvoice

Since 2.17

Data dictionary requested by TTN Invoice format.

Field Type Description

supplierIdentifier String Supplier identifier. Must be in the

official format:
XXXXXXXLAMXXX (fiscal
number).

supplierDetails PartnerDetails Suppliers detailed information.

29
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 30/49

clientIdentifier String Client identifier. Must be in the

official format:
XXXXXXXLAMXXX (fiscal
number).

clientDetails PartnerDetails Client detailed information.

documentIdentifier String Invoice identifier.

invoiceDate Date Invoice issuance date.

items List<InvoiceItem> Invoice items.

invoiceTotalWithoutTax float Detailed invoice figures.

invoiceTotalWithTax float

invoiceTotalTax float

invoiceTotalinLetters String

stampTax float

tvaRate float

tvaTax float

totalDiscount float

7.14. PartnerDetails

Since 2.17

Field Type Description

partnerIdentifier String Identifier (fiscal identifier).

partnerName String Name (free text String).

address String Adress.

partnerReference String Internal reference.

7.15. InvoiceItem

30
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 31/49

Since 2.17

Field Type Description

name String Item name.

code String Item code

quantity String Item quantity.

tvaRate float TVA rate for this item.

7.16. NGInvoice

Since 2.17

Field Type Description

uuid String Invoice unique identifier.

status String Processing status. One of the

values of InvoiceStatus..

clientEmail String Client email.

clientId String Client identifier.

ttnReference float Unique reference generated by

TTN.

invoiceNumber String Invoice identifier.

invoiceDate Date Invoice issuance date.

amount float Invoice amount.

7.17. CertificateResponse

Since 2.18.

Field Type Description

hasNgCert Boolean True if an ngcert certificate with
the given email exists.

31
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 32/49

hasDigiGO Boolean True if a DigiGO certificate with

the given email exists.

7.18. Enumerations

This section lists all the enumerations used in the API.

7.18.1. Users status

Value Description
TEMPORARY_CREATED User created but not yet activated.
CREATED User created and activated.
DELETED User deleted.
SUSPENDED User suspended.

7.18.2. Transactions status

Value Description Since

CREATED Transaction created, and PDF 2.8
documents received.
CONFIGURED Transaction configured with the 2.8
list of signers and their
corresponding configurations.
SIGNATURE_LAUNCHED Transaction Launched. The first 2.8
signer has received invitation to
proceed to the signature.
SIGNED Transaction finished (all 2.8
expected signers signed).
CANCELLED Transaction cancelled. 2.8
REJECTED One of the signers has refused 2.10
signing the document. Singing
workflow has been aborted.

7.18.3. Signature modes

Value Description Since

FACE_TO_FACE The signer is present "face to face" at the time of the 2.8
creation of the signature transaction. NGSign will
redirect the user to the Signature Page immediately
after transaction creation. Most typical case is that
the transaction creator is as well the first signer.

This value can only be used for the first signer.

32
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 33/49

BY_MAIL The signer will receive an email with the signature 2.8
invitation link.
BY_LINK The redirection to the Signature Page is the total 2.9
responsibility of the API called. He must create the
URL redirection to the Signature Page and redirect
the signer.
AUTOMATIC No manual approval. The signature (timestamp) will 2.8
be automatically applied on the document.
Document viewing and approval must be done out
of the scope of NGSign.

7.18.4. Signature Types

Value Description Since

LATER No specific type. The signer will have to 2.9
choose the signature type before signing in
the Signature Page.
SIGNATURE_WITH_SSCD Qualified Electronic Signature with a 2.8
cryptographic token (USB dongle,
smartcard…). The signer is authenticated
with an electronic certificate.
CERTIFIED_TIMESTAMP Simple electronic signature with a 2.8
timestamp. The signer is authenticated with
validation factors (e.g an OTP code received
by SMS).
REMOTE_SIGN Qualified Electronic Signature with a 2.8
certificate in Remote Trust PKI.
DIGI_GO Qualified Electronic Signature with a 2.8
certificate in DigiGO (TunTrust, Tunisia).

7.18.5. OTP modes

Value Description
OTP Request the signer to enter an OTP code received by SMS
before signing.
NONE No SMS validation

7.18.6. Mail receiver modes

Value Description
RECEIVER The signer will receive the email of the corresponding event.
NONE The signer will not receive any email.

7.18.7. Invoice status

Value Description
33
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 34/49

CREATED Invoice created in NGSign. Not yet validated neither sent

to TTN.
SIGNED Invoice validated and signed.
CANCELED Invoice cancelled.
TTN_TRANSFERED Invoice transferred to TTN.
TTN_REJECTED Invoice rejected by TTN or an error occurred once sent to
TTN.
TTN_SIGNED Invoice validated and signed by TTN. The final invoice
can be downloaded.

8. ERROR CODES
Error code Valu Description
e
MISSING_PDF_ERROR 101 A PDF is missing for the
transaction.
TRANSACTION_NOT_FOUND_ERROR 102 This transaction does not
exist.
TRANSACTION_USER_NOT_FOUND_ERROR 103 The user referenced in the
transaction does not exist.
INVALID_OTP_ERROR 104 The OTP is invalid.
TRANSACTION_SIGNED_ERROR 105 This transaction is already
signed.
TRANSACTION_CANCELLED_ERROR 106 This transaction is
cancelled.
NO_MORE_TOKENS_ERROR 107 The creator is not allowed
to create more transactions
(no tokens)
TIME_STAMPING_ERROR 108 Timestamping failed (may
happen if the signature
mode is
“CERTIFIED_TIMESTA
MP”.
ONLY_CREATOR_CANCEL_TRANSACTION_ 109 An error occurred when a
ERROR user which is not the
creator try to cancel
transaction.
INVALID_PAGE_NUMBER_ERROR 110 The given page number is
invalid (out of range)
OTP_SEND_ERROR 112 An error occurred when
trying to send the OTP
code.
INVALID_CONFIGURATION 113 Invalid configuration. The
transaction remains in the
status “CREATED”
USER_IS_NOT_CREATOR_ERROR 114 The user is not the creator

34
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 35/49

of the transaction
TRNASACTION_CONFIGURED_ERROR 119 The transaction is already
configured
MAIL_FILE_NOT_FOUND_ERROR 151 The email template (email
body) is not found. Check
the server configuration.
MAIL_MESSAGING_ERROR 152 An error occurred when
sending email.
PDF_SAVING_DOC_ERROR 252 An IO error occurred when
trying to save a document
used in a transaction.
Check the server
configuration.
PDF_SERVER_CALL_ERROR 253 An error occurred when
calling internal PDF
server. Check the server
configuration.
PDF_BAD _ENCODING 255 Invalid PDF file encoding.
INVALID_XML_ENCODING 5000 The XML document
1 cannot be parsed properly.

9. EXAMPLES
Some CURL examples are presented below. They may be used from command line or
imported in tools like Postman. Values that must be changed are highlighted.

The first step before doing any WS call is to obtain a JWT token from your NGSign
account (Using bearer token). The token must be used in all WS calls:

curl --location --request POST 'https://app.ng-sign.com.tn/server/protected/[any URL] \

--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [Your token goes here]' \
--data-raw '{"values": “your object goes here”}'

9.1. Authentication using Login/Password

Note: Authentication using Login/Password will be disable starting from version 2.16.

Input

curl 'https://app.ng-sign.com.tn/server/authenticate' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'email=test%40test.com&password=Password1' \
--compressed

35
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 36/49

Output

{"email":"[email protected]","firstName":"xxxx","lastName":"xxx
xxxx","phoneNumber":"xxxxxx","uuid":"xxxxxxx","roles":["USER"],"status":"CREATED"
,"tokensNumber":92,"orgTokensNumber":0,"customEmails":false,"sigPreconfigured":true,"
certificate":null,"digigoCertificate":null,"serialNumber":null,"certificateStatus":null,"manag
er":false,"organizationName":null,"registrationDate":null,"completeName":"xxxx"}

9.1.1.

9.2. Upload of PDF documents

Input

curl 'https://app.ng-sign.com.tn/server/protected/transaction/pdfs/' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer Your token goes here' \
--data-binary '[{"fileName":"NoteInterne","fileExtension":"pdf","fileBase64":"base64 of
the document"}]' \
--compressed

Output

{"object":{"uuid":"7d45cff2-17c8-497d-8064-
14fc14af2891","puuid":null,"creationDate":"2020-09-
02T01:07:16.487+0000","status":"CREATED","digestAlgo":null,"signingTime":null,"creat
or":{"email":"[email protected]","firstName":"Moez","lastName":"Ben
MBarka","phoneNumber":"52270383","uuid":"8ce07832-b383-4115-8dd0-
851047ea4a8a","roles":["USER"],"status":"CREATED","tokensNumber":92,"orgTokensNu
mber":0,"customEmails":true,"sigPreconfigured":true,"certificate":null,"digigoCertificate":n
ull,"serialNumber":null,"certificateStatus":null,"manager":false,"organizationName":null,"re
gistrationDate":null,"completeName":"Moez Ben
MBarka"},"nextSigner":null,"signers":[],"observers":[],"pdfs":[{"size":141226,"name":"Not
eInterne","extension":"pdf","identifier":"0ebef9f6-f39a-4a9d-adce-
2a03233b3000","pdfA":false}]},"message":null,"errorCode":0}

• transactionUuid is in blue.
• document identifier is in green.

9.3. Configure and launch

Must use the transactionUuid and the document identifier returned by the previous web
service.

36
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 37/49

Input

curl 'https://app.ng-sign.com.tn/server/protected/transaction/transactionUuid/launch' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer Your token goes here' \
--data-binary '{"sigConf":[{"signer":{"firstName":"First Name","lastName":"Last
Name","email":"[email protected]","phoneNumber":"55555555"},"sigType":"CERTIFIED_TI
MESTAMP","docsConfigs":[{"page":1,"xAxis":81,"yAxis":44.28125,"documentName":"N
oteInterne","documentExtension":"pdf","identifier":"document
identifier"}],"mode":"FACE_TO_FACE","otp":"NONE"}], "message":"This is a message
included in the e-mail invitation that will be sent to all signatories."
”}' \
--compressed

9.4. Retrieving transaction information example

Input

curl 'https://app.ng-sign.com.tn/server/any/transaction/66cc5fac-c657-43fa-b59e-
89d2639e616f/' \
-H 'Authorization: Bearer Your token goes here' \ \
--compressed

Output

{"object":{"uuid":"66cc5fac-c657-43fa-b59e-
89d2639e616f","puuid":null,"creationDate":"2020-09-
02T01:20:38.000+0000","status":"CONFIGURED","digestAlgo":"SHA256","signingTime"
:null,"creator":{"email":"test@ng-
sign.com","firstName":"XXX","lastName":"XXX","phoneNumber":"66666666","uuid":"8c
e07832-b383-4115-8dd0-
851047ea4a8a","roles":["USER"],"status":"CREATED","tokensNumber":92,"orgTokensNu
mber":0,"customEmails":true,"sigPreconfigured":true,"certificate":null,"digigoCertificate":n
ull,"serialNumber":null,"certificateStatus":null,"manager":false,"organizationName":null,"re
gistrationDate":null,"completeName":"XXXX"},"nextSigner":"41429481-4dfa-49a2-972b-
f2016053ca34","signers":[{"signer":{"email":"test@ng-
sign.com","firstName":"XXX","lastName":"XXXX","phoneNumber":"66666666","uuid":"8
ce07832-b383-4115-8dd0-
851047ea4a8a","roles":["USER"],"status":"CREATED","tokensNumber":92,"orgTokensNu
mber":0,"customEmails":true,"sigPreconfigured":true,"certificate":null,"digigoCertificate":n
ull,"serialNumber":null,"certificateStatus":null,"manager":false,"organizationName":null,"re
gistrationDate":null,"completeName":"XXXXX"},"status":"CONFIGURED","type":"CERT
IFIED_TIMESTAMP","mode":"FACE_TO_FACE","otp":"NONE","receiveDocument":tru
e,"signingTime":null,"redirectionUrl":null,"pdsAccessDate":"2020-09-
02T01:43:43.000+0000"}],"observers":[],"pdfs":[{"size":141226,"name":"NoteInterne","ext
ension":"pdf","identifier":"af4a3b5b-64d3-49f7-929a-
37
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 38/49

2603d204d9c9","pdfA":false}]},"message":null,"errorCode":0}

9.5. Retrieving a document

Input

curl 'https://app.ng-sign.com.tn/server/any/transaction/a3c12507-c8f6-464d-a5bd-
f50b4f2b32f8/pdfs/8d4054d2-a05d-4bba-ad99-6318709b5fcc' \
-H 'Authorization: Bearer Your token goes here' \
--compressed

Output

The PDF document encoding as “application/pdf”.

9.6. Adding a QR-Secure

Input

curl --location --request POST 'https://app.ng-

sign.com.tn/server/protected/transaction/document/764c5af2-296f-4d5e-b653-
80a3c3c0cd5f/qrsecure/template_de_test?size=118' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your token goes here ' \
--data-raw '{
"values": [
“value 1”, “value 2”, “value 3”
]
}'

Output

{"object":{"uuid":"7d45cff2-17c8-497d-8064-
14fc14af2891","puuid":null,"creationDate":"2020-09-
02T01:07:16.487+0000","status":"CREATED","digestAlgo":null,"signingTime":null,"creat
or":{"email":"[email protected]","firstName":"Moez","lastName":"Ben
MBarka","phoneNumber":"52270383","uuid":"8ce07832-b383-4115-8dd0-
851047ea4a8a","roles":["USER"],"status":"CREATED","tokensNumber":92,"orgTokensNu
mber":0,"customEmails":true,"sigPreconfigured":true,"certificate":null,"digigoCertificate":n
ull,"serialNumber":null,"certificateStatus":null,"manager":false,"organizationName":null,"re
gistrationDate":null,"completeName":"Moez Ben
MBarka"},"nextSigner":null,"signers":[],"observers":[],"pdfs":[{"size":141226,"name":"Not
eInterne","extension":"pdf","identifier":"0ebef9f6-f39a-4a9d-adce-
2a03233b3000","pdfA":false}]},"message":null,"errorCode":0}
38
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 39/49

9.7. Configuring a transaction with two documents

NGSign allows signing more than one document in the same transaction.

9.7.1. Uploading two documents:

Input

curl 'https://app.ng-sign.com.tn/server/protected/transaction/pdfs/' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer Your token goes here' \
--data-binary '[{"fileName":"NoteInterne","fileExtension":"pdf","fileBase64":"base64 of
the document"}, [{"fileName":"NoteInterne2","fileExtension":"pdf","fileBase64":"base64
of the document"}]' \
--compressed

Output

{
"object": {
"uuid": "8d1782c8-d8e1-484d-b469-eeacf936797c",
"puuid": null,
"creationDate": "2020-09-21T15:58:09.297+0000",
"status": "CREATED",
"digestAlgo": null,
"signingTime": null,
"creator": {
"email": "[email protected]",
"firstName": "First Name",
"lastName": "Last Name",
"phoneNumber": "XXXXXXX",
"uuid": "14073406-f497-43b4-9f4c-2f1d17edc9a1",
"roles": [
"USER"
],
"status": "CREATED",
"tokensNumber": 9,
"orgTokensNumber": 0,
"customEmails": false,
"sigPreconfigured": true,
"certificate": null,
"digigoCertificate": null
"serialNumber": null,
"certificateStatus": null,
"manager": false,
39
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 40/49

"organizationName": null,
"registrationDate": null,
"completeName": "Khaidja Ferjani"
},
"nextSigner": null,
"signers": [],
"observers": [],
"pdfs": [
{
"size": 33331,
"name": "NoteInterne",
"extension": "pdf",
"identifier": "aec1925c-ed9a-42ee-9248-d510ab74d4d5",
"pdfA": false
},
{
"size": 33331,
"name": "NoteInterne2",
"extension": "pdf",
"identifier": "9e8e5a08-0fae-4d95-9ee4-537555b10878",
"pdfA": false
}
]
},
"message": null,
"errorCode": 0
}

9.7.2. Launching the transaction with two documents

Input

curl -X POST \
https://app.ng-sign.com.tn/server/protected/transaction/8d1782c8-d8e1-484d-b469-
eeacf936797c/launch \
-H 'content-type: application/json' \
-H 'Authorization: Bearer Your token goes here' \
-d '{"observers":null,
"sigConf":[{"signer":{"email":"[email protected]","firstName":"First
Name","lastName":"Last Name","phoneNumber":"XXXXXXX","uuid":"14073406-f497-
43b4-9f4c-2f1d17edc9a1","roles":["USER"],"status":"CREATED",
"tokensNumber":9,"orgTokensNumber":0,"customEmails":false,"sigPreconfigured":true,"ce
rtificate":null,"digigoCertificate":null,"serialNumber":null,"certificateStatus":null,"manager
":false,"organizationName":null,"registrationDate":null,"completeName":"Khaidja
Ferjani"},"sigType":"CERTIFIED_TIMESTAMP","mode":"FACE_TO_FACE","otp":null,"
receiveDocument":true,"docsConfigs":[{"identifier":"aec1925c-ed9a-42ee-9248-
d510ab74d4d5","page":1,"xAxis":103.5,"yAxis":233}, {"identifier":"9e8e5a08-0fae-4d95-
40
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 41/49

9ee4-537555b10878","page":1,"xAxis":103.5,"yAxis":233}],"redirectionUrl":null}]}'

Output

{
"object": {
"uuid": "8d1782c8-d8e1-484d-b469-eeacf936797c",
"puuid": null,
"creationDate": "2020-09-21T15:58:09.000+0000",
"status": "CONFIGURED",
"digestAlgo": "SHA256",
"signingTime": null,
"creator": {
"email": "[email protected]",
"firstName": "First Name",
"lastName": "Last Name",
"phoneNumber": "XXXXXXX",
"uuid": "14073406-f497-43b4-9f4c-2f1d17edc9a1",
"roles": [
"USER"
],
"status": "CREATED",
"tokensNumber": 9,
"orgTokensNumber": 0,
"customEmails": false,
"sigPreconfigured": true,
"certificate": null,
"digigoCertificate":
"serialNumber": null,
"certificateStatus": null,
"manager": false,
"organizationName": null,
"registrationDate": null,
"completeName": "LastName FirstName"
},
"nextSigner": "e7139b61-88e9-4333-9bdb-713b07c6313e",
"signers": [
{
"signer": {
"email": "[email protected]",
"firstName": "First Name",
"lastName": "Last Name",
"phoneNumber": "XXXXXXX",
"uuid": "14073406-f497-43b4-9f4c-2f1d17edc9a1",
"roles": [
"USER"
],
41
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 42/49

"status": "CREATED",
"tokensNumber": 9,
"orgTokensNumber": 0,
"customEmails": false,
"sigPreconfigured": true,
"certificate": null,
"digigoCertificate": null
"serialNumber": null,
"certificateStatus": null,
"manager": false,
"organizationName": null,
"registrationDate": null,
"completeName": "Khaidja Ferjani"
},
"status": "CONFIGURED",
"type": "CERTIFIED_TIMESTAMP",
"mode": "FACE_TO_FACE",
"otp": "NONE",
"receiveDocument": true,
"signingTime": null,
"redirectionUrl": null,
"pdsAccessDate": null,
"pdfsUuid": [
"aec1925c-ed9a-42ee-9248-d510ab74d4d5",
"9e8e5a08-0fae-4d95-9ee4-537555b10878"
]
}
],
"observers": [],
"pdfs": [
{
"size": 33331,
"name": "NoteInterne",
"extension": "pdf",
"identifier": "aec1925c-ed9a-42ee-9248-d510ab74d4d5",
"pdfA": false
},
{
"size": 33331,
"name": "NoteInterne2",
"extension": "pdf",
"identifier": "9e8e5a08-0fae-4d95-9ee4-537555b10878",
"pdfA": false
}
]
},
"message": null,

42
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 43/49

"errorCode": 0
}

9.8. Sending an Invoice to NGSign

curl --request POST \

--url https://app.ng-sign.com.tn/server /protected/invoice/ \
--header 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJmZXJqYW5pQG5nLXNpZ24uY29tIiwiaWF0IjoxNj
E1Mzk1OTE5fQ.nypc5JkzeD2b4_7bsD2Bi3STJM2tMFlabkiclD1JI56qJqBEJYVpSjtUa7Q
vCExwQ1841AaE3HS4YygimPOeLQ' \
--header 'content-type: application/json' \
--data '{
"invoiceTIEF": {
"supplieridentifier": "Supplier",
"supplierDetails": {
"partnerIdentifier": "XXXXXXXLAMXXX",
"partnerName": "Partner",
"address": {
"description": "Addresse Partner",
"street": "Rue",
"cityName": "Rue",
"cityName": "1053",
"country": "Tunisie"
},
"partnerReference": "Référence Partner"
},
"clientIdentifier": "Allo Coursier",
"clientDetails": {
"partnerIdentifier": "XXXXXXXLAMXXX",
"partnerName": "Allo Coursier",
"address": {
"description": "Siège ",
"street": "",
"cityName": "Lac 1",
"cityName": "1053",
"country": "Tunisie"
},
"partnerReference": "Partner Reference"
},
"documentIdentifier": "123455886",
"items": [
{
"name": "Carte Essence",
"code": "111",
"quantity": 3,

43
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 44/49

"tvaRate": 19,
"unitPrice": 10,
"totalPrice": 30,
"discount": 75
}
],
"invoiceTotalWithoutTax": 30,
"invoiceTotalWithTax": 39,
"invoiceTotalTax": 9,
"invoiceTotalinLetters": "Trente Neuf Dinars",
"stampTax": "0.6",
"tvaRate": 19,
"tvaTax": 9,
"totalDiscount": 0
},
"invoiceFileB64": "Base64 of the invoice PDF file",

"configuration": {
"qrPositionX": 10,
"qrPositionY": 10,
"qrPositionP": 1,
"labelPositionX": 100,
"labelPositionY": 100,
"labelPositionP": 1
},
"clientEmail": "[email protected]"
}'

Output:
{
"object": {
"status": "CREATED",
"clientEmail": "[email protected]",
"clientId": " Partner Reference ",
"ttnReference": null,
"invoiceNumber": "123455886",
"invoiceDate": "2021-05-11T08:04:04.547+00:00",
"amount": 39.0,
"uuid": "e5c54caf-b66f-476d-bedd-2d7c6342e81d"
},
"message": null,
"errorCode": 0
}

9.9. Checking for the existence of a certificate

44
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 45/49

curl --location --request GET

https://app.ng-sign.com.tn/server/protected/certificate/[email protected]'
--header 'Authorization: Bearer XXXXXXXX'

Output:
{
HasNgCert:false,
HasDigiGO:true
}

45
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 46/49

SAMPLE INTEGRATION WORKFLOW – SIGNING PDF

DOCUMENT
A typical integration workflow is to configure a signature transaction with one or more
documents / one or more signer and expects that the first signer receives immediately the
signature invitation email.

Prior to any WS call, the bearer token must be obtained from your NGSign account: Using
bearer token. This is only possible if the API option is enabled for your account.

This simple integration can be done in two steps:

Figure 10: Sample integration workflow

CURL examples of these calls are given in Upload of PDF documents and Configure and
launch.

46
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 47/49

Main configurations

The configuration call takes as input an NGSignatureConfiguration which includes the list of
the expected signers (list of NGSignerConfiguration). The main configuration of each signer:
• The signature mode: most common value is BY_MAIL (the signer will receive an
email notification with a signing link). See Signature modes.
• The signature type: the type of certificate that the signer must use. See Signature
Types.
• The landing page: once the signer finishes the signature, he will be redirected to the
given page. See NGRedirectionUrl.
• The position of the signature field in the document. See NGDocumentConfig

Good to know

• If the position of the signature field is not known when calling the API, it is possible
to use an NGSign web interface to manually place the fields. In this case, the
integration is done in three steps:

Figure 11: Manual placement of the signature fields

47
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 48/49

• At any step while doing the workflows above or afterwards, it is possible to get the
current status of a transaction using a GET call Retrieving transaction information.

48
Internal NG Technologies 2022
 NG Technologies Remote Trust Services
NGSIGN-WS
NGSign 2.20 - 1.0
NGSign WS Specifications Page 49/49

SAMPLE INTEGRATION WORKFLOW – INVOICE SIGNING

Since 2.17, NGSign Alfatoora is natively integrated in NGSign API. NGSign Alfatoora
allows to sign invoices in the TIEF format of TTN (Tunisia Trade Net).

In most cases, Alfatoora API is used to send invoices from a business application (ERP, web
site…) to NGSign for electronic signature and submission to TTN. Once, the invoice is
stamped by TTN, the calling business application downloads the final PDF and XML
invoice.

Before using this API, ensure that the “Invoice” option is enabled for your NGSign account.

The workflow is as follows:

Figure 12: Invoice workflow

Three web services calls are used:

• /protected/invoice/ to send the invoice data (Sending invoice data to NGSign). A
CURL call example is given at Sending an Invoice to NGSign.
• /protected/invoice/check to check the status of the invoice (Checking the status of an
invoice);
• /protected/invoice/pdf/ to download the invoice PDF file (Downloading signed
invoice).

49
Internal NG Technologies 2022