# Calendar API और MCP


# Calendar API और MCP

imatic Calendar में आप जो कुछ भी करते हैं, उसे आप स्वचालित कर सकते हैं। स्लॉट क्वेरी करने और बुकिंग बनाने के लिए **REST API**, रीयल टाइम में इवेंट पर प्रतिक्रिया देने के लिए **webhooks**, और किसी AI एजेंट को आपकी ओर से बुक करने देने के लिए **MCP सर्वर** का उपयोग करें। यह पेज उन डेवलपर्स के लिए है जो imatic Calendar को अपने स्वयं के ऐप और टूल में जोड़ रहे हैं।

आप अपने डैशबोर्ड में **Developers** के अंतर्गत क्रेडेंशियल प्रबंधित करते हैं।

:::note[एडमिन-प्रबंधित]

**API keys** और **Webhooks** पेज एक **खाता एडमिन** (org एडमिन या super एडमिन) द्वारा प्रबंधित किए जाते हैं। यदि आप उन्हें अपने डैशबोर्ड में नहीं देखते, तो अपने खाते के किसी एडमिन से कुंजी जारी करने या आपके लिए webhook सेट करने को कहें।

:::

## प्रमाणीकरण और API कुंजियाँ

API पर कॉल एक **API कुंजी** से प्रमाणित होती हैं जो bearer टोकन के रूप में भेजी जाती है:

```http
Authorization: Bearer <your_api_key>
```

कुंजियों को **Developers → API keys** के अंतर्गत प्रबंधित करें, जहाँ आप:

- एक कुंजी **बनाएँ** — जब सीक्रेट दिखाया जाए तो उसे कॉपी करें; यह दोबारा प्रदर्शित नहीं किया जाता।
- अपनी कुंजियों की **सूची** देखें और देखें कि प्रत्येक किसलिए है।
- कोई कुंजी लीक होने या अब आवश्यक न रहने पर उसे तुरंत **रद्द** करें।
- **स्कोप** असाइन करें — प्रत्येक कुंजी केवल वही अनुमतियाँ रखती है जो आप देते हैं, इसलिए एक केवल-पठनीय कुंजी बुकिंग की सूची तो दे सकती है पर उन्हें कभी बना या रद्द नहीं कर सकती।

उपलब्ध स्कोप हैं:

| स्कोप | अनुमति देता है |
| --- | --- |
| `slots:read` | किसी इवेंट प्रकार के लिए उपलब्ध समय स्लॉट पढ़ना |
| `bookings:read` | बुकिंग की सूची देखना और पढ़ना |
| `bookings:write` | बुकिंग बनाना, रद्द करना, और पुनर्निर्धारित करना |
| `mcp` | MCP सर्वर का उपयोग करना (एक छत्र स्कोप जो `slots:read`, `bookings:read`, और `bookings:write` को भी कवर करता है) |

:::warning[कुंजियों को पासवर्ड की तरह समझें]

एक कुंजी अपने स्कोप के भीतर आपके खाते तक पहुँच देती है। इसे किसी सीक्रेट मैनेजर या एनवायरनमेंट वेरिएबल में रखें, कभी क्लाइंट-साइड कोड या सार्वजनिक रिपॉज़िटरी में नहीं। यदि यह उजागर हो जाए तो तुरंत रद्द करें और घुमाएँ।

:::

## REST API v1

REST API `/v1` बेस पाथ के अंतर्गत प्रस्तुत किया जाता है और JSON लौटाता है। उपलब्ध संसाधन हैं:

- **Event types** — अपने [इवेंट प्रकार](./event-types) की **सूची देखें और पढ़ें**, साथ ही किसी इवेंट प्रकार की **नकल** करें (`POST /v1/event-types/:code/duplicate`)। (बनाना/संपादन/हटाना डैशबोर्ड में किया जाता है।)
- **Slots** — किसी इवेंट प्रकार के लिए उपलब्ध समय स्लॉट क्वेरी करें (वही उपलब्ध समय जो आपके [बुकिंग पेज](./booking-page) पर दिखते हैं, सभी बफ़र, सूचना, और सीमाएँ लागू होने के साथ)।
- **Bookings** — पूर्ण CRUD के साथ-साथ **पुनर्निर्धारण**: एक बुकिंग बनाएँ, बुकिंग की सूची देखें और पढ़ें, रद्द करें, और किसी को नए समय पर ले जाएँ। `GET /v1/bookings/stats` कुल बुकिंग गणना लौटाता है।
- **Event links** — किसी इवेंट प्रकार से जुड़े एकल-उपयोग बुकिंग लिंक बनाएँ, सूचीबद्ध करें, और रद्द करें (`POST`/`GET /v1/event-types/:code/links`, `DELETE /v1/event-links/:linkCode`)।
- **Webhooks** — अपनी webhook सदस्यताओं को प्रोग्रामेटिक रूप से प्रबंधित करें।
- **Users / me** — `GET /v1/users/me` API कुंजी की पहचान लौटाता है (प्रमाणित खाता और org)।
- **Calendars** — अपने जुड़े हुए कैलेंडर के साथ काम करें ([इंटीग्रेशन](./integrations) देखें)।

