API ile Çok Belgeli Sözleşme (Zarf)

Bir sözleşmeye birden fazla belge ekleyip (sözleşme, KVKK aydınlatma, açık rıza, ön bilgilendirme, fiyat listesi) hepsini tek zarfta göndermek artık API’den de mümkün. Bu rehber sekiz zarf ucunu curl örnekleriyle anlatır. Panel tarafındaki davranış için Çok Belgeli Sözleşme (Zarf) Gönderme rehberine, kesin istek/yanıt şemaları için api-docs.imzala.org referansına bakın.

Ön koşullar

• API anahtarınızda demands:read (listeleme) ve demands:write (diğer tüm uçlar) yetkisi olmalı. Anahtar X-API-Key başlığıyla gönderilir.
• Zarf uçları, önce bir sözleşme oluşturmanızı bekler. Sözleşmeyi POST /api/v1/demands/upload (dosyadan) ya da POST /api/v1/demands (şablondan) ile oluşturun; dönen id aşağıdaki {demandId}’dir. Oluşturma sırasında davet gönderMEyin; davetler zarf tamamlandıktan sonra dispatch ucuyla gider.
• Bir zarfta en fazla 20 belge ve toplam 300 sayfa bulunabilir.

Tüm örneklerde taban adres https://api-prd.imzala.org/api/v1’dir.

Şablondan zarf: gönderilecek belgeleri seçin

Şablonunuzda birden fazla belge varsa POST /demands ile sözleşme oluştururken hangilerinin gideceğini istek başına seçebilirsiniz.

1. Şablonun belgelerini okuyun:

curl -H "X-API-Key: imz_xxx" \
  https://api-prd.imzala.org/api/v1/templates/{templateId}

Yanıttaki documents listesinde her belgenin id, title, is_required, default_included ve assigned_template_party_ids (bu belgeyi imzalayacak şablon rolleri; parties[].id ile aynı kimlikler) alanları bulunur.

2. Sözleşmeyi oluştururken documents alanını ekleyin:

curl -X POST -H "X-API-Key: imz_xxx" -H "Content-Type: application/json" \
  https://api-prd.imzala.org/api/v1/demands \
  -d '{
    "template_id": "{templateId}",
    "party_mapping": [ ... ],
    "documents": { "exclude": ["{fiyatListesiBelgeId}"] }
  }'

• documents hiç gönderilmezse default_included: true olan belgeler gider.
• include, varsayılan olarak gönderilmeyen bir belgeyi bu istekte ekler; exclude, varsayılan olarak gönderilen bir belgeyi çıkarır.
• Zorunlu (is_required: true) bir belge de çıkarılabilir. Zorunluluk, imzacının belgeyi atlayıp atlayamayacağını belirler; gönderilecek belgeleri seçmekle ilgisi yoktur. Yasal olarak verilmesi gereken bir belgeyi (örneğin ön bilgilendirme formu) başka bir kanaldan vermiyorsanız çıkarmayın; bu belgelerin verilmesi yükümlülüğü sözleşmeyi gönderene aittir.
• Çıkarılan belge bu imza sürecine (zarfa) eklenmez: imzacıya gösterilmez, imzalı PDF’te ve tamamlanma sertifikasında yer almaz, kredi hesaplamasına dahil edilmez (ücretlendirilmez).
• Sonuçta en az bir belge kalmalıdır. Seçim sonucunda eşlediğiniz bir role imzalayacak belge kalmıyorsa istek 409 ile reddedilir (yanıttaki template_party_ids hangi roller olduğunu söyler); seçimi değiştirin ya da o rolü party_mapping’den çıkarın.
• Toplu gönderimde (POST /demands/bulk) seçim satır başınadır: rows[i].documents. options.documents kabul edilmez.

Belge kimlikleri: Belgenin başlığını, türünü ya da sırasını değiştirmek kimliğini değiştirmez. Şablonu panelde kopyaladığınızda ya da bir sözleşmeden yeni şablon oluşturduğunuzda yeni şablonun belgeleri yeni kimlik alır; entegrasyonunuz yeni şablonun kimliklerini yeniden okumalıdır.

Uçlar bir bakışta

Uç	İş	Yetki
GET /demands/{demandId}/documents	Zarftaki belgeleri listele	demands:read
POST /demands/{demandId}/documents	Dosyasız belge kaydı oluştur	demands:write
POST /demands/{demandId}/documents/upload	Dosya yükleyerek belge ekle	demands:write
PUT /demands/{demandId}/documents/order	Belge sırasını değiştir	demands:write
PATCH /demands/{demandId}/documents/{docId}	Belge başlığı / ayarlarını güncelle	demands:write
DELETE /demands/{demandId}/documents/{docId}	Belgeyi sil	demands:write
PUT /demands/{demandId}/documents/{docId}/assignments	Belgeye imzacı ata	demands:write
POST /demands/{demandId}/dispatch	Zarfı gönder (kredi + davetler)	demands:write

