# REST API


# REST API

imatic தயாரிப்புகள் REST API-களை வழங்குகின்றன, அவற்றை உங்கள் சொந்த குறியீட்டிலிருந்து தானியக்கமாக்கலாம். இந்தப் பக்கத்தில் உள்ள மரபுகள் — நீங்கள் எப்படி அங்கீகரிக்கிறீர்கள், API விசைகள் எப்படி வேலை செய்கின்றன, webhooks எப்படி கையொப்பமிடப்படுகின்றன, மற்றும் பக்கப்பிரிப்பு, விகித வரம்புகள், மற்றும் பிழைகள் எப்படி நடந்துகொள்கின்றன — தயாரிப்புகள் முழுவதும் ஒரே மாதிரியானவை. வேறுபடுவது 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` (ஒரு AI முகவரின் விசைக்குத் தேவைப்படுவது `mcp` வரம்பு — [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" }
}
```

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

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

```json
{
  "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`** — ஒரு சேவையக-பக்க பிழை; தற்காலிக தோல்விகளை மீண்டும் முயற்சிக்கவும்.

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

```json
{
  "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 ஐப்](/calendar/developers) பார்க்கவும்.
- **Survey** — படிவங்கள், பதில்கள், பதில் திரட்டல், AI படிவ உருவாக்கம், மற்றும் webhooks (`form.published`, `response.submitted`). [டெவலப்பர்களுக்கான Survey ஐப்](/survey/developers) பார்க்கவும்.
- **Voice Portal** — முகவர்கள், பிரச்சாரங்கள், மற்றும் தொடர்புகள், மேலும் கருவிகள் மற்றும் MCP சேவையக பதிவு. [முகவர்களுக்கான Tools & MCP ஐப்](/voice/agents/tools-mcp) பார்க்கவும்.

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

- [தள மேலோட்டம்](./overview) — கணக்குகள், நிறுவனங்கள், மற்றும் பகிரப்பட்ட கருத்துக்கள்.
- [AI முகவர்களுக்கான MCP](./mcp) — AI உதவியாளர்கள் உங்களுக்காக இந்த வளங்களை அழைக்க அனுமதிக்கவும்.
- [டெவலப்பர்களுக்கான Calendar](/calendar/developers) — Calendar இன் REST API மற்றும் webhooks.
- [டெவலப்பர்களுக்கான Survey](/survey/developers) — Survey இன் API, webhooks, மற்றும் MCP கருவிகள்.