Calendar API ਅਤੇ MCP
imatic Calendar ਵਿੱਚ ਤੁਸੀਂ ਜੋ ਵੀ ਕਰਦੇ ਹੋ, ਉਸ ਨੂੰ ਸਵੈਚਾਲਿਤ ਕਰ ਸਕਦੇ ਹੋ। ਸਲਾਟਾਂ ਦੀ ਪੁੱਛਗਿੱਛ ਕਰਨ ਅਤੇ ਬੁਕਿੰਗਾਂ ਬਣਾਉਣ ਲਈ REST API ਵਰਤੋ, ਇਵੈਂਟਾਂ ਪ੍ਰਤੀ ਰੀਅਲ ਟਾਈਮ ਵਿੱਚ ਪ੍ਰਤੀਕਿਰਿਆ ਦੇਣ ਲਈ ਵੈੱਬਹੁੱਕ, ਅਤੇ ਕਿਸੇ AI ਏਜੰਟ ਨੂੰ ਤੁਹਾਡੇ ਵੱਲੋਂ ਬੁੱਕ ਕਰਨ ਦੇਣ ਲਈ MCP ਸਰਵਰ। ਇਹ ਪੰਨਾ ਉਨ੍ਹਾਂ ਡਿਵੈਲਪਰਾਂ ਲਈ ਹੈ ਜੋ imatic Calendar ਨੂੰ ਆਪਣੀਆਂ ਐਪਾਂ ਅਤੇ ਟੂਲਾਂ ਵਿੱਚ ਜੋੜ ਰਹੇ ਹਨ।
ਤੁਸੀਂ ਆਪਣੇ ਡੈਸ਼ਬੋਰਡ ਵਿੱਚ Developers ਅਧੀਨ ਪ੍ਰਮਾਣ-ਪੱਤਰ ਪ੍ਰਬੰਧਿਤ ਕਰਦੇ ਹੋ।
API keys ਅਤੇ Webhooks ਪੰਨੇ ਇੱਕ ਖਾਤਾ ਐਡਮਿਨ (org admin ਜਾਂ super admin) ਦੁਆਰਾ ਪ੍ਰਬੰਧਿਤ ਕੀਤੇ ਜਾਂਦੇ ਹਨ। ਜੇ ਤੁਹਾਨੂੰ ਇਹ ਆਪਣੇ ਡੈਸ਼ਬੋਰਡ ਵਿੱਚ ਨਹੀਂ ਦਿਸਦੇ, ਤਾਂ ਆਪਣੇ ਖਾਤੇ 'ਤੇ ਕਿਸੇ ਐਡਮਿਨ ਨੂੰ ਤੁਹਾਡੇ ਲਈ ਕੁੰਜੀ ਜਾਰੀ ਕਰਨ ਜਾਂ ਵੈੱਬਹੁੱਕ ਸੈੱਟ ਕਰਨ ਲਈ ਕਹੋ।
ਪ੍ਰਮਾਣੀਕਰਨ ਅਤੇ API ਕੁੰਜੀਆਂ
API ਨੂੰ ਕੀਤੀਆਂ ਕਾਲਾਂ ਇੱਕ API ਕੁੰਜੀ ਨਾਲ ਪ੍ਰਮਾਣਿਤ ਕੀਤੀਆਂ ਜਾਂਦੀਆਂ ਹਨ ਜੋ ਇੱਕ ਬੀਅਰਰ ਟੋਕਨ ਵਜੋਂ ਭੇਜੀ ਜਾਂਦੀ ਹੈ:
Authorization: Bearer <your_api_key>
ਕੁੰਜੀਆਂ ਨੂੰ Developers → API keys ਅਧੀਨ ਪ੍ਰਬੰਧਿਤ ਕਰੋ, ਜਿੱਥੇ ਤੁਸੀਂ:
- ਇੱਕ ਕੁੰਜੀ ਬਣਾ ਸਕਦੇ ਹੋ — ਜਦੋਂ ਰਾਜ਼ ਦਿਖਾਇਆ ਜਾਵੇ ਤਾਂ ਉਸ ਨੂੰ ਕਾਪੀ ਕਰ ਲਓ; ਇਹ ਦੁਬਾਰਾ ਨਹੀਂ ਦਿਖਾਇਆ ਜਾਂਦਾ।
- ਆਪਣੀਆਂ ਕੁੰਜੀਆਂ ਦੀ ਸੂਚੀ ਦੇਖ ਸਕਦੇ ਹੋ ਅਤੇ ਹਰ ਇੱਕ ਕਿਸ ਲਈ ਹੈ ਇਹ ਦੇਖ ਸਕਦੇ ਹੋ।
- ਜੇ ਕੋਈ ਕੁੰਜੀ ਲੀਕ ਹੋ ਜਾਵੇ ਜਾਂ ਹੁਣ ਲੋੜੀਂਦੀ ਨਾ ਹੋਵੇ ਤਾਂ ਉਸ ਨੂੰ ਤੁਰੰਤ ਰੱਦ ਕਰ ਸਕਦੇ ਹੋ।
- ਸਕੋਪ ਨਿਯੁਕਤ ਕਰ ਸਕਦੇ ਹੋ — ਹਰ ਕੁੰਜੀ ਸਿਰਫ਼ ਉਹੀ ਅਨੁਮਤੀਆਂ ਰੱਖਦੀ ਹੈ ਜੋ ਤੁਸੀਂ ਦਿੰਦੇ ਹੋ, ਇਸ ਲਈ ਇੱਕ ਸਿਰਫ਼-ਪੜ੍ਹਨ ਵਾਲੀ ਕੁੰਜੀ ਬੁਕਿੰਗਾਂ ਦੀ ਸੂਚੀ ਦੇ ਸਕਦੀ ਹੈ ਪਰ ਉਨ੍ਹਾਂ ਨੂੰ ਕਦੇ ਬਣਾ ਜਾਂ ਰੱਦ ਨਹੀਂ ਕਰ ਸਕਦੀ।
ਉਪਲਬਧ ਸਕੋਪ ਹਨ:
| ਸਕੋਪ | ਕੀ ਦਿੰਦਾ ਹੈ |
|---|---|
slots:read | ਕਿਸੇ ਇਵੈਂਟ ਕਿਸਮ ਲਈ ਉਪਲਬਧ ਸਮਾਂ ਸਲਾਟ ਪੜ੍ਹੋ |
bookings:read | ਬੁਕਿੰਗਾਂ ਦੀ ਸੂਚੀ ਬਣਾਓ ਅਤੇ ਪੜ੍ਹੋ |
bookings:write | ਬੁਕਿੰਗਾਂ ਬਣਾਓ, ਰੱਦ ਕਰੋ, ਅਤੇ ਮੁੜ-ਨਿਯਤ ਕਰੋ |
mcp | MCP ਸਰਵਰ ਵਰਤੋ (ਇੱਕ ਛਤਰੀ ਜੋ slots:read, bookings:read, ਅਤੇ bookings:write ਨੂੰ ਵੀ ਕਵਰ ਕਰਦੀ ਹੈ) |
ਇੱਕ ਕੁੰਜੀ ਆਪਣੇ ਸਕੋਪਾਂ ਅੰਦਰ ਤੁਹਾਡੇ ਖਾਤੇ ਤੱਕ ਪਹੁੰਚ ਦਿੰਦੀ ਹੈ। ਇਸ ਨੂੰ ਇੱਕ ਸੀਕ੍ਰੇਟ ਮੈਨੇਜਰ ਜਾਂ ਵਾਤਾਵਰਣ ਵੇਰੀਏਬਲ ਵਿੱਚ ਸਟੋਰ ਕਰੋ, ਕਦੇ ਵੀ ਕਲਾਇੰਟ-ਸਾਈਡ ਕੋਡ ਜਾਂ ਜਨਤਕ ਰਿਪੋ ਵਿੱਚ ਨਹੀਂ। ਜੇ ਇਹ ਉਜਾਗਰ ਹੋ ਜਾਵੇ ਤਾਂ ਤੁਰੰਤ ਰੱਦ ਕਰੋ ਅਤੇ ਘੁਮਾਓ।
REST API v1
REST API /v1 ਬੇਸ ਪਾਥ ਅਧੀਨ ਪਰੋਸਿਆ ਜਾਂਦਾ ਹੈ ਅਤੇ JSON ਵਾਪਸ ਕਰਦਾ ਹੈ। ਉਪਲਬਧ ਸਰੋਤ ਹਨ:
- ਇਵੈਂਟ ਕਿਸਮਾਂ — ਆਪਣੀਆਂ ਇਵੈਂਟ ਕਿਸਮਾਂ ਦੀ ਸੂਚੀ ਬਣਾਓ ਅਤੇ ਪੜ੍ਹੋ, ਨਾਲ ਹੀ ਇੱਕ ਇਵੈਂਟ ਕਿਸਮ ਦੀ ਨਕਲ ਬਣਾਓ (
POST /v1/event-types/:code/duplicate)। (ਬਣਾਉਣਾ/ਸੰਪਾਦਨ/ਮਿਟਾਉਣਾ ਡੈਸ਼ਬੋਰਡ ਵਿੱਚ ਕੀਤਾ ਜਾਂਦਾ ਹੈ।) - ਸਲਾਟ — ਕਿਸੇ ਇਵੈਂਟ ਕਿਸਮ ਲਈ ਉਪਲਬਧ ਸਮਾਂ ਸਲਾਟਾਂ ਦੀ ਪੁੱਛਗਿੱਛ ਕਰੋ (ਉਹੀ ਖੁੱਲ੍ਹਾ ਸਮਾਂ ਜੋ ਤੁਹਾਡੇ ਬੁਕਿੰਗ ਪੰਨੇ 'ਤੇ ਦਿਖਾਇਆ ਜਾਂਦਾ ਹੈ, ਸਾਰੇ ਬਫ਼ਰ, ਨੋਟਿਸ, ਅਤੇ ਹੱਦਾਂ ਲਾਗੂ ਕਰਕੇ)।
- ਬੁਕਿੰਗਾਂ — ਪੂਰਾ CRUD ਅਤੇ ਨਾਲ ਮੁੜ-ਨਿਯਤ: ਇੱਕ ਬੁਕਿੰਗ ਬਣਾਓ, ਬੁਕਿੰਗਾਂ ਦੀ ਸੂਚੀ ਬਣਾਓ ਅਤੇ ਪੜ੍ਹੋ, ਰੱਦ ਕਰੋ, ਅਤੇ ਇੱਕ ਨੂੰ ਨਵੇਂ ਸਮੇਂ 'ਤੇ ਲੈ ਜਾਓ।
GET /v1/bookings/statsਕੁੱਲ ਬੁਕਿੰਗ ਗਿਣਤੀਆਂ ਵਾਪਸ ਕਰਦਾ ਹੈ। - ਇਵੈਂਟ ਲਿੰਕ — ਇੱਕ ਇਵੈਂਟ ਕਿਸਮ ਨਾਲ ਜੁੜੇ ਇੱਕ-ਵਾਰ-ਵਰਤੋਂ ਵਾਲੇ ਬੁਕਿੰਗ ਲਿੰਕ ਬਣਾਓ, ਸੂਚੀਬੱਧ ਕਰੋ, ਅਤੇ ਰੱਦ ਕਰੋ (
POST/GET /v1/event-types/:code/links,DELETE /v1/event-links/:linkCode)। - ਵੈੱਬਹੁੱਕ — ਆਪਣੀਆਂ ਵੈੱਬਹੁੱਕ ਸਬਸਕ੍ਰਿਪਸ਼ਨਾਂ ਨੂੰ ਪ੍ਰੋਗਰਾਮੈਟਿਕ ਤੌਰ 'ਤੇ ਪ੍ਰਬੰਧਿਤ ਕਰੋ।
- ਯੂਜ਼ਰ / me —
GET /v1/users/meAPI ਕੁੰਜੀ ਦੀ ਪਛਾਣ (ਪ੍ਰਮਾਣਿਤ ਖਾਤਾ ਅਤੇ org) ਵਾਪਸ ਕਰਦਾ ਹੈ। - ਕੈਲੰਡਰ — ਆਪਣੇ ਜੁੜੇ ਕੈਲੰਡਰਾਂ ਨਾਲ ਕੰਮ ਕਰੋ (ਦੇਖੋ ਏਕੀਕਰਨ)।
ਇੱਕ ਆਮ ਸਵੈਚਾਲਨ ਪ੍ਰਵਾਹ: ਕਿਸੇ ਇਵੈਂਟ ਕਿਸਮ ਲਈ ਸਲਾਟ ਦੀ ਪੁੱਛਗਿੱਛ ਕਰੋ, ਫਿਰ ਤੁਹਾਡੇ ਯੂਜ਼ਰ ਦੁਆਰਾ ਚੁਣੇ ਸਲਾਟ ਲਈ ਇੱਕ ਬੁਕਿੰਗ ਬਣਾਓ — ਉਹੀ ਪਰਮਾਣੂ, ਦੋਹਰੀ-ਬੁਕਿੰਗ-ਰਹਿਤ ਗਾਰੰਟੀ ਜੋ ਬੁਕਿੰਗ ਪੰਨਾ ਵਰਤਦਾ ਹੈ ਉਹ API 'ਤੇ ਵੀ ਲਾਗੂ ਹੁੰਦੀ ਹੈ।
ਵੈੱਬਹੁੱਕ
ਵੈੱਬਹੁੱਕ ਇਵੈਂਟਾਂ ਨੂੰ ਉਨ੍ਹਾਂ ਦੇ ਵਾਪਰਨ ਦੇ ਪਲ ਤੁਹਾਡੇ ਸਰਵਰ ਵੱਲ ਧੱਕਦੇ ਹਨ, ਤਾਂ ਜੋ ਤੁਹਾਨੂੰ ਪੋਲ ਨਾ ਕਰਨਾ ਪਵੇ। ਇਨ੍ਹਾਂ ਨੂੰ Developers → Webhooks ਅਧੀਨ ਪ੍ਰਬੰਧਿਤ ਕਰੋ।
- ਬੁਕਿੰਗ ਇਵੈਂਟ ਪ੍ਰਾਪਤ ਕਰਨ ਲਈ ਇੱਕ URL ਨੂੰ ਸਬਸਕ੍ਰਾਈਬ ਕਰੋ। ਇਵੈਂਟ ਠੀਕ ਇਹੀ ਹਨ:
booking.created,booking.cancelled,booking.rescheduled, ਅਤੇbooking.no_show। - ਹਰ ਡਿਲੀਵਰੀ HMAC ਨਾਲ ਹਸਤਾਖਰਿਤ ਹੁੰਦੀ ਹੈ — ਪੇਲੋਡ 'ਤੇ ਭਰੋਸਾ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਇਹ ਪੁਸ਼ਟੀ ਕਰਨ ਲਈ ਕਿ ਬੇਨਤੀ ਸੱਚਮੁੱਚ imatic Calendar ਤੋਂ ਆਈ ਹੈ, ਹਸਤਾਖਰ ਹੈਡਰ ਨੂੰ ਆਪਣੇ ਵੈੱਬਹੁੱਕ ਦੇ ਰਾਜ਼ ਖ਼ਿਲਾਫ਼ ਪੁਸ਼ਟ ਕਰੋ।
- ਨਿਰਮਾਣ ਦੌਰਾਨ ਆਪਣੇ ਅੰਤ-ਬਿੰਦੂ 'ਤੇ ਇੱਕ ਨਮੂਨਾ ਇਵੈਂਟ ਭੇਜਣ ਲਈ ਅੰਦਰੂਨੀ Test ਕਾਰਵਾਈ ਵਰਤੋ, ਤਾਂ ਜੋ ਤੁਸੀਂ ਲਾਈਵ ਹੋਣ ਤੋਂ ਪਹਿਲਾਂ ਪੁਸ਼ਟੀ ਕਰ ਸਕੋ ਕਿ ਤੁਹਾਡਾ ਹੈਂਡਲਰ ਕੰਮ ਕਰਦਾ ਹੈ।
ਹਸਤਾਖਰ X-Imatic-Signature ਹੈਡਰ ਵਿੱਚ, ਇੱਕ Stripe-ਸ਼ੈਲੀ ਫਾਰਮੈਟ ਵਿੱਚ ਜਾਂਦਾ ਹੈ:
X-Imatic-Signature: t=<unix-epoch-seconds>,v1=<hmac-sha256>
ਪੁਸ਼ਟੀ ਕਰਨ ਲਈ: t ਅਤੇ ਕੱਚਾ ਬੇਨਤੀ ਬਾਡੀ ਲਓ, HMAC-SHA256(secret, "<t>.<body>") ਦੀ ਗਣਨਾ ਕਰੋ (ਟਾਈਮਸਟੈਂਪ ਅਤੇ ਬਾਡੀ ਇੱਕ ਅੱਖਰੀ ਬਿੰਦੀ ਨਾਲ ਜੁੜੇ ਹੋਏ), ਇਸ ਨੂੰ ਹੈਕਸ-ਏਨਕੋਡ ਕਰੋ, ਅਤੇ ਇਸ ਨੂੰ v1 ਨਾਲ ਮਿਲਾਓ। ਜੇ ਮੇਲ ਨਾ ਖਾਣ ਤਾਂ ਬੇਨਤੀ ਨੂੰ ਅਸਵੀਕਾਰ ਕਰੋ।
ਕਿਸੇ ਵੀ ਵੈੱਬਹੁੱਕ ਨੂੰ ਅਸਵੀਕਾਰ ਕਰੋ ਜਿਸ ਦਾ HMAC ਹਸਤਾਖਰ ਮੇਲ ਨਹੀਂ ਖਾਂਦਾ। ਇਹ ਇੱਕ ਭਰੋਸੇਯੋਗ ਸਵੈਚਾਲਨ ਅਤੇ ਇੱਕ ਖੁੱਲ੍ਹੇ ਦਰਵਾਜ਼ੇ ਵਿਚਕਾਰ ਫ਼ਰਕ ਹੈ।
MCP ਸਰਵਰ
imatic Calendar ਇੱਕ Model Context Protocol (MCP) ਸਰਵਰ ਨਾਲ ਆਉਂਦਾ ਹੈ, ਤਾਂ ਜੋ AI ਏਜੰਟ ਅਤੇ ਸਹਾਇਕ ਚੰਗੀ ਤਰ੍ਹਾਂ ਪਰਿਭਾਸ਼ਿਤ ਟੂਲਾਂ ਰਾਹੀਂ ਤੁਹਾਡੀ ਉਪਲਬਧਤਾ ਪੜ੍ਹ ਸਕਣ ਅਤੇ ਬੁਕਿੰਗਾਂ ਪ੍ਰਬੰਧਿਤ ਕਰ ਸਕਣ — REST API ਵਾਲੇ ਉਹੀ API-ਕੁੰਜੀ ਪ੍ਰਮਾਣੀਕਰਨ ਅਤੇ ਸਕੋਪ ਵਰਤਦੇ ਹੋਏ।
ਸਰਵਰ ਸੱਤ ਟੂਲ ਉਜਾਗਰ ਕਰਦਾ ਹੈ:
| ਟੂਲ | ਇਹ ਕੀ ਕਰਦਾ ਹੈ |
|---|---|
list_event_types | ਤੁਹਾਡੀਆਂ ਬੁੱਕ-ਯੋਗ ਇਵੈਂਟ ਕਿਸਮਾਂ ਦੀ ਸੂਚੀ ਬਣਾਓ |
list_slots | ਕਿਸੇ ਇਵੈਂਟ ਕਿਸਮ ਲਈ ਖੁੱਲ੍ਹੇ ਸਲਾਟ ਪ੍ਰਾਪਤ ਕਰੋ |
create_booking | ਇੱਕ ਸਲਾਟ ਬੁੱਕ ਕਰੋ |
cancel_booking | ਇੱਕ ਬੁਕਿੰਗ ਰੱਦ ਕਰੋ |
reschedule_booking | ਇੱਕ ਬੁਕਿੰਗ ਨੂੰ ਨਵੇਂ ਸਮੇਂ 'ਤੇ ਲੈ ਜਾਓ |
list_bookings | ਮੌਜੂਦਾ ਬੁਕਿੰਗਾਂ ਦੀ ਸੂਚੀ ਬਣਾਓ |
get_booking | ਇੱਕ ਬੁਕਿੰਗ ਨੂੰ ਉਸ ਦੇ ਕੋਡ ਦੁਆਰਾ ਪੜ੍ਹੋ |
ਆਪਣੇ MCP-ਸਮਰੱਥ ਕਲਾਇੰਟ ਨੂੰ ਸਰਵਰ ਵੱਲ ਨਿਰਦੇਸ਼ਿਤ ਕਰੋ, ਇੱਕ API ਕੁੰਜੀ ਨਾਲ ਪ੍ਰਮਾਣਿਤ ਕਰੋ, ਅਤੇ ਤੁਹਾਡਾ ਏਜੰਟ "Priya ਵੀਰਵਾਰ ਕਦੋਂ ਫ਼ੁਰਸਤ ਵਿੱਚ ਹੈ?" ਦਾ ਜਵਾਬ ਦੇ ਸਕਦਾ ਹੈ ਅਤੇ ਸਲਾਟ ਬੁੱਕ ਕਰ ਸਕਦਾ ਹੈ — ਸਭ ਉਨ੍ਹਾਂ ਸਕੋਪਾਂ ਅੰਦਰ ਜੋ ਤੁਸੀਂ ਉਸ ਕੁੰਜੀ ਨੂੰ ਦਿੱਤੇ ਹਨ।
ਖਾਤੇ ਦੀ ਆਪਣੀ ਪ੍ਰੋਫਾਈਲ REST ਉੱਤੇ GET /v1/users/me ਨਾਲ ਪੜ੍ਹੀ ਜਾਂਦੀ ਹੈ, ਨਾ ਕਿ ਕਿਸੇ MCP ਟੂਲ ਰਾਹੀਂ।
ਇੱਕ AI ਏਜੰਟ ਨੂੰ ਸਿਰਫ਼ ਉਹੀ ਟੂਲ ਵਾਲੀ ਕੁੰਜੀ ਦਿਓ ਜਿਨ੍ਹਾਂ ਦੀ ਇਸ ਨੂੰ ਲੋੜ ਹੈ। ਜੇ ਇਸ ਨੂੰ ਸਿਰਫ਼ ਉਪਲਬਧਤਾ ਪੜ੍ਹਨ ਦੀ ਲੋੜ ਹੈ, ਤਾਂ ਇਸ ਨੂੰ ਰੱਦ ਕਰਨ ਜਾਂ ਮੁੜ-ਨਿਯਤ ਕਰਨ ਦੀਆਂ ਅਨੁਮਤੀਆਂ ਨਾ ਦਿਓ।
ਅਗਲੇ ਕਦਮ
- ਏਕੀਕਰਨ — ਦੋ-ਪਾਸੀ ਸਿੰਕ ਲਈ Google ਅਤੇ Outlook ਜੋੜੋ।
- ਇਵੈਂਟ ਕਿਸਮਾਂ — ਉਹ ਸਰੋਤ ਜਿਸ ਦੇ ਆਲੇ-ਦੁਆਲੇ ਤੁਹਾਡੀਆਂ ਜ਼ਿਆਦਾਤਰ API ਕਾਲਾਂ ਘੁੰਮਦੀਆਂ ਹਨ।
- ਤੁਹਾਡਾ ਜਨਤਕ ਬੁਕਿੰਗ ਪੰਨਾ — ਨੋ-ਕੋਡ ਮਾਰਗ ਜਿਸ ਨੂੰ ਤੁਹਾਡੇ ਸਵੈਚਾਲਨ ਪ੍ਰਤੀਬਿੰਬਤ ਕਰਦੇ ਹਨ।