Onam API Entegrasyonu: REST ile Onam Açma ve Webhook

Onam API entegrasyonu, hasta yönetim yazılımınızın (HBYS, muayenehane ya da klinik yazılımı) dijital onam sürecini kendi ekranından başlatması, durumunu takip etmesi ve tamamlanan onamın sonucunu otomatik olarak alması demektir. eOnam'da bu, HTTP Basic kimlik doğrulamalı bir REST API ile yapılır: POST /v1/consents ile onam açılır, consent.completed webhook olayıyla sonuç yazılıma bildirilir.

Bu yazı, entegrasyonu yapacak yazılım ekibi ile süreci tasarlayacak klinik yöneticisi için ortak bir referans olarak hazırlandı. Uç noktaların tam listesi, alan tanımları ve hata kodları API belgelerinde yer alır; burada mantığı ve dikkat edilecek noktaları anlatıyoruz.

Neden entegrasyon?

Onam sistemini ayrı bir panelden kullanmak da mümkündür. Ancak hasta bilgisini bir ekrandan diğerine elle taşımak hem zaman alır hem de hata üretir: yanlış telefon numarası, yanlış yazılmış ad, yanlış hastaya gönderilen form. Entegrasyonla:

• Hasta bilgileri yazılımınızdan doğrudan aktarılır, yeniden yazılmaz.
• Onamın durumu hasta kartında görünür; personel ayrı bir ekrana bakmaz.
• Tamamlanan onamın belge numarası ve bağlantısı hasta kaydına otomatik bağlanır.
• Onamı alınmamış bir işlemi planlamak yazılım düzeyinde uyarıyla engellenebilir.

Onam sürecinin bütün bileşenlerini ve entegrasyonun bu resimdeki yerini dijital onam sistemi rehberinde anlattık.

Kimlik doğrulama ve anahtarlar

REST API, HTTP Basic kimlik doğrulaması kullanır. Panelden oluşturduğunuz anahtar iki parçadan oluşur: bir anahtar kimliği ve bir gizli değer. Her istekte bunlar key_id:secret biçiminde gönderilir. REST anahtarları eo_live_ önekiyle başlar; bu önek, anahtarın hangi amaçla üretildiğini günlük kayıtlarda ve kod incelemelerinde kolayca ayırt etmenizi sağlar.

Anahtar güvenliği için:

• Gizli değeri kaynak koduna yazmayın; ortam değişkeni ya da güvenli yapılandırma deposunda tutun.
• Anahtarı istemci tarafına (tarayıcı, masaüstü uygulamanın kullanıcı bilgisayarı) göndermeyin; istekleri sunucu tarafından yapın.
• Anahtarın sızdığından şüphelenirseniz panelden iptal edip yenisini oluşturun.
• İstekleri yalnızca HTTPS üzerinden yapın.

Adım 1: Onam açmak

Bir onamı başlatmak için hangi şablonun kullanılacağını ve hastanın iletişim bilgisini göndermeniz yeterlidir:

POST /v1/consents

{"sablon_kod":"cerrahi_cekim","adsoyad":"Ayşe Yılmaz","telefon":"05551234567"}

Burada sablon_kod, panelde oluşturduğunuz ya da yüklediğiniz form şablonunun kodudur. Şablonlar sürümlendiği için, onam açıldığı andaki güncel sürüm kullanılır ve belgeye işlenir. Başarılı istek sonucunda dönen yanıtta onamın kimliği (id) yer alır; bu kimliği hasta kaydınızla ilişkilendirip saklayın.

Onam açıldığında hastanın telefonuna bir bağlantı gönderilir. Hasta metni kendi telefonunda okur ve tek kullanımlık SMS koduyla onaylar; uygulama indirmesi ya da üye olması gerekmez.

Komut satırından deneme

