اتوماسیون سیگنال: انتشار از طریق API و تلگرام

پیش از شروع

اتوماسیون سیگنال چه کار می‌کند

به‌جای این‌که هر سیگنال را دستی در پنل بنویسید، سامانهٔ خودتان آن را از طریق یک کلید API در سیگره منتشر می‌کند. سیگنالی که می‌رسد یک سیگنال کاملاً عادی سیگره است: دنبال‌کننده‌ها آن را می‌بینند، ربات‌های کپی‌ترید ارزیابی‌اش می‌کنند و همهٔ قواعد سیگنال دستی برای آن هم برقرار است.

کدام پلن‌ها آن را دارند

اتوماسیون سیگنال از سطح ۳ به بالا فعال است. در سطح ۳ در هر دورهٔ ماهانه تا ۳۰ سیگنال خودکار منتشر می‌کنید و سطح ۴ نامحدود است. سطح‌های ۱ و ۲ کارت‌ها را در ابزارهای حرفه‌ای می‌بینند، همراه با سطحی که در آن باز می‌شود.

نکته: فقط سیگنال‌هایی که واقعاً پذیرفته و منتشر می‌شوند از سهمیهٔ ماهانه کم می‌کنند. درخواست‌های ردشده، خطاهای اعتبارسنجی و تکراری‌ها هیچ سهمیه‌ای مصرف نمی‌کنند.

کجا پیدایش کنید

در پنل ارائه‌دهنده وارد «ابزارهای حرفه‌ای» شوید. کارت «API و وب‌هوک سیگنال» کلیدها را مدیریت می‌کند و سهمیهٔ اتوماسیون دورهٔ جاری را نشان می‌دهد؛ کارت «سیگنال از تلگرام» اتصال آیندهٔ کانال را معرفی می‌کند.

کلید API شما

کلید بسازید

در کارت Signal API یک نام انتخاب کنید و کلید بسازید. کلید کامل فقط همان یک بار نمایش داده می‌شود. همان لحظه آن را در محل امن سامانهٔ خودتان ذخیره کنید — سیگره فقط اثر انگشت کلید را نگه می‌دارد و دیگر هرگز نمی‌تواند نشانش دهد.

مهم: با کلید مثل رمز عبور رفتار کنید. هر کسی آن را داشته باشد می‌تواند به نام شما سیگنال منتشر کند. اگر لو رفت، برای غیرفعال‌کردن به پشتیبانی خبر دهید و کلید تازه بسازید.

چطور ارسالش کنید

هر درخواست، کلید را در یک هدر می‌فرستد: یا هدر x-sigrah-provider-key با خودِ کلید، یا هدر استاندارد Authorization به شکل Bearer و سپس کلید.

انتشار سیگنال

آدرس انتشار

یک درخواست HTTP POST به https://api.sigrah.ir/api/v1/provider-api/signals بفرستید، با بدنهٔ JSON و هدر کلید. یک GET به https://api.sigrah.ir/api/v1/provider-api/status با همان هدر، پلن و سهمیه و باقی‌مانده را برمی‌گرداند؛ ساده‌ترین درخواست برای تست کلید تازه همین است.

بدنهٔ سیگنال

فیلدهای JSON همان فیلدهای فرم انتشارند. لازم: externalSignalId (شناسهٔ یکتای خودتان، حداکثر ۱۲۰ کاراکتر)، pair، action (BUY یا SELL)، entryPrice و riskLevel (LOW، MEDIUM یا HIGH). اختیاری: orderType (پیش‌فرض MARKET، یا LIMIT، STOP، STOP_LIMIT)، stopLimitPrice (برای STOP_LIMIT لازم)، expiresAt (تاریخ ISO در آینده، برای سفارش معلق)، stopLossLevels و takeProfitLevels، stopLoss و takeProfit، timeframe (M1، M5، M15، M30، H1، H4، D1 یا W1)، suggestedLot، audienceType (PUBLIC یا VIP)، copyTradeEnabled و note (حداکثر ۲۰۰۰ کاراکتر).

