مستندات API تیک‌ها
هر چیزی که برای اتصال کسب‌وکارت به تیک‌ها نیاز داری، همینجاست.
https://api.tikha.ir/v1
POST احراز هویت و دریافت توکن
/auth/tokenبرای استفاده از تمام endpoint ها، ابتدا باید توکن دسترسی دریافت کنید. توکن رو توی Header به صورت Bearer Token بفرستید.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| api_key | string | اجباری | کلید API که از داشبورد تیک‌ها دریافت کردید |
| business_id | integer | اجباری | شناسه یکتای کسب‌وکار شما |
curl -X POST https://api.tikha.ir/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"api_key": "tk_live_xxxxxxxxxxxx", "business_id": 1234}'
// Response 200
{
"status": "success",
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"expires_in": 86400,
"token_type": "Bearer"
}
}
توکن بعد از ۲۴ ساعت منقضی میشه. برای تمدید خودکار از refresh_token که توی پاسخ لاگین میاد استفاده کنید.
GET دریافت لیست نوبت‌ها
/appointmentsلیست نوبت‌های فعال، آینده و گذشته رو با قابلیت فیلتر بر اساس تاریخ، مشتری یا وضعیت دریافت کنید.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| date_from | string | اختیاری | تاریخ شروع (YYYY-MM-DD) |
| date_to | string | اختیاری | تاریخ پایان (YYYY-MM-DD) |
| status | string | اختیاری | pending / confirmed / cancelled / done |
| page | integer | اختیاری | شماره صفحه (پیش‌فرض: ۱) |
curl https://api.tikha.ir/v1/appointments?status=confirmed&date_from=2025-01-01 \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
// Response 200
{
"status": "success",
"data": [
{
"id": 5678,
"customer_name": "سارا محمدی",
"service": "مشاوره روانشناسی",
"date": "2025-01-15",
"time": "14:00",
"status": "confirmed",
"staff": "دکتر رضایی"
}
],
"pagination": {
"current_page": 1,
"total_pages": 4,
"total_items": 38
}
}
POST ایجاد نوبت جدید
/appointmentsاز این endpoint برای ایجاد نوبت از سمت سایت خودتون یا ربات تلگرام استفاده کنید.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| customer_id | integer | اجباری | شناسه مشتری ثبت‌شده |
| service_id | integer | اجباری | شناسه خدمت (مشاوره، کراتین و...) |
| date | string | اجباری | تاریخ نوبت (YYYY-MM-DD) |
| time | string | اجباری | ساعت نوبت (HH:MM) |
| staff_id | integer | اختیاری | شناسه پرسنل (در صورت انتخاب نشدن، خودکار تخصیص) |
curl -X POST https://api.tikha.ir/v1/appointments \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": 291,
"service_id": 12,
"date": "2025-01-20",
"time": "10:30"
}'
DEL کنسل کردن نوبت
/appointments/{id}/cancelنوبت رو کنسل کن. در صورت کنسلی قبل از ۲۴ ساعت، هزینه به مشتری برگشت داده میشه.
کنسلی نوبت غیرقابل بازگشته. حتماً قبلش به مشتری اطلاع بدید یا از سیستم یادآوری خودکار استفاده کنید.
GET جستجوی مشتریان
/customers/searchمشتریان رو بر اساس نام، شماره تماس یا ایمیل جستجو کنید. برای استفاده توی ربات تلگرام یا سایت خودتون عالیه.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
| q | string | اجباری | عبارت جستجو (حداقل ۲ کاراکتر) |
| limit | integer | اختیاری | حداکثر نتایج (پیش‌فرض: ۱۰) |
GET تاریخچه تراکنش‌ها
/transactionsگزارش کامل تراکنش‌های مالی، پرداخت‌های موفق و ناموفق، کارمزدها و تسویه‌حساب‌ها.
// Response 200
{
"status": "success",
"data": [
{
"id": 8932,
"amount": 350000,
"fee": 17500,
"net_amount": 332500,
"status": "settled",
"date": "2025-01-14"
}
]
}
POST وب‌هوک‌ها (Real-time Events)
/webhooks/registerوب‌هوک ثبت کنید تا هر وقت نوبت جدید رزرو شد، پرداخت انجام شد یا مشتری پیام داد، به صورت Real-time به سرور شما اطلاع داده بشه.
| رویداد | توضیح | زمان ارسال |
|---|---|---|
| appointment.created | نوبت جدید رزرو شد | بلافاصله بعد از رزرو |
| appointment.cancelled | نوبت کنسل شد | بلافاصله بعد از کنسلی |
| payment.completed | پرداخت موفق | بعد از تأیید بانک |
| chat.new_message | پیام جدید از مشتری | زمان ارسال پیام |
| customer.registered | مشتری جدید ثبت‌نام کرد | بعد از تکمیل ثبت‌نام |
آدرس وب‌هوک باید HTTPS باشه و در کمتر از ۵ ثانیه پاسخ 200 بده. در غیر این صورت ۳ بار تلاش مجدد میشه.