Kod yazmaya başlamadan önce isteği komut satırından denemek, kimlik doğrulama ve şablon kodu sorunlarını erkenden gösterir. curl ile HTTP Basic kimlik doğrulaması -u parametresiyle verilir: anahtar kimliği ve gizli değer iki nokta üst üste ile birleştirilir, gövde -d ile JSON olarak gönderilir ve Content-Type: application/json başlığı eklenir. API'nin tam adresi belgelerde yer alır. Deneme için kendi telefon numaranızı kullanın; böylece hastanın göreceği mesajı ve ekranı da kendiniz görürsünüz.

Hangi veriyi göndermeli?

Onam açmak için gereken veri azdır: şablon kodu, hastanın adı soyadı ve telefon numarası. Yazılımınızda hastaya ait çok daha fazla bilgi bulunabilir, ancak onam için gerekmeyen sağlık verisini API'ye göndermeyin. 6698 sayılı KVKK'nın veri işleme ilkeleri, verinin işlendiği amaçla bağlantılı, sınırlı ve ölçülü olmasını ister. Az veri göndermek, hem hukuki riski hem de olası bir hata anında etkilenecek bilgi miktarını azaltır.

Adım 2: Durumu sorgulamak

Onamın o anki durumunu görmek için:

GET /v1/consents/{id}

Onamın başından geçen olayları (gönderim, açılma, onay gibi) zaman sırasıyla görmek için:

GET /v1/consents/{id}/events

Olay listesi, destek taleplerinde çok işe yarar. "Hasta mesajı almadığını söylüyor" dendiğinde, gönderimin yapılıp yapılmadığını ve bağlantının açılıp açılmadığını buradan görebilirsiniz. Olay kayıtlarının belge bütünlüğündeki yerini elektronik belge bütünlüğü yazısında anlattık.

Durumu kullanıcıya nasıl göstermeli?

Entegrasyonun başarısı, personelin durumu tek bakışta anlayabilmesine bağlıdır. Hasta kartında onam için küçük bir durum alanı yeterlidir: gönderildi, hasta açtı, tamamlandı gibi sade ifadeler. Tamamlanan onam için belge numarası ve belgeye giden bir bağlantı gösterilmesi, hekimin işlem öncesinde onamı kontrol etmesini kolaylaştırır. Uzun süre tamamlanmayan onamları listeleyen basit bir ekran da sekreterin hastayı hatırlatma için aramasına yardımcı olur.

Adım 3: Webhook ile sonucu almak

Hasta onayı tamamladığında eOnam, panelde tanımladığınız adrese consent.completed olayını gönderir. Yazılımınız bu isteği aldığında onamı tamamlandı olarak işaretleyebilir, belge numarasını hasta kaydına yazabilir ve ilgili personele bildirim gösterebilir.

Webhook imzasını doğrulamak

Webhook adresiniz internete açık olduğu için, gelen her isteğin gerçekten eOnam'dan geldiğini doğrulamanız gerekir. İsteklerle birlikte iki başlık gönderilir:

• X-eOnam-Timestamp: İsteğin gönderildiği zaman.
• X-eOnam-Signature: Webhook gizli değerinizle hesaplanmış HMAC-SHA256 imzası.

