REST API

ಪ್ರತಿ imatic ಉತ್ಪನ್ನವೂ ಆವೃತ್ತಿಯುಳ್ಳ REST API ಅನ್ನು ಒದಗಿಸುತ್ತದೆ, ಇದರಿಂದ ನಿಮ್ಮ ಸ್ವಂತ ಕೋಡ್‌ನಿಂದ ಅದನ್ನು ಸ್ವಯಂಚಾಲಿತಗೊಳಿಸಬಹುದು. ಈ ಪುಟದಲ್ಲಿನ ಸಂಪ್ರದಾಯಗಳು — ನೀವು ಹೇಗೆ ದೃಢೀಕರಿಸುತ್ತೀರಿ, API ಕೀಗಳು ಹೇಗೆ ಕೆಲಸ ಮಾಡುತ್ತವೆ, webhooks ಹೇಗೆ ಸಹಿ ಮಾಡಲ್ಪಡುತ್ತವೆ, ಮತ್ತು ಪುಟೀಕರಣ, ದರ ಮಿತಿಗಳು ಮತ್ತು ದೋಷಗಳು ಹೇಗೆ ವರ್ತಿಸುತ್ತವೆ — ಎಲ್ಲಾ ಉತ್ಪನ್ನಗಳಲ್ಲಿ ಒಂದೇ ರೀತಿಯಾಗಿರುತ್ತವೆ. ಭಿನ್ನವಾಗಿರುವುದು ಪ್ರತಿ ಉತ್ಪನ್ನವು ತೆರೆದಿಡುವ ಸಂಪನ್ಮೂಲಗಳು, ಅವುಗಳನ್ನು ಅದರ ಡೆವಲಪರ್ ಪುಟದಲ್ಲಿ ದಾಖಲಿಸಲಾಗಿದೆ.

ಉದಾಹರಣೆಗಳು ವಿವರಣಾತ್ಮಕವಾಗಿವೆ

ಕೆಳಗಿನ ವಿನಂತಿ ಮತ್ತು ಪ್ರತಿಕ್ರಿಯೆ ತುಣುಕುಗಳು ಕರೆಗಳ ಆಕಾರವನ್ನು ತೋರಿಸುತ್ತವೆ — headers, auth, ದೋಷ envelopes — ನಿಖರವಾದ ಕ್ಷೇತ್ರ-ಬೈ-ಕ್ಷೇತ್ರ schema ಅಲ್ಲ. ಒಂದು ಉತ್ಪನ್ನದ ನಿಖರ endpoints, ನಿಯತಾಂಕಗಳು ಮತ್ತು ಕ್ಷೇತ್ರ ಹೆಸರುಗಳಿಗಾಗಿ, ಆ ಉತ್ಪನ್ನದ ಡೆವಲಪರ್ ಪುಟಕ್ಕೆ ಲಿಂಕ್‌ಗಳನ್ನು ಅನುಸರಿಸಿ.

ದೃಢೀಕರಣ

imatic ಎರಡು ಬಗೆಯ ರುಜುವಾತುಗಳನ್ನು ಬಳಸುತ್ತದೆ, ಎರಡು ವಿಭಿನ್ನ ಕರೆಗಾರರಿಗೆ:

• JWT (session token) — ನೀವು ಇಮೇಲ್ ಮತ್ತು ಪಾಸ್‌ವರ್ಡ್‌ನೊಂದಿಗೆ ಸೈನ್ ಇನ್ ಮಾಡಿದ ನಂತರ ವೆಬ್ ಅಪ್ಲಿಕೇಶನ್ ಬಳಸುವುದು. ಇದು ಬ್ರೌಸರ್‌ನಲ್ಲಿ ನಿಮ್ಮನ್ನು ಪ್ರತಿನಿಧಿಸುತ್ತದೆ ಮತ್ತು ಅಲ್ಪಾಯುಷಿಯಾಗಿದೆ. ನೀವು ಇದನ್ನು ನೇರವಾಗಿ ನಿರ್ವಹಿಸುವುದಿಲ್ಲ; ಅಪ್ಲಿಕೇಶನ್ ನಿರ್ವಹಿಸುತ್ತದೆ.
• ಸ್ಕೋಪ್ ಮಾಡಲಾದ API ಕೀ — ನಿಮ್ಮ ಕೋಡ್ v1 REST API ಅನ್ನು ಕರೆಯಲು ಬಳಸುವುದು. ನೀವೇ ಅದನ್ನು ರಚಿಸುತ್ತೀರಿ, ಅದು ಸ್ಪಷ್ಟ scopes ಗಳನ್ನು ಹೊಂದಿರುತ್ತದೆ, ಮತ್ತು ಬ್ರೌಸರ್ ಸೆಷನ್‌ನೊಂದಿಗೆ ಅವಧಿ ಮುಗಿಯುವುದಿಲ್ಲ.

