راهنمای توسعه‌دهندگان: API، وب‌هوک و فرم سایت

مدیر میزکار (مالک یا ادمین) از منوی «اتصال‌ها و API» در میزکار کلید می‌سازد. کلید فقط یک بار نمایش داده می‌شود و ما فقط اثر SHA-256 آن را نگه می‌داریم؛ اگر گم شد، کلید تازه بسازید و قبلی را باطل کنید. هر کلید فقط به دادهٔ همان میزکار دسترسی دارد و رکوردهایی که با آن ساخته می‌شوند به نام سازندهٔ کلید ثبت می‌شوند.

curl https://raybancrm.ir/api/v1/me \
  -H "Authorization: Bearer rbk_XXXXXXXXXXXXXXXX"

سقف درخواست: ۱۲۰ درخواست در دقیقه برای هر کلید. پاسخ هدرهای X-RateLimit-Limit و X-RateLimit-Remaining دارد و در صورت عبور از سقف، کد 429 با هدر Retry-After برمی‌گردد.

• GET /api/v1/customers?limit=50&offset=0&phone=0912…
• POST /api/v1/customers (?upsert=phone)
• GET · PATCH /api/v1/customers/:id
• GET /api/v1/deals?customerId=…&stage=…
• POST /api/v1/deals · GET · PATCH /api/v1/deals/:id
• GET /api/v1/quotes?customerId=…&status=…
• POST /api/v1/quotes · GET · PATCH /api/v1/quotes/:id

فهرست‌ها به ترتیب جدیدترین برمی‌گردند و حداکثر ۱۰۰ ردیف در هر صفحه دارند (paging.total تعداد کل است). مبالغ به تومان و تاریخ‌ها در API به شکل میلادی YYYY-MM-DD هستند (میزکار همان تاریخ‌ها را شمسی نشان می‌دهد). حذف از راه API پشتیبانی نمی‌شود.

curl -X POST "https://raybancrm.ir/api/v1/customers?upsert=phone" \
  -H "Authorization: Bearer rbk_…" -H "Content-Type: application/json" \
  -d '{"name":"سارا محمدی","phone":"09121234567","company":"نوآوران","source":"site","tags":["ووکامرس"]}'

فیلدها: name (الزامی)، phone، company، note، source(یکی از intro, instagram, site, call, visit) و tags (حداکثر ۸). شماره در هر میزکار یکتا در نظر گرفته می‌شود: بدون upsert=phone شمارهٔ تکراری خطای 409 duplicate_phone می‌دهد و با آن، همان مشتری موجود برمی‌گردد (created: false). ارقام فارسی و پیش‌شمارهٔ ‎+98 پذیرفته می‌شوند. PATCH فقط فیلدهای ارسال‌شده را تغییر می‌دهد.

curl -X POST https://raybancrm.ir/api/v1/deals -H "Authorization: Bearer rbk_…" -H "Content-Type: application/json" \
  -d '{"customerId":"…","title":"سفارش ۱۰۴۲","amount":4500000,"stage":"contact","expectOn":"2026-11-01"}'

مرحله‌ها: contact, proposal, negotiation, won, lost (برای lost می‌توانید lossReason بفرستید). با PATCH عنوان، مبلغ، تاریخ پیش‌بینی و مرحله قابل تغییر است؛ مشتریِ فرصت از راه API عوض نمی‌شود.

curl -X POST https://raybancrm.ir/api/v1/quotes -H "Authorization: Bearer rbk_…" -H "Content-Type: application/json" \
  -d '{"customerId":"…","dealId":"…","title":"پیش‌فاکتور نصب","taxRate":10,
       "lines":[{"title":"نصب و راه‌اندازی","qty":1,"unitPrice":3000000,"discount":0}]}'

شمارهٔ پیش‌فاکتور اگر خالی باشد مثل میزکار خودکار ساخته می‌شود. ردیف‌ها عنوان آزاد دارند (اتصال به کاتالوگ محصول از راه API فعلاً پشتیبانی نمی‌شود). با PATCH می‌توانید پیش‌فاکتورِ پیش‌نویس یا ارسال‌شده را ویرایش کنید یا status را به sent، accepted یا void ببرید. پاسخ شامل totals (جمع، مالیات، مبلغ نهایی) است.

{ "error": { "code": "validation_failed", "message": "نام مشتری لازم است…", "field": "name" } }

401 unauthorized · 403 forbidden · 404 not_found · 409 duplicate_phone / duplicate_number / locked / invalid_transition · 413 too_large · 422 validation_failed · 429 rate_limited

در «اتصال‌ها و API» آدرس https خود را ثبت و رویدادها را انتخاب کنید: customer.created, customer.updated, deal.created, deal.updated, quote.created, quote.updated. ورود گروهی از اکسل وب‌هوک نمی‌فرستد. بدنهٔ هر درخواست:

POST https://your-site.example/hook
X-Rayban-Event: deal.updated
X-Rayban-Delivery: evt_…
X-Rayban-Signature: t=1760950000,v1=<hex HMAC-SHA256(secret, t + "." + body)>

{ "id": "evt_…", "event": "deal.updated", "createdAt": "…", "workspaceId": "…", "data": { …deal… } }

