# Calendar API અને MCP


# Calendar API અને MCP

imatic Calendar માં તમે જે કંઈ કરો છો, તે તમે ઓટોમેટ કરી શકો છો. સ્લોટ્સ ક્વેરી કરવા અને બુકિંગ્સ બનાવવા માટે **REST API** નો ઉપયોગ કરો, રિયલ ટાઇમમાં ઇવેન્ટ્સ પર પ્રતિક્રિયા આપવા માટે **webhooks**, અને AI એજન્ટને તમારા વતી બુક કરવા દેવા માટે **MCP સર્વર**. આ પેજ એવા ડેવલપર્સ માટે છે જે imatic Calendar ને તેમની પોતાની એપ્સ અને ટૂલ્સમાં વાયર કરી રહ્યા છે.

તમે તમારા ડેશબોર્ડમાં **Developers** હેઠળ ઓળખપત્રો મેનેજ કરો છો.

:::note[એડમિન-મેનેજ્ડ]

**API keys** અને **Webhooks** પેજ **એકાઉન્ટ એડમિન** દ્વારા મેનેજ થાય છે. જો તમે તેમને તમારા ડેશબોર્ડમાં ન જુઓ, તો તમારા એકાઉન્ટ પરના એડમિનને તમારા માટે કી ઇશ્યૂ કરવા અથવા webhook સેટ કરવા કહો.

:::

## ઓથેન્ટિકેશન અને 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[કીને પાસવર્ડ જેવી ગણો]

કી તેના સ્કોપ્સની અંદર તમારા એકાઉન્ટની ઍક્સેસ આપે છે. તેને secret manager અથવા environment variable માં સંગ્રહ કરો, ક્યારેય ક્લાયન્ટ-સાઇડ કોડ અથવા સાર્વજનિક repo માં નહીં. જો તે ખુલ્લી પડે તો તરત જ રદ કરો અને રોટેટ કરો.

:::

## 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** — તમારા webhook સબ્સ્ક્રિપ્શન્સને પ્રોગ્રામેટિક રીતે મેનેજ કરો.
- **Users / me** — `GET /v1/users/me` API કીની ઓળખ પરત કરે છે (ઓથેન્ટિકેટ થયેલ એકાઉન્ટ અને org).
- **Calendars** — તમારા જોડાયેલ કેલેન્ડર્સ સાથે કામ કરો ([Integrations](./integrations) જુઓ).

એક લાક્ષણિક ઓટોમેશન પ્રવાહ: ઇવેન્ટ પ્રકાર માટે **slots** ક્વેરી કરો, પછી તમારા યુઝરે પસંદ કરેલા સ્લોટ માટે **booking** બનાવો — એ જ અણ્વાત્મક, નો-ડબલ-બુક ગેરંટી જે [બુકિંગ પેજ](./booking-page#ક્યારેય-ડબલ-બુકિંગ-નહીં) વાપરે છે તે API ને પણ લાગુ પડે છે.

## Webhooks

Webhooks ઇવેન્ટ્સ થતાં જ તમારા સર્વર પર પુશ કરે છે, જેથી તમારે પોલ કરવાની જરૂર નથી. તેમને **Developers → Webhooks** હેઠળ મેનેજ કરો.

- બુકિંગ ઇવેન્ટ્સ પ્રાપ્ત કરવા માટે URL ને **સબ્સ્ક્રાઇબ** કરો. ઇવેન્ટ્સ બરાબર આ છે: `booking.created`, `booking.cancelled`, `booking.rescheduled`, અને `booking.no_show`.
- દરેક ડિલિવરી **HMAC સાથે સહી થયેલી** હોય છે — પેલોડ પર વિશ્વાસ કરતા પહેલા વિનંતી ખરેખર imatic Calendar પરથી આવી છે તેની પુષ્ટિ કરવા માટે તમારા webhook ના રહસ્ય સામે signature header ચકાસો.
- બિલ્ટ-ઇન **Test** ક્રિયાનો ઉપયોગ કરો અને જ્યારે તમે બિલ્ડ કરી રહ્યા હો ત્યારે તમારા એન્ડપોઇન્ટ પર સેમ્પલ ઇવેન્ટ મોકલો, જેથી લાઇવ થતા પહેલા તમે ખાતરી કરી શકો કે તમારું હેન્ડલર કામ કરે છે.

સહી `X-Imatic-Signature` header માં, Stripe-શૈલીના ફોર્મેટમાં મુસાફરી કરે છે:

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

ચકાસવા માટે: `t` અને કાચું વિનંતી બોડી લો, `HMAC-SHA256(secret, "<t>.<body>")` ગણો (ટાઇમસ્ટેમ્પ અને બોડી શાબ્દિક ડોટથી જોડાયેલા), તેને hex-encode કરો, અને તેને `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](./integrations) — દ્વિ-માર્ગી સિંક માટે Google અને Outlook જોડો.
- [ઇવેન્ટ પ્રકારો](./event-types) — તે રિસોર્સ જેની આસપાસ તમારા મોટાભાગના API કોલ્સ ફરે છે.
- [તમારું સાર્વજનિક બુકિંગ પેજ](./booking-page) — નો-કોડ પાથ જેને તમારા ઓટોમેશન્સ પ્રતિબિંબિત કરે છે.