# REST API


# REST API

imatic उत्पादने REST API सोबत येतात जी तुम्ही तुमच्या स्वतःच्या कोडमधून स्वयंचलित करू शकता. या पृष्ठावरील परंपरा — प्रमाणीकरण, API की, वेबहुक स्वाक्षरी, पृष्ठांकन, दर मर्यादा, आणि त्रुटी — उत्पादनांमध्ये समान आहेत. जे वेगळे असते ते म्हणजे URL चा आकार आणि प्रत्येक उत्पादन उघड करणारी **संसाधने**: Calendar आवृत्तीकृत `/v1` पथ वापरते, तर Survey क्रियापद-शैलीचे `POST` एंडपॉईंट वापरते. प्रत्येक उत्पादनाचे डेव्हलपर पृष्ठ त्याची नेमकी पृष्ठभाग दस्तऐवजित करते.

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

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

:::

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

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

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

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

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

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

```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 की पासवर्डसारख्या वागवा]

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

:::

## वेबहुक

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

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

```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` ने प्रतिसाद देते. एंडपॉईंटवर सतत आदळण्याऐवजी मागे हटा आणि पुन्हा प्रयत्न करा — आदर्शपणे घातीय बॅकऑफ आणि jitter सह.

```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**, बुकिंग (तयार करा, पुनर्नियोजित करा, रद्द करा), कॅलेंडर, वेबहुक, API की, आणि इव्हेंट लिंक. वेबहुक इव्हेंट `booking.created`, `booking.cancelled`, `booking.rescheduled`, आणि `booking.no_show` आहेत. [डेव्हलपर्ससाठी Calendar](/calendar/developers) पहा.
- **Survey** — फॉर्म, प्रतिसाद, प्रतिसाद एकत्रीकरण, AI फॉर्म निर्मिती, आणि वेबहुक (`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 आणि वेबहुक.
- [डेव्हलपर्ससाठी Survey](/survey/developers) — Survey चे API, वेबहुक, आणि MCP साधने.