NGSIGN API REFERENCE

Simple version

Table of Contents

Introduction

NGSIGN API operates on REST principles. It features structured and predictable URLs for resources, delivers JSON-encoded  responses and uses standard HTTP response codes, authentication and verbs.

This page explains the basic features of NGSIGN API :

  • Obtaining an API Token
  • Creation of an electronic signature transaction 
  • Retrieving transaction information 
  • Downloading transaction’s document (s)
 
NGSIGN API provides more API features  with enhanced capabilities. Please contact our sales team to access the advanced version of NGSIGN API Documentation.

Obtaining an API Token  

To access any /protected web services, 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.

API token generation from the Web interface

The Token must be used in all WS calls

Exemple : 
				
					curl --location --request POST 'https://www.ngsign.app/server/protected/[any URL] \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [Your token goes here]' \

[Your token goes here] must be changed with your API Token

Creation of an Electronic Signature Transaction

Below the steps to follow to create an electronic signature transaction via NGSIGN API :

  1. Upload the PDF(s) to be signed 

  2. Configure and launch the transaction 

  3. Redirect to the signature page (optional)

 1. Upload the PDF(s) to be signed

 
To create a transaction, the first step is to send the list of PDF files to sign in Base64 format.
 

Exemple : 

Input

				
					curl 'https://www.ngsign.app/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, 
					"creator": 
					{ 
						"email": "test@email.com", 
						"firstName": "First Name", 
						"lastName": "Last Name", 
						"phoneNumber": "55555555", 
						"uuid": "8ce07832-b383-4115-8dd0- 851047ea4a8a", 
						"roles": ["USER"], 
						"status": "CREATED", 
						"tokensNumber": 92, 
						"orgTokensNumber": 0, 
						"customEmai ls": true, 
						"sigPreconfigured": true, 
						"certificate": null, 
						"digigoCertificate": null, 
						"serialNumber": null, 
						"certificateStatus": null, 
						"manager": false, 
						"organizationName": null, 
						"registrationDate": nul l, 
						"completeName": "Full Name" 
					}, 
					"nextSigner": null, 
					"signers": [], 
					"observers": [], 
					"pdfs": [ 
					{ 
						"size": 141226, 
						"name": "NoteInterne", 
						"extension": "pdf", 
						"identifier": "0ebef9f6- f39a-4a9d-adce-2a03233b3000", 
						"pdfA": false 
					}] 
				}, 
				"message": null, 
				"errorCode": 0 
			}

{transactionUuid} is in line 16.

{document identifier} is in line 40.

 2. Configure and launch the transaction

 

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

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

Exemple : 

