REST API başvuru belgesi

REST + JSON, HTTP Basic kimlik doğrulama. HTTP konuşan her yazılım entegre olabilir. Tüm adresler https://api.eonam.tr altındadır.

Kimlik doğrulama

curl -u "eo_live_xxxxxxxxxxxxxxxx:sk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  https://api.eonam.tr/v1/me

Kullanıcı adı anahtar kimliği, parola gizli anahtardır. Gizli anahtar yalnızca üretildiği anda bir kez gösterilir.

GET /v1/me

Anahtarın hangi kuruma ait olduğunu, yetkilerini, kalan kontörü ve zaman damgası durumunu döndürür. Entegrasyonu doğrulamak için ilk çağıracağınız uçtur.

curl -u "$KEY:$SECRET" https://api.eonam.tr/v1/me

{
  "tenant": {
    "code":    "demoklinik",
    "name":    "Demo Ağız ve Diş Sağlığı Polikliniği",
    "type":    "klinik",
    "storage": "merkezi"
  },
  "key": {
    "id":     "eo_live_5354d1a1daafee14",
    "name":   "İlk anahtar",
    "scopes": ["onam:yaz", "onam:oku", "sablon:oku", "sablon:yaz"]
  },
  "quota": {
    "remaining":    497,
    "unlimited":    false,
    "license_ends": "2026-09-13"
  },
  "timestamping": {
    "driver":        "http",
    "provider":      "turktrust",
    "provider_name": "TÜRKTRUST",
    "legally_valid": true,
    "warning":       null
  }
}

storage değeri kurum ise onam kayıtlarınız kendi veritabanınızda tutuluyor demektir; eOnam merkezinde yalnızca belge numarası ve özet değeri kalır.

Şablonlar

GET /v1/templates

Kurumun şablonlarını listeler. Yetki: sablon:oku.

{
  "data": [
    {
      "code":                   "implant_onami",
      "title":                  "Dental İmplant Uygulaması Onam Formu",
      "category":               "Cerrahi",
      "type":                   "tibbi_onam",
      "active":                 true,
      "version":                2,
      "body_type":              "html",
      "content_hash":           "75282db059a084562c3bf786f0471096…",
      "wet_signature_required": false,
      "published_at":           "2026-08-29 11:05:53"
    }
  ],
  "count": 3
}

GET /v1/templates/{kod}

Tek şablonun ayrıntısı ve beklediği değişkenlerin sözleşmesi. Onam açmadan önce hangi alanları göndermeniz gerektiğini buradan öğrenirsiniz.

{
  "code":  "implant_onami",
  "title": "Dental İmplant Uygulaması Onam Formu",
  "variables": [
    { "name": "implant_marka", "label": "İmplant markası",
      "type": "metin", "required": true },
    { "name": "implant_adet", "label": "Adet",
      "type": "sayi",  "required": false, "default": "1" }
  ]
}

Zorunlu bir değişken eksikse onam açılmaz ve 422 döner. Bu kasıtlıdır: içinde doldurulmamış {yer_tutucu} kalan bir onam belgesi mahkemede savunulamaz.

POST /v1/templates · PUT /v1/templates/{kod}

Şablon oluşturur veya günceller. Yetki: sablon:yaz. Her yayın ayrı bir sürümdür; yayımlanan sürüm bir daha değişmez.

curl -u "$KEY:$SECRET" -H "Content-Type: application/json" \
  -X POST https://api.eonam.tr/v1/templates \
  -d '{
        "kod":     "implant_onami",
        "baslik":  "Dental İmplant Uygulaması Onam Formu",
        "kategori":"Cerrahi",
        "govde":   "<p>… {implant_marka} markalı implant …</p>",
        "yayimla": true,
        "degiskenler": [
          { "ad": "implant_marka", "etiket": "İmplant markası",
            "tip": "metin", "zorunlu": true }
        ]
      }'

Onamlar

POST /v1/consents

Yeni onam açar. Yetki: onam:yaz. Eş anlamlı adres: POST /v1/consent/create.

