Skip to main content

REST API

प्रत्येक imatic उत्पादन एक आवृत्तीकृत REST API सोबत येते जेणेकरून तुम्ही ते तुमच्या स्वतःच्या कोडमधून स्वयंचलित करू शकता. या पृष्ठावरील परंपरा — तुम्ही कसे प्रमाणित करता, API की कशा काम करतात, वेबहुक कसे स्वाक्षरीकृत होतात, आणि पृष्ठांकन, दर मर्यादा आणि त्रुटी कशा वागतात — उत्पादनांमध्ये समान आहेत. जे वेगळे असते ते प्रत्येक उत्पादन उघड करते ती संसाधने, जी त्याच्या डेव्हलपर पृष्ठावर दस्तऐवजित आहेत.

उदाहरणे स्पष्टीकरणात्मक आहेत

खालील विनंती आणि प्रतिसाद स्निपेट कॉलचा आकार दाखवतात — हेडर, auth, त्रुटी एन्व्हलप — एक अचूक फील्ड-बाय-फील्ड स्कीमा नव्हे. एका उत्पादनाच्या नेमक्या एंडपॉईंट, पॅरामीटर आणि फील्ड नावांसाठी, त्या उत्पादनाच्या डेव्हलपर पृष्ठाच्या लिंकचे अनुसरण करा.

प्रमाणीकरण​

imatic दोन वेगवेगळ्या कॉलरसाठी दोन प्रकारची क्रेडेन्शियल वापरते:

  • JWT (सत्र टोकन) — तुम्ही ईमेल आणि पासवर्डने साइन इन केल्यानंतर वेब ॲप जे वापरते. ते ब्राउझरमध्ये तुमचे प्रतिनिधित्व करते आणि अल्पायुषी आहे. तुम्ही हे थेट व्यवस्थापित करत नाही; ॲप करते.
  • स्कोप्ड API की — तुमचा कोड v1 REST API ला कॉल करण्यासाठी जे वापरतो. तुम्ही ती स्वतः तयार करता, ती स्पष्ट स्कोप घेऊन जाते, आणि ती ब्राउझर सत्रासह कालबाह्य होत नाही.

सर्व्हर-ते-सर्व्हर कॉलसाठी, नेहमी एक API की वापरा — कधीही तुमचा पासवर्ड किंवा कॉपी केलेले सत्र टोकन नाही.

एक API की पाठवणे​

की Authorization हेडरमध्ये Bearer token म्हणून पाठवा:

curl https://<product-host>/v1/event-types \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial" \
  -H "Content-Type: application/json"

API की कशा काम करतात​

तुम्ही प्रत्येक उत्पादनाच्या डेव्हलपर क्षेत्रात API की तयार आणि व्यवस्थापित करता — उदाहरणार्थ Calendar चे Developers → API keys आणि Survey चे Developers → API keys. एका कीचे समजून घेण्यासारखे तीन गुणधर्म आहेत:

  • prefix.secret स्वरूप — एका कीला एक सार्वजनिक prefix आणि एक सिक्रेट भाग असतो, एका डॉटने जोडलेले (उदाहरणार्थ cal_abc123.s3cr3t_keymaterial — Calendar की एक लहान cal_ prefix वापरतात). prefix imatic ला सूची आणि लॉगमध्ये की ओळखू देतो; सिक्रेट हेच सिद्ध करते की ती तुमची आहे.
  • एकदाच दाखवली जाते — पूर्ण की मूल्य फक्त तुम्ही ती तयार करता त्या क्षणी दाखवले जाते. त्यानंतर, फक्त prefix दिसतो.
  • स्कोप — प्रत्येक की तुम्ही तिला दिलेल्या क्रियांपुरती मर्यादित असते. Calendar चे स्कोप slots:read, bookings:read, bookings:write, आणि mcp आहेत (mcp स्कोप हेच AI एजंटच्या कीला आवश्यक असते — AI एजंटसाठी MCP पहा). कीच्या स्कोपपलीकडे जाणारी विनंती नाकारली जाते.
