# Calendar API आणि MCP


# Calendar API आणि MCP

imatic Calendar मध्ये तुम्ही जे काही करता, ते तुम्ही स्वयंचलित करू शकता. स्लॉटची चौकशी करण्यासाठी आणि बुकिंग तयार करण्यासाठी **REST API** वापरा, इव्हेंटवर रिअल टाइममध्ये प्रतिक्रिया देण्यासाठी **वेबहुक** वापरा, आणि AI एजंटला तुमच्या वतीने बुक करू देण्यासाठी **MCP सर्व्हर** वापरा. हे पृष्ठ imatic Calendar त्यांच्या स्वतःच्या ॲप्स आणि साधनांमध्ये जोडणाऱ्या डेव्हलपर्ससाठी आहे.

तुम्ही तुमच्या डॅशबोर्डमधील **Developers** अंतर्गत क्रेडेन्शियल्स व्यवस्थापित करता.

:::note[ॲडमिन-व्यवस्थापित]

**API keys** आणि **Webhooks** पृष्ठे एका **खाते ॲडमिन** द्वारे व्यवस्थापित केली जातात. जर तुम्हाला ती तुमच्या डॅशबोर्डमध्ये दिसत नसतील, तर तुमच्या खात्यावरील ॲडमिनला तुमच्यासाठी की देण्यास किंवा वेबहुक सेट करण्यास सांगा.

:::

## प्रमाणीकरण आणि API की

API ला केलेले कॉल **API की** द्वारे प्रमाणित केले जातात जी bearer token म्हणून पाठवली जाते:

```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 अधिक **reschedule**: एक बुकिंग तयार करा, बुकिंग सूचीबद्ध करा आणि वाचा, रद्द करा, आणि एक नवीन वेळेत हलवा. `GET /v1/bookings/stats` एकत्रित बुकिंग संख्या परत करते.
- **Event links** — एका इव्हेंट प्रकाराशी जोडलेल्या एकल-वापर बुकिंग लिंक तयार करा, सूचीबद्ध करा आणि रद्द करा (`POST`/`GET /v1/event-types/:code/links`, `DELETE /v1/event-links/:linkCode`).
- **Webhooks** — तुमचे वेबहुक सबस्क्रिप्शन प्रोग्रामॅटिकली व्यवस्थापित करा.
- **Users / me** — `GET /v1/users/me` API कीची ओळख परत करते (प्रमाणित खाते आणि org).
- **Calendars** — तुमच्या जोडलेल्या कॅलेंडरसह कार्य करा ([इंटिग्रेशन्स](./integrations) पहा).

एक विशिष्ट स्वयंचलन प्रवाह: एका इव्हेंट प्रकारासाठी **slots** ची चौकशी करा, मग तुमच्या वापरकर्त्याने निवडलेल्या स्लॉटसाठी एक **booking** तयार करा — [बुकिंग पृष्ठ](./booking-page#कधीही-डबल-बुकिंग-नाही) जी तीच अणुस्तरीय, डबल-बुक-नाही हमी वापरते ती API लाही लागू होते.

## वेबहुक

वेबहुक इव्हेंट घडताच तुमच्या सर्व्हरकडे पुश करतात, त्यामुळे तुम्हाला पोल करावे लागत नाही. ती **Developers → Webhooks** अंतर्गत व्यवस्थापित करा.

- बुकिंग इव्हेंट प्राप्त करण्यासाठी एक URL **सबस्क्राइब** करा. इव्हेंट नेमके हे आहेत: `booking.created`, `booking.cancelled`, `booking.rescheduled`, आणि `booking.no_show`.
- प्रत्येक डिलिव्हरी **HMAC ने स्वाक्षरीकृत** असते — पेलोडवर विश्वास ठेवण्याआधी विनंती खरोखर 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[नेहमी स्वाक्षरी पडताळा]

ज्याची 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 गुरुवारी कधी मोकळी आहे?" याचे उत्तर देऊन तो स्लॉट बुक करू शकतो — तुम्ही त्या कीला दिलेल्या स्कोपमध्येच.

खात्याचे स्वतःचे प्रोफाइल MCP साधनाद्वारे नव्हे तर `GET /v1/users/me` ने REST वर वाचले जाते.

:::note[तुमच्या एजंटची की घट्ट स्कोप करा]

AI एजंटला फक्त त्याला आवश्यक असलेली साधने असलेली की द्या. जर त्याला फक्त उपलब्धता वाचायची असेल, तर त्याला रद्द किंवा पुनर्नियोजन परवानग्या देऊ नका.

:::

## पुढील पावले

- [इंटिग्रेशन्स](./integrations) — दुहेरी सिंकसाठी Google आणि Outlook जोडा.
- [इव्हेंट प्रकार](./event-types) — तुमचे बहुतेक API कॉल ज्याभोवती फिरतात ते संसाधन.
- [तुमचे सार्वजनिक बुकिंग पृष्ठ](./booking-page) — तुमची स्वयंचलने ज्याची नक्कल करतात तो नो-कोड मार्ग.