راهنمای توسعه‌دهندگان API بوکورا

شروع سریع

1. مالک کلینیک در بخش «تنظیمات › اتصال‌ها (API)» پنل، یک کلید با سطح دسترسی لازم می‌سازه. کلید فقط یک بار نمایش داده می‌شه.
2. کلید رو فقط روی سرور خودتون نگه دارید و در کد سایت یا اپ موبایل که کاربر به اون دسترسی داره قرار ندید.
3. اولین درخواست:

curl https://bookora.net/api/v1/clinic-api/me \
  -H "Authorization: Bearer bk_live_<public-id>_<secret>"

نشانی پایه: https://bookora.net/api/v1/clinic-api. پاسخ‌ها ساختار {"data": …, "meta": …} دارن. پاسخ خطا شامل فیلدهای statusCode، code، message، details و requestId می‌شه؛ متن message فارسیه. مبلغ‌ها به ریال و به‌صورت عدد صحیح، و زمان‌ها با قالب ISO-8601 و به وقت جهانی (UTC) ارسال می‌شن.

احراز هویت

در هر درخواست، هدر Authorization: Bearer bk_live_<public-id>_<secret> رو ارسال کنید. کلید لغوشده یا منقضی‌شده بلافاصله رد می‌شه. هنگام تعویض کلید می‌تونید برای اعتبار کلید قبلی مهلت تعیین کنید.

سطح دسترسی

هیچ‌کس نمی‌تونه کلیدی با سطح دسترسی بالاتر از دسترسی خودش در پنل بسازه.

محدودیت تعداد درخواست‌ها

• هر کلید: ۱۲۰ درخواست در دقیقه
• هر کلینیک، مجموع همه کلیدها: ۳۰۰ درخواست در دقیقه
• ثبت یا تغییر اطلاعات (ثبت نوبت، لغو، جابه‌جایی و ثبت بیمار): ۳۰ درخواست در دقیقه برای هر کلید
• جست‌وجوی بیمار: ۳۰ در دقیقه برای هر کلید

هر پاسخ هدرهای X-RateLimit-Limit، X-RateLimit-Remaining، X-RateLimit-Reset رو داره. اگر تعداد درخواست‌ها از سقف مجاز بیشتر بشه، پاسخ ۴۲۹ همراه با Retry-After برمی‌گرده.

جلوگیری از ثبت تکراری

برای ثبت نوبت یا بیمار، باید هدر Idempotency-Key رو ارسال کنید؛ مقدار اون باید بین ۸ تا ۱۲۸ کاراکتر باشه. برای لغو یا جابه‌جایی نوبت، ارسال این هدر اختیاریه. اگر تا ۲۴ ساعت همون درخواست رو با همون کلید و بدنه دوباره بفرستید، نتیجه قبلی با هدر Idempotent-Replayed: true برمی‌گرده و نوبت یا پرونده تکراری ثبت نمی‌شه.

curl -X POST https://bookora.net/api/v1/clinic-api/appointments \
  -H "Authorization: Bearer bk_live_<public-id>_<secret>" \
  -H "Idempotency-Key: 6f1c2a9e-booking-4411" \
  -H "Content-Type: application/json" \
  -d '{"patientId":"<patient-id>","serviceId":"<service-id>","startAt":"2026-10-10T07:30:00.000Z"}'

مسیرهای API

خطاها

وب‌هوک

با وب‌هوک می‌تونید از تغییرات نوبت‌ها باخبر بشید. در پنل برای هر نشانی، رویدادهای موردنیاز رو انتخاب کنید. نشانی باید از HTTPS استفاده کنه و از داخل ایران در دسترس باشه؛ نشانی‌های شبکه داخلی پذیرفته نمی‌شن. پیام وب‌هوک شامل اطلاعات هویتی بیمار نیست.

• appointment.created — ثبت نوبت
• appointment.confirmed — تأیید نوبت
• appointment.rescheduled — جابه‌جایی نوبت
• appointment.cancelled — لغو نوبت
• appointment.no_show — عدم مراجعه بیمار
• appointment_request.created — درخواست نوبت جدید

{
  "id": "evt_…",
  "type": "appointment.cancelled",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-10T07:31:02.000Z",
  "clinicId": "…",
  "data": {
    "appointment": {
      "id": "…", "status": "CANCELLED",
      "startAt": "…", "endAt": "…",
      "patientId": "…", "doctorId": "…",
      "serviceIds": ["…"], "source": "API"
    },
    "cancelledByPatient": false,
    "actor": { "type": "api_key", "apiKeyId": "…" }
  }
}

امضا

هر پیام هدر X-Bookora-Signature: t=<unix>,v1=<hex> داره. برای ساخت امضا، مقدار t، یک نقطه و بدنه خام درخواست کنار هم قرار می‌گیرن و با HMAC-SHA256 و رمز وب‌هوک امضا می‌شن. هنگام تعویض رمز، یک امضای v1 دیگه با رمز قبلی هم فرستاده می‌شه. هدرهای X-Bookora-Event و X-Bookora-Delivery هم همراه پیام ارسال می‌شن.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the request body exactly as received (a Buffer or string).
export function verifyBookoraSignature(rawBody, header, secret, toleranceSec = 300) {
  const items = header.split(',').map((part) => part.trim().split('='));
  const t = items.find(([key]) => key === 't')?.[1];
  const signatures = items.filter(([key]) => key === 'v1').map(([, value]) => value);
  if (!t || signatures.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return signatures.some(
    (sig) => sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected)),
  );
}

PHP

function verify_bookora_signature(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
    $t = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
        if ($key === 't') { $t = $value; }
        if ($key === 'v1') { $signatures[] = $value; }
    }
    if ($t === null || !$signatures || abs(time() - (int) $t) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) { return true; }
    }
    return false;
}

Python

import hashlib
import hmac
import time


def verify_bookora_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    t, signatures = None, []
    for part in header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t":
            t = value
        elif key == "v1":
            signatures.append(value)
    if t is None or not signatures or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, signature) for signature in signatures)

ارسال مجدد و توقف خودکار

پاسخ 2xx یعنی پیام با موفقیت دریافت شده. پاسخ‌های دیگه، تغییر مسیر یا پاسخ ندادن تا ۱۰ ثانیه، ارسال ناموفق حساب می‌شن. تلاش‌های بعدی با فاصله‌های ۱ دقیقه، ۵ دقیقه، ۳۰ دقیقه، ۲ ساعت، ۶ ساعت، ۱۲ ساعت، ۲۴ ساعت انجام می‌شن و در مجموع حدود دو روز ادامه دارن. اگر ارسال به یک نشانی ۵۰ بار پیاپی ناموفق باشه، یا طی ۷۲ ساعت حداقل ۱۰ بار ارسال ناموفق داشته باشه و هیچ ارسال موفقی نداشته باشه، ارسال به اون نشانی خودکار متوقف می‌شه و به مالک کلینیک اطلاع داده می‌شه.

ممکنه پیام‌ها به ترتیب ایجادشون نرسن. اون‌ها رو بر اساس createdAt مرتب کنید و برای دریافت وضعیت فعلی، اطلاعات نوبت رو دوباره از API بخونید.

نسخه‌ها

apiVersion: 2026-10-01 — نسخه اول شامل دوازده مسیر برای نوبت‌ها و بیماران، شش رویداد وب‌هوک و امکان انتخاب شعبه در نوبت‌ها و زمان‌های آزاده.