# క్యాలెండర్ API & MCP


# క్యాలెండర్ API & MCP

imatic Calendarలో మీరు చేసే ప్రతిదాన్ని మీరు ఆటోమేట్ చేయవచ్చు. స్లాట్‌లను ప్రశ్నించడానికి మరియు బుకింగ్‌లను సృష్టించడానికి **REST API**ను, రియల్ టైమ్‌లో ఈవెంట్‌లకు ప్రతిస్పందించడానికి **వెబ్‌హుక్‌లు**ను, మరియు మీ తరఫున AI ఏజెంట్ బుక్ చేయడానికి **MCP సర్వర్**ను ఉపయోగించండి. ఈ పేజీ imatic Calendarను తమ స్వంత యాప్‌లు మరియు సాధనాలలోకి వైర్ చేసే డెవలపర్‌ల కోసం.

మీరు మీ డ్యాష్‌బోర్డ్‌లో **Developers** క్రింద ఆధారాలను నిర్వహిస్తారు.

:::note[అడ్మిన్-నిర్వహించబడింది]

**API keys** మరియు **Webhooks** పేజీలు ఒక **account admin** ద్వారా నిర్వహించబడతాయి. మీరు వాటిని మీ డ్యాష్‌బోర్డ్‌లో చూడకపోతే, మీ కోసం ఒక కీని జారీ చేయడానికి లేదా ఒక వెబ్‌హుక్‌ను సెటప్ చేయడానికి మీ ఖాతాపై ఒక అడ్మిన్‌ను అడగండి.

:::

## ప్రామాణీకరణ & API కీలు

API కు చేసే కాల్‌లు బేరర్ టోకెన్‌గా పంపబడిన ఒక **API key**తో ప్రామాణీకరించబడతాయి:

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

**Developers → API keys** క్రింద కీలను నిర్వహించండి, అక్కడ మీరు:

- ఒక కీని **సృష్టించండి** — చూపించినప్పుడు రహస్యాన్ని కాపీ చేయండి; అది మళ్లీ ప్రదర్శించబడదు.
- మీ కీలను **జాబితా** చేయండి మరియు ప్రతి ఒక్కటి దేని కోసమో చూడండి.
- అది లీక్ అయితే లేదా ఇకపై అవసరం లేకపోతే ఒక కీని తక్షణమే **రద్దు** చేయండి.
- **స్కోప్‌లు**ను కేటాయించండి — ప్రతి కీ మీరు మంజూరు చేసిన అనుమతులను మాత్రమే కలిగి ఉంటుంది, కాబట్టి ఒక చదవడానికి-మాత్రమే కీ బుకింగ్‌లను జాబితా చేయగలదు కానీ వాటిని ఎప్పటికీ సృష్టించలేదు లేదా రద్దు చేయలేదు.

అందుబాటులో ఉన్న స్కోప్‌లు:

| Scope | మంజూరు చేస్తుంది |
| --- | --- |
| `slots:read` | ఒక ఈవెంట్ రకం కోసం అందుబాటులో ఉన్న సమయ స్లాట్‌లను చదవండి |
| `bookings:read` | బుకింగ్‌లను జాబితా చేయండి మరియు చదవండి |
| `bookings:write` | బుకింగ్‌లను సృష్టించండి, రద్దు చేయండి, మరియు రీషెడ్యూల్ చేయండి |
| `mcp` | MCP సర్వర్‌ను ఉపయోగించండి (`slots:read`, `bookings:read`, మరియు `bookings:write`లను కూడా కవర్ చేసే ఒక గొడుగు) |

:::warning[కీలను పాస్‌వర్డ్‌ల వలె భావించండి]

ఒక కీ దాని స్కోప్‌లలో మీ ఖాతాకు యాక్సెస్‌ను మంజూరు చేస్తుంది. దానిని ఒక సీక్రెట్ మేనేజర్ లేదా ఎన్విరాన్‌మెంట్ వేరియబుల్‌లో నిల్వ చేయండి, ఎప్పుడూ క్లయింట్-సైడ్ కోడ్‌లో లేదా పబ్లిక్ రెపోలో కాదు. అది బయటపడితే వెంటనే రద్దు చేయండి మరియు తిప్పండి.

:::

## REST API v1

REST API `/v1` బేస్ పాత్ క్రింద అందించబడుతుంది మరియు JSONను తిరిగి ఇస్తుంది. అందుబాటులో ఉన్న వనరులు:

- **ఈవెంట్ రకాలు** — మీ [ఈవెంట్ రకాలు](./event-types)ను **జాబితా చేయండి మరియు చదవండి**, అలాగే ఒక ఈవెంట్ రకాన్ని **నకలు చేయండి** (`POST /v1/event-types/:code/duplicate`). (సృష్టించడం/సవరించడం/తొలగించడం డ్యాష్‌బోర్డ్‌లో జరుగుతుంది.)
- **స్లాట్‌లు** — ఒక ఈవెంట్ రకం కోసం అందుబాటులో ఉన్న సమయ స్లాట్‌లను ప్రశ్నించండి (మీ [బుకింగ్ పేజీ](./booking-page)లో చూపించిన అదే ఖాళీలు, అన్ని బఫర్‌లు, నోటీసు, మరియు పరిమితులు వర్తింపజేయబడ్డాయి).
- **బుకింగ్‌లు** — పూర్తి CRUD ప్లస్ **రీషెడ్యూల్**: ఒక బుకింగ్‌ను సృష్టించండి, బుకింగ్‌లను జాబితా చేయండి మరియు చదవండి, రద్దు చేయండి, మరియు ఒకదాన్ని కొత్త సమయానికి తరలించండి. `GET /v1/bookings/stats` సముదాయ బుకింగ్ గణనలను తిరిగి ఇస్తుంది.
- **ఈవెంట్ లింక్‌లు** — ఒక ఈవెంట్ రకానికి కట్టుబడి ఉన్న ఒకే-వినియోగ బుకింగ్ లింక్‌లను సృష్టించండి, జాబితా చేయండి, మరియు రద్దు చేయండి (`POST`/`GET /v1/event-types/:code/links`, `DELETE /v1/event-links/:linkCode`).
- **వెబ్‌హుక్‌లు** — మీ వెబ్‌హుక్ సబ్‌స్క్రిప్షన్‌లను ప్రోగ్రామాటిక్‌గా నిర్వహించండి.
- **Users / me** — `GET /v1/users/me` API కీ యొక్క గుర్తింపును తిరిగి ఇస్తుంది (ప్రామాణీకరించబడిన ఖాతా మరియు org).
- **క్యాలెండర్‌లు** — మీ కనెక్ట్ చేయబడిన క్యాలెండర్‌లతో పని చేయండి ([ఇంటిగ్రేషన్‌లు](./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>")` (టైమ్‌స్టాంప్ మరియు బాడీ ఒక అక్షర చుక్క ద్వారా కలపబడ్డాయి)ను లెక్కించండి, దానిని హెక్స్-ఎన్‌కోడ్ చేయండి, మరియు దానిని `v1`తో పోల్చండి. అవి సరిపోలకపోతే అభ్యర్థనను తిరస్కరించండి.

:::tip[ఎల్లప్పుడూ సంతకాన్ని ధృవీకరించండి]

దాని HMAC సంతకం సరిపోలని ఏ వెబ్‌హుక్‌నైనా తిరస్కరించండి. ఇది ఒక నమ్మదగిన ఆటోమేషన్ మరియు ఒక తెరిచిన తలుపు మధ్య తేడా.

:::

## MCP సర్వర్

imatic Calendar ఒక **Model Context Protocol (MCP) సర్వర్**ను అందిస్తుంది, కాబట్టి AI ఏజెంట్‌లు మరియు అసిస్టెంట్‌లు బాగా నిర్వచించబడిన సాధనాల ద్వారా మీ అందుబాటును చదవగలవు మరియు బుకింగ్‌లను నిర్వహించగలవు — REST API లాంటి అదే API-కీ ప్రామాణీకరణ మరియు స్కోప్‌లను ఉపయోగించి.

సర్వర్ **ఏడు సాధనాలు**ను బహిర్గతం చేస్తుంది:

| Tool | ఇది ఏమి చేస్తుంది |
| --- | --- |
| `list_event_types` | మీ బుక్ చేయదగిన ఈవెంట్ రకాలను జాబితా చేస్తుంది |
| `list_slots` | ఒక ఈవెంట్ రకం కోసం ఖాళీ స్లాట్‌లను పొందుతుంది |
| `create_booking` | ఒక స్లాట్‌ను బుక్ చేస్తుంది |
| `cancel_booking` | ఒక బుకింగ్‌ను రద్దు చేస్తుంది |
| `reschedule_booking` | ఒక బుకింగ్‌ను కొత్త సమయానికి తరలిస్తుంది |
| `list_bookings` | ఇప్పటికే ఉన్న బుకింగ్‌లను జాబితా చేస్తుంది |
| `get_booking` | ఒక బుకింగ్‌ను దాని కోడ్ ద్వారా చదువుతుంది |

మీ MCP-సామర్థ్యం ఉన్న క్లయింట్‌ను సర్వర్ వద్దకు చూపండి, ఒక API కీతో ప్రామాణీకరించండి, మరియు మీ ఏజెంట్ "ప్రియ గురువారం ఎప్పుడు ఖాళీగా ఉంటుంది?"కు సమాధానం ఇవ్వగలదు మరియు స్లాట్‌ను బుక్ చేయగలదు — మీరు ఆ కీకి మంజూరు చేసిన స్కోప్‌లలోనే అంతా.

ఖాతా యొక్క స్వంత ప్రొఫైల్ ఒక MCP సాధనం ద్వారా కాకుండా `GET /v1/users/me`తో REST ద్వారా చదవబడుతుంది.

:::note[మీ ఏజెంట్ కీని గట్టిగా స్కోప్ చేయండి]

ఒక AI ఏజెంట్‌కు దానికి అవసరమైన సాధనాలతో మాత్రమే ఒక కీని ఇవ్వండి. దానికి అందుబాటును చదవడానికి మాత్రమే అవసరమైతే, దానికి రద్దు లేదా రీషెడ్యూల్ అనుమతులను మంజూరు చేయవద్దు.

:::

## తదుపరి దశలు

- [ఇంటిగ్రేషన్‌లు](./integrations) — రెండు-మార్గ సింక్ కోసం Google మరియు Outlookను కనెక్ట్ చేయండి.
- [ఈవెంట్ రకాలు](./event-types) — మీ API కాల్‌లలో చాలావరకు చుట్టూ తిరిగే వనరు.
- [మీ పబ్లిక్ బుకింగ్ పేజీ](./booking-page) — మీ ఆటోమేషన్‌లు ప్రతిబింబించే నో-కోడ్ మార్గం.