# Calendar API & MCP


# Calendar API & MCP

imatic Calendar-ൽ നിങ്ങൾ ചെയ്യുന്നതെല്ലാം നിങ്ങൾക്ക് ഓട്ടോമേറ്റ് ചെയ്യാം. സ്ലോട്ടുകൾ അന്വേഷിക്കാനും ബുക്കിംഗുകൾ സൃഷ്ടിക്കാനും **REST API** ഉപയോഗിക്കുക, ഇവന്റുകളോട് തത്സമയം പ്രതികരിക്കാൻ **webhooks** ഉപയോഗിക്കുക, ഒപ്പം ഒരു AI ഏജന്റിനെ നിങ്ങൾക്കുവേണ്ടി ബുക്ക് ചെയ്യാൻ അനുവദിക്കാൻ **MCP server** ഉപയോഗിക്കുക. imatic Calendar സ്വന്തം ആപ്പുകളിലേക്കും ടൂളുകളിലേക്കും വയർ ചെയ്യുന്ന ഡെവലപ്പർമാർക്കുള്ളതാണ് ഈ പേജ്.

നിങ്ങളുടെ ഡാഷ്ബോർഡിലെ **Developers**-ന് കീഴിൽ നിങ്ങൾ ക്രെഡൻഷ്യലുകൾ കൈകാര്യം ചെയ്യുന്നു.

:::note[അഡ്മിൻ-കൈകാര്യം ചെയ്യുന്നത്]

**API keys**, **Webhooks** പേജുകൾ ഒരു **account admin** കൈകാര്യം ചെയ്യുന്നു. നിങ്ങളുടെ ഡാഷ്ബോർഡിൽ അവ കാണുന്നില്ലെങ്കിൽ, നിങ്ങൾക്കായി ഒരു കീ ഇഷ്യൂ ചെയ്യാനോ വെബ്‌ഹുക്ക് സജ്ജമാക്കാനോ നിങ്ങളുടെ അക്കൗണ്ടിലെ ഒരു അഡ്മിനോട് ആവശ്യപ്പെടുക.

:::

## പ്രാമാണീകരണവും API കീകളും

API-യിലേക്കുള്ള കോളുകൾ ഒരു bearer ടോക്കൺ ആയി അയയ്ക്കുന്ന ഒരു **API key** ഉപയോഗിച്ച് പ്രാമാണീകരിക്കുന്നു:

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

**Developers → API keys**-ന് കീഴിൽ കീകൾ കൈകാര്യം ചെയ്യുക, അവിടെ നിങ്ങൾക്ക്:

- ഒരു കീ **Create** ചെയ്യുക — കാണിക്കുമ്പോൾ രഹസ്യം പകർത്തുക; അത് വീണ്ടും കാണിക്കില്ല.
- നിങ്ങളുടെ കീകൾ **List** ചെയ്യുക, ഓരോന്നും എന്തിനുള്ളതാണെന്ന് കാണുക.
- ഒരു കീ ലീക്ക് ആയാലോ ഇനി ആവശ്യമില്ലെങ്കിലോ ഉടനെ **Revoke** ചെയ്യുക.
- **Scopes** അസൈൻ ചെയ്യുക — ഓരോ കീയും നിങ്ങൾ നൽകുന്ന അനുമതികൾ മാത്രമേ വഹിക്കൂ, അതിനാൽ വായിക്കാൻ-മാത്രമുള്ള ഒരു കീക്ക് ബുക്കിംഗുകൾ പട്ടികപ്പെടുത്താൻ കഴിയും, പക്ഷേ അവ ഒരിക്കലും സൃഷ്ടിക്കാനോ റദ്ദാക്കാനോ കഴിയില്ല.

ലഭ്യമായ സ്കോപ്പുകൾ ഇവയാണ്:

| സ്കോപ്പ് | അനുവദിക്കുന്നത് |
| --- | --- |
| `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](./integrations) കാണുക).

ഒരു സാധാരണ ഓട്ടോമേഷൻ പ്രവാഹം: ഒരു ഇവന്റ് തരത്തിന് **slots** അന്വേഷിക്കുക, പിന്നീട് നിങ്ങളുടെ ഉപയോക്താവ് തിരഞ്ഞെടുത്ത സ്ലോട്ടിന് ഒരു **booking** സൃഷ്ടിക്കുക — [ബുക്കിംഗ് പേജ്](./booking-page#ഇരട്ട-ബുക്കിംഗുകൾ-ഒരിക്കലുമില്ല) ഉപയോഗിക്കുന്ന അതേ ആറ്റോമിക്, ഇരട്ട-ബുക്ക്-ഇല്ലാത്ത ഉറപ്പ് API-ക്കും ബാധകമാണ്.

## വെബ്‌ഹുക്കുകൾ

ഇവന്റുകൾ സംഭവിക്കുന്ന നിമിഷം വെബ്‌ഹുക്കുകൾ അവ നിങ്ങളുടെ സെർവറിലേക്ക് പുഷ് ചെയ്യുന്നു, അതിനാൽ നിങ്ങൾക്ക് പോൾ ചെയ്യേണ്ടതില്ല. **Developers → Webhooks**-ന് കീഴിൽ അവ കൈകാര്യം ചെയ്യുക.

- ബുക്കിംഗ് ഇവന്റുകൾ സ്വീകരിക്കാൻ ഒരു URL **Subscribe** ചെയ്യുക. ഇവന്റുകൾ കൃത്യമായി ഇവയാണ്: `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) server** അയയ്ക്കുന്നു, അതിനാൽ 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](./integrations) — രണ്ട്-വഴി സിങ്കിനായി Google-ഉം Outlook-ഉം കണക്റ്റ് ചെയ്യുക.
- [ഇവന്റ് തരങ്ങൾ](./event-types) — നിങ്ങളുടെ മിക്ക API കോളുകളും ചുറ്റിക്കറങ്ങുന്ന റിസോഴ്സ്.
- [നിങ്ങളുടെ പൊതു ബുക്കിംഗ് പേജ്](./booking-page) — നിങ്ങളുടെ ഓട്ടോമേഷനുകൾ പ്രതിഫലിപ്പിക്കുന്ന നോ-കോഡ് പാത.