API
المواعيد
الخدمات والفريق والمواعيد بالجملة لجدولك
# المواعيد > الخدمات والفريق والمواعيد بالجملة لجدولك - الصفحة: https://tbit.app/ar/docs/api/appointments - عنوان URL الأساسي: `https://rest-api.tbit.app/v1` - المصادقة: ترويسة `X-API-Key` تحمل مفتاحك في كل طلب (تقرأه الأمثلة من متغير البيئة `TBIT_API_KEY`) ## نظرة عامة ما تحتاجه لإدارة جدول أعمالك من نظام آخر: الخدمات التي تُحجز مع من يقدمها، الفريق، وتحميل المواعيد بالجملة. هذا هو ما تفعله أدوات MCP list_services و list_collaborators و import_appointments، بنفس أسماء الحقول. ## نقاط النهاية | الطريقة | المسار | الوصف | | --- | --- | --- | | `GET` | `/v1/services` | الخدمات التي تُحجز، ومن يقدمها | | `GET` | `/v1/collaborators` | الفريق: الاسم، البريد، الدور والخدمات التي يقدمها | | `POST` | `/v1/appointments/import` | تحميل حتى 200 موعد في طلب واحد | ## عرض الخدمات كل خدمة تحمل id و name و duration_minutes و price و currency و location و active و collaborators (id و name و email لمن يقدمها). الـ id هو ما تطلبه كـ service_id عند استيراد المواعيد. الخدمات التي تُؤجَّر (غرف، قاعات، مركبات) لا تظهر هنا. `GET /v1/services` ```bash curl "https://rest-api.tbit.app/v1/services" \ -H "X-API-Key: $TBIT_API_KEY" ``` الاستجابة: ```json { "data": [ { "id": "6a0f3c2e9b1d4a0012ab34cd", "name": "Endodoncia", "duration_minutes": 60, "price": 350000, "currency": "COP", "location": "Sede norte · Calle 72 # 7-41", "active": true, "collaborators": [ { "id": "6a0f3c2e9b1d4a0012ab0001", "name": "Geral Díaz", "email": "[email protected]" } ] } ] } ``` ## عرض الفريق كل شخص يحمل id و name و email و role و attends_appointments (هل يقدم المواعيد) و service_ids (الخدمات التي يقدمها). عندما لا يكون للشخص اسم محمّل، يأتي name فارغًا: تعرّف عليه من بريده. `GET /v1/collaborators` ```bash curl "https://rest-api.tbit.app/v1/collaborators" \ -H "X-API-Key: $TBIT_API_KEY" ``` الاستجابة: ```json { "data": [ { "id": "6a0f3c2e9b1d4a0012ab0001", "name": "Geral Díaz", "email": "[email protected]", "role": "ADMIN", "attends_appointments": true, "service_ids": [ "6a0f3c2e9b1d4a0012ab34cd" ] } ] } ``` ## استيراد المواعيد أرسل حتى 200 موعدًا في كل استدعاء ضمن appointments. كل صف يحمل phone (مع رمز الدولة، مثل 573001234567: يُبحث عن جهة الاتصال برقم الهاتف، وإن لم تكن موجودة تُنشأ) أو contact_id (جهة اتصال موجودة بالفعل: يذهب الموعد إلى تلك البطاقة حتى لو لم يكن لديها رقم هاتف، كمن يكتب بمستخدم WhatsApp؛ وإذا أرسلت phone أيضًا فلا يُستخدم إلا للإشعار)، وcontact_name وemail اختياريان، والخدمة (service_id أو service_name، الاسم الدقيق دون اعتبار لحالة الأحرف)، ومن يقدّم الخدمة (collaborator_id أو collaborator_email؛ وإذا كان شخص واحد فقط يقدّم الخدمة يمكنك حذفه)، وstart بصيغة ISO 8601 (بدون منطقة زمنية يُقرأ في المنطقة الزمنية للنشاط التجاري)، وend اختياري (افتراضيًا start زائد مدة الخدمة)، وexternal_id (مفتاح الحدث في نظامك: إعادة الاستيراد لا تكرره) وnotes. خيارات، كلها في المستوى الأول من الجسم: notify_customer (افتراضيًا false: لا يصل للعميل تأكيد؛ true يرسله كأي موعد)، و send_reminders (افتراضيًا true)، و release_blocks (true يزيل حجوزات ذلك الشخص المتقاطعة مع الموعد)، و on_existing (skip أو update: إذا وُجد موعد بنفس external_id، يتركه كما هو أو ينقله دون إشعار أحد) و dry_run (true يتحقق من كل شيء ويقول ما سيفعل، دون كتابة أي شيء). ابدأ دائمًا بـ dry_run. تقول الاستجابة لكل صف ما حدث: status هو created أو updated أو skipped أو failed (would_create أو would_update مع dry_run)، مع appointment_id و contact_id، وإن فشل، error مع السبب بالكلمات («أندريس لا يقدم علاج الجذور؛ يقدمه: جيرالد دياز.»). صف سيئ لا يوقف الباقي. احفظ import_id: هو ما تحتاجه للتراجع. `POST /v1/appointments/import` ```bash curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "dry_run": true, "appointments": [ { "phone": "573001234567", "contact_name": "Ana Pérez", "service_name": "Endodoncia", "collaborator_email": "[email protected]", "start": "2026-11-20T10:00", "external_id": "gcal-7f3k2" } ] }' ``` الاستجابة: ```json { "data": { "import_id": null, "dry_run": true, "created": 1, "updated": 0, "skipped": 0, "failed": 0, "results": [ { "index": 0, "external_id": "gcal-7f3k2", "status": "would_create", "contact_id": "6a0f3c2e9b1d4a0012ab9f10" } ] } } ``` ## التراجع عن استيراد أرسل فقط undo_import_id مع import_id الذي أعادته عملية الاستيراد: كل المواعيد التي أنشأها ذلك الاستيراد تصبح ملغاة، دون إشعار أحد، ويصبح external_id الخاص بها حرًا لإعادة استيرادها. `POST /v1/appointments/import` ```bash curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "undo_import_id": "6a1e0b7c5d4f3a0012cd5678" }' ``` الاستجابة: ```json { "data": { "import_id": "6a1e0b7c5d4f3a0012cd5678", "cancelled": 198, "already_cancelled": 2, "failed": [] } } ``` ## القواعد والأخطاء - على الشخص أن يقدم تلك الخدمة. وإلا يفشل الصف ويقول الخطأ من يقدمها فعلًا. - لا يمكن أن يتقاطع موعد مع آخر لنفس الشخص، ولا مع صف آخر من نفس الدفعة. إذا تقاطع مع حجز في الأجندة، يفشل الصف إلا إذا أرسلت release_blocks: true. - الدفعة التي لا يمكن قراءتها كاملة (فارغة، أكثر من 200 صف، حقل غير معروف في الجسم) تستجيب بـ 400 VALIDATION_ERROR ولا تكتب شيئًا. - قد تستغرق الدفعة الكبيرة وقتًا: كل موعد ينشئ طلبه وجهة اتصاله. إذا تجاوزت دفعاتك 100 موعد، قسّمها إلى طلبات أصغر.ما تحتاجه لإدارة جدول أعمالك من نظام آخر: الخدمات التي تُحجز مع من يقدمها، الفريق، وتحميل المواعيد بالجملة. هذا هو ما تفعله أدوات MCP list_services و list_collaborators و import_appointments، بنفس أسماء الحقول.
| الطريقة | المسار | الوصف |
|---|---|---|
| GET | /v1/services | الخدمات التي تُحجز، ومن يقدمها |
| GET | /v1/collaborators | الفريق: الاسم، البريد، الدور والخدمات التي يقدمها |
| POST | /v1/appointments/import | تحميل حتى 200 موعد في طلب واحد |
كل خدمة تحمل id و name و duration_minutes و price و currency و location و active و collaborators (id و name و email لمن يقدمها). الـ id هو ما تطلبه كـ service_id عند استيراد المواعيد. الخدمات التي تُؤجَّر (غرف، قاعات، مركبات) لا تظهر هنا.
/v1/servicescurl "https://rest-api.tbit.app/v1/services" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/services', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/services',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/services',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/services');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "6a0f3c2e9b1d4a0012ab34cd",
"name": "Endodoncia",
"duration_minutes": 60,
"price": 350000,
"currency": "COP",
"location": "Sede norte · Calle 72 # 7-41",
"active": true,
"collaborators": [
{
"id": "6a0f3c2e9b1d4a0012ab0001",
"name": "Geral Díaz",
"email": "[email protected]"
}
]
}
]
}كل شخص يحمل id و name و email و role و attends_appointments (هل يقدم المواعيد) و service_ids (الخدمات التي يقدمها). عندما لا يكون للشخص اسم محمّل، يأتي name فارغًا: تعرّف عليه من بريده.
/v1/collaboratorscurl "https://rest-api.tbit.app/v1/collaborators" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/collaborators', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/collaborators',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/collaborators',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/collaborators');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "6a0f3c2e9b1d4a0012ab0001",
"name": "Geral Díaz",
"email": "[email protected]",
"role": "ADMIN",
"attends_appointments": true,
"service_ids": [
"6a0f3c2e9b1d4a0012ab34cd"
]
}
]
}أرسل حتى 200 موعدًا في كل استدعاء ضمن appointments. كل صف يحمل phone (مع رمز الدولة، مثل 573001234567: يُبحث عن جهة الاتصال برقم الهاتف، وإن لم تكن موجودة تُنشأ) أو contact_id (جهة اتصال موجودة بالفعل: يذهب الموعد إلى تلك البطاقة حتى لو لم يكن لديها رقم هاتف، كمن يكتب بمستخدم WhatsApp؛ وإذا أرسلت phone أيضًا فلا يُستخدم إلا للإشعار)، وcontact_name وemail اختياريان، والخدمة (service_id أو service_name، الاسم الدقيق دون اعتبار لحالة الأحرف)، ومن يقدّم الخدمة (collaborator_id أو collaborator_email؛ وإذا كان شخص واحد فقط يقدّم الخدمة يمكنك حذفه)، وstart بصيغة ISO 8601 (بدون منطقة زمنية يُقرأ في المنطقة الزمنية للنشاط التجاري)، وend اختياري (افتراضيًا start زائد مدة الخدمة)، وexternal_id (مفتاح الحدث في نظامك: إعادة الاستيراد لا تكرره) وnotes.
خيارات، كلها في المستوى الأول من الجسم: notify_customer (افتراضيًا false: لا يصل للعميل تأكيد؛ true يرسله كأي موعد)، و send_reminders (افتراضيًا true)، و release_blocks (true يزيل حجوزات ذلك الشخص المتقاطعة مع الموعد)، و on_existing (skip أو update: إذا وُجد موعد بنفس external_id، يتركه كما هو أو ينقله دون إشعار أحد) و dry_run (true يتحقق من كل شيء ويقول ما سيفعل، دون كتابة أي شيء). ابدأ دائمًا بـ dry_run.
تقول الاستجابة لكل صف ما حدث: status هو created أو updated أو skipped أو failed (would_create أو would_update مع dry_run)، مع appointment_id و contact_id، وإن فشل، error مع السبب بالكلمات («أندريس لا يقدم علاج الجذور؛ يقدمه: جيرالد دياز.»). صف سيئ لا يوقف الباقي. احفظ import_id: هو ما تحتاجه للتراجع.
/v1/appointments/importcurl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dry_run": true,
"appointments": [
{
"phone": "573001234567",
"contact_name": "Ana Pérez",
"service_name": "Endodoncia",
"collaborator_email": "[email protected]",
"start": "2026-11-20T10:00",
"external_id": "gcal-7f3k2"
}
]
}'const response = await fetch('https://rest-api.tbit.app/v1/appointments/import', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
dry_run: true,
appointments: [
{
phone: '573001234567',
contact_name: 'Ana Pérez',
service_name: 'Endodoncia',
collaborator_email: '[email protected]',
start: '2026-11-20T10:00',
external_id: 'gcal-7f3k2',
},
],
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/appointments/import',
{
dry_run: true,
appointments: [
{
phone: '573001234567',
contact_name: 'Ana Pérez',
service_name: 'Endodoncia',
collaborator_email: '[email protected]',
start: '2026-11-20T10:00',
external_id: 'gcal-7f3k2',
},
],
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/appointments/import',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'dry_run': True,
'appointments': [
{
'phone': '573001234567',
'contact_name': 'Ana Pérez',
'service_name': 'Endodoncia',
'collaborator_email': '[email protected]',
'start': '2026-11-20T10:00',
'external_id': 'gcal-7f3k2',
},
],
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/appointments/import');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'dry_run' => true,
'appointments' => [
[
'phone' => '573001234567',
'contact_name' => 'Ana Pérez',
'service_name' => 'Endodoncia',
'collaborator_email' => '[email protected]',
'start' => '2026-11-20T10:00',
'external_id' => 'gcal-7f3k2',
],
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"import_id": null,
"dry_run": true,
"created": 1,
"updated": 0,
"skipped": 0,
"failed": 0,
"results": [
{
"index": 0,
"external_id": "gcal-7f3k2",
"status": "would_create",
"contact_id": "6a0f3c2e9b1d4a0012ab9f10"
}
]
}
}أرسل فقط undo_import_id مع import_id الذي أعادته عملية الاستيراد: كل المواعيد التي أنشأها ذلك الاستيراد تصبح ملغاة، دون إشعار أحد، ويصبح external_id الخاص بها حرًا لإعادة استيرادها.
/v1/appointments/importcurl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"undo_import_id": "6a1e0b7c5d4f3a0012cd5678"
}'const response = await fetch('https://rest-api.tbit.app/v1/appointments/import', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
undo_import_id: '6a1e0b7c5d4f3a0012cd5678',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/appointments/import',
{
undo_import_id: '6a1e0b7c5d4f3a0012cd5678',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/appointments/import',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'undo_import_id': '6a1e0b7c5d4f3a0012cd5678',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/appointments/import');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'undo_import_id' => '6a1e0b7c5d4f3a0012cd5678',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"import_id": "6a1e0b7c5d4f3a0012cd5678",
"cancelled": 198,
"already_cancelled": 2,
"failed": []
}
}- على الشخص أن يقدم تلك الخدمة. وإلا يفشل الصف ويقول الخطأ من يقدمها فعلًا.
- لا يمكن أن يتقاطع موعد مع آخر لنفس الشخص، ولا مع صف آخر من نفس الدفعة. إذا تقاطع مع حجز في الأجندة، يفشل الصف إلا إذا أرسلت release_blocks: true.
- الدفعة التي لا يمكن قراءتها كاملة (فارغة، أكثر من 200 صف، حقل غير معروف في الجسم) تستجيب بـ 400 VALIDATION_ERROR ولا تكتب شيئًا.
- قد تستغرق الدفعة الكبيرة وقتًا: كل موعد ينشئ طلبه وجهة اتصاله. إذا تجاوزت دفعاتك 100 موعد، قسّمها إلى طلبات أصغر.