ಸರ್ವರ್-ಟು-ಸರ್ವರ್ ಕರೆಗಳಿಗಾಗಿ, ಯಾವಾಗಲೂ API ಕೀ ಬಳಸಿ — ಎಂದಿಗೂ ನಿಮ್ಮ ಪಾಸ್‌ವರ್ಡ್ ಅಥವಾ ನಕಲು ಮಾಡಿದ session token ಅಲ್ಲ.

API ಕೀ ಕಳುಹಿಸುವುದು

ಕೀಯನ್ನು Authorization header ನಲ್ಲಿ Bearer token ಆಗಿ ರವಾನಿಸಿ:

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 ಮಾತ್ರ ಗೋಚರಿಸುತ್ತದೆ.
• Scopes — ಪ್ರತಿ ಕೀ ನೀವು ನೀಡುವ ಕ್ರಿಯೆಗಳಿಗೆ ಸೀಮಿತವಾಗಿರುತ್ತದೆ. Calendar ನ scopes ಗಳು slots:read, bookings:read, bookings:write, ಮತ್ತು mcp (AI ಏಜೆಂಟ್‌ನ ಕೀಗೆ mcp scope ಬೇಕು — AI ಏಜೆಂಟ್‌ಗಳಿಗಾಗಿ MCP ನೋಡಿ). ಕೀಯ scope ಅನ್ನು ಮೀರುವ ವಿನಂತಿಯನ್ನು ತಿರಸ್ಕರಿಸಲಾಗುತ್ತದೆ.

API ಕೀಗಳನ್ನು ಪಾಸ್‌ವರ್ಡ್‌ಗಳಂತೆ ಪರಿಗಣಿಸಿ

ಕೀಯ ರಹಸ್ಯವನ್ನು ರಚನೆಯ ಸಮಯದಲ್ಲಿ ಒಮ್ಮೆ ಮಾತ್ರ ತೋರಿಸಲಾಗುತ್ತದೆ. ಆಗ ಅದನ್ನು ನಕಲಿಸಿ ಮತ್ತು ರಹಸ್ಯ ನಿರ್ವಾಹಕ ಅಥವಾ ಪರಿಸರ ಅಸ್ಥಿರದಲ್ಲಿ ಸಂಗ್ರಹಿಸಿ — ಎಂದಿಗೂ source control, ಸ್ಕ್ರೀನ್‌ಶಾಟ್ ಅಥವಾ ಹಂಚಿಕೊಂಡ ದಾಖಲೆಯಲ್ಲಿ ಅಲ್ಲ. ಒಂದು ಕೀ ಬಯಲಾದರೆ, ಡೆವಲಪರ್ ಪ್ರದೇಶದಲ್ಲಿ ಅದನ್ನು ರದ್ದುಗೊಳಿಸಿ ಮತ್ತು ಬದಲಿಯನ್ನು ರಚಿಸಿ. ರದ್ದತಿ ತಕ್ಷಣ ಜಾರಿಗೆ ಬರುತ್ತದೆ.

Webhooks

ಬದಲಾವಣೆಗಳಿಗಾಗಿ ಪೋಲಿಂಗ್ ಮಾಡುವ ಬದಲು, webhook URL ಅನ್ನು ನೋಂದಾಯಿಸಿ ಮತ್ತು ಏನಾದರೂ ಸಂಭವಿಸಿದಾಗ imatic ಅದಕ್ಕೆ ಒಂದು ಘಟನೆಯನ್ನು POST ಮಾಡುತ್ತದೆ — ಉದಾಹರಣೆಗೆ Calendar ನಲ್ಲಿ ಬುಕಿಂಗ್ ರಚಿಸಲಾಗುತ್ತದೆ ಅಥವಾ Survey ನಲ್ಲಿ ಪ್ರತಿಕ್ರಿಯೆ ಸಲ್ಲಿಸಲಾಗುತ್ತದೆ. ನೀವು ಪ್ರತಿ ಉತ್ಪನ್ನದ Developers → Webhooks ಪ್ರದೇಶದಲ್ಲಿ webhook endpoints ಅನ್ನು ನಿರ್ವಹಿಸುತ್ತೀರಿ, ಅಲ್ಲಿ ನೀವು ಪರೀಕ್ಷಾ ವಿತರಣೆಯನ್ನೂ ಕಳುಹಿಸಬಹುದು.

ಒಂದು ವಿತರಣೆಯು ಸುಮಾರು ಹೀಗೆ ಕಾಣುತ್ತದೆ:

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" }
}

ಸಹಿ ಪರಿಶೀಲಿಸುವುದು

