Podpisuj.cz Podpisuj.cz by WOPRO
Pro vývojáře

API Podpisuj.cz

Verze v1 · Základní adresa https://podpisuj.cz/api/v1

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.

Kdo může API použít

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ů

Než začnete

  1. Aktivujte si balíček obálek.
  2. V účtu v sekci API klíče si vytvořte klíč. Tajnou část ukazujeme jenom jednou, hned si ji uložte.
  3. Ověřte si spojení voláním 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.

Základní pravidla

Přihlášení
Klíč v hlavičce X-API-Key, případně jako Authorization: Bearer. Tvar klíče je pps_live_<prefix>_<secret>.
Tvar odpovědi
Úspěch {"data": …}, chyba {"error": {"code": …, "message": …}}. Rozhodujte se podle code, ne podle textu, ten se může změnit.
Cena
Jeden dokument = jedna obálka, ať ho podepíše jeden člověk nebo 100. Ceny přes API jsou stejné jako ve webu.
Podepisujících v obálce
Určuje váš balíček: u menších 5, od balíčku 100 výše 100.
Stavy dokumentu
draft → signing → finalizing → completed, případně cancelled. Dokument založený přes API jde rovnou do signing, protože je zaplacený obálkou.
Limit volání
120 požadavků za minutu na klíč. Při překročení vrátíme 429 s hlavičkou Retry-After, podle které víte, kdy to zkusit znovu.

Co API umí

Úplný popis včetně parametrů a ukázek je ve Swaggeru. Tady je jen seznam, ať víte, s čím počítat.

Dokumenty k podpisu

POST/v1/documentsNahraje PDF, přidá podepisující a rovnou jim rozešle výzvy. Spotřebuje jednu obálku.
GET/v1/documents/{id}Stav dokumentu včetně stavu jednotlivých podepisujících.
GET/v1/documentsVýpis dokumentů od nejnovějších, s filtrem podle stavu.
GET/v1/documents/{id}/fileStažení PDF. Výchozí je podepsaná verze, na vyžádání původní soubor.
POST/v1/documents/{id}/remindZnovu pošle výzvu tomu, kdo je na řadě. Nic nestojí.
POST/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í.

Ověření totožnosti

POST/v1/identity-verificationsZaloží žádost a vrátí odkaz, na který člověka pošlete.
GET/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.

pending
Žádost běží, člověk ověřením zatím neprošel.
verified
Totožnost ověřena. Člověk teď může i podepisovat.
rejected
Ověření neprošlo. Důvod bývá jiný, než čekáte, viz níže.
expired
Odkaz vypršel dřív, než ho člověk otevřel. Platí 14 dní.

Proč 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.

Účet

GET/v1/pingKontrola klíče. Vrátí i organizaci, balíček a zůstatek obálek.
GET/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íň.

Webhooky

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.signed
Někdo podepsal. V těle je, kdo podepsal, kdo je na řadě dál a jestli už podepsali všichni.
document.completed
Podepsali všichni a PDF je hotové. V těle je i otisk podepsaného souboru a odkaz na ověřovací stránku.
document.cancelled
Dokument byl zrušen. Obálka se nevrací.
identity.verified
Ověření totožnosti dopadlo. Pozor na název: chodí i při zamítnutí, skutečný výsledek je v status.

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

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