مستندات

شروع

معرفی

API نوبت‌دهی به شما اجازه می‌دهد نمایه‌ی ارائه‌دهنده، سرویس‌ها، بازه‌های خالی و رزروها را در برنامه‌ی خودتان بخوانید و بسازید. اگر فقط یک دکمه‌ی رزرو می‌خواهید، به‌جای API از ویجت استفاده کنید.

https://api.example.com/v1

شروع

شروع سریع

در سه قدم اولین رزرو را بسازید: سرویس‌ها را بگیرید، بازه‌ی خالی را پیدا کنید، رزرو را ثبت کنید.

# 1) list services
curl https://api.example.com/v1/providers/ilia-salon/services \
  -H "Authorization: Bearer hg_test_xxxxxxxx"

# 2) find free slots
curl "https://api.example.com/v1/providers/ilia-salon/availability?service=svc_color&date=2026-10-10" \
  -H "Authorization: Bearer hg_test_xxxxxxxx"

# 3) book one
curl -X POST https://api.example.com/v1/bookings \
  -H "Authorization: Bearer hg_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"svc_color","start":"2026-10-10T10:30:00+03:30"}'

شروع

احراز هویت

هر درخواست باید کلید API را در هدر Authorization بفرستد. کلیدهای hg_test فقط روی داده‌ی آزمایشی کار می‌کنند و کلیدهای hg_live روی داده‌ی واقعی.

Authorization: Bearer hg_test_xxxxxxxx

API نوبت‌دهی

ارائه‌دهنده‌ها

{
  "slug": "ilia-salon",
  "name": "Ilia Salon",
  "kind": "business",
  "timezone": "Asia/Tehran",
  "services": 3
}

API نوبت‌دهی

سرویس‌ها

{
  "data": [
    { "id": "svc_cut", "name": "Haircut", "duration": 45, "fixed": true },
    { "id": "svc_color", "name": "Colour & highlights", "duration": 90, "fixed": true },
    { "id": "svc_skin", "name": "Skin cleansing", "duration": null, "fixed": false }
  ]
}

API نوبت‌دهی

بازه‌های خالی

API نوبت‌دهی

رزروها

{
  "id": "bk_8f2a",
  "status": "confirmed",
  "service": "svc_color",
  "start": "2026-10-10T10:30:00+03:30",
  "end": "2026-10-10T12:00:00+03:30"
}

API نوبت‌دهی

مشتری‌ها

{
  "id": "cus_31c9",
  "bookings": 6,
  "last_visit": "2026-09-21",
  "notes": ["prefers mornings"]
}

API نوبت‌دهی

وب‌هوک‌ها

برای اطلاع از تغییر نوبت‌ها یک آدرس ثبت کنید تا رویدادهایی مثل booking.created و booking.cancelled به آن ارسال شود. هر درخواست با هدر X-Signature امضا می‌شود.

{
  "event": "booking.created",
  "data": { "id": "bk_8f2a", "service": "svc_color", "start": "2026-10-10T10:30:00+03:30" }
}

ویجت رزرو

افزودن ویجت

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

<script src="https://cdn.example.com/booking-widget.js" defer></script>
<div data-booking-widget="ilia-salon"></div>

ویجت رزرو

گزینه‌های ویجت

ویجت رزرو

رویدادهای ویجت

ویجت رویدادهای مرورگر را روی همان عنصر منتشر می‌کند تا بتوانید مثلاً یک پیام تشکر نشان دهید.

document
  .querySelector("[data-booking-widget]")
  .addEventListener("booking:confirmed", (e) => {
    console.log("confirmed", e.detail.id);
  });

مرجع

خطاها

خطاها با کد وضعیت HTTP و یک بدنه‌ی JSON شامل code و message برمی‌گردند.

{
  "error": { "code": "slot_taken", "message": "This slot is no longer free." }
}

مرجع

محدودیت نرخ

هر کلید در هر دقیقه تا ۶۰ درخواست مجاز است. هدرهای X-RateLimit-Remaining و Retry-After وضعیت را نشان می‌دهند.

مرجع

تغییرات