نکته: دیگر فیلد riskPercent وجود ندارد. سیگنال یک «سطح» ریسک اعلام می‌کند — LOW، MEDIUM یا HIGH — و سابسکرایبرها روی همان فیلتر می‌کنند. درخواستی که هنوز riskPercent می‌فرستد پذیرفته می‌شود و آن فیلد فقط نادیده گرفته می‌شود.

برنامهٔ خروج

stopLossLevels و takeProfitLevels برنامهٔ خروج‌اند. هرکدام تا سه پله می‌گیرد و هر پله یک price و یک closePercent دارد — سهمی از معامله که می‌بندد.

• closePercent بیشتر از ۰ و حداکثر ۱۰۰ است، با دو رقم اعشار، و جمع هر نردبان دقیقاً ۱۰۰: ۳۳٫۳۳ و ۳۳٫۳۳ و ۳۳٫۳۴ قبول است؛ ۹۹٫۹۹ و ۱۰۰٫۰۱ رد می‌شوند.
• در BUY همهٔ حد ضررها پایین‌تر از entryPrice و همهٔ حد سودها بالاتر از آن‌اند؛ در SELL برعکس. قیمت برابر ورود رد می‌شود.
• پله‌ها را به هر ترتیبی بفرستید. هر نردبان از نزدیک‌ترین پله به ورود ذخیره می‌شود، پس پلهٔ ۱ نزدیک‌ترین است. دو پله با یک قیمت رد می‌شود.
• stopLoss و takeProfit اختیاری‌اند. تنها که بیایند، هرکدام یک پله با ۱۰۰٪ است. کنار نردبان، باید با یکی از قیمت‌های همان نردبان برابر باشند — معمولاً پلهٔ ۱ — وگرنه درخواست رد می‌شود. ساده‌ترین راه، فرستادن فقط نردبان‌هاست.
• در کپی‌ترید هر پله با رسیدن قیمت سهم خودش را از معاملهٔ کپی‌شده می‌بندد. بروکر دورترین حد ضرر را برای باقی‌مانده نگه می‌دارد، و مشترکی که حجم را با درصد ریسک تعیین می‌کند بر پایهٔ همین دورترین حد ضرر حجم می‌گیرد.

یک درخواست کامل

یک BUY با سه حد ضرر و سه حد سود که جمع هر نردبان ۱۰۰ است:

{"externalSignalId": "my-system-2026-000123", "pair": "EURUSD", "action": "BUY", "orderType": "MARKET", "entryPrice": 1.0850, "stopLossLevels": [{"price": 1.0830, "closePercent": 50}, {"price": 1.0815, "closePercent": 30}, {"price": 1.0800, "closePercent": 20}], "takeProfitLevels": [{"price": 1.0900, "closePercent": 50}, {"price": 1.0950, "closePercent": 30}, {"price": 1.1000, "closePercent": 20}], "riskLevel": "MEDIUM", "timeframe": "H1", "note": "London session breakout"}

همین درخواست، آمادهٔ ارسال، روی کارت «API و وب‌هوک سیگنال» در ابزارهای حرفه‌ای هست. پیش از فرستادن همهٔ مقدارها را با مقدار خودتان عوض کنید.

تکرارِ امن

externalSignalId همان چیزی است که تکرار درخواست را امن می‌کند. اگر درخواست‌تان به هر دلیل بی‌پاسخ ماند و همان را با همان externalSignalId دوباره فرستادید، سیگره آن را می‌شناسد، همان سیگنال اول را با idempotent برابر true برمی‌گرداند و چیزی دوباره از سهمیه کم نمی‌کند. برای تکرارِ همان سیگنال هرگز شناسهٔ تازه نسازید.

توجه: اگر با شناسهٔ تازه ولی همان نماد، جهت، نوع سفارش و ورود در کمتر از ۹۰ ثانیه دوباره بفرستید، به‌عنوان تکرار ناخواسته با کد ۴۰۹ و SIGNAL_PUBLISH_DUPLICATE رد می‌شود — این محافظ برای آن است که یک اشکال در سامانهٔ شما نتواند دنبال‌کننده‌ها را غرق سیگنال کند.

پاسخ چیست

