Další pokročilé příklady volání Signi API

Změněno dne Út, 4 Červen v 3:17 ODPOLEDNE

Varianty podepisování zástupců organizace použivající Signi

Při integraci Signi umožňuje několik variant podepisování pracovníků organizace používající Signi, typicky statutáře, zplnomocněné obchodníky apod. :

A - Pracovníci organizace v Signi nemají účet, pouze přes něj podepisují stejně jako protistrany.
B - Pracovníci organizace v Signi mají účet, mohou se jejich podpisy vkládat automaticky.
C - Podpis pracovníka organizace je již vložen např. v grafické podobě do dokumentu vkládaného do Signi, Signi zajišťuje jen podpis protistran.

Klíčovým faktem přitom je, že každý dokument v Signi musí mít svého jednoznačného autora dokumentu.

Ve scénáři A

Výhodou scénáře je jednoduchost na zprovoznění. Nevýhodou je, že podepisující pracovníci organizace, typicky statutáři, musí podepsat či schválit každý jednotlivý dokument.

Pracovníci organizace nemusí mít účet v Signi, podepisují stejně jako protistrany - dostanou e-mail s výzvou k podpisu, otevřou si z něho stránku podpisu a dokument podepíší či schválí.
Pří integraci lze jako navrhovatele/autora dokumentu uvést e-mail zakladatele pracovního prostoru / workspace na Signi, kam se dokument odesílá, a říci, že on dokument bude pouze (přes API automaticky) schvalovat.
Pracovníci organizace i protistrany mohou dokumenty podepisovat (smlouvy) nebo pouze schvalovat (např. Všeobecné obchodní podmínky).
Scénář podepisování předaný přes API pak bude obsahovat například toto:

{
"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"
  }
],

Ve scénáři B

Pokud pracovníci organizace:

může být jejich podpis vložen do dokumentu automaticky. Podle EIDAS je to v pořádku, podpis probíhá v kontrolovaném prostředí Signi, které zajistí, že podpis bude neoddělitelně připojen k odpovídajícím dokumentům, a volající aplikace (vaše) daného člověka autentifikovala a autorizovala ho k vytvoření, podepsání a předání dokumentu k podpisu dalším protistranám.

Scénář podepisování předaný přes API pak bude obsahovat například takto , autorem / navrhovatelem dokumentu, jehož podpis může být za podmínek výše vložen automaticky je podepisujiciobchodnik@firmanavrhujicidokument.cz:

{
"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"
  }
],

Libovolný uživatel workspace s právem podpisu jako autor/navrhovatel dokumentu může být podepsán i automaticky. Musí ale podepisovat jako první před protistranami. Pro propojení na Signi přitom lze použít API klíč zakladatele workspace. 3 pracovníci/e v HR tak mohou být na "svých" dokumentech automaticky podepsány, pouze při volání API jsou jejich maily uváděny jako emaily navrhovatele tj. “is_proposer”: true u osoby na první místě podpisového scénáře v poli Person.

Ve scénáři C

Z hlediska EU direktivy eIDAS lze za elektronický podpis na úrovni prostý považovat i podpis v grafické podobě vložený do dokumentu. Je to obdoba situace, kdy v dopisu z banky je umístěn podpis odpovědného manažera banky, nepředpokládá se, že by se pracovník podepisoval na tisíce dokumentů.

Má smysl v případech, kdy je nízké riziko sporu resp. toho, že protistrana bude rozporovat podpis navrhovatele.

V tom případě podepisuje jen protistrana, zástupce navrhovatele, kterým je zakladatel workspace dokument automaticky schválí.

