# REST API


# REST API

imatic उत्पाद REST API के साथ आते हैं जिन्हें आप अपने स्वयं के कोड से स्वचालित कर सकते हैं। इस पेज की परंपराएँ — प्रमाणीकरण, API कुंजियाँ, webhook हस्ताक्षर, पेजिनेशन, दर सीमाएँ, और त्रुटियाँ — सभी उत्पादों में एक समान हैं। जो अलग है वह है URL का स्वरूप और प्रत्येक उत्पाद द्वारा उजागर किए गए संसाधन: Calendar संस्करणयुक्त `/v1` पथ उपयोग करता है, जबकि Survey क्रिया-शैली `POST` एंडपॉइंट उपयोग करता है। प्रत्येक उत्पाद का डेवलपर पेज उसकी सटीक सतह का प्रलेखन करता है।

:::note[उदाहरण दृष्टांत मात्र हैं]

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

:::

## प्रमाणीकरण

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

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

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

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

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

```bash
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](./mcp))। एक अनुरोध जो किसी कुंजी के स्कोप से अधिक हो, अस्वीकार कर दिया जाता है।

:::danger[API कुंजियों को पासवर्ड की तरह समझें]

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

:::

## Webhooks

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

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

```http
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` कुछ मिनटों से पुराना हो।

```js
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);
}
```

:::note[प्रति उत्पाद सटीक योजना]

ऊपर दी गई `t=…,v1=…` योजना Calendar की है। कोई वेरिफ़ायर शिप करने से पहले प्रत्येक उत्पाद के डेवलपर पेज पर हेडर नाम, फ़ील्ड, और हस्ताक्षरित स्ट्रिंग की पुष्टि करें।

:::

:::tip[तेज़ी से जवाब दें, बाद में प्रोसेस करें]

प्राप्ति की पुष्टि के लिए जल्दी एक `2xx` लौटाएँ, फिर कोई भी धीमा काम एसिंक्रोनस रूप से करें। यदि आपका एंडपॉइंट धीमा है या त्रुटि देता है, तो डिलीवरी का पुनः प्रयास किया जा सकता है।

:::

## पेजिनेशन

सूची एंडपॉइंट परिणामों को पन्नों में लौटाते हैं ताकि किसी एक कॉल को कभी सब कुछ लोड न करना पड़े। अनुरोध पर पेजिंग पैरामीटर पास करें और अगला पन्ना लाने के लिए प्रतिक्रिया पर पेजिंग मेटाडेटा पढ़ें।

```bash
curl "https://<product-host>/v1/bookings?limit=25" \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial"
```

```json
{
  "success": true,
  "data": [ { "...": "one item per result" } ],
  "pagination": { "page": 1, "limit": 20, "total": 0, "pages": 0 }
}
```

जब तक और परिणाम न रहें तब तक अगला पन्ना माँगते रहें।

## दर सीमित करना

प्लेटफ़ॉर्म को निष्पक्ष और स्थिर रखने के लिए API कुंजियाँ दर-सीमित हैं। यदि आप सीमा से अधिक जाते हैं, तो API HTTP `429 Too Many Requests` के साथ जवाब देता है। एंडपॉइंट पर लगातार प्रहार करने के बजाय बैक ऑफ करें और पुनः प्रयास करें — आदर्श रूप से घातीय बैकऑफ़ और जिटर के साथ।

```json
{
  "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`** — एक सर्वर-साइड त्रुटि; क्षणिक विफलताओं का पुनः प्रयास करें।

एक सामान्य त्रुटि एनवलप:

```json
{
  "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](/calendar/developers)।
- **Survey** — फ़ॉर्म, प्रतिक्रियाएँ, प्रतिक्रिया एकत्रीकरण, AI फ़ॉर्म निर्माण, और webhooks (`form.published`, `response.submitted`)। देखें [डेवलपर्स के लिए Survey](/survey/developers)।
- **Voice Portal** — एजेंट, अभियान, और संपर्क, साथ ही टूल और MCP सर्वर पंजीकरण। देखें [एजेंटों के लिए टूल और MCP](/voice/agents/tools-mcp)।

## संबंधित

- [प्लेटफ़ॉर्म अवलोकन](./overview) — खाते, संगठन, और साझा अवधारणाएँ।
- [AI एजेंटों के लिए MCP](./mcp) — AI सहायकों को आपके लिए इन संसाधनों को कॉल करने दें।
- [डेवलपर्स के लिए Calendar](/calendar/developers) — Calendar का REST API और webhooks।
- [डेवलपर्स के लिए Survey](/survey/developers) — Survey का API, webhooks, और MCP टूल।