Geliştirici belgeleri

Nitelora'yı yazılımınıza birkaç istekle bağlayın: müşterinize, çalışanınıza ya da hastanıza onay linki gönderin, PDF'leri çok imzacılı imzalatın, sonucu imzalı webhook ile alın. Tüm uçlar JSON konuşur; taban adres https://nitelora.com.

1. Hesap açın. Panelden kayıt olun; hesabınız test modunda açılır.
2. Anahtar oluşturun. Panel → API anahtarları → sk_test_…. Anahtar yalnızca bir kez gösterilir.
3. İlk isteği atın. Aşağıdaki örnek bir tedavi planı onayı oluşturur ve hastaya gönderilecek linki döner.

Kimlik doğrulama

Her istekte anahtarı Authorization başlığında gönderin. Anahtarlar kliniğe ya da platforma bağlıdır; panel ve sunucunuz dışında (tarayıcı, mobil uygulama) kullanmayın.

Platform anahtarıyla klinik açmak için POST /v1/platform/klinikler (hariciRef ile idempotent); klinik başına kullanım ve hakediş GET /v1/platform/kullanim.

Postman ve örnek kod

Onay linki (şablonlu, tek imzacı)

Hazır ya da kuruma özel bir şablondan belge üretilir; kişi linki açar, okur ve telefonuna gelen kodla onaylar. Teklif ve hizmet sözleşmesi onayı, KVKK açık rıza, tedavi planı ve ücret onayı, fotoğraf izni gibi onaylar içindir.

Yanıt 201:

{
  "id": "8726827d-…", "durum": "bekliyor", "mod": "standart", "test": true,
  "onayLinki": "https://nitelora.com/o/x7K9…",
  "sonGecerlilik": "2026-11-09T12:00:00Z", "belgeHash": "4be1c0…", "dogrulamaUrl": "…/dogrula/8726827d-…"
}

Sistem şablonları: dis-tedavi-plani, kvkk-acik-riza, fotograf-izni, implant-riza (tıbbi rıza). Şablonların alanları GET /v1/sablonlar ile listelenir; kendi şablonunuzu panelden ya da POST /v1/sablonlar ile oluşturabilirsiniz.

Durumlar: bekliyor → onaylandi | reddedildi | suresi_doldu | iptal. Onaylanınca PDF GET /v1/onaylar/{id}/pdf, kanıt paketi /kanit.

PDF imzalatma (zarf)

Kendi PDF'inizi gönderin (base64, en fazla 10 MB / 300 sayfa), imza yerlerini belirtin. 1–10 imzacı, sıralı ya da paralel. Her imzacı el imzasını çizer ve SMS koduyla onaylar; son imzada imzalar belgeye basılır, kanıt sayfaları eklenir, zaman damgası ve mühür uygulanır.

Alan konumları