API की पासवर्डसारख्या वागवा

कीचे सिक्रेट फक्त एकदाच, निर्मितीच्या वेळी दाखवले जाते. तेव्हा ते कॉपी करा आणि सिक्रेट मॅनेजर किंवा एन्व्हायर्नमेंट व्हेरिएबलमध्ये साठवा — कधीही सोर्स कंट्रोल, स्क्रीनशॉट, किंवा सामायिक दस्तऐवजात नाही. जर एक की उघड झाली, तर डेव्हलपर क्षेत्रात ती रद्द करा आणि एक बदली तयार करा. रद्दीकरण तत्काळ अंमलात येते.

वेबहुक​

बदलांसाठी पोलिंग करण्याऐवजी, एक वेबहुक URL नोंदवा आणि काही घडल्यावर imatic त्याला एक इव्हेंट POST करेल — उदाहरणार्थ Calendar मध्ये एक बुकिंग तयार झाली किंवा Survey मध्ये एक प्रतिसाद सबमिट झाला. तुम्ही प्रत्येक उत्पादनाच्या Developers → Webhooks क्षेत्रात वेबहुक एंडपॉईंट व्यवस्थापित करता, जिथे तुम्ही एक चाचणी डिलिव्हरीही पाठवू शकता.

एक डिलिव्हरी साधारणपणे अशी दिसते:

POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json
X-Imatic-Signature: t=1718900000,v1=9f86d081884c7d659a2feaa0c55ad015...

{
  "event": "booking.created",
  "data": { "...": "event-specific payload" }
}

स्वाक्षरी पडताळणे​

प्रत्येक डिलिव्हरी तुमच्या एंडपॉईंटच्या साइनिंग सिक्रेटचा वापर करून HMAC-SHA256 ने स्वाक्षरीकृत असते, Stripe-शैलीच्या X-Imatic-Signature हेडरमध्ये. हेडर दोन फील्ड घेऊन जातो: t, पाठवण्याच्या वेळी unix-epoch सेकंद, आणि v1, ${t}.${body} या स्ट्रिंगचा hex HMAC (टाइमस्टॅम्प, एक शाब्दिक डॉट, मग नेमका कच्चा विनंती मुख्यभाग). पडताळण्यासाठी, हेडर विभाजित करा, तुमच्या साइनिंग सिक्रेटने t + "." + rawBody वर v1 पुन्हा गणित करा, आणि स्थिर-वेळेत तुलना करा. जुळत नसल्यास नाकारा — आणि रीप्लेपासून संरक्षण करण्यासाठी t काही मिनिटांपेक्षा जुना असल्यास पर्यायाने नाकारा.

import crypto from "node:crypto";

function isValid(rawBody, signatureHeader, signingSecret) {
  // Header shape: "t=<epoch-seconds>,v1=<hex hmac>"
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("=")),
  );
  const { t, v1 } = parts;
  if (!t || !v1) return false;

  // Sign the timestamped body: `${t}.${rawBody}` — NOT the raw body alone.
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  // Constant-time comparison to avoid timing attacks.
  const a = Buffer.from(v1);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
प्रति उत्पादन नेमकी योजना

वरील t=…,v1=… योजना Calendar ची आहे. एक पडताळणीकर्ता शिप करण्याआधी प्रत्येक उत्पादनाच्या डेव्हलपर पृष्ठावर हेडर नाव, फील्ड, आणि स्वाक्षरीकृत स्ट्रिंगची पुष्टी करा.

जलद प्रतिसाद द्या, नंतर प्रक्रिया करा

पावती देण्यासाठी जलद एक 2xx परत करा, मग कोणतेही संथ काम असिंक्रोनसपणे करा. जर तुमचा एंडपॉईंट संथ असेल किंवा त्रुटी देत असेल, तर डिलिव्हरी पुन्हा प्रयत्न केल्या जाऊ शकतात.

