Zarflar ve alıcılar

Zarf, imzalanma yolundaki tek bir sözleşmedir: değişkenlerinizle oluşturulmuş bir şablon sürümü, üzerinde işlem yapan alıcılar ve gerçekleşen her şeyin kanıtı. POST /v1/envelopes ile bir zarf oluşturun.

Zarf oluşturma

Alan	Tür	Notlar
`template`	`tpl_…`	Zorunlu
`version`	sayı veya `"latest"`	Varsayılan `latest`; oluşturma anında çözümlenir ve sabitlenir. Yayımlanmış olmalıdır
`variables`	nesne	Sürümün JSON Schema’sına göre doğrulanır
`recipients`	dizi	Her rol için bir tane (`role`, `name`, `email`; isteğe bağlı `externalUserId`, `verification`, alan kimliğine göre ön doldurma için `fields`, imzalama sırasını değiştirmek için `order`)
`subject`, `message`	dize	İmzalama e-postalarında kullanılır ve imzalama sayfasında gösterilir
`delivery`	`email` · `embedded` · `none`	Varsayılan `email`
`expiresAt`	RFC 3339	Gelecekte bir zaman olmalıdır; zarfın süresi o anda dolar ve imzalama ile izleyici bağlantıları çalışmaz hâle gelir
`cc`	dizi	Şablonun CC rollerine ek CC alıcıları (`name`, `email`); en fazla 50
`viewers`	dizi	İmzalamadan zarfı takip eden kişiler (`name`, `email`, isteğe bağlı `notifyOnSignature`); zarf başına sayısı plana göre sınırlıdır
`viewerDocumentAccess`	boolean	İzleyicilerin durum sayfalarında belgeyi açmasına izin verir. Varsayılan `false` (yalnızca durum); Team planı ve üstü
`reminders`	nesne	`{ "enabled": false }` hatırlatıcıları kapatır; `{ "enabled": true, "intervalHours": 24 }` aralığı değiştirir (1 ila 720)
`externalId`	dize	Kendi kimliğiniz, en fazla 200 karakter
`dedupeOn`	`"external_id"`	Yeni bir zarf oluşturmak yerine bu `externalId` değerine sahip mevcut zarfı döndürür
`metadata`	dizelerden oluşan nesne	Değer başına en fazla 500 karakter; zarfta ve webhook’larda döndürülür

Her alıcının sürümde tanımlı bir rolü olmalıdır; CC olmayan her rolün tam olarak bir alıcısı olmalıdır. Hatalar /recipients/1/role veya /recipients/0/fields/start_date gibi işaretçilerle birlikte topluca bildirilir.

Yanıtlar: zarf ve bir Location başlığıyla 201; dedupeOn eşleştiğinde mevcut zarf ve x-deduplicated: true ile 200; ?dry_run=true için deneme çalıştırması özetiyle 200; bir Free çalışma alanı dahil zarflarını kullandığında 402; izleyiciler planın izin verdiği sayıyı aştığında veya viewerDocumentAccess planda yoksa 403 plan-upgrade-required (Planlar ve limitler). Deneme çalıştırmaları da plan limitlerini kontrol eder.

İlk sürümden sonra eklenen her alan isteğe bağlıdır: bu alanları içermeyen bir istek tam olarak eskisi gibi davranır.

Gönderim anı seçenekleri

Kimin hangi sırayla imzalayacağını şablon belirler. Tek bir zarf için şablona dokunmadan bunu değiştirebilirsiniz:

{
  "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"
}