1. Belgeleri listeleyin

curl -H "X-API-Key: imz_xxx" \
  https://api-prd.imzala.org/api/v1/demands/{demandId}/documents

Yanıt, order alanına göre sıralı belge listesidir. Her belgede id, title, doc_kind, is_required, signature_required, page_count, assigned_party_ids ve mühür durumu (sealing_status) bulunur. sealing_status, belgenin tamamlandıktan sonra imzala.org’un ürettiği Belge Bütünlük Mührü ile korunup korunmadığını gösterir; bu, Elektronik Mühür Yönetmeliği anlamında nitelikli elektronik mühür değildir. Sözleşmeyi oluştururken yüklediğiniz ilk dosya, zarfın order: 1 belgesi olarak zaten listede yer alır.

2. Dosya yükleyerek belge ekleyin

curl -X POST -H "X-API-Key: imz_xxx" \
  -F "[email protected]" \
  -F "title=KVKK Aydınlatma Metni" \
  -F "doc_kind=KVKK_NOTICE" \
  -F "is_required=true" \
  -F "idempotency_key=siparis-4821-kvkk" \
  https://api-prd.imzala.org/api/v1/demands/{demandId}/documents/upload

• file: Tek dosya. PDF, DOC, DOCX, ODT, RTF, TXT veya görsel kabul edilir; PDF dışındakiler sunucuda dönüştürülür.
• doc_kind: CONTRACT, KVKK_NOTICE, KVKK_CONSENT, PREINFO, PRICE_LIST, OTHER. Verilmezse OTHER varsayılır.
• is_required: Çok parçalı istekte metin olarak gönderilir ("true" / "false"). Varsayılan true.
• idempotency_key: Zorunlu. Aynı sözleşmede aynı anahtarla ikinci istek yeni belge yaratmaz; 409 IDEMPOTENT_REPLAY kodu ve mevcut belge döner. Ağ hatasında güvenle tekrar deneyebilirsiniz.

KVKK_CONSENT türü is_required=true ile birlikte gönderilemez; açık rıza zorunlu tutulamaz ve istek 400 ile reddedilir.

3. Dosyasız belge kaydı (isteğe bağlı)

Sayfalarını daha sonra yükleyeceğiniz ya da yalnızca onay alacağınız bir belge için önce kaydı açabilirsiniz:

curl -X POST -H "X-API-Key: imz_xxx" -H "Content-Type: application/json" \
  -d '{"title":"Fiyat Listesi","doc_kind":"PRICE_LIST","is_required":false,"signature_required":false}' \
  https://api-prd.imzala.org/api/v1/demands/{demandId}/documents

Yanıt 201 ve belge nesnesidir. doc_kind verilmezse OTHER, is_required ve signature_required verilmezse true varsayılır.

4. Sıralayın

İmzacı belgeleri bu sırayla görür. Tüm belge kimliklerini istediğiniz sırada gönderin:

curl -X PUT -H "X-API-Key: imz_xxx" -H "Content-Type: application/json" \
  -d '{"document_ids":["<preinfo-id>","<contract-id>","<kvkk-id>"]}' \
  https://api-prd.imzala.org/api/v1/demands/{demandId}/documents/order

Öneri: ön bilgilendirme sözleşmeden önce, KVKK aydınlatma metni açık rızadan önce gelsin. (Bu öneri genel bilgilendirme amaçlıdır, hukuki tavsiye değildir; belge içeriği ve sıralamasından siz sorumlusunuz.)

5. Güncelleyin ve silin

# Başlık / ayar güncelle
curl -X PATCH -H "X-API-Key: imz_xxx" -H "Content-Type: application/json" \
  -d '{"title":"Fiyat Listesi (Eylül)","is_required":false}' \
  https://api-prd.imzala.org/api/v1/demands/{demandId}/documents/{docId}

# Sil
curl -X DELETE -H "X-API-Key: imz_xxx" \
  https://api-prd.imzala.org/api/v1/demands/{demandId}/documents/{docId}

Bir imzacı belge üzerinde işlem yaptıysa (onay ya da imza) belge artık değiştirilemez ve silinemez; istek 409 döner.

6. İmzacı atayın

Her belge hangi imzacılara gidecek, siz belirlersiniz. Sözleşmenin taraf kimliklerini (party_id) sözleşme oluşturma yanıtındaki signing_urls listesinden ya da GET /demands/{demandId} ile alın:

