انتقل إلى المحتوى
القائمة

ابحث في الموقع

اكتب للبحث في الأدلة والمدونة والـ API والمنتج.

↑ ↓ للتنقل · Enter للفتح · Esc للإغلاق

مرجع الـ API

API

المواعيد

الخدمات والفريق والمواعيد بالجملة لجدولك

عرض بصيغة Markdown

ما تحتاجه لإدارة جدول أعمالك من نظام آخر: الخدمات التي تُحجز مع من يقدمها، الفريق، وتحميل المواعيد بالجملة. هذا هو ما تفعله أدوات 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
curl "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 فارغًا: تعرّف عليه من بريده.

GET/v1/collaborators
curl "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: هو ما تحتاجه للتراجع.

POST/v1/appointments/import
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"
      }
    ]
  }'
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 الخاص بها حرًا لإعادة استيرادها.

POST/v1/appointments/import
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"
  }'
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 موعد، قسّمها إلى طلبات أصغر.