Skip to main content

REST API

દરેક imatic પ્રોડક્ટ એક versioned REST API આપે છે જેથી તમે તેને તમારા પોતાના કોડથી ઑટોમેટ કરી શકો. આ પાનાં પરના સંમેલનો — તમે કેવી રીતે authenticate કરો છો, API keys કેવી રીતે કામ કરે છે, webhooks કેવી રીતે signed થાય છે, અને પેજિનેશન, રેટ લિમિટ્સ અને ભૂલો કેવી રીતે વર્તે છે — દરેક પ્રોડક્ટમાં સમાન છે. જે અલગ પડે છે તે છે દરેક પ્રોડક્ટ ખુલ્લા કરતા resources, જે તેના ડેવલપર પાનાં પર દસ્તાવેજ કરેલા છે.

ઉદાહરણો સ્પષ્ટતા માટે છે

નીચેના request અને response સ્નિપેટ્સ કૉલ્સનો આકાર દર્શાવે છે — headers, auth, error envelopes — નહીં કે ચોક્કસ ફીલ્ડ-બાય-ફીલ્ડ schema. કોઈ પ્રોડક્ટના ચોક્કસ એન્ડપોઇન્ટ્સ, parameters અને ફીલ્ડ નામો માટે, તે પ્રોડક્ટના ડેવલપર પાનાંની લિંક્સ અનુસરો.

પ્રમાણીકરણ (Authentication)​

imatic બે પ્રકારના ઓળખપત્રો વાપરે છે, બે અલગ-અલગ કૉલર્સ માટે:

  • JWT (session token) — ઇમેલ અને પાસવર્ડ સાથે સાઇન ઇન કર્યા પછી વેબ ઍપ જે વાપરે છે. તે બ્રાઉઝરમાં તમારું પ્રતિનિધિત્વ કરે છે અને અલ્પજીવી હોય છે. તમે આને સીધું મેનેજ કરતા નથી; ઍપ કરે છે.
  • Scoped API key — તમારો કોડ v1 REST API ને કૉલ કરવા જે વાપરે છે. તમે તેને જાતે બનાવો છો, તે સ્પષ્ટ scopes ધરાવે છે, અને તે બ્રાઉઝર સત્ર સાથે સમાપ્ત થતી નથી.

સર્વર-થી-સર્વર કૉલ્સ માટે, હંમેશા API key વાપરો — ક્યારેય તમારો પાસવર્ડ કે કૉપિ કરેલ session token નહીં.

API key મોકલવી​

કીને Authorization header માં Bearer token તરીકે મોકલો:

curl https://<product-host>/v1/event-types \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial" \
  -H "Content-Type: application/json"

API keys કેવી રીતે કામ કરે છે​

તમે દરેક પ્રોડક્ટના ડેવલપર વિસ્તારમાં API keys બનાવો અને મેનેજ કરો છો — ઉદાહરણ તરીકે Calendar નું Developers → API keys અને Survey નું Developers → API keys. એક કીના ત્રણ ગુણધર્મો સમજવા યોગ્ય છે:

  • prefix.secret ફોર્મેટ — એક કીમાં એક જાહેર prefix અને એક ગુપ્ત ભાગ હોય છે, જે એક ટપકાથી જોડાયેલા હોય છે (ઉદાહરણ તરીકે cal_abc123.s3cr3t_keymaterial — Calendar keys ટૂંકો cal_ prefix વાપરે છે). prefix imatic ને યાદીઓ અને લોગ્સમાં કીને ઓળખવા દે છે; secret એ સાબિત કરે છે કે તે તમારી છે.
  • એક જ વાર દર્શાવાય — પૂર્ણ કી મૂલ્ય માત્ર તમે તેને બનાવો છો તે ક્ષણે જ દર્શાવાય છે. તે પછી, માત્ર prefix દેખાય છે.
  • Scopes — દરેક કી તમે મંજૂર કરેલ ક્રિયાઓ સુધી મર્યાદિત હોય છે. Calendar ના scopes છે slots:read, bookings:read, bookings:write, અને mcp (mcp scope એ છે જે AI એજન્ટની કીને જોઈએ — જુઓ AI એજન્ટ્સ માટે MCP). કોઈ request જે કીના scope કરતાં વધારે હોય તેને નકારી દેવામાં આવે છે.
API keys ને પાસવર્ડની જેમ ગણો

કીનું secret માત્ર એક જ વાર દર્શાવાય છે, બનાવતી વખતે. ત્યારે જ તેને કૉપિ કરો અને તેને secret manager કે environment variable માં સંગ્રહો — ક્યારેય source control, screenshot કે શેર કરેલ doc માં નહીં. જો કોઈ કી ખુલ્લી પડે, તો ડેવલપર વિસ્તારમાં તેને રદ કરો અને બદલી બનાવો. રદ કરવાનું તરત જ અમલમાં આવે છે.

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

