Signaturit w Odoo: co daje natywny moduł, czego nie da Zapier

Krótka odpowiedź: Zapier wystarczy, by uruchomić podpis i dowiedzieć się, że został zakończony. Nie wystarczy, by odzwierciedlić w Odoo statusy pośrednie, przez które przechodzi dokument, by odzyskać dane po zaginionym webhooku ani by zapisać podpisany PDF i jego dokument dowodowy w odpowiednim rekordzie. Jeśli Twój proces kończy się w momencie podpisu klienta, Zap wystarczy i jest tańszy. Jeśli Twój proces zaczyna się w momencie podpisu klienta (fakturowanie, otwarcie sprawy, zatrudnienie pracownika), statusy muszą być w ERP.

Punkt wyjścia: dokument podróżuje pocztą e-mail

Typowy obieg ma trzy ręczne kroki: ktoś generuje w Odoo PDF oferty, wgrywa go do panelu Signaturit i czeka; gdy klient podpisze, podpisany PDF trafia do skrzynki jednej osoby; ta osoba wgrywa go z powrotem do Odoo, jeśli o tym pamięta. Objawy są zawsze te same: nikt nie wie, czy klient otworzył dokument, podpisany PDF ląduje na czyimś pulpicie, a gdy potrzebny jest dowód (dokument dowodowy, audit trail), nie leży obok faktury, czyli tam, gdzie każdy by go szukał.

Najpierw wymóg, który dotyczy wszystkich trzech dróg tak samo: Twój plan Signaturit musi obejmować dostęp do API. Uwierzytelnianie odbywa się tokenem Bearer pobieranym z panelu, a sandbox i produkcja to dwa osobne rekordy z dwoma różnymi tokenami. Signaturit nie publikuje jawnie, które plany obejmują ten dostęp, więc potwierdź to u nich, zanim cokolwiek zaprojektujesz. Bez tokenu nie ma ani Zapa, ani n8n, ani modułu.

Trzy sposoby połączenia i kiedy wystarczy Zapier

Aplikacja Signaturit w Zapier udostępnia obecnie jeden trigger („New Signed Document”, czyli „dokument został podpisany”) i pięć akcji: utworzenie wniosku o podpis, utworzenie go z szablonu, anulowanie, wysłanie przypomnienia oraz utworzenie certyfikowanego e-maila. Aplikacja Odoo hostowanego we własnym zakresie udostępnia z kolei ogólne triggery i akcje na rekordach (utworzenie rekordu, leada, zadania…). To cały dostępny materiał.

Kiedy wystarczy Zapier (i możesz przestać czytać)

Jeśli wysyłasz jeden typ dokumentu, kilka miesięcznie, i potrzebujesz tylko, by po podpisaniu powstało zadanie lub przyszło powiadomienie na czacie, zbuduj Zap i nie zastanawiaj się dłużej. Wystarczy też wtedy, gdy dokument nie powstaje w Odoo (NDA przygotowane w panelu Signaturit). Zasada jest taka: jeśli status podpisu nie zmienia żadnej decyzji w ERP, ERP nie musi go znać.

Jaki dokument pochodzi z jakiego modelu Odoo

To część, której ogólny krok „utwórz rekord” nie potrafi wykonać: nie umie wyrenderować raportu QWeb zamówienia sprzedaży. Każdy model wymaga trzech własnych elementów: tytułu, który zobaczy podpisujący, domyślnego odbiorcy i sposobu generowania PDF. W zbudowanym przez nas konektorze każdy mostek rozwiązuje dokładnie te trzy kwestie.

• Oferta i zamówienie sprzedaży (sale.order): standardowy raport zamówienia sprzedaży, z klientem jako podpisującym.
• Faktura (account.move) i zamówienie zakupu (purchase.order), do akceptacji i potwierdzeń dostawcy.
• Dokument dostawy (stock.picking): raport dokumentu dostawy, który po podpisaniu służy jako dowód dostawy.
• Umowa o pracę: hr.contract w Odoo 17 i 18 oraz hr.version w Odoo 19, gdzie moduł HR został przebudowany. Taki szczegół wymusza utrzymywanie trzech gałęzi kodu, a nie jednej.
• Oferta dla kandydata (hr.applicant), szansa w CRM (crm.lead), zgłoszenie (helpdesk.ticket) oraz projekt i zadanie, do akceptacji wykonanej pracy.

