API عمومی مُنشیوا v1

تماس‌ها، مشتریان، نوبت‌ها و پیگیری‌های شیوا را در نرم‌افزار خودتان بخوانید و بنویسید؛ سرنخ بفرستید تا شیوا همان لحظه تماس بگیرد؛ برای هر رویداد وب‌هوک امضاشده بگیرید.

https://monshiva.com/api/public/v1

شروع سریع

API عمومی مُنشیوا برای این است که سایت، فرم‌ها، CRM یا ابزار اتوماسیون شما (n8n، Make و مانند آن) مستقیماً با شیوا کار کنند: تماس‌ها و مشتریان را بخوانید، سرنخ ثبت کنید، نوبت‌ها و پیگیری‌ها را همگام کنید و برای هر رویداد وب‌هوک بگیرید.

فایل OpenAPI: مشخصات کامل همهٔ مسیرها در openapi.json؛ آن را در Postman، Insomnia یا ابزار ساخت کد خودتان وارد کنید.

  1. در پنل: تنظیمات و اشتراک ← API و وب‌هوک ← کلید تازه (فقط مالک/مدیر). کلید فقط یک بار نمایش داده می‌شود.
  2. هر درخواست را با هدر Authorization: Bearer msk_live_… بفرستید.
  3. آدرس پایه: https://monshiva.com/api/public/v1 — فقط HTTPS.
bashcurl https://monshiva.com/api/public/v1/me \
  -H "Authorization: Bearer msk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
json{
  "workspace": {"id": "8a75…", "name": "ویستا ویزا", "industry": "immigration", "branch": {"label": "شیراز · مرکزی", "organization": "گروه ویستا"}},
  "key": {"id": "key_1a2b3c", "name": "سایت", "scopes": ["read", "leads:write"]},
  "limits": {"per_minute": 60, "per_day": 5000}, "version": "v1", "time": "2026-11-08T14:05:12+03:30"
}

احراز هویت و دسترسی‌ها

هر کلید فقط به یک فضای کار دسترسی دارد و در سرور به‌صورت هش (SHA-256) نگه داشته می‌شود. دسترسی‌ها (scope) هنگام ساخت کلید انتخاب می‌شوند:

scopeاجازه می‌دهد
readخواندن تماس‌ها، مشتریان، نوبت‌ها، زمان‌های آزاد و پیگیری‌ها (پیش‌فرض، همیشه هست)
leads:writeثبت سرنخ تازه (و درخواست تماس فوری شیوا)
bookings:writeثبت نوبت برای یک تماس، جابه‌جایی و لغو نوبت
tasks:writeثبت پیگیری برای یک مشتری
contacts:phoneنمایش شمارهٔ کامل مشتری (بدون آن شماره‌ها ماسک می‌شوند: 0912***4567)
webhooks:manageساخت/حذف/آزمایش وب‌هوک از طریق API

کلید لو رفته را همان لحظه از پنل لغو کنید؛ «آخرین استفاده» هر کلید در پنل دیده می‌شود.

محدودیت‌ها، خطاها و Idempotency

  • نرخ: ۶۰ درخواست در دقیقه و ۵٬۰۰۰ در روز برای هر کلید؛ بیش از آن 429 با هدر Retry-After.
  • زمان‌ها: ISO-8601 به وقت تهران (+03:30). تاریخ‌ها میلادی YYYY-MM-DD.
  • صفحه‌بندی: ?page= از ۱؛ هر صفحه ۲۰ تا ۲۵ مورد؛ در فهرست تماس‌ها has_more می‌گوید صفحهٔ بعدی هست یا نه.
  • Idempotency: روی POST /leads و POST /tasks هدر Idempotency-Key: <شناسهٔ یکتای شما> بفرستید؛ تکرار همان درخواست تا ۲۴ ساعت همان پاسخ را برمی‌گرداند و رکورد تکراری نمی‌سازد.

همهٔ خطاها یک شکل دارند:

