Süreç Yönetimi API¶

Dijital Belge Sistemi'nde belge işleme süreçlerini yönetmek için kullanılan API'dir.

Genel Bakış¶

Süreç, imzalama akışının yönetildiği merkezi bir birimdür. Bir süreç içinde:

Birden fazla döküman imzalanabilir veya yüklenebilir
Tüm imza akışları süreç altında gruplanır
İmzalama sayfasına yönlendirme yapılır
Benzersiz bir QR kodu otomatik olarak oluşturulur ve sayfaya basılır

Süreçler API aracılığıyla oluşturulabilir, yönetilebilir, başlatılabilir, tamamlanabilir veya iptal edilebilir.

Süreç Tipleri (processType)¶

Bir sürecin nasıl işleyeceğini processType alanı belirler. Süreç oluşturulurken bu alan gönderilmezse varsayılan olarak BELGE_IMZALAMA kullanılır.

Değer	Açıklama
`BELGE_IMZALAMA`	(Varsayılan) Belge üzerinde PDF imzalama işlemi yapılır. İmzacılar, dökümanı `DocumentSigningTask` üzerinden PDF olarak imzalar.
`DIJITAL_ONAY`	Metin tabanlı dijital onay işlemi yapılır. Onaylayan kişi metni onaylar; onay dosyası oluşturularak metne bağlanır.
`DOSYA_IMZALAMA`	Herhangi bir dosya türü (PDF, DOCX, XML vb.) CAdES ayrık imzayla imzalanır. Sürece eklenen tüm belgeler, tüm imzacılar tarafından imzalanır. Her imza ASiC-E (`.asice`) container'ı olarak ayrık şekilde saklanır. Ayrıntılar için Dosya İmzalama API sayfasına bakın.
`DIJITAL_KIMLIK_DOGRULAMA`	Belge imzalanmaz; bir kişinin kimliği TCKK NFC çip okuma + yüz/video doğrulama ile teyit edilir. İmzacı gizli bir "signing control" belgesine bağlanır, gerçek bir dosya üretilmez.

Varsayılan Değer

processType alanı "Yeni Süreç Oluştur" isteğinde gönderilmezse süreç otomatik olarak BELGE_IMZALAMA tipinde oluşturulur.

Özet¶

Özellik	Değer
Temel URL	`https://app.dijitalbelge.com/api`
Temel Path	`/external`
Base URL	`https://app.dijitalbelge.com/api/external`
Kimlik Doğrulama	X-Client-Id, X-Client-Secret

QR Kod Özelliği¶

Her oluşturulan sürecin otomatik olarak benzersiz bir QR kodu oluşturulur. Bu QR kod:

Sürecin kimliğini taşır ve güvenli bir şekilde kodlanır
İmzalama sayfasına basılabilir ve yazdırılan belgelerde yer alır
Mobil cihazlardan taranarak sürece hızlı erişim sağlar
Takip ve doğrulama amacıyla kullanılır

Endpoint Özeti¶

Method	Path	Scope	Açıklama
`POST`	`/process-instances`	`process:start`	Yeni süreç oluştur
`GET`	`/process-instances/{processId}`	`process:status`	Süreç detayını getir
`GET`	`/process-instances/{processId}/qr`	`process:status`	Doğrulama QR kodunu PNG olarak getir
`PUT`	`/process-instances/{processId}/status/start`	`process:start`	Süreci başlat
`PUT`	`/process-instances/{processId}/status/cancel`	`process:start`	Süreci iptal et
`PUT`	`/process-instances/{processId}/status/complete`	`process:start`	Süreci tamamla
`DELETE`	`/process-instances/{processId}`	`process:start`	Süreci sil
`POST`	`/process-instances/{processId}/autosign`	`autosign:write`	Bulut imzalamayı etkinleştir → detay
`DELETE`	`/process-instances/{processId}/autosign`	`autosign:write`	Bulut imzalamayı devre dışı bırak → detay

ℹ️ Döküman ekleme/silme, döküman dosyası indirme ve döküman imzacı yönetimi uç noktaları için bkz. Döküman API.

Süreç Yönetimi¶

1. Yeni Süreç Oluştur¶

Yeni bir belge işleme süreci oluşturur.

Scope: process:start

İstek¶

POST {baseURL}/process-instances

Content-Type: application/json

Request Body¶

{
  "name": "test süreci",
  "processType": "BELGE_IMZALAMA",
  "expiresAt": "2026-10-15T18:00:00"
}

