# Calendar API ও MCP


# Calendar API ও MCP

imatic Calendar-এ আপনি যা কিছু করেন, তা স্বয়ংক্রিয় করতে পারেন। স্লট কোয়েরি করতে এবং বুকিং তৈরি করতে **REST API** ব্যবহার করুন, রিয়েল টাইমে ইভেন্টে প্রতিক্রিয়া জানাতে **webhook**, এবং একটি AI এজেন্টকে আপনার পক্ষ থেকে বুক করতে দিতে **MCP সার্ভার**। এই পেজটি সেইসব ডেভেলপারদের জন্য যারা imatic Calendar-কে তাদের নিজস্ব অ্যাপ ও টুলে যুক্ত করছেন।

আপনি আপনার ড্যাশবোর্ডের **Developers**-এর অধীনে ক্রেডেনশিয়াল পরিচালনা করেন।

:::note[অ্যাডমিন-পরিচালিত]

**API keys** এবং **Webhooks** পেজগুলি একজন **অ্যাকাউন্ট অ্যাডমিন** দ্বারা পরিচালিত হয়। যদি আপনি আপনার ড্যাশবোর্ডে এগুলি না দেখেন, আপনার অ্যাকাউন্টের একজন অ্যাডমিনকে আপনার জন্য একটি কী ইস্যু করতে বা একটি webhook সেট আপ করতে বলুন।

:::

## অথেনটিকেশন ও API কী

API-তে কলগুলি একটি bearer টোকেন হিসেবে পাঠানো একটি **API কী** দিয়ে অথেনটিকেট করা হয়:

```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

Webhook ঘটনা ঘটার মুহূর্তেই আপনার সার্ভারে ইভেন্ট পুশ করে, তাই আপনাকে পোল করতে হয় না। **Developers → Webhooks**-এর অধীনে এগুলি পরিচালনা করুন।

- বুকিং ইভেন্ট পেতে একটি URL **সাবস্ক্রাইব** করুন। ইভেন্টগুলি ঠিক এই: `booking.created`, `booking.cancelled`, `booking.rescheduled`, এবং `booking.no_show`।
- প্রতিটি ডেলিভারি **HMAC দিয়ে স্বাক্ষরিত** — পেলোড বিশ্বাস করার আগে অনুরোধটি সত্যিই imatic Calendar থেকে এসেছে তা নিশ্চিত করতে আপনার webhook-এর সিক্রেটের বিপরীতে স্বাক্ষর হেডার যাচাই করুন।
- আপনি তৈরি করার সময় আপনার এন্ডপয়েন্টে একটি নমুনা ইভেন্ট পাঠাতে অন্তর্নির্মিত **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 কখন বৃহস্পতিবার মুক্ত?" উত্তর দিতে এবং স্লটটি বুক করতে পারে — সবই আপনি সেই কী-কে দেওয়া স্কোপের মধ্যে।

অ্যাকাউন্টের নিজস্ব প্রোফাইল একটি MCP টুলের মাধ্যমে নয়, বরং REST-এর মাধ্যমে `GET /v1/users/me` দিয়ে পড়া হয়।

:::note[আপনার এজেন্টের কী শক্তভাবে স্কোপ করুন]

একটি AI এজেন্টকে শুধুমাত্র তার প্রয়োজনীয় টুলগুলি সহ একটি কী দিন। যদি এটির শুধুমাত্র প্রাপ্যতা পড়ার প্রয়োজন হয়, এটিকে বাতিল বা রিশিডিউল অনুমতি দেবেন না।

:::

## পরবর্তী ধাপ

- [ইন্টিগ্রেশন](./integrations) — দ্বিমুখী সিঙ্কের জন্য Google এবং Outlook সংযুক্ত করুন।
- [ইভেন্ট টাইপ](./event-types) — যে রিসোর্সকে কেন্দ্র করে আপনার বেশিরভাগ API কল ঘোরে।
- [আপনার পাবলিক বুকিং পেজ](./booking-page) — যে নো-কোড পথটি আপনার অটোমেশন প্রতিফলিত করে।