REST API iş akışı kılavuzu

Genel Bakış

Bu kılavuz, doküman imzalama iş akışlarını oluşturmak ve yönetmek için REST API'nin nasıl kullanılacağını açıklar. Platform, PDF dokümanlarla dijital imzaları destekler ve birden fazla alıcının dokümanları sırayla veya paralel olarak imzalamasına olanak tanır.

Temel Kavramlar

• İşler (Jobs): İmzalama iş akışı için kapsayıcı. Her işin bir tipi (ME_OTHERS veya SELF) ve durumu (NONE, DRAFT, IN_PROGRESS, COMPLETED) vardır.
• Dokümanlar (Documents): İmzalanması gereken PDF dosyaları.
• Alıcılar (Recipients): Dokümanları imzalaması gereken kişiler.
• Form Alanları (Form Fields): PDF'deki etkileşimli öğeler; imza alanları, metin kutuları, onay kutuları ve ek dosya listelerini içerir.
• Ek Dosyalar (Attachments): Ana PDF doküman içine gömülü ek dosyalar. Maksimum 15 ek dosya, her biri 40MB.

İş Yaşam Döngüsü

İşler, yaşam döngüleri boyunca farklı durumlardan geçer:

stateDiagram-v2
    [*] --> NONE: POST /jobs
    NONE --> DRAFT: PUT .../startrequestsignature
    DRAFT --> IN_PROGRESS: PUT .../finish
    IN_PROGRESS --> COMPLETED: Tüm imzalar toplandı
    COMPLETED --> [*]

    note right of NONE
        Başlangıç durumu
        Ek eklenip/çıkarılabilir
        Doküman yüklenebilir
    end note

    note right of DRAFT
        Yapılandırma aşaması
        Ek eklenip/çıkarılıp/güncellenebilir
        Alıcı eklenip/çıkarılabilir
        Form alanları eklenebilir
    end note

    note right of IN_PROGRESS
        İmzalama aşaması
        Ekler SALT OKUNUR
        Alıcılar bildirim alır
        İmzalar toplanıyor
    end note

    note right of COMPLETED
        Son durum
        Tüm imzalar toplandı
        Ekler SALT OKUNUR
        Doküman arşivlendi
    end note
                

Durum Açıklamaları

Durumlara Göre İşlemler

İş durumuna bağlı olarak farklı işlemlere izin verilir:

REST API Uç Noktaları

Tüm uç noktalar access_token header'ı ile kimlik doğrulama gerektirir. Temel URL: /rest

İş Yönetimi

curl -X POST "http://localhost:8080/agree/rest/jobs" \
  -H "access_token: $ACCESS_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "job_type=ME_OTHERS" \
  -d "name=Ekli Belgelerle Doküman İmzalama"

curl -X PUT "http://localhost:8080/agree/rest/jobs/$JOB_ID/actions/startrequestsignature" \
  -H "access_token: $ACCESS_TOKEN"

curl -X PUT "http://localhost:8080/agree/rest/jobs/$JOB_ID/actions/finish" \
  -H "access_token: $ACCESS_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "subject=Lütfen imzalayın: Ekli Belgeli Doküman" \
  --data-urlencode "message=Lütfen dokümanı inceleyin ve imzalayın."

Doküman Yönetimi

curl -X POST "http://localhost:8080/agree/rest/jobs/$JOB_ID/documents" \
  -H "access_token: $ACCESS_TOKEN" \
  -F "file=@/path/to/document.pdf;filename=sozlesme.pdf;type=application/pdf"

Ek Dosya Yönetimi

curl -X POST "http://localhost:8080/agree/rest/documents/$DOCUMENT_ID/attachments" \
  -H "access_token: $ACCESS_TOKEN" \
  -F "file=@/path/to/attachment.pdf;filename=kimlik.pdf;type=application/pdf" \
  -F "displayName=Nüfus Cüzdanı Belgesi"

curl -X GET "http://localhost:8080/agree/rest/documents/$DOCUMENT_ID/attachments" \
  -H "access_token: $ACCESS_TOKEN"

curl -X GET "http://localhost:8080/agree/rest/attachments/$ATTACHMENT_ID" \
  -H "access_token: $ACCESS_TOKEN" \
  -o indirilen-ek.pdf

Tam İş Akışı Örneği

Bu bölüm, gerçek test script'i test-attachments-signing-workflow.sh'e dayalı olarak, ekli belgelerle tam bir doküman imzalama iş akışını adım adım anlatır.

Ön Koşullar

# Access token'ınızı ayarlayın
ACCESS_TOKEN="your_access_token_here"

