Podpis elektroniczny API: umowy do podpisu prosto z Twojego systemu

1. Raz, przy wdrożeniu: generujesz token w panelu (sekcja API i integracje) i rejestrujesz adres webhooka, zapisując jego sekret.
2. Wysyłka: zapytanie POST /documents z plikiem PDF i listą sygnatariuszy. Dokument domyślnie od razu idzie do podpisu. Możesz też utworzyć go z polem send=false i wysłać później przez POST /documents/{uuid}/send.
3. Zdarzenia: dostajesz powiadomienia o kolejnych krokach, a po ostatnim podpisie zdarzenie document.completed.
4. Odbiór: GET /documents/{uuid}/pdf zwraca podpisany plik, a /audyt ślad audytowy jako dane, razem z wynikiem sprawdzenia łańcucha skrótów.

Sygnatariusz nie widzi Twojej integracji. Dostaje e-mail z linkiem, podpisuje w przeglądarce na komputerze lub telefonie, bez konta, tak samo jak przy dokumentach wysłanych z panelu.

Każde zapytanie niesie token osobisty w nagłówku Authorization w postaci Bearer. Token tworzysz i unieważniasz w panelu. Pokazujemy go tylko raz, przy utworzeniu. Działa wyłącznie na koncie, na którym powstał, i widzi dokładnie te dokumenty, które widzi to konto w przeglądarce. Adres bazowy to https://podpiszmy.pl/api/v1, a wersja w adresie chroni działającą integrację przed zmianami w kolejnych wydaniach.

API i webhooki działają w planach Business i Team. Konto bez takiego planu dostaje kod 402 z nazwą wymaganego planu i adresem cennika. Limity liczymy na konto, nie na adres IP: 120 zapytań odczytu i 20 zapytań zapisu na minutę (tworzenie dokumentów, wysyłka, anulowanie, przypomnienia, zmiany webhooków). Po przekroczeniu dostajesz kod 429 z nagłówkiem Retry-After.

Przy tworzeniu dokumentu podajesz plik PDF (do 6 MB), tytuł, opcjonalną wiadomość, tryb podpisywania (po kolei albo równolegle) i od jednego do piętnastu sygnatariuszy z imieniem i adresem e-mail. Dla wybranych osób możesz włączyć weryfikację tożsamości polem require_id_check. Podpisany plik powstaje w chwili ostatniego podpisu: wcześniej adres /pdf odpowiada kodem 409 i podaje, ilu podpisów brakuje.

Zamiast odpytywać API w pętli, rejestrujesz publiczny adres https, na który wysyłamy zdarzenia metodą POST w formacie JSON. Dostępne zdarzenia to: document.sent, document.viewed, document.signed, document.rejected, document.expired, document.cancelled i document.completed. Każde niesie adresy pdf_url i audit_url. Przy rejestracji możesz zaznaczyć, żeby do document.completed dołączać podpisany plik w base64 (pliki do 3 MB), razem z sumą SHA-256 do porównania ze śladem audytowym.

Nagłówek X-Podpiszmy-Signature zawiera HMAC-SHA256 policzony z surowego ciała zapytania i Twojego sekretu. Licz go przed parsowaniem JSON i porównuj funkcją odporną na pomiar czasu; dokumentacja ma gotowe przykłady w PHP i Pythonie. Gdy Twój serwer nie odpowie kodem 2xx, ponawiamy dostarczenie, łącznie pięć podejść z rosnącymi odstępami. Nagłówek X-Podpiszmy-Delivery jest ten sam we wszystkich podejściach, więc łatwo odsiać duplikaty.

Nie każdy system umie dołożyć nagłówek z tokenem albo wysłać plik PDF. Dla CRM-ów, formularzy oraz narzędzi takich jak Zapier, Make i n8n przygotowaliśmy wyzwalacz. Zapisujesz umowę jako szablon w panelu, tworzysz wyzwalacz i dostajesz jeden adres. Twoje narzędzie wysyła pod niego zapytanie POST z imieniem i adresem e-mail osoby podpisującej, a my wysyłamy jej umowę z szablonu. Opcjonalnie podajesz tytuł, wiadomość albo listę do 15 sygnatariuszy w kolejności podpisywania.

Adres wyzwalacza jest sekretem: pokazujemy go raz, przechowujemy tylko jego skrót, a w panelu wyłączysz go jednym kliknięciem. Treść PDF z szablonu jest dla wszystkich taka sama, więc wyzwalacz nadaje się do regulaminów, zgód i umów standardowych. O tym, dlaczego nie jest to generator umów, piszemy na stronie generator umów online.

Dokument wysłany przez API ma tę samą moc co wysłany z panelu. Domyślnie to zwykły podpis elektroniczny. Gdy każdy sygnatariusz przejdzie silną identyfikację, dokument dostaje poziom podpisu zaawansowanego, pieczętowany certyfikatem platformy. API nie służy do umów, dla których prawo wymaga formy pisemnej pod rygorem nieważności albo aktu notarialnego: tam potrzebny jest podpis odręczny, kwalifikowany albo notariusz. Szczegóły są na stronie moc prawna.

Token widzi tylko dokumenty swojego konta, a o cudzy dokument API odpowiada kodem 404, żeby nie potwierdzać jego istnienia. Jak chronimy dane i pliki, opisujemy na stronie bezpieczeństwo, a autentyczność podpisanego PDF każdy sprawdzi w walidatorze.