Alan	Tip	Zorunlu	Açıklama
`name`	string	Hayır	Sürecin adı
`processType`	string	Hayır	Süreç tipi. Gönderilmezse varsayılan olarak `BELGE_IMZALAMA` kullanılır. Olası değerler için Süreç Tipleri bölümüne bakın.
`expiresAt`	string	Hayır	Sürecin son geçerlilik tarihi (ISO 8601, saat dilimi eki olmadan, Türkiye saati). Bu zamana kadar tamamlanmayan süreç otomatik iptal edilir. Gönderilmezse süreç süresiz açık kalır. Bkz. Geçerlilik Süresi

Başarılı Yanıt¶

HTTP 201 Created

{
  "id": 147,
  "accountId": 202,
  "createdByUserId": null,
  "name": "Test Süreci",
  "statusCode": "NEW",
  "processType": "BELGE_IMZALAMA",
  "signers": [],
  "documents": [],
  "createdAt": "2026-01-05T19:59:29.5282888",
  "updatedAt": "2026-01-05T19:59:29.5282888",
  "responsibleBy": null,
  "accessToken": "kQQQioa",
  "tokenExpiry": null,
  "expiresAt": "2026-10-15T18:00:00",
  "startedAt": null,
  "completedAt": null
}

Alan	Tip	Açıklama
`id`	number	Sürecin benzersiz ID'si
`accountId`	number	Hesap ID'si
`createdByUserId`	number	Süreci oluşturan kullanıcı ID'si
`name`	string	Sürecin adı
`statusCode`	string	Sürecin durum kodu (`NEW`, `STARTED`, `IN_PROGRESS`, `COMPLETED`, `ARCHIVED`, `CANCELED`, `DELETED`)
`processType`	string	Süreç tipi (bkz. Süreç Tipleri). Belirtilmemişse `BELGE_IMZALAMA`
`signers`	array	İmzalayıcılar listesi
`documents`	array	Belgeler listesi
`createdAt`	string	Oluşturulma tarihi (ISO 8601)
`updatedAt`	string	Son güncellenme tarihi (ISO 8601)
`responsibleBy`	string	Sorumlu kişi
`accessToken`	string	Erişim token'ı
`tokenExpiry`	string	Token geçerlilik süresi
`expiresAt`	string \| null	Sürecin son geçerlilik tarihi; `null` ise süresiz
`startedAt`	string \| null	Sürecin başlatıldığı an (`STARTED`'a ilk geçiş)
`completedAt`	string \| null	Sürecin tamamlandığı an. Tamamlanma süresi = `completedAt − startedAt`

Örnek cURL¶

curl -X POST https://app.dijitalbelge.com/api/external/process-instances \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx" \
  -d '{
    "name": "test süreci"
  }'

2. Süreç Detayını Getir¶

Belirtilen sürecin imzacı ve döküman bilgileriyle birlikte detaylı bilgilerini döndürür.

Scope: process:status

İstek¶

GET {baseURL}/process-instances/{processId}

Path Parameters:

Parametre	Tip	Açıklama
`processId`	number	Sürecin ID'si

Başarılı Yanıt¶

HTTP 200 OK

{
  "id": 147,
  "accountId": 202,
  "createdByUserId": null,
  "name": "Test Süreci",
  "statusCode": "IN_PROGRESS",
  "signers": [
    {
      "id": 1,
      "name": "İmzacı 1",
      "email": "[email protected]",
      "signedAt": null
    }
  ],
  "documents": [
    {
      "id": 101,
      "name": "Sözleşme.pdf",
      "uploadedAt": "2026-01-05T19:59:29Z"
    }
  ],
  "createdAt": "2026-01-05T19:59:29.5282888",
  "updatedAt": "2026-01-05T19:59:29.5282888",
  "responsibleBy": null,
  "accessToken": "kQQQioa",
  "tokenExpiry": null,
  "expiresAt": "2026-10-15T18:00:00",
  "startedAt": "2026-10-01T09:12:44",
  "completedAt": null
}

Örnek cURL¶

curl -X GET https://app.dijitalbelge.com/api/external/process-instances/147 \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx"

3. Süreci Başlat¶

Belirtilen süreci başlatır. Başlatılan süreç imzacılara bildirim gönderir.

Scope: process:start

İstek¶

PUT {baseURL}/process-instances/{processId}/status/start

Path Parameters:

Parametre	Tip	Açıklama
`processId`	number	Sürecin ID'si

Başarılı Yanıt¶

HTTP 200 OK

ok

Örnek cURL¶

curl -X PUT https://app.dijitalbelge.com/api/external/process-instances/147/status/start \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx"

4. Süreci İptal Et¶

Belirtilen süreci iptal eder.

Scope: process:start

İstek¶

PUT {baseURL}/process-instances/{processId}/status/cancel

Path Parameters:

Parametre	Tip	Açıklama
`processId`	number	Sürecin ID'si

Başarılı Yanıt¶

HTTP 200 OK

ok

Örnek cURL¶