Pełny cykl statusów, czyli miejsce, w którym wszystko inne się wykłada

API v3 Signaturit raportuje dla każdego dokumentu osiem statusów: in_queue, ready, signing, completed, expired, canceled, declined i error. Jego zdarzenia webhooka są jeszcze bardziej szczegółowe: e-mail dostarczony, e-mail odrzucony, dokument otwarty, dokument podpisany, dodano dokument tożsamości, przedłużono termin ważności, wygenerowano audit trail…

W Odoo musi to zostać zamienione na dwie różne rzeczy. Pierwsza: sam wniosek, z własnym cyklem (szkic, wysłany, w toku, zakończony, odrzucony, wygasły, anulowany, błąd). Druga: pole w dokumencie źródłowym, aby handlowiec otwierający ofertę widział status, nie wychodząc z oferty. W naszym konektorze to pole ma siedem wartości: niewysłany, oczekuje na podpis, podpisany, odrzucony, wygasły, anulowany i błąd.

Przy kilku podpisujących status trzeba wyprowadzić z całości: wszyscy zakończyli, wniosek zakończony; jeden odrzuca, wniosek odrzucony; część podpisała, a część nie, w toku. Jest też zabezpieczenie, którego uczysz się tylko na błędach: wniosek anulowany ręcznie nigdy nie może zostać nadpisany przez późniejsze zdarzenie, bo Signaturit może zgłosić error dla dokumentu we wniosku, który już anulowałeś. Bez tego celowe anulowanie samo zamienia się w niewyjaśniony błąd.

Ostatni element: trzy złe statusy końcowe (odrzucony, wygasły i błąd) nie mogą kończyć się samą zmianą koloru. W konektorze generują oczekującą aktywność dla osoby, która utworzyła wniosek, z poleceniem, by zdecydowała, czy wysłać ponownie, przedłużyć termin czy zastąpić dokument. Odrzucenie, którego nikt nie sprawdza, jest dokładnie tym samym co niewiedza o nim.

Ponowienia i błędy: dlaczego zaginiony webhook jest gorszy niż widoczny błąd

Widoczny błąd Cię zatrzymuje. Zaginiony webhook sprawia, że wierzysz, iż dokument nadal czeka, choć jest podpisany od kilku dni: albo odwrotnie. Druga sytuacja jest znacznie droższa, bo nikt jej nie szuka.

Ponowienia muszą być asymetryczne. W konektorze każde wywołanie ma domyślnie maksymalny czas oczekiwania 30 sekund, z możliwością konfiguracji. Odczyt (GET) jest ponawiany do dwóch razy, ze wzrastającym odstępem, przy odpowiedzi 429, 500, 502, 503 lub 504. Zapis (POST, PATCH, DELETE) nie jest ponawiany nigdy: ponowienie tworzenia, które nie jest idempotentne, oznacza wysłanie tej samej umowy dwa razy temu samemu podpisującemu. Lepszy widoczny błąd niż cichy duplikat. Jest też reguła, której zwykle brakuje: przekierowanie z API traktuje się jako błąd krytyczny i nigdy się za nim nie podąża, bo podążanie z nagłówkiem autoryzacji to przekazanie Twojego tokenu pod adres, który wskaże Location.

Webhook nie jest prawdą: jest dzwonkiem. Signaturit nie podpisuje kryptograficznie swoich webhooków (nie ma HMAC), a jego dokumentacja nie opisuje żadnej polityki automatycznego ponawiania; oferuje natomiast endpoint do ręcznego ponownego wysłania zdarzenia. Mając to na stole, przychodzące zdarzenie w konektorze jest uwierzytelniane tokenem przypisanym do konta, umieszczonym w samym adresie URL, opcjonalnie ograniczane do publikowanego przez Signaturit adresu IP źródłowego (jednego, tego samego w sandboxie i na produkcji), rejestrowane z kluczem deduplikacji SHA-256 skanonizowanego JSON-a, a dopiero potem (i tylko wtedy) ponownie odpytywane jest uwierzytelnione API. Zduplikowane dostarczenie zwraca 200 i nie jest przetwarzane dwa razy.

