Tek istekte belge gönderme

Harici entegrasyon için önerilen yol: PDF, alıcı bilgisi, imza/form alanları ve ayarları tek istekte gönderin.

Create → PDF → configuration → send adımlarını sunucu yürütür.

Auth: API anahtarı. Scope: documents:create.

Gelişmiş (adım adım) yüzey hâlâ durur: Belge gönderme akışı.

Şablondan gönderim: Şablon gönderme akışı.

Base path: /api/v1

Uç

POST /developer/documents/send

workspaceId gövdede istenmez; token workspace’i kullanılır.

Form alanları

Content-Type: multipart/form-data

curl örneği

curl -X POST "https://api.dijital-imza.com/api/v1/developer/documents/send" \
  -H "Authorization: Bearer dijital_imza_…" \
  -F "[email protected];type=application/pdf" \
  -F "[email protected];type=application/json"

payload.json örneği (önerilen — ayrık imza; PDF üzerinde konum gerekmez):

{
  "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"],
      "recipientProfile": {
        "verification": {
          "phoneOtpVerification": true
        }
      },
      "fields": [
        {
          "type": "SIGNATURE",
          "pageNumber": 0,
          "label": "İmza",
          "required": true,
          "config": {
            "isDetached": true
          }
        }
      ]
    }
  ]
}

Entegrasyonlarda en sık kullanılan model ayrık imzadır: pageNumber: 0 ve config.isDetached: true. x / y göndermeniz gerekmez; imza belge sonuna basılır.

Konumlu imza alanı (PDF sayfasına yerleştirme):

{
  "type": "SIGNATURE",
  "pageNumber": 1,
  "x": 120,
  "y": 640,
  "width": 180,
  "height": 48,
  "label": "İmza",
  "required": true
}

Ayarlar (settings)

displayFileName boşsa PDF dosya adı kullanılır (uyarı döner). pages gönderilmez; sayfalar alanlardaki pageNumber değerlerinden türetilir.

Alıcılar (recipients)

En az 1, en fazla 5 alıcı.

open_on_device diğer kanallar veya scheduledSendAtUtc ile birlikte seçilemez.

Kiosk gönderimi

1. GET /developer/kiosks ile cihaz listesini alın (scope: documents:read).
2. Yanıttaki id değerini alıcının kioskDeviceId alanına yazın.
3. channels içine yalnızca kiosk koyun (open_on_device ile birlikte seçilemez).

{
  "id": "r1",
  "fullName": "Ayşe Yılmaz",
  "role": "Signee",
  "order": 1,
  "channels": ["kiosk"],
  "kioskDeviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fields": [
    {
      "type": "SIGNATURE",
      "pageNumber": 1,
      "x": 120,
      "y": 640,
      "width": 180,
      "height": 48,
      "required": true
    }
  ]
}

Alanlar (fields)

Koordinatlar PDF sayfasında sol-üst köşeden piksel cinsindendir. Sayfa numarası 1 tabanlıdır.

Ayrık imza (PDF dışı doldurma): pageNumber: 0 — config.isDetached sunucuda açılır. width/height yoksa 180×48 varsayılır (uyarı).

Örnek ayrık alan:

{
  "type": "SIGNATURE",
  "pageNumber": 0,
  "label": "İmza",
  "required": true,
  "config": { "isDetached": true }
}

Alan tipi tablosu: Geliştirici belgeleri.

Hata ve uyarı

Doğrulama tüm hataları toplar; ilk hatada kesilmez. Gönderim yapılmaz.

Örnek hatalar: PDF boş veya .pdf değil; alıcı yok / 5’ten fazla; email kanalı var e-posta yok; hiç alan yok; konumlu alanda width/height ≤ 0.

Örnek uyarılar: displayFileName PDF adından alındı; alıcı id üretildi; order 1’den atandı.

Ara adım (yükleme / konfigürasyon / gönderim) başarısız olursa oluşturulan taslak silinir; yarım belge kalmaz.

Yanıt data

İmza linki: {appBase}/r/{code} — İmzalama akışı.

Durum: Durum takibi.