Sıra: recipients[].order, alıcının imzaladığı adımdır; aynı numaraya sahip alıcılar aynı anda imzalar. Belirtilmezse şablondaki rolün order değeri geçerlidir. Sıralar pozitif tam sayılardır; CC rolleri sıralanamaz; her rolün yine bir alıcısı olmalıdır (böylece şablonun alanları imzacısını korur); en az bir alıcı imzalamalıdır. envelope.created olayı routingOverridden: true kaydeder.
CC: ek CC alıcıları tamamlanan belge e-postasını alır ve hiçbir zaman imzalamaz. recipients içinde kind: "cc" ve _cc rolüyle görünürler.
Hatırlatıcılar: sırası gelen kişiye her intervalHours sürede bir hatırlatma yapılır (varsayılan: dağıtımın REMINDER_INTERVAL_HOURS değeri, 72), en fazla üç kez; enabled: false hiç hatırlatma göndermez. Hatırlatıcılar email teslimatı için geçerlidir.
İmzacı kimlik doğrulaması alıcı bazındadır: verification, rolün yöntemini geçersiz kılar. none (yalnızca benzersiz imzalama bağlantısı; yöntem belirtmeyen roller için varsayılan) ve email_otp (bağlantı artı e-postayla gönderilen kod) bugün kullanılabilir; passkey ve id_check henüz kullanılamadığı için reddedilir. Bkz. imzacı doğrulaması.
Dil: bir alıcı, CC veya izleyici üzerindeki locale (veya kendi değeri olmayan herkes için zarf üzerindeki) imzalama sayfasının ve e-postalarının dilini belirler; 50 imzalama dilinden biri olmalıdır. Belirtilmezse imzalama sayfası tarayıcıyı izler ve e-postalar İngilizce olur.

Paneldeki gönderim ekranı aynı seçenekleri sunar: adımları öne veya arkaya taşıyın, Aynı anda imzala seçeneğini işaretleyin, CC’ler ve izleyiciler ekleyin, her imzacının kimlik doğrulamasını (Yalnızca e-posta bağlantısı veya E-posta bağlantısı + kod) ve dilini seçin, bir son geçerlilik tarihi ve hatırlatma takvimi belirleyin.

Teslimat

email: sırası geldiğinde her alıcıya barındırılan imzalama sayfasının bağlantısı e-postayla gönderilir. İmzalamamış alıcılar birkaç günde bir hatırlatma alır (en fazla üç) ve zarf tamamlandığında herkese e-posta gönderilir.
embedded: imzacılara e-posta gönderilmez. İmzacı ürününüzdeyken bir imzalama oturumu oluşturun. İzleyicilere durum bağlantıları yine e-postayla gönderilir.
none: hiç e-posta gönderilmez (izleyiciler dahil); bağlantıları kendiniz ilettiğinizde (barındırılan oturumlar) kullanın.

POST /v1/envelopes/{id}/recipients/{recipient}/resend, sırası gelmiş bir alıcıya e-postayla yeni bir bağlantı gönderir (dakikada en fazla bir kez).

Yaşam döngüsü

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

`status`	Anlamı
`rendering`	Hazırlanıyor
`sent`	Devam ediyor: alıcılar yönlendirme sırasına göre imzalıyor
`completed`	Tüm alıcılar işlemini bitirdi. Mühürleme başlar
`declined`	Bir alıcı reddetti; zarf sona erer
`voided`	Zarfı siz iptal ettiniz (`{ "reason": "…" }`); açık imzalama oturumları çalışmaz hâle gelir
`expired`	Tamamlanmadan önce `expiresAt` geçti

seal, mühürlü PDF’in durumunu izler: not_started, pending (tamamlandı, mühürleniyor), sealed veya failed. Mühürleme tamamlanmayı hiçbir zaman engellemez: zarf önce tamamlanır ve hemen ardından mühürlenir.

Alıcılar ve yönlendirme

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

Alıcının status değeri pending (henüz sırası gelmedi), sent, viewed, completed veya declined olur; kind ise rolün signer, approver, form_filler veya cc türüdür. Yönlendirme order değerine göre yapılır (rolün değeri veya gönderim anı geçersiz kılması): tamamlanmamış en düşük sıradaki tüm alıcılar paralel olarak işlem yapar ve onlar bitirdiğinde sonraki grup başlar. CC alıcıları yönlendirmeyi hiçbir zaman engellemez.

İzleyiciler

İzleyici, bir zarfı imzalamadan takip eder: bir yönetici, bir hukuk asistanı, müşteri tarafındaki hesap sahibi. İzleyiciler alıcı değildir. Rolleri ve sıraları yoktur, hiçbir şeyi engellemez veya tamamlamaz ve sertifikadaki imzacı listesinde hiçbir zaman yer almazlar.