json{"error": {"code": "validation_error", "message": "شمارهٔ موبایل ایرانی معتبر (09…) لازم است.", "field": "mobile"}}
کد HTTPcodeمعنی
400bad_requestبدنهٔ JSON خراب است
401unauthorizedکلید نیست، نامعتبر یا لغو شده
403insufficient_scope / crm_unavailableکلید این دسترسی را ندارد / CRM فضا فعال نیست
404not_foundرکورد پیدا نشد
409limitسقف تعداد (کلید/وب‌هوک)
422validation_errorفیلد نامعتبر (در field آمده)
429rate_limitedمحدودیت نرخ
503upstream_unavailableموتور مکالمه یا CRM لحظه‌ای در دسترس نیست؛ کمی بعد دوباره بفرستید

تماس‌ها

GET /calls?page=1&status=all|completed|incomplete — تماس‌ها و گفتگوهای واقعی مشتریان (جدیدترین اول). GET /calls/{id} جزئیات یک تماس.

json{
  "calls": [{
    "id": 438, "created": "2026-11-07T20:34:45+03:30", "completed": true, "state": "completed",
    "channel": "phone",            // phone | web | chat
    "direction": "outbound",       // inbound | outbound
    "customer": {"name": "ستار غیرتمند", "phone": "0933***9003"},
    "summary": "درخواست مشاورهٔ مهاجرت تحصیلی…", "requested_service": "مشاوره تحصیلی",
    "booking": {"id": "VV-1100BE7AEC", "status": "confirmed"},   // یا null
    "callback_requested": false, "recording_available": true, "transcript_available": true
  }],
  "page": 1, "limit": 20, "has_more": true
}

در نسخهٔ ۱ فایل صوت و متن کامل از طریق API داده نمی‌شود (پنل و ضبط با رضایت)؛ فقط «در دسترس بودن» آن‌ها اعلام می‌شود.

مشتریان

GET /contacts?q=&page=&stage= — مشتریان CRM فضا (۲۵ در هر صفحه). GET /contacts/{id} پروندهٔ یک مشتری با تماس‌ها، نوبت‌ها و پیگیری‌ها.

json{"contacts": [{"id": "o000000035", "name": "ستار غیرتمند", "phone": "0912***1203", "verified": true, "stage": "new", "created": "2026-11-06T05:08:08+03:30"}],
 "page": 1, "limit": 25, "total": 86, "stages": {"new": "متقاضی جدید", "qualified": "بررسی اولیه", "...": "..."}}

نوبت‌ها و زمان‌های آزاد

GET /bookings?date_from=&date_to=&status= — نوبت‌های ثبت‌شده. GET /availability?date=YYYY-MM-DD&advisor_id=default — زمان‌های آزاد همان روز طبق برنامهٔ کاری فضا.

json{"bookings": [{"id": "VV-1100BE7AEC", "call_id": 187, "date": "2026-11-07", "time": "11:30", "customer": "ستار غیرتمند",
   "service": "مشاوره مهاجرت به کانادا", "status": "confirmed", "revision": 1, "advisor_id": "default"}], "timezone": "Asia/Tehran", "duration_minutes": 30}

ثبت نوبت (bookings:write): POST /bookings با {"call_id": 438, "date": "2026-11-12", "time": "10:30", "service": "…"} — در نسخهٔ ۱ نوبت به یک تماس تکمیل‌شدهٔ مشتری (call_id) وصل می‌شود تا هویت و شمارهٔ تأییدشدهٔ او از همان تماس بیاید. جابه‌جایی/لغو: PATCH /bookings/{id} با {"operation": "reschedule", "date": "…", "time": "…", "revision": 1} یا {"operation": "cancel", "reason": "…", "revision": 1}؛ revision همان مقدار فعلی نوبت است (قفل خوش‌بینانه). پیامک تأیید/تغییر مثل پنل از خط خود شما می‌رود.

پیگیری‌ها

