मुख्य कंटेंट तक स्किप करें

REST API

प्रत्येक imatic उत्पाद एक संस्करणयुक्त REST API के साथ आता है ताकि आप इसे अपने स्वयं के कोड से स्वचालित कर सकें। इस पेज की परंपराएँ — आप कैसे प्रमाणित होते हैं, API कुंजियाँ कैसे काम करती हैं, webhooks कैसे हस्ताक्षरित होते हैं, और पेजिनेशन, दर सीमाएँ, और त्रुटियाँ कैसे व्यवहार करती हैं — सभी उत्पादों में एक समान हैं। जो अलग है वह है प्रत्येक उत्पाद द्वारा उजागर किए गए संसाधन, जो उसके डेवलपर पेज पर प्रलेखित हैं।

उदाहरण दृष्टांत मात्र हैं

नीचे दिए गए अनुरोध और प्रतिक्रिया स्निपेट कॉल का आकार दिखाते हैं — हेडर, auth, त्रुटि एनवलप — न कि एक सटीक फ़ील्ड-दर-फ़ील्ड स्कीमा। किसी उत्पाद के सटीक एंडपॉइंट, पैरामीटर, और फ़ील्ड नामों के लिए, उस उत्पाद के डेवलपर पेज के लिंक का अनुसरण करें।

प्रमाणीकरण​

imatic दो अलग-अलग कॉलर के लिए, दो प्रकार के क्रेडेंशियल उपयोग करता है:

  • JWT (सत्र टोकन) — वह जो वेब ऐप ईमेल और पासवर्ड से साइन इन करने के बाद उपयोग करता है। यह ब्राउज़र में आपका प्रतिनिधित्व करता है और अल्पकालिक है। आप इसे सीधे प्रबंधित नहीं करते; ऐप करता है।
  • स्कोप्ड API कुंजी — वह जो आपका कोड v1 REST API को कॉल करने के लिए उपयोग करता है। आप इसे स्वयं बनाते हैं, यह स्पष्ट स्कोप रखती है, और यह किसी ब्राउज़र सत्र के साथ समाप्त नहीं होती।

सर्वर-से-सर्वर कॉल के लिए, हमेशा एक API कुंजी का उपयोग करें — कभी अपना पासवर्ड या कॉपी किया हुआ सत्र टोकन नहीं।

एक API कुंजी भेजना​

कुंजी को Authorization हेडर में Bearer टोकन के रूप में पास करें:

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 कुंजियों को पासवर्ड की तरह समझें

किसी कुंजी का सीक्रेट केवल एक बार, निर्माण के समय दिखाया जाता है। उसे तभी कॉपी करें और किसी सीक्रेट मैनेजर या एनवायरनमेंट वेरिएबल में रखें — कभी सोर्स कंट्रोल, स्क्रीनशॉट, या साझा दस्तावेज़ में नहीं। यदि कोई कुंजी उजागर हो जाए, तो डेवलपर क्षेत्र में उसे रद्द करें और एक प्रतिस्थापन बनाएँ। रद्दीकरण तुरंत प्रभावी होता है।

Webhooks​

परिवर्तनों के लिए पोल करने के बजाय, एक webhook URL रजिस्टर करें और जब कुछ होता है तो imatic उस पर एक इवेंट POST करेगा — उदाहरण के लिए Calendar में कोई बुकिंग बनती है या Survey में कोई प्रतिक्रिया प्रस्तुत होती है। आप प्रत्येक उत्पाद के Developers → Webhooks क्षेत्र में webhook एंडपॉइंट प्रबंधित करते हैं, जहाँ आप एक परीक्षण डिलीवरी भी भेज सकते हैं।

एक डिलीवरी मोटे तौर पर इस तरह दिखती है:

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 के साथ जवाब देता है। एंडपॉइंट पर लगातार प्रहार करने के बजाय बैक ऑफ करें और पुनः प्रयास करें — आदर्श रूप से घातीय बैकऑफ़ और जिटर के साथ।

{
  "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, बुकिंग (बनाना, पुनर्निर्धारित करना, रद्द करना), कैलेंडर, webhooks, API कुंजियाँ, और इवेंट लिंक। Webhook इवेंट booking.created, booking.cancelled, booking.rescheduled, और booking.no_show हैं। देखें डेवलपर्स के लिए Calendar।
  • Survey — फ़ॉर्म, प्रतिक्रियाएँ, प्रतिक्रिया एकत्रीकरण, AI फ़ॉर्म निर्माण, और webhooks (form.published, response.submitted)। देखें डेवलपर्स के लिए Survey।
  • Voice Portal — एजेंट, अभियान, और संपर्क, साथ ही टूल और MCP सर्वर पंजीकरण। देखें एजेंटों के लिए टूल और MCP।

संबंधित​