Konumlar sayfanın görünür kutusuna oranla 0–1 arasıdır, başlangıç sol üst köşedir. A4'te (595×842 pt) sağ alttaki 170×50 pt'lik bir imza kutusu: x = 0.6, y = 0.85, genislik = 0.286, yukseklik = 0.06. Türler: imza, paraf, ad_soyad, tarih. imzaci alanı imzacılar dizisindeki sıradır (0'dan başlar). Alanı olmayan imzacının imzası yalnızca kanıt sayfasında yer alır.

Yanıttaki her imzacının imzaLinki'ni kendiniz de iletebilirsiniz ("smsGonder": false). İmzacıya eposta verirseniz davet ve tamamlanma bildirimi e-postayla da gider.

Durumlar: bekliyor → tamamlandi | reddedildi | suresi_doldu | iptal. İmzalı PDF GET /v1/zarflar/{id}/pdf. Tamamlanan belge, PDF'in içine gömülü platform mühürü (PAdES) taşır; Adobe Reader gibi görüntüleyicilerde imza panelinde görünür.

Nitelikli imza (mobil imza)

"imzaTuru": "nitelikli" gönderirseniz imzacılar el imzası yerine mobil imzalarıyla imzalar: imza, imzacının nitelikli sertifikasıyla PDF'in içine gömülür (PAdES) ve elle atılan imzayla aynı hukuki sonucu doğurur. Bu türde:

• Zarf her zaman sıralıdır; her imzacı belgenin o anki hâlini imzalar, önceki imzalar geçerli kalır.
• Yalnız imza alanı yerleştirilir, imzacı başına en fazla bir tane; ad, tarih ve yöntem imza kutusunun içinde yer alır.
• Kanıt sayfaları imzalı belgeye eklenmez (imzaları bozardı); ayrı, mühürlü bir rapor olarak GET /v1/zarflar/{id}/kanit-raporu ile alınır.
• Yanıtta ve webhook'ta her imzacının yontem (mobil_imza) ve sertifika bilgisi bulunur.

Şablon ve toplu gönderim

Aynı belgeyi tekrar tekrar gönderiyorsanız şablon olarak saklayın: belge, roller (ör. Hasta, Hekim) ve role bağlı imza yerleri tutulur; gönderirken yalnızca kişileri verirsiniz. Gönderilmiş bir zarftan POST /v1/zarflar/{id}/sablon ya da doğrudan POST /v1/zarf-sablonlari (roller + alanlar).

Toplu gönderimde satırlar bağımsızdır: hatalı satır diğerlerini durdurmaz, yanıt satır satır id ya da hata döner. En fazla 100 satır.

Çok dilli belgeler

Onay şablonları birden fazla dilde tutulabilir: tr (varsayılan), en, de, ar, ru. Aynı şablon kodu her dilde ayrı metin ve ayrı sürüm geçmişiyle saklanır; alan adları (veriler) ve mod tüm dillerde aynıdır, böylece yazılımınız dil ne olursa olsun aynı veriyi gönderir. Sistem şablonlarından dis-tedavi-plani, kvkk-acik-riza, fotograf-izni ve implant-riza beş dilde hazırdır.

POST /v1/onaylar
{ "sablon": "kvkk-acik-riza", "dil": "en", "imzaci": { "ad": "John Smith", "telefon": "+447700900123" }, ... }

GET /v1/sablonlar                 # her (kod, dil) ayrı satır; "dil" ve "diller" alanları
GET /v1/sablonlar/{kod}?dil=ar    # bir dilin metni
POST /v1/sablonlar                # yeni şablon ya da mevcut koda yeni dil: { "kod": "...", "dil": "de", ... }
PUT /v1/sablonlar/{kod}           # gövdedeki "dil" sürümünü günceller

Zarflarda (POST /v1/zarflar, şablondan tek ve toplu gönderim) dil imzacıya giden SMS'in, e-postanın ve imza sayfasının dilini belirler; PDF'in kendisi değişmez. Hasta/imzacı sayfası belgenin dilinde açılır, Arapça sağdan sola gösterilir. Tarih ve saatler belgenin dilinin biçimindedir.

SMS hattı yalnızca Latin karakter taşıdığından Arapça ve Rusça belgelerde SMS İngilizce gider. PDF'teki kanıt etiketleri Türkçe esas, yanında çevirisiyle yazılır (ör. Onaylayan / Approved by); belge metni seçilen dildedir. Dil verilmezse tr. Bilinmeyen dil 400 dil_gecersiz; şablonun o dilde sürümü yoksa 400 sablon_dil_yok döner ve mesajda mevcut diller listelenir.

WhatsApp kanalı

Kodlar ve imza bağlantıları SMS yerine WhatsApp ile gönderilebilir. Platformda WhatsApp açık değilse istek SMS ile karşılanır. Kanal kayıt bazında seçilir:

POST /v1/onaylar   { "sablon": "kvkk-acik-riza", "mesajKanali": "whatsapp", ... }
POST /v1/zarflar   { ..., "mesajKanali": "whatsapp" }

WhatsApp mesajı Meta tarafından reddedilirse aynı mesaj SMS ile gider. Kod gönderim yanıtında kanal alanı kodun gittiği kanalı verir (sms ya da whatsapp). Kişi "Gelmedi mi? SMS ile gönder" ile SMS isteyebilir: POST /api/p/{token}/kod {"kanal":"sms"}, imzacı için POST /api/i/{token}/kod?kanal=sms. Onay ve zarf yanıtlarında mesajKanali döner. Tıbbi rıza akışında yalnızca SMS kullanılır (400 whatsapp_tibbi_riza). Kanıt kaydı kodun hangi kanalla iletildiğini gösterir.

Tıbbi rıza (SBYS üzerinden)

Bilgilendirilmiş Rızanın Elektronik Ortamda Alınması Hakkında Yönetmelik (RG 27.10.2026, 33413) gereği tıbbi rıza, kliniğin Bakanlık kayıtlı sağlık bilgi yönetim sisteminden (SBYS) alınır: hasta formu kendi telefonunda okur, gelen kodu sağlık çalışanına söyler, kodu sağlık çalışanı SBYS'den girer. Bu akışta hastanın kodu kendisinin girmesi kapalıdır; panelden tıbbi rıza başlatılamaz. Canlıda klinik ayrıca tıbbi rızaya yetkilendirilir.

hekim.ekipDogrulandi: SBYS'nin, süreci yürüten sağlık meslek mensubunun EKİP'te tanımlı ve aktif olduğunu doğruladığı beyanıdır (m.6); kodu giren hekim bilgisiyle birlikte denetim kaydına yazılır. Telefon bir kez doğrulandıktan sonra o klinikte 12 ay geçerlidir. Merkezi sisteme aktarım SBYS'nin sorumluluğundadır.

Gömülü imza (iframe) ve kiosk

Onay linkini (onayLinki) ya da imzacı linkini (imzaLinki) kendi ekranınızda <iframe> ile açabilirsiniz. Sayfa durum değiştikçe üst pencereye postMessage ile olay gönderir; kişisel veri içermez.

Bağlantıya ?kiosk=1 eklerseniz belge indirme ve doğrulama bağlantıları gizlenir (ortak cihazlar için). Kesin sonuç için her zaman webhook'u ya da GET /v1/onaylar/{id} durumunu esas alın; tarayıcı olayları yalnız ekranı güncellemek içindir.

Kiosk (klinikteki tablet)

Panelde Kiosk sekmesinden ya da API'den cihaz ekleyin (POST /v1/kiosk-cihazlari); dönen 8 haneli kodu tablette /kiosk sayfasında girin. İmzacı tablette T.C. kimlik numarası ya da telefonuyla kendi bekleyen belgelerini bulur. Yazılımınızdan bir belgeyi doğrudan tablete göndermek için:

POST /v1/kiosk-cihazlari/{cihazId}/gonder
{ "onayId": "…" }                       // ya da
{ "zarfId": "…", "imzaciId": "…" }     // imzaciId verilmezse sıradaki imzacı

Tablet birkaç saniye içinde belgeyi açar; imza bitince ekran kendiliğinden temizlenir. Kioskta açılan her belge denetim kaydına cihaz adıyla yazılır.

Otomatik teslim (SFTP / e-posta)

Tamamlanan her onay ve imza belgesi; imzalı PDF, kanıt paketi (JSON) ve mobil imzalı belgelerde ayrı kanıt raporuyla birlikte kendi sisteminize gönderilir. Webhook'tan farkı: dosyanın kendisi teslim edilir, sizin uç noktanızı yazmanız gerekmez.

• SFTP: parola ya da özel anahtar (OpenSSH/PEM, parolalı olabilir) şifreli saklanır. Sunucunun SHA-256 parmak izi zorunludur; /dene parmak izini döndürür, siz teyit edip kaydedersiniz. Dosyalar önce .part adıyla yüklenip sonra asıl adına çevrilir; PDF en son yazılır (klasörü izleyen sisteminiz yarım dosya görmez).
• E-posta: en fazla 5 alıcı, ekler en fazla 20 MB. Şifreli bir kanal değildir; sağlık verisi için SFTP önerilir.
• Dosya adı şablonu: {tarih} {ref} {baslik} {id} {tur} (ör. 20261106-223000_HASTA-1029_Kira_sözleşmesi_3f2a9c41.pdf).
• Gönderilemezse 1 dk, 5 dk, 30 dk, 2 sa, 12 sa, 24 sa sonra yeniden denenir. Başarılı teslim belgenin denetim zincirine hedefe_teslim_edildi olarak (dosya özetleriyle) yazılır.
• Test anahtarıyla oluşan kayıtlar yalnız testKayitlari: true olan hedeflere gider.

Webhook

Adresi panelden ya da PUT /v1/hesap/webhook ile ayarlayın (canlıda yalnızca https, iç ağ adresleri reddedilir); kayıt bazında callbackUrl ile ezebilirsiniz. 2xx dışındaki yanıtlar ve zaman aşımları 1 dk, 5 dk, 30 dk, 2 sa ve 12 sa sonra yeniden denenir; bunlar da başarısız olursa teslimat panelden (onay detayı) ya da POST /v1/onaylar/{id}/webhooklar/{teslimatId}/tekrar ile elle tekrarlanabilir. Yanıtı 10 saniye içinde verin; ağır işi kuyruğa alın.

POST https://yazilim.example.com/nitelora-webhook
X-Nitelora-Olay: zarf.tamamlandi
X-Nitelora-Teslimat: 3f6c…            (aynı teslimat tekrar gelebilir: bu kimlikle tekilleştirin)
X-Nitelora-Imza: t=1793961125,v1=5f2c…

{ "olay": "zarf.tamamlandi", "tur": "zarf", "id": "…", "durum": "tamamlandi", "refNo": "SOZ-77",
  "pdfHash": "…", "pdfUrl": "…/v1/zarflar/…/pdf", "kanitUrl": "…", "dogrulamaUrl": "…",
  "imzacilar": [{ "sira": 1, "ad": "Ayşe Yılmaz", "rol": "Kiracı", "durum": "imzaladi", "imzaZamani": "…" }] }

İmzayı doğrulayın

v1 = hex(HMAC-SHA256(webhookSecret, t + "." + hamGövde)). Gövdeyi ayrıştırmadan önce ham haliyle doğrulayın, sabit zamanlı karşılaştırın ve 5 dakikadan eski t'yi reddedin.

Tekrar deneme (Idempotency-Key)

Oluşturma isteklerinde (POST /v1/onaylar, /v1/zarflar, şablondan gönderim ve toplu gönderim) Idempotency-Key: <benzersiz değer> gönderin. Ağ hatasında aynı anahtarla tekrar ettiğinizde yeni kayıt açılmaz, ilk yanıt döner. Toplu gönderimde her satır ayrı korunur; yarıda kalan gönderim tekrarlandığında yalnızca eksik satırlar oluşturulur.

Hatalar

Hatalar her zaman aynı biçimdedir; kod makine için sabittir, mesaj kullanıcıya gösterilebilir Türkçe metindir, alan varsa hatalı alanın yoludur.

HTTP/1.1 400 Bad Request
{ "hata": { "kod": "telefon_gecersiz", "mesaj": "Telefon numarası geçersiz (ör. 0532 123 45 67).", "alan": "imzaci.telefon" } }

Doğrulama

Kimlik gerektirmez. Belgedeki QR /dogrula/{id} sayfasını açar. Programla: GET /api/dogrula/{id} ya da dosyanın SHA-256 özetiyle GET /api/dogrula/hash/{sha256} — kayıt durumu, imzacılar, zaman damgası ve mühür sonucu döner. Tek bayt değişmiş bir dosya eşleşmez.

PDF içindeki imzalar: POST /api/dogrula/pdf, gövde ham PDF (Content-Type: application/pdf, en fazla 20 MB; dosya saklanmaz). Her PAdES imzası için bütünlük, güven zinciri (TR/KKTC/AB güven listeleri), iptal durumu, nitelikli sertifika ve zaman damgası incelenir; sonuc: gecerli, gecerli_uyarili, gecersiz, dogrulanamadi. Başka sistemlerde atılmış imzalar da incelenir.

Tüm uçlar