Logo PDFHQ

Dokumenty

DokumentacjaPodpisywanie

Interfejs API żądań podpisu elektronicznego

Twórz i edytuj wersjonowane wersje robocze podpisów, umieszczaj i sprawdzaj poprawność pól przypisanych do nadawcy, wysyłaj jawne żądania do piaskownicy i pobieraj podpisane artefakty.

Klucze API po stronie serwera Podpisane przesyłanie danych do magazynu

Cykl życia żądania podpisu — najpierw piaskownica#

PDFHQ eSign obsługuje niezależną od dostawcy kopertę: prześlij i zweryfikuj jeden plik PDF za pomocą POST /v1/documents/uploads, a następnie utwórz szkic żądania podpisu. Szkice mają własną tożsamość, sygnatariuszy i status niezależnie od zadań konwersji PDF.

Aktualna wersja: Tylko tryb testowy Dropbox Sign. Dokumenty testowe są opatrzone znakiem wodnym i nie są prawnie wiążące. Dostawca wysyła własne wiadomości e-mail dla osób podpisujących. Żądania podpisu na żywo, korporacyjne połączenia OAuth i taryfy produkcyjne nie są włączone.

Utwórz wersję roboczą podpisu elektronicznego
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"upload_id":"VERIFIED_UPLOAD_UUID","provider":"managed","title":"Mutual NDA","subject":"Please review and sign","message":"Please sign this agreement.","signers":[{"name":"Alice Example","email":"alice@example.com","order":0},{"name":"Bob Example","email":"bob@example.com","order":1}]}'

Przygotuj dokładne pola sygnatariuszy i wersje robocze#

Klienci Sandbox mogą umieszczać pola podpisu, inicjałów i daty podpisania na zapieczętowanym, pionowym, nieprzyciętym dokumencie PDF z listem amerykańskim. Współrzędne prostokąta publicznego są normalizowane od 0 do 1 względem lewego górnego rogu strony; numer strony zaczyna się od 1. Każdy podpisujący musi otrzymać wymagane pole podpisu. Odrzucaj nakładające się, brakujące lub wykraczające poza zakres miejsca docelowe. W przypadku wszystkich innych rozmiarów stron pomiń fields aby móc korzystać z dołączonej strony podpisu dostawcy podczas sprawdzania wsparcia.

Utwórz ustawioną wersję roboczą z dwoma sygnatariuszami
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Idempotency-Key: sample-signing-draft-001' \
  -H 'Content-Type: application/json' \
  -d '{"upload_id":"VERIFIED_UPLOAD_UUID","provider":"managed","title":"NDA", "subject":"Sign NDA","message":"Please review and sign","signers":[{"name":"Example One","email":"first@example.test","order":0},{"name":"Example Two","email":"second@example.test","order":1}],"fields":[{"field_id":"first_sig","signer_index":0,"type":"signature","page":1,"rect":{"x":0.10,"y":0.72,"width":0.30,"height":0.08},"required":true},{"field_id":"second_sig","signer_index":1,"type":"signature","page":1,"rect":{"x":0.55,"y":0.72,"width":0.30,"height":0.08},"required":true}]}'

Kreacja jest idempotentna z opcją Idempotency-Key. Ten sam klucz i te same zapieczętowane dane dokumentu/projektu zwracają istniejącą wersję roboczą; inny ładunek zwraca 409. Wersja robocza może być edytowana tylko przed wysyłką przez PATCH /v1/esign/envelopes/ENVELOPE_UUID z pełnym zestawem pól zastępczych i If-Match: 1 z jego draft_version. Zmiany zwiększają wersję i podsumowanie. Pola pozostają niezmienne po wysłaniu.

Przeprowadź inspekcję dokładnego układu źródła i pola
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/validate' \
  -H 'x-api-key: YOUR_API_KEY'

Ta inspekcja wstępna porównuje wymiary i rotację strony z rzeczywistymi zapieczętowanymi bajtami, a nie z metadanymi przeglądarki. Jest ograniczony szybkością i przeznaczony tylko do odczytu. Przepływający podgląd lokalny nie potwierdza idealnego rozmieszczenia Dropbox Sign; przejrzyj faktyczną ceremonię podpisywania testów przed aktywacją produkcji.