{
"settings": {
  "signing_order": one_at_a_time",
}
{
"people": [
  {
    "is_proposer": true,
    "email": "zakladatelworkspace@firmanavrhujicidokument.cz",
    "contract_role": "approve"
  },
  {
    "is_proposer": false,
    "party_order": 2,
    "email": "podepisujícizakazník@firmaprotistrana.cz",
    "contract_role": "sign"
  }
],

Volba "contract_role = sign / approve" říká, zda bude fyzicky nějaký podpis na dokumentu, či zda ho má nějaký člověk pouze schválit.

Pokud má být vidět někde na dokumentu podpis, například na smlouvě, volá se se "sign".
Pokud má někdo dokument jen odsouhlasit, například Všeobecné podmínky, volá se s "approve".

Jak je zachycena vazba uživatel integrované aplikace a workspace a uživatel v Signi

Vazba uživatelé integrované aplikace - Signi workspace

Workspace v Signi slouží pro ukládání dokumentů, do jeho týmu může být přiřazeno více lidí. Více lidí naopak může mít přístup do více workspace.
Při volání Signi API se pro autentizaci používá API klíč, tj. jasně se určuje, do kterého workspace bude dokument uložen. Více viz Generování API klíče.
Pokud jsou ve vaší aplikaci evidováni:
- a) pouze uživatelé - musí být u každého uživatele uveden API klíč.
- b) také firmy či pobočky uživatelů - k nimž jsou pak přiřazení jednotliví uživatelé ukládající dokumenty v jednom workspace v Signi, může být Signi API klíč uveden u firmy či pobočky a využívat se při volání všech "jejích" uživatelů

Vazba uživatelé integrované aplikace - Signi uživatelé

V režimu účtu A viz výše, je to jednodušší. Stačí mít
- u všech uživatelů zadaný e-mail hlavního účtu zákazníka v Signi,
- u firmy/pobočky zadaný e-mail hlavního účtu zákazníka v Signi.
V režimu účtu B je třeba u všech uživatelů zadaný jejich e-mail, kterým se přihlašují do Signi.

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.

PŘIPRAVUJEME: Paralelní verzi fundamentálně pojatého RestAPI, kde například binární soubory jsou překódované do textového řetězce.

Jak testovat chování Signi pro neregistrované uživatele?

Signi se chová odlišně pro ty, kteří jsou a nejsou zaregistrovaní v Signi. U prvních Signi pro podepsání dokumentu vyžaduje jejich přihlášení do Signi. Jim doručené dokumenty k podpisu mají pak přístupné v jejich privátním workspace. Druhým se nabízí anonymní unikátní stránky pro identifikaci a podpisy.

Pro testování Signi pro neregistrované uživatele je vhodné následující:

použití emailů:

Pokud používáte emailové účty na Google, lze využít jejich funkci, kdy do schránky neco@firmanagoogle.cz přijdou i emaily odeslané na neco+cokoliv@firmanagoogle.cz. Pokud odešlete k podpisu dokument na v Signi neregistrovaného podepisujícího jarda.ripa+test@signi.com, dojdou notifikační emaily do vaší existující schránky jarda.ripa@signi.com, pod kteroužto adresou je účet v Signi vytvořen.
V jiných případech má smysl založil firemní e-mailovou skupinu neregistrovanivsigni@firma.cz, zařadit do ní všechny testovače Signi a používat tento email jako adresu podepisujícího neregistrovaného v Signi.

vyvolání odkazů pro podepisování protistran:

Pokud jste v www prohlížeči přihlášení do Signi jako navrhovatelé, je třeba odkazy pro podpisy otevírat v anonymním okně, protože Signi jinak předpokládá, že dokument chcete podepisovat jako navrhovatel tj. odkaz pro protistranu je vám nepřístupný. Projeví se to zobrazením chyby neplatný link.

Tip: Pro testování podpisů protistran je možné si testování zkrátit tím, že nečekáme na došlý email, ale využijeme odkaz přístupný v detailu dokumentu, který si zkopírujeme ikonou kopírování.

První podepisuje navrhovatel a druhý protistrana, plní se data vzoru

