API: Çoklu Taraf Değişkenleri

Bir kira sözleşmesi şablonunuzda Kiraya Veren ve Kiracı olmak üzere iki taraf varsa, aynı şablon değişkenlerini ({{full_name}}, {{government_id}}, {{phone}} vb.) iki kişiye farklı değerlerle doldurmanız gerekir. Önceden API’de bu mümkün değildi — flat variables alanı tüm partilere aynı değeri yazıyordu (sessiz bir bug’dı).

Yeni: party_mapping[].variables

DocuSign’ın templateRoles[i].tabs mantığına benzer şekilde, her partinin değişkenlerini ayrı ayrı tanımlayabilirsiniz:

POST /api/v1/demands
{
  "template_id": "907f6f26-...",
  "party_mapping": [
    {
      "template_party_id": "kiraya-veren",
      "name": "Ahmet Yılmaz",
      "email": "[email protected]",
      "phone": "+905551112233",
      "variables": {
        "full_name": "Ahmet Yılmaz",
        "government_id": "12345678901",
        "address": "Maslak Mah. ..."
      }
    },
    {
      "template_party_id": "kiraci",
      "name": "Mehmet Demir",
      "email": "[email protected]",
      "phone": "+905554445566",
      "variables": {
        "full_name": "Mehmet Demir",
        "government_id": "98765432109",
        "address": "Kadıköy Mah. ..."
      }
    }
  ],
  "variables": {
    "contract_date": "2026-05-15",
    "monthly_rent": "12500"
  }
}

3 Aşamalı Çözümleme

Sözleşme oluşturulurken her alan için doğru değer şu sırayla aranır:

1. Parti bazlı — party_mapping[i].variables[slug] (en spesifik)
2. Genel — root-seviye variables[slug] (tüm partiler için ortak veriler)
3. Şablon varsayılanı — şablonu hazırlarken tanımladığınız “varsayılan değer kaynağı” (örn. {{signer.full_name}} gibi otomatik dolan alanlar)

Geriye Uyumluluk

Mevcut entegrasyonlarınız aynen çalışır. Tek-partyli şablonlar (vize başvuru formu, müşteri sözleşmesi vb.) party_mapping olmadan, sadece root variables ile çalışmaya devam eder.

Yanıt Echo’su

API yanıtında ek olarak iki yeni alan döner:

• variables_applied[] — başarıyla yerleştirilen değişkenler
• variables_ignored[] — şablonda eşleşmediği için atlanan değişkenler (yazım hatası, yanlış slug yakalamak için)

Bu sayede sessiz başarısızlık ortadan kalktı; yanlış slug gönderirseniz API yanıtı size hangilerinin atlandığını söyler.

Doğrulama

Üç katmanlı validation:

• Wrapper — party_mapping array yapısı geçerli mi
• Değer tipi — string/number/boolean kabul ediliyor
• Çakışma — aynı template_party_id iki kez geliyor mu

Hatalı bir istek 400 döner, hangi maddenin hatalı olduğunu açıklar.