Randevu Ajandam - Entegrasyon Geliştirici Portalı

Giriş

Randevu Ajandam API, premium paket sahibi hekimlerin (doktoradi.com) ve kliniklerin (klinikadi.com) kendi özel web siteleri ile ana platform arasındaki çift yönlü veri akışını yönetir.

API altyapısı, güvenlik, yüksek performans ve izolasyon sağlamak amacıyla ana platformdan bağımsız çalışan bir Laravel API servisi olarak tasarlanmıştır. Bu servis, ana veritabanı ile doğrudan senkronize olarak çalışır.

Güvenlik & Kimlik Doğrulama

API isteklerinin güvenliği API Key + Secret Key (HMAC Signature) yöntemiyle sağlanmaktadır. Ağ üzerinden Secret Key asla ham biçimde aktarılmaz. Her isteğin sahtecilik ve manipülasyona karşı korunması için her istek özel olarak imzalanır.

Replay Attack Koruması: X-Timestamp bilgisi sunucu saati ile +/- 5 dakikadan daha fazla fark gösteriyorsa, istek güvenlik gerekçesiyle reddedilir.

İstek Başlıkları (HTTP Headers)

Başlık	Tip	Zorunlu	Açıklama
X-Api-Key	string	Evet	Size tahsis edilen benzersiz API Anahtarınız.
X-Timestamp	integer	Evet	İsteğin oluşturulduğu Unix Zaman Damgası (saniye cinsinden).
X-Signature	string	Evet	İstek verileriyle üretilmiş HMAC-SHA256 imzası.

İmza Hesaplama Metodu

İmzalanacak metin (payload) şu verilerin ardışık olarak birleştirilmesiyle elde edilir:

            payload = X-Timestamp + HTTP_METHOD + PATH_INFO + REQUEST_BODY
        

Bu payload, size verilen Secret Key kullanılarak HMAC-SHA256 algoritmasından geçirilir. Çıkan hex değeri imzanızdır.

İmza Oluşturma Kod Örneği

<?php
$apiKey = "api_key_demo_123";
$secretKey = "secret_key_demo_456";
$timestamp = time();
$method = "POST";
$path = "/api/v1/appointments";
$body = json_encode([
    "service_id" => 1,
    "date" => "2026-07-15",
    "slot" => "10:30"
]);

// 1. Payload oluşturma
$payload = $timestamp . $method . $path . $body;

// 2. HMAC-SHA256 ile imzalama
$signature = hash_hmac("sha256", $payload, $secretKey);

// 3. İstek Gönderme (cURL Örneği)
$ch = curl_init("https://api.randevuajandam.com/api/v1/appointments");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Api-Key: " . $apiKey,
    "X-Timestamp: " . $timestamp,
    "X-Signature: " . $signature
]);

$response = curl_exec($ch);
curl_close($ch);

const crypto = require('crypto');
const axios = require('axios');

const apiKey = "api_key_demo_123";
const secretKey = "secret_key_demo_456";
const timestamp = Math.floor(Date.now() / 1000);
const method = "POST";
const path = "/api/v1/appointments";
const bodyData = {
    service_id: 1,
    date: "2026-07-15",
    slot: "10:30"
};
const body = JSON.stringify(bodyData);

// 1. Payload oluşturma
const payload = timestamp + method + path + body;

// 2. HMAC-SHA256 ile imzalama
const signature = crypto
    .createHmac('sha256', secretKey)
    .update(payload)
    .digest('hex');

// 3. İstek Gönderme
axios.post('https://api.randevuajandam.com/api/v1/appointments', bodyData, {
    headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': apiKey,
        'X-Timestamp': timestamp,
        'X-Signature': signature
    }
})
.then(res => console.log(res.data))
.catch(err => console.error(err.response.data));

Bağlam Algılama (Context Detection)

API Anahtarları veritabanında bir hekim (doktor_id) veya klinik (klinik_id) ile ilişkilendirilir. İstek atıldığında API hangi kimlik üzerinden geldiğini otomatik olarak algılar:

Bireysel Hekim Bağlamı: API sadece o hekime ait verileri (bloglar, hizmetler, randevular) döndürür ve yönetir. Klinik rotaları bu bağlamda kapalıdır (403 Forbidden).
Klinik Bağlamı: API klinik düzeyinde çalışır. Klinikte yer alan tüm doktorların verilerine, randevularına, hakedişlerine ve klinik ayarları ile personel listelerine erişim sağlanır.

Standart HTTP Hata Kodları