Wysyłka z wyraźnym potwierdzeniem testowym#

cURL
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/send' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"confirm_test_mode":true,"draft_version":1}'

# Poll the envelope for status; never auto-retry an uncertain send.
curl 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID' -H 'x-api-key: YOUR_API_KEY'

Wysyłka dostawcy jest chroniona przez jawną konfigurację po stronie serwera i wyłączona w środowisku produkcyjnym. Żądania, które mogły dotrzeć do Dropbox, ale utraciły odpowiedź, zostaną wprowadzone needs_reconciliation i nie można ślepo żywić urazy.

Przypomnienia i anulowanie piaskownicy — podpisane wywołania zwrotne są miarodajne#

Po wysłaniu żądania testowego nadawca może wysłać jedno testowe przypomnienie na każdego odbiorcę w ciągu 24 godzin. Anuluj żądania, korzystając z interfejsu API dostawcy asynchronicznie; HTTP 202 oznacza jedynie, że zażądano anulowania, a nie, że odbiorcy nie mogą już podpisywać. Żadna operacja nie jest przepływem pracy związanym z produkcyjnym podpisem elektronicznym.

Poproś o jedno przypomnienie dla odbiorcy
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/remind'   -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"recipient_index":0,"confirm_test_mode":true}'

curl 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/reminders'   -H 'x-api-key: YOUR_API_KEY'

Potwierdzenia przypomnień informują o przyjęciu/odrzuceniu/niepewności, a nie o faktycznym dostarczeniu wiadomości e-mail. Próba przypomnienia jest trwale rejestrowana przed skontaktowaniem się z usługodawcą; jeśli wynik sieci jest niepewny, nie próbuj ponownie. Dostęp do potwierdzeń mają tylko osoby dzwoniące w ramach oryginalnego konta/projektu API; e-maile osób podpisujących są wykluczone.

Poproś o anulowanie asynchronii; sprawdzić stan
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/void'   -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"reason":"agreement_withdrawn","confirm_test_mode":true}'

curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/sync'   -H 'x-api-key: YOUR_API_KEY'

Anulowanie jest dozwolone wyłącznie w momencie wysłania, przeglądania lub oczekiwania na dostawę. Częściowo podpisanych i wypełnionych żądań nie można anulować z poziomu PDFHQ. Dostawca HTTP 200 nie oznacza, że ​​koperta została unieważniona. Poczekaj na uwierzytelnienie signature_request_canceled oddzwonienie lub potwierdzony status dostawcy. Odpowiedzi typu cancel_uncertain wymagać zbadania przez operatora; nigdy więcej nie poddawaj się na ślepo.

Ten interfejs API nie gwarantuje usunięcia zaproszeń przesłanych wcześniej pocztą elektroniczną, wykonalności prawnej, anulowania z mocą wsteczną istniejącego podpisu, automatycznych zwrotów kosztów ani umowy SLA dla dostawcy klasy produkcyjnej. Przyszły tryb na żywo wymaga centralnego rozliczeń opartych na kredytach, weryfikacji tożsamości, przeglądu umowy i pełnej akceptacji dostawcy usług przejściowych.

Odbiór podpisanego dokumentu#

Po zweryfikowaniu signature_request_downloadable oddzwonienie, użyj POST /v1/esign/envelopes/ENVELOPE_UUID/archive . PDFHQ pobiera ukończony plik PDF z Dropbox do prywatnej przestrzeni nazw magazynu HQ. Następnie pobierz GET /v1/esign/envelopes/ENVELOPE_UUID/download-url dla krótkotrwałego wyjściowego adresu URL o zasięgu konta.

Źródłowy plik PDF nigdy nie jest wysyłany za pośrednictwem adresu URL określonego przez klienta. Przesyłamy zweryfikowane, zapieczętowane bajty plików do stałego hosta API Dropbox. Strony podpisujące hostowane przez dostawcę i dowody kontroli dostawcy są zarządzane przez wybraną usługę.

Bezpieczeństwo webhooka i zmiany stanu →
Logo PDFHQ

Narzędzia PDF i inteligencja dokumentów. Przygotuj, zrozum i pracuj ze swoimi dokumentami.

© 2026 PDFHQ. Wszystkie prawa zastrzeżone.