API ile Alan Şablonu Kullanımı

Alan Şablonu, belgenin kendisini değil yalnızca alanların yerleşimini saklar. Belge her gönderimde değiştiği için (analiz raporu, aylık fatura, kişiye özel teklif) yerleşimi bir kez kurar, her çağrıda o günün PDF’ini gönderirsiniz. Bu sayfa aynı akışın API tarafını anlatır.

Alan Şablonunu panelden nasıl kuracağınız ayrı bir konudur: Alan Şablonu.

1. Kimlik doğrulama

Tüm çağrılar X-API-Key başlığıyla yapılır. Anahtarı panelden Ayarlar → API Anahtarları bölümünden oluşturursunuz.

curl https://api-prd.imzala.org/api/v1/field-templates \
  -H "X-API-Key: imz_xxxxxxxx"

Bu sayfadaki uçların kapsam gereksinimleri:

Uç	Kapsam
GET /api/v1/field-templates	templates:read
GET /api/v1/field-templates/{id}	templates:read
POST /api/v1/field-templates/{id}/preview-layout	demands:write
POST /api/v1/demands/upload	demands:write

Kuru koşum ucunun demands:write istemesi bilinçlidir: yaptığı şey tam olarak bir yazma işleminin provasıdır ve döndürdüğü bilgi o çağrının hata gövdesiyle aynıdır.

2. Alan Şablonlarını listeleyin

curl https://api-prd.imzala.org/api/v1/field-templates \
  -H "X-API-Key: imz_xxxxxxxx"

