Koperty i odbiorcy

Koperta to jedna umowa w drodze do podpisania: wersja szablonu wyrenderowana z Twoimi zmiennymi, odbiorcy, którzy wykonują na niej działania, oraz dowody wszystkiego, co się z nią dzieje. Utworzysz ją za pomocą POST /v1/envelopes.

Tworzenie koperty

Pole	Typ	Uwagi
template	tpl_…	Wymagane
version	liczba lub "latest"	Domyślnie latest; ustalana i przypinana w chwili utworzenia. Musi być opublikowana
variables	obiekt	Walidowane względem JSON Schema danej wersji
recipients	tablica	Jeden na rolę (role, name, email; opcjonalnie externalUserId, verification, fields do wstępnego wypełnienia według identyfikatora pola, order do zmiany kolejności podpisywania)
subject, message	ciąg znaków	Używane w wiadomościach e-mail z prośbą o podpis i wyświetlane na stronie podpisywania
delivery	email · embedded · none	Domyślnie email
expiresAt	RFC 3339	Musi wskazywać przyszłość; w tym momencie koperta wygasa, a linki do podpisu i linki obserwatorów przestają działać
cc	tablica	Dodatkowi odbiorcy CC (name, email) poza rolami CC szablonu; maksymalnie 50
viewers	tablica	Osoby, które śledzą kopertę, nie podpisując jej (name, email, opcjonalnie notifyOnSignature); liczba na kopertę zależy od planu
viewerDocumentAccess	wartość logiczna	Pozwala obserwatorom otworzyć dokument na stronie statusu. Domyślnie false (tylko status); od planu Team
reminders	obiekt	{ "enabled": false } wyłącza przypomnienia; { "enabled": true, "intervalHours": 24 } zmienia odstęp (od 1 do 720)
externalId	ciąg znaków	Twój własny identyfikator, do 200 znaków
dedupeOn	"external_id"	Zwraca istniejącą kopertę z tym externalId zamiast tworzyć kolejną
metadata	obiekt z ciągami znaków	Do 500 znaków na wartość; zwracane w kopercie i w webhookach

Każdy odbiorca musi mieć rolę z danej wersji; każda rola inna niż CC musi mieć dokładnie jednego odbiorcę. Błędy są zgłaszane łącznie, ze wskaźnikami takimi jak /recipients/1/role lub /recipients/0/fields/start_date.

Odpowiedzi: 201 z kopertą i nagłówkiem Location; 200 z istniejącą kopertą i x-deduplicated: true, gdy zadziałało dedupeOn; 200 z podsumowaniem przebiegu próbnego dla ?dry_run=true; 402, gdy przestrzeń robocza w planie Free wykorzystała zawarte w nim koperty; 403 plan-upgrade-required, gdy liczba obserwatorów przekracza limit planu lub viewerDocumentAccess nie jest dostępne w planie (Plany i limity). Przebiegi próbne również sprawdzają limity planu.

Każde pole dodane po pierwszym wydaniu jest opcjonalne: żądanie bez niego działa dokładnie tak jak wcześniej.

Opcje przy wysyłce

Szablon określa, kto podpisuje i w jakiej kolejności. Dla pojedynczej koperty możesz to zmienić bez modyfikowania szablonu:

