AuraDoc
Zaloguj sięZałóż

Blog

Webhooki i REST API w AuraDoc

Połącz AuraDoc z własnymi systemami: klucze API z zakresami, podpisane webhooki, dziennik dostaw i automatyczne ponowienia.


Prędzej czy później każdy zespół chce, by dokumenty rozmawiały z resztą oprogramowania: przesłać plik ze skryptu, uruchomić przepływ pracy z harmonogramu albo dowiedzieć się natychmiast, gdy dokument zostanie przetworzony. AuraDoc oferuje dwie uzupełniające się drogi. REST API pozwala Twoim systemom poprosić AuraDoc o wykonanie czegoś, a webhooki pozwalają AuraDoc powiadomić Twoje systemy, że coś się stało. Ten artykuł omawia oba, a także szczegóły bezpieczeństwa ważne w produkcji.

Klucze API i zakresy

Wszystko zaczyna się od klucza API. Utwórz go w Dashboard › Settings › API keys, nadaj mu nazwę i wybierz zakresy. Zakresy ograniczają to, co klucz może robić, więc klucz używany tylko do przesyłania plików nie potrzebuje uprawnień do zarządzania czymkolwiek innym. Klucz nie może utworzyć innego klucza o szerszych zakresach niż jego własne, a faktyczne uprawnienia to zawsze te wspólne dla klucza i roli osoby, jak opisano w role i uprawnienia zespołu. Żądania niosą klucz w nagłówku Authorization jako token bearer.

Ta sama strona pokazuje statystyki użycia każdego klucza, dzięki czemu widać, która integracja jest aktywna, a która ucichła. W planach płatnych można też ustawić limit żądań dla pojedynczego klucza, co przydaje się, gdy hałaśliwy skrypt nie powinien szkodzić innym. Jeśli klucz wycieknie, usuń go i utwórz nowy; po stronie AuraDoc nic więcej nie trzeba zmieniać.

Co potrafi API

Strona integracji w dokumentacji podaje adres bazowy i zawiera przykłady gotowe do skopiowania. Obecnie możesz przesłać dokument, poprosić AuraDoc o pobranie dokumentu z adresu URL, uruchomić przepływ pracy i utworzyć prośbę o podpis, każde jednym uwierzytelnionym żądaniem. To te same operacje, które ludzie wykonują w panelu, więc wynik utworzony przez API pojawia się w interfejsie jak każdy inny.

Jeśli wolisz odpytywać niż przyjmować wywołania, są punkty końcowe wyzwalaczy zwracające nowe dokumenty, ukończone uruchomienia przepływów i ukończone podpisy, wraz z katalogiem je opisującym. Narzędzia, które nie odbierają webhooków, takie jak dodatki do arkuszy lub platformy no-code, mogą odpytywać je cyklicznie. Pełna dokumentacja jest na stronie dokumentacji integracji.

Webhooki wychodzące

Aby dostawać powiadomienia na bieżąco, otwórz Dashboard › Webhooks i dodaj punkt końcowy. Interesujące zdarzenia wybierasz z listy, na której są między innymi dokument utworzony, sklasyfikowany i usunięty, OCR i tłumaczenie zakończone lub nieudane, zdarzenia przepływów, ostrzeżenia o limicie miejsca oraz zdarzenia podpisów. Przy zapisie AuraDoc pokazuje sekret podpisu tylko raz. Skopiuj go od razu do usługi odbierającej; jeśli go zgubisz, wymień sekret, a zostanie wygenerowany nowy, przy czym wymiana trafia do dziennika audytu.

Treść można ukształtować szablonem o długości do kilku tysięcy znaków i sprawdzić go przed zapisem. Przycisk testu wysyła przykładowe zdarzenie z nagłówkiem testowym, abyś mógł upewnić się, że punkt końcowy jest osiągalny i odczytuje treść, zanim na nim polegasz. Każdy webhook można wyłączyć bez usuwania, co pomaga w oknach serwisowych.

Weryfikacja podpisów i obsługa awarii

Każda dostawa jest podpisana. AuraDoc oblicza HMAC-SHA256 z znacznika czasu i surowej treści przy użyciu Twojego sekretu i wysyła wynik w nagłówku podpisu, razem z nagłówkami z nazwą zdarzenia, identyfikatorem webhooka, identyfikatorem dostawy, znacznikiem czasu i licznikiem ponowień. Odbiorca powinien ponownie obliczyć podpis z surowej treści, porównać go w stałym czasie i odrzucać żądania ze zbyt starym znacznikiem czasu. Dzięki temu nikt nie podrobi zdarzenia dla Twojego punktu końcowego, nawet znając jego adres.

Punkty końcowe się psują, a AuraDoc to przewiduje. Gdy dostawa się nie powiedzie, jest automatycznie ponawiana ze wzrastającymi odstępami, od pięciu minut do sześciu godzin. Widok dostaw pokazuje każdą próbę z wynikiem, a po naprawieniu problemu możesz ręcznie uruchomić ponowienie. Ponieważ przy ponowieniach używany jest ten sam identyfikator dostawy, odbiorca może bezpiecznie ignorować duplikaty. O łączeniu webhooków z plikami od dostawców przechowywania przeczytasz w chmurowy magazyn i obserwowane foldery.

Powrót do bloga