Gdy dokumenty powstają w innym systemie

Pytanie, które pada na drugim spotkaniu: „czy integrujecie się z naszym systemem?”. Do tej pory uczciwa odpowiedź brzmiała: nie. Teraz odpowiedź jest taka: masz portal, CRM lub system księgowy, w którym transakcja już istnieje, a DocuTract może działać jako jego część.

Szósta funkcja tej fali to wyjście na zewnątrz. Token, którym Twój system się z nami łączy, adres, na który piszemy z własnej inicjatywy, i otwarty opis wszystkiego pomiędzy.

Token, którego nie możemy pokazać dwa razy

Token tworzy się na ekranie Integracje: nazwa, którą później rozpoznasz, żeby wiedzieć, który system go używa, i lista tego, co wolno mu robić. Potem jest pokazywany raz.

To nie zapominalstwo, tylko sposób, w jaki musi działać produkt przechowujący cudzy klucz. Przechowujemy tylko skrót (hash): ponowne pokazanie tokenu jest niemożliwe nawet dla nas, co oznacza, że nie da się go od nas ukraść. Lista zachowuje pierwsze znaki, uprawnienia i datę ostatniego użycia, więc widać, który token jest aktywny i czy ktoś go jeszcze używa.

Unieważnij wyłącza go natychmiast. Zapis o nim zostaje: to, że istniał i kiedy przestał działać, jest częścią historii przestrzeni roboczej, a nie śmieciem.

Uprawnienia są sprawdzane osobno dla każdego adresu. Token, któremu wolno tylko odczytywać szablony, przy próbie utworzenia dokumentu dostaje jasny komunikat „brakuje zakresu documents:write”, a nie pusty „nie znaleziono”. Zakładamy, że integrację podłącza żywy człowiek, a odpowiedź, która niczego nie wyjaśnia, kosztuje go wieczór.

Co potrafi API

Tyle samo, co możesz zrobić na ekranie, tylko bez ekranu: otworzyć sprawę i przesłać do niej skany, utworzyć dokument z szablonu z już wypełnionymi wartościami, zapytać, na jakim etapie jest, pobrać wszystkie wartości wraz ze skanem, z którego każda została odczytana, i otrzymać krótkotrwały link do gotowego pliku.

Ta ostatnia część odróżnia tę integrację od innych. Twój system dostaje nie tylko wypełniony plik, ale każdą wartość z jej pochodzeniem: skan, pole, poziom pewności odczytu. To samo źródło, które człowiek widzi na ekranie sprawdzania, jest dostępne dla kodu.

Opis każdego adresu i pola jest generowany z samego kodu i publikowany otwarcie, bez tokenu: /api/v1/openapi.json. Dokumentacja, o którą trzeba najpierw prosić, to dokumentacja, której nikt nie czyta.

Webhooki i uczciwy dziennik

Nie musisz pytać nas, czy dokument jest gotowy. Podaj nam adres i zaznacz zdarzenia: dokument gotowy, błąd dokumentu, sprawa gotowa, wykryto rozbieżność, klient przesłał plik.

Każde żądanie jest podpisane, a sekret do weryfikacji podpisu jest pokazywany raz, tak jak token. Jeśli Twój serwer odpowiedział czymś innym lub nie odpowiedział wcale, próbujemy ponownie: po minucie, po pięciu, po pół godzinie, po dwóch godzinach i po dziesięciu. Potem przestajemy, bo integracja, której nikt nie utrzymuje, nie powinna bez końca zużywać czyichś zasobów.

A teraz część, dla której to wszystko zostało napisane. Gdy druga strona mówi „nasz system nic nie dostał”, odpowiedź jest na ekranie: zdarzenie, czas, liczba prób, jaki kod odpowiedzi wrócił i początek treści odpowiedzi. Widać, że pięć razy odpowiedział kodem 500. To nie narzędzie do debugowania dla nas, tylko odpowiedź dla Twojego inżyniera.

Obok dwa przyciski na czas, gdy integracja jest jeszcze konfigurowana. Wyślij test wysyła próbne żądanie od razu, bez czekania na prawdziwe zdarzenie, dzięki czemu odbiornik można sprawdzić, zanim przejdzie przez niego jakakolwiek praca. Ponów przy nieudanym dostarczeniu wykonuje jeszcze jedną próbę natychmiast i nie resetuje historii: cztery nieudane próby zostają w zapisie, bo to prawda o tym, ile kosztowało to powiadomienie.

Ograniczenia, które sami sobie narzuciliśmy

Webhook trafia tylko na https i tylko na adres publiczny: adres w sieci prywatnej jest odrzucany zarówno przy zapisie, jak i przed każdą próbą, bo nazwa hosta, która wczoraj wskazywała na zewnątrz, dziś może wskazywać do środka. Limit częstotliwości liczony jest dla tokenu, a nie dla adresu, więc sąsiad na tym samym serwerze nie zużywa Twojego limitu, a jego przekroczenie kończy się uczciwym „wróć za tyle a tyle sekund”.

API i webhooki są częścią planu Team. Jeśli przestrzeń robocza przejdzie na inny plan, to, co już zostało utworzone, pozostaje widoczne i można to unieważnić: klucze, do których nikt nie ma dostępu, są gorsze niż płatna funkcja.

Czego nie ma w tym wydaniu

Założenia tej fazy opisywały jeszcze dwie części: eksport gotowego dokumentu do Google Drive, OneDrive lub Dropbox oraz wysyłanie go do podpisu przez DocuSign lub Dropbox Sign. Obie wymagają danych dostępowych od tych dostawców, których w tej chwili nie mamy, a pisanie integracji, której nigdzie nie da się przetestować, oznacza podawanie nienapisanego kodu za gotowy. Pozostają w planie jako osobne wydania.

Co dalej

Siódma i ostatnia funkcja tej fali to generowanie seryjne: lista pięćdziesięciu wierszy lub archiwum skanów zamiast pięćdziesięciu identycznych ręcznych wypełnień, z widocznym postępem i możliwością powtórzenia tylko tych, które się nie udały.

Pełna lista jest we wpisie nad czym pracujemy dalej, a instrukcje krok po kroku dotyczące integracji – w centrum pomocy.