API'de Tek İstekte Sözleşme Oluşturma ve Davet Gönderme

İmzala API v1 ile sözleşme oluşturan entegrasyonlarda iki noktayı iyileştirdik: davetin ayrı bir çağrı gerektirmesi ve tekrarlanan isteklerin kopya sözleşme yaratması.

Tek istekte sözleşme ve davet

POST /api/v1/demands/upload çağrısına send_invitations parametresini eklediğinizde belge yükleme, Alan Şablonuyla imza alanlarının yerleştirilmesi ve imza davetinin gönderilmesi aynı çağrıda tamamlanır. Daha önce davet için ayrı bir istek atmanız gerekiyordu.

Kanalı seçebilirsiniz: email yalnızca e-posta, sms telefon numarası üzerinden giden kanallar (SMS ve WhatsApp), all ise açık olan tüm kanallar. Parametreyi hiç göndermezseniz davranış eskisi gibi kalır, yani sözleşme oluşur ve davet gitmez. Mevcut entegrasyonunuz değişiklikten etkilenmez, ayrı davet çağrısı da çalışmaya devam eder.

Kanal seçimi yalnızca daraltır: sözleşmenin bildirim ayarlarında veya tarafın tercihinde kapalı olan bir kanalı açmaz. Yanıtta taraf başına hangi kanaldan davet gittiği döner.

Davet mesajında tarafın adı soyadı ve kendisine özel imza bağlantısı yer alır; sözleşmenin bildirim metnini kendiniz düzenlediyseniz o metin gider ve metnin işlemsel kalması sizin sorumluluğunuzdadır. SMS ve WhatsApp davetlerinde belge dosyası ve belge içeriği gönderilmez. sms değeri iki kanalı birden kapsar; WhatsApp bildirimi bir yurt dışı aktarımı içerdiğinden imzacılarınıza yaptığınız aydınlatmada bu kanalı da gösterin.

Tek istekte davet gönderilebilecek taraf sayısı 20 ile sınırlıdır; sözleşme sıralı imzaya ayarlıysa davet yalnızca sıradaki ilk tarafa gider. Bu uçtan giden iletiler, imzalanacak sözleşmeye ilişkin işlemsel bildirimlerdir; pazarlama içermez.

Aynı sözleşmenin iki kez oluşmasına karşı koruma

Ağ zaman aşımında istemcinizin isteği yeniden göndermesi, ikinci bir sözleşme ve imzacılara ikinci bir davet anlamına geliyordu. İki koruma ekledik.

Tekrar anahtarı: Idempotency-Key başlığına kendi referansınızı (sipariş veya dosya numarası) koyabilirsiniz. Aynı anahtarla gelen ikinci istek yeni sözleşme yaratmaz, ilk sözleşmeyi geri döndürür ve davet göndermez. Aynı anahtar farklı bir içerikle gelirse istek reddedilir ve yanıtta mevcut sözleşmenin kimliği bildirilir.

Tekrar anahtarı yolundaki karşılaştırma belge baytlarına bakmaz. Sözleşme üreten sistemler belgeye oluşturma zamanını gömdüğü için aynı sözleşmeyi yeniden ürettiğinizde dosya bayt olarak değişir, anahtar yolu bundan etkilenmez.

Anahtar göndermeyenler için kopya kapısı: Aynı API anahtarıyla aynı belge ve aynı taraflar 10 dakika içinde ikinci kez gelirse istek reddedilir ve mevcut sözleşmenin kimliği döner. Aynı kişilere bilerek ikinci bir sözleşme göndermek istiyorsanız force=true parametresiyle devam edebilirsiniz.

Bu kapı bir kolaylık kontrolüdür, kesin bir güvence değildir: yalnız aynı API anahtarıyla, 10 dakikalık pencerede ve birebir aynı dosyayla çalışır. Belgeyi yeniden ürettiğiniz için baytı değiştiyse kapı devreye girmez. Tekrarlardan kesin olarak korunmak istiyorsanız tekrar anahtarı kullanın.

Davet tekrarında hız sınırı

Bir imzacıya kısa sürede üst üste davet gönderilmesini sınırlandırdık. Sınır alıcı başına uygulanır (telefon numarası; numara yoksa e-posta adresi) ve hem tek istekli gönderimde hem taraf bazlı davet ucunda geçerlidir. Sınır aşıldığında istek reddedilmez, yalnız o taraf atlanır ve yanıtta işaretlenir; diğer taraflara gönderim sürer. Amaç, hatalı bir döngünün imzacıyı mesaj yağmuruna tutmasını önlemek.

Teknik ayrıntılar, örnek çağrılar ve hata kodları için bilgi bankasındaki API ile Alan Şablonu Kullanımı makalesine ve api-docs.imzala.org adresindeki referansa bakabilirsiniz.