curl -u "$KEY:$SECRET" \
  -H "Content-Type: application/json" \
  -X POST https://api.eonam.tr/v1/consents \
  -d '{
        "sablon_kod": "implant_onami",
        "adsoyad":    "Ayşe Yılmaz",
        "telefon":    "05551234567",
        "tc":         "12345678901",
        "hekim":      "Dr. Öznur Çağlayan",
        "islem":      "Alt çene implant uygulaması",
        "dis_ref":    "ISLEM-2026-8842",
        "sms_gonder": true,
        "degiskenler": { "implant_marka": "Straumann", "implant_adet": "2" }
      }'

Bilgilendirilmiş Rıza Yönetmeliği (RG 27.10.2026/33413)

Tıbbi müdahale onamları (şablon türü tibbi_onam, anestezi, estetik) yönetmelik kapsamındadır. KVKK açık rızası, aydınlatma metni ve sözleşmeler kapsam dışıdır. Kurumunuzun uyum modunu GET /v1/me cevabındaki compliance.mode alanından öğrenirsiniz:

• uyari — eksik alanlar onamı durdurmaz; cevaptaki compliance.warnings listesinde ve olay zincirinde kalır. Geçiş dönemi içindir.
• zorunlu — personel, hastanın tc'si, kimlik_dogrulama, personel.ekip_aktif ve gerekiyorsa temsilci eksikse 422 döner. 18 yaşından küçük hasta onaylayan_tip: "hasta" ile açılamaz.
• kapali — veteriner gibi kapsam dışı kurumlar.

Telefon doğrulaması (m.7). Bağlantı ve onam kodu yalnızca doğrulanmış numaraya gider. Doğrulama numara ve kişi (T.C.) için 12 ay geçerlidir. Numara doğrulanmamışsa ve mod zorunlu ise onam açılır ama bağlantı gönderilmez; cevapta "next_step": "verify_phone" döner ve numaraya doğrulama kodu gider. Hasta kodu size söyler, siz iletirsiniz:

POST /v1/consents/{id}/verify-phone   { "code": "123456", "sms_gonder": true }
POST /v1/consents/{id}/phone-code     (kodu yeniden gönder)

Cevaptaki link.url'yi hastaya kendi kanalınızdan (ekranda, QR ile) açtırırsanız onam ekranı önce bu kodu ister; metin numara doğrulandıktan sonra açılır ve yöntem sms_hasta olarak kaydedilir (compliance.phone_verification.method).

Numarayı onamdan bağımsız, hasta kaydı sırasında bir kez doğrulamak için:

POST /v1/phone-verifications              { "telefon": "05551234567" }   → { "id": 812 }
POST /v1/phone-verifications/812/verify   { "code": "123456", "tc": "1234…" }
GET  /v1/phone-verifications?telefon=…&tc=…   → { "verified": true, "valid_until": "…" }

Kodu personelin girmesi (m.8/7-b). otp_giris: "personel" ile açılan onamda hasta metni okuyup kabul eder, kod telefonuna gelir ve hasta kodu size söyler:

POST /v1/consents/{id}/sign   { "code": "123456" }

e-Nabız aktarımı (m.8/9). İmzalı onamı merkezi sağlık veri sistemine aktardığınızda bildirin; aktarım delil zincirine yazılır:

POST /v1/consents/{id}/enabiz   { "reference": "SYS-…", "transferred_at": "2026-10-27 14:05" }

Her onam cevabında ve webhook'unda compliance nesnesi döner: mod, uyarılar, telefon doğrulamasının yöntemi ve geçerliliği, kimlik doğrulama yöntemi, sağlık meslek mensubu ve e-Nabız aktarım durumu. Bu bilgiler imzalı PDF'in delil ekine de basılır ve zaman damgasının kapsamına girer.

Test ederken "sms_gonder": false kullanın. Aksi hâlde verdiğiniz numaraya gerçek SMS gider; o numara birine aitse rahatsızlık verir ve kontör harcanır.

Cevap 201 ve onam nesnesidir:

{
  "id":           "ons_260829_hm97qdtv9z5m1e15",
  "status":       "sent",
  "status_text":  "Gönderildi",
  "external_ref": "ISLEM-2026-8842",
  "patient": {
    "name":      "Ayşe Yılmaz",
    "tc_masked": "123****8901",
    "phone":     "0555 *** ** 67"
  },
  "template": {
    "code":           "implant_onami",
    "version":        2,
    "content_sha256": "75282db059a084562c3bf786f0471096…"
  },
  "created_at":   "2026-08-29 20:14:36",
  "expires_at":   "2026-08-30 20:14:36",
  "document":     null,
  "timestamp":    { "status": "none", "error": "" },
  "link": {
    "url":   "https://eonam.tr/o/670e5bc806a880c0dc548934569e53dd…",
    "short": "https://lnkz.tr/a7Kd2"
  }
}

template.content_sha256 değerini kendi kaydınıza yazın. "Hasta tam olarak şu metni okudu" iddiasının dayanağı budur ve şablonu sonradan güncellemeniz bu değeri değiştirmez.

GET /v1/consents

Filtrelenebilir liste. Yetki: onam:oku.

curl -u "$KEY:$SECRET" \
  "https://api.eonam.tr/v1/consents?external_ref=ISLEM-2026-8842"

GET /v1/consents/{id}

Tek onamın güncel hâli. Tamamlanmışsa document nesnesi dolar:

{
  "status": "completed",
  "document": {
    "sha256":       "63300946b032e0c4…",
    "pdf_url":      "https://eonam.tr/indir.php?…",
    "evidence_url": "https://eonam.tr/indir.php?…",
    "tsr_url":      "https://eonam.tr/indir.php?…",
    "verify_url":   "https://eonam.tr/dogrula.php?u=ons_260829_…"
  },
  "timestamp": {
    "status":   "ok",
    "time":     "2026-08-29 00:42:14",
    "serial":   "07586FE9",
    "provider": "turktrust"
  }
}

İndirme adresleri 24 saatlik imzalı bağlantılardır; kalıcı değildir, veritabanınızda saklamayın. Gerektiğinde bu uçtan yeniden alın.

timestamp.status değerleri: ok, queued (kuyrukta), failed (alınamadı), none (yok).

GET /v1/consents/{id}/events

Onamın olay kaydı ve zincir doğrulaması. Delil raporunun makine okunur karşılığıdır: her olay bir öncekinin özetini taşır; araya kayıt eklenirse veya bir kayıt değiştirilirse zincir kırılır.

{
  "data": [
    { "event": "olusturuldu", "at": "2026-08-29 09:26:00",
      "ip": "45.11.96.89", "hash": "a41f…" },
    { "event": "otp_dogrulandi", "at": "2026-08-29 10:55:12", … }
  ],
  "chain": { "ok": true, "count": 8 }
}

POST /v1/consents/{id}/resend

Bağlantıyı yeniden gönderir. Yetki: onam:yaz. İmzalanmış, iptal edilmiş veya süresi dolmuş onamda 409 döner.

Kısa bağlantı yeniden üretilmez; ilk üretilen bağlantı tekrar kullanılır.

POST /v1/consents/{id}/cancel

Onamı iptal eder. Gövdede {"reason": "…"} gönderebilirsiniz. İmzalanmış onam iptal edilemez — 409 döner. Bu kasıtlıdır: verilmiş bir onamı geriye dönük silmek delil değerini yok eder.

POST /v1/consents/{id}/timestamp

Damgası alınamamış bir belgeyi yeniden mühürlemeyi dener.

{
  "ok":      true,
  "message": "",
  "consent": { … }
}

Sonradan alınan damga, belgenin damga anında var olduğunu gösterir; imza anında var olduğunu değil. Aradaki gecikme uzunsa bu fark anlamlıdır ve delil raporunda görünür.

POST /v1/verify

Elinizdeki bir belgenin gerçekliğini sorgular.

curl -u "$KEY:$SECRET" -H "Content-Type: application/json" \
  -X POST https://api.eonam.tr/v1/verify \
  -d '{ "id": "ons_260829_hm97qdtv9z5m1e15",
        "sha256": "63300946b032e0c4…" }'

Belge numarası ile gönderilen özet eşleşmiyorsa belge değiştirilmiş demektir. Kimlik doğrulaması gerektirmeyen genel doğrulama sayfası da vardır: eonam.tr/dogrula.

Sonraki adım

Onamın tamamlandığını öğrenmek için sürekli sorgulama yapmayın; webhook kurun.