GET /tasks?status=open|completed|all&page= — پیگیری‌های ثبت‌شده روی پرونده‌ها. ثبت پیگیری (tasks:write): POST /tasks

json{"contact_id": "o000000035", "title": "تماس برای ارسال مدارک", "note": "مدارک تحصیلی را بخواهید", "due": "2026-11-12T10:00:00", "assignee": "office"}

due به وقت تهران و در آینده؛ assignee اختیاری (شناسهٔ همکار از پنل؛ پیش‌فرض همکار مسئول دفتر).

سرنخ‌ها و تماس فوری شیوا

POST /leads (leads:write) — فرم سایت، کمپین یا هر منبع دیگر را به یک سرنخ در CRM فضا تبدیل می‌کند؛ با "call_now": true شیوا در ساعت کاری (۸ تا ۲۱:۳۰ تهران) با مشتری تماس می‌گیرد و نتیجه به همان پرونده می‌رود (Speed-to-Lead). تماس فوری فقط برای فضاهایی فعال است که خط خروجی دارند؛ وگرنه call_now.queued=false با reason برمی‌گردد.

bashcurl -X POST https://monshiva.com/api/public/v1/leads \
  -H "Authorization: Bearer msk_live_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-2026-11-08-1234" \
  -d '{"name": "مریم احمدی", "mobile": "09121234567", "source": "site-form", "note": "مشاورهٔ ویزای تحصیلی کانادا", "call_now": true}'
json{"lead": {"id": "odoo:41", "name": "مریم احمدی", "mobile": "0912***4567", "source": "site-form", "duplicate": false, "created": "2026-11-08T14:10:03+03:30"},
 "call_now": {"queued": true, "reason": null, "window": "08:00–21:30 Asia/Tehran"}}

دریافت فرم از هر فرم‌ساز (پرس‌لاین، فرمالو، Google Forms و …)

POST /forms/inbound (leads:write) — نشانی وب‌هوکی است که در تنظیمات فرم‌ساز می‌گذارید. بدنه هر شکلی داشته باشد (JSON یا فرم معمولی، تخت یا تو در تو، یا فهرست «پرسش/پاسخ»)، شمارهٔ موبایل ایرانی، نام و ایمیل خودکار پیدا می‌شوند و همهٔ پاسخ‌ها در یادداشت سرنخ می‌آیند؛ نقشه‌کشی فیلد لازم نیست. همان پاسخ اگر دوباره فرستاده شود، سرنخ تکراری نمی‌سازد (duplicate: true).

  • احراز هویت: سرآیند Authorization: Bearer msk_live_…؛ اگر فرم‌ساز سرآیند نمی‌پذیرد، ?key=msk_live_… در نشانی (برای این کار یک کلید جدا با فقط دسترسی «ثبت سرنخ» بسازید تا هر وقت خواستید باطلش کنید).
  • پارامترهای اختیاری نشانی: source=porsline (برچسب منبع در CRM) و call_now=1 (تماس فوری شیوا، در فضاهایی که خط خروجی دارند).
  • اگر در پاسخ شمارهٔ موبایل نباشد: 422 validation_error با field: "mobile"؛ یک پرسش «شمارهٔ موبایل» به فرم اضافه کنید.
bashcurl -X POST "https://monshiva.com/api/public/v1/forms/inbound?source=porsline"   -H "Authorization: Bearer msk_live_…" -H "Content-Type: application/json"   -d '{"answers": [{"question": "نام و نام خانوادگی", "answer": "مریم احمدی"}, {"question": "شمارهٔ موبایل", "answer": "۰۹۱۲۱۲۳۴۵۶۷"}, {"question": "خدمت مورد نظر", "answer": "ایمپلنت"}]}'
json{"lead": {"id": "odoo:52", "name": "مریم احمدی", "mobile": "0912***4567", "source": "porsline", "duplicate": false, "created": "2026-11-18T13:12:44+03:30"},
 "call_now": {"queued": false, "reason": null, "window": "08:00–21:30 Asia/Tehran"}}