بررسی امضا در PHP یا Node:

// PHP
[$t, $v1] = sscanf($_SERVER['HTTP_X_RAYBAN_SIGNATURE'], 't=%d,v1=%s');
$ok = hash_equals(hash_hmac('sha256', $t . '.' . file_get_contents('php://input'), $secret), $v1)
      && abs(time() - $t) < 300;

// Node
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const ok = crypto.timingSafeEqual(
  Buffer.from(crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex")),
  Buffer.from(v1));

هر پاسخ 2xx یعنی تحویل موفق. در غیر این صورت ۵ بار دیگر تلاش می‌کنیم: پس از ۱ دقیقه، ۵ دقیقه، ۳۰ دقیقه، ۲ ساعت و ۶ ساعت. مهلت هر درخواست ۱۰ ثانیه است و ریدایرکت دنبال نمی‌شود. گزارش ارسال‌ها در همان صفحه دیده می‌شود. برای امنیت، آدرس‌هایی که به IP خصوصی، localhost یا شبکهٔ داخلی می‌رسند (حتی از راه DNS) مسدود می‌شوند. ممکن است یک رویداد بیش از یک بار برسد؛ با X-Rayban-Delivery تکرار را تشخیص دهید.

در «اتصال‌ها و API» یک فرم بسازید تا آدرس و کد HTML آماده بگیرید. فرم را می‌توانید با JSON یا ارسال عادی فرم HTML بفرستید و نیازی به کلید API ندارد:

curl -X POST https://raybancrm.ir/api/leads/lf_XXXXXXXX \
  -H "Content-Type: application/json" \
  -d '{"name":"علی رضایی","phone":"09351234567","email":"ali@example.com","message":"قیمت نسخهٔ تیمی؟"}'

هر سرنخ تازه مشتری‌ای با منبع «سایت» و برچسب «فرم سایت» می‌سازد (و اگر در تنظیم فرم خواسته باشید، فرصت فروش در مرحلهٔ تماس اول). اگر شماره در میزکار وجود داشته باشد مشتری تکراری ساخته نمی‌شود و درخواست به‌صورت یادداشت روی همان مشتری ثبت می‌شود. ضداسپم: فیلد پنهان website (اگر پر شود چیزی ذخیره نمی‌شود) و حداکثر ۵ ارسال در دقیقه برای هر IP.

افزونهٔ رایبان را از صفحهٔ «اتصال‌ها و API» دانلود و در وردپرس از «افزونه‌ها ← افزودن ← بارگذاری» نصب کنید. در «تنظیمات ← رایبان CRM» کلید API را وارد کنید. پس از آن:

• هر سفارش تازهٔ ووکامرس: مشتری (بر اساس شمارهٔ صورت‌حساب، بدون تکرار) و یک فرصت فروش با مبلغ سفارش. مبلغ ریالی خودکار به تومان تبدیل می‌شود.
• هر مشتری تازهٔ ووکامرس که شماره دارد: مشتری در رایبان.
• اگر شناسهٔ فرم سرنخ را وارد کنید: ارسال‌های Contact Form 7 (فیلدهای name/phone/email/message یا your-name/your-phone/…) به همان فرم سرنخ.

در «اتصال‌ها و API» آدرس دریافت تماس بسازید. مرکز تلفن پس از هر تماس یک درخواست POST با JSON می‌فرستد؛ تماس با شمارهٔ مشتری (برای تماس ورودی شمارهٔ تماس‌گیرنده و برای خروجی شمارهٔ مقصد) تطبیق داده و روی پرونده ثبت می‌شود. تماس با شمارهٔ ناشناس هم در فهرست تماس‌های میزکار می‌ماند. با callId تکراری چیزی دوباره ثبت نمی‌شود.

curl -X POST https://raybancrm.ir/api/voip/vp_XXXXXXXX \
  -H "Content-Type: application/json" -H "X-Rayban-Token: vps_…" \
  -d '{"direction":"in","from":"09121234567","to":"02112345678","status":"answered",
       "duration":95,"startedAt":"2026-10-20T08:15:00Z","callId":"pbx-123","extension":"101"}'

direction: in یا out · status: answered، missed، no-answer، busy، failed · مدت به ثانیه. به‌جای توکن می‌توانید امضای X-Rayban-Signature را مثل وب‌هوک‌ها با همان راز بسازید.

پنل پیامک sms.ir یا کاوه‌نگار را مدیر میزکار در «اتصال‌ها و API» وصل می‌کند (کلید رمزنگاری‌شده ذخیره می‌شود و دوباره نمایش داده نمی‌شود). ارسال دستی به مشتری، لینک امن مشاهدهٔ پیش‌فاکتور و فاکتور، و یادآوری پیگیری‌های روز به کارشناس از همان‌جا انجام می‌شود و همه در گزارش پیامک ثبت می‌شوند.

در «ورود و خروجی» دو خروجی CSV عمومی برای نرم‌افزار حسابداری هست: فاکتورها و پرداخت‌ها، با سرستون‌های انگلیسی، تاریخ میلادی و شمسی کنار هم و مبلغ به تومان (currency=IRT). اتصال مستقیم به نرم‌افزار حسابداری خاصی وجود ندارد.