OneClick API — tek bağlantıyla onam açma

OneClick, JSON kütüphanesi ve HTTP istemcisi kurmadan onam açmanızı sağlar. Yazılımınız bir metin birleştirir, onaltılığa çevirir ve tarayıcıyı açar. Hepsi bu.

// Delphi'de entegrasyonun tamamı
ShellExecute(0, 'open',
  PChar('https://api.eonam.tr/oneclick?' + OneClickSorgu(...)),
  nil, nil, SW_SHOWNORMAL);

Neden var

Kliniklerdeki yazılımların önemli bir bölümü Delphi veya Visual Basic ile yazılmıştır; JSON kütüphanesi yoktur, TLS yığını eskidir ve tek bir POST isteği eklemek çoğu zaman haftalar sürer. OneClick tam olarak bu yazılımlar içindir. Sonuçta üretilen onam, REST ile üretilenden farksızdır: aynı SMS doğrulaması, aynı olay zinciri, aynı zaman damgası, aynı delil paketi.

Uç nokta

GET https://api.eonam.tr/oneclick?d=<onaltılık>&s=<imza>

d, aşağıdaki alanlardan kurulmuş bir sorgu dizesinin onaltılık (hex) karşılığıdır. s, d'nin HMAC-SHA256 imzasıdır.

Onaltılık kodlama şifreleme değildir; tek amacı Türkçe karakterlerin ve boşlukların adres çubuğunda bozulmamasıdır. Güvenlik imzadan gelir.

Alanlar

Kipler

mod=ekran — hasta karşınızda

Varsayılan kip. Onam açılır ve tarayıcı doğrudan hastanın onam ekranına yönlendirilir. Tableti hastaya uzatırsınız; metni okur, onaylar, telefonuna gelen kodu girer. SMS ile bağlantı gönderilmez — hasta zaten karşınızdadır, gereksiz masraf çıkmaz. Doğrulama kodu SMS'i elbette gider.

mod=sms — hasta uzakta

Onam açılır, kısa bağlantı hastanın telefonuna SMS ile gider ve personele "gönderildi" ekranı gösterilir. Hasta işlemden önce evinde okuyup onaylayabilir.

mod=json — tarayıcı açmadan

Onam açılır ve JSON döner. Tarayıcı açmak istemeyen, ama JSON okuyabilen yazılımlar için. Cevap, REST'teki onam nesnesinin aynısıdır; ek olarak reused alanı bulunur.

{
  "id":           "ons_260829_hm97qdtv9z5m1e15",
  "status":       "created",
  "external_ref": "ISLEM-2026-8842",
  "patient":      { "name": "Ayşe Yılmaz", "phone": "0555 *** ** 33" },
  "template":     { "code": "implant_onami", "version": 2, … },
  "reused":       false
}

İmza

s = HMAC-SHA256(d, imza_gizi)

İmza gizi, panelde anahtarın yanında görünen 64 karakterlik onaltılık değerdir. Adres çubuğuna hiç çıkmaz. Bu sayede bağlantıyı gören biri başka bir hasta için yeni bağlantı üretemez.

İmzalanan metin d'nin kendisidir — onaltılık dizenin tamamı, çözülmüş hâli değil.

İmzasız çalışma

HMAC üretemeyen çok eski istemciler için anahtara oneclick:imzasiz yetkisi verilebilir; o zaman s gönderilmeden çalışır.

Bunun bedeli açıktır: bağlantıyı ele geçiren biri, o kurum adına istediği numaraya onam açabilir. Bu da SMS masrafı ve hastalarınıza giden istenmeyen mesaj demektir. Anahtara mutlaka IP kısıtı tanımlayın ve imzasız kipi yalnızca gerçekten başka çare yoksa kullanın.

Aynı bağlantının iki kez açılması

Kullanıcılar düğmeye iki kez basar, tarayıcıyı yeniler, sekmeyi geri açar. OneClick bunu bekler:

• ref verdiyseniz, o referansla açık bir onam varsa yeni kayıt açılmaz; var olana yönlendirilir ve ikinci SMS gitmez.
• ref vermediyseniz, referans bağlantının özetinden türetilir (oc_…). Aynı bağlantı yine aynı onama düşer.

Zaten imzalanmış, iptal edilmiş veya süresi dolmuş bir onam "açık" sayılmaz; o referansla yeni çağrı gelirse yeni onam açılır. Bu kasıtlıdır: aynı hasta aynı işlem için tekrar onam vermek isteyebilir.

Kod örnekleri

Delphi

XE8 ve sonrasında HMAC için ek kütüphane gerekmez; System.Hash yeterlidir.

uses System.SysUtils, System.Hash, System.NetEncoding, Winapi.ShellAPI;

// UTF-8 metni onaltılığa çevirir
function ToHex(const S: string): string;
var
  Bytes: TBytes;
  I: Integer;
begin
  Bytes := TEncoding.UTF8.GetBytes(S);
  Result := '';
  for I := 0 to High(Bytes) do
    Result := Result + LowerCase(IntToHex(Bytes[I], 2));
end;

// Sorgu dizesi için yüzde kodlaması
function Enc(const S: string): string;
begin
  Result := TNetEncoding.URL.Encode(S);
end;

