eOnam API dokümanı

eOnam iki ayrı entegrasyon yolu sunar. İkisi de aynı altyapıyı kullanır, aynı onamı üretir ve aynı delil paketini verir; aralarındaki fark, yazılımınızın ne kadar iş yapması gerektiğidir.

Hangisini seçmeliyim?

Kısa cevap: HTTP isteği atıp JSON okuyabilen bir yazılımınız varsa REST, yoksa OneClick. İkisini aynı anda da kullanabilirsiniz; örneğin randevu modülünüz REST ile toplu onam açarken, resepsiyon ekranındaki düğme OneClick bağlantısı üretebilir.

	OneClick API	REST API
Yazılımın yapması gereken	Metin birleştir, onaltılığa çevir, tarayıcı aç	HTTPS POST gönder, JSON çöz, cevabı sakla
JSON kütüphanesi	Gerekmez	Gerekir
Sonucu öğrenme	Webhook ile	Cevaptan anında + webhook
Onam listesi çekme	Yapamaz	Yapabilir
Belge indirme	Yapamaz	Yapabilir
Şablon yönetimi	Yapamaz	Yapabilir
Tipik entegrasyon süresi	Yarım gün	Birkaç gün
Uygun olduğu yer	Delphi/VB ile yazılmış eski masaüstü programlar, hızlı pilot	Tam entegrasyon, arka plan işleri, raporlama

OneClick'in yapamadıkları bilinçli bir sınırdır: OneClick anahtarı yalnızca onam açabilir. Bağlantı adres çubuğunda göründüğü için, o adresi ele geçiren birinin geçmiş hasta kayıtlarına ulaşamaması gerekir.

OneClick API belgesine geç → · REST API belgesine geç →

Adresler

Ortam	Adres
API	`https://api.eonam.tr`
Kurum paneli	`https://app.eonam.tr`
Hasta onam ekranı	`https://eonam.tr/o/<token>`
Belge doğrulama	`https://eonam.tr/dogrula`

Tüm çağrılar HTTPS üzerinden yapılır. HTTP isteği kabul edilmez.

Kimlik doğrulama

REST API, HTTP Basic kullanır: kullanıcı adı anahtar kimliği, parola gizli anahtardır.

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

OneClick'te Authorization başlığı yoktur; kimlik bağlantının içindedir ve HMAC-SHA256 ile imzalanır. Ayrıntısı OneClick bölümündedir.

Anahtarları panelden Ayarlar → API anahtarları ekranından üretirsiniz. Gizli anahtar (sk_…) yalnızca üretildiği anda bir kez gösterilir; veritabanında yalnızca özeti tutulur. Kaybederseniz yeni anahtar üretmeniz gerekir.

Yetkiler

Her anahtarın bir yetki listesi vardır. Yalnızca ihtiyaç duyulan yetkiyi verin.

Yetki	Ne yapar
`onam:yaz`	Onam açar, yeniden gönderir, iptal eder
`onam:oku`	Onam listeler, ayrıntı ve olay kaydı okur
`sablon:oku`	Şablonları ve değişken tanımlarını okur
`sablon:yaz`	Şablon oluşturur, günceller, yayımlar
`oneclick:imzasiz`	İmzasız OneClick bağlantısına izin verir (önerilmez)

IP kısıtı

Anahtara IP veya CIDR listesi tanımlarsanız, yalnızca o adreslerden gelen istekler kabul edilir. Sabit IP'si olan kurumlarda anahtarın çalınması hâlinde en etkili ikinci savunma budur.

Ortak kavramlar

Şablon kodu

Onam açarken hangi metnin imzalanacağını sablon_kod ile belirtirsiniz. Kodları siz seçersiniz: implant_onami, kvkk_acik_riza gibi. Panelden veya GET /v1/templates ile listelenir.

Bir onam, imzalandığı metin sürümüne bağlanır. Şablonu daha sonra güncellemeniz, eski onamların içeriğini veya delil değerini değiştirmez; her onam kendi sürümünün özetini (content_sha256) taşır.

Şablon değişkenleri

Onam metnine {implant_marka} gibi yer tutucular koyabilir, değerlerini çağrı sırasında gönderebilirsiniz. Zorunlu bir değişken eksikse onam açılmaz — içinde doldurulmamış yer tutucu kalan bir onam belgesi mahkemede savunulamaz.

Bir şablonun beklediği değişkenler GET /v1/templates/{kod} cevabında bildirilir.

Dış referans ve mükerrer kayıt

dis_ref (OneClick'te ref), onamın sizin sistemenizdeki karşılığıdır: işlem numarası, protokol numarası, randevu kimliği. Zorunlu değildir ama vermeniz şiddetle önerilir:

Webhook geldiğinde kaydı eşleştirmenizi sağlar.
OneClick'te aynı referansla ikinci kez bağlantı açılırsa yeni onam oluşturulmaz; var olan onama düşülür. Çift tıklama ve tarayıcı yenilemesi mükerrer kayıt ve gereksiz SMS masrafı doğurmaz.

Onam durumları

Kod	Anlamı
`created`	Onam açıldı, henüz bağlantı gönderilmedi
`sent`	Hastaya SMS gönderildi
`viewed`	Hasta onam ekranını açtı
`otp_sent`	Hasta onayladı, doğrulama kodu gönderildi
`signed`	Kod doğrulandı, onam imzalandı
`completed`	Belge üretildi ve mühürlendi
`cancelled`	Kurum iptal etti
`rejected`	Hasta onaylamadı
`expired`	Geçerlilik süresi doldu

Onam completed olmadan belge indirilemez. Belgenin hukuki değeri, zaman damgasının durumuna da bağlıdır — bkz. zaman damgası nedir.

Zaman damgası durumu

GET /v1/me cevabındaki timestamping.legally_valid alanına bakın. false ise damga ya kapalıdır ya da test sağlayıcısındandır; bu durumda kendi arayüzünüzde belgeyi "mühürlü" diye göstermeyin.

{
  "timestamping": {
    "driver":        "yok",
    "provider":      "turktrust",
    "provider_name": "TÜRKTRUST",
    "legally_valid": false,
    "warning":       "Zaman damgası kapalı (ZD_SURUCU=yok)."
  }
}

Hata biçimi

Tüm hatalar aynı zarfla döner:

{
  "error": {
    "code":    "validation_error",
    "message": "Şablon değişkenleri eksik veya hatalı: implant_marka zorunludur."
  }
}

HTTP	`code`	Ne demek
400	`invalid_request`	İstek biçimi bozuk
401	`unauthorized`	Anahtar yok, yanlış veya imza tutmadı
403	`forbidden`	Yetki yok, IP kısıtı veya pasif anahtar
404	`not_found`	Uç nokta, şablon veya onam bulunamadı
409	`conflict`	Şablonun yayımlanmış sürümü yok gibi durum çakışması
410	`link_expired`	OneClick bağlantısının süresi dolmuş
422	`validation_error`	Alan eksik veya geçersiz
429	`rate_limited`	Dakikalık istek sınırı aşıldı
500	`server_error`	Bizim tarafımızda hata

422 alırsanız isteği aynen tekrar göndermeyin; mesajda yazan alanı düzeltin. 429 ve 500 yeniden denenebilir; 429 cevabında Retry-After başlığı gelir.

İstek sınırları

Yol	Sınır
REST	Anahtar başına dakikada 120 istek
OneClick	Anahtar başına dakikada 60 istek
OneClick bağlantı ömrü	En fazla 24 saat

Kontör

Her tamamlanan onam bir kontör düşer. Kalan kontörü GET /v1/me içindeki quota.remaining alanından izleyebilirsiniz; unlimited: true ise sınırsız pakettesiniz. Kontör bittiğinde yeni onam açma çağrıları 403 döner — bu yüzden kalan kontörü kendi izleme ekranınıza da koymanız iyi olur.

Sıradaki adım

OneClick API — tek bağlantıyla onam açma, Delphi ve C# örnekleriyle
REST API — tüm uç noktalar
Webhook — sonucu yazılımınıza bildirme