క్యాలెండర్ API & MCP
imatic Calendarలో మీరు చేసే ప్రతిదాన్ని మీరు ఆటోమేట్ చేయవచ్చు. స్లాట్లను ప్రశ్నించడానికి మరియు బుకింగ్లను సృష్టించడానికి REST APIను, రియల్ టైమ్లో ఈవెంట్లకు ప్రతిస్పందించడానికి వెబ్హుక్లును, మరియు మీ తరఫున AI ఏజెంట్ బుక్ చేయడానికి MCP సర్వర్ను ఉపయోగించండి. ఈ పేజీ imatic Calendarను తమ స్వంత యాప్లు మరియు సాధనాలలోకి వైర్ చేసే డెవలపర్ల కోసం.
మీరు మీ డ్యాష్బోర్డ్లో Developers క్రింద ఆధారాలను నిర్వహిస్తారు.
API keys మరియు Webhooks పేజీలు ఒక account admin (org admin లేదా super admin) ద్వారా నిర్వహించబడతాయి. మీరు వాటిని మీ డ్యాష్బోర్డ్లో చూడకపోతే, మీ కోసం ఒక కీని జారీ చేయడానికి లేదా ఒక వెబ్హుక్ను సెటప్ చేయడానికి మీ ఖాతాపై ఒక అడ్మిన్ను అడగండి.
ప్రామాణీకరణ & API కీలు
API కు చేసే కాల్లు బేరర్ టోకెన్గా పంపబడిన ఒక API keyతో ప్రామాణీకరించబడతాయి:
Authorization: Bearer <your_api_key>
Developers → API keys క్రింద కీలను నిర్వహించండి, అక్కడ మీరు:
- ఒక కీని సృష్టించండి — చూపించినప్పుడు రహస్యాన్ని కాపీ చేయండి; అది మళ్లీ ప్రదర్శించబడదు.
- మీ కీలను జాబితా చేయండి మరియు ప్రతి ఒక్కటి దేని కోసమో చూడండి.
- అది లీక్ అయితే లేదా ఇకపై అవసరం లేకపోతే ఒక కీని తక్షణమే రద్దు చేయండి.
- స్కోప్లును కేటాయించండి — ప్రతి కీ మీరు మంజూరు చేసిన అనుమతులను మాత్రమే కలిగి ఉంటుంది, కాబట్టి ఒక చదవడానికి-మాత్రమే కీ బుకింగ్లను జాబితా చేయగలదు కానీ వాటిని ఎప్పటికీ సృష్టించలేదు లేదా రద్దు చేయలేదు.
అందుబాటులో ఉన్న స్కోప్లు:
| Scope | మంజూరు చేస్తుంది |
|---|---|
slots:read | ఒక ఈవెంట్ రకం కోసం అందుబాటులో ఉన్న సమయ స్లాట్లను చదవండి |
bookings:read | బుకింగ్లను జాబితా చేయండి మరియు చదవండి |
bookings:write | బుకింగ్లను సృష్టించండి, రద్దు చేయండి, మరియు రీషెడ్యూల్ చేయండి |
mcp | MCP సర్వర్ను ఉపయోగించండి (slots:read, bookings:read, మరియు bookings:writeలను కూడా కవర్ చేసే ఒక గొడుగు) |
ఒక కీ దాని స్కోప్లలో మీ ఖాతాకు యాక్సెస్ను మంజూరు చేస్తుంది. దానిని ఒక సీక్రెట్ మేనేజర్ లేదా ఎన్విరాన్మెంట్ వేరియబుల్లో నిల్వ చేయండి, ఎప్పుడూ క్లయింట్-సైడ్ కోడ్లో లేదా పబ్లిక్ రెపోలో కాదు. అది బయటపడితే వెంటనే రద్దు చేయండి మరియు తిప్పండి.
REST API v1
REST API /v1 బేస్ పాత్ క్రింద అందించబడుతుంది మరియు JSONను తిరిగి ఇస్తుంది. అందుబాటులో ఉన్న వనరులు:
- ఈవెంట్ రకాలు — మీ ఈవెంట్ రకాలును జాబితా చేయండి మరియు చదవండి, అలాగే ఒక ఈవెంట్ రకాన్ని నకలు చేయండి (
POST /v1/event-types/:code/duplicate). (సృష్టించడం/సవరించడం/తొలగించడం డ్యాష్బోర్డ్లో జరుగుతుంది.) - స్లాట్లు — ఒక ఈవెంట్ రకం కోసం అందుబాటులో ఉన్న సమయ స్లాట్లను ప్రశ్నించండి (మీ బుకింగ్ పేజీలో చూపించిన అదే ఖాళీలు, అన్ని బఫర్లు, నోటీసు, మరియు పరిమితులు వర్తింపజేయబడ్డాయి).
- బుకింగ్లు — పూర్తి CRUD ప్లస్ రీషెడ్యూల్: ఒక బుకింగ్ను సృష్టించండి, బుకింగ్లను జాబితా చేయండి మరియు చదవండి, రద్దు చేయండి, మరియు ఒకదాన్ని కొత్త సమయానికి తరలించండి.
GET /v1/bookings/statsసముదాయ బుకింగ్ గణనలను తిరిగి ఇస్తుంది. - ఈవెంట్ లింక్లు — ఒక ఈవెంట్ రకానికి కట్టుబడి ఉన్న ఒకే-వినియోగ బుకింగ్ లింక్లను సృష్టించండి, జాబితా చేయండి, మరియు రద్దు చేయండి (
POST/GET /v1/event-types/:code/links,DELETE /v1/event-links/:linkCode). - వెబ్హుక్లు — మీ వెబ్హుక్ సబ్స్క్రిప్షన్లను ప్రోగ్రామాటిక్గా నిర్వహించండి.
- Users / me —
GET /v1/users/meAPI కీ యొక్క గుర్తింపును తిరిగి ఇస్తుంది (ప్రామాణీకరించబడిన ఖాతా మరియు org). - క్యాలెండర్లు — మీ కనెక్ట్ చేయబడిన క్యాలెండర్లతో పని చేయండి (ఇంటిగ్రేషన్లు చూడండి).
ఒక సాధారణ ఆటోమేషన్ ప్రవాహం: ఒక ఈవెంట్ రకం కోసం slotsను ప్రశ్నించండి, ఆపై మీ వినియోగదారు ఎంచుకున్న స్లాట్ కోసం ఒక bookingను సృష్టించండి — బుకింగ్ పేజీ ఉపయోగించే అదే అటామిక్, నో-డబుల్-బుక్ హామీ APIకి కూడా వర్తిస్తుంది.
వెబ్హుక్లు
వెబ్హుక్లు ఈవెంట్లు జరిగిన క్షణంలోనే వాటిని మీ సర్వర్కు పుష్ చేస్తాయి, కాబట్టి మీరు పోల్ చేయవలసిన అవసరం లేదు. వాటిని Developers → Webhooks క్రింద నిర్వహించండి.
- బుకింగ్ ఈవెంట్లను స్వీకరించడానికి ఒక URLను సబ్స్క్రైబ్ చేయండి. ఈవెంట్లు ఖచ్చితంగా:
booking.created,booking.cancelled,booking.rescheduled, మరియుbooking.no_show. - ప్రతి డెలివరీ HMACతో సంతకం చేయబడుతుంది — మీరు పేలోడ్ను విశ్వసించడానికి ముందు అభ్యర్థన నిజంగా imatic Calendar నుండి వచ్చిందని నిర్ధారించడానికి మీ వెబ్హుక్ యొక్క రహస్యానికి వ్యతిరేకంగా సంతకం హెడర్ను ధృవీకరించండి.
- మీరు బిల్డ్ చేస్తున్నప్పుడు మీ ఎండ్పాయింట్కు ఒక నమూనా ఈవెంట్ను పంపడానికి అంతర్నిర్మిత Test చర్యను ఉపయోగించండి, తద్వారా లైవ్గా వెళ్లే ముందు మీ హ్యాండ్లర్ పని చేస్తుందని మీరు నిర్ధారించవచ్చు.
సంతకం X-Imatic-Signature హెడర్లో, ఒక Stripe-శైలి ఫార్మాట్లో ప్రయాణిస్తుంది:
X-Imatic-Signature: t=<unix-epoch-seconds>,v1=<hmac-sha256>
ధృవీకరించడానికి: t మరియు ముడి అభ్యర్థన బాడీని తీసుకోండి, HMAC-SHA256(secret, "<t>.<body>") (టైమ్స్టాంప్ మరియు బాడీ ఒక అక్షర చుక్క ద్వారా కలపబడ్డాయి)ను లెక్కించండి, దానిని హెక్స్-ఎన్కోడ్ చేయండి, మరియు దానిని v1తో పోల్చండి. అవి సరిపోలకపోతే అభ్యర్థనను తిరస్కరించండి.
దాని 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 ద్వారా చదవబడుతుంది.
ఒక AI ఏజెంట్కు దానికి అవసరమైన సాధనాలతో మాత్రమే ఒక కీని ఇవ్వండి. దానికి అందుబాటును చదవడానికి మాత్రమే అవసరమైతే, దానికి రద్దు లేదా రీషెడ్యూల్ అనుమతులను మంజూరు చేయవద్దు.
తదుపరి దశలు
- ఇంటిగ్రేషన్లు — రెండు-మార్గ సింక్ కోసం Google మరియు Outlookను కనెక్ట్ చేయండి.
- ఈవెంట్ రకాలు — మీ API కాల్లలో చాలావరకు చుట్టూ తిరిగే వనరు.
- మీ పబ్లిక్ బుకింగ్ పేజీ — మీ ఆటోమేషన్లు ప్రతిబింబించే నో-కోడ్ మార్గం.