Skip to main content

REST API

ప్రతి imatic ఉత్పత్తి ఒక వెర్షన్డ్ REST APIని అందిస్తుంది, తద్వారా మీరు దాన్ని మీ స్వంత కోడ్ నుండి ఆటోమేట్ చేయవచ్చు. ఈ పేజీలోని సంప్రదాయాలు — మీరు ఎలా ప్రామాణీకరిస్తారు, API కీలు ఎలా పని చేస్తాయి, వెబ్‌హుక్‌లు ఎలా సంతకం చేయబడతాయి, మరియు పేజినేషన్, రేట్ పరిమితులు, మరియు ఎర్రర్‌లు ఎలా ప్రవర్తిస్తాయి — ఉత్పత్తుల అంతటా ఒకే విధంగా ఉంటాయి. తేడా ఉండేది ప్రతి ఉత్పత్తి బహిర్గతం చేసే వనరులులో, అవి దాని డెవలపర్ పేజీలో డాక్యుమెంట్ చేయబడ్డాయి.

ఉదాహరణలు ఉదాహరణార్థమైనవి

క్రింది అభ్యర్థన మరియు ప్రతిస్పందన స్నిప్పెట్‌లు కాల్‌ల ఆకారంను చూపిస్తాయి — హెడర్‌లు, ఆథ్, ఎర్రర్ ఎన్వలప్‌లు — ఖచ్చితమైన ఫీల్డ్-బై-ఫీల్డ్ స్కీమా కాదు. ఒక ఉత్పత్తి యొక్క ఖచ్చితమైన ఎండ్‌పాయింట్‌లు, పారామీటర్‌లు, మరియు ఫీల్డ్ పేర్ల కోసం, ఆ ఉత్పత్తి యొక్క డెవలపర్ పేజీకి లింక్‌లను అనుసరించండి.

ప్రామాణీకరణ​

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 కీలను పాస్‌వర్డ్‌ల వలె భావించండి

ఒక కీ యొక్క రహస్యం ఒకసారి మాత్రమే, సృష్టి సమయంలో చూపబడుతుంది. అప్పుడు దాన్ని కాపీ చేసి ఒక సీక్రెట్ మేనేజర్ లేదా ఎన్విరాన్‌మెంట్ వేరియబుల్‌లో నిల్వ చేయండి — ఎప్పుడూ సోర్స్ కంట్రోల్, ఒక స్క్రీన్‌షాట్, లేదా ఒక షేర్డ్ డాక్‌లో కాదు. ఒక కీ బయటపడితే, దాన్ని డెవలపర్ ప్రాంతంలో రద్దు చేయండి మరియు ఒక ప్రత్యామ్నాయాన్ని సృష్టించండి. రద్దు తక్షణమే అమలులోకి వస్తుంది.

వెబ్‌హుక్‌లు​

మార్పుల కోసం పోల్ చేయడం కంటే, ఒక వెబ్‌హుక్ URLను నమోదు చేయండి, మరియు ఏదైనా జరిగినప్పుడు imatic దానికి ఒక ఈవెంట్‌ను POST చేస్తుంది — ఉదాహరణకు Calendarలో ఒక బుకింగ్ సృష్టించబడింది లేదా Surveyలో ఒక ప్రతిస్పందన సమర్పించబడింది. మీరు ప్రతి ఉత్పత్తి యొక్క Developers → Webhooks ప్రాంతంలో వెబ్‌హుక్ ఎండ్‌పాయింట్‌లను నిర్వహిస్తారు, అక్కడ మీరు ఒక పరీక్ష డెలివరీని కూడా పంపవచ్చు.

ఒక డెలివరీ స్థూలంగా ఇలా కనిపిస్తుంది:

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} స్ట్రింగ్ యొక్క హెక్స్ 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."
}

ఎర్రర్ నిర్వహణ​

ఎర్రర్‌లు ఏమి తప్పు జరిగిందో వివరించే ఒక JSON బాడీతో ప్రామాణిక HTTP స్థితి కోడ్‌లను ఉపయోగిస్తాయి. మీరు ఎక్కువగా చూసే కోడ్‌లు:

  • 400 — అభ్యర్థన తప్పుగా రూపొందించబడింది లేదా ధృవీకరణలో విఫలమైంది.
  • 401 — లేని లేదా చెల్లని API కీ.
  • 403 — కీ చెల్లుబాటు అయ్యేది కానీ ఈ చర్యకు స్కోప్ (లేదా org యాక్సెస్) లేదు.
  • 404 — వనరు ఉనికిలో లేదు లేదా ఈ కీకి కనిపించదు.
  • 409 — ఇప్పుడే తీసుకోబడిన స్లాట్‌ను బుక్ చేయడానికి ప్రయత్నించడం వంటి ఒక సంఘర్షణ.
  • 429 — రేట్ లిమిట్ చేయబడింది; వెనక్కి తగ్గి మళ్లీ ప్రయత్నించండి.
  • 5xx — ఒక సర్వర్-సైడ్ ఎర్రర్; తాత్కాలిక వైఫల్యాలను మళ్లీ ప్రయత్నించండి.

ఒక సాధారణ ఎర్రర్ ఎన్వలప్:

{
  "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 చూడండి.
  • Survey — ఫారమ్‌లు, ప్రతిస్పందనలు, ప్రతిస్పందన సముదాయీకరణ, AI ఫారమ్ ఉత్పత్తి, మరియు వెబ్‌హుక్‌లు (form.published, response.submitted). డెవలపర్‌ల కోసం Survey చూడండి.
  • Voice Portal — ఏజెంట్‌లు, ప్రచారాలు, మరియు సంప్రదింపులు, ప్లస్ సాధనాలు మరియు MCP సర్వర్ నమోదు. ఏజెంట్‌ల కోసం సాధనాలు & MCP చూడండి.

సంబంధితం​