Page Comparison

Jak se předávají podklady k podepisování?

Předání souborů

• Do Signi se z vaší Aplikace předá soubor k podpisu v PDF, DOCX apod. a informace o umístění podpisů v dokumentu.

• Protistraně je pak při schvalování dokumentu zobrazen dokument včetně polí k podpisu.

• Dokument včetně podpisů je ze Signi zaslán zpět do aplikace jako soubor PDF.

Předání parametrů pro vzor

• V Signi je připraven vzor dokumentu se značkami odpovídajícími jednotlivým pametrům dokumentu na vhodná místa ve dokumentu.

• Konkrétní hodnoty parametrů, například jméno klienta, se předají jako podklady při vyvolání požadavku na vytvoření smlouvy.

• Dokument včetně podpisů je ze Signi zaslán zpět do aplikace v PDF .

• Více k tématu “Jak při použití vzorů při podepisování předat parametry k vyplnění do vzoru?” níže.

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 of a specific person, but using an e-mail such as info@company.com or signi@company.com, in that the mail sent to this e-mail must be accessible to the account creator. He/she must confirm the registration e-mail 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 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 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.

1. 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.

2. 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.

3. 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 messages sent to signatories to identify the sender of the document. As in the case of the name of the sender in the header of the e-mail.

• If data about the signatories 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 of the party that set up the workspace in Signi, to which documents are sent via API, i.e. typically the e-mail 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 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.

 {
    "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.

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 signatory. 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 in e-mail 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)

Jak při předávání dokumentů k popisu předat informaci o umístění podpisů?

Dynamické umístění podpisu

...

• velikost podpisu se vždy přizpůsobuje velikosti zařízení

• pokud je velikost podpisu nadstandardní, půjde ovlivnit vhodným parametrem

...

Jak při použití vzorů při podepisování předat parametry k vyplnění do vzoru? 

Při předávání údaj pro vzor jejsou v sekci parameters předány jednotlivé parametru vozru s tím, že “id” odpovídá id parametru ve vzoru.

...

    <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>

Část kódu vzoru

Jaké parametry jsou při volání nepovinné a k čemu se používají? 

• Pro zaslání dokumentu k podpisu je nutný jen e-mail a telefon, nicméně mezi parametry jsou i další identifikační údaje.

...

• Ve zprávách podepisujícím přes SMS a e-mail se použije Jméno, Příjmení či Organizace coby identifikace odesílatele dokumentu. Stejně jako ve jménu odesílajícího v hlavičce e-mailu.

• Pokud se předají údaje o podepisujících ve strukturované podobě, bylo by možné po jejich následné registraci jim zobrazit i jejich dokumenty podepsané  bez registrace. Vzhledem ke GDPR a potenciálnímu riziku omylu tato funkce zřejmě nebude dostupná.

Jak získám výsledek předání podkladů pro podpis

• Okamžitý výsledek předání podkladů pro podpis zjistíte synchronně jako “Response” na volání příslušného endpointu.

• Pokud jsou podklady kompletní a validní, kód odezvy je 200 Chybové kódy začínají 400 , kde v body je popis chyby. Občas můžete narazit na universlání chybu 500, snažíme se jí minimalizovat.

• V BODY odpovědi získáte i hodnotu proměnné Contract_ID, což je identifikace dokumentu v Signi. Tento údaj je pak použit ve webhooku (viz dále), lze ho použít pro stažení Kontrolního listu s průběhem podpisování dokumentu apod.

• Součástí odezvy jsou i URL unikátních adres stránek pro podpis dokumentu konkrétními podepisujícími/schvalujícími, které lze použít při integraci.

...

Jak získat přístup ke stránkám pro podepsání?

Jsou dvě základní cesty :

...

Jak získat výsledky podepisování? 

Vyvoláním zpětného webhooku

• Součástí předávání podkladů pro podpis jsou i 3 URL adresy  tzv. “webhooků” pro každou hodnotu výsledku:

  • podepsáno - signed,

  • odmítnuto  - rejected,

  • neověřeno - expired.

• URL adresy typicky obsahují volání integrované aplikace. 

• Zavolán je vždy jen jeden webhook z těchto tří podle výsledku. Pokud se parametr url ponechá prázdný, web hook se nevyvolá.

• Ve vzoru volání na apiary.io je třeba text “your_webhook_url\” nahradit reálnou URL.

• Nyní se volá webhook pro každý dokument zvlášť včetně příloh.

• Při volání webhooku předáváme stejný API klíč jako byl použit pro volání Signi tj. zabezpečení je stejné jako směrem do Signi. Typ autorizace je tedy API Key, jako hodnota klíče x-api-key je uveden API klíč workspace, do kterého byl dokument k podpisu poslán, a hodnota se předává v Header.

• Výsledný podepsaný dokumentse do integrované aplikace při vyvolání webhooku předává následovně:

  • {

  •   "contract_id": 3359,

  •   "state": "completed",

  •   "file": "https://api.test.ismlouva.cz/api/v1/contract/pdf/preview?hash=95d02b75275851c8851b3528a4b365fd7e03fa8991ed23b25e30d16c4558",

  •   "attachments": []

  • }

...

• Později lze stáhnout dokumentpřeshttps://api.signi.com/api/v1/contract/id/download