راهنمای قدم‌به‌قدم پرس‌لاین و فرم‌سازهای دیگر: اتصال‌ها و افزونه‌ها.

اتصال سایت و افزونهٔ وردپرس

POST /sites (leads:write) — یک سایت را به فضای شما وصل می‌کند: دامنه و نسخهٔ www آن به فهرست مجاز دستیار صوتی و چت اضافه می‌شود و نشانی اسکریپت دستیار برمی‌گردد. افزونهٔ وردپرس منشیوا هنگام اتصال همین را صدا می‌زند؛ برای سایت‌های غیروردپرسی هم کار می‌کند. فراخوانی دوباره بی‌خطر است: همان توکن برمی‌گردد و فقط زمان آخرین اتصال به‌روز می‌شود.

bashcurl -X POST https://monshiva.com/api/public/v1/sites \
  -H "Authorization: Bearer msk_live_…" -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "platform": "wordpress", "version": "1.2.1"}'
json{"site": {"domain": "example.com", "platform": "wordpress"},
 "widget": {"token": "emb_…", "script": "https://monshiva.com/widget/monshiva-widget.js?token=emb_…", "type": "voice"},
 "outbound_calls": false, "business": {"name": "کلینیک لبخند"}}

برای نصب دستیار، این خط را پیش از </body> بگذارید:

html<script src="{widget.script}" defer></script>

outbound_calls نشان می‌دهد call_now در این فضا تماس می‌گیرد یا نه. دامنهٔ نامعتبر: 422 validation_error با field: "domain".

کاربران وردپرس به کد نیازی ندارند: افزونهٔ وردپرس منشیوا اتصال، فرم «یک دقیقه‌ای با شما تماس می‌گیریم» و ورود فرم‌های Contact Form 7، WPForms، Gravity، المنتور، Ninja و Fluent و سفارش‌های ووکامرس به CRM را خودش انجام می‌دهد.

بیعانهٔ نوبت

اگر کسب‌وکار «بیعانهٔ نوبت» را در پنل فعال کرده باشد (تنظیمات ← بیعانهٔ نوبت؛ با درگاه و حساب خودِ کسب‌وکار — زرین‌پال یا آقای پرداخت)، برای هر نوبت تأییدشده یک لینک پرداخت یک‌بارمصرف ساخته می‌شود: https://monshiva.com/pay/<token>. مشتری در درگاه پرداخت می‌کند، منشیوا نتیجه را سمت سرور تأیید می‌کند و وضعیت را نگه می‌دارد؛ پولی نزد منشیوا نمی‌ماند.

GET /deposits?booking_id=&status=&page= — فهرست بیعانه‌ها (جدیدترین اول). هر نوبت در GET /bookings هم فیلد deposit دارد (یا null).

json{"deposits": [{"token": "k3Jf…", "booking_id": "VV-1100BE7AEC", "call_id": 187, "amount": 500000, "currency": "IRT", "gateway": "zarinpal",
   "state": "paid", "state_label": "پرداخت شد", "pay_url": null, "customer": {"name": "ستار غیرتمند", "phone": "0912***1203"},
   "service": "مشاوره", "date": "2026-11-12", "time": "10:30", "ref_id": "123456789", "sms_status": "awaiting_template",
   "created": "2026-11-08T18:40:00+03:30", "expires": "2026-11-09T18:40:00+03:30", "paid_at": "2026-11-08T19:02:11+03:30"}],
 "page": 1, "limit": 20, "has_more": false, "enabled": true, "amount": 500000}
stateیعنی
pendingلینک ساخته شده، پرداخت شروع نشده
ready / verifyingمشتری در درگاه است / در حال تأیید
paidتأیید شد (ref_id کد پیگیری درگاه)
reviewنتیجهٔ درگاه نامعلوم ماند؛ از پنل «بررسی مجدد» بزنید
expiredمهلت تمام شد (پیش‌فرض ۲۴ ساعت و همیشه پیش از ساعت نوبت)
cancelledنوبت لغو شد
waivedهمکار «حضوری/معاف» زد

