Ne všichni děláme integrace každý den. Proto jsme pro vás připravili rychlokurz integrace v dnešním světě, kde stručně zmiňujeme ty nejdůležitější pojmy a nástroje. Až se všim prokousáte, můžete pokračovat na příklady volání API.
Základní principy a pojmy
Co potřebuje mít člověk v hlavě, aby rozuměl věcem kolem API
Komunikace po internetu https://everything.curl.dev/protocols/network
Internetové protokoly https://everything.curl.dev/protocols/protocols
EndPoint - https://en.wikipedia.org/wiki/Web_API
REST- https://en.wikipedia.org/wiki/Representational_state_transfer https://zdrojak.cz/clanky/rest-architektura-pro-webove-api/
Curl
Curl je open source program pro přenos dat přes různé internetové protokoly. Jeho příkazy se používají k popisu toho, jak se jaká data se při integraci přenáší. Stejně tak lze příkazy v programu spustit.
HTTP POST https://everything.curl.dev/http/post
HTTP Multipart formposts https://everything.curl.dev/http/multipart
HTTP cheat sheet - https://everything.curl.dev/http/cheatsheet
Seznam všech příkazů - https://curl.se/docs/manpage.html
curl HTTP cheat sheet:
hide progress -s | verbose -v --trace-ascii <file> | extra info -w "format" | output -O -o <file> | timeout -m <seconds> |
POST -d "string" -d @file | POST encoded --data-urlencode "[name]=val" | multipart formpost -F name=value -F name=@file | PUT -T <file> | HEAD (ers too) -I -i |
custom method -X "METHOD" | read cookiejar -b <file> | write cookiejar -c <file> | send cookies -b "c=1; d=2" | user-agent -A "string" |
proxy -x <host:port> | add/remove headers -H "name: value" -H "name:" | custom address --resolve <host:port:addr> | smaller data --compressed | insecure HTTPS -k |
Basic auth -u user:passwd | follow redirects -L | parallel -Z | generate code --libcurl <file> | list options --help |
Zdroj: https://curl.github.io/curl-cheat-sheet/http-sheet.html
Seznam všech příkazů: https://curl.se/docs/manpage.html
Curl je většinou již součástí operačního systému - např. MS Windows, kde se spouští z aplikace Příkazová řádka, jež se spouští vyhledáním “cmd” ve vyhledávacím poli na pracovní ploše.
...
Curl příkaz spuštěný z příkazové řádky na MS Windows a jeho výsledek
Apiary
Apiary je jedna ze služeb sloužících pro zveřejňování dokumentace API. Využívá ji i Signi na https://ismlouva3rdpartyservice1.docs.apiary.io/
...
Příklad popisu endpointu “Autorizace > x-api-key > Detail uživatele”,
při volbě cURL v pravém panelu je vidět sada příkaz curl, stejně tak je možné zvolit jiná prostředí
Postman
Postman je jedna ze služeb pro testování volání API. Využívá ji i Signi na https://signiapi.postman.co/.
...
Příklad volání endpointu Detail uživatele
Odkud se vezmou kontaktní údaje na podepisující? - Jméno, Příjmení, E-mail, Telefon (ten není povinný, ale pak ho uživatel musí zadat sám, aby mu přišla SMS a on mohl být ověřen).
Co se bude to posílat? - Hotový dokument PDF/DOCX/HTML/XSLX nebo parametry pro vzor dokumentu uložený v Signi
Jak se vyvolá akce podpisování? - Akce v menu na relevantním záznamu, nastavení nějakého custom pole na hodnotu "Odeslat k podpisu” apod.
Kde se uživateli ukáže výsledek podpisu? - Stav podepisování / výsledný dokument případně celou historii podepisování (viz kontrolní list)
Jak se umístí podpisy? - Nejjednodušší je dynamické umístění podpisů na závěr dokumentu na Podpisovém archu. Variantou je statické umístění na přesné souřadnice (vhodné pro formuláře typu Evidenční list důchodového pojištění).
Jak se předávají výsledky zpět? - Preferovanou variantou je webhook volající aktivně integrovaný systém s výsledkem podepisování. Alternativně se lze z integrovaného systému periodicky ptát na výsledek podepisování.
Jaká bude vazba mezi uživateli a pracovními prostory - workspace v Signi? - Nejjednodušší scénář: V Signi je zavedený servisní účet pro celý integrovaný systém nebo jeho jednotlivé koncové zákazníky. Podepisující z firmy zákazníka jsou uváděni jako jedna z podepisujících stran, přijde jim e-mail a SMS. Jinou variantou je, že si zákazníci zřídí svůj účet na Signi sami, mají pak možnost přístupu k dokumentům i v Signi, pouze se nastaví integrace přes API, která jim posílá dokumenty k podpisu do určeného pracovního prostoru / workspace . Další scénáře jsou možné dle domluvy.