API ile Sözleşme Yaşam Döngüsü Yönetimi

İmzala API v1’in sözleşme yaşam döngüsü uç noktaları, panelde elle yaptığınız işlemleri (listeleme, durum takibi, indirme, iptal, tekrar davet, silme) kendi uygulamanızdan otomatik yapmanızı sağlar. Bu rehber, uç noktaların tamamını curl ve resmi Node SDK örnekleriyle anlatır. Tüm istek/yanıt şemalarının kesin hâli için api-docs.imzala.org resmi referansına bakın.

Beta: Node SDK şu an beta etiketiyle (@imzala/node@next) yayınlanır. Alan adları ve dönüş tipleri kararlı sürüme kadar değişebilir; üretimde kullanmadan önce resmi referansı kontrol edin.

1. Kimlik doğrulama

Tüm istekler bir API anahtarı ister. Anahtarı Panel → Geliştirici → API Anahtarları bölümünden oluşturun (app.imzala.org/developer). Anahtar imz_ ile başlar ve her istekte X-API-Key başlığıyla gönderilir:

curl -H "X-API-Key: imz_xxxxxxxxxxxxxxxx" \
  https://api-prd.imzala.org/api/v1/demands

Anahtar bir şifre gibidir; sızarsa panelden iptal edin. İstemci tarafı (tarayıcı, mobil uygulama) koduna gömmeyin, yalnızca sunucu tarafında saklayın.

2. Node SDK kurulumu

npm i @imzala/node@next

import { Imzala } from "@imzala/node";

const imzala = new Imzala({
  apiKey: process.env.IMZALA_API_KEY, // imz_...
});

SDK, istek başlıklarını, yeniden denemeleri ve hata tiplerini sizin için yönetir. Anahtarı ortam değişkeninden (process.env) okuyun, kaynak koda yazmayın.

3. Uç nokta özeti

İşlem	Uç nokta	Node SDK
Sözleşme listesi	GET /api/v1/demands	demands.list()
Sözleşme detayı	GET /api/v1/demands/{id}	demands.get(id)
İmzalı PDF indir	GET /api/v1/demands/{id}/pdf	demands.getPdf(id)
Tamamlanma sertifikası	GET /api/v1/demands/{id}/certificate	demands.getCertificate(id)
İmza denetim izi	GET /api/v1/demands/{id}/timeline	demands.getTimeline(id)
Sözleşme iptal	POST /api/v1/demands/{id}/cancel	demands.cancel(id)
Tekil tarafa tekrar davet	POST /api/v1/demands/{id}/parties/{partyId}/resend	demands.resendParty(id, partyId)
Tamamlanmamış sözleşmeyi sil	DELETE /api/v1/demands/{id}	demands.delete(id)
Şablon güncelle	PATCH /api/v1/templates/{id}	templates.update(id, data)
Şablon sil	DELETE /api/v1/templates/{id}	templates.delete(id)

4. Sözleşmeleri listeleme

Liste uç noktası yalnızca sayımları döndürür: taraf sayısı ve kaç tarafın imzaladığı gibi alanlar gelir, imzacıların kişisel bilgileri gelmez. Bu, dolduramayacağınız veriyi hiç almadığınız veri minimizasyonu yaklaşımının bir parçasıdır (bkz. “Kişisel veri ve KVKK”).

curl -H "X-API-Key: imz_xxxxxxxxxxxxxxxx" \
  "https://api-prd.imzala.org/api/v1/demands?status=PENDING&page=1"

const { data } = await imzala.demands.list({ status: "PENDING", page: 1 });

for (const demand of data) {
  console.log(
    demand.id,
    demand.status,
    `${demand.parties_signed}/${demand.parties_total} imzalandı`,
  );
}

Örnek yanıt (alanlar açıklama amaçlıdır, kesin şema referansta):

{
  "data": [
    {
      "id": "d_9f2c...",
      "title": "Hizmet Sözleşmesi",
      "status": "PENDING",
      "parties_total": 3,
      "parties_signed": 1,
      "created_at": "2026-07-01T09:30:00Z"
    }
  ],
  "page": 1,
  "has_more": false
}

5. Sözleşme detayı

Detay uç noktası tek bir sözleşmenin taraflarını ve durumunu döndürür. Kişisel veriler maskeli gelir: imzacı adı kısaltılır, e-posta maskelenir, ham IP adresi veya T.C. kimlik numarası dönmez.

curl -H "X-API-Key: imz_xxxxxxxxxxxxxxxx" \
  https://api-prd.imzala.org/api/v1/demands/d_9f2c...

const demand = await imzala.demands.get("d_9f2c...");

console.log(demand.status);
for (const party of demand.parties) {
  console.log(party.name, party.email, party.signed ? "imzaladı" : "bekliyor");
  // Örn: "Ah** Y****", "a***@e***.com"
}

6. İmzalı PDF indirme

Bu uç nokta ikili (binary) veri döndürür, JSON değil. curl ile bir dosyaya kaydedin:

curl -H "X-API-Key: imz_xxxxxxxxxxxxxxxx" \
  https://api-prd.imzala.org/api/v1/demands/d_9f2c.../pdf \
  --output sozlesme.pdf

Node SDK dönüşü bir Buffer’dır; diske yazabilir veya akışa aktarabilirsiniz:

