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. Ç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.

7. 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.

8. 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.