ಪ್ರತಿ ವಿತರಣೆಯನ್ನು ನಿಮ್ಮ endpoint ನ ಸಹಿ ರಹಸ್ಯವನ್ನು ಬಳಸಿ HMAC-SHA256 ನೊಂದಿಗೆ ಸಹಿ ಮಾಡಲಾಗುತ್ತದೆ, Stripe-ಶೈಲಿಯ X-Imatic-Signature header ನಲ್ಲಿ. header ಎರಡು ಕ್ಷೇತ್ರಗಳನ್ನು ಹೊಂದಿರುತ್ತದೆ: t, ಕಳುಹಿಸುವ ಸಮಯದಲ್ಲಿ unix-epoch ಸೆಕೆಂಡುಗಳು, ಮತ್ತು v1, ${t}.${body} ಸ್ಟ್ರಿಂಗ್‌ನ hex HMAC (timestamp, ಒಂದು ಅಕ್ಷರಶಃ ಚುಕ್ಕೆ, ನಂತರ ನಿಖರ raw ವಿನಂತಿ body). ಪರಿಶೀಲಿಸಲು, header ಅನ್ನು ವಿಭಜಿಸಿ, ನಿಮ್ಮ ಸಹಿ ರಹಸ್ಯದೊಂದಿಗೆ 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 ನದ್ದು. verifier ಅನ್ನು ಬಿಡುಗಡೆ ಮಾಡುವ ಮೊದಲು ಪ್ರತಿ ಉತ್ಪನ್ನದ ಡೆವಲಪರ್ ಪುಟದಲ್ಲಿ header ಹೆಸರು, ಕ್ಷೇತ್ರಗಳು ಮತ್ತು ಸಹಿ ಮಾಡಲಾದ ಸ್ಟ್ರಿಂಗ್ ಅನ್ನು ದೃಢೀಕರಿಸಿ.

ವೇಗವಾಗಿ ಪ್ರತಿಕ್ರಿಯಿಸಿ, ನಂತರ ಪ್ರಕ್ರಿಯೆ ಮಾಡಿ

ಸ್ವೀಕೃತಿಯನ್ನು ಒಪ್ಪಿಕೊಳ್ಳಲು ಬೇಗನೆ 2xx ಹಿಂತಿರುಗಿಸಿ, ನಂತರ ಯಾವುದೇ ನಿಧಾನ ಕೆಲಸವನ್ನು ಅಸಮಕಾಲಿಕವಾಗಿ ಮಾಡಿ. ನಿಮ್ಮ endpoint ನಿಧಾನವಾಗಿದ್ದರೆ ಅಥವಾ ದೋಷ ನೀಡಿದರೆ, ವಿತರಣೆಗಳನ್ನು ಮರುಪ್ರಯತ್ನಿಸಬಹುದು.

ಪುಟೀಕರಣ

List endpoints ಫಲಿತಾಂಶಗಳನ್ನು ಪುಟಗಳಲ್ಲಿ ಹಿಂತಿರುಗಿಸುತ್ತವೆ ಇದರಿಂದ ಒಂದೇ ಕರೆ ಎಲ್ಲವನ್ನೂ ಲೋಡ್ ಮಾಡಬೇಕಾಗಿಲ್ಲ. ಮುಂದಿನ ಪುಟವನ್ನು ಪಡೆಯಲು ವಿನಂತಿಯಲ್ಲಿ paging ನಿಯತಾಂಕಗಳನ್ನು ರವಾನಿಸಿ ಮತ್ತು ಪ್ರತಿಕ್ರಿಯೆಯ ಮೇಲೆ paging metadata ಅನ್ನು ಓದಿ.

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 ನೊಂದಿಗೆ ಪ್ರತಿಕ್ರಿಯಿಸುತ್ತದೆ. endpoint ಅನ್ನು ಚಚ್ಚುವ ಬದಲು ಹಿಮ್ಮೆಟ್ಟಿ ಮತ್ತು ಮರುಪ್ರಯತ್ನಿಸಿ — ಆದರ್ಶವಾಗಿ ಘಾತೀಯ backoff ಮತ್ತು jitter ನೊಂದಿಗೆ.

{
  "success": false,
  "error": "rate_limited",
  "message": "Too many requests. Please retry after a short delay."
}

ದೋಷ ನಿರ್ವಹಣೆ

ದೋಷಗಳು ಪ್ರಮಾಣಿತ HTTP ಸ್ಥಿತಿ ಕೋಡ್‌ಗಳನ್ನು ಬಳಸುತ್ತವೆ, ಏನು ತಪ್ಪಾಯಿತು ಎಂಬುದನ್ನು ವಿವರಿಸುವ JSON body ಯೊಂದಿಗೆ. ನೀವು ಹೆಚ್ಚಾಗಿ ನೋಡುವ ಕೋಡ್‌ಗಳು:

• 400 — ವಿನಂತಿ ತಪ್ಪಾಗಿ ರಚಿಸಲಾಗಿತ್ತು ಅಥವಾ ಮೌಲ್ಯಮಾಪನ ವಿಫಲವಾಯಿತು.
• 401 — ಕಾಣೆಯಾದ ಅಥವಾ ಅಮಾನ್ಯ API ಕೀ.
• 403 — ಕೀ ಮಾನ್ಯವಾಗಿದೆ ಆದರೆ ಈ ಕ್ರಿಯೆಗೆ scope (ಅಥವಾ org ಪ್ರವೇಶ) ಇಲ್ಲ.
• 404 — ಸಂಪನ್ಮೂಲ ಅಸ್ತಿತ್ವದಲ್ಲಿಲ್ಲ ಅಥವಾ ಈ ಕೀಗೆ ಗೋಚರಿಸುವುದಿಲ್ಲ.
• 409 — ಒಂದು ಸಂಘರ್ಷ, ಉದಾಹರಣೆಗೆ ಈಗಷ್ಟೇ ತೆಗೆದುಕೊಂಡ slot ಅನ್ನು ಬುಕ್ ಮಾಡಲು ಪ್ರಯತ್ನಿಸುವುದು.
• 429 — ದರ ಮಿತಿಗೊಳಿಸಲಾಗಿದೆ; ಹಿಮ್ಮೆಟ್ಟಿ ಮತ್ತು ಮರುಪ್ರಯತ್ನಿಸಿ.
• 5xx — ಸರ್ವರ್-ಸೈಡ್ ದೋಷ; ತಾತ್ಕಾಲಿಕ ವೈಫಲ್ಯಗಳನ್ನು ಮರುಪ್ರಯತ್ನಿಸಿ.

ಒಂದು ವಿಶಿಷ್ಟ ದೋಷ envelope:

{
  "success": false,
  "error": "validation_failed",
  "message": "A human-readable explanation of the problem."
}

ಉತ್ಪನ್ನದ ಪ್ರಕಾರ ಸಂಪನ್ಮೂಲಗಳು

ಮೇಲಿನ ಸಂಪ್ರದಾಯಗಳು ಹಂಚಿಕೊಳ್ಳಲಾಗಿದೆ, ಆದರೆ ಪ್ರತಿ ಉತ್ಪನ್ನವೂ ತನ್ನದೇ ಆದ endpoints ಅನ್ನು ತೆರೆದಿಡುತ್ತದೆ. ನಿಖರ ಸಂಪನ್ಮೂಲಗಳು, ನಿಯತಾಂಕಗಳು ಮತ್ತು ಕ್ಷೇತ್ರ ಹೆಸರುಗಳಿಗಾಗಿ ಉತ್ಪನ್ನದ ಡೆವಲಪರ್ ಪುಟದಿಂದ ಪ್ರಾರಂಭಿಸಿ:

• Calendar — event types, ಲಭ್ಯತೆ slots, bookings (ರಚಿಸಿ, ಮರುಹೊಂದಿಸಿ, ರದ್ದುಗೊಳಿಸಿ), calendars, webhooks, API keys ಮತ್ತು event links. Webhook ಘಟನೆಗಳು booking.created, booking.cancelled, booking.rescheduled, ಮತ್ತು booking.no_show. ಡೆವಲಪರ್‌ಗಳಿಗಾಗಿ Calendar ನೋಡಿ.
• Survey — forms, responses, ಪ್ರತಿಕ್ರಿಯೆ ಸಮಗ್ರೀಕರಣ, AI form ರಚನೆ, ಮತ್ತು webhooks (form.published, response.submitted). ಡೆವಲಪರ್‌ಗಳಿಗಾಗಿ Survey ನೋಡಿ.
• Voice Portal — agents, campaigns, ಮತ್ತು contacts, ಜೊತೆಗೆ tools ಮತ್ತು MCP ಸರ್ವರ್ ನೋಂದಣಿ. ಏಜೆಂಟ್‌ಗಳಿಗಾಗಿ Tools & MCP ನೋಡಿ.

ಸಂಬಂಧಿತ

• ವೇದಿಕೆ ಅವಲೋಕನ — accounts, organizations, ಮತ್ತು ಹಂಚಿಕೊಂಡ ಪರಿಕಲ್ಪನೆಗಳು.
• AI ಏಜೆಂಟ್‌ಗಳಿಗಾಗಿ MCP — AI ಸಹಾಯಕರು ನಿಮಗಾಗಿ ಈ ಸಂಪನ್ಮೂಲಗಳನ್ನು ಕರೆಯಲು ಅವಕಾಶ ನೀಡಿ.
• ಡೆವಲಪರ್‌ಗಳಿಗಾಗಿ Calendar — Calendar ನ REST API ಮತ್ತು webhooks.
• ಡೆವಲಪರ್‌ಗಳಿಗಾಗಿ Survey — Survey ನ API, webhooks, ಮತ್ತು MCP tools.