# REST API


# REST API

imatic পণ্যগুলি REST API সরবরাহ করে যা আপনি আপনার নিজের কোড থেকে স্বয়ংক্রিয় করতে পারেন। এই পেজের কনভেনশনগুলি — আপনি কীভাবে অথেনটিকেট করেন, API কী কীভাবে কাজ করে, webhook কীভাবে স্বাক্ষরিত হয়, এবং পেজিনেশন, রেট লিমিট, ও এরর কীভাবে আচরণ করে — পণ্যগুলির মধ্যে একই। যা ভিন্ন তা হলো URL-এর আকার এবং প্রতিটি পণ্য যে **রিসোর্স** প্রকাশ করে: Calendar ভার্সনযুক্ত `/v1` পাথ ব্যবহার করে, যেখানে Survey ক্রিয়াপদ-শৈলীর `POST` এন্ডপয়েন্ট ব্যবহার করে। প্রতিটি পণ্যের ডেভেলপার পেজ এর সঠিক সারফেস নথিভুক্ত করে।

:::note[উদাহরণগুলি দৃষ্টান্তমূলক]

নিচের অনুরোধ ও প্রতিক্রিয়া স্নিপেটগুলি কলের *আকার* দেখায় — হেডার, অথ, এরর এনভেলপ — একটি সঠিক ফিল্ড-বাই-ফিল্ড স্কিমা নয়। একটি পণ্যের সুনির্দিষ্ট এন্ডপয়েন্ট, প্যারামিটার, এবং ফিল্ড নামের জন্য, সেই পণ্যের ডেভেলপার পেজের লিঙ্ক অনুসরণ করুন।

:::

## অথেনটিকেশন

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` ফরম্যাট** — একটি কী-এর একটি পাবলিক **প্রিফিক্স** এবং একটি সিক্রেট অংশ থাকে, একটি ডট দিয়ে যুক্ত (উদাহরণস্বরূপ `cal_abc123.s3cr3t_keymaterial` — Calendar কী একটি ছোট `cal_` প্রিফিক্স ব্যবহার করে)। প্রিফিক্সটি imatic-কে তালিকা ও লগে কী শনাক্ত করতে দেয়; সিক্রেটটি প্রমাণ করে এটি আপনার।
- **একবার দেখানো হয়** — সম্পূর্ণ কী মান কেবলমাত্র আপনি এটি তৈরি করার মুহূর্তে প্রদর্শিত হয়। এরপর, শুধুমাত্র প্রিফিক্স দৃশ্যমান।
- **স্কোপ** — প্রতিটি কী আপনি যে অ্যাকশনগুলি প্রদান করেন তার মধ্যে সীমাবদ্ধ। 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**, বুকিং (তৈরি, রিশিডিউল, বাতিল), ক্যালেন্ডার, webhook, API কী, এবং ইভেন্ট লিঙ্ক। Webhook ইভেন্টগুলি হলো `booking.created`, `booking.cancelled`, `booking.rescheduled`, এবং `booking.no_show`। দেখুন [ডেভেলপারদের জন্য Calendar](/calendar/developers)।
- **Survey** — ফর্ম, প্রতিক্রিয়া, প্রতিক্রিয়া সমষ্টিকরণ, AI ফর্ম জেনারেশন, এবং webhook (`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 এবং webhook।
- [ডেভেলপারদের জন্য Survey](/survey/developers) — Survey-এর API, webhook, এবং MCP টুল।