API و وب‌هوک (بتا): پلن حرفه‌ای و سازمانی
مستندات API رشتا
سایت اختصاصی، ERP یا نرم‌افزار حسابداری‌تان را به رشتا وصل کنید: مخاطب و معامله بسازید، سفارش ثبت کنید و با وب‌هوک از هر تغییر باخبر شوید. REST و JSON، با یک کلید.
- ۱ساخت کلید API در رشتااتصال ← توسعه‌دهنده
- ۲اولین درخواستسامانهٔ شما به رشتا
curl -H "Authorization: Bearer …" …/contacts - ۳دریافت وب‌هوکرشتا به سامانهٔ شماPOST deal.won
رشتابا API رشتا چه می‌سازید؟
همگام‌سازی سایت اختصاصی یا ERPمخاطب، شرکت و معامله را از سامانهٔ خودتان در رشتا بسازید و به‌روز نگه دارید.POST /contacts
سرنخ از فرم و صفحهٔ فرود خودتانهر فرمی که خارج از رشتا ساخته‌اید، مخاطب و معامله را مستقیم در رشتا می‌سازد.POST /deals
سفارش از سامانهٔ فروشسفارش‌هایی که از ووکامرس یا بازارها نمی‌آیند، به پروندهٔ همان مشتری می‌رسند.POST /orders
واکنش به رویدادهاوقتی معامله برنده شد یا سفارش ثبت شد، وب‌هوک امضاشده سامانهٔ شما را خبر می‌کند.deal.won
آدرس پایه
همهٔ درخواست‌ها با HTTPS به این آدرس می‌روند. بدنه‌ها JSON با UTF-8 است، زمان‌ها ISO 8601 به وقت UTC و مبلغ‌ها عدد صحیح به ریال.
آدرس پایه
URL
https://app.reshta.ir/api/v1/publicاحراز هویت با کلید API
هر درخواست باید سرآیند Authorization را با کلید API کسب‌وکار داشته باشد. کلید را مدیر کسب‌وکار در اپ رشتا می‌سازد:
- ۱با حساب مدیر وارد app.reshta.ir شوید؛ ایمیل حساب باید تأییدشده باشد.
- ۲از منوی کناری «اتصال» و بعد «توسعه‌دهنده» را باز کنید.
- ۳«ساخت کلید API»: یک نام بدهید و دسترسی را انتخاب کنید: «خواندن» یا «خواندن و نوشتن».
- ۴کلید را همان لحظه کپی کنید و در جای امن (متغیر محیطی سرور) نگه دارید.
سرآیند احراز هویت
HTTP
Authorization: Bearer rk_live_…- کلید به نام همکاری که آن را ساخته کار می‌کند؛ اگر کلید باطل شود یا حساب سازنده غیرفعال شود، پاسخ 401 است.
- کلید «خواندن» روی درخواست نوشتنی پاسخ 403 می‌گیرد.
- کلید را هرگز در کد مرورگر یا اپ موبایل نگذارید؛ فقط از سرور خودتان درخواست بفرستید.
محدودیت نرخ
۱۲۰درخواست در دقیقهبرای هر کلید. بیشتر از آن پاسخ 429 با کد rate_limited می‌گیرد؛ سرآیند Retry-After می‌گوید چند ثانیه صبر کنید.
۳۰تلاش ناموفق در دقیقهدرخواست با کلید نادرست برای هر IP محدود است تا حدس زدن کلید ممکن نباشد.
۲۴ ساعتتلاش دوبارهٔ وب‌هوکتحویل ناموفق وب‌هوک تا حدود ۲۴ ساعت دوباره فرستاده می‌شود.
یکتایی درخواست (Idempotency)
هر درخواست نوشتنی (POST و PATCH) باید سرآیند Idempotency-Key داشته باشد: یک شناسهٔ تازه برای هر عملیات، مثلاً UUID، تا ۲۵۵ نویسه. اگر همان درخواست دوباره برسد، مثلاً بعد از قطع شبکه، رشتا همان پاسخ اول را برمی‌گرداند و چیزی دوبار ساخته نمی‌شود.
درخواست نوشتنی
POST /ordersAuthorization: Bearer rk_live_…Idempotency-Key: 7f3c2b1e-4a5d-4c6f-9e1a-2b3c4d5e6f70Content-Type: application/jsonهمان کلید، همان بدنهپاسخ اول دوباره برمی‌گردد، با سرآیند Idempotency-Replayed؛ چیزی تکرار نمی‌شود.
همان کلید، بدنهٔ دیگرپاسخ 409 با کد conflict. اگر درخواست اول هنوز در جریان باشد هم 409.
بدون سرآیندپاسخ 400 با کد validation_error. هر کلید ۲۴ ساعت نگه داشته می‌شود.
خطاها
همهٔ خطاها یک شکل دارند: یک code ثابت که برنامهٔ شما می‌تواند رویش تصمیم بگیرد، یک message برای انسان و details؛ در خطای اعتبارسنجی، details نام فیلد را دارد.
شکل همهٔ خطاها
JSON
{ "error": { "code": "validation_error", "message": "Invalid request", "details": [ { "field": "emails.0.email", "message": "Invalid email address" } ] }}validation_error400بدنه، پارامتر یا سرآیند نادرست است؛ details می‌گوید کدام فیلد.
unauthorized401کلید نیست، نادرست یا باطل است، یا سازنده‌اش غیرفعال است.
plan_limit_reached402به سقف پلن کسب‌وکار رسیده‌اید.
forbidden403کلید دسترسی نوشتن ندارد یا این کار برای سازنده‌اش مجاز نیست.
not_found404رکورد در این کسب‌وکار پیدا نشد.
conflict409همان Idempotency-Key با بدنهٔ دیگر یا هنوز در جریان.
rate_limited429از سقف ۱۲۰ درخواست در دقیقه گذشتید؛ Retry-After را ببینید.
internal500خطای رشتا؛ کمی بعد دوباره بفرستید.
provider_error502سرویس بیرونی، مثلاً پیامک، خطا داد.
صفحه‌بندی
فهرست‌ها با cursor صفحه‌بندی می‌شوند، نه با شمارهٔ صفحه. هر پاسخ data و next_cursor دارد؛ next_cursor را در درخواست بعدی بفرستید. وقتی next_cursor برابر null است، به آخر رسیده‌اید. اندازهٔ پیش‌فرض صفحه ۵۰ و بیشینه ۱۰۰ است.
صفحهٔ بعد
HTTP
GET /contacts?limit=50&cursor=eyJpZCI6IjAxOTJjNGU4In0{ "data": [ … ], "next_cursor": "eyJpZCI6IjAxOTJjNGY5In0"}نسخه‌بندی
در همین v1 اضافه می‌شودفیلد، endpoint و رویداد تازه. کد شما باید فیلدهای ناشناخته را نادیده بگیرد.
تغییر ناسازگار ← v2حذف یا تغییر معنای یک فیلد فقط در /api/v2 می‌آید و از قبل در «تغییرات» اعلام می‌شود.
شروع سریع
- ۱کلید «خواندن و نوشتن» بسازید
- ۲آن را در RESHTA_API_KEY بگذارید
- ۳اولین مخاطب را بسازید
ساخت اولین مخاطب
curl https://app.reshta.ir/api/v1/public/contacts \ -X POST \ -H "Authorization: Bearer $RESHTA_API_KEY" \ -H "Idempotency-Key: 7f3c2b1e-4a5d-4c6f-9e1a-2b3c4d5e6f70" \ -H "Content-Type: application/json" \ -d '{"first_name":"سارا","last_name":"رضایی","phones":[{"phone":"09121234567","is_primary":true}]}'پاسخ
{ "id": "0192c4e8-7b1a-7c3e-9f20-5d6a1b2c3d4e", "first_name": "سارا", "last_name": "رضایی", "company_id": null, "company_name": null, "job_title": null, "national_id": null, "owner_id": "0192a7f0-3b4c-7d5e-8f60-718293a4b5c6", "lifecycle_stage": "lead", "birthday": null, "unsubscribed_email": false, "unsubscribed_sms": false, "is_sample": false, "source": null, "marketing_block_reason": null, "address": null, "custom": {}, "emails": [], "phones": [ { "id": "0192c4e8-7b1b-7a10-8c21-3d4e5f607182", "phone": "09121234567", "label": null, "is_primary": true } ], "created_at": "2026-10-26T14:05:12.000Z", "updated_at": "2026-10-26T14:05:12.000Z"}