ihbys API

Kimlik doğrulama

Her istek HTTP Basic ile kimliklenir. Kullanıcı adı kurum kodunuz (USERCODE), şifre API anahtarınızdır (userAPIKey). İkisini de Softmed size iletir.

curl -u "2:<userAPIKey>" https://ihbys.com/api/v1/me

Anahtar başına dakikada 120 istek sınırı vardır. Aşıldığında 429 ve Retry-After başlığı döner. Bütün istekler HTTPS üzerinden yapılmalıdır.

Uç noktalar

Randevu kaydetme

En sık kullanacağınız uç budur. Randevu kaydedilir ve aynı yanıtta hastaya göndereceğiniz kısa bağlantı döner — iki ayrı istek atmanız gerekmez.

appointment_id sizin randevu kimliğinizdir; kendi tablo kimliğiniz, HBYS GUID'iniz, ne kullanıyorsanız. Aynı kimlikle ikinci kez gönderim güncelleme sayılır ve bağlantı adresi değişmez — bu sayede hatırlatma iki kez gitse bile hasta aynı adresi görür.

curl -u "2:<userAPIKey>" \
  -H "Content-Type: application/json" \
  -X POST https://ihbys.com/api/v1/appointments \
  -d '{
    "frid": 1,
    "appointment_id": "RND-2026-8841",
    "date": "2026-08-14",
    "time_start": "10:30",
    "time_end": "11:00",
    "type_label": "Muayene",
    "service": "Kardiyoloji kontrolü",
    "protocol": "PRT-9911",
    "patient": {
      "name": "Ayşe Yılmaz",
      "tc": "12345678901",
      "birthdate": "1985-03-02",
      "phone": "05321234567"
    },
    "doctor": {
      "no": "7",
      "name": "Mehmet Demir",
      "title": "Uzm. Dr.",
      "specialty": "Kardiyoloji"
    }
  }'

Yanıt — yeni kayıtta 201, güncellemede 200:

{
  "appointment": {
    "appointment_id": "RND-2026-8841",
    "status": "scheduled",
    "date": "2026-08-14",
    "time_start": "10:30",
    ...
  },
  "link": {
    "token": "76b8d31b57895135b0f6081823a951f8",
    "url": "https://ihbys.com/r/76b8d31b57895135b0f6081823a951f8",
    "short_url": "https://lnkz.tr/REQSHUW1",
    "sms_url": "https://lnkz.tr/REQSHUW1",
    "expires_at": "2026-09-13 10:30:00"
  }
}

Hatırlatma mesajınızda sms_url alanını kullanın — kısaltılmış adres varsa onu, yoksa tam adresi verir.

Alanlar

Listeleme

GET /api/v1/appointments?frid=1&status=scheduled&from=2026-08-01&to=2026-08-31&limit=100

q parametresiyle hasta adı, appointment_id ve protokol numarasında arama yapılır. Sayfalama limit (en fazla 200) ve offset ile.

İptal

DELETE /api/v1/appointments/RND-2026-8841?frid=1&reason=Hasta%20talebi

Randevu cancelled olarak işaretlenir ve hasta bağlantısı kapanır; bağlantıyı açan hasta "bu randevu iptal edilmiş" ekranını görür.

İptal ve değişiklik talepleri

Hasta ekrandan iptal ya da tarih değişikliği istediğinde randevuya dokunulmaz — bir talep açılır. Talebi iki yoldan alabilirsiniz.

1. Çekerek

curl -u "2:<userAPIKey>" "https://ihbys.com/api/v1/requests?status=open"

{
  "count": 1,
  "requests": [{
    "id": 42,
    "type": "cancel",
    "status": "new",
    "appointment_id": "RND-2026-8841",
    "frid": 1,
    "reason": "Planım değişti",
    "preferred_date": null,
    "contact_phone": "+905321234567",
    "created_at": "2026-08-10 09:14:00"
  }]
}

İşlemi kendi sisteminizde yaptıktan sonra talebi kapatın:

curl -u "2:<userAPIKey>" -H "Content-Type: application/json" \
  -X POST https://ihbys.com/api/v1/requests/42 \
  -d '{"status":"approved","note":"Randevu iptal edildi"}'

2. Webhook ile

Panelden bir https adresi tanımlarsanız talep anında oraya POST edilir. Gövde, tanımladığınız gizli anahtarla imzalanır:

X-Ihbys-Signature: sha256=<hmac_sha256(gövde, gizli_anahtar)>

{
  "event": "request.created",
  "sent_at": "2026-08-10T09:14:00+03:00",
  "data": {
    "request_id": 42,
    "type": "cancel",
    "appointment_id": "RND-2026-8841",
    "frid": 1,
    "reason": "Planım değişti"
  }
}

Webhook ulaşmazsa talep kaybolmaz; çekme ucundan okunmaya devam eder. İmzayı hash_equals gibi sabit zamanlı bir karşılaştırmayla doğrulayın.

Hata biçimi

{
  "error": {
    "type": "invalid_request",
    "message": "frid pozitif bir tam sayı olmalı. patient.name zorunlu."
  }
}

HBYS'den okuma modu

Randevularınızı ihbys'e göndermek yerine kendi veritabanınızda tutmak istiyorsanız kurum modunu pull yaparız. Bu durumda randevu kaydetmezsiniz; yalnızca bağlantı üretirsiniz:

curl -u "2:<userAPIKey>" -H "Content-Type: application/json" \
  -X POST https://ihbys.com/api/v1/links \
  -d '{"frid":1,"appointment_id":"a8faa905-477a-11f0-89df-52e18006e243"}'

appointment_id burada prandevu.RANDEVUGUID değeridir. Bağlantı üretilmeden önce randevunun gerçekten var olduğu doğrulanır.