انتشار موفق با accepted برابر true پاسخ می‌دهد، همراه signalId تازه و وضعیت سهمیه بعد از انتشار: سقف، مصرف‌شده و باقی‌مانده در دوره. خود سیگنال در بخش سیگنال‌های شما با نشان منبع API دیده می‌شود.

بستن و تغییر

سیگنالی که با API منتشر کرده‌اید، با همان API مدیریت می‌شود. یک POST به https://api.sigrah.ir/api/v1/provider-api/signals/:reference/commands بفرستید؛ به جای :reference همان externalSignalId خودتان (یا شناسهٔ سیگنال در سیگراه) را بگذارید و در بدنه action را مشخص کنید:

• FULL_CLOSE هرچه هنوز باز است را می‌بندد.
• PARTIAL_CLOSE با closePercent (بیشتر از ۰، حداکثر ۱۰۰) همان سهم از باقی‌ماندهٔ معامله را می‌بندد؛ closeVolume به جای درصد، حجم می‌گیرد.
• MODIFY_STOP_LOSS با stopLoss، یا MODIFY_TAKE_PROFIT با takeProfit، کل نردبان همان طرف را با یک پله برای باقی‌ماندهٔ معامله عوض می‌کند؛ null آن را برمی‌دارد. حد ضرر تازه باید سمت زیانِ ورود بماند — روی ورود (سربه‌سر) یا آن‌طرف‌تر رد می‌شود.
• MODIFY_PENDING_PRICE با entryPrice سفارش معلقی را که پر نشده جابه‌جا می‌کند؛ اگر حد ضرر یا حد سود ثبت‌شده سمت اشتباه ورود تازه بیفتد، رد می‌شود. CANCEL_PENDING آن را لغو می‌کند.
• نردبان بعد از انتشار عوض نمی‌شود: دستوری که stopLossLevels یا takeProfitLevels داشته باشد رد می‌شود. سیگنال را ببندید و دوباره منتشر کنید.
• پله‌هایی که منتشر کرده‌اید روی معامله‌های کپی‌شده خودشان بسته می‌شوند. برای آن‌ها PARTIAL_CLOSE نفرستید، وگرنه همان سهم دو بار بسته می‌شود.

این‌ها همان دستورهای پنل‌اند، پس سیستم شما و دست خودتان دقیقاً یک چیز را می‌خواهند. اگر idempotencyKey (۱۲ تا ۱۸۰ کاراکتر) بفرستید، تلاش مجدد دستور را دو بار اجرا نمی‌کند.

نکته: این دستورها هیچ‌وقت از سهمیه کم نمی‌کنند و پشت وضعیت پلن نمی‌مانند. سهمیهٔ تمام‌شده یا سطحِ منقضی نباید بتواند یک معاملهٔ واقعی را باز نگه دارد — فقط باز کردن معاملهٔ جدید هزینه دارد.

سهمیه و محدودیت نرخ

سهمیهٔ ماهانه

سهمیهٔ ماهانه فقط انتشارهای پذیرفته‌شده را می‌شمارد، از همهٔ منابع اتوماسیون روی هم. وقتی سهمیهٔ دوره تمام شود، انتشارهای تازه با کد ۴۰۳ و AUTOMATION_QUOTA_EXHAUSTED رد می‌شوند تا دوره نو شود — ولی تکرارِ سیگنال‌های قبلاً پذیرفته همچنان موفق است.

محدودیت فنی نرخ

جدا از سهمیه، خود API یک سقف فنیِ درخواست-در-دقیقه دارد که زیرساخت را از رگبار درخواست حفظ می‌کند. برخورد با آن پاسخ ۴۲۹ با هدر retry-after می‌دهد؛ صبر کنید و دوباره بفرستید. پاسخ ۴۲۹ نه سهمیه مصرف می‌کند و نه سیگنالی می‌سازد.

نکته: وقتی سیگنال دارید منتشر کنید، نه در حلقهٔ سرکشی مداوم. انتشار خودکار عادی هیچ‌وقت به این سقف نزدیک نمی‌شود.

خواندن پاسخ‌های رد

هر پاسخ رد JSON است: { code, message, details }. کد ۴۰۰ یعنی چیزی منتشر نشد:

