link

# Full flow example (DocumentService)

# Introduction

In this example we will use Signicat's SOAP APIs to send an electronic signing order to a single signer, who is going to sign the document with a public eID.

# Use case introduction

John is planning to buy a new apartment and is logged in to his bank to apply for a loan. He fills out and submits the loan application.

Jane, an employee at John's bank, receives John's loan application and approves the application based on information on John's financial situation. Jane prepares the loan contract for John, uploads it and sends it to John to sign.

# 1. Prepare the signing order

For John to get his loan application approved and signed, some specifications have to be in place. It has to be specified which methods are to be made available for signing, as well as which functionality is available for handling the document. As the loan application only has to be signed, the "Sign" action is the only action needed for this process.

# Upload the document to Signicat's standalone Session Data Storage (SDS)

Jane uploads the document "Loan contract.pdf" to Signicat's standalone SDS for temporary storage accessible via a REST interface. Jane also chooses to save the SDS document, as well as the document after it has been signed. The data-type should be set to "sds-document" and is given a unique SDS ID that identifies the document, "ref-sds-id". These fields will be set in the signing request.

For more information about the different document data types and uploading to Session Data Storage, see the following:

An alternative is to send the document to be signed along with the signing request, but SDS is both more efficient and can handle larger documents.

# 2. Create and send signing request

Jane creates the signature request with the createRequest method in DocumentService.

The following options is set:

  • The task should have document-action of type "Sign" that is set to be saved after signing
  • The method to be used for signing to be Norwegian BankID
  • The type of signing to be authentication-based signing
  • language is set to "en" for English (optional)
  • subject is set to "John Doe" with national id "10109001290" and mobile number "11223344" (optional)
  • notification to "Dear John, Please sign this loan contract. Best regards Jane" (optional)
  • send-result-to-archive is set to true for archiving the signed document to the archive. (optional)
  • on-task-postpone, on-task-complete and on-task-cancel values are only set to illustrate their existence (optional)

# Sample request

See the complete signing request here:

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <S:Body>
        <create-request-request xmlns="https://id.signicat.com/definitions/wsdl/Document-v3">
            <service>demo</service>
            <password>Bond007</password>
            <request>
                <language>en</language>
                <task bundle="false" id="1">
                    <subject>
                        <national-id>10109001290</national-id>
                        <first-name>John</first-name>
                        <last-name>Doe</last-name>
                        <mobile>11223344</mobile>
                    </subject>
                    <document-action optional="false" send-result-to-archive="true" type="sign">
                        <document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ref-sds-id="021020172365t7y0xwatgum3d7973311le4u44bdo31o1vo9gu3lcmwtcn" send-to-archive="false" xsi:type="sds-document">
                            <sign-text-entry/>
                            <description>Loan contract.pdf</description>
                        </document>
                    </document-action>
                    <notification notification-id="1" type="SMS">
                        <recipient>11223344</recipient>
                        <sender>Jane</sender>
                        <message>Dear John,
                            Please sign this loan contract.

                            Best regards Jane</message>
                    </notification>
                    <on-task-postpone>https://en.wiktionary.org/wiki/postpone</on-task-postpone>
                    <on-task-complete>https://en.wiktionary.org/wiki/complete</on-task-complete>
                    <on-task-cancel>https://en.wiktionary.org/wiki/cancel</on-task-cancel>
                    <configuration>default</configuration>
                    <signature>
                        <method>nbid-sign</method>
                    </signature>
                </task>
            </request>
        </create-request-request>
    </S:Body>
</S:Envelope>

# 3. Notify signer

John gets notified about the document through an SMS from Jane, specified in the signing request. It says "Dear John, Please sign this loan contract. Best regards Jane". An URL for signing the document is attached in the SMS.

# 4. Redirect the signer to Signicat

The URL leading attached to the SMS notifying John about the signing has this format:

https://env.signicat.com/std/docaction/service?request_id=request_id&task_id=task_id&artifact=artifact

More information: Learn more about how the URL is constructed and the different parts of the URL.

ø.l.,

# 5. The signer signs the document

John clicks the URL sent to him and the document presenter opens and he signs the Loan contract with his Norwegian BankID.

The screenshots show the signing process with Norwegian BankID for John. John will not have specify his national identification number; Norwegian BankID only requires one-time-code and personal password for this scenario, as subject is set with the national identification number (national-id) in the signing request.

Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide

# 6. Signing result is created

The signing results is a Long Term Validation Signed Data Object (LTV-SDO) that is packed to an electronically signed PDF (PAdES) through createPackage in PackagingService.

# Example files

# Electronically signed PDF (PAdES)

Below you can download an electronically signed PDF (PAdES). If you open the PDF in a PDF-reader such as Acrobat you can see the electronic signature information. The document is protected against tampering and cryptographically sealed.

Download PAdES

Important

Since this signed PDF is just an example file generated from our test environment, you might get a warnings regarding the validity of the certificate. In production the validity will be verified by in the reader.

# Signed Data Object (SDO)

Below you can download an example SDO file. The SDO is an XML and can be useful if you want to electronically process the signed document or extract data.

Download an LTV-SDO XML example file

# 7. Sender checks the status of the request

With the DocumentService method getStatus, it is possible for Jane to get information about the signing requests. She can see if the status still is "Created", if John has signed (status set to "completed") or if the signing request is cancelled for some reason (status set to "cancelled"). As John has signed the Loan contract document, getStatus will return "completed".

An alternative is for Jane to be notified when the status is changed.

# 8. Download signed document from Signicat's archive

Jane defined through "send-result-to-archive" that the signed document should be archived. The signed document can be downloaded from the archive for later use and validation through the getDocument in ArchiveService.

# 9. Flow diagram

Full flow diagram click-to-zoom

Last updated: 8/17/2021, 4:10:54 PM