Zarf gönderildiğinde (veya onları daha sonra POST /v1/envelopes/{id}/viewers ile eklediğinizde) her izleyici, salt okunur bir durum sayfasına bağlantı içeren markalı bir e-posta alır: zarf başlığı, gönderen, her adım ve o adımdaki alıcıların adları, rolleri, durumları ve zaman damgaları; kişiler imzaladıkça canlı olarak güncellenir. Alıcıların e-posta adresleri gösterilmez.
Zarf tamamlandığında, reddedildiğinde veya iptal edildiğinde ve notifyOnSignature true ise (varsayılan kapalı) her imzadan sonra izleyicilere yeniden e-posta gönderilir.
Belge yalnızca viewerDocumentAccess: true ayarladığınızda (Team planı ve üstü) sayfada yer alır: devam ederken orijinali, mühürlendikten sonra mühürlü PDF. Aksi hâlde izleyiciler yalnızca durumu görür.
DELETE /v1/envelopes/{id}/viewers/{viewer} bir izleyicinin erişimini iptal eder: ona gönderilen tüm bağlantılar anında çalışmaz hâle gelir.
Bağlantılar kişiye özel yetki URL’leridir. Her bağlantı belirtecinin yalnızca SHA-256 değeri saklanır. Bir bağlantı, zarfın süresi dolana kadar (en fazla 90 gün) ve zarf bittikten sonra 30 gün boyunca çalışır; izleyicinin erişimi iptal edildiğinde ise hiç çalışmaz.
Ekleme, açma (sayfanın ve belgenin ilk görüntülenmesi) ve iptal etme işlemleri denetim kaydına viewer.added, viewer.viewed, viewer.document_viewed ve viewer.revoked olarak, dolayısıyla sertifikaya da kaydedilir.

Tek zarf yanıtları (oluşturma, getirme, iptal etme) izleyicileri listeler:

{
  "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
}

Zarf başına izleyici sayısı plana bağlıdır (Free 1, Kullandıkça Öde 2, Team 5, Business 20, Platform sınırsız); CC alıcıları sayılmaz. Erişimi iptal edilen izleyiciler yerlerini boşaltır.

Belgeler

GET /v1/envelopes/{id}/document?version=…, SHA-256 değeri x-document-sha256 içinde olacak şekilde bir PDF indirir:

`version`	Dosya
`original` (varsayılan)	İmzaya gönderildiği hâliyle oluşturulan belge
`sealed`	Nihai PDF: değerler düzleştirilmiş, tamamlama sertifikası eklenmiş, belge zaman damgalı. `envelope.sealed` sonrasında
`certificate`	Tek başına tamamlama sertifikası

Zarfın documentHash değeri orijinalin, sealedDocumentHash değeri ise mühürlü dosyanın SHA-256 değeridir; doğrulama bu değerleri sorgular.

Denetim kaydı

Her işlem, zarf başına bir hash zincirindeki bir olaydır: hash = SHA-256(prevHash ‖ canonical JSON of the event); ilk prevHash 64 sıfırdan oluşur. GET /v1/envelopes/{id}/events olayları döndürür ve zinciri kontrol eder:

{
  "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 }
}

Kayıtta webhook olay türlerinin yanı sıra session.created, recipient.verified, recipient.reminded ve izleyici olayları (bir izleyicinin sayfasını açması için aktör türü viewer) gibi yalnızca denetime özgü girdiler de bulunur.

Bir arayüzde canlı durum için GET /v1/envelopes/{id}/events/stream bir server-sent events akışıdır: her çerçevenin olay adı olayın type değeri, kimliği ise seq değeridir; kaldığınız yerden devam etmek için Last-Event-ID ile yeniden bağlanın.

Listeleme

GET /v1/envelopes; status, seal, template ve q (alıcı adları ve e-postaları, externalId ve zarf kimliği üzerinde serbest metin) ile filtreler. Her liste gibi imleç tabanlı sayfalama kullanır:

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

nextCursor değerini cursor olarak geri gönderin; limit 1 ile 100 arasındadır (varsayılan 20).