Geliştirici belgeleri API

Base path: /api/v1/developer/documents

Önerilen entegrasyon: Tek istekte belge gönderme (POST /developer/documents/send).

---

Kiosk listesi — GET /developer/kiosks

Workspace’e bağlı kiosk cihazlarını döner. Scope: documents:read. Yanıttaki id alanı gönderimde kioskDeviceId olarak kullanılır.

Oluşturma, PIN ve eşleştirme Developer API’de yoktur (panel /kiosk).

---

İndirme (binary)

Başarılı yanıt CustomResponse değildir; dosya akışıdır. Hata durumunda JSON CustomResponse (400).

Completed sonrası:

• GET /developer/documents/{operationId}/final-pdf
• GET /developer/documents/{operationId}/certificate-pdf
• GET /developer/documents/{operationId}/timestamp-file

---

Yeniden gönderim

Yalnızca Dispatched belgeler.

• GET /developer/documents/{operationId}/resend-options — alıcı uygunluğu
• POST /developer/documents/{operationId}/resend — body: recipientId, channels, kioskDeviceId?

Kiosk yeniden gönderiminde kioskDeviceId için GET /developer/kiosks kullanın.

İmza deneyimi özeti: İmzalama akışı.

---

Tek istekte gönder — POST /developer/documents/send

multipart/form-data: file (PDF) + payload (JSON). workspaceId token’dan alınır. Alıcıların fields[] dizisi ve channels aynı nesnede gider.

Müşteri entegrasyonlarında sık kullanılan ayrık imza örneği (pageNumber: 0, config.isDetached: true):

{
  "displayFileName": "sozlesme.pdf",
  "description": "İki taraflı sözleşme",
  "privateNote": "ERP #12345",
  "settings": {
    "isOrderedFlow": true,
    "useUniqueDeliveryKey": true,
    "showOtherRecipientsFields": false,
    "showOtherRecipientsFieldsAsRendered": false,
    "documentLanguageCode": "tr",
    "timestampProvider": "dijital-imza"
  },
  "recipients": [
    {
      "id": "r1",
      "fullName": "Ayşe Yılmaz",
      "email": "[email protected]",
      "phone": "+905551112233",
      "role": "Signee",
      "order": 1,
      "channels": ["email", "sms"],
      "copyNotificationChannels": ["email"],
      "fields": [
        {
          "type": "SIGNATURE",
          "pageNumber": 0,
          "label": "İmza",
          "required": true,
          "config": { "isDetached": true }
        }
      ]
    }
  ]
}

Rehber, curl ve hata/uyarı modeli: Tek istekte belge gönderme.

---

Referans: alan (element) tipleri

Konfigürasyonda her alan elementType ile belirtilir. Büyük/küçük harf duyarsızdır; önerilen kanonik değerler:

Element ortak alanları:

Sık config anahtarları:

Element örnekleri

Aşağıdan elementType seçin; yalnızca seçilen tipin elements[] örneği gösterilir. Hepsi aynı alıcıya (r1) atanmış varsayılır.

{
  "externalId": "e-input-1",
  "pageNumber": 1,
  "recipientExternalId": "r1",
  "elementType": "INPUT",
  "x": 40,
  "y": 40,
  "width": 220,
  "height": 28,
  "config": {
    "required": true,
    "label": "Ad Soyad",
    "placeholder": "Adınızı yazın",
    "type": "text"
  }
}

---

Ayrık bileşenler (config.isDetached)

PDF üzerine konum vermeden imza, metin vb. istemek için kullanılır. Alıcı /r/{code} ekranında alanı PDF dışı doldurma adımlarında doldurur; nihai PDF’te değerler belgenin sonuna ek sayfada alt alta basılır.

Örnek — yalnızca ayrık imza:

{
  "operationType": "document",
  "displayFileName": "sozlesme.pdf",
  "recipients": [
    {
      "externalId": "r1",
      "fullName": "Ayşe Yılmaz",
      "email": "[email protected]",
      "role": "Signee",
      "order": 1
    }
  ],
  "pages": [{ "pageNumber": 1, "width": 595, "height": 842 }],
  "elements": [
    {
      "externalId": "e-sig-detached",
      "pageNumber": 0,
      "recipientExternalId": "r1",
      "elementType": "SIGNATURE",
      "x": 0,
      "y": 0,
      "width": 180,
      "height": 48,
      "config": {
        "isDetached": true,
        "required": true,
        "label": "İmza"
      }
    }
  ]
}

---

Referans: gönderim kanalları (channels)

POST .../send içindeki deliveryPlans[].channels:

copyNotificationChannels yalnızca email ve sms kabul eder.

---

Referans: diğer sabitler

workspaceId create isteğinde token workspace’i ile aynı olmalıdır.

Roller ve sıralı akış

isOrderedFlow: true iken alıcılar order sırasıyla ilerler.

---

Create — POST /developer/documents

İstek alanları

Örnek istek

{
  "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "operationType": "document",
  "description": "Sözleşme — örnek"
}

Yanıt data (özet)

---

PDF — POST /developer/documents/{operationId}/pdf

multipart/form-data; alan adı file (PDF). JSON body değildir.

---

Configuration — PUT /developer/documents/{operationId}/configuration

Gerçek model: düz recipients + pages + elements (pages içinde nested elements yok).

Üst alanlar

recipients[] alanları

recipientProfile / verification

pages[]

Örnek istek (imza + doğrulama + biyometrik)

