# अपॉइंटमेंट

> आपके कैलेंडर के लिए सेवाएं, टीम और बैच में अपॉइंटमेंट

- पेज: https://tbit.app/hi/docs/api/appointments
- Base URL: `https://rest-api.tbit.app/v1`
- ऑथेंटिकेशन: हर request में आपकी key के साथ `X-API-Key` header (उदाहरण इसे `TBIT_API_KEY` environment variable से पढ़ते हैं)

## सामान्य विवरण

अपने व्यवसाय का कैलेंडर किसी अन्य सिस्टम से चलाने के लिए आपको जो चाहिए: वे सेवाएं जो किसके साथ बुक होती हैं, टीम, और बैच में अपॉइंटमेंट लोड करना। यह वही है जो MCP की tools list_services, list_collaborators और import_appointments करती हैं, उन्हीं फ़ील्ड नामों के साथ।

## Endpoints

| मेथड | रूट | विवरण |
| --- | --- | --- |
| `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"
```

Response:

```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": "geral@tuclinica.co"
        }
      ]
    }
  ]
}
```

## टीम की सूची

हर व्यक्ति में 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"
```

Response:

```json
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab0001",
      "name": "Geral Díaz",
      "email": "geral@tuclinica.co",
      "role": "ADMIN",
      "attends_appointments": true,
      "service_ids": [
        "6a0f3c2e9b1d4a0012ab34cd"
      ]
    }
  ]
}
```

## अपॉइंटमेंट आयात करें

appointments में एक कॉल में 200 तक अपॉइंटमेंट भेजें। हर पंक्ति में phone (देश कोड के साथ, जैसे 573001234567: संपर्क को फ़ोन से खोजा जाता है और, अगर मौजूद न हो, तो बनाया जाता है) या contact_id (एक ऐसा संपर्क जो पहले से मौजूद है: अपॉइंटमेंट उसी प्रोफ़ाइल में जाता है भले ही उसका फ़ोन न हो, जैसे कोई WhatsApp उपयोगकर्ता से लिखता है; अगर आप phone भी भेजते हैं, तो वह सिर्फ़ सूचित करने के लिए इस्तेमाल होता है), contact_name और email वैकल्पिक, सेवा (service_id या service_name, बिल्कुल सही नाम, बड़े-छोटे अक्षरों से फ़र्क नहीं पड़ता), कौन सेवा देता है (collaborator_id या collaborator_email; अगर सेवा सिर्फ़ एक व्यक्ति देता है तो आप इसे छोड़ सकते हैं), start ISO 8601 में (बिना ज़ोन के हो तो व्यवसाय के ज़ोन में पढ़ा जाता है), end वैकल्पिक (डिफ़ॉल्ट रूप से start में सेवा की अवधि जोड़कर), external_id (आपके सिस्टम में इवेंट की key: दोबारा इम्पोर्ट करने पर डुप्लिकेट नहीं होता) और 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 है (dry_run के साथ would_create या would_update), appointment_id, contact_id के साथ और, यदि विफल हुआ, तो error में कारण शब्दों में («Andrés no atiende Endodoncia; lo atienden: Geral Díaz.»)। एक खराब पंक्ति बाकी को नहीं रोकती। 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": "geral@tuclinica.co",
        "start": "2026-11-20T10:00",
        "external_id": "gcal-7f3k2"
      }
    ]
  }'
```

Response:

```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"
  }'
```

Response:

```json
{
  "data": {
    "import_id": "6a1e0b7c5d4f3a0012cd5678",
    "cancelled": 198,
    "already_cancelled": 2,
    "failed": []
  }
}
```

## नियम और त्रुटियाँ

- व्यक्ति को वह सेवा संभालनी चाहिए। यदि नहीं, तो पंक्ति विफल हो जाती है और त्रुटि बताती है कि कौन इसे संभालता है।
- एक अपॉइंटमेंट उसी व्यक्ति के किसी अन्य अपॉइंटमेंट से नहीं टकरा सकता, न ही उसी बैच की किसी अन्य पंक्ति से। यदि यह शेड्यूल ब्लॉक से टकराता है, तो पंक्ति विफल हो जाती है जब तक आप release_blocks: true न भेजें।
- एक बैच जिसे पूरा पढ़ा नहीं जा सकता (खाली, 200 से अधिक पंक्तियाँ, बॉडी में अज्ञात फ़ील्ड) 400 VALIDATION_ERROR के साथ प्रतिक्रिया देता है और कुछ नहीं लिखता।
- एक बड़े बैच में समय लग सकता है: हर अपॉइंटमेंट अपना ऑर्डर और अपना संपर्क बनाता है। यदि आपके बैच 100 अपॉइंटमेंट से अधिक हैं, तो उन्हें छोटी कॉल में बाँटें।