curl -X PUT https://app.dijitalbelge.com/api/external/process-instances/147/status/cancel \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx"

5. Süreci Tamamla¶

Belirtilen süreci tamamlanmış duruma alır.

Scope: process:start

İstek¶

PUT {baseURL}/process-instances/{processId}/status/complete

Path Parameters:

Parametre	Tip	Açıklama
`processId`	number	Sürecin ID'si

Başarılı Yanıt¶

HTTP 200 OK

ok

Örnek cURL¶

curl -X PUT https://app.dijitalbelge.com/api/external/process-instances/147/status/complete \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx"

6. Süreci Sil¶

Belirtilen süreci sistemden siler.

Scope: process:start

İstek¶

DELETE {baseURL}/process-instances/{processId}

Path Parameters:

Parametre	Tip	Açıklama
`processId`	number	Silinecek sürecin ID'si

Başarılı Yanıt¶

HTTP 200 OK

(boş)

Örnek cURL¶

curl -X DELETE https://app.dijitalbelge.com/api/external/process-instances/147 \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx"

7. Doğrulama QR Kodunu Getir (PNG)¶

Belgeye gömülen doğrulama QR'ının PNG görselini döndürür. Entegratör kendi doğrulama ekranında dökümanla aynı QR'ı göstermek için kullanabilir.

Scope: process:status

İstek¶

GET {baseURL}/process-instances/{processId}/qr?size=300

Query Parameters:

Parametre	Tip	Varsayılan	Açıklama
`size`	number	`300`	PNG kenar uzunluğu (px)

Başarılı Yanıt¶