{
  "success": true,
  "data": {
    "field_templates": [
      {
        "id": "6f1c…",
        "name": "Analiz raporu",
        "description": "Laboratuvar çıktısı",
        "category": "lab",
        "usage_count": 128,
        "parties": [
          { "id": "p-1", "order": 1, "label": "Analist", "is_required": true },
          { "id": "p-2", "order": 2, "label": "Kontrol", "is_required": false }
        ]
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Neden ayrı bir uç: GET /api/v1/templates Alan Şablonlarını bilerek listelemez, GET /api/v1/templates/{id} de onlara 404 döner. Alan Şablonunun referans belgesi hiçbir imzacıya gönderilmez; belgeli şablon sanılması, o referans belgenin karşı tarafa gitmesi anlamına gelirdi. Bu yüzden varsayılan davranış hariç tutmaktır ve Alan Şablonlarını görmek açık bir talep gerektirir.

3. Rolleri okuyun

curl https://api-prd.imzala.org/api/v1/field-templates/6f1c… \
  -H "X-API-Key: imz_xxxxxxxx"

{
  "success": true,
  "data": {
    "id": "6f1c…",
    "name": "Analiz raporu",
    "total_field_count": 6,
    "parties": [
      { "id": "p-1", "order": 1, "label": "Analist", "is_required": true, "field_count": 4 },
      { "id": "p-2", "order": 2, "label": "Kontrol", "is_required": false, "field_count": 2 }
    ]
  }
}

field_count, o rolün belgede dolduracağı alan sayısıdır. Alanların koordinatları dönmez: yerleşimin belgeye nasıl oturduğunu görmek için bir sonraki adımdaki kuru koşumu kullanın.

Belgeli bir şablonun kimliğini verirseniz 404 alırsınız. Var olmayan kimlik ve size ait olmayan şablon da aynı yanıtı verir; hangi durumun geçerli olduğu ifşa edilmez.

4. Göndermeden önce kuru koşum

Bu uç sözleşme oluşturmaz, kredi düşmez, dosya saklamaz. Yalnızca “bu yerleşim bu belgeye uygulanabilir mi” sorusunu yanıtlar.

curl -X POST https://api-prd.imzala.org/api/v1/field-templates/6f1c…/preview-layout \
  -H "X-API-Key: imz_xxxxxxxx" \
  -F "[email protected]" \
  -F "on_anchor_miss=block"

Yanıtta resolvable alanına bakın. false ise diagnostics içinde en az bir hata vardır ve aynı belge gerçek çağrıda da reddedilecektir.

Çözülemeyen belge 200 döner, 422 değil: kuru koşumun cevabı “uygulanamaz”dır, isteğin kendisi başarısız değildir. Belgenin okunamaması (parola korumalı PDF, sayfa tavanı aşımı) ise gerçek bir girdi hatasıdır ve kendi durum kodunu döner.

Bu uçta ayrı ve daha sıkı bir hız sınırı vardır: dakikada 5 istek. Kredi freni olmayan tek ağır iş ucu budur.

5. Sözleşmeyi oluşturun

curl -X POST https://api-prd.imzala.org/api/v1/demands/upload \
  -H "X-API-Key: imz_xxxxxxxx" \
  -F "[email protected]" \
  -F "field_template_id=6f1c…" \
  -F 'parties=[
        {"template_party_id":"p-1","first_name":"Ada","last_name":"Kalkan","email":"[email protected]"},
        {"template_party_id":"p-2","first_name":"Deniz","last_name":"Yılmaz","email":"[email protected]"}
      ]'

Bu dalda geçerli kurallar:

• Yüklenen dosya PDF olmak zorundadır. Karar dosyanın sihirli baytlarından verilir, beyan edilen içerik türüne bakılmaz. Word, ODT ve RTF kabul edilmez: PDF’e çevrilirken sayfalandırma değişebilir ve sayfa numarasına dayanan kurallar yanlış sayfaya düşer. Aksi halde 415 UNSUPPORTED_FILE_TYPE alırsınız.
• parties dizisindeki her taraf template_party_id taşımalıdır ve şablondaki her rol tam olarak bir tarafa eşlenmelidir.
• field_template_id ile template_id birlikte gönderilemez.
• Bir role panelde varsayılan kişi bağlıysa API otomatik seçim yapmaz; o rol için açık bir taraf gönderin.
• Yerleşim, kredi düşümünden ve sözleşme yaratımından önce çözülür. 422 dönen bir istek ne sözleşme, ne dosya, ne de kredi hareketi bırakır.

6. Daveti aynı istekte gönderin

Sözleşme oluşturulduğunda imza daveti kendiliğinden gitmez. Eskiden her taraf için ayrıca bir davet çağrısı yapmanız gerekiyordu. Artık send_invitations parametresiyle yükleme, alan yerleşimi ve davet tek istekte tamamlanır.

curl -X POST https://api-prd.imzala.org/api/v1/demands/upload \
  -H "X-API-Key: imz_xxxxxxxx" \
  -F "[email protected]" \
  -F "field_template_id=6f1c…" \
  -F "send_invitations=email" \
  -F 'parties=[ … ]'

Değer	Anlamı
true, 1, all	Açık olan tüm kanallar
email	Yalnızca e-posta
sms	Telefon numarası üzerinden giden kanallar: SMS ve WhatsApp
false, 0, off, no, hayır	Davet gönderilmez (varsayılan)

sms değeri telefon numarası üzerinden giden iki kanalı birden kapsar. Yalnızca SMS gitmesini istiyorsanız sözleşmenin bildirim ayarlarında WhatsApp kanalını kapalı tutun. WhatsApp bildirimi bir yurt dışı aktarımı içerir; imzacılarınıza yaptığınız aydınlatmada bu kanalı da göstermeniz gerekir.

Parametreyi hiç göndermezseniz davranış eskisi gibi kalır: sözleşme oluşur, davet gitmez. Mevcut entegrasyonunuz bundan etkilenmez.

Davette ne gider: tarafın adı soyadı ve kendisine özel imza bağlantısı. Sözleşmenin bildirim metnini kendiniz düzenlediyseniz ({{name}} ve {{link}} değişkenleriyle) o metin gönderilir. Düzenlediğiniz metin de işlemsel kalmalıdır: kampanya, indirim, tanıtım veya imzalanacak belgeyle ilgisi olmayan içerik eklemeyin; böyle bir içerik iletinin ticari elektronik ileti sayılmasına yol açar. SMS ve WhatsApp davetlerinde belge dosyası ve belge içeriği gönderilmez; belgeye yalnızca bağlantı açıldığında erişilir (imza tamamlandığında imzacıya giden e-postaya imzalı PDF eklenir). WhatsApp bildirimi İmzala’nın kendi WhatsApp hattından gider ve gönderim WhatsApp altyapısı üzerinden yapılır; bu kanalın kişisel veri ayrıntısı İmza Süreci Aydınlatma Metni ve Alt-İşleyenler sayfalarındadır.

Kanal seçimi yalnızca daraltır. Sözleşmenin bildirim ayarlarında veya tarafın kendi tercihinde kapalı olan bir kanalı açamaz. Tanınmayan bir değer gönderirseniz istek 400 INVALID_SEND_INVITATIONS ile reddedilir; sessizce yok sayılmaz, çünkü davetin gittiğini sanmanız en kötü sonuçtur.

Yanıtta taraf başına sonuç döner:

"dispatch": {
  "requested": true,
  "sent": 2,
  "results": [
    { "party_id": "…", "sms": false, "email": true, "whatsapp": false },
    { "party_id": "…", "sms": true, "email": false, "whatsapp": false }
  ]
}

Davet gönderimi isteği düşürmez. Sözleşme oluşturulup kredi düşüldükten sonra bir kanal hata verirse yanıt yine 201 olur ve ilgili taraf error: "DISPATCH_FAILED" ile işaretlenir. WhatsApp kanalında whatsapp: true gönderimin denendiğini gösterir, alıcıya ulaştığını garanti etmez; bu kanalda sağlayıcı tarafındaki bir hata ayrıca işaretlenmez. Bir tarafa daveti sonradan tekrar göndermek için taraf bazlı davet ucunu kullanabilirsiniz.

Sözleşme sıralı imzaya ayarlıysa davet yalnızca sıradaki ilk tarafa gider; sonraki taraflara davet kendi sıraları geldiğinde gönderilir ve results dizisinde yalnız o taraf yer alır.

Tek istekte davet gönderilebilecek taraf sayısı 20 ile sınırlıdır. Daha fazla taraf içeren bir sözleşmede istek yine 201 döner ve sözleşme oluşur, ancak dispatch nesnesinde error: "DISPATCH_TOO_MANY" alırsınız ve hiçbir davet gönderilmez; bu durumda tarafları taraf bazlı davet ucuyla tek tek çağırın. Yanıttaki sent alanını okumadan davetin gittiğini varsaymayın.

Aynı alıcıya kısa sürede giden davet tekrarları alıcı ekseninde sınırlanır. Sınır alıcı başına uygulanır (telefon numarası; numara yoksa e-posta adresi) ve hem bu uçta hem taraf bazlı davet ucunda geçerlidir. Sınır aşıldığında istek reddedilmez, yalnız o taraf atlanır ve error: "RECIPIENT_QUOTA_EXCEEDED" ile işaretlenir; diğer taraflara gönderim sürer.

Bu uçtan giden iletiler, taraf olduğunuz sözleşmenin imzalanması için gönderilen işlemsel bildirimlerdir; pazarlama veya tanıtım içermez. Daveti yalnızca gerçekten sözleşmenin tarafı olan kişilere gönderin. Alıcıların iletişim bilgisini hukuka uygun elde etmiş olmak ve ticari elektronik ileti mevzuatına uymak veri sorumlusu ve hizmet sağlayıcı sıfatıyla size aittir.

7. Aynı isteğin iki sözleşme yaratmasını önleyin

Ağ zaman aşımında istemcinizin isteği körlemesine tekrarlaması, ikinci bir sözleşme, ikinci bir kredi ve imzacılara ikinci bir davet demektir. İki koruma vardır. Kesin koruma yalnızca idempotency anahtarıyla sağlanır; anahtarsız kopya kapısı bir kolaylık kontrolüdür, güvence değildir. Tekrar korumasını kurmak ve yanıtı okumak entegrasyonun sorumluluğundadır.

Idempotency anahtarı

Idempotency-Key başlığına kendi referansınızı (sipariş, dosya veya iş emri numarası) koyun. Multipart gövdesinde idempotency_key alanı da kabul edilir; ikisini birden gönderip farklı değer yazarsanız istek 400 INVALID_IDEMPOTENCY_KEY ile reddedilir.

curl -X POST https://api-prd.imzala.org/api/v1/demands/upload \
  -H "X-API-Key: imz_xxxxxxxx" \
  -H "Idempotency-Key: SIP-2026-00187" \
  -F "[email protected]" \
  -F "field_template_id=6f1c…" \
  -F 'parties=[ … ]'

Aynı API anahtarıyla ve aynı idempotency anahtarıyla gelen ikinci istek yeni sözleşme yaratmaz: ilk sözleşme reused: true ve created_at alanlarıyla döner, kredi düşülmez, davet gönderilmez.

Bilmeniz gereken dört nokta:

• Anahtar kalıcıdır, süre sınırı yoktur. Numaralandırmanız yıl döngüsünde tekrar ediyorsa yıl ön eki ekleyin.
• Aynı anahtar farklı bir içerikle gelirse 409 IDEMPOTENCY_KEY_REUSED alırsınız. Gövdedeki demand_id zaten üretilmiş sözleşmedir; körlemesine yeni anahtarla tekrar denemeyin, ikinci sözleşme yaratırsınız.
• Tekrar yanıtı ilk yanıtın birebir kopyası değildir. Yalnızca kalıcı alanlar döner; dispatch, field_layout gibi o isteğe özgü çalışma zamanı çıktıları bulunmaz.
• Anahtar daha önce kullanılmış ama isteğin aynı olduğu doğrulanamıyorsa 409 IDEMPOTENCY_UNVERIFIABLE alırsınız. Bu bir hata değil ihtiyat kararıdır: gövdedeki demand_id üzerinden sözleşmeyi kontrol edin, yeni bir anahtarla körlemesine tekrar denemeyin.

Anahtar yolundaki karşılaştırma belge baytlarına bakmaz. Sözleşme üreten sistemler PDF’e oluşturma zamanı gömdüğü için aynı sözleşmeyi yeniden ürettiğinizde dosya bayt olarak değişir; karşılaştırma bayta bağlı olsaydı meşru bir tekrar reddedilirdi.

Anahtar göndermezseniz

Aynı API anahtarıyla aynı içerik (aynı belge, aynı başlık, aynı taraflar) 10 dakika içinde ikinci kez gelirse istek 409 DUPLICATE_SUSPECTED ile reddedilir ve gövdede mevcut sözleşmenin demand_id alanı döner.

Aynı kişilere kasten ikinci bir sözleşme göndermek istiyorsanız force=true ekleyin. Bu kapı yalnızca anahtar göndermeyen çağrılarda çalışır: Idempotency-Key gönderen istemci zaten korunmuş sayılır.

Taraf başına değişkenleriniz farklıysa (tutar, ürün, tarih) iki gönderim kopya sayılmaz, ikisi de oluşur. İptal edilmiş sözleşmeler de kopya sayılmaz; yanlış bir gönderimi iptal edip doğrusunu yollayabilirsiniz.

Bu kapının sınırlarını bilerek kullanın. Anahtar yolunun aksine birebir aynı dosyayı arar: sözleşmeyi yeniden ürettiğiniz için belge baytı değiştiyse kapı devreye girmez ve ikinci sözleşme oluşur. Yalnızca aynı API anahtarı ekseninde ve 10 dakikalık pencerede çalışır. Aynı anda gönderilen iki özdeş istekte de kesin sonuç vermez. Tekrarlardan kesin olarak korunmak istiyorsanız Idempotency-Key kullanın.

8. Çapa bulunamazsa ne olur

on_anchor_miss parametresi, metin çapasına bağlı bir alanın çapası belgede bulunamazsa ne yapılacağını belirler:

Değer	Davranış
block	İşlem durur, sözleşme oluşturulmaz (varsayılan)
drop	Çapası tutmayan alan düşürülür, kalanla devam edilir

Parametreyi hiç göndermezseniz block uygulanır. Şablonunuzun panelde daha gevşek bir ayarı olsa bile API bunu yalnızca sıkılaştırır: drop istemeniz şablon block ise sonucu değiştirmez, yanıtta bir uyarı görürsünüz.

Gerekçe şudur: panelde yerleşimi uyguladığınızda sonucu gözünüzle görürsünüz, API’de böyle bir insan önizlemesi yoktur. Önizlemesiz bir yüzeyde varsayılanın en katı davranış olması gerekir.

9. Sonucun doğruluğu size aittir

İmzala yerleşimi hesaplar; alanların doğru yere düştüğünü doğrulamaz. Belgeleriniz beklediğiniz biçimde değilse alan yanlış yere oturabilir ve bunu yalnız siz fark edebilirsiniz. Üretime almadan önce birkaç gerçek belgeyle kuru koşum yapmanızı, çıktıyı gözle kontrol etmenizi öneririz.

Uzunluğu değişen belgelerde sondan sayarak sayfa ve metin çapası kuralları, sabit sayfa numarasından daha dayanıklıdır.

10. Kredi

Kuru koşum ücretsizdir. Kredi yalnızca POST /api/v1/demands/upload sözleşmeyi gerçekten oluşturduğunda düşer ve tutar, şablonun imza ayarlarına ve sözleşmedeki imzacı sayısına göre hesaplanır. Yerleşim çözülemediği için 422 dönen bir istek kredi harcamaz.

Kişisel veri ve KVKK

API üzerinden gönderdiğiniz imzacı bilgileri (ad, soyad, e-posta, telefon) sözleşmenin tarafı olarak işlenir. Yüklediğiniz belgede yer alan kişisel verilerin hukuka uygun toplanmış olmasından ve ilgili kişilerin aydınlatılmasından veri sorumlusu olarak siz sorumlusunuz. Ayrıntı için Gizlilik Politikası ve KVKK Aydınlatma Metni sayfalarına bakın.