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" }
      }'

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.