• VALIDATION_FAILED — details.fields نام فیلدهایی را می‌گوید که نیامده‌اند یا شکلشان درست نیست، مثل riskLevel یا stopLossLevels.0.closePercent.
• EXIT_CLOSE_SUM_INCOMPLETE یا EXIT_CLOSE_SUM_EXCEEDED — جمع یک نردبان کمتر یا بیشتر از ۱۰۰ است؛ details.field نام نردبان و details.total جمع آن است.
• STOP_LOSS_LEVEL_ON_WRONG_SIDE یا TAKE_PROFIT_LEVEL_ON_WRONG_SIDE — یک پله سمت اشتباه ورود است؛ details.field و details.level (با همان شماره‌ای که فرستادید) و details.price و details.entryPrice می‌گویند کدام. stopLoss یا takeProfit تکی در سمت اشتباه، SIGNAL_STOP_LOSS_WRONG_SIDE یا SIGNAL_TAKE_PROFIT_WRONG_SIDE می‌گیرد.
• EXIT_LEVEL_PRICE_DUPLICATE — دو پلهٔ یک نردبان یک قیمت دارند (details.field و details.price).
• EXIT_SINGLE_PRICE_NOT_IN_LADDER — stopLoss یا takeProfit با هیچ قیمتی از نردبان خودش یکی نیست (details.field و details.price).

۴۰۱ یعنی کلید نیامده یا شناخته نشده. ۴۰۳ یا پلنِ بدون اتوماسیون است یا سهمیهٔ تمام‌شده — کدِ داخل پاسخ می‌گوید کدام. ۴۰۹ با SIGNAL_PUBLISH_DUPLICATE همان پنجرهٔ تکرار است و details.signalId را دارد. هیچ‌کدام سهمیه مصرف نمی‌کنند.

کانال تلگرام — به‌زودی

چه خواهد بود

به‌زودی می‌توانید کانال یا گروه تلگرام خودتان را به سیگراه وصل کنید. سیگنالی که آن‌جا با قالب سیگراه می‌فرستید، دقیقاً مثل سیگنالی که در پنل ثبت شده برای دنبال‌کننده‌هایتان منتشر می‌شود و از همان سهمیهٔ اتوماسیونِ API کم می‌کند. کانال فقط برای باز کردن معامله نیست: از همان‌جا می‌توانید معامله را کامل یا بخشی ببندید، حد ضرر و حد سود را تغییر دهید، و سفارش معلق را لغو کنید — پس ارائه‌دهنده‌ای که با موبایل کار می‌کند، وسط معامله مجبور به باز کردن پنل نیست.

اتصال چطور خواهد بود

یک کد یک‌بارمصرف در ابزارهای حرفه‌ای می‌سازید، ربات سیگره را به کانال‌تان اضافه می‌کنید و کد را همان‌جا ارسال می‌کنید. مالکیت داخل خود کانال اثبات می‌شود — هیچ‌کس نمی‌تواند کانالی را که در اختیارش نیست وصل کند.

قالب پیام

پیام فقط وقتی خوانده می‌شود که سرخط سیگراه در سه خط اولش باشد: «سیگراه سیگنال» برای باز کردن معامله، «سیگراه بستن» برای بستن همه یا بخشی از آن، «سیگراه اصلاح» برای تغییر حد ضرر یا حد سود، و «سیگراه لغو» برای لغو سفارش معلق. معادل انگلیسی‌شان (SIGRAH SIGNAL، CLOSE، MODIFY، CANCEL) هم کار می‌کند. زیر سرخط، هر مورد در یک خط: نماد، جهت، قیمت ورود و ریسک لازم‌اند؛ نوع سفارش، حد ضرر، حد سود، تایم‌فریم، یادداشت و شناسه اختیاری‌اند؛ خط RISK% خوانده و نادیده گرفته می‌شود. حد ضرر یا یک SL است که کل معامله را می‌بندد، یا نردبان — SL1: 1.0800 50%، SL2: 1.0780 30%، SL3: 1.0760 20% — یا همین در یک خط: SL: 1.0800 50% / 1.0780 30% / 1.0760 20%. حد سود هم با TP و TP1 تا TP3 همین‌طور است. در نردبان هر پله درصدش را می‌گوید، از ۱ تا ۱۰۰، و جمعشان دقیقاً ۱۰۰ است. نام کلیدهای فارسی (نماد، جهت، قیمت ورود، حد ضرر، حد سود، ریسک، شناسه) هم خوانده می‌شود — شمارهٔ پله می‌تواند لاتین یا فارسی باشد، مثل حد سود 1 یا حد سود ۱ — و ارقام فارسی در مقدارها، متن پررنگ، ایموجی و نوشتن دستور زیر عکس چارت هم پذیرفته می‌شود. نمونهٔ پنل را کپی کنید و پیش از فرستادن همهٔ مقدارها را عوض کنید.