एक सामान्य स्वचालन प्रवाह: किसी इवेंट प्रकार के लिए **slots** क्वेरी करें, फिर आपके उपयोगकर्ता द्वारा चुने गए स्लॉट के लिए एक **booking** बनाएँ — वही एटॉमिक, दोहरी-बुकिंग न होने की गारंटी जो [बुकिंग पेज](./booking-page#कभी-भी-दोहरी-बुकिंग-नहीं) उपयोग करता है, API पर भी लागू होती है।

## Webhooks

Webhooks इवेंट होते ही उन्हें आपके सर्वर पर भेज देते हैं, इसलिए आपको पोल करने की ज़रूरत नहीं। इन्हें **Developers → Webhooks** के अंतर्गत प्रबंधित करें।

- बुकिंग इवेंट प्राप्त करने के लिए किसी URL को **सब्सक्राइब** करें। इवेंट ठीक ये हैं: `booking.created`, `booking.cancelled`, `booking.rescheduled`, और `booking.no_show`।
- प्रत्येक डिलीवरी **HMAC के साथ हस्ताक्षरित** होती है — पेलोड पर भरोसा करने से पहले अपने webhook के सीक्रेट के विरुद्ध हस्ताक्षर हेडर की पुष्टि करें ताकि यह पक्का हो सके कि अनुरोध वास्तव में imatic Calendar से आया है।
- बनाते समय अपने एंडपॉइंट पर एक नमूना इवेंट भेजने के लिए अंतर्निहित **Test** क्रिया का उपयोग करें, ताकि लाइव होने से पहले आप पुष्टि कर सकें कि आपका हैंडलर काम करता है।

हस्ताक्षर `X-Imatic-Signature` हेडर में, Stripe-शैली प्रारूप में आता है:

```http
X-Imatic-Signature: t=<unix-epoch-seconds>,v1=<hmac-sha256>
```

पुष्टि करने के लिए: `t` और कच्चा अनुरोध बॉडी लें, `HMAC-SHA256(secret, "<t>.<body>")` की गणना करें (टाइमस्टैम्प और बॉडी एक शाब्दिक बिंदु से जुड़े), इसे hex-एनकोड करें, और इसकी तुलना `v1` से करें। यदि वे मेल नहीं खाते तो अनुरोध अस्वीकार करें।

:::tip[हमेशा हस्ताक्षर की पुष्टि करें]

किसी भी ऐसे webhook को अस्वीकार करें जिसका HMAC हस्ताक्षर मेल नहीं खाता। यही एक भरोसेमंद स्वचालन और एक खुले दरवाज़े के बीच का अंतर है।

:::

## MCP सर्वर

imatic Calendar एक **Model Context Protocol (MCP) सर्वर** के साथ आता है, ताकि AI एजेंट और सहायक अच्छी तरह परिभाषित टूल के माध्यम से आपकी उपलब्धता पढ़ सकें और बुकिंग प्रबंधित कर सकें — REST API की तरह ही API-कुंजी प्रमाणीकरण और स्कोप का उपयोग करते हुए।

सर्वर **सात टूल** उजागर करता है:

| टूल | यह क्या करता है |
| --- | --- |
| `list_event_types` | आपके बुक करने योग्य इवेंट प्रकारों की सूची देता है |
| `list_slots` | किसी इवेंट प्रकार के लिए खुले स्लॉट प्राप्त करता है |
| `create_booking` | एक स्लॉट बुक करता है |
| `cancel_booking` | एक बुकिंग रद्द करता है |
| `reschedule_booking` | किसी बुकिंग को नए समय पर ले जाता है |
| `list_bookings` | मौजूदा बुकिंग की सूची देता है |
| `get_booking` | किसी एकल बुकिंग को उसके कोड से पढ़ता है |

अपने MCP-सक्षम क्लाइंट को सर्वर पर इंगित करें, एक API कुंजी से प्रमाणित करें, और आपका एजेंट "Priya गुरुवार को कब खाली है?" का उत्तर देकर स्लॉट बुक कर सकता है — सब कुछ उन स्कोप के भीतर जो आपने उस कुंजी को दिए हैं।

खाते की अपनी प्रोफ़ाइल REST के माध्यम से `GET /v1/users/me` से पढ़ी जाती है, किसी MCP टूल के माध्यम से नहीं।

:::note[अपने एजेंट की कुंजी को कसकर स्कोप करें]

किसी AI एजेंट को केवल उन्हीं टूल वाली कुंजी दें जिनकी उसे ज़रूरत है। यदि उसे केवल उपलब्धता पढ़नी है, तो उसे रद्द या पुनर्निर्धारण की अनुमतियाँ न दें।

:::

## अगले कदम

- [इंटीग्रेशन](./integrations) — दो-तरफ़ा सिंक के लिए Google और Outlook कनेक्ट करें।
- [इवेंट प्रकार](./event-types) — वह संसाधन जिसके इर्द-गिर्द आपकी अधिकांश API कॉल घूमती हैं।
- [आपका सार्वजनिक बुकिंग पेज](./booking-page) — वह नो-कोड पथ जिसकी आपके स्वचालन नकल करते हैं।