لینک پرداخت را خودتان هم می‌توانید به مشتری برسانید (پیامک، پیام‌رسان، سایت): از رویداد deposit.created یا همین فهرست. پیامک خودکار منشیوا پس از تأیید الگوی اپراتور فعال می‌شود (sms_status).

وب‌هوک‌ها

برای هر رویداد، یک POST با بدنهٔ JSON به آدرس https شما فرستاده می‌شود. وب‌هوک را از پنل (API و وب‌هوک ← وب‌هوک تازه) یا با POST /webhooks بسازید؛ secret فقط یک بار نمایش داده می‌شود.

رویدادکی
call.completedپایان هر تماس/گفتگوی مشتری (همان شکل /calls)
booking.createdثبت نوبت در تماس یا از API
callback.createdمشتری درخواست تماس/پیگیری گذاشته
lead.createdسرنخ تازه از API
task.createdپیگیری تازه از API
deposit.createdلینک بیعانه برای یک نوبت ساخته شد (data.deposit.pay_url)
deposit.paidبیعانه پرداخت و تأیید شد
deposit.expiredمهلت بیعانه تمام شد
webhook.testدکمهٔ «آزمایش»
json{"id": "evt_6f1c…", "type": "call.completed", "created": "2026-11-08T14:12:40+03:30", "workspace": "8a75…", "branch": null,
 "data": {"call": {"id": 441, "channel": "phone", "customer": {"name": "…", "phone": "0912***4567"}, "summary": "…", "booking": null, "callback_requested": true}}}

مدیریت وب‌هوک‌ها با API (نیاز به scope webhooks:manage):

مسیرکار
GET /webhooksفهرست وب‌هوک‌های فضای کار + فهرست رویدادهای مجاز (events)
POST /webhooksساخت: {{"url": "https://…", "events": ["call.completed", …]}} → پاسخ شامل secret (فقط همین یک بار)
DELETE /webhooks/{{id}}حذف وب‌هوک
POST /webhooks/{{id}}/testارسال یک رویداد آزمایشی ping به آدرس شما و برگرداندن نتیجهٔ تحویل
GET /webhooks/{{id}}/deliveriesآخرین تحویل‌ها (وضعیت HTTP، زمان، تلاش مجدد) برای عیب‌یابی

امضا و تلاش مجدد. هدر X-Monshiva-Signature: t=<unix>,v1=<hex> که در آن v1 = HMAC-SHA256(secret, t + "." + body). فقط درخواست‌هایی را بپذیرید که امضا درست است و t کمتر از ۵ دقیقه با زمان حال فاصله دارد. پاسخ 2xx یعنی تحویل شد؛ در غیر این صورت ۱، ۵، ۳۰، ۱۸۰ و ۷۲۰ دقیقه بعد دوباره تلاش می‌شود و پس از ۵ شکست پیاپی وب‌هوک معلق می‌شود (در پنل با «تحویل‌ها» ببینید و دوباره بسازید). ترتیب تضمین نمی‌شود؛ با id رویداد تکراری‌زدایی کنید.

pythonimport hmac, hashlib, time
def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    if abs(time.time() - int(parts['t'])) > 300: return False
    expected = hmac.new(secret.encode(), (parts['t'] + '.').encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts['v1'])