Input

				
					curl 'https://www.ngsign.app/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": "test@email.com", 
						"phoneNumber": "55555555" 
					}, 
					"sigType": "CERTIFIED_T IMESTAMP", 
					"docsConfigs": [ 
					{ 
						"page": 1, 
						"xAxis": 81, 
						"yAxis": 44.28125, 
						"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

Output

				
					{
    "object": {
        "uuid": "f725a10a-6a51-4722-9051-3f264c27b701",
        "puuid": null,
        "creationDate": "2024-03-25T13:54:45.000+00:00",
        "status": "CONFIGURED",
        "digestAlgo": "SHA256",
        "signingTime": null,
        "creator": {
            "email": "test@test.com",
            "firstName": "First Name",
            "lastName": "Last Name",
            "phoneNumber": "55555555",
            "uuid": "bec49b4c-0e0c-4e78-be28-ffa04defc7db",
            "roles": null,
            "status": "CREATED",
            "tokensNumber": 2,
            "reminderTime": null,
            "orgTokensNumber": 0,
            "sigPreconfigured": false,
            "certificate": null,
            "digigoCertificate": null,
            "serialNumber": null,
            "certificateStatus": null,
            "manager": null,
            "invoice": false,
            "organizationName": "organizationName",
            "registrationDate": null,
            "invitationDate": null,
            "lastLoginDate": null,
            "jwt": null,
            "apiUser": false,
            "usingApi": false,
            "ngcertClient": false,
            "ngcertManager": false,
            "ngcertGuest": null,
            "ngcertUser": null,
            "handwrittenSig": null,
            "preferredLanguage": null,
            "hasCertificate": false,
            "hasCsr": false,
            "tokenExpireDate": null,
            "tokenExpirationNotif": false,
            "completeName": " First Name Last Name"
        },
        "nextSigner": null,
        "parallelSignatures": false,
        "byApi": true,
        "lockDate": null,
        "lockingSigner": null,
        "auditDate": null,
        "transactionName": "null",
        "signers": [
            {
                "uuid": "3aa9d331-6d6c-4421-beac-74e8630c4ee1",
                "signer": {
                    "email": "test@test.com",
                    "firstName": "First Name",
                    "lastName": "Last Name",
                    "phoneNumber": "55555555",
                    "uuid": "bec49b4c-0e0c-4e78-be28-ffa04defc7db",
                    "roles": null,
                    "status": "CREATED",
                    "tokensNumber": 0,
                    "reminderTime": null,
                    "orgTokensNumber": 0,
                    "sigPreconfigured": false,
                    "certificate": null,
                    "digigoCertificate": null,
                    "serialNumber": null,
                    "certificateStatus": null,
                    "manager": null,
                    "invoice": false,
                    "organizationName": "organizationName",
                    "registrationDate": null,
                    "invitationDate": null,
                    "lastLoginDate": null,
                    "jwt": null,
                    "apiUser": false,
                    "usingApi": false,
                    "ngcertClient": false,
                    "ngcertManager": false,
                    "ngcertGuest": null,
                    "ngcertUser": null,
                    "handwrittenSig": null,
                    "preferredLanguage": null,
                    "hasCertificate": false,
                    "hasCsr": false,
                    "tokenExpireDate": null,
                    "tokenExpirationNotif": false,
                    "completeName": "First Name Last Name"
                },
                "status": "CONFIGURED",
                "type": "CERTIFIED_TIMESTAMP",
                "mode": "BY_MAIL",
                "otp": "OTP",
                "receiveDocument": true,
                "signingTime": null,
                "redirectionUrl": null,
                "pdsAccessDate": null,
                "withHandwrittenSignature": true,
                "pdfsUuid": [
                    "0fa2e83d-1e77-417c-9449-c9d370cba845"
                ],
                "refusalReason": null
            }
        ],
        "observers": [],
        "pdfs": [
            {
                "size": 33331,
                "name": "NoteInterne",
                "extension": "pdf",
                "identifier": "0fa2e83d-1e77-417c-9449-c9d370cba845",
                "pdfA": false,
                "numberPages": 0
            }
        ]
    },
    "message": null,
    "errorCode": 0
}

 Transaction  configuration

ValueRequiredTypeDescription
sigConf[signer]  

firstName

yesStringSigner’s first name

lastName

yesStringSigner’s last name

email

yesStringSigner’s email

phoneNumber

yes Optional if the signature type is DIGI_GOStringSigner’s phone number
sigTypeyesStringPossible signature types  are :

• Later

• SIGNATURE_WITH_SSCD

• CERTIFIED_TIMESTAMP

• DIGI_GO

• CERTIFIED_TIMESTAMP _WACOM

docsConfigs

pageyesIntegerThe 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

yesIntegerThe horizontal coordinate of the signature on the page. The default value is 0.

yAxis

yesIntegerThe vertical coordinate of the signature on the page. The default value is 0.

identifier

yesStringDocument identifier.
ModeyesStringPossible signature modes are :

• FACE_TO_FACE

• BY_MAIL

• BY_LINK

• AUTOMATIC

please read the signature modes section to know more.
otpyes Optional if the signature type is DIGI_GO or SIGNATURE_WITH_SSCDStringActivation / Deactivation of authentication by an OTP (One Time Password).OTP modes are :

• OTP

• NONE

MessageoptionalStringCustom message that will be displayed in the signature invitation email.

 Signature types

ValueDescription
LATERNo specific type. The signer will have to choose the signature type before signing in the Signature Page.
SIGNATURE_WITH_SSCDQualified Electronic Signature with a cryptographic token (USB dongle, smartcard…). The signer is authenticated with an electronic certificate.
CERTIFIED_TIMESTAMPSimple electronic signature with a timestamp. The signer is authenticated with validation factors (e.g an OTP code received by SMS).
DIGI_GOQualified Electronic Signature with a certificate in DigiGO (TunTrust, Tunisia).
CERTIFIED_TIMESTAMP _WACOMCERTIFIED_TIMESTAMP plus a signature with a WACOM pen tablet.

 Signature modes

ValueDescription
FACE_TO_FACEThe signer is present « face to face » at the time of the 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.
BY_MAILThe signer will receive an email with the signature invitation link.
BY_LINKThe redirection to the Signature Page is the total responsibility of the API called. He must create the URL redirection to the Signature Page and redirect the signer.
AUTOMATICNo manual approval. The signature (timestamp) will be automatically applied on the document. Document viewing and approval must be done out of the scope of NGSign.

 3. Redirect to the signature page (optional)

Redirecting to the signature page is optional. If the first signer’s mode is BY_MAIL, NGSign will send an email with the link to the signature page.
If the first signer’s mode is FACE_TO_FACE or BY_LINK, the calling application can create the link to the signature page and redirect the signer.
 

Below how to build the signature page url :

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

  • {server}: Base URL of NGSign plateform ;
  • {transactionUuid}: transaction identifier ;
  • {nextSigner}: nextSigner identifier returned in the call Configure and launch below. This identifier can be retrieved at any time with the transaction information Retrieving transaction information.

Retrieving transaction information

To retrieve 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.

Exemple : 

Input

				
					curl 'https://www.ngsign.app/server/any/transaction/66cc5fac-c657-43fa-b59e89d2639e616f/' \ 

-H 'Authorization: Bearer Your token goes here' \ \ 

--compressed

Output

				
					{
	"object":
	{
		"uuid": "66cc5fac-c657-43fa-b59e89d2639e616f",
		"puuid": null,
		"creationDate": "2020-09- 02T01:20:38.000+0000",
		"status": "CONFIGURED",
		"digestAlgo": "SHA256",
		"signingTime ": null,
		"creator":
		{
			"email": "test@ngsign.com",
			"firstName": "XXX",
			"lastName": "XXX",
			"phoneNumber": "66666666",
			"uuid": "8 ce07832-b383-4115-8dd0-851047ea4a8a",
			"roles": ["USER"],
			"status": "CREATED",
			"tokensNumber": 92,
			"orgTokensNumber": 0,
			"customEmai ls": true,
			"sigPreconfigured": true,
			"certificate": null,
			"digigoCertificate": null,
			"serialNumber": n ull,
			"certificateStatus": null,
			"manager": false,
			"organizationName": null,
			"registrationDate": nul l,
			"completeName": "XXXX"
		},
		"nextSigner": "41429481-4dfa-49a2-972bf2016053ca34",
		"signers": [
		{
			"signer":
			{
				"email": "test@ngsign.com",
				"firstName": "XXX",
				"lastName": "XXXX",
				"phoneNumber": "66666666",
				"uuid": " 8ce07832-b383-4115-8dd0-851047ea4a8a",
				"roles": ["USER"],
				"status": "CREATED",
				"tokensNumber": 92,
				"orgTokensNumber": 0,
				"customEmai ls": true,
				"sigPreconfigured": true,
				"certificate": null,
				"digigoCertificate": null,
				"serialNumber": n ull,
				"certificateStatus": null,
				"manager": false,
				"organizationName": null,
				"registrationDate": nul l,
				"completeName": "XXXXX"
			},
			"status": "CONFIGURED",
			"type": "CERTIFIED_TIMEST AMP",
			"mode": "FACE_TO_FACE",
			"otp": "NONE",
			"receiveDocument": true,
			"signingTime ": null,
			"redirectionUrl": null,
			"pdsAccessDate": "2020-09- 02T01:43:43.000+0000"
		}],
		"observers": [],
		"pdfs": [
		{
			"size": 141226,
			"name": "NoteInterne",
			"extension": "pdf",
			"identifier": "af4a3b5b-64d3- 49f7-929a-2603d204d9c9",
			"pdfA": false
		}]
	},
	"message": null,
	"errorCode": 0
}

Downloading transaction’s document(s)

To download 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.

Exemple : 

Input

				
					curl 'https://www.ngsign.app/server/any/transaction/a3c12507-c8f6-464d-a5bdf50b4f2b32f8/pdfs/8d4054d2-a05d-4bba-ad99-6318709b5fcc' \ 

-H 'Authorization: Bearer Your token goes here' \ 

--compressed

Output

				
					The PDF document encoding as “application/pdf”.

Request Access and discover NGSIGN API

We provide a 40 days free access to our Sandbox environnement for integration test
Request

API Access

Activate NGSIGN API access to your sandbox account.

Click here if you don’t have a Sandbox account

Laissez-nous un message

Nous vous contacterons dans les meilleurs délai pour répondre à votre message.