{
  "contract_name":"document name - nonmandatory",
  "number": "document number - nonmandatory",
  "locale": "cs",
  "settings": {
    "signing_order": "proposers_before_counterparties",
    "autosign_proposers": "V Praze"
  },
  "people": [
    {
      "is_proposer": true,
      "email": "demo@signi.com",
      "contract_role": "sign"
    },
    {
      "is_proposer": false,
      "party_order": 1,
      "email": "demo+API@signi.com",
      "contract_role": "sign",
    "person_type": "nature",
          "first_name": "John",
          "last_name": "Doe#2"
    }
  ],
  "template": {
      "id": "7v1",
      "parameters": [
        {"id": "112", "value": "Hnutí za digitalní revoluci"},
        {"id": "131", "value": "Chci"},
        {"id": "411", "value": "V šíření zpráv"},
        {"id": "421","value": "27.5.2021"},
        {"id": "431","value": "v Praze"}
      ]
  }
}

Automaticky schválí zástupce navrhovatele a následně podepisuje protistrana, podepisuje se soubor, podpisy na konci v Podpisovém archu.

Viz Autoplacement of Signature

Podepisuje najednou zástupce navrhovatele i protistrany, podepisuje se soubor, pozice podpisů jsou určeny poli pro umístění podpisů v dokumentu.

{
    "contract_name": "Document with placeholders",
    "number": "2022000001",
    "locale": "cs",
    "settings": {
        "signing_order": "all_at_once"
    },
    "people": [
        {
            "is_proposer": true,
            "email": "demo@signi.com",
            "contract_role": "sign",
            "positions": [
              {
                "anchor": "signi-signature-00"
              } 
            ]

        },
        {
            "is_proposer": false,
            "email": "zakaznik@seznam.cz",
            "contract_role": "sign",
            "person_type": "nature",
            "first_name": "John",
            "last_name": "Doe#2",
            "positions": [
              {
                "anchor": "signi-signature-02"
              } 
            ]
        }
    ],
    "file": "uploaded_file_key"
}

Obě strany podpisují přes BankID Sign

JSON viz Signing with BankID

Broker a dva zákazníci podpisují formulář přes BankID

{
  "locale": "cs",
  "settings": {
    "signing_order": "all_at_once"
  },
  "people": [
    {
      "is_proposer": true,
      "email": "registered.broker@test.cz",
      "contract_role": "sign_bank_id_sign",
      "positions": [
        {"x": 20, "y": 60, "page": 0}
      ]
    },
    {
      "is_proposer": false,
      "email": "customer1@test.cz",
      "contract_role": "sign_bank_id_sign",
      "person_type": "nature",
      "first_name": "John",
      "last_name": "Customer#1",
      "positions": [
        {"x": 20, "y": 70, "page": 0}
      ]
    },
    {
      "is_proposer": false,
      "email": "customer2@test.com",
      "contract_role": "sign_bank_id_sign",
      "person_type": "nature",
      "first_name": "John",
      "last_name": "Customer#2",
      "positions": [
        {"x": 20, "y": 80, "page": 0}
      ]
    }

  ],

  "file": "uploaded_file_key",
  "attachments": []
}

Podepisuje neregistrovaný makléř a neregistrovaný klient přes BankID Sign např. když v hlavním systému připraví smlouvu a nabídnou jí k podpisu přímo v hlavním systému

{
   "locale": "cs",
   "settings": {
       "signing_order": "all_at_once",
       "autosign_proposers": true
   },
   "people": [ 
       {
           "is_proposer": true,
            "email": "registered.bot@test.cz",
            "contract_role": "approve"
        },
        {
            "is_proposer": false,
            "email": "broker@test.cz",
            "person_type": "nature",
            "first_name": "John",
            "last_name": "Broker",
            "contract_role": "sign_bank_id_sign",
            "positions": [
                {"x": 40, "y": 70, "page": 0}
            ]
        },
        {
            "is_proposer": false,
            "email": "customer1@test.cz",
            "contract_role": "sign_bank_id_sign",
            "person_type": "nature",
            "first_name": "John",
            "last_name": "Customer#1",
            "positions": [
                {"x": 20, "y": 70, "page": 0}
            ]
        }
    ],

    "file": "uploaded_file_key",
    "attachments": []
}