javascript// Node.js (Express): app.post('/monshiva-hook', express.raw({type: 'application/json'}), (req, res) => { ... })
const crypto = require('crypto');
function verify(secret, header, rawBody) {
  const p = Object.fromEntries(header.split(',').map(x => x.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const v1 = crypto.createHmac('sha256', secret).update(p.t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(p.v1));
}
php<?php // WordPress / PHP
$raw = file_get_contents('php://input');
$parts = []; parse_str(str_replace(',', '&', $_SERVER['HTTP_X_MONSHIVA_SIGNATURE']), $parts);
$ok = abs(time() - (int)$parts['t']) <= 300 && hash_equals(hash_hmac('sha256', $parts['t'] . '.' . $raw, $secret), $parts['v1']);
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($raw, true);  // $event['type'], $event['data']
http_response_code(200);

نمونهٔ n8n

قالب‌های آماده: فایل را بگیرید و در n8n از منوی گردش‌کار «Import from File» را بزنید؛ راهنمای هر قالب روی یادداشت داخل خودش است.

گرفتن رویدادها: یک گرهٔ Webhook (POST) بسازید، آدرس Production آن را در پنل منشیوا ثبت کنید و در گرهٔ بعدی (Code) امضا را با کد بالا بررسی کنید. خواندن یا نوشتن: گرهٔ HTTP Request با Authentication = Header Auth (نام Authorization، مقدار Bearer msk_live_…).

json{"method": "POST", "url": "https://monshiva.com/api/public/v1/leads",
 "sendHeaders": true, "headerParameters": {"parameters": [{"name": "Idempotency-Key", "value": "={{ $json.form_id }}"}]},
 "sendBody": true, "specifyBody": "json",
 "jsonBody": "={{ {\"name\": $json.name, \"mobile\": $json.phone, \"source\": \"site-form\", \"call_now\": true} }}"}

جریان پیشنهادی: فرم سایت ← n8n ← POST /leads (call_now) ← شیوا تماس می‌گیرد ← call.completed به n8n ← پیام به تلگرام/ایمیل تیم فروش.

تغییرات

  • مستندات — ۱ آذر ۱۴۰۵ (۲۲ نوامبر ۲۰۲۶): فایل openapi.json (OpenAPI 3) و سه قالب آمادهٔ n8n.
  • v1 — ۱۸ آبان ۱۴۰۵ (۸ نوامبر ۲۰۲۶): انتشار اول: کلیدهای tenant-scoped، تماس‌ها، مشتریان، نوبت‌ها/زمان‌های آزاد، پیگیری‌ها، سرنخ + تماس فوری، وب‌هوک با امضای HMAC و تلاش مجدد.
  • v1.1 — ۱۸ آبان ۱۴۰۵ (۸ نوامبر ۲۰۲۶، عصر): بیعانهٔ نوبت: GET /deposits، فیلد deposit روی نوبت‌ها، رویدادهای deposit.created / deposit.paid / deposit.expired.
  • v1.2 — ۱۸ آبان ۱۴۰۵ (۸ نوامبر ۲۰۲۶، شب): چندشعبه: فیلد branch (برچسب شعبه و نام سازمان، یا null) در GET /me و در بدنهٔ همهٔ رویدادهای وب‌هوک. کلید هر شعبه جداست؛ کلید سازمانی در نسخهٔ بعد.
  • مستندات (۸ نوامبر، شب): جدول مدیریت وب‌هوک با API (GET/POST /webhooks، DELETE، /test، /deliveries) اضافه شد؛ رفتار API تغییری نکرده است.
  • v1.3 — ۲۴ آبان ۱۴۰۵ (۱۵ نوامبر ۲۰۲۶): اتصال سایت: POST /sites (مجازکردن دامنه برای دستیار + اسکریپت نصب)؛ پایهٔ افزونهٔ وردپرس منشیوا.
  • v1.4 — ۲۷ آبان ۱۴۰۵ (۱۸ نوامبر ۲۰۲۶): POST /forms/inbound برای وب‌هوک هر فرم‌ساز (پرس‌لاین، فرمالو، Google Forms…) بدون نقشه‌کشی فیلد.
  • در راه: ارسال پیامک/پیام الگودار (messages:send)، ثبت نوبت بدون تماس قبلی، دسترسی به فایل صوت/متن با قرارداد (calls:media).

فیلد تازه اضافه می‌شود، حذف نمی‌شود؛ هر تغییر ناسازگار نسخهٔ جدید (v2) خواهد داشت.