# Full flow example (DocumentService)
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
- 1. Prepare the signing order
- 2. Create and send signing request
- 3. Notify signer
- 4. Redirect the signer to Signicat
- 5. The signer signs the document
- 6. Signing result is created
- 7. Sender checks the status of the request
- 8. Download signed document from Signicat's archive
- 9. Flow diagram
# 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 Session Data Storage (SDS)
Jane uploads the document "Loan contract.pdf" to 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.
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
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:
# 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 signature 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.
# 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 signing information. The document is protected against tampering and cryptographically sealed.
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.
# 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.