স্কিপ করে মূল কন্টেন্ট এ যান

REST API

প্রতিটি imatic পণ্য একটি ভার্সনযুক্ত REST API সরবরাহ করে যাতে আপনি আপনার নিজের কোড থেকে এটি স্বয়ংক্রিয় করতে পারেন। এই পেজের কনভেনশনগুলি — আপনি কীভাবে অথেনটিকেট করেন, API কী কীভাবে কাজ করে, webhook কীভাবে স্বাক্ষরিত হয়, এবং পেজিনেশন, রেট লিমিট, ও এরর কীভাবে আচরণ করে — পণ্যগুলির মধ্যে একই। যা ভিন্ন তা হলো প্রতিটি পণ্য যে রিসোর্স প্রকাশ করে, যা এর ডেভেলপার পেজে নথিভুক্ত।

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

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

অথেনটিকেশন​

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

সম্পর্কিত​