signature ચકાસવી​

દરેક ડિલિવરી તમારા endpoint ના signing secret નો ઉપયોગ કરીને HMAC-SHA256 સાથે signed થાય છે, Stripe-શૈલીના X-Imatic-Signature header માં. header બે ફીલ્ડ ધરાવે છે: t, મોકલવાના સમયે unix-epoch સેકન્ડ્સ, અને v1, સ્ટ્રિંગ ${t}.${body} નું hex HMAC (timestamp, એક literal ટપકું, પછી ચોક્કસ raw request body). ચકાસવા માટે, header ને વિભાજિત કરો, તમારા signing secret સાથે t + "." + rawBody પર v1 ફરી ગણો, અને constant time માં સરખામણી કરો. જો તે મેળ ન ખાય તો નકારો — અને replay સામે રક્ષણ માટે વૈકલ્પિક રીતે 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);
}
દરેક પ્રોડક્ટ માટે ચોક્કસ scheme

ઉપરનું t=…,v1=… scheme Calendar નું છે. તમે verifier ship કરો તે પહેલાં દરેક પ્રોડક્ટના ડેવલપર પાનાં પર header નામ, ફીલ્ડ્સ અને signed string ની પુષ્ટિ કરો.

ઝડપથી જવાબ આપો, પછી પ્રક્રિયા કરો

પ્રાપ્તિ સ્વીકારવા માટે ઝડપથી 2xx પાછું આપો, પછી કોઈપણ ધીમું કામ asynchronously કરો. જો તમારું endpoint ધીમું હોય કે ભૂલ આપે, તો ડિલિવરી ફરી પ્રયાસ થઈ શકે છે.

પેજિનેશન (Pagination)​

List endpoints પરિણામો પાનાંમાં પાછા આપે છે જેથી એક જ કૉલને ક્યારેય બધું જ લોડ ન કરવું પડે. request પર paging parameters મોકલો અને આગલું પાનું મેળવવા response પર 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 }
}

જ્યાં સુધી વધુ પરિણામો ન રહે ત્યાં સુધી આગલું પાનું માગતા રહો.

રેટ લિમિટિંગ (Rate limiting)​

પ્લેટફોર્મને નિષ્પક્ષ અને સ્થિર રાખવા માટે API keys રેટ લિમિટેડ હોય છે. જો તમે મર્યાદા ઓળંગો, તો API એ HTTP 429 Too Many Requests સાથે જવાબ આપે છે. endpoint પર સતત ઘા કરવાને બદલે પાછા હટો અને ફરી પ્રયાસ કરો — આદર્શ રીતે exponential backoff અને jitter સાથે.

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

ભૂલ-સંચાલન (Error handling)​

ભૂલો પ્રમાણભૂત HTTP status codes અને એક JSON body વાપરે છે જે વર્ણવે છે કે શું ખોટું થયું. તમે જે codes સૌથી વારંવાર જોશો:

  • 400 — request ખામીયુક્ત હતી કે validation નિષ્ફળ ગયું.
  • 401 — ગુમ કે અમાન્ય API key.
  • 403 — કી માન્ય છે પણ આ ક્રિયા માટે scope (કે org ઍક્સેસ) નથી.
  • 404 — resource અસ્તિત્વમાં નથી કે આ કીને દેખાતું નથી.
  • 409 — એક સંઘર્ષ, જેમ કે હમણાં જ લેવાયેલા slot ને બુક કરવાનો પ્રયાસ.
  • 429 — રેટ લિમિટેડ; પાછા હટો અને ફરી પ્રયાસ કરો.
  • 5xx — એક સર્વર-સાઇડ ભૂલ; transient નિષ્ફળતાઓ ફરી પ્રયાસ કરો.

એક લાક્ષણિક error envelope:

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

પ્રોડક્ટ પ્રમાણે resources​

ઉપરના સંમેલનો વહેંચાયેલા છે, પણ દરેક પ્રોડક્ટ તેના પોતાના endpoints ખુલ્લા કરે છે. ચોક્કસ resources, parameters અને ફીલ્ડ નામો માટે પ્રોડક્ટના ડેવલપર પાનાંથી શરૂ કરો:

  • Calendar — event types, availability slots, bookings (create, reschedule, cancel), calendars, webhooks, API keys, અને event links. Webhook events છે booking.created, booking.cancelled, booking.rescheduled, અને booking.no_show. જુઓ Calendar for developers.
  • Survey — forms, responses, response aggregation, AI ફોર્મ જનરેશન, અને webhooks (form.published, response.submitted). જુઓ Survey for developers.
  • Voice Portal — agents, campaigns, અને contacts, ઉપરાંત tools અને MCP સર્વર રજિસ્ટ્રેશન. જુઓ એજન્ટ્સ માટે Tools અને MCP.

સંબંધિત​