Hlavní systém vygeneruje již PDF již podepsané certifikátem a klient podepisuje přes BankID Sign

{
   "locale": "cs",
   "settings": {
       "signing_order": "all_at_once",
       "autosign_proposers": true
   },
   "people": [ 
       {
           "is_proposer": true,
            "email": "registered.bot@test.cz",
            "contract_role": "approve"
        },
        {
            "is_proposer": false,
            "email": "customer1@test.cz",
            "contract_role": "sign_bank_id_sign",
            "person_type": "nature",
            "first_name": "John",
            "last_name": "Customer#1",
            "positions": [
                {"x": 20, "y": 70, "page": 0}
            ]
        }
    ],

    "file": "uploaded_file_key",
    "attachments": []
}

Posílání dokumentů ve stavu Rozpracováno / Draft

Integrovaná aplikace posílá dokument do Signi ve stavu draft, tam se objeví ve stavu Rozpracováno, zde lze doupravit a odeslat.

Příklady použití

{
  "locale": "cs",
  "state": "draft",
  "settings": {
    "signing_order": "all_at_once"
  },
  "people": [
    {
      "is_proposer": true,
      "email": "registered.broker@test.cz",
      "contract_role": "sign_bank_id_sign",
      "positions": [
        {"x": 30, "y": 70, "page": 0}
      ]
    },
    {
      "is_proposer": false,
      "email": "customer1@test.cz",
      "contract_role": "sign_bank_id_sign",
      "person_type": "nature",
      "first_name": "John",
      "last_name": "Customer#1",
      "positions": [
        {"x": 20, "y": 70, "page": 0}
      ]
    }
  ],

  "file": "uploaded_file_key",
  "attachments": []
}

Podepsání dokumentu s kontrolou před podpisem statutárních zástupců

Viz také Knihovna scénářů >Podepsání dokumentu s kontrolou před podpisem statutárních zástupců

{

    "contract_name": "S kontrolou dokumentu před odesláním, záleží na pořadí",
    "state": "pending",
    "settings": {
        "signing_order": "one_at_a_time"
    },
    "template": {
        "parameters": [
            {"id": "Zadost.Name", "value": "000477"},
            {"id": "Zadost.Organizace__r.Name", "value": "Nadace TEST"},
            {"id": "Zadost.Organizace__r.BillingStreet","value": "Zelenecska 954/24b"},
            {"id": "Zadost.Organizace__r.BillingCity","value": "Prague 9"},
            {"id": "Zadost.Organizace__r.BillingPostalCode", "value": "19800"},
            {"id": "Zadost.Organizace__r.Clouderia_Reg__ICO__c","value": "10203058"},  
            {"id": "Zadost.Organizace__r.Typ_rejstriku__c", "value": "Nadační rejstřík"},
            {"id": "Zadost.Organizace__r.Clouderia_Reg__Court_Name__c","value": "soud Praha 10"},
            {"id": "Zadost.Organizace__r.Clouderia_Reg__Court_File_Number__c","value": "35"},  

            {"id": "1.1 varianta 1", "value": "hide"},
            {"id": "1.1 varianta 2", "value": "show"}
            
        ],
        "id": "1085"
    },
    "people": [
        {
            "contract_role": "approve",
            "email": "demo+CZzamestnanec4@signi.com",
            "is_proposer": true,
            "last_name": "Kontrolující za navrhovatele s právem přístupu do workspace"
        },
        {
            "contract_role": "sign",
            "email": "demo+CZzamestnanec1@signi.com",
            "is_proposer": true,
            "last_name": "Podepisující za navrhovatele s právem přístupu do workspace"
        },
        {
            "last_name": "Jenik",
            "first_name": "Ales",
            "person_type": "nature",
            "contract_role": "sign",
            "email": "demo+protistrana1@signi.com",
            "is_proposer": false
        }
     
    ]
}

Integrovaná aplikace vrací URL, na které může schválit aktuální uživatel v PipeDrive. Na stránce otevřené z odkazu lze dokument schválit nebo podepsat.

Odmítnutí

Schválení