function OnamAc(const KeyId, ImzaGizi, Sablon, Ad, Tel, Ref, Islem: string): string;
var
  Ham, D, Imza: string;
begin
  Ham := 'k='      + Enc(KeyId)
       + '&sablon=' + Enc(Sablon)
       + '&ad='     + Enc(Ad)
       + '&tel='    + Enc(Tel)
       + '&ref='    + Enc(Ref)
       + '&islem='  + Enc(Islem)
       + '&mod=ekran'
       + '&exp='    + IntToStr(DateTimeToUnix(Now, False) + 3600);

  D    := ToHex(Ham);
  Imza := LowerCase(THashSHA2.GetHMAC(D, ImzaGizi, THashSHA2.TSHA2Version.SHA256));

  Result := 'https://api.eonam.tr/oneclick?d=' + D + '&s=' + Imza;
end;

// Kullanımı — resepsiyondaki "Onam al" düğmesi
procedure TFormHasta.btnOnamClick(Sender: TObject);
var
  Url: string;
begin
  Url := OnamAc(KEY_ID, IMZA_GIZI, 'implant_onami',
                edAdSoyad.Text, edTelefon.Text,
                'ISLEM-' + IntToStr(IslemNo), edIslem.Text);
  ShellExecute(0, 'open', PChar(Url), nil, nil, SW_SHOWNORMAL);
end;

Delphi 7 gibi çok eski sürümlerde: System.Hash yoktur. Ya bir HMAC-SHA256 birimi eklersiniz (Indy'nin TIdHMACSHA256 sınıfı iş görür) ya da anahtara oneclick:imzasiz yetkisi verip s parametresini göndermezsiniz.

C#

using System.Security.Cryptography;
using System.Text;

static string OneClickUrl(string keyId, string imzaGizi, string sablon,
                          string ad, string tel, string reff)
{
    var exp = DateTimeOffset.UtcNow.ToUnixTimeSeconds() + 3600;

    var ham = $"k={Uri.EscapeDataString(keyId)}"
            + $"&sablon={Uri.EscapeDataString(sablon)}"
            + $"&ad={Uri.EscapeDataString(ad)}"
            + $"&tel={Uri.EscapeDataString(tel)}"
            + $"&ref={Uri.EscapeDataString(reff)}"
            + $"&mod=ekran&exp={exp}";

    var d = Convert.ToHexString(Encoding.UTF8.GetBytes(ham)).ToLowerInvariant();

    using var h = new HMACSHA256(Encoding.UTF8.GetBytes(imzaGizi));
    var s = Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(d))).ToLowerInvariant();

    return $"https://api.eonam.tr/oneclick?d={d}&s={s}";
}

// Açmak için
Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });

PHP

function oneclickUrl(array $alanlar, string $imzaGizi): string
{
    $alanlar['exp'] ??= time() + 3600;

    $d = bin2hex(http_build_query($alanlar, '', '&', PHP_QUERY_RFC3986));
    $s = hash_hmac('sha256', $d, $imzaGizi);

    return 'https://api.eonam.tr/oneclick?d=' . $d . '&s=' . $s;
}

$url = oneclickUrl([
    'k'      => 'eo_oc_xxxxxxxxxxxxxxxx',
    'sablon' => 'implant_onami',
    'ad'     => 'Ayşe Yılmaz',
    'tel'    => '05551234567',
    'ref'    => 'ISLEM-2026-8842',
    'mod'    => 'sms',
], $imzaGizi);

Python

import hmac, hashlib, time
from urllib.parse import urlencode

def oneclick_url(alanlar, imza_gizi):
    alanlar.setdefault("exp", int(time.time()) + 3600)

    ham = urlencode(alanlar)
    d   = ham.encode("utf-8").hex()
    s   = hmac.new(imza_gizi.encode(), d.encode(), hashlib.sha256).hexdigest()

    return f"https://api.eonam.tr/oneclick?d={d}&s={s}"

Hata durumları

Ekran kiplerinde hatalar, hastanın karşısına ham metin çıkmasın diye küçük bir HTML sayfasında gösterilir. mod=json kipinde ve &format=json eklendiğinde JSON döner.

Güvenlik notları

• Bağlantıları saklamayın. Her tıklamada yeniden üretin. exp alanının varlık sebebi budur.
• İmza gizini istemciye gömerken düşünün. Masaüstü programın içindeki bir sabit, o programa erişen herkesin eline geçer. Mümkünse bağlantıyı kendi sunucunuzda üretip masaüstüne yalnızca sonucu verin.
• IP kısıtı tanımlayın. Kurumun sabit IP'si varsa bu, tek başına en etkili önlemdir.
• OneClick anahtarı onam:yaz dışında bir şey yapamaz: onam listeleyemez, belge indiremez, hasta bilgisi okuyamaz.
• eOnam bu adreslerde Referrer-Policy: no-referrer ve X-Robots-Tag: noindex gönderir; adres ne arama motoruna ne de sonraki sayfaya sızar.

Sonucu öğrenmek

OneClick onam açar; onamın tamamlandığını size webhook bildirir. Webhook kuramıyorsanız REST ile GET /v1/consents?external_ref=… sorgulayabilirsiniz — ama bunun için REST anahtarı gerekir.