HTTP 200 OK — Content-Type: image/png (ham PNG byte'ları).

Örnek cURL¶

curl -X GET "https://app.dijitalbelge.com/api/external/process-instances/147/qr?size=300" \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx" \
  --output surec-147-qr.png

Döküman ve Döküman İmzacı Yönetimi¶

Sürece döküman ekleme/silme, döküman ve ilişkili dosyaları (kanıt/ek) indirme ve döküman bazlı imzacı yönetimi işlemleri ayrı bir sayfaya taşınmıştır: Döküman API.

Otomatik İmzalama¶

Bulut İmzalama (Autosign) endpoint'leri bu sayfadan ayrılmış olup ayrıntılar için Bulut İmzalama (Autosign) sayfasını inceleyin.

Süreç Durumları¶

Durum	Açıklama
`NEW`	İlk oluşturulduğunda atanan durum
`STARTED`	Başlayınca imzacılara bildirim gider
`IN_PROGRESS`	İlk imzacı imzaladığında süreç devam ediyor durumuna geçer
`COMPLETED`	Tüm imzacılar imzalamayı tamamladığında süreç tamamlanır
`ARCHIVED`	Tamamlanan süreçler, arşiv hizmeti alınmış ise arşive taşınır
`CANCELED`	Süreç iptal edilmiş durumda (elle ya da geçerlilik süresi dolduğu için)
`DELETED`	Süreç silinmiş durumda

Geçerlilik Süresi (Son Tarih)¶

Süreç oluştururken (POST /process-instances) ya da taslaktan başlatırken (POST /process-definitions/{definitionId}/start) isteğe bağlı expiresAt gönderilebilir.

Biçim: ISO 8601, saat dilimi eki olmadan ("2026-10-15T18:00:00"); değer Türkiye saati (Europe/Istanbul) olarak yorumlanır.
Süre dolunca: Bu zamana kadar sonuçlanmamış (COMPLETED, CANCELED, ARCHIVED, DELETED dışındaki) süreç otomatik olarak CANCELED yapılır. Kontrol 5 dakikada bir çalışır; iptal son tarihten en geç birkaç dakika sonra gerçekleşir.
Webhook: Otomatik iptalde de elle iptaldeki gibi PROCESS_STATUS_CHANGED (newStatus: "CANCELED") olayı gönderilir (bkz. Webhook).
Süresiz: expiresAt gönderilmezse süreç süresiz açık kalır (önceki davranış).
Geçmiş tarih: Şimdiden önceki bir tarih 400 Bad Request ile reddedilir ("Geçerlilik süresi ileri bir tarih olmalıdır").

Yanıttaki startedAt / completedAt alanlarıyla sürecin ne kadar sürede tamamlandığını hesaplayabilirsiniz.

Hata Yanıtları¶

400 Bad Request¶

{
  "error": "INVALID_REQUEST",
  "message": "Request parametreleri hatalı"
}

401 Unauthorized¶

{
  "error": "UNAUTHORIZED",
  "message": "Geçersiz veya eksik kimlik doğrulama"
}

403 Forbidden¶

{
  "error": "FORBIDDEN",
  "message": "Bu işlem için yeterli yetki yok veya IP adresi yetkisiz"
}

404 Not Found¶

{
  "error": "NOT_FOUND",
  "message": "İstenilen süreç bulunamadı"
}

409 Conflict¶

{
  "error": "CONFLICT",
  "message": "Sürecin mevcut durumunda bu işlem gerçekleştirilemez"
}

500 Internal Server Error¶

{
  "error": "INTERNAL_ERROR",
  "message": "Sunucuda bir hata oluştu"
}

Kullanım Örnekleri¶

Tam Akış Örneği¶

# 1. Yeni süreç oluştur
PROCESS_ID=$(curl -s -X POST https://app.dijitalbelge.com/api/external/process-instances \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx" \
  -d '{"name":"test süreci"}' | jq -r '.id')

# 2. Dökümana imzacı ekle
curl -X POST https://app.dijitalbelge.com/api/external/process-instances/$PROCESS_ID/document/7203/signers \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx" \
  -d '{"signerId": 138, "order": 1}'

# 3. Süreci başlat
curl -X PUT https://app.dijitalbelge.com/api/external/process-instances/$PROCESS_ID/status/start \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx"

# 4. Süreci tamamla
curl -X PUT https://app.dijitalbelge.com/api/external/process-instances/$PROCESS_ID/status/complete \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx"

Kimlik Doğrulama¶

DijitalBelge External API'ye yapılan tüm istekler entegrasyon bazlı kimlik doğrulama ile korunmaktadır. API'yi kullanabilmek için size özel ClientId ve ClientSecret bilgileri gerekmektedir.

Yetkilendirme Header'ları¶

Tüm API isteklerine aşağıdaki header'ları eklemeniz zorunludur:

Header	Açıklama
`X-Client-Id`	Entegrasyon Client ID
`X-Client-Secret`	Entegrasyon Client Secret

Warning

X-Client-Secret bilgisi gizli tutulmalı ve herkese açık ortamlarda saklanmamalıdır.

Örnek İstekler¶

cURLJavaJavaScriptPython

curl -X POST https://app.dijitalbelge.com/api/external/process-instances \
  -H "X-Client-Id: app_xxxxx" \
  -H "X-Client-Secret: secret_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"test süreci"}'

HttpHeaders headers = new HttpHeaders();
headers.set("X-Client-Id", "app_xxxxx");
headers.set("X-Client-Secret", "secret_xxxxx");

fetch("https://app.dijitalbelge.com/api/external/process-instances", {
  method: "POST",
  headers: {
    "X-Client-Id": "app_xxxxx",
    "X-Client-Secret": "secret_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({name: "test süreci"})
});

import requests

headers = {
    "X-Client-Id": "app_xxxxx",
    "X-Client-Secret": "secret_xxxxx"
}

requests.post(
    "https://app.dijitalbelge.com/api/external/process-instances",
    headers=headers,
    json={"name": "test süreci"}
)

Daha fazla bilgi için Kimlik Doğrulama sayfasını ziyaret edin.

Sınırlamalar¶

Her API çağrısı için maksimum 30 saniye timeout vardır
Dakika başına maksimum 100 istek yapılabilir
Süreç adı maksimum 255 karakterden oluşabilir

Süreç Yönetimi API¶

Genel Bakış¶

Süreç Tipleri (processType)¶

Özet¶

QR Kod Özelliği¶

Endpoint Özeti¶

Süreç Yönetimi¶

1. Yeni Süreç Oluştur¶

İstek¶

Request Body¶

Başarılı Yanıt¶

Örnek cURL¶

2. Süreç Detayını Getir¶

İstek¶

Başarılı Yanıt¶

Örnek cURL¶

3. Süreci Başlat¶

İstek¶

Başarılı Yanıt¶

Örnek cURL¶

4. Süreci İptal Et¶

İstek¶

Başarılı Yanıt¶

Örnek cURL¶

5. Süreci Tamamla¶

İstek¶

Başarılı Yanıt¶

Örnek cURL¶

6. Süreci Sil¶

İstek¶

Başarılı Yanıt¶

Örnek cURL¶

7. Doğrulama QR Kodunu Getir (PNG)¶

İstek¶

Başarılı Yanıt¶

Örnek cURL¶

Döküman ve Döküman İmzacı Yönetimi¶

Otomatik İmzalama¶

Süreç Durumları¶

Geçerlilik Süresi (Son Tarih)¶

Hata Yanıtları¶

400 Bad Request¶

401 Unauthorized¶

403 Forbidden¶

404 Not Found¶

409 Conflict¶

500 Internal Server Error¶

Kullanım Örnekleri¶

Tam Akış Örneği¶

Kimlik Doğrulama¶

Yetkilendirme Header'ları¶

Örnek İstekler¶

Sınırlamalar¶

İlgili Kaynaklar¶