A jeśli zdarzenie nigdy nie dotrze, jest siatka bezpieczeństwa: cron uruchamiany co godzinę przegląda do 200 oczekujących wniosków i odpytuje je ponownie. Ta linijka to prawdziwa różnica względem Zapa. Zap zależy od webhooka; jeśli webhook zaginie, nie ma nic więcej.

Załącznik, który wraca: gdzie jest zapisany, pod jaką nazwą i z jakim audytem

Gdy wniosek osiąga status „zakończony”, wracają dwa pliki, nie jeden. Podpisany PDF zapisywany jest jako <nombre>.signed.pdf, a dokument dowodowy jako <nombre>.audit_trail.pdf, oba jako załączniki do rekordu wniosku, który z kolei wskazuje ofertę, fakturę lub dokument dostawy, z którego powstał. Żaden z nich nie ląduje w niczyjej skrzynce.

Szczegół, który pojawia się dopiero na produkcji: dokument dowodowy nie zawsze jest gotowy w chwili podpisania dokumentu. Signaturit generuje go osobno i wysyła własne zdarzenie, gdy jest dostępny. Jeśli pobranie się nie powiedzie, nie wolno zostawiać luki: trzeba jawnie zlecić jego wygenerowanie i pobrać go w kolejnym cyklu. Konektor, który pobiera podpisany PDF i zapomina o śladzie, zostawia Cię z połową dowodu. A jeśli poprosiłeś podpisującego o dosłanie dokumentacji (dowód osobisty, potwierdzenie adresu), te pliki są pobierane osobno, w ZIP-ie, do tego samego rekordu.

Na co zwrócić uwagę przed wyborem podejścia

1. Ile typów dokumentów wysyłasz do podpisu? Jeden: Zap. Cztery lub więcej, każdy z własnym PDF i odbiorcą: utrzymanie czterech Zapów kosztuje już więcej niż moduł.
2. Czy status podpisu zmienia jakąś decyzję w Odoo? Jeśli po podpisie trzeba wystawić fakturę, zaplanować coś lub zatrudnić kogoś, ERP potrzebuje statusu. Jeśli trzeba tylko kogoś powiadomić, nie.
3. Czy potrzebujesz zapisanego dokumentu dowodowego? Jeśli musisz go okazać podczas kontroli lub w sporze, lepiej, by leżał obok faktury.
4. Co się stanie, jeśli nikt nie zajrzy do panelu przez dwa tygodnie? Zapytaj, u kogo pojawi się zadanie, gdy umowa wygaśnie niepodpisana. Jeśli odpowiedź brzmi „u nikogo”, nie masz jeszcze integracji.
5. Ile wersji Odoo musisz utrzymywać? Zap nie zależy od wersji; moduł tak, a przejście z hr.contract na hr.version to realny koszt tego faktu.
6. Czy Twój plan Signaturit ma API? Bez tokenu nie działa żadna z trzech opcji. Sprawdź to przed wszystkim innym.

Skąd to wszystko pochodzi

Zbudowaliśmy siedem modułów na tej integracji: rdzeń, który obsługuje konta, wnioski, odbiorców, zdarzenia i archiwizację, oraz sześć mostków dla CRM, punktu pomocy, HR, projektów, rekrutacji i magazynu. W sumie 270 testów automatycznych w gałęzi Odoo 19, 262 w gałęzi 18 i 266 w gałęzi 17: ten sam kod jest utrzymywany jednocześnie dla trzech wersji.

Żadna z decyzji w tym artykule nie wynika z czytania dokumentacji. Wynikają z kolejnych rund QA na prawdziwym konektorze: w jednej rundzie poprawiono 23 błędy znalezione podczas testów na żywo i 5 kolejnych z audytu przeciwnika względem dokumentacji API; w następnej jeszcze 17. Dziennik zmian modułu wylicza je jeden po drugim, z datami. Automatycznie generowana karta „produkt A × produkt B” nie ma żadnej z tych blizn, bo nikt jej nigdy nie używał.

Przydatne linki w FlexigoTech

Najczęściej zadawane pytania

Co robimy w tym zakresie