Amikor a dokumentumok egy másik rendszerben kezdődnek

A kérdés, amely a második megbeszélésen felmerül: „integrálódtok a rendszerünkkel?”. Eddig az őszinte válasz nem volt. Most a válasz a következő: van egy portálod, CRM-ed vagy könyvelési rendszered, ahol az ügylet már létezik, és a DocuTract működhet annak részeként.

A hullám hatodik funkciója a kiút. Egy token, amellyel a rendszered hív minket, egy cím, amelyre mi magunktól írunk, és mindennek nyílt leírása, ami a kettő között van.

Egy token, amelyet nem tudunk kétszer megmutatni

A tokent az Integrációk képernyőn hozod létre: egy név, amelyet később felismersz, hogy tudd, melyik rendszer használja, és egy lista arról, mit tehet. Ezután egyszer jelenik meg.

Ez nem feledékenység, hanem így kell működnie egy terméknek, amely valaki más kulcsát őrzi. Csak egy hash-t tárolunk: a token másodszori megjelenítésére még mi sem vagyunk képesek, ami azt jelenti, hogy tőlünk sem lehet ellopni. A lista megőrzi az első karaktereket, a jogosultságokat és az utolsó használat dátumát, így látszik, melyik token él, és használja-e még valaki.

A Visszavonás azonnal kikapcsolja. A nyoma megmarad: az, hogy létezett, és mikor szűnt meg működni, a munkaterület történetének része, nem szemét.

A jogosultságokat minden címen külön ellenőrizzük. Egy token, amely csak sablonokat olvashat, egyértelmű „hiányzik a documents:write jogosultság” választ kap, ha dokumentumot próbál létrehozni, nem egy üres „nem található” üzenetet. Abból indulunk ki, hogy egy élő ember köti be az integrációt, és egy semmit sem magyarázó válasz egy estéjébe kerül.

Mire képes az API

Ugyanarra, amire a képernyőn, csak képernyő nélkül: ügyet nyithatsz, és szkeneket tölthetsz fel bele, dokumentumot hozhatsz létre egy sablonból már kitöltött értékekkel, lekérdezheted, melyik szakaszban tart, lekérheted az összes értéket azzal a szkennel együtt, amelyből mindegyiket kiolvastuk, és rövid életű linket kaphatsz a kész fájlhoz.

Ez az utolsó rész teszi ezt az integrációt különbözővé a többitől. A rendszered nem csak egy kitöltött fájlt kap, hanem minden értéket a származásával együtt: a szkent, a mezőt és azt, mennyire volt biztos a kiolvasás. Ugyanaz a forrás, amelyet egy ember az ellenőrző képernyőn lát, a kód számára is elérhető.

Minden cím és mező leírását magából a kódból generáljuk, és nyilvánosan, token nélkül tesszük közzé: /api/v1/openapi.json. Az a dokumentáció, amelyet előbb el kell kérni, olyan dokumentáció, amelyet senki sem olvas el.

Webhookok és egy őszinte napló

Nem kell megkérdezned tőlünk, hogy elkészült-e egy dokumentum. Adj meg egy címet, és jelöld be az eseményeket: a dokumentum elkészült, a dokumentum sikertelen, az ügy kész, eltérést találtunk, egy ügyfél fájlt küldött.

Minden kérés alá van írva, és az aláírást ellenőrző titkos kulcs a tokenhez hasonlóan egyszer jelenik meg. Ha a szervered mást válaszolt, vagy egyáltalán nem válaszolt, újra próbálkozunk: egy perc után, öt után, fél óra után, két óra után és tíz után. Ezután abbahagyjuk, mert egy integráció, amelyet senki sem tart karban, ne fogyassza örökké valakinek az erőforrásait.

És most jön az a rész, amiért mindez készült. Amikor a másik fél azt mondja, „a rendszerünk semmit sem kapott”, a válasz a képernyőn van: az esemény, az időpont, hány próbálkozás volt, milyen válaszkód jött vissza, és a válasz törzsének eleje. Látszik, hogy ötször 500-zal válaszolt. Ez nem nekünk szóló hibakeresési segédlet, hanem válasz a te mérnöködnek.

Mellette két gomb arra az órára, amikor az integrációt még éppen beállítják. A Teszt küldése azonnal küld egy próbakérést, anélkül hogy valódi eseményre várna, így a fogadó oldal még azelőtt ellenőrizhető, hogy bármilyen munka átmenne rajta. Az Újra egy sikertelen kézbesítés mellett azonnal még egy próbálkozást indít, és nem nullázza az előzményeket: a négy sikertelen próbálkozás a naplóban marad, mert ez az igazság arról, mibe került ez az értesítés.

A korlátok, amelyeket magunkra szabtunk

Egy webhook csak https-re és csak nyilvános címre megy: a privát hálózaton belüli címet mentéskor és minden próbálkozás előtt is elutasítjuk, mert egy gépnév, amely tegnap kifelé mutatott, ma befelé mutathat. A sebességkorlát tokenenként számol, nem címenként, így egy szomszéd ugyanazon a szerveren nem a te keretedet fogyasztja, túllépéskor pedig egy őszinte „gyere vissza ennyi másodperc múlva” választ kapsz.

Az API és a webhookok a Team díjcsomag részei. Ha egy munkaterület másik díjcsomagra vált, ami már létrejött, látható marad és visszavonható: a senki által el nem érhető kulcsok rosszabbak, mint egy fizetős funkció.

Mi nincs benne ebben a kiadásban

Ennek a szakasznak a leírása még két részt tartalmazott: a kész dokumentum exportálását Google Drive-ra, OneDrive-ra vagy Dropboxba, és aláírásra küldését DocuSignon vagy Dropbox Signon keresztül. Mindkettőhöz ezektől a szolgáltatóktól származó hozzáférési adatok kellenek, amelyekkel jelenleg nem rendelkezünk, és egy sehol sem tesztelhető integráció megírása azt jelentené, hogy megíratlan kódot adunk ki késznek. Ezek önálló kiadásokként a tervben maradnak.

Mi következik

A hullám hetedik, egyben utolsó funkciója a kötegelt generálás: egy ötvensoros lista vagy egy szkeneket tartalmazó archívum ötven egyforma kézi kitöltés helyett, látható előrehaladással és azzal a lehetőséggel, hogy csak azokat ismételd meg, amelyek nem sikerültek.

A teljes lista a Min dolgozunk ezután című bejegyzésben található, az integrációk lépésről lépésre szóló útmutatója pedig a súgóközpontban.