{
  "template": "tpl_9fK2mQ7xLp",
  "variables": { "client": { "name": "Jane Doe" } },
  "recipients": [
    { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev", "order": 2 },
    { "role": "company", "name": "Sam Lee", "email": "sam@bonafide.dev", "order": 1 },
    { "role": "witness", "name": "Kim Park", "email": "kim@acme.dev", "order": 1 }
  ],
  "cc": [{ "name": "Legal", "email": "legal@acme.dev" }],
  "viewers": [{ "name": "Alex Chen", "email": "alex@acme.dev", "notifyOnSignature": true }],
  "reminders": { "enabled": true, "intervalHours": 48 },
  "expiresAt": "2026-11-30T23:59:59Z"
}

• Kolejność: recipients[].order to krok, w którym odbiorca podpisuje; odbiorcy z tym samym numerem podpisują jednocześnie. Bez tego pola obowiązuje order roli z szablonu. Wartości kolejności to dodatnie liczby całkowite; ról CC nie można ustawiać w kolejności; każda rola nadal potrzebuje swojego odbiorcy (dzięki temu pola szablonu zachowują osobę podpisującą); co najmniej jeden odbiorca musi podpisać. Zdarzenie envelope.created zapisuje routingOverridden: true.
• CC: dodatkowi odbiorcy CC dostają wiadomość z zakończonym dokumentem i nigdy nie podpisują. Pojawiają się w recipients z kind: "cc" i rolą _cc.
• Przypomnienia: osoba, na którą przypada kolej, otrzymuje przypomnienie co intervalHours (domyślnie wartość REMINDER_INTERVAL_HOURS wdrożenia, czyli 72), najwyżej trzy razy; enabled: false wyłącza je całkowicie. Przypomnienia dotyczą dostarczania email.
• Uwierzytelnianie osoby podpisującej ustawia się dla każdego odbiorcy: verification nadpisuje metodę roli. Obecnie dostępne są none (sam unikalny link do podpisu, domyślnie dla ról, które nie ustawiają metody) i email_otp (link plus kod wysłany e-mailem); passkey i id_check są odrzucane jako jeszcze niedostępne. Zobacz weryfikację osoby podpisującej.
• Język: locale u odbiorcy, odbiorcy CC lub obserwatora (albo w kopercie – dla wszystkich bez własnego ustawienia) określa język jego strony podpisywania i wiadomości e-mail; to jeden z 50 języków podpisywania. Bez tego ustawienia strona podpisywania dopasowuje się do przeglądarki, a wiadomości e-mail są po angielsku.

Ekran wysyłki w panelu oferuje te same opcje: przesuwanie kroków wcześniej lub później, zaznaczenie Podpisz w tym samym czasie, dodawanie odbiorców CC i obserwatorów, wybór uwierzytelniania (Tylko link e-mail lub Link e-mail + kod) i języka dla każdej osoby podpisującej oraz ustawienie daty wygaśnięcia i harmonogramu przypomnień.

Dostarczanie

• email: każdy odbiorca otrzymuje e-mailem link do hostowanej strony podpisywania, gdy nadejdzie jego kolej. Odbiorcy, którzy nie podpisali, co kilka dni dostają przypomnienie (maksymalnie trzy), a po zakończeniu koperty wszyscy dostają wiadomość e-mail.
• embedded: brak wiadomości e-mail do osób podpisujących. Utwórz sesję podpisywania, gdy osoba podpisująca jest w Twoim produkcie. Obserwatorzy nadal otrzymują e-mailem link do statusu.
• none: żadnych wiadomości e-mail (także do obserwatorów); używaj, gdy dostarczasz linki samodzielnie (sesje hostowane).

POST /v1/envelopes/{id}/recipients/{recipient}/resend wysyła e-mailem nowy link do odbiorcy, na którego przypada kolej (najwyżej raz na minutę).

Cykl życia

          ┌──────────── declined (a signer declined)
          │
sent ─────┼──────────── voided   (POST /v1/envelopes/{id}/void)
          │
          ├──────────── expired  (expiresAt passed)
          │
          └──────────── completed ──► seal: pending ──► sealed

status	Znaczenie
rendering	Trwa przygotowywanie
sent	W toku: odbiorcy podpisują w kolejności kierowania
completed	Wszyscy odbiorcy zakończyli. Rozpoczyna się pieczętowanie
declined	Odbiorca odmówił; koperta się kończy
voided	Unieważniono ją ({ "reason": "…" }); otwarte sesje podpisywania przestają działać
expired	expiresAt minęło przed zakończeniem

seal śledzi zapieczętowany PDF: not_started, pending (zakończona, w trakcie pieczętowania), sealed lub failed. Pieczętowanie nigdy nie blokuje zakończenia: koperta najpierw zostaje zakończona, a zaraz potem zapieczętowana.

Odbiorcy i kierowanie

{
  "id": "rcp_5Jw0pLs9Xe",
  "role": "client",
  "name": "Jane Doe",
  "email": "jane@acme.dev",
  "order": 1,
  "status": "viewed",
  "verification": "email_otp",
  "completedAt": null
}

status odbiorcy to pending (jeszcze nie jego kolej), sent, viewed, completed lub declined, a kind to rodzaj roli: signer, approver, form_filler lub cc. Kierowanie odbywa się według order (z roli lub z nadpisania przy wysyłce): wszyscy odbiorcy z najniższej niezakończonej pozycji działają równolegle, a kolejna grupa zaczyna, gdy skończą. Odbiorcy CC nigdy nie blokują kierowania.

Obserwatorzy

Obserwator śledzi kopertę, nie podpisując jej: menedżer, asystent prawny, opiekun klienta po stronie klienta. Obserwatorzy nie są odbiorcami. Nie mają roli ani kolejki, nigdy niczego nie blokują ani nie kończą i nigdy nie pojawiają się na liście osób podpisujących w certyfikacie.

• Gdy koperta zostaje wysłana (lub gdy dodasz ich później za pomocą POST /v1/envelopes/{id}/viewers), każdy obserwator dostaje wiadomość e-mail z Twoim brandingiem i linkiem do strony statusu tylko do odczytu: tytuł koperty, nadawca, każdy krok z imionami i nazwiskami odbiorców, rolami, statusem i znacznikami czasu – aktualizowane na bieżąco w miarę podpisywania. Adresy e-mail odbiorców nie są wyświetlane.
• Obserwatorzy otrzymują kolejną wiadomość, gdy koperta zostanie zakończona, odrzucona lub unieważniona, a także po każdym podpisie, jeśli notifyOnSignature ma wartość true (domyślnie wyłączone).
• Dokument jest na stronie tylko wtedy, gdy ustawisz viewerDocumentAccess: true (od planu Team): oryginał w trakcie procesu, zapieczętowany PDF po zapieczętowaniu. W przeciwnym razie obserwatorzy widzą tylko status.
• DELETE /v1/envelopes/{id}/viewers/{viewer} odwołuje obserwatora: każdy wysłany mu link natychmiast przestaje działać.
• Linki są osobistymi adresami URL dającymi dostęp. Przechowywany jest wyłącznie skrót SHA-256 tokenu każdego linku. Link działa do wygaśnięcia koperty (najwyżej 90 dni), przez 30 dni po zakończeniu koperty i nigdy po odwołaniu obserwatora.
• Dodanie, otwarcie (pierwsze wyświetlenie strony i dokumentu) oraz odwołanie są zapisywane w ścieżce audytu jako viewer.added, viewer.viewed, viewer.document_viewed i viewer.revoked, a więc także w certyfikacie.

Odpowiedzi dotyczące pojedynczej koperty (utworzenie, pobranie, unieważnienie) zawierają ich listę:

{
  "viewers": [
    {
      "id": "vwr_2Hc8sQ1nVt",
      "name": "Alex Chen",
      "email": "alex@acme.dev",
      "notifyOnSignature": true,
      "status": "active",
      "invitedAt": "2026-10-13T13:58:04.512Z",
      "firstViewedAt": "2026-10-13T14:05:41.090Z",
      "lastViewedAt": "2026-10-13T15:12:09.337Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T13:58:04.512Z"
    }
  ],
  "viewerDocumentAccess": false
}

Liczba obserwatorów na kopertę zależy od planu (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform bez limitu); odbiorcy CC nie są wliczani. Odwołani obserwatorzy zwalniają swoje miejsce.

Dokumenty

GET /v1/envelopes/{id}/document?version=… pobiera plik PDF, a jego SHA-256 podaje w x-document-sha256:

version	Plik
original (domyślnie)	Wyrenderowany dokument w postaci wysłanej do podpisu
sealed	Końcowy PDF: wartości spłaszczone, dołączony certyfikat ukończenia, znacznik czasu dokumentu. Po envelope.sealed
certificate	Sam certyfikat ukończenia

documentHash koperty to SHA-256 oryginału, a sealedDocumentHash – SHA-256 zapieczętowanego pliku; to właśnie ich szuka weryfikacja.

Ścieżka audytu

Każde działanie jest zdarzeniem w łańcuchu hashy danej koperty: hash = SHA-256(prevHash ‖ canonical JSON of the event), przy czym pierwszy prevHash to 64 zera. GET /v1/envelopes/{id}/events zwraca zdarzenia i sprawdza łańcuch:

{
  "data": [
    {
      "id": "evt_…",
      "envelope": "env_8Gm2kQ4rT1",
      "seq": 1,
      "type": "envelope.created",
      "createdAt": "2026-10-13T13:58:04.512Z",
      "recipient": null,
      "actor": { "kind": "api_key", "id": "…", "name": null, "email": null },
      "ip": "203.0.113.7",
      "userAgent": null,
      "data": { "template": "tpl_…", "templateVersion": 3, "documentHash": "9f2c…" },
      "hash": "4b1d…",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "chain": { "valid": true, "brokenAt": null }
}

Oprócz typów zdarzeń webhooków ścieżka zawiera wpisy występujące tylko w audycie, takie jak session.created, recipient.verified, recipient.reminded oraz zdarzenia obserwatorów (rodzaj aktora viewer, gdy obserwator otwiera swoją stronę).

Do wyświetlania statusu na żywo w interfejsie służy GET /v1/envelopes/{id}/events/stream – strumień zdarzeń wysyłanych przez serwer (SSE): nazwa zdarzenia w każdej ramce to type zdarzenia, a jej identyfikator to seq; aby wznowić, połącz się ponownie z Last-Event-ID.

Listy

GET /v1/envelopes filtruje według status, seal, template i q (wyszukiwanie pełnotekstowe w imionach i nazwiskach oraz adresach e-mail odbiorców, externalId i identyfikatorze koperty). Jak każda lista jest stronicowana kursorem:

{ "data": [ … ], "hasMore": true, "nextCursor": "…" }

Przekaż nextCursor z powrotem jako cursor; limit wynosi od 1 do 100 (domyślnie 20).

Wskazówka

Przechowuj id koperty (lub używaj externalId) po swojej stronie i reaguj na webhooki zamiast odpytywać API.