{
  "operationType": "document",
  "displayFileName": "sozlesme.pdf",
  "description": "İki taraflı imza akışı",
  "privateNote": "İç not",
  "useUniqueDeliveryKey": true,
  "showOtherRecipientsFields": false,
  "showOtherRecipientsFieldsAsRendered": false,
  "isOrderedFlow": true,
  "documentLanguageCode": "tr",
  "timestampProvider": "dijital-imza",
  "saveAsDraft": false,
  "recipients": [
    {
      "externalId": "r1",
      "fullName": "Ayşe Yılmaz",
      "email": "[email protected]",
      "phone": "+905551112233",
      "role": "Signee",
      "order": 1,
      "recipientProfile": {
        "verification": {
          "phoneOtpVerification": true
        }
      }
    },
    {
      "externalId": "r2",
      "fullName": "Mehmet Demir",
      "email": "[email protected]",
      "phone": "+905559998877",
      "role": "Signee",
      "order": 2
    }
  ],
  "pages": [{ "pageNumber": 1, "width": 595, "height": 842 }],
  "elements": [
    {
      "externalId": "e-sig-1",
      "pageNumber": 1,
      "recipientExternalId": "r1",
      "elementType": "SIGNATURE",
      "x": 120,
      "y": 640,
      "width": 180,
      "height": 48,
      "config": { "required": true, "label": "İmza" }
    },
    {
      "externalId": "e-bio-2",
      "pageNumber": 1,
      "recipientExternalId": "r2",
      "elementType": "BIOMETRIC_SIGNATURE",
      "x": 120,
      "y": 720,
      "width": 180,
      "height": 48,
      "config": {
        "required": true,
        "label": "Biyometrik imza",
        "biometricSignatureType": "basic"
      }
    }
  ]
}

---

Şablon listesi — GET /developer/templates

Workspace’teki UI şablonlarını (/mytemplates) listeler. Yanıt şekli belge listesi ile aynıdır; items[].operationId şablon kimliğidir (templateOperationId).

Scope: documents:read.

Şablon detayı — GET /developer/templates/{templateOperationId}

Şablon iskeletini alıcılarla döndürür. from-template gönderiminden önce çağırın: kaç kişi, hangi role / order, vekil var mı, recipientExternalId (GUID) nedir.

Scope: documents:read. Yanıt şekli belge detayı ile aynıdır (operationType: template).

Şablondan gönder — POST /developer/documents/from-template/{templateOperationId}/send

Panelde oluşturulan şablondan tek istekte yeni belge üretir ve gönderimi başlatır. Create → PDF → configuration adımları gerekmez.

Scope: documents:create. Token workspace’i şablonun workspace’i ile aynı olmalıdır.

İstek alanları

recipients[]

Örnek istek

recipientExternalId: "r1" çalışmaz (configuration örneğidir). Şablon alıcı eşlemesi:

1. recipientExternalId = şablon alıcı GUID (DocumentRecipient.Id / panel externalId), veya
2. order ve role birlikte şablondakiyle aynı

deliveryPlans sayısı şablon alıcı sayısına eşitse sıra ile eşlenir (GUID zorunlu değil).

Tek alıcılı şablon örneği (privateNote, uyruk, vekil, OTP dahil):

{
  "isOrderedFlow": true,
  "privateNote": "ERP sipariş #4521 — iç not",
  "recipients": [
    {
      "order": 1,
      "role": "Signee",
      "fullName": "Ayşe Yılmaz",
      "email": "[email protected]",
      "phone": "+905551112233",
      "recipientProfile": {
        "firstName": "Ayşe",
        "lastName": "Yılmaz",
        "principalEmail": "[email protected]",
        "principalPhone": "+905551112233",
        "personCategory": "TurkishCitizen",
        "identityDocumentKind": "TcKimlik",
        "tcKimlikNo": "12345678901",
        "useRepresentativeForDelivery": true,
        "representative": {
          "personCategory": "TurkishCitizen",
          "identityDocumentKind": "TcKimlik",
          "tcKimlikNo": "10987654321",
          "firstName": "Mehmet",
          "lastName": "Demir",
          "email": "[email protected]",
          "phone": "+905559998877"
        },
        "verification": {
          "phoneOtpVerification": true
        }
      }
    }
  ],
  "deliveryPlans": [
    { "channels": ["email", "sms"] }
  ]
}

personCategory: TurkishCitizen | Foreign | Stateless. Vekil yoksa useRepresentativeForDelivery ve representative alanlarını göndermeyin.

İki alıcılı şablon: recipients ve deliveryPlans içinde şablondaki kadar kayıt gönderin (order: 1, order: 2 …).

Yanıt data

Şablon kimliği path’tedir; yanıt operationId üretilen belgenindir. Durum: GET /developer/documents/{operationId}.

Send — POST /developer/documents/{operationId}/send

İstek alanları

deliveryPlans[]

Örnek istek

{
  "isOrderedFlow": true,
  "deliveryPlans": [
    {
      "recipientExternalId": "r1",
      "channels": ["email", "sms"],
      "copyNotificationChannels": ["email"]
    },
    {
      "recipientExternalId": "r2",
      "channels": ["email"],
      "scheduledSendAtUtc": "2026-08-20T09:00:00Z"
    }
  ]
}

Kiosk örneği:

{
  "recipientExternalId": "r1",
  "channels": ["kiosk"],
  "kioskDeviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Yanıt data

{
  "enqueuedJobCount": 2,
  "initialRecipientAccessCode": "ABC12XYZ",
  "openOnThisDeviceForActiveRecipient": false
}

Imza linki: {appBase}/r/{initialRecipientAccessCode} — bkz. İmzalama akışı.

Liste yanıtı (data)

---

Detay yanıtı (data)

GET /developer/documents/{operationId} ve GET /developer/templates/{templateOperationId} aynı data şeklini döner.

recipients[] (detay)

Şablondan gönderirken her recipients[] öğesi için body’de bir kayıt doldurun (order+role veya recipientExternalId).