import { writeFile } from "node:fs/promises";

const pdf = await imzala.demands.getPdf("d_9f2c...");
await writeFile("sozlesme.pdf", pdf);

İmzalı PDF yalnızca tamamlanmış sözleşmeler için hazırdır; tamamlanmamış bir sözleşmede bu uç nokta hata döndürür.

7. Sertifika ve denetim izi

• Tamamlanma sertifikası (getCertificate): sözleşmenin tamamlandığını özetleyen sertifika PDF’i (imza zamanları, denetim izi özeti). İmzalı PDF gibi ikili veri döner.
• Denetim izi (getTimeline): gönderim, görüntüleme, imza ve zaman damgası olaylarının zaman çizelgesi. Kişisel alanlar burada da maskelidir.

// Sertifikayı indir
const cert = await imzala.demands.getCertificate("d_9f2c...");
await writeFile("sertifika.pdf", cert);

// Denetim izini oku
const timeline = await imzala.demands.getTimeline("d_9f2c...");
for (const event of timeline.events) {
  console.log(event.at, event.type); // örn: "2026-07-01T10:00:00Z", "party_signed"
}

8. Yaşam döngüsü işlemleri

Sözleşmeyi iptal etme

Henüz tamamlanmamış bir sözleşmeyi iptal eder. İptal sonrası taraflar imza atamaz, imza bağlantıları “iptal edildi” durumunu gösterir. İsteğe bağlı bir iptal nedeni ekleyebilirsiniz.

curl -X POST \
  -H "X-API-Key: imz_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Yanlış taraf eklendi"}' \
  https://api-prd.imzala.org/api/v1/demands/d_9f2c.../cancel

await imzala.demands.cancel("d_9f2c...", { reason: "Yanlış taraf eklendi" });

Tekil tarafa tekrar davet gönderme

İmzalamayı bekleyen belirli bir tarafa daveti yeniden iletir (e-posta ve/veya SMS):

await imzala.demands.resendParty("d_9f2c...", "p_a1b2...");

Tamamlanmamış sözleşmeyi silme

Yalnızca henüz imza atılmamış (tamamlanmamış) sözleşmeler silinebilir. Tamamlanmış sözleşmeler kanıt bütünlüğü için silinemez, gerekirse iptal edilir.

await imzala.demands.delete("d_9f2c...");

9. Şablon işlemleri

Şablon üstverisini güncelleyebilir veya bir şablonu silebilirsiniz. Güncelleme kısmi (PATCH) çalışır: yalnızca gönderdiğiniz alanlar değişir.

curl -X PATCH \
  -H "X-API-Key: imz_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kira Sözleşmesi 2026", "description": "Güncel kira şablonu"}' \
  https://api-prd.imzala.org/api/v1/templates/t_77aa...

// Üstveri güncelle
await imzala.templates.update("t_77aa...", {
  name: "Kira Sözleşmesi 2026",
  description: "Güncel kira şablonu",
});

// Şablonu sil
await imzala.templates.delete("t_77aa...");

Şablondan yeni sözleşme oluşturma akışı için API Anahtarı ve SDK Kullanımı rehberine ve resmi referanstaki POST /api/v1/demands uç noktasına bakın.

Kişisel veri ve KVKK

API, veri minimizasyonu ilkesiyle tasarlanmıştır: uç noktalar iş akışınız için gereken en az veriyi döndürür.

• Liste yanıtı yalnızca sayımları verir (taraf sayısı, imzalayan sayısı); imzacı kişisel bilgisi taşımaz.
• Detay ve denetim izi yanıtlarında imzacı adı kısaltılır, e-posta maskelenir.
• Ham IP adresi ve T.C. kimlik numarası gibi hassas alanlar API üzerinden dönmez.

Böylece entegrasyonunuz, gerekmeyen kişisel veriyi hiç almadan çalışır. KVKK yükümlülükleriniz açısından bu, sisteminizde tutulan kişisel veri yüzeyini küçültür.

Durum kodları ve hatalar

• 200 başarılı, 204 içeriksiz başarı (örn. silme).
• 401 geçersiz veya eksik API anahtarı.
• 403 bu anahtarın ilgili kaynağa yetkisi yok.
• 404 sözleşme veya şablon bulunamadı.
• 409 işlem mevcut durumda yapılamaz (örn. tamamlanmış sözleşmeyi silme).
• 429 hız sınırı; bir süre bekleyip tekrar deneyin.

Node SDK bu durumları tiplendirilmiş hata olarak fırlatır; try/catch ile yakalayıp error.status ve error.code alanlarına bakabilirsiniz.

Tam referans

Tüm uç noktalar, sorgu parametreleri, istek/yanıt şemaları ve örnekler resmi dokümantasyonda:

👉 api-docs.imzala.org

Olayları anlık almak için (imzalandı, tamamlandı) sürekli sorgulama yerine Webhook’lar’ı kullanın.

Sonraki adımlar

• Anahtarınızı oluşturun: Panel → Geliştirici
• İlk çağrınızı yapın: API Anahtarı ve SDK Kullanımı
• Olay bildirimleri kurun: Webhook’lar
• Panelden manuel yönetim: Sözleşmelerinizi Yönetme

Entegrasyonla ilgili sorularınız için destek ekibine yazabilirsiniz.