पृष्ठांकन​

सूची एंडपॉईंट निकाल पृष्ठांत परत करतात जेणेकरून एका कॉलला कधीही सर्व काही लोड करावे लागत नाही. विनंतीवर पेजिंग पॅरामीटर पाठवा आणि पुढील पृष्ठ आणण्यासाठी प्रतिसादावरील पेजिंग मेटाडेटा वाचा.

curl "https://<product-host>/v1/bookings?limit=25" \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial"
{
  "success": true,
  "data": [ { "...": "one item per result" } ],
  "pagination": { "page": 1, "limit": 20, "total": 0, "pages": 0 }
}

आणखी निकाल नसेपर्यंत पुढील पृष्ठाची विनंती करत राहा.

दर मर्यादा​

प्लॅटफॉर्म न्याय्य आणि स्थिर ठेवण्यासाठी API की दर-मर्यादित असतात. जर तुम्ही मर्यादा ओलांडली, तर API HTTP 429 Too Many Requests ने प्रतिसाद देते. एंडपॉईंटवर सतत आदळण्याऐवजी मागे हटा आणि पुन्हा प्रयत्न करा — आदर्शपणे घातीय बॅकऑफ आणि jitter सह.

{
  "success": false,
  "error": "rate_limited",
  "message": "Too many requests. Please retry after a short delay."
}

त्रुटी हाताळणी​

त्रुटी मानक HTTP स्थिती कोड वापरतात आणि एका JSON मुख्यभागासह जो काय चुकले ते वर्णन करतो. तुम्हाला सर्वाधिक वेळा दिसणारे कोड:

  • 400 — विनंती चुकीची होती किंवा पडताळणी अयशस्वी झाली.
  • 401 — गहाळ किंवा अवैध API की.
  • 403 — की वैध आहे परंतु या क्रियेसाठी स्कोप (किंवा org प्रवेश) नाही.
  • 404 — संसाधन अस्तित्वात नाही किंवा या कीला दृश्यमान नाही.
  • 409 — एक संघर्ष, जसे की नुकताच घेतला गेलेला स्लॉट बुक करण्याचा प्रयत्न.
  • 429 — दर-मर्यादित; मागे हटा आणि पुन्हा प्रयत्न करा.
  • 5xx — एक सर्व्हर-बाजूची त्रुटी; तात्पुरत्या अपयशांचा पुन्हा प्रयत्न करा.

एक विशिष्ट त्रुटी एन्व्हलप:

{
  "success": false,
  "error": "validation_failed",
  "message": "A human-readable explanation of the problem."
}

उत्पादनानुसार संसाधने​

वरील परंपरा सामायिक आहेत, परंतु प्रत्येक उत्पादन स्वतःचे एंडपॉईंट उघड करते. नेमक्या संसाधने, पॅरामीटर आणि फील्ड नावांसाठी उत्पादनाच्या डेव्हलपर पृष्ठापासून सुरुवात करा:

  • Calendar — इव्हेंट प्रकार, उपलब्धता slots, बुकिंग (तयार करा, पुनर्नियोजित करा, रद्द करा), कॅलेंडर, वेबहुक, API की, आणि इव्हेंट लिंक. वेबहुक इव्हेंट booking.created, booking.cancelled, booking.rescheduled, आणि booking.no_show आहेत. डेव्हलपर्ससाठी Calendar पहा.
  • Survey — फॉर्म, प्रतिसाद, प्रतिसाद एकत्रीकरण, AI फॉर्म निर्मिती, आणि वेबहुक (form.published, response.submitted). डेव्हलपर्ससाठी Survey पहा.
  • Voice Portal — एजंट, मोहिमा, आणि संपर्क, अधिक साधने आणि MCP सर्व्हर नोंदणी. एजंटसाठी साधने आणि MCP पहा.

संबंधित​