Description #
This section provides a practical example of an advanced approving process using the Signatus 2 API. It demonstrates how documents can go through one or more approval steps, including advanced configuration of approvers and process rules before the workflow is completed.
This use case describes the process of creating an envelope with documents for signature, the subsequent signing of documents by a client with OTP authentication, approval of documents by an approver, and the final delivery of signed documents to the client. Information about the envelope status is also sent back to the portal.
Our API-driven process involves two core interactions:
- POST /api/envelope: Programmatically create a new signature envelope, providing document binaries and relevant metadata.
- POST /envelope-info : Endpoint in portal backend, where Signatus sends information about the completed envelope
Request example #
Create envelope dataText :
{
"rules": {
"emailTo.client": "client@company.com",
"emailTo.approver": "approver@portal.com",
"emailFrom": "approver@portal.com",
"nameFrom": "Jack Employer",
"emailFinal": "client@company.com",
"openOtpPhone.client": "+421907863752",
"mouseSignature": false,
"guiSignerName.client": "John Client",
"guiSignerName.approver": "Jack Employer",
"sendInfo": "https://portalbackend.com/envelope-info"
},
"processes": [
{
"signer": "client",
"sigtype": "bio",
"documents": [
{
"reference": "Document1",
"method": "write",
"data": {
"allowedFields": {
"SIGNATURE": [
"SC_signature"
]
}
}
},
{
"reference": "Document2",
"method": "write"
},
{
"reference": "Document3",
"method": "optional"
}
]
},
{
"signer": "approver",
"sigtype": "data",
"documents": [
{
"reference": "Document1",
"method": "write",
"data": {
"allowedFields": {
"SIGNATURE": [
"SO_signature"
]
}
}
},
{
"reference": "Document2",
"method": "read"
}
]
}
]
}HTTP- Click to view HTTP code snippet
POST /app/api/envelope HTTP/1.1
Host: signatus.ana.sk
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJTGNWSnp4SFkyd1RDcGlLZU5Oa2VmbWZHa1ljUnBtQ1lMMUhsNG13Zm5VIn0.eyJleHAiOjE3NTU2ODE1NjksImlhdCI6MTc1NTY4MTI2OSwianRpIjoiMzg1OThkMjgtZmU4YS00NzlhLWI1ODYtYjA4OTYwYjNhZjRmIiwiaXNzIjoiaHR0cHM6Ly9vYXV0aC5hbmEuc2svcmVhbG1zL1NpZ25hdHVzIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImYzYmUxYTY2LTU1M2YtNGFlOC04OTUyLTY3OGQ4NTU2ZDAxYiIsInR5cCI6IkJlYXJlciIsImF6cCI6InNpZ25hdHVzIiwic2lkIjoiMjJhZWY2ZTAtMmI2NC00MThiLWFhNmQtMWM3YzllMTI1MzU0IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyIvKiJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiUk9MRV9QUk9YWSIsImRlZmF1bHQtcm9sZXMtc2lnbmF0dXMiLCJST0xFX1BPUlRBTCIsIlJPTEVfVVNFUiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicGhvbmUgZ3JvdXBzIHRlbmFudGlkIHByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInRlbmFudGlkIjoiZGVtbyIsIm5hbWUiOiJQYXZvbCBQdW5hIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiZGVtby5hcGkiLCJnaXZlbl9uYW1lIjoiUGF2b2wiLCJmYW1pbHlfbmFtZSI6IlB1bmEiLCJlbWFpbCI6InBhdm9sLnB1bmFAYW5hc29mdC5jb20ifQ.y0FWYDKwcAJ6s8gvRu8NcJj5pX9QRxWNz9VcX7g_aAxUcoyG2B5XEFnTcmZJ6Ia3CKLNn_vljVOqCJY6ucHbamQHBRwTZD8nA1GPZhPcfG5kCqAlbDizDTkNfqitSeTCruN5RFd9BGP5R50ETfuG7SBpgvSijsIj1jxb5DwDUPSQ1voPi1YaXyJeQBPet8WI8F1L4E9bHGMsjetPV9PJ844tHFBAsyEHlyqI9T4wLxtKOD75l8o7udAl2vNBU-8BNmAZiqBOa8CokRl4ts1RFthtog6MHoL0OWAqIysZTWloiUGVUmTuMLgXNEcXoV4jQfWmj3J0hy_iJ1JB08NBLw
Content-Length: 1772
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="dataText"
{
"rules": {
"emailTo.client": "client@company.com",
"emailTo.approver": "approver@portal.com",
"emailFrom": "approver@portal.com",
"nameFrom": "Jack Employer",
"emailFinal": "client@company.com",
"openOtpPhone.client": "+421907863752",
"mouseSignature": false,
"guiSignerName.client": "John Client",
"guiSignerName.approver": "Jack Employer",
"sendInfo": "https://portalbackend.com/envelope-info"
},
"processes": [
{
"signer": "client",
"sigtype": "bio",
"documents": [
{
"reference": "Document1",
"method": "write",
"data": {
"allowedFields": {
"SIGNATURE": [
"SC_signature"
]
}
}
},
{
"reference": "Document2",
"method": "write"
},
{
"reference": "Document3",
"method": "optional"
}
]
},
{
"signer": "approver",
"sigtype": "data",
"documents": [
{
"reference": "Document1",
"method": "write",
"data": {
"allowedFields": {
"SIGNATURE": [
"SO_signature"
]
}
}
},
{
"reference": "Document2",
"method": "read"
}
]
}
]
}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="Document1"; filename="Signatus2-API/Test.pdf"
Content-Type: application/pdf
(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="Document2"; filename="Signatus2-API/Test2.pdf"
Content-Type: application/pdf
(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="Document3"; filename="Signatus2-API/Test3.pdf"
Content-Type: application/pdf
(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Create envelope response :
{
"id": "2a79588d-f722-4293-94c1-61e6594c0ff9",
"userId": "demo.api",
"state": "ready",
"envelopetypeid": 4,
"expirationtime": 1755767728640,
"extension": {},
"processes": [
{
"id": "92d4cfd2-2170-449a-8989-2d049ad0882e",
"userId": "demo.api",
"envelopeid": "2a79588d-f722-4293-94c1-61e6594c0ff9",
"signer": "client",
"state": "ready",
"extension": {},
"sigtype": "bio",
"envelopetypeid": 4,
"tenant": "demo",
"rules": {}
},
{
"id": "47aa3bf0-7381-4a44-b93f-a0cf22880fba",
"userId": "demo.api",
"envelopeid": "2a79588d-f722-4293-94c1-61e6594c0ff9",
"signer": "approver",
"state": "ready",
"extension": {},
"sigtype": "data",
"envelopetypeid": 4,
"tenant": "demo",
"rules": {}
}
],
"type": "inbox",
"product": [],
"contact": {},
"tenant": "demo",
"rules": {
"guiSignerName.client": "John Client",
"sendInfo": "https://portalbackend.com/envelope-info",
"mouseSignature": false,
"guiSignerName.approver": "Jack Employer",
"emailTo.client": "client@company.com",
"emailTo.approver": "approver@portal.com",
"emailFrom": "approver@portal.com",
"nameFrom": "Jack Employer",
"openOtpPhone.client": "+421907863752",
"emailFinal": "client@company.com"
}
}Sequence diagram #
This sequence diagram illustrates the interaction between a Portal (initiating system), Signatus2, SMTP, SMS Gateway and a Signer and Approver (the end-users) during the process of creating and signing
Where :
- envelopeId = response.id
- processId-1 = response.processes[0].id
- processId-2 = response.processes[1].id
Envelope info service specifications: #
| URL | /envelope-info URL to endpoint will be added in request : rules.sendInfo |
| Method | POST |
| Authentication | NONE |
| Content Type | application/json |
Request body example :
{
"id": "2a79588d-f722-4293-94c1-61e6594c0ff9",
"userId": "demo.api",
"state": "final",
"envelopetypeid": 4,
"expirationtime": 1755767728640,
"extension": {},
"processes": [
{
"id": "92d4cfd2-2170-449a-8989-2d049ad0882e",
"userId": "demo.api",
"envelopeid": "2a79588d-f722-4293-94c1-61e6594c0ff9",
"signer": "client",
"state": "final",
"extension": {},
"sigtype": "bio",
"envelopetypeid": 4,
"tenant": "demo",
"rules": {}
},
{
"id": "47aa3bf0-7381-4a44-b93f-a0cf22880fba",
"userId": "demo.api",
"envelopeid": "2a79588d-f722-4293-94c1-61e6594c0ff9",
"signer": "approver",
"state": "final",
"extension": {},
"sigtype": "data",
"envelopetypeid": 4,
"tenant": "demo",
"rules": {}
}
],
"type": "inbox",
"product": [],
"contact": {},
"tenant": "demo",
"rules": {
"guiSignerName.client": "John Client",
"sendInfo": "https://portalbackend.com/envelope-info",
"mouseSignature": false,
"guiSignerName.approver": "Jack Employer",
"emailTo.client": "client@company.com",
"emailTo.approver": "approver@portal.com",
"emailFrom": "approver@portal.com",
"nameFrom": "Jack Employer",
"openOtpPhone.client": "+421907863752",
"emailFinal": "client@company.com"
}
}