• Soubor ve webhooku a end pointu download se předává ve formátu - Application/pdf .

• PŘIPRAVUJEME: Volbu, kdy půjde pouze podepsat všechny dokumenty v jednom volání a zpět se bude volat pouze jeden webhook. Hodí se např. tehdy, pokud v integrovaném  workflow systému je možné jedno větvení podmínek pro jeden případ, který ale zahrnuje více dokumentů.

Průběžným ověřováním stavu

• Někdy lze webhooky v integrovaném systému obtížně implementovat.

• Je možné se periodicky anebo např. při otevření detailu souvisejícího záznamu v integrovaném dokumentu dotazovat na aktuální stav dokumentu.

• Při odeslání dokumentu k podpisu v odpovědi získáte identifikátor dokumentu Contract_id:
  Response 200 HEADERS Content-Type:application/json BODY {  "contract_id": "1234",   "attachments": [] }

Stav příslušného dokumentu získáte přes End Point Detail smlouvy, tj. https://api.ismlouva.cz/api/v1/contract/id, kde id je Contract_id.

Jak se dostanu k polím definovaným v daném vzoru?

• Vzor dokumentu je uložen v rozšířené verzi HTML. 

• Přístupný je na endpointu https://ismlouva3rdpartyservice1.docs.apiary.io/#reference/smlouvy/contract/contract-detail

• Obsahuje pole pro nahrazení reálnými hodnotami (placeholder), typu CON_TEXT a další.

V jakém formátu se předávají soubory k podpisu i zpět?

• Soubory k podpisu s předávají ve formátu - multipart/form-data

• Soubor ve webhooku a end pointu download se předává ve formátu  - Application/pdf

PŘIPRAVUJEME: Ve variantě End Pointů Full RestAPI budou binární soubory překódovány do textu.

Jak se předávají identifikační čísla dokumentu?

• Nyní se pro identifikaci používá číslo dokumentu v Signi - Contract_ID, které je výsledkem vyvolání podpisu a je i součástí volání webhooku (v HEAD sekci).

• Pokud si chcete předávat i identifikaci dokumentu v integrovaném systému, jako workaround je možné tuto identifikaci vložit do adresy webhooků.

PŘIPRAVUJEME: Předání identifikace dokumentu v integrovaném systému v logice “vaše číslo/naše číslo” do parametrů vyvolání podpisu i webhooků.

Jdou změnit texty zasílaných e-mailů a SMS? 

• Ano, lze - je to nastavení platné pro celý workspace/pracovní prostor a může je měnit jakýkoli uživatel s přístupem do prostoru.

• Lze určit i jméno odesílatele, resp. jméno adresáta odpovědi (REPLY TO)

• Parametry v textech k záměně dle aktuálního stavu:

  • {CONTRACTNAME} - Doplní název dokumentu, pokud není vyplněn název souboru nebo použitého vzoru

  • {NAME} - Doplní celé jméno vlastníka pracovního prostoru

  • {CLIENTNAME} - Doplní celé jméno klienta - u osob jméno a příjmení??, u firem??

Vytváření hlavního dokumentu s několika přílohami

• Posloupnost volání

  • endpoint template {.... Last_document:false… }

  • endpoint template attachment  {.... Last_document:false… }

  • endpoint template attachment  {.... Last_document:false… }

  • endpoint template attachment  {.... Last_document:true… }

• Dokument může mít neomezené množství příloh, podpis každého je účtován jako samostatný podpis.

• Pokud má člověk podepsat více dokumentů v jedné dávce, dojde mu pouze jedna SMS a e-mail. Pak se mu ukáží jednotlivé dokumenty, které musí podepsat jeden po druhém.

PŘIPRAVUJEME: Výsledek podpisu každého z dokumentů se předává samostatným voláním příslušného webhooku. Volbu, kdy půjde pouze podepsat všechny dokumenty v jednom volání.

Je možné mít vlastní branding?

• Vlastní branding se hodí : 

  • v rámci prodejního procesu -  kdy ukážeme zákazníkovi “jeho design” na prvcích komunikace = mailech a stránkách pro schválení dokumentů,

  • při skutečném nasazení.

• Zatím nelze “naklikat”, lze zaslat požadavek.

• Možnosti brandingu jsou popsány v Kroky podpisu dokumentu a možnosti brandingu - PUBLIC.

PŘIPRAVUJEME: Cílově půjde o jeden z úkonů, které mohou připravovat pro koncové zákazníky ve svém rozhraní a účtovat partneři.

Jak sladit vzory a volání API, aby se podpisy ukazovaly na správných místech ? 

Pole pro podpisy ve vzorech je třeba mít přízpůsobené scénáři podepisování předávaném přes API. Pokud záleží na pořadí podepisujících, musí být vzory přízpůsobené i tomu. Dva základní scénáře jsou následující. 

...

"settings": {
        "signing_order": "one_at_a_time"
    },

Proč není API Signi striktně RestAPI?

• Signi je integrovaná s různě vyspělými aplikacemi.

• Tomu odpovídá současná podoba API, kterou lze nazvat “Essential” a lze snadno použít jednoduše i při základním volání z jednoduchého webu na PHP či CURL utilitu přes HTTP. 

...