نکته: سطرهایی که دستور نیستند — لینک چارت، امضا، سلام — نادیده گرفته می‌شوند و پیام را خراب نمی‌کنند؛ توضیح را در خط یادداشت بنویسید، چون خطی که با کلمهٔ یک کلید شروع شود (حد ضرر، حد سود، سود، هدف، استاپ، نوع) دستور خوانده می‌شود. پیام اما رد می‌شود اگر کلیدی تکرار شود یا یک حرف با کلید واقعی فرق داشته باشد، مثل SLL به جای SL، چون نادیده گرفتنش یعنی انتشار سیگنالی بدون حد ضرر؛ و اگر درصدهای یک نردبان نوشته نشده باشد یا جمعشان ۱۰۰ نباشد، چون اینکه چند درصد از معامله کجا بسته شود حرفِ خود پرووایدر است، نه تصمیم ماشین. پیام ردشده چیزی منتشر نمی‌کند: ربات در پیام خصوصی و به زبان خودتان دلیلش را می‌گوید، و تلاش‌های اخیرتان در پنل ارائه‌دهنده فهرست می‌شوند.

بستن و تغییر از خود کانال

دستور بستن، اصلاح یا لغو سیگنالش را این‌طور مشخص می‌کند: با ریپلای روی پیام سیگنال — چه آن پیام شناسه داشته باشد چه نه — یا با همان شناسه، یا با نماد وقتی فقط یک سیگنال روی آن باز است. «سیگراه بستن» به اندازهٔ درصد نوشته‌شده از آنچه هنوز باز است را می‌بندد؛ ۱۰۰، یا بدون درصد، همه را. «سیگراه اصلاح» برای هر طرف یک قیمت می‌گیرد: حد ضرر یا حد سود کل نردبان همان طرف را با یک پله برای باقی‌ماندهٔ معامله عوض می‌کند، و NONE یا «حذف» آن را برمی‌دارد. حد ضرر تازه باید سمت زیانِ ورود بماند؛ بردنش روی ورود یا آن‌طرف‌تر رد می‌شود. قیمت ورود تازه سفارش معلق را جابه‌جا می‌کند و «سیگراه لغو» آن را لغو می‌کند. هیچ‌کدام سهمیه مصرف نمی‌کند.

توجه: پله‌هایی که منتشر کرده‌اید روی معامله‌های کپی‌شده خودشان بسته می‌شوند — آن‌ها را دوباره دستی نبندید، وگرنه همان سهم دو بار بسته می‌شود. نردبان بعد از انتشار عوض نمی‌شود: سیگنال را ببندید و سیگنال تازه منتشر کنید.

وقتی چیزی سر جایش نیست

کلید کار نمی‌کند

اگر همهٔ درخواست‌ها ۴۰۱ می‌گیرند، کلید با آنچه سیگره دارد یکی نیست: فاصله یا بریدگی هنگام ذخیره را بررسی کنید. اگر کلید درست است و باز رد می‌شود، شاید غیرفعال شده باشد — کلیدهای فعال را در کارت Signal API ببینید.

سیگنال دیده نمی‌شود

اگر پاسخ انتشار accepted برابر true بود، سیگنال ساخته شده — بخش سیگنال‌ها را باز کنید و نشان منبع API را ببینید. اگر پاسخ چیز دیگری بود، بدنهٔ پاسخ دقیقاً می‌گوید چرا؛ همان دلیل برای پشتیبانی هم در تاریخچهٔ اتصال شما ثبت شده است.