curl -X PUT -H "X-API-Key: imz_xxx" -H "Content-Type: application/json" \
  -d '{"party_ids":["<party-1>","<party-2>"]}' \
  https://api-prd.imzala.org/api/v1/demands/{demandId}/documents/{docId}/assignments

Atama listesi bütünüyle değiştirilir (ekleme değil). signature_required belgelerde, editörde imza alanı olmayan bir imzacı atamak gönderimde uyarı üretir.

7. Zarfı gönderin

Belgeler ve atamalar tamamlanınca zarfı tek istekte gönderin:

curl -X POST -H "X-API-Key: imz_xxx" -H "Content-Type: application/json" \
  -d '{"send_invitations":"email"}' \
  https://api-prd.imzala.org/api/v1/demands/{demandId}/dispatch

send_invitations kanalı daraltır: "all" (ya da true) sözleşmenin kendi bildirim ayarına uyar, "email" yalnız e-posta, "sms" yalnız SMS gönderir, false hiç davet göndermeden yalnızca yayına alır. Tanınmayan değer 400 INVALID_SEND_INVITATIONS döner ve kredi düşmez.

Yanıt:

{
  "success": true,
  "data": {
    "demand_id": "…",
    "status": "PENDING",
    "dispatched": true,
    "credits": { "charged": 2, "refunded": 0, "expected": 2 },
    "invitations": { "sent": 2, "results": [ { "party_id": "…", "email": true, "sms": false } ] }
  }
}

• Kredi tek noktadan düşer ve mutabakat idempotenttir: aynı zarfı ikinci kez göndermek yeniden ücretlendirmez (charged: 0).
• Eşzamanlı istekler: Aynı zarfa aynı anda iki dispatch gelirse yalnız biri gönderimi üstlenir (dispatched: true); diğeri dispatched: false döner ve davet göndermez.
• Yeniden davet: Gönderilmiş bir zarfa dakikalar sonra tekrar dispatch çağırmak, henüz işini bitirmemiş taraflara davetleri yeniden yollar; imzalamış taraflara gitmez. Bu uç anahtar başına hız sınırına tabidir.
• demand.dispatched webhook olayı yalnız ilk gönderimde yayınlanır.

Hata kodları

Kod	Anlamı
400 INVALID_DOC_KIND	doc_kind tanınmıyor
400 INVALID_SEND_INVITATIONS	send_invitations değeri tanınmıyor
400 INVALID_DOCUMENT_SELECTION	Belge seçimi hatası; details.reason: shape (biçim hatası, bilinmeyen alan, 20’den fazla kimlik ya da toplu uçta options.documents), unknown_document (kimlik bu şablonun belgesi değil, details.document_ids), conflict (aynı kimlik iki listede), empty (seçim sonucunda belge kalmadı)
402	Yetersiz kredi; zarf yayına alınmaz, davet gitmez
404	Sözleşme ya da belge bu anahtarın erişiminde değil
409 IDEMPOTENT_REPLAY	Aynı idempotency_key ile tekrar yükleme; mevcut belge döner
409 ENVELOPE_MULTI_DOC_DISABLED	Çok belgeli zarf bu hesap için kapalı
409 DISPATCH_NO_PARTIES	Sözleşmede imzacı yok
409 DISPATCH_TOO_MANY	Tek istekte gönderilebilecek taraf sayısı aşıldı
409 PARTY_WITHOUT_DOCUMENTS	Eşlediğiniz bir role imzalayacak belge kalmadı (template_party_ids); sözleşme oluşturulmaz
409 TEMPLATE_DOCUMENTS_NOT_READY	Şablonun belge yapısı henüz hazır değil; documents göndermeden deneyin
409 DOCUMENT_SOURCE_UNAVAILABLE	Şablonun ilk belgesini çıkardınız ve kalan ilk belgenin dosyası yok
413 / 415 / 422	Dosya çok büyük / tür desteklenmiyor / içerik işlenemedi
429	Hız sınırı; Retry-After başlığına uyun

Tipik akış

1. POST /demands/upload ile sözleşmeyi ve tarafları oluşturun (davet göndermeden).
2. POST /documents/upload ile KVKK aydınlatma, açık rıza ve ön bilgilendirme belgelerini ekleyin; her birine benzersiz idempotency_key verin.
3. PUT /documents/order ile sırayı mevzuata uygun kurun.
4. Gerekirse PUT /assignments ile belge bazında imzacı daraltın.
5. POST /dispatch ile gönderin; demand.dispatched ve ardından belge onayları için webhook’ları dinleyin.