Rozhraní slouží k tomu, aby smlouvy k podpisu vznikaly rovnou ve vašem systému: v ERP se schválí objednávka a zákazníkovi odejde smlouva, v CRM se uzavře obchod a podepíše se, v HR systému nastoupí člověk a podepíše smlouvu. Podpisuj se stará o ověření totožnosti, doručení, podpis i archivaci.
Ukázky kódu, parametry a odpovědi najdete ve Swaggeru. Na
interaktivní dokumentaci si volání rovnou
vyzkoušíte v prohlížeči, stačí nahoře vložit klíč. Strojově čitelná specifikace
je na /api/openapi.json,
vygenerujete si z ní klienta ve svém jazyce.
Tahle stránka je jen rychlý přehled: k čemu API je, kdo ho může použít a co je dobré vědět předem.
Každý, kdo má aktivní balíček obálek. Klíč si v účtu vytvoříte kdykoli,
i bez balíčku, takže si integraci můžete připravit dopředu. Do doby, než balíček
pořídíte, ale každé volání skončí chybou 402. Nejmenší
balíček je Balíček 10 za
149 Kč měsíčně.
Klíč patří vaší organizaci, ne jednomu člověku. Čerpá stejný zůstatek obálek jako web, takže dokument odeslaný z ERP a dokument odeslaný ručně jdou z jedné hromádky. Přehled balíčků
GET /v1/ping.Klíč patří na server, ne do prohlížeče ani do mobilní aplikace. Kdokoli ho získá, může vaším jménem zakládat dokumenty k podpisu a utrácet vaše obálky.
X-API-Key, případně jako
Authorization: Bearer. Tvar klíče je
pps_live_<prefix>_<secret>.{"data": …}, chyba
{"error": {"code": …, "message": …}}. Rozhodujte se
podle code, ne podle textu, ten se může změnit.draft → signing →
finalizing → completed,
případně cancelled. Dokument založený přes API jde
rovnou do signing, protože je zaplacený obálkou.429 s hlavičkou Retry-After,
podle které víte, kdy to zkusit znovu.Úplný popis včetně parametrů a ukázek je ve Swaggeru. Tady je jen seznam, ať víte, s čím počítat.
/v1/documentsNahraje PDF, přidá podepisující a rovnou jim rozešle výzvy. Spotřebuje jednu obálku./v1/documents/{id}Stav dokumentu včetně stavu jednotlivých podepisujících./v1/documentsVýpis dokumentů od nejnovějších, s filtrem podle stavu./v1/documents/{id}/fileStažení PDF. Výchozí je podepsaná verze, na vyžádání původní soubor./v1/documents/{id}/remindZnovu pošle výzvu tomu, kdo je na řadě. Nic nestojí./v1/documents/{id}/cancelZruší rozpracovaný podpis. Obálka se nevrací, pozvánky už odešly.Pozvánky rozesíláme e-mailem sami. Odkaz na podpis přesto v odpovědi dostanete, kdybyste chtěli podpis nabídnout rovnou ve svém rozhraní.
/v1/identity-verificationsZaloží žádost a vrátí odkaz, na který člověka pošlete./v1/identity-verifications/{id}Stav ověření. U otevřené žádosti se doptáme ověřovací služby, takže dostanete čerstvý výsledek.Totožnost si můžete nechat ověřit i bez podpisu, třeba při registraci klienta nebo v onboardingu, všude tam, kde dnes chcete kopii občanky. Člověk se na našem odkazu přihlásí, vyfotí doklad a sebe, a vy si výsledek vyzvednete dotazem nebo počkáte na webhook.
pendingverifiedrejectedexpiredProč přijde rejected, i když byl doklad v pořádku.
Nejčastější důvod není špatná fotka, ale neshoda jména: jméno na dokladu
neodpovídá jménu na účtu Wopro. Stává se to po svatbě nebo při překlepu v účtu.
Člověk to spraví opravou jména v účtu a novým pokusem. Počítejte s tím
v textech, které mu zobrazíte.
429./v1/pingKontrola klíče. Vrátí i organizaci, balíček a zůstatek obálek./v1/balanceZůstatek obálek, rozpis dávek s daty platnosti a čerpání limitu ověření.Obálky se sčítají a každá připsaná dávka platí 12 měsíců. Čerpáme vždy tu, které platnost končí nejdřív, ať propadne co nejmíň.
U klíče si můžete nastavit adresu, na kterou pošleme POST, když se něco stane. Ušetří vám to opakované dotazování na stav.
document.signeddocument.completeddocument.cancelledidentity.verifiedstatus.Události chodí na všechny aktivní klíče vaší organizace, které mají vyplněnou adresu webhooku. Když máte víc integrací, dozví se to každá z nich.
Ověřte si, že zpráva je opravdu od nás. V hlavičce
X-Podpisuj-Signature posíláme HMAC-SHA256 celého těla
požadavku, podepsaný klíčem webhooku, který dostanete při vytvoření klíče.
Porovnejte ho časově konstantním porovnáním, ne obyčejnou rovností.
Novější integrace ať raději ověřují X-Podpisuj-Signature-V2:
je to HMAC-SHA256 řetězce timestamp + "." + tělo, kde
timestamp je unixový čas z hlavičky
X-Podpisuj-Timestamp. Zprávu s časem starším než pár minut
odmítněte, zachycený webhook pak nejde přehrát znovu. Původní hlavička zůstává.
Odpovězte prosím do pěti vteřin jakýmkoli kódem 2xx. Doručení neopakujeme, takže když váš server zrovna neběží, událost se ztratí. Proto si stav pro jistotu ověřte i dotazem všude, kde na něm stojí účetní nebo schvalovací proces. Webhook berte jako urychlení, ne jako jediný zdroj pravdy.
Chcete začít? Otevřít Swagger dokumentaci nebo si rovnou vytvořit API klíč.
Něco nefunguje nebo vám v rozhraní něco chybí? Napište na [email protected]. Podpisuj.cz je služba Wopro (Websprofiky s.r.o.).