REST API

ஒவ்வொரு imatic தயாரிப்பும் ஒரு பதிப்பிடப்பட்ட REST API ஐ வழங்குகிறது, இதனால் உங்கள் சொந்த குறியீட்டிலிருந்து அதை தானியக்கமாக்கலாம். இந்தப் பக்கத்தில் உள்ள மரபுகள் — நீங்கள் எப்படி அங்கீகரிக்கிறீர்கள், API விசைகள் எப்படி வேலை செய்கின்றன, webhooks எப்படி கையொப்பமிடப்படுகின்றன, மற்றும் பக்கப்பிரிப்பு, விகித வரம்புகள், மற்றும் பிழைகள் எப்படி நடந்துகொள்கின்றன — தயாரிப்புகள் முழுவதும் ஒரே மாதிரியானவை. வேறுபடுவது ஒவ்வொரு தயாரிப்பும் வெளிப்படுத்தும் வளங்கள், அவை அதன் டெவலப்பர் பக்கத்தில் ஆவணப்படுத்தப்பட்டுள்ளன.

எடுத்துக்காட்டுகள் விளக்கமானவை

கீழே உள்ள கோரிக்கை மற்றும் பதில் துணுக்குகள் அழைப்புகளின் வடிவத்தைக் காட்டுகின்றன — தலைப்புகள், அங்கீகாரம், பிழை உறைகள் — ஒரு துல்லியமான புலம்-வாரியான திட்டத்தை அல்ல. ஒரு தயாரிப்பின் துல்லியமான இறுதிப்புள்ளிகள், அளவுருக்கள், மற்றும் புலப் பெயர்களுக்கு, அந்த தயாரிப்பின் டெவலப்பர் பக்கத்திற்கான இணைப்புகளைப் பின்தொடரவும்.

அங்கீகாரம்

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 (ஒரு AI முகவரின் விசைக்குத் தேவைப்படுவது mcp வரம்பு — 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" }
}

கையொப்பத்தைச் சரிபார்த்தல்

ஒவ்வொரு வழங்கலும் உங்கள் இறுதிப்புள்ளியின் கையொப்ப ரகசியத்தைப் பயன்படுத்தி, ஒரு Stripe-பாணி X-Imatic-Signature தலைப்பில், HMAC-SHA256 உடன் கையொப்பமிடப்படுகிறது. தலைப்பு இரண்டு புலங்களைச் சுமக்கிறது: 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 உடன் பதிலளிக்கிறது. இறுதிப்புள்ளியை அடிப்பதைவிட — சிறந்தது அதிவேக பின்வாங்கல் மற்றும் jitter உடன் — பின்வாங்கி மீண்டும் முயற்சிக்கவும்.

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

பிழை கையாளுதல்

பிழைகள் என்ன தவறு நடந்தது என்பதை விவரிக்கும் ஒரு JSON உடலுடன் நிலையான HTTP நிலைக் குறியீடுகளைப் பயன்படுத்துகின்றன. நீங்கள் அடிக்கடி பார்க்கும் குறியீடுகள்:

400 — கோரிக்கை தவறாக வடிவமைக்கப்பட்டது அல்லது சரிபார்ப்பில் தோல்வியடைந்தது.
401 — விடுபட்ட அல்லது தவறான API விசை.
403 — விசை செல்லுபடியாகும் ஆனால் இந்த செயலுக்கான வரம்பு (அல்லது நிறுவன அணுகல்) இல்லை.
404 — வளம் இல்லை அல்லது இந்த விசைக்குத் தெரியவில்லை.
409 — ஒரு முரண்பாடு, எடுத்துக்காட்டாக சற்று முன் எடுக்கப்பட்ட ஒரு இடைவெளியை முன்பதிவு செய்ய முயற்சிப்பது.
429 — விகித வரம்பிடப்பட்டது; பின்வாங்கி மீண்டும் முயற்சிக்கவும்.
5xx — ஒரு சேவையக-பக்க பிழை; தற்காலிக தோல்விகளை மீண்டும் முயற்சிக்கவும்.

ஒரு வழக்கமான பிழை உறை:

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

தயாரிப்பு வாரியான வளங்கள்

மேலே உள்ள மரபுகள் பகிரப்படுகின்றன, ஆனால் ஒவ்வொரு தயாரிப்பும் அதன் சொந்த இறுதிப்புள்ளிகளை வெளிப்படுத்துகிறது. துல்லியமான வளங்கள், அளவுருக்கள், மற்றும் புலப் பெயர்களுக்கு தயாரிப்பின் டெவலப்பர் பக்கத்திலிருந்து தொடங்கவும்:

Calendar — நிகழ்வு வகைகள், கிடைக்கும் நேர இடைவெளிகள், முன்பதிவுகள் (உருவாக்கு, மறுஅட்டவணை, ரத்து), காலெண்டர்கள், webhooks, API விசைகள், மற்றும் நிகழ்வு இணைப்புகள். Webhook நிகழ்வுகள் booking.created, booking.cancelled, booking.rescheduled, மற்றும் booking.no_show. டெவலப்பர்களுக்கான Calendar ஐப் பார்க்கவும்.
Survey — படிவங்கள், பதில்கள், பதில் திரட்டல், AI படிவ உருவாக்கம், மற்றும் webhooks (form.published, response.submitted). டெவலப்பர்களுக்கான Survey ஐப் பார்க்கவும்.
Voice Portal — முகவர்கள், பிரச்சாரங்கள், மற்றும் தொடர்புகள், மேலும் கருவிகள் மற்றும் MCP சேவையக பதிவு. முகவர்களுக்கான Tools & MCP ஐப் பார்க்கவும்.

தொடர்புடையவை

தள மேலோட்டம் — கணக்குகள், நிறுவனங்கள், மற்றும் பகிரப்பட்ட கருத்துக்கள்.
AI முகவர்களுக்கான MCP — AI உதவியாளர்கள் உங்களுக்காக இந்த வளங்களை அழைக்க அனுமதிக்கவும்.
டெவலப்பர்களுக்கான Calendar — Calendar இன் REST API மற்றும் webhooks.
டெவலப்பர்களுக்கான Survey — Survey இன் API, webhooks, மற்றும் MCP கருவிகள்.

அங்கீகாரம்​

ஒரு API விசையை அனுப்புதல்​

API விசைகள் எப்படி வேலை செய்கின்றன​

Webhooks​

கையொப்பத்தைச் சரிபார்த்தல்​

பக்கப்பிரிப்பு​

விகித வரம்பிடல்​

பிழை கையாளுதல்​

தயாரிப்பு வாரியான வளங்கள்​

தொடர்புடையவை​