imzala / imzala-php
imzala.org server-side SDK — templates, demands, embedded signing, timestamps, webhook verification.
Requires
- php: ^8.1
- ext-json: *
- guzzlehttp/guzzle: ^7.8
Requires (Dev)
- phpunit/phpunit: ^10.5 || ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
İmzala dijital imza platformunun resmi PHP SDK'sı. Sözleşme oluşturma, imza takibi, imzalı PDF ve sertifika indirme, denetim izi, şablon yönetimi ve zaman damgası işlemlerini tek bir tip-güvenli istemciyle yapın.
composer require imzala/imzala-php
Sunucu-taraflı paket. API anahtarınız hesabınızın tamamına erişir; tarayıcıya veya mobil uygulamaya gömmeyin. Tarayıcıda imza almak için
@imzala/embedkullanın. Ayrıntı: Sunucu-taraflı bölümü.
İçindekiler
- Gereksinimler
- Hızlı başlangıç
- Yapılandırma
- API referansı
- İmzalı PDF ve sertifika (binary)
- Otomatik yeniden deneme
- Sayfalama
- Webhook doğrulama
- Hata yönetimi
- Sık karşılaşılan hatalar
- Sürüm uyumu
- Sunucu-taraflı
- İmza sınıfı
Gereksinimler
- PHP 8.1+,
ext-jsonetkin imz_ile başlayan bir API anahtarı: Panel, Geliştirici, API Anahtarları
Hızlı başlangıç
<?php use Imzala\ImzalaClient; $imzala = new ImzalaClient(getenv('IMZALA_API_KEY')); // 1) Şablonları listele, birini seç $templates = $imzala->templates()->list(); $template = $templates->getTemplates()[0]; // 2) Şablondan sözleşme oluştur (imza daveti otomatik gider) $demand = $imzala->demands()->create([ 'template_id' => $template->getId(), 'party_mapping' => [ [ 'template_party_id' => $template->getParties()[0]->getId(), 'first_name' => 'Ayşe', 'last_name' => 'Yılmaz', 'email' => 'ayse@example.com', 'phone' => '+905551112233', ], ], ]); print_r($demand->getSigningUrls()); // her taraf için imzalama linki // 3) Durumu takip et $status = $imzala->demands()->get($demand->getId()); echo $status->getStatus() . "\n"; // 4) Tamamlanınca imzalı PDF'i indir if ((string) $status->getStatus() === 'COMPLETED') { file_put_contents('sozlesme.pdf', $imzala->demands()->getPdf($demand->getId())); }
Yapılandırma
Constructor konumsal veya isimli argümanlarla çağrılabilir:
<?php use Imzala\ImzalaClient; $imzala = new ImzalaClient( apiKey: getenv('IMZALA_API_KEY'), baseUrl: 'https://api-prd.imzala.org', // varsayılan; test için test-api.imzala.org timeoutSeconds: 30.0, // istek başına zaman aşımı (varsayılan 30sn) maxRetries: 2, // güvenli GET'ler için (varsayılan 2, 0 = kapalı) retryBaseDelayMs: 300, // backoff temel gecikmesi (varsayılan 300ms) );
| Seçenek | Tip | Varsayılan | Açıklama |
|---|---|---|---|
apiKey |
string |
(zorunlu) | imz_<64 hex> |
baseUrl |
string |
https://api-prd.imzala.org |
Test: https://test-api.imzala.org |
timeoutSeconds |
float |
30.0 |
Guzzle istek zaman aşımı (saniye) |
maxRetries |
int |
2 |
Yalnızca GET'ler; 0 kapatır (bkz. Otomatik yeniden deneme) |
retryBaseDelayMs |
int |
300 |
Exponential backoff temel gecikmesi |
API anahtarı ve Idempotency-Key değerleri yazdırılabilir ASCII olmalıdır; dosyadan okunan anahtarın sonundaki satır sonu gibi karakterler istek gönderilmeden ImzalaValidationException fırlatır (getStatusCode() null).
X-Workspace-Id başlığı için bir seçenek yoktur: organizasyon içinde üretilmiş anahtar kendi organizasyonuna bağlıdır, ayrıca başlık gerekmez. Kişisel anahtarla bir organizasyon adına çalışmak bu sürümde desteklenmez.
API referansı
Tüm resource metodları { success, data } zarfını açar ve data'yı (vendored generated model nesnesi) döndürür; hata durumunda tipli bir ImzalaException fırlatır (bkz. Hata yönetimi). Resource'lara metod çağrısıyla erişilir: $imzala->demands(), $imzala->templates(), $imzala->fieldTemplates(), $imzala->contacts(), $imzala->reports(), $imzala->embed(), $imzala->timestamps().
Sözleşmeler (demands)
| Metod | Açıklama | Retry |
|---|---|---|
demands()->create($body, $idempotencyKey?) |
Şablondan sözleşme oluştur + imza daveti gönder (dispatch_notifications: false ile sessiz taslak) |
Anahtar varsa 429'da 1 kez |
demands()->createBulk($body) |
Tek istekte en çok 10 sözleşme; her satır bağımsız, failed sayısını ve her satırın durumunu kontrol edin |
❌ POST |
demands()->uploadDocument($params) |
Şablonsuz, dosya yükleyerek sözleşme (1 PDF/DOC ya da 1-20 görsel) | Anahtar varsa 429'da 1 kez |
demands()->list($status?, $q?, $from?, $to?, $templateId?, $page?, $limit?, $sort?, $archived?) |
Sözleşme listesi (counts-only, taraf PII'siz); $sort biçimi alan:yön (ör. createdAt:desc); $archived: 'exclude' / 'only' / 'include' (verilmezse include) |
✅ GET |
demands()->get($id) |
Sözleşme detayı + taraf imza durumu (maskeli) | ✅ GET |
demands()->getPdf($id) |
İmzalı sözleşme PDF'i → ham bayt (string) |
GET (binary, retry yok) |
demands()->getDocumentPdf($id, $documentId) |
Çok belgeli zarfta tek belgenin imzalı PDF'i → ham bayt (string) |
GET (binary, retry yok) |
demands()->getCertificate($id, $lang?) |
Tamamlanma sertifikası (PAdES B-T) → ham bayt (string) |
GET (binary, retry yok) |
demands()->getTimeline($id) |
İmza denetim izi (maskeli olaylar) | ✅ GET |
demands()->cancel($id, $body?) |
Bekleyen sözleşmeyi iptal et | ❌ POST |
demands()->resendParty($id, $partyId) |
Tekil tarafa daveti tekrar gönder | ❌ POST |
demands()->delete($id) |
Tamamlanmamış sözleşmeyi sil | ❌ DELETE |
demands()->addItems($id, $body) |
Sayfa alanlarını (imza/form) yerleştir (PAGE_ID_REQUIRED, INVALID_ITEM_TYPE) |
❌ POST |
demands()->updateStamp($id, $itemId, $body) |
Tek bir kaşe alanını StampData ile doldur (kısmi güncelleme: null/'' alanı kaldırır, gönderilmeyen korunur; DEMAND_PARTIALLY_SIGNED) |
❌ PATCH |
demands()->updateTerm($id, $body) |
Süre ve yenileme takibini güncelle (kısmi: gönderilen anahtar yazılır, null temizler, gönderilmeyen korunur; TERM_INVALID, DEMAND_ARCHIVED) |
❌ PATCH |
demands()->archive($id) / demands()->unarchive($id) |
Tamamlanmış, iptal edilmiş veya süresi dolmuş sözleşmeyi arşivle / arşivden çıkar (durum değişmez; arşivdeki sözleşme değiştirilemez ve silinemez) | ❌ POST |
demands()->sendReminder($id, $body?) |
İmzalamamış taraflara hatırlatma (5 dk pencerede RATE_LIMITED, ['force' => true] aşar) |
❌ POST |
demands()->dispatch($id, $sendInvitations?) |
Sessiz hazırlanmış sözleşmeyi yayına al, davetleri gönder | ❌ POST |
<?php // Filtreli liste (isimli argümanlar) $list = $imzala->demands()->list(status: 'PENDING', limit: 20, sort: 'createdAt:desc'); foreach ($list->getDemands() ?? [] as $d) { echo $d->getId() . ' [' . $d->getStatus() . '] ' . $d->getPartiesSigned() . '/' . $d->getPartiesTotal() . "\n"; } // İptal (düz array ya da typed request) $imzala->demands()->cancel($id, ['reason' => 'Anlaşma değişti']); // Denetim izi (maskeli olaylar) $timeline = $imzala->demands()->getTimeline($id); // Tekil tarafa daveti tekrar gönder $imzala->demands()->resendParty($id, $partyId); // Tamamlanmamış sözleşmeyi sil (COMPLETED sözleşme 409 döner, panelden silinir) $imzala->demands()->delete($id);
Şablonsuz (dosya yükleyerek) sözleşme oluşturma FileInput + UploadDemandParams kullanır. SDK içeride geçici bir dosyaya yazıp temizler; çağıran taraf dosya sistemiyle uğraşmaz:
<?php use Imzala\FileInput; use Imzala\UploadDemandParams; use Imzala\UploadPartyInput; $params = new UploadDemandParams( files: [new FileInput(file_get_contents('sozlesme.pdf'), 'sozlesme.pdf', 'application/pdf')], parties: [new UploadPartyInput('Ayşe', 'Yılmaz', 'ayse@example.com', '+905551112233')], ); $demand = $imzala->demands()->uploadDocument($params->withTitle('Hizmet Sözleşmesi')); // Tekrar-güvenli oluşturma: aynı anahtarla ikinci istek ikinci sözleşme üretmez $created = $imzala->demands()->create($body, idempotencyKey: "siparis-{$orderId}"); // Alan Şablonu ile yükleme: her tarafta templatePartyId zorunludur $uploaded = $imzala->demands()->uploadDocument( (new UploadDemandParams( files: [new FileInput($pdfBytes, 'sozlesme.pdf')], parties: [new UploadPartyInput('Ayşe', 'Yılmaz', 'ayse@example.com', null, $partyTemplateId)], )) ->withFieldTemplateId($fieldTemplateId) ->withOnAnchorMiss('block') // çapa bulunamazsa sözleşme oluşturulmaz, kredi düşmez ->withIdempotencyKey("yukleme-{$orderId}") );
UploadDemandParams diğer seçenekleri: withSendInvitations() (bu uçta varsayılan kapalı; 'sms' SMS ve WhatsApp'ı kapsar, yalnız daraltır) ve withForce().
Şablonun hangi belgelerinin gönderileceğini seçme. İstekteki documents alanı şablonun varsayılanını bu isteğe özel değiştirir: include varsayılanı kapalı bir belgeyi ekler, exclude varsayılanı açık bir belgeyi çıkarır (her liste en çok 20 kimlik). Kimlikler templates()->get($id)->getDocuments() içinden gelir. Alanı hiç göndermezseniz şablonun varsayılanı gider; davranış eskisiyle birebir aynıdır. Çıkarılan belge bu imza sürecine hiç girmez: imzacıya gösterilmez, imzalı PDF'te ve tamamlanma sertifikasında yer almaz, kredi hesabına katılmaz. Mevzuat gereği karşı tarafa verilmesi gereken bir belgeyi (ör. doc_kind: PREINFO ya da KVKK_NOTICE) başka bir kanaldan vermiyorsanız çıkarmayın; bu yükümlülük sözleşmeyi gönderene aittir.
<?php use Imzala\Client\Model\DocumentSelectionInput; $template = $imzala->templates()->get($templateId); $kvkk = null; foreach ($template->getDocuments() as $document) { if ($document->getDocKind() === 'KVKK_NOTICE') { $kvkk = $document; } } $demand = $imzala->demands()->create([ 'template_id' => $templateId, 'party_mapping' => [[ 'template_party_id' => $roleId, 'first_name' => 'Ayşe', 'last_name' => 'Yılmaz', 'email' => 'ayse@example.com', ]], // varsayılanı kapalı belgeyi bu isteğe ekle 'documents' => new DocumentSelectionInput(['include' => [$kvkk->getId()]]), ]); // Toplu uçta seçim satır başınadır (batch geneli `options.documents` reddedilir) $imzala->demands()->createBulk([ 'template_id' => $templateId, 'rows' => [['party_mapping' => [...], 'documents' => ['exclude' => [$ekId]]]], ]);
Geçersiz seçim INVALID_DOCUMENT_SELECTION (400) fırlatır; details.reason nedeni verir: shape, unknown_document, conflict, empty. Eşlediğiniz bir role hiç belge kalmazsa PARTY_WITHOUT_DOCUMENTS (409) döner ve sözleşme oluşmaz.
Çok belgeli zarf (documents, dispatch)
Bir sözleşme dispatch_notifications: false ile sessizce oluşturulur, belgeler eklenir, sonra tek çağrıyla yayına alınır. Belge uçları kimseye bildirim göndermez ve kredi düşmez; kredi yalnız dispatch anında düşer.
| Metod | Açıklama | Retry |
|---|---|---|
demands()->documents()->list($demandId, $view?) |
Zarftaki belgeler ('wizard' atama ve karar sayılarını da verir) |
✅ GET |
demands()->documents()->create($demandId, $body) |
Mevcut bir belgeyi zarfa ekle | ❌ POST |
demands()->documents()->upload($demandId, $file, $title, $idempotencyKey, $docKind?, $isRequired?) |
Dosya yükleyerek belge ekle; $idempotencyKey zorunlu |
429'da 1 kez |
demands()->documents()->update($demandId, $docId, $body) |
Başlık / zorunluluk bayrakları | ❌ PATCH |
demands()->documents()->delete($demandId, $docId) |
Belgeyi kaldır (son belge silinemez) | ❌ DELETE |
demands()->documents()->reorder($demandId, $documentIds) |
Belge sırası (kimlik kümesi birebir eşleşmeli) | ❌ PUT |
demands()->documents()->setAssignments($demandId, $docId, $partyIds) |
Belgeyi imzalayacak taraflar | ❌ PUT |
demands()->dispatch($demandId, $sendInvitations?) |
Zarfı yayına al (bool ya da 'email' / 'sms' gibi bir string) |
❌ POST |
upload aynı $idempotencyKey ile tekrar çağrılırsa yeni belge oluşmaz; sunucunun 409 IDEMPOTENT_REPLAY yanıtı normal sonuç olarak (mevcut belge) döner. Özellik hesabınızda açık değilse her belge metodu ENVELOPE_MULTI_DOC_DISABLED fırlatır; list boş liste döndürmez.
Şablonlar (templates)
| Metod | Açıklama | Retry |
|---|---|---|
templates()->list($page?, $limit?) |
Aktif şablonlar (tek sayfa) | ✅ GET |
templates()->listAll($page?, $limit?) |
Tüm şablonları gezen generator (bkz. Sayfalama) | ✅ GET |
templates()->get($id) |
Şablon detayı + taraflar + doldurulabilir alanlar + zarf belgeleri (documents) |
✅ GET |
templates()->usage($id) |
API kullanım kılavuzu (curl + JSON örneği) | ✅ GET |
templates()->update($id, $body) |
Şablon metadata güncelle (name / description / category) | ❌ PATCH |
templates()->delete($id) |
Şablonu sil; kayıt 30 gün saklanır, mevcut sözleşmeler etkilenmez. Aktif (taslak veya imza bekleyen) sözleşmesi olan şablon silinemez (409 TEMPLATE_IN_USE) |
❌ DELETE |
<?php // Metadata güncelle (düz array ya da typed request) $imzala->templates()->update($templateId, ['name' => 'Yeni Ad', 'category' => 'HR']); // Şablon sil $imzala->templates()->delete($templateId);
Şablon detayında gönderenin kaşesi (item_type: stamp) varsayılan olarak variables listesinde yer almaz; listelemek için isteğe bağlı include değerini verin. Değer verilmezse istek eskisiyle birebir aynıdır. Kaşe slug'ına değer göndermek için include gerekmez.
$template = $imzala->templates()->get($templateId, include: 'stamp_variables');
templates()->list() Alan Şablonlarını listelemez ve templates()->get() bir Alan Şablonu kimliğine 404 döner; onlar için aşağıdaki fieldTemplates() kaynağını kullanın.
Alan Şablonları (fieldTemplates)
| Metod | Açıklama | Retry |
|---|---|---|
fieldTemplates()->list($page?, $limit?) |
Alan Şablonları (tek sayfa) | ✅ GET |
fieldTemplates()->get($id) |
Alan Şablonu detayı | ✅ GET |
fieldTemplates()->previewLayout($id, $files, $onAnchorMiss?) |
Yerleşimi tam bir PDF üzerinde kuru koşumla dener; sözleşme oluşturmaz, kredi harcamaz | ❌ POST |
<?php $preview = $imzala->fieldTemplates()->previewLayout( $fieldTemplateId, [new FileInput($pdfBytes, 'sozlesme.pdf')], 'drop', // verilmezse sunucu 'block' uygular );
Kişiler (contacts)
| Metod | Açıklama | Retry |
|---|---|---|
contacts()->list($q?, $page?, $limit?, $sort?, $companyId?, $archived?) |
Kişiler (tek sayfa); $limit 10 ile 100 arası, $sort biçimi -createdAt (- öneki azalan) |
✅ GET |
contacts()->listAll(...) |
Tüm kişileri gezen generator | ✅ GET |
contacts()->create($body) |
Kişi oluştur (CONTACT_DUPLICATE: aynı e-posta veya telefon zaten var) |
❌ POST |
Üretilmiş istemci $limit aralığını (10..100) istek gönderilmeden denetler; aralık dışı değer ImzalaValidationException fırlatır.
Raporlar (reports)
<?php $report = $imzala->reports()->get(); // sözleşme durumlarının toplu sayımı; parametre almaz
Gömülü imza (embed)
<?php $session = $imzala->embed()->createSession($demandId, $partyId); echo $session->getEmbedUrl(); // bir <iframe>'e gömün (bkz. @imzala/embed)
$partyId, sözleşmenin create/get yanıtındaki signing_urls[].party_id'sidir. Gömülü imza, 5070 sayılı Kanun m.3 anlamında elektronik imzadır; güvenli elektronik imza değildir ve AB hukuku bakımından gelişmiş veya nitelikli imza olarak sunulmaz. Tarayıcı tarafı için @imzala/embed.
Zaman damgası (timestamps)
<?php use Imzala\CreateTimestampParams; $params = (new CreateTimestampParams(file_get_contents('belge.pdf'), 'belge.pdf')) ->withIdempotencyKey('unique-key') // tekrarları güvenli yapar (5dk pencere) ->withDescription('Sözleşme taslağı'); $ts = $imzala->timestamps()->create($params); echo $ts->getTimestampTime() . ', ' . $ts->getTsaAuthority(); $listing = $imzala->timestamps()->list(status: 'COMPLETED', sort: '-createdAt'); // limit 10..100 $one = $imzala->timestamps()->get($ts->getId());
TÜBİTAK KAMU SM TSA ile RFC 3161 zaman damgası (var-olma + değişmezlik kanıtı; imza değildir). SDK içeride geçici bir dosyaya yazıp temizler. Bu uç anahtar başına dakikada 10 istekle sınırlıdır (RATE_LIMIT_EXCEEDED).
Hesap (me)
<?php $me = $imzala->me(); echo $me->getEmail() . ', kalan kredi: ' . $me->getCredits();
me(), API anahtarının sahibini döndürür (id, e-posta, ad, workspace, kalan kredi). Hiçbir kapsam (scope) istemez. GET, güvenle otomatik yeniden denenir.
İmzalı PDF ve sertifika (binary)
getPdf, getDocumentPdf ve getCertificate ham baytları bir PHP string olarak döndürür (JSON değil; PHP ikili veriyi bayt-string olarak modeller). GET olsalar da otomatik yeniden denenmezler; hata durumunda diğer metodlar gibi ImzalaException fırlatırlar. Diske yazın veya stream'leyin:
<?php // İmzalı sözleşme PDF'i (yalnızca status === 'COMPLETED' iken) file_put_contents('sozlesme.pdf', $imzala->demands()->getPdf($id)); // Tamamlanma sertifikası (PAdES B-T), Türkçe/İngilizce file_put_contents('sertifika.pdf', $imzala->demands()->getCertificate($id, 'tr'));
Otomatik yeniden deneme
Üç kural vardır; hepsi SDK'nın içindedir ve Guzzle'a ayrıca bir tekrar politikası bağlanmaz:
- Okumalar (GET):
demands()->list/get/getTimeline,templates()->list/get/usage/listAll,fieldTemplates()->list/get,contacts()->list/listAll,timestamps()->list/get,reports()->get(),demands()->documents()->list()veme()429 veya 5xx aldığında en çokmaxRetrieskez (varsayılan 2) jitter'lı exponential backoff ile yeniden denenir.0kapatır. Binary indirmeler (getPdf/getDocumentPdf/getCertificate) bu kapsamda değildir. Idempotency-Keyile gönderilen yazmalar:demands()->create($body, $idempotencyKey),uploadDocument()(withIdempotencyKey()),timestamps()->create()(withIdempotencyKey()) vedemands()->documents()->upload()bir 429 sonrasında tam bir kez yeniden denenir; sunucu aynı anahtar için ikinci kayıt oluşturmaz. İkinci 429, 5xx ve diğer tüm hatalar doğrudan fırlatılır. Anahtar verilmezse tek denemedir.maxRetriesbu kuralı etkilemez.- Diğer yazmalar hiç yeniden denenmez:
createBulk,contacts()->create,dispatch,sendReminder,cancel,resendParty,delete,addItems,updateStamp,updateTerm,archive,unarchive,templates()->update/delete,embed()->createSessionve zarf belgesicreate/update/delete/reorder/setAssignments. Tekrarlanan bircreateBulkikinci bir toplu iş, tekrarlanan birsendReminderikinci bir SMS/e-posta üretir.
Bekleme süresi Retry-After başlığından okunur (saniye ya da HTTP tarihi); başlık yoksa backoff gecikmesi uygulanır. Bekleme tavanı 60 saniyedir: sunucu daha uzun bir süre isterse SDK beklemek yerine 429'u fırlatır (ImzalaRateLimitException::getRetryAfter() süreyi taşır). NAN, sonsuz ve negatif Retry-After değerleri yok sayılır.
Sayfalama
templates()->list() tek sayfa döner ({ templates, total, page, limit }). Tüm şablonları elle sayfalamak yerine listAll() generator'ını kullanın:
<?php foreach ($imzala->templates()->listAll(limit: 50) as $template) { echo $template->getId() . ' ' . $template->getName() . "\n"; }
total'a ulaşınca ya da bir sayfa limit'ten az öğe döndürünce durur (sonsuz döngü yok).
Webhook doğrulama
verifyWebhook, imzala.org webhook teslimatının X-Imzala-Signature-256 başlığını doğrular. Statiktir ve istemci nesnesine gerek duymaz:
<?php use Imzala\ImzalaClient; $rawBody = file_get_contents('php://input'); // ham body, json_decode ETMEDEN $valid = ImzalaClient::verifyWebhook( getenv('IMZALA_WEBHOOK_SECRET'), $rawBody, $_SERVER['HTTP_X_IMZALA_SIGNATURE_256'] ?? null, ); if (!$valid) { http_response_code(401); exit; } $event = json_decode($rawBody, true); // $event['type']: demand.created / demand.dispatched / demand.completed / demand.expired / // party.signed / party.viewed / party.rejected / kyc.completed / kyc.failed / // contract.expiring / contract.ended / contract.advanced http_response_code(200);
verifyWebhook exception fırlatmaz; geçersiz/eksik imzada, boş secret'ta veya bozuk başlıkta false döner. Body'yi parse edip yeniden serialize etmeyin: imza byte-byte karşılaştırılır (hash_equals ile sabit-zamanlı).
Hata yönetimi
<?php use Imzala\ImzalaException; use Imzala\ImzalaAuthException; use Imzala\ImzalaRateLimitException; use Imzala\ImzalaValidationException; try { $imzala->demands()->get($demandId); } catch (ImzalaRateLimitException $e) { echo "Rate limit: {$e->getRetryAfter()} sn sonra tekrar dene"; } catch (ImzalaAuthException $e) { echo 'API anahtarı geçersiz veya yetkisiz'; } catch (ImzalaValidationException $e) { echo 'İstek doğrulanamadı: ' . $e->getBody(); } catch (ImzalaException $e) { echo 'İmzala API hatası: ' . $e->getStatusCode() . ' ' . $e->getMessage(); }
Tüm hatalar ImzalaException'dan türer (getStatusCode(), getBody(), getErrorCode(), getCodeDescription() ortak). 401/403 → ImzalaAuthException, 429 → ImzalaRateLimitException (getRetryAfter() saniye, getRateLimit()), 422 → ImzalaValidationException. Diğer statüler (400, 404, 409, 500, ...) doğrudan ImzalaException olarak fırlatılır. İstek gönderilmeden yakalanan yerel doğrulama hataları (geçersiz API anahtarı veya Idempotency-Key karakteri, üretilmiş istemcinin parametre denetimleri) de ImzalaValidationException'dır; getStatusCode() null döner.
getErrorCode(): sunucunun makine-okunur kodu.{"error": "metin", "code": "KOD"}biçimindeki gövdelerdecodealanından okunur; yalnız metin taşıyan gövdedenullkalır.getCodeDescription(): kod için katalogdaki tek satırlık Türkçe açıklama. KatalogImzala\ErrorCodes::CODES(73 kod);ErrorCodes::describe($code)veErrorCodes::isKnown($code)ile sorgulanır. Katalogda olmayan bir kod açıklamasız fırlatılır, yani yeni bir sunucu sürümü eski SDK'yı kırmaz.ImzalaRateLimitException::getRateLimit(): standartRateLimit-Limit/RateLimit-Remaining/RateLimit-Reset/RateLimit-Policybaşlıkları (RateLimitInfo). Birden çok sınır 429 döndürür ve farklı kod taşır; bkz. aşağıdaki tablo.
<?php use Imzala\ErrorCodes; echo ErrorCodes::describe('TEMPLATE_IN_USE'); // Şablonun aktif (taslak veya imza bekleyen) sözleşmesi olduğu için silinemez. echo count(ErrorCodes::CODES); // 73
Sık karşılaşılan hatalar
| Durum | Kod | Ne yapmalı |
|---|---|---|
| 400 | INVALID_PAGE |
page 1 veya daha büyük bir tam sayı olmalı |
| 400 | INVALID_EXPIRY_DATE |
expiry_date geçerli bir takvim tarihi olmalı |
| 400 | PAGE_ID_REQUIRED |
Alan yerleştirmede her öğede tam sayı page_id zorunlu |
| 400 | INVALID_ITEM_TYPE |
Desteklenen alan tiplerinden birini kullanın (hata mesajı listeler) |
| 404 | (kodsuz) | Alan Şablonu kimliğiyle templates()->get() çağrıldı; Alan Şablonları için fieldTemplates()->get() kullanın (iki kavram ayrıdır) |
| 409 | TEMPLATE_IN_USE |
Şablonun taslak veya imza bekleyen sözleşmesi var; tamamlanınca silinebilir |
| 409 | DEMAND_NOT_DISPATCHABLE |
Sözleşme tamamlanmış veya iptal edilmiş; tekrar gönderilemez |
| 409 | ENVELOPE_MULTI_DOC_DISABLED |
Çok belgeli zarf bu hesapta açık değil; demands()->documents()->* bu kodu fırlatır |
| 409 | IDEMPOTENCY_KEY_REUSED |
Aynı anahtar farklı gövdeyle kullanıldı; yeni sözleşme için yeni anahtar üretin |
| 409 | IDEMPOTENCY_UNVERIFIABLE |
Anahtar daha önce sözleşme üretti ama isteğin aynı olduğu doğrulanamadı; gövdedeki demand_id ile durumu sorgulayın, yeni anahtarla körlemesine tekrarlamayın |
| 409 | DUPLICATE_SUSPECTED |
Anahtarsız istek son 10 dakikada gönderilmiş aynı içerikle eşleşti; kasten tekrarlamak için force gönderin |
| 422 | FIELD_LAYOUT_UNRESOLVED |
Alan yerleşimi belgeye uygulanamadı; sözleşme oluşturulmadı, kredi düşülmedi. withOnAnchorMiss() seçin veya belgeyi düzeltin |
| 429 | RATE_LIMIT_EXCEEDED |
Genel sınır: anahtar başına dakikada 60 istek (zaman damgası ucunda 10). Retry-After kadar bekleyin |
| 429 | TOO_MANY_REQUESTS |
Uca özgü sınır: belge yüklemede dakikada 30, davet tekrarı ve zarf gönderiminde saatte 300 |
| 429 | RECIPIENT_RESEND_LIMIT |
Aynı alıcıya saatte en çok 3, günde en çok 10 davet tekrarı |
Sözleşme, şablon ve Alan Şablonu listelerinde limit üst sınırı 100'dür; daha büyük bir değer hata vermez, sessizce 100'e kırpılır. Kişi ve zaman damgası listelerinde limit 10 ile 100 arasında olmalıdır (üretilmiş istemci bunu yerelde denetler).
Sürüm uyumu
| imzala/imzala-php | Konuştuğu API | Durum |
|---|---|---|
| 1.2.0 | v1 (1.17.0) |
Güncel: sözleşme numarası (contract_numbers), PARTY_PHONE_MISSING ve CONTRACT_NUMBER_SEQUENCE_COLLISION hata kodları, onaylayan kredisi kuralı, demand.dispatched webhook olayı, hatırlatmada kredi kontrolü, DISPATCH_PREPARATION_FAILED ve CREDIT_CHECK_FAILED hata kodları ve 1.1.0'ın tüm yüzeyi |
| 1.1.0 | v1 (1.12.0) |
Desteklenir: taraf bazında telefon doğrulaması (require_phone_verification) ve 1.0.0'ın tüm yüzeyi |
| 1.0.0 | v1 (1.11.1) |
Desteklenir: Belge Toplama ayarları, süre ve yenileme takibi, arşivleme, contract.* webhook olayları, imza yöntemi listesi ve sırası, kaşe verisi, belge başına değişkenler |
| 0.x | v1 (1.7.x) |
Bakım dışı; 1.0.0'a yükseltin |
İmzala dış API'si v1'dir ve geriye dönük uyumludur: yeni alanlar opsiyonel, yeni davranışlar opt-in, varsayılan davranış eskisidir. Kırıcı bir değişiklik gerekirse yeni bir major API sürümü yayımlanır; eski sürüm duyurudan sonra 12 ay çalışmaya devam eder.
Not: Bu paket, diğer dört dil SDK'sının (Node/Python/.NET/Java)
ImzalaErrorisimlendirmesinden farklı olarak PHP konvansiyonuna uyupImzalaException/Imzala*Exceptionisimlerini kullanır; davranış (4'lü taksonomi, aynı alanlar) aynıdır.
⚠️ Sunucu-taraflı
Bu paket yalnızca sunucuda kullanılır. API anahtarı sızarsa hesabınızdaki tüm sözleşme/şablon/zaman damgası işlemlerine erişilir. API anahtarınızı tarayıcı JavaScript'ine veya mobil uygulamaya asla gömmeyin. Tarayıcıda imza için @imzala/embed / @imzala/embed-react.
İmza sınıfı
Bu API ile tarayıcıdan atılan dijital imza, 5070 sayılı Elektronik İmza Kanunu m.3 anlamında elektronik imzadır; tamamlanan sözleşmeler otomatik olarak zaman damgasıyla işaretlenir. Güvenli elektronik imza değildir; AB hukuku bakımından gelişmiş veya nitelikli imza olarak sunulmaz. Gömülü imza da aynı niteliktedir. Telefon doğrulaması veya T.C. kimlik numarası kontrolü gibi ek adımlar delil değerini güçlendirir; imzayı gelişmiş ya da güvenli elektronik imzaya dönüştürmez.
Daha fazla
- Tam API referansı: api-docs.imzala.org
- Kullanım kılavuzu: imzala.org/docs/api-sozlesme-yasam-dongusu
- Çalışan örnekler:
examples/php(altı senaryo) - Değişiklik günlüğü: CHANGELOG.md
- Monorepo README