# Base URL'i ayarlayın
BASE_URL="http://localhost:8080/agree/rest"
# Veya production için:
# BASE_URL="https://imzayeri.com/api/rest"

Adım 1: İş Oluşturma (NONE Durumu)

Yeni bir imzalama işi oluşturun.

RESPONSE=$(curl -s -X POST "$BASE_URL/jobs" \
  -H "access_token: $ACCESS_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "job_type=ME_OTHERS" \
  -d "name=Ekli Belgelerle Doküman İmzalama")

JOB_ID=$(echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['id'])")
echo "Oluşturulan İş ID: $JOB_ID"

Sonuç: NONE durumu ile iş oluşturuldu

Adım 2: Doküman Yükleme

İmzalanacak ana PDF dokümanı yükleyin.

RESPONSE=$(curl -s -X POST "$BASE_URL/jobs/$JOB_ID/documents" \
  -H "access_token: $ACCESS_TOKEN" \
  -F "file=@/path/to/sozlesme.pdf;filename=sozlesme.pdf;type=application/pdf")

DOCUMENT_ID=$(echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['id'])")
echo "Yüklenen Doküman ID: $DOCUMENT_ID"

Adım 3: İmza İsteği Başlatma (NONE → DRAFT)

ME_OTHERS iş akışını başlatın.

RESPONSE=$(curl -s -X PUT "$BASE_URL/jobs/$JOB_ID/actions/startrequestsignature" \
  -H "access_token: $ACCESS_TOKEN")

JOB_STATUS=$(echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['status'])")
RECIPIENT0_ID=$(echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['recipients'][0]['id'])")
echo "İş Durumu: $JOB_STATUS"

Adım 4-7: Ek Dosyalar Ekleme (DRAFT Durumu)

Dokümana birden fazla ek ekleyin.

# PDF ek
curl -s -X POST "$BASE_URL/documents/$DOCUMENT_ID/attachments" \
  -H "access_token: $ACCESS_TOKEN" \
  -F "file=@/path/to/ornek.pdf" \
  -F "displayName=Nüfus Cüzdanı Belgesi"

# Büyük PDF (30MB)
curl -s -X POST "$BASE_URL/documents/$DOCUMENT_ID/attachments" \
  -H "access_token: $ACCESS_TOKEN" \
  -F "file=@/path/to/buyuk-dosya.pdf" \
  -F "displayName=İmza Sirküsü Belgesi (30MB Test)"

# DWG dosyası
curl -s -X POST "$BASE_URL/documents/$DOCUMENT_ID/attachments" \
  -H "access_token: $ACCESS_TOKEN" \
  -F "file=@/path/to/cizim.dwg" \
  -F "displayName=ÇAĞ Testere Tezgahı"

# PowerPoint dosyası
curl -s -X POST "$BASE_URL/documents/$DOCUMENT_ID/attachments" \
  -H "access_token: $ACCESS_TOKEN" \
  -F "file=@/path/to/sunum.ppt" \
  -F "displayName=DENİZ Savaş Sistemleri Belgesi"

Adım 8-10: Alıcıları Yapılandırma (DRAFT Durumu)

Varsayılan alıcıyı çıkarın ve iki yeni alıcı ekleyin.

# İlk alıcıyı sil
curl -s -X DELETE "$BASE_URL/recipients/$RECIPIENT0_ID" \
  -H "access_token: $ACCESS_TOKEN"

# İlk alıcıyı ekle
RESPONSE=$(curl -s -X POST "$BASE_URL/jobs/$JOB_ID/recipients" \
  -H "access_token: $ACCESS_TOKEN" \
  -d "name=Ahmet Yılmaz" \
  -d "email=ahmet.yilmaz@example.com")

# İkinci alıcıyı ekle ve HER İKİ yeni alıcı ID'sini çıkar
RESPONSE=$(curl -s -X POST "$BASE_URL/jobs/$JOB_ID/recipients" \
  -H "access_token: $ACCESS_TOKEN" \
  -d "name=Ayşe Kaya" \
  -d "email=ayse.kaya@example.com")

# ÖNEMLİ: Yanıt tüm alıcıları içeren tam iş nesnesini döner
# Eski RECIPIENT0_ID silindiği için, her ikisini de yeniden atıyoruz
RECIPIENT0_ID=$(echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['recipients'][0]['id'])")
RECIPIENT1_ID=$(echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['recipients'][1]['id'])")
echo "Alıcı 0 ID: $RECIPIENT0_ID"
echo "Alıcı 1 ID: $RECIPIENT1_ID"

Adım 11: Ek Dosya Listesi Alanı Ekleme

PDF'de tüm ekleri göstermek için özel bir alan ekleyin.

FORM_FIELDS="[{
  \"documentId\": $DOCUMENT_ID,
  \"recipientId\": $RECIPIENT0_ID,
  \"page\": 1,
  \"type\": \"file-list\",
  \"x\": 50,
  \"y\": 200,
  \"width\": 400,
  \"height\": 100,
  \"label\": \"Ekler\",
  \"enabled\": true,
  \"variable\": \"attachments_list\",
  \"orderno\": 0,
  \"required\": \"false\"
}]"

curl -s -X PUT "$BASE_URL/documents/$DOCUMENT_ID/fields" \
  -H "access_token: $ACCESS_TOKEN" \
  --data-urlencode "fields=$FORM_FIELDS"

Adım 12: İşin Tasarımını Bitirme (DRAFT → IN_PROGRESS)

Yapılandırmayı sonlandırın ve alıcılara gönderin.

curl -s -X PUT "$BASE_URL/jobs/$JOB_ID/actions/finish" \
  -H "access_token: $ACCESS_TOKEN" \
  -d "subject=Lütfen imzalayın: Ekli Belgeli Doküman" \
  --data-urlencode "message=Lütfen dokümanı inceleyin ve imzalayın."

Adım 13-14: İlk Alıcı İmzalıyor

Alıcı, e-posta ile bir link alır, tıklar, dokümanı inceler (ek listesi görünür) ve sertifikası veya mobil imzası ile imzalar.

Adım 15-16: İlk İmzadan Sonra Ekleri Doğrulama

İlk imzadan sonra eklerin hala mevcut ve erişilebilir olduğunu kontrol edin.

RESPONSE=$(curl -s -X GET "$BASE_URL/documents/$DOCUMENT_ID/attachments" \
  -H "access_token: $ACCESS_TOKEN")

ATTACHMENT_COUNT=$(echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['count'])")
echo "Ek sayısı: $ATTACHMENT_COUNT"

if [ "$ATTACHMENT_COUNT" -eq 4 ]; then
  echo "✓ İlk imzadan sonra tüm 4 ek hala mevcut"
fi

Adım 17-18: İkinci Alıcı İmzalıyor

İkinci alıcı da artık dokümanı imzalıyor (yine frontend üzerinden).

Sonuç: Tüm imzalar toplandı, iş COMPLETED durumuna geçti

Adım 19-20: Final Doğrulama (COMPLETED Durumu)

Eklerin tüm imzalama iş akışı boyunca devam ettiğini doğrulayın.

RESPONSE=$(curl -s -X GET "$BASE_URL/documents/$DOCUMENT_ID/attachments" \
  -H "access_token: $ACCESS_TOKEN")

ATTACHMENT_COUNT=$(echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['count'])")
echo "Final ek sayısı: $ATTACHMENT_COUNT"
echo "✓ Tüm ekler tam imzalama iş akışı boyunca devam etti"

Özel Özellikler

Ek Dosya Listesi Alanı (file-list)

Ek dosya listesi alanı, tüm doküman eklerini otomatik olarak doğrudan PDF içinde formatlanmış bir liste olarak gösteren özel bir form alanı tipidir.

Nasıl Çalışır:

1. Amaç: Ana doküman içinde tüm ekli dosyaların görsel bir referansını sağlar
2. Render: "Ekli Belgeler Listesi" başlığıyla numaralı bir liste oluşturur
3. İçerik: Her ekin displayName'ini gösterir
4. Kalıcılık: Liste, iş bittiğinde render edilir ve final imzalı PDF'de kalır

Yapılandırma Örneği:

FORM_FIELDS='[{
  "documentId": '$DOCUMENT_ID',
  "recipientId": '$RECIPIENT_ID',
  "page": 1,
  "type": "file-list",
  "x": 50,
  "y": 200,
  "width": 400,
  "height": 100,
  "label": "Ekler",
  "enabled": true,
  "variable": "attachments_list",
  "orderno": 0,
  "required": "false"
}]'

Önemli Notlar

Ek Kalıcılığı

• Gömme: Ekler PDFBox kütüphanesi kullanılarak fiziksel olarak PDF içine gömülür
• Kalıcılık: Bir kez gömüldükten sonra, ekler tüm aşamalarda devam eder
• İmzalama: Dijital imzalar ekleri kaldırmaz veya bozmaz
• Erişim: Ekler tüm aşamalarda indirilebilir durumda kalır

Karakter İşleme

Dosya Limitleri

Hata Kodları

HTTP Durum Kodları

• 200 OK: Başarılı istek
• 201 Created: Kaynak oluşturuldu
• 400 Bad Request: Geçersiz parametreler
• 403 Forbidden: İşlem yapılamaz
• 404 Not Found: Kaynak bulunamadı