Doğrulama mantığı şöyledir: İmzanın hangi verilerden hesaplandığı belgelerde tanımlıdır; aynı hesabı kendi tarafınızda, isteğin ham gövdesini değiştirmeden yaparsınız. Sonucu başlıktaki imzayla sabit zamanlı bir karşılaştırma fonksiyonuyla (örneğin PHP'de hash_equals) karşılaştırırsınız. Zaman başlığı çok eskiyse isteği reddedersiniz; bu, eski bir isteğin kaydedilip yeniden gönderilmesine karşı korur.

Webhook adresini hazırlamak

Webhook alıcısı, internetten erişilebilen ve HTTPS ile çalışan bir adres olmalıdır. Yazılımınız yalnızca kurumun yerel ağında çalışıyorsa, webhook'u karşılayacak küçük bir sunucu bileşeni ya da güvenli bir ara katman gerekebilir; bu mümkün değilse durum sorgusuyla ilerleyen ya da OneClick tabanlı bir yapı daha uygun olabilir. Alıcı adresi tahmin edilmesi zor bir yol içermeli, ama güvenliği yalnızca adresin gizliliğine değil, her zaman imza doğrulamasına dayanmalıdır.

Webhook alıcısı için iyi uygulamalar

1. İsteği aldığınızda hızlıca başarılı yanıt dönün; ağır işleri kuyruğa alıp sonra yapın.
2. Aynı olayın birden fazla kez ulaşabileceğini varsayın ve işlemi tekrar güvenli (idempotent) kurun: onam kimliğine göre "zaten işlendi mi" kontrolü yapın.
3. İmza doğrulaması başarısız olan istekleri kaydedin ama işlemeyin.
4. Webhook'a tam güvenmek yerine, kritik durumlarda GET /v1/consents/{id} ile son durumu teyit edin.

Adım 4: Belge doğrulama

Yazılımınız bir belgenin geçerliliğini kontrol etmek isterse POST /v1/verify uç noktasını kullanabilir. Gövdede ya belge numarasını ({"id": ...}) ya da belgenin SHA-256 özetini ({"sha256": ...}) gönderirsiniz. Aynı kontrol, insanlar için herkese açık doğrulama sayfasında da yapılabilir. Damganın bağımsız, komut satırıyla doğrulanması için zaman damgası doğrulama yazısına bakabilirsiniz.

REST mi, OneClick mi?

Her yazılım modern bir HTTP istemcisine ve JSON kütüphanesine sahip değildir. Uzun yıllardır kullanılan bazı masaüstü yazılımlarda JSON işlemek zordur. Bu durum için OneClick bağlantısı vardır.

Küçük bir muayenehane yazılımında OneClick ile başlamak, daha sonra REST'e geçmek de mümkündür. Bu senaryoyu muayenehane yazılımına dijital onam eklemek yazısında ele aldık.

Hata yönetimi ve test

• Telefon numarası doğrulaması: Numarayı göndermeden önce kendi tarafınızda biçim kontrolü yapın. Yanlış numara, onamın hiç ulaşmaması demektir.
• Şablon kodu: Panelde şablonun kodunu değiştirirseniz yazılımınızdaki eşlemeyi de güncelleyin.
• Zaman aşımı ve yeniden deneme: Ağ hatasında aynı onamı iki kez açmamak için, isteği göndermeden önce kendi veritabanınızda "gönderiliyor" olarak işaretleyin; yeniden denemeden önce bu kaydı ve varsa dönen onam kimliğini kontrol edin.
• Kontör: Her onam bir kontör kullanır; kontör bittiğinde isteğin nasıl yanıtlandığını belgelerden kontrol edip kullanıcıya anlaşılır bir mesaj gösterin.
• Günlük kaydı: İstek ve yanıtları kaydederken hasta kişisel verilerini maskeleyin; gizli anahtarı asla günlüğe yazmayın.

Entegrasyon kontrol listesi

1. Panelde şablonları oluşturun ve kodlarını yazılımınızdaki işlem türleriyle eşleyin.
2. eo_live_ anahtarını güvenli yapılandırmada saklayın.
3. POST /v1/consents ile onam açmayı ve dönen kimliği hasta kaydına bağlamayı kurun.
4. Webhook adresinizi tanımlayın, X-eOnam-Signature ve X-eOnam-Timestamp ile imza doğrulamasını uygulayın.
5. consent.completed olayını tekrar güvenli biçimde işleyin.
6. Destek için /events uç noktasını kullanıcı ekranına bağlayın.
7. Eski masaüstü modülleriniz için OneClick seçeneğini değerlendirin.

Denemeye başlamak için ücretsiz hesap açabilir, anahtarınızı panelden oluşturabilirsiniz.