| Table of Contents |
|---|
How to set up the Signi environment for integration?
1.Set up a single main account in Signi, which is the Owner of all workspaces
Setting up an account in Signi - see procedure at Creating an account and signing into the application for the first time. We recommend that you do not set up the main Signi account using the e-mail email of a specific person, but using an e-mail email such as info@company.com or signi@company.com, in that the mail sent to this e-mail email must be accessible to the account creator. He/she must confirm the registration e-mail email sent from Signi.
This account is then used to deal with all orders of and payments for Signi services for your company, establishing a workspace, setting its parameters, adding people to the team, generating API keys, etc.
2. Setting up a workspace for testing integration
A workspace is automatically created for the account creator when setting up an account in Signi.
Another 2-3 workspaces are generally created under the main account, for example Agenda X - PRODUCTION / Agenda X - TEST / Agenda X - DEVELOPMENT, see Creating multiple workspaces . This ensures that operating data are not mixed up with development or testing data.
Each workspace has its own API key, and each environment on the side of the integrated application uses the API key for its “own” workspace. All you have to do to shift from development to test or production is therefore to switch the API key.
3. Making API available and obtaining API keys
API access is free for Demo workspace; the solution at present is to write an "I want demo workspace" request to help@signi.com, stating the primary e-mail email and the workspace you want to use in DEMO mode. We will then afford you access via API.
You then generate API keys for your workspaces under your main account; see Generating an API key.
4. Using workspace for business without integration
In parallel to this, an organization may have multiple workspaces for using Signi via user interface directly, when the users add documents to be signed via Signi user interface.
For more see There is also a possibility of Combination of both approaches.
If you don’t feel like picking through the set-up process yourself, we will be happy to guide you through it when putting Signi into service at your company.
Did you find that something else worked for you? Have you encountered any situations when this arrangement didn’t suit you? Let us know at help@signi.com.
Transferring supporting documents for signing
How are the supporting documents to be signed transferred?
Transferring files
A file that needs to be signed is transferred from your Application to Signi; for the format see In which formats are files sent for signing?and information about the placement of signatures in a document.
When approving the document, the counterparty is then shown the document and the fields to be signed.
The document, including signatures, is sent back to the Application from Signi as a PDF file.
For more see Creating a contract/document 2.0 > From a document and “How to transfer information about the placement of signatures when transferring documents for signing?” below.
Transferring parameters for a template
A template document is prepared in Signi, with tags that correspond to the individual parameters of the document at appropriate places in the document.
Specific parameter values, such as the client's name, are transferred as supporting documents when invoking a contract creation request.
The document, including signatures, is sent back to the Application from Signi as a PDF file.
More on this in Creating a contract / document 2.0 > From a template and the paragraph below, How to transfer parameters for filling into a template if using templates when signing.
What parameters are optional when calling and what are they used for?
Only email and telephone are required to send a document for signing; other identification data, however, are also among the parameters.
Some data are required when transferring supporting documents for a template when there is no identification of the contracting parties in the template document, and this is filled in from the parameters transferred when calling.
Here too a name is mandatory; it makes sense to enter a date of birth when the customer would like that this be specified to ensure more precise identification of the contracting parties.
They are not required when transferring documents; they remain there, however, in order to maintain the same structure of the parameters.
First name, Surname, or Organization is used in SMS and e-mail email messages sent to signatoriessigners to identify the sender of the document. As in the case of the name of the sender in the header of the e-mailemail.
If data about the signatories signers were transferred in structured format, it would be possible to show them their documents signed without registration after their subsequent registration. In light of GDPR and the potential risk of error, this function will evidently not be available.
What is the simplest signing scenario?
When connecting, it is good to start with the simplest signing scenario and only then to make it more complex according to the needs of the users. How it looks:
The author/proposer of documents (is_proposer=true when calling API) is the e-mail email of the party that set up the workspace in Signi, to which documents are sent via API, i.e. typically the e-mail email of the main account in Signi for the document proposer’s company. He/she only approves the document (contract_role=true); i.e. his/her signature is not visible on the document. Approval proceeds automatically when calling via API.
All signatories signers or approvers, whether or not they are from the proposer’s company, are designated as counterparties (is_proposer=false). As a result, they need not have an account set up in Signi, only in the integrated application. They will all receive calls to sign and are able to sign a document. The only disadvantage is that they have to physically sign each and every document.
| Code Block |
|---|
{
"name": "Document name - XXXXX",
"number": "Document number - YYYYY",
"locale": "cs",
"settings": {
"signing_order": "proposers_before_counterparties",
"autosign_proposers": "V Praze"
},
"people": [
{
"is_proposer": true,
"email": "vlastnikworkspace@firma.cz",
"contract_role": "approve"
.....
},
{
"is_proposer": false,
"party_order": 2,
"email": "podepisujicizanavrhovatele@firma.cz",
"contract_role": "sign"
....
}
{
"is_proposer": false,
"party_order": 3,
"email": "podepisujicizaprotistranu@jinafirma.cz",
"contract_role": "sign"
....
}
],
.... template a parametry či soubor a přílohy apod. |
| Info |
|---|
Is it possible to avoid the situation in which the proposer’s representative has to sign each and every document? It is, but the scenario thereafter is more complex. Contact us at help@signi.com and we will discuss the options in more detail. |
How to specify the name of a document in the right way?
The document name is at the same time the name of the PDF file of the signed document which is returned to the integrated system or when downloading the document from user interface. At the same time, the PDF file of the checklist has the same name as the PDF file of the signed document, the difference being the prefix KL_ in the name.
It is therefore advisable during integration to send to API in the document name, i.e. contract_name, a unique value which is also understandable to the signatorysigner. It will then be easy to clearly trace both the document and its checklist. At the same time, it should be borne in mind that the document name is shown to the signatories signers in e-mail email and SMS notifications; i.e. it is not entirely appropriate to send, for example, the number itself. Example of correct naming: “Solemn declaration regarding warranty claim no. 6493543”.
How are the identification numbers of a document transferred?
The document number in Signi - Contract_ID, which is the result of invoking signature and is also a component part of the webhook call (in the HEAD section) - is currently used for identification.
If you want to transfer the identification of the document in the integrated system as well, this identification may be added to the address of the webhooks as workaround.
UNDER PREPARATION: Transferring document identification in the integrated system in the “your number/our number” logic to the parameters of invoking signature and webhooks.
Can the texts of sent emails and SMS be changed?
Yes, they can - this is a setting valid for the entire workspace, and they can be changed by any user with access to the space.
You can also specify the name of the sender, or the name of the addressee of the reply (REPLY TO).
Parameters in texts to be interchanged according to current status:
{CONTRACTNAME} - Adds the document name if the name of the file or template used is not filled in.
{NAME} - Adds the full name of the workspace owner
{CLIENTNAME} - Adds the full name of the client - for persons first name and surname??, for companies??
How to send multiple documents in one set?
Sequence of calling
endpoint template {.... Last_document:false… }
endpoint template attachment {.... Last_document:false… }
endpoint template attachment {.... Last_document:false… }
endpoint template attachment {.... Last_document:true… }
The document may have an unlimited number of attachments, each signature is billed as a separate signature.
If someone is to sign multiple documents in a single batch, he/she will only receive one SMS and email. He/she will then be shown the individual documents, which must be signed one by one.
Multiple documents sent in one set - for example, the customer receives one email. After clicking on it, it can access all documents in the set (see above) and can sign them (for example, an offer or a contract) or merely approve them (for example, General Terms and Conditions)
How do I receive the outcome of transferring supporting documents for signing?
You can find the immediate outcome of transferring supporting documents for signing synchronously as a “Response” to calling the relevant endpoint.
If the supporting documents are complete and valid, the response code is 200. Error codes begin with 400, and a description of the error is given in the body. You might sometimes encounter the universal error 500, although we try to minimize this.
The BODY of the response also provides you with the value of the variable Contract_ID, which is the identification of the document in Signi. This information is then used in the webhook (see below) and can be used to download a Checklist with the process of signing a document, etc.
The response also includes the URL of unique page addresses for signing a document by specific signatoriessigners/approvers, which can be used for integration.
How to sign via API remotely and in the integrated application itself?
There are two basic ways:
Remote signing via API - After signing is invoked in the integrated application, an e-mail email message with a link to the pages for signing is sent after calling Signi API. If a phone number is provided, SMS notifications can also be sent. This is similar to the standard sending of documents for signing via Signi user interface.
Signing in the integrated application itself via API - The option of Signing on one device is available in Signi user interface, when both the proposer and all counterparties are in the one place and sign in Signi at the one time on the one device. This can be done in a similar way when integrating with another application, in that signing goes ahead in the integrated application. When transferring documents or supporting documents for a template, Signi returns the URL for the signature of individual signatories signers – see How do I receive the outcome of transferring supporting documents for signing?. The integrated application then displays pages with these addresses for signing by one or more signatoriessigners. Note that when there are multiple signatoriessigners, they must all have their own space for signing. If multiple documents are signed at the same time in a set, everything still comes under one URL, only the user sees several bookmarks with individual documents in the left-hand panel.
| Info |
|---|
N.B. There is not presently any direct flag in API as to whether notifications should be sent or not; if a signature is to be made on one device, one system e-mail email is shown for the signatory signer when calling. The signatory signer is therefore actually verified with his/her signature and, if necessary, a PIN copied from the verification SMS sent during 2FA authorization. |
Documents
In which formats are files transferred for signing?
In the current version, only PDF can be sent via API; support for other formats, DOC, docx, XLS, xlsx, HTML, will be added, or reinstated.
In the HTTP request, files for signing are transferred in multichart/form-data format.
UNDER PREPARATION:
Reinstatement of support for DOC, docx, XLS, xlsx, HTML when uploading via API.
Binary files will be recoded into text in the End Point Full RestAPI variant.
How to transfer information about the placement of signatures when transferring files?
The placement of signatures is only resolved when you send your documents for signing. If using Signi templates, the position of the signatures is set by the template.
The dynamic placement of a signature
The easiest way to place signatures in documents when transferring via API is to attach a separate signature sheet with signatures at the end of the document. When calling the end point Create a contract 2.0 > From a document, "missing_positions": "append_to_the_end" is listed in the settings section as one of the parameters; see below or full example of Hello World 2.
| Code Block |
|---|
"settings": {
"signing_order": "all_at_once",
"autosign_proposers": "V Praze",
"missing_positions": "append_to_the_end"
}, |
Example of stating the parameter missing_positions
Example of dynamic placement of a signature
Static placement of signatures
When calling the endpoint Create a contract 2.0 > From a document, you can also specify in the positions field exactly where the signature is to be placed for each person. This typically covers forms, where the place of the signature is always the same.
Parameters X, Y, sign_proposer [position][x] sign_proposer [position][y] sign_proposer [position][page] and sign_negotiator [position][x] sign_negotiator [position][y] sign_negotiator [position][page] are specified
This is the distance of the upper left-hand corner of the signature from the upper left-hand corner of the document, taken in relation to the dimensions of the uploaded document in %, i.e. the value is between 0 and 100.
Recommended size of signatures for uploading to the signatory’s y’s profile: from 2034 x 792 to 646 x 298.
The placement of each signatory signer and signature is determined separately, i.e. there may be any number of signatures on the document, e.g. for multilateral agreements or multiple signatory signer statutory bodies.
By contrast, when there are multiple records in the positions field, the signature of one signatory signer is required in multiple places on a single document. This is useful, for example, in cases when multiple documents are merged in one PDF and the signatory signer should sign several of them.
| Code Block |
|---|
{
"contract_name": "document name - nonmandatory",
"number": "document number - nonmandatory",
"locale": "cs",
"settings": {
"signing_order": "all_at_once",
"missing_positions": "error"
},
"people": [
{
"is_proposer": true,
"email": "demo@signi.com",
"contract_role": "approve"
},
{
"is_proposer": false,
"email": "zakaznik@seznam.cz",
"contract_role": "sign",
"person_type": "nature",
"first_name": "John",
"last_name": "Doe#2",
"positions": [
{
"x": 50,
"y": 50,
"page": 0
}
]
}
],
"file": "uploaded_file_key"
}
|
Example of coordinates and page for a person
In the example, only the counterparty signs, which is why "contract_role": "approve" is specified for the proposer ("is_proposer": true); the approval takes place automatically during the API call
UNDER PREPARATION
the size of the signature is always adjusted to the size of the device
if the size of the signature is unconventional, it can be influenced using a suitable parameter
the use of “placeholders” in a document in the same way as, for example, in mass correspondence
Templates
When using templates, how to determine which parameters a template has?
End point https://api.signi.com/api/v1/contract/templates will return you all templates accessible for the workspace with the API key used when calling; the parameters of calling individual templates are found in JSON format in the returned list of templates - see, for example, below.
| Code Block |
|---|
{
"templates": [
{
"id": 396,
"name": "Pohybový doklad ",
"parameters": [
{
"id": "111",
"name": "Typ dokladu",
"type": "con-options",
"values": [
"Příjemka",
"Výdejka",
"Objednávka vydaná",
"Objednávka přijatá",
"Rezervace vydaná",
"Rezervace přijatá",
"Příjemka",
"Vratné obaly"
]
}
...
]
}
]
} |
How to transfer information about the placement of signatures when using templates?
There is no need to think about the placement of signatures when using document templates managed in Signi. Both the placement and the size of the signatures are determined by the template.
One signature can be placed in a template multiple times, only the field for the specified signature order is stated in the template code more than once. The signatorysigner, however, must physically sign only once.
See below for more information on arranging continuity between calling API and the template code.
How to harmonize templates and API calling so that signatures appear in the right places?
The signatures field in templates must have customized signing scenarios transferred via API. If it depends on the order of the signers, templates must also be adjusted to account for this. The two basic scenarios are as follows.
If the signing scenario involves the proposer as signer
"people": [ { "is_proposer": true, "party_order": 1, "email": "me@example.com", "contract_role": "sign" }, { "is_proposer": false, "party_order": 2, "email": "unregistered+1@example.com", "contract_role": "sign",
the corresponding signature fields in the template are:
<tr> <td> <p> <con-sign con-id="16" party-type="proposer"></con-sign> </p> </td> <td> <p> <con-sign con-id="17" party-type="counterparty" party-order="2"></con-sign> </p> </td> </tr>
If the signing scenario does not involve the proposer as signer
"people": [ { "is_proposer": true, "party_order": 1, "email": "zakladatelworkspace@firmanavrhovatele.cz", "contract_role": "approve" }, { "is_proposer": false, "party_order": 2, "email": "me@example.com", "contract_role": "sign" }, { "is_proposer": false, "party_order": 3, "email": "unregistered+1@example.com", "contract_role": "sign",
the corresponding signature fields in the template are:
<tr> <td> <p> <con-sign con-id="16" party-type="counterparty" party-order="2"></con-sign> </p> </td> <td> <p> <con-sign con-id="17" party-type="counterparty" party-order="3"></con-sign> </p> </td> </tr>
If it depends on the order of the signers, the signing_order: "one_at_a_time” switch is also a component part of calling endpoints in API, essentially the same as ticking "Depends on order" in Signi user interface. When transferring signatures via API for individual persons, the parameter “party_order” corresponds to 1,2 3… The respective placements of the signatures in the templates must correspond to the order of signing and these numbers.
| Code Block |
|---|
"settings": {
"signing_order": "one_at_a_time"
}, |
How do I display the whole template code of a template?
A template document is saved in the enhanced version of HTML.
It is accessible at the endpoint https://signi.docs.apiary.io/#reference/smlouva/smlouva/detail-smlouvy
It contains a field for replacement with real values (placeholder), such as CON_TEXT and others.
When using templates for signing, how to transfer the parameters to be filled into the template?
The Create contract / document 2.0 > From a template endpoint is used when transferring data for a template. The individual parameters of the template are transferred in the Parameters section, in that “id” corresponds to the id parameter in the template.
| Code Block |
|---|
BODY {
“number:”
... další standardní parametry dokumentů….
"parameters": [
{
"id": "12",
"value": "neurčito"
… další volitelné parametry pro daný vzor...}
"webhooks"
... další části volání
} |
Part of calling the Endpoint “Creating from a template” in Signi API
| Code Block |
|---|
<con-section con-id="12">:
Datum pohybu: <con-date con-id="1201" name="Datum pohybu" label="[Datum pohybu]" placeholder="Datum pohybu" description="Datum pohybu."></con-date>.<br>
Zakázka: <con-textarea con-id="1202" name="Zakázka" label="[Zakázka]" placeholder="Zakázka" description="Zakázka "></con-textarea><br>
Středisko:
<con-textarea con-id="1203" name="Středisko" label="[Středisko]" placeholder="Středisko" description="Středisko "></con-textarea>
</con-section> |
Part of the template code
How to hide and display sections via API in a template when using templates?
You can define sections in templates which can then be switched on and off via API. Con-part serves this purpose in the template.
| Code Block |
|---|
<con-part con-id="6" hideable=true>
<div class="part1">
<div>
<h4>ADRESA PRE ZASIELANIE KOREŠPONDENCIE</h4>
<con-section con-id="61">
<span class="col-2">Ulica: <con-textarea con-id="611" name="Ulica" label="[Doplňte]" placeholder="" description="Uveďte ulicu" style="color:#004085 !important;"></con-textarea></span>
<span class="col-1">| Súpisné číslo: <con-textarea con-id="612" name="Súpisné číslo" label="[Doplňte]" placeholder="" description="Uveďte súpisné číslo" style="color:#004085 !important;"></con-textarea></span>
<span class="col-1">| Orientačné č.: <con-textarea con-id="613" name="Orientačné číslo" label="[Doplňte]" placeholder="" description="Uveďte orientačné číslo" style="color:#004085 !important;"></con-textarea></span>
<span class="col-2">Obec: <con-textarea con-id="614" name="Obec" label="[Doplňte]" placeholder="" description="Uveďte obec" style="color:#004085 !important;"></con-textarea></span>
<span class="col-1">| PSČ: <con-textarea con-id="615" name="PSČ" label="[Doplňte]" placeholder="" description="Uveďte PSČ" style="color:#004085 !important;"></con-textarea></span>
<span class="col-1">| Číslo bytu: <con-textarea con-id="616" name="Číslo bytu" label="[Doplňte]" placeholder="" description="Uveďte číslo bytu" style="color:#004085 !important;"></con-textarea></span>
</span>
</p>
</con-section>
</div>
</div>
</con-part> |
Displaying or hiding an entire section can be done by adding the ID parameter corresponding to the section con-part, where the value is either hide or show, to the parameters transferred via API.
The code in the JSON file for creating a document from a template then contains the following in the parameters field to cover the case in which the con-part section=2 is to be hidden.
| Code Block |
|---|
....
"parameters": [
{
"id": "2",
"value": "hide"
},
... |
| Info |
|---|
N.B.! Identifiers of the con-part section are NOT shown in the list of template parameters - see When using templates, how to determine which parameters a template has? One of the ways of finding out is to download the whole template code using How do I display the whole template code of a template?, and there you will find the appropriate identifiers of the con-part section. |
The outcomes of signing
How to receive the outcomes of signing?
By webhook callback
Three URL addresses of what are known as “webhooks” for each outcome value are also involved in the transfer of supporting documents for signing:
signed;
rejected;
expired.
URL addresses typically include calls from the integrated application.
Only one of the three webhooks is called according to the outcome. If the url parameter is left blank, the web hook is not called.
In the template of calls to apiary.io, the text “your_webhook_url\” needs to be replaced with a real URL.
Now a web hook is called for each document separately, attachments included.
When calling a webhook, we transfer the same API key as was used for calling Signi, i.e. security is the same as towards Signi. The authorization type is therefore an API key, the API key of the workspace to which the document was sent for signing is stated as the value of the x-api-key, and the value is transferred in the Header.
The resulting signed document is transferred to the integrated application when calling the webhook as follows:
{
"contract_id": 3359,
"state": "completed",
"attachments": []
}
which is only valid for 10 minutes after calling the webhook; later, and an error is returned during attempts to download.
Later, you can download the document via https://api.signi.com/api/v1/contract/id/download
The file in the webhook and the download end point is transferred in the format - Application/pdf .
UNDER PREPARATION: The option of only signing all documents in one call and only one webhook will be called back. This is useful, for example, if one branching of conditions is possible in the integrated workflow system for one case which includes multiple documents.
Regularly checking status
Sometimes it is difficult to implement webhooks in the integrated system. Or when, for security reasons, it is not possible to set up access to the system from the Internet.
When sending a document for signing, you receive the document identifier Contract_id in Signi in the response; see, for example Response200HEADERS Content-Type:application/json BODY { "contract_id": "1234", "attachments": []
You obtain the status of the relevant document via the End Point Contract details, i.e. https://api.ismlouva.cz/api/v1/contract/id, where Contract_id is the id. You can then use this to call, for example, the end-points: Document status Download document Download document audit trail/checklist.
End points are called at the right time, either regularly through a timer/cron, when opening the form, by pressing the “Update status” button, etc.
In which format are the resulting documents transferred?
The file in the webhook and download end point is transferred in the format - Application/pdf
UNDER PREPARATION: Binary files will be recoded into text in the End Point Full RestAPI variant.
Advanced functions
Is it possible to have your own branding?
Own branding is useful:
as part of the sales process - when we show the customer “its design” on communication elements = e-mails emails and document approval pages;
in real deployment.
You cannot yet “click” for this - you can sales@signi.com.
UNDER PREPARATION: The target is one of the tasks that partners can prepare for, and charge to, end customers in their interface.
How does calling API differ when users of the integrated application do not have/have an account in Signi?
Signi facilitates two account modes for an organization's workers during integration:
A - The workers at the organization do not have an account in Signi, they merely use Signi to sign, as do the counterparties
B - The workers at the organization have an account in Signi and their signatures can be added automatically
The key fact is that every document in Signi must have its own unambiguous proposer.
In scenario A
Workers at the organization need not have an account in Signi, they sign in the same way as the counterparties.
The simplest way is to use the founder of the workspace to which the document is sent as the proposer of the document and to say that it will merely approve the document (automatically via API).
Both the workers at the organization and the counterparty can sign (contracts) or merely approve (for example, General Terms and Conditions).
The signing scenario transferred via API will then include the following, for example:
| Code Block |
|---|
{
"settings": {
"signing_order": one_at_a_time",
}
{
"people": [
{
"is_proposer": true,
"email": "zakladatelworkspace@firmanavrhujicidokument.cz",
"contract_role": "approve"
},
{
"is_proposer": false,
"party_order": 1,
"email": "podepisujiciobchodnik@firmanavrhujicidokument.cz",
"contract_role": "sign"
},
{
"is_proposer": false,
"party_order": 2,
"email": "podepisujícizakazník@firmaprotistrana.cz",
"contract_role": "sign"
}
], |
In scenario B
Workers at the organization must have an account in Signi and can pre-set their own signature in the account, and at the same time permit automatic signing by the proposer in the workspace.
The signing scenario transferred via API will then include, for example, the following:
| Code Block |
|---|
{
"settings": {
"signing_order": "one_at_a_time",
"autosign_proposers": "V Praze"
},
"people": [
{
"is_proposer": true,
"email": "podepisujiciobchodnik@firmanavrhujicidokument.cz",
"contract_role": "sign"
},
{
"is_proposer": false,
"party_order": 1,
"email": "podepisujícizakazník@firmaprotistrana.cz",
"contract_role": "sign"
}
], |
| Info |
|---|
Consent versus Signature
|
How is the integrated application and workspace user connected to the user in Signi?
Connection of integrated application users - Signi workspace
A workspace in Signi is used to store documents, and multiple people may be assigned to its team. Multiple people can also have access to multiple workspaces.
An API key is used for authentication when calling Signi API; i.e. it is clearly determined in which workspace the document will be saved. For more see Generating API keys.
If your application registers:
A) users only- an API key must be specified for each user.
b) the companies or branches of users too- individual users that store documents in one workspace in Signi are then assigned to them; the Signi API key may be stated for the company or branch and is used for calling all "its" users.
Connection of integrated application users - Signi users
It is simpler in account mode A, see above. It is enough to have
the e-mail email of the customer’s main account in Signi submitted for all users;
the e-mail email of the customer’s main account in Signi submitted for a company/branch.
In account mode B, all users must have their e-mail email entered to sign into Signi.
Why is API Signi not strictly RestAPI?
Signi is integrated with various advanced applications.
This corresponds to the current form of API, which can be termed “Essential” and can be easily used even when making basic calls from a simple website on PHP or CURL utility via HTTP.
UNDER PREPARATION: A parallel version of the fundamentally conceived RestAPI, where, for example, binary files are recoded to text string.