Když dokumenty začínají v jiném systému

Otázka, která zazní na druhé schůzce: „integrujete se s naším systémem?“ Až dosud byla poctivá odpověď ne. Teď zní odpověď takto: máte portál, CRM nebo účetní systém, ve kterém obchod už existuje, a DocuTract může fungovat jako jeho součást.

Šestá funkce této vlny je cesta ven. Token, se kterým nás váš systém volá, adresa, na kterou píšeme sami od sebe, a otevřený popis všeho mezi tím.

Token, který vám nemůžeme ukázat dvakrát

Token se vytváří na obrazovce Integrace: název, který později poznáte, abyste věděli, který systém ho používá, a seznam toho, co smí dělat. Pak se zobrazí jednou.

Nejde o zapomnětlivost, takhle musí fungovat produkt, který drží cizí klíč. Uchováváme jen hash: zobrazit token podruhé nedokážeme ani my, což znamená, že ho od nás nelze ukrást. Seznam uchovává první znaky, oprávnění a datum posledního použití, takže je vidět, který token je živý a zda ho ještě někdo používá.

Zneplatnit ho okamžitě vypne. Záznam o něm zůstane: že existoval a kdy přestal fungovat, je součástí historie pracovního prostoru, ne smetí.

Oprávnění se kontrolují u každé adresy zvlášť. Token, který smí jen číst šablony, dostane při pokusu vytvořit dokument srozumitelné „chybí oprávnění documents:write“, ne prázdné „nenalezeno“. Počítáme s tím, že integraci zapojuje živý člověk, a odpověď, která nic nevysvětlí, ho stojí celý večer.

Co umí API

Tolik, kolik můžete udělat na obrazovce, jen bez obrazovky: založit případ a nahrát do něj skeny, vytvořit dokument ze šablony s již vyplněnými hodnotami, zjistit, v jaké fázi je, převzít všechny hodnoty spolu se skenem, ze kterého byla každá přečtena, a získat krátkodobý odkaz na hotový soubor.

Právě ta poslední část odlišuje tuto integraci od ostatních. Váš systém nedostane jen vyplněný soubor, ale každou hodnotu s jejím původem: sken, pole, jak spolehlivé bylo čtení. Stejný zdroj, jaký člověk vidí na obrazovce kontroly, má k dispozici i kód.

Popis každé adresy a pole se generuje přímo z kódu a je veřejně dostupný, bez tokenu: /api/v1/openapi.json. Dokumentaci, o kterou musíte nejdřív požádat, nikdo nečte.

Webhooky a poctivý protokol

Nemusíte se nás ptát, zda je dokument hotový. Dejte nám adresu a zaškrtněte události: dokument hotový, dokument selhal, případ hotový, nalezena nesrovnalost, klient poslal soubor.

Každý požadavek je podepsán a tajný klíč, kterým se podpis ověřuje, se zobrazí jednou, stejně jako token. Pokud váš server odpověděl něčím jiným nebo neodpověděl vůbec, zkusíme to znovu: po minutě, po pěti, po půl hodině, po dvou hodinách a po deseti. Pak přestaneme, protože integrace, o kterou se nikdo nestará, by neměla donekonečna spotřebovávat něčí prostředky.

A pak část, kvůli které tohle všechno vzniklo. Když druhá strana řekne „náš systém nic nedostal“, odpověď je na obrazovce: událost, čas, kolik pokusů, jaký kód odpovědi se vrátil a začátek těla odpovědi. Je vidět, že pětkrát odpověděl 500. Nejde o ladicí pomůcku pro nás, je to odpověď pro vašeho inženýra.

Vedle toho dvě tlačítka pro chvíle, kdy se integrace teprve nastavuje. Odeslat test pošle zkušební požadavek hned teď, bez čekání na skutečnou událost, takže příjemce lze ověřit dřív, než přes něj půjde jakákoli práce. Zkusit znovu u neúspěšného doručení provede ještě jeden pokus okamžitě a historii nevynuluje: čtyři neúspěšné pokusy zůstanou v záznamu, protože to je pravda o tom, co toto upozornění stálo.

Omezení, která jsme si dali sami

Webhook jde jen na https a jen na veřejnou adresu: adresa uvnitř privátní sítě se odmítne jak při uložení, tak před každým pokusem, protože název hostitele, který včera mířil ven, může dnes mířit dovnitř. Limit četnosti se počítá na token, ne na adresu, takže soused na stejném serveru nečerpá váš limit a jeho překročení dostane poctivé „vraťte se za tolik a tolik sekund“.

API a webhooky jsou součástí tarifu Team. Pokud pracovní prostor přejde na jiný tarif, to, co už bylo vytvořeno, zůstane viditelné a lze to zneplatnit: klíče, ke kterým se nikdo nedostane, jsou horší než placená funkce.

Co v této verzi není

Zadání této fáze popisovalo ještě dvě části: export hotového dokumentu na Google Drive, OneDrive nebo Dropbox a jeho odeslání k podpisu přes DocuSign nebo Dropbox Sign. Obojí vyžaduje přístupové údaje od těchto poskytovatelů, které teď nemáme, a napsat integraci, kterou nelze nikde otestovat, by znamenalo vydávat nenapsaný kód za hotový. Zůstávají v plánu jako samostatné verze.

Co bude dál

Sedmá a poslední funkce této vlny je dávkové generování: seznam o padesáti řádcích nebo archiv skenů místo padesáti stejných ručních vyplnění, s viditelným průběhem a možností zopakovat jen ty, které neprošly.

Celý seznam najdete v článku na čem pracujeme dál a návod krok za krokem pro integrace v centru nápovědy.