مستندات API وب‌سرویس | شرکت اطلس داده سفید

Conventions

نشانی پایهBase URL

برای Base URL از محیط خود استفاده کنید. مثال:

https://api.adsefid.com

احراز هویتAuthentication

همه endpointها در این مستند به Header زیر نیاز دارند:

X-API-KEY: <your_api_key>

در صورت نبودن یا نامعتبر بودن API key، پاسخ خطا با code 2018 (UNAUTHORIZED) یا 2005 (INVALID_API_KEY) برمی‌گردد.

نوع محتواContent Types

درخواست JSON: application/json
آپلود File: multipart/form-data
پاسخ JSON: application/json

نام‌گذاری و نوع‌هاNaming and Types

نام فیلدهای JSON به‌صورت snake_case است.
همه IDها مگر خلاف آن ذکر شود از نوع UUID string هستند.
فیلدهای تاریخ/زمان از فرمت ISO-8601 timestamp استفاده می‌کنند.
مقدار segment_count به encoding متن وابسته است.

قالب پاسخResponse Envelope

نکته‌ها:

مقدار error.code یک WebServiceResponseCode عددی است.
مقدار error.name نام نمادین uppercase است.
شکل error.details در همه اندپوینت‌ها یکسان است:
- errors — نگاشت نام فیلد به { "code", "name" }. کلیدها با نام snake_case فیلدهای request یکسان هستند و فیلدهای collection تو‌در‌تو به‌شکل مسیر flat مانند messages[0].local_id می‌آیند.
- items — خطای هر آیتم در اندپوینت‌های چندگیرنده، هر کدام به‌شکل { "index": n, "errors": { … } }.
هر ورودی همان جفت envelope را دارد: code مقدار عددی WebServiceResponseCode و name نام نمادین آن. هیچ‌کدام ترجمه نمی‌شوند، پس می‌توان روی هر دو شرط گذاشت.
اگر errors، items یا خود details خالی باشد، در پاسخ نمی‌آید. خطایی که جزئیاتی ندارد، کلید details هم ندارد.
بدنه‌ای که قابل تجزیه نباشد با 2024 و details.errors.request برابر INVALID_PARAMETER برگردانده می‌شود.

پاسخ موفقJSON

{
    "status": "success",
    "data": {}
}

پاسخ خطاJSON

{
    "status": "error",
    "error": {
        "code": 2024,
        "name": "INVALID_PARAMETER",
        "details": {
            "errors": {
                "line_number": {
                    "code": 2012,
                    "name": "EMPTY_LINE"
                }
            }
        }
    }
}

پذیرش جزئیPartial Acceptance

اندپوینت‌های POST /v1/sms/bulk, POST /v1/sms/p2p, POST /v1/messenger/bulk و POST /v1/messenger/p2p هر آیتمی را که بتوانند ارسال می‌کنند و بقیه را جداگانه گزارش می‌دهند.

آیتم‌های ردشده در همان پاسخ 200 با status خودشان و cost: 0 برمی‌گردند و در counts شمارش می‌شوند.
کد هر آیتم یکی از این‌هاست: 2014 (INVALID_RECEPTOR), 2029 (INVALID_LOCAL_IDS), 2007 (DUPLICATE_LOCAL_ID), 2013 (EMPTY_MESSAGE), 2016 (MESSAGE_TOO_LARGE), 2025 (RECEPTOR_BLACKLISTED).
اگر یک local_id در یک درخواست تکرار شود، آیتم اول ارسال و آیتم‌های بعدی رد می‌شوند. اگر local_id پیش‌تر در ارسال دیگری استفاده شده باشد، همان آیتم رد می‌شود.
اگر همه آیتم‌ها رد شوند، درخواست با 2024 (INVALID_PARAMETER) شکست می‌خورد و details.items برای هر آیتم ردشده یک عضو با index دارد:

اگر همه آیتم‌ها به یک دلیل رد شوند، کد همان دلیل به‌جای 2024 می‌آید: 2020 (ALL_RECEPTORS_BLACKLISTED) برای درخواستی که همه گیرنده‌هایش در لیست سیاه‌اند و 2026 (INVALID_LINK_IN_MESSAGE) وقتی خط یا پروفایل لینک را نمی‌پذیرد. در هر دو حالت details.items هم برگردانده می‌شود.
خطاهای سطح درخواست همچنان کل درخواست را با 2024 و details.errors رد می‌کنند؛ همین‌طور single و template.

JSON

{
    "status": "error",
    "error": {
        "code": 2024,
        "name": "INVALID_PARAMETER",
        "details": {
            "items": [
                {
                    "index": 0,
                    "errors": {
                        "receptor": {
                            "code": 2014,
                            "name": "INVALID_RECEPTOR"
                        }
                    }
                },
                {
                    "index": 2,
                    "errors": {
                        "local_id": {
                            "code": 2007,
                            "name": "DUPLICATE_LOCAL_ID"
                        }
                    }
                }
            ]
        }
    }
}

پشتیبانی و محدودیت‌هاSupport & Limits

برای اطلاع از سهمیه‌های درخواست API (از جمله حداکثر تعداد درخواست در دقیقه، ساعت و روز) و همچنین محدودیت‌های ارسال پیام، با تیم پشتیبانی در ارتباط باشید. تیم پشتیبانی می‌تواند سقف‌های اختصاصی حساب شما را اعلام کند، برای تنظیم یا افزایش محدودیت‌ها راهنمایی کند و به سوالات مرتبط پاسخ دهد.

به‌صورت پیش‌فرض، سقف ارسال 500 واحد در هر ثانیه است. این سقف برای مجموع ترافیک SMS و Messenger محاسبه می‌شود. در SMS، محاسبه بر اساس پارت انجام می‌شود؛ بنابراین یک SMS چندپارتی به تعداد پارت‌های خود از این سقف مصرف می‌کند.

راه‌های ارتباط با پشتیبانی:

وب‌سایت: adsefid.com
ثبت تیکت از طریق پنل کاربری

Enums

LineSelector

مقدار	نام
0	`PromotionalSendBased`
1	`PromotionalDeliverBased`
2	`BulkServiceSendBased`
3	`BulkServiceDeliverBased`
4	`CustomerClubServiceSendBased`
5	`CustomerClubServiceDeliverBased`

WebServiceMessageStatus

مقدار	نام	نهایی
1000	`SCHEDULED`	خیر
1001	`SENDING`	خیر
1002	`DELIVERED`	بله
1003	`UNDELIVERED`	بعد از ۳ ساعت
1004	`CANCELED`	بله
1005	`SENT_TO_OPERATOR`	خیر
1006	`BLACKLISTED`	بله
1007	`PROVIDER_ERROR`	بعد از ۳ ساعت
1008	`PENDING_APPROVAL`	خیر
1009	`REJECTED`	بله
1010	`INVALID_SENDER`	بله
1011	`INVALID_ATTACHMENT`	بله
1012	`FORBIDDEN_WORD`	بله
1013	`LINK_NOT_ALLOWED`	بله
1014	`INVALID_RECEIVER`	بله
1015	`UNDELIVERABLE`	بعد از ۶ ساعت
1016	`SENDER_LIMIT_REACHED`	خیر
1999	`UNKNOWN`	خیر

WebServiceCode

در فیلدهای status و keyهای counts استفاده می‌شود.

1000-1999: مقادیر message status
2000+: مقادیر error code

در JSON و در فیلد counts، keyها به‌صورت string serialize می‌شوندJSON

{
    "counts": {
        "1000": 120,
        "2025": 8
    }
}

WebServiceResponseCode (کدهای پاسخ endpointها)

کد	نام	HTTP Status
2000	`INTERNAL_ERROR`	500
2001	`INVALID_PLAN`	400
2002	`LINE_NOT_FOUND`	404
2003	`TOO_MANY_RECEPTORS`	400
2004	`INVALID_LINE`	400
2005	`INVALID_API_KEY`	401
2006	`IP_NOT_ALLOWED`	403
2007	`DUPLICATE_LOCAL_ID`	409
2008	`USER_INFORMATION_NOT_FOUND`	404
2009	`EMPTY_RECEPTORS`	400
2010	`INVALID_RECEPTORS`	400
2011	`EMPTY_BODY`	400
2012	`EMPTY_LINE`	400
2013	`EMPTY_MESSAGE`	400
2014	`INVALID_RECEPTOR`	400
2015	`EMPTY_RECEPTOR`	400
2016	`MESSAGE_TOO_LARGE`	413
2017	`INVALID_LINE_SELECTOR`	400
2018	`UNAUTHORIZED`	401
2019	`INVALID_SEND_RANGE`	400
2020	`ALL_RECEPTORS_BLACKLISTED`	403
2021	`MESSAGE_CONTAINS_FORBIDDEN_WORDS`	400
2022	`NOT_ENOUGH_CREDIT`	402
2023	`DUPLICATE_TAG`	409
2024	`INVALID_PARAMETER`	400
2025	`RECEPTOR_BLACKLISTED`	403
2026	`INVALID_LINK_IN_MESSAGE`	400
2027	`TEMPLATE_NOT_APPROVED`	400
2028	`INVALID_TEMPLATE_PARAMETER`	400
2029	`INVALID_LOCAL_IDS`	400
2030	`EMPTY_LOCAL_IDS`	400
2031	`EMPTY_MESSAGE_IDS`	400
2032	`INVALID_SMS_TYPE`	400
2033	`LINE_NOT_ACTIVE`	400
2034	`LINE_EXPIRED`	410
2035	`MESSAGE_LIMIT_REACHED`	429
2036	`REQUEST_LIMIT_REACHED`	429
2037	`INVALID_SEND_TIME`	400
2038	`INVALID_EXPIRY`	400
2039	`INVALID_TEMPLATE_ID`	400
2040	`PROFILE_NOT_FOUND`	400
2041	`PROFILE_EXPIRED`	400
2042	`FILE_NOT_FOUND`	400
2043	`INVALID_FILE`	400
2044	`ACCESS_DENIED`	403
2045	`REJECTED`	400
2046	`INVALID_MESSAGE_IDS`	400
2047	`FILE_TOO_LARGE`	413

TemplateState

وضعیت Template به‌صورت string با حروف کوچک برمی‌گردد. مجموعه کامل مقادیر پشتیبانی‌شده:

pendingapproval
approved
rejected

TemplateParameterType

نوع پارامتر Template به‌صورت string با حروف کوچک برمی‌گردد. مجموعه کامل مقادیر پشتیبانی‌شده:

string
number

API پیامکSMS API

ارسال تکی SMS

POST/v1/sms/single

ارسال یک پیام SMS.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`receptor`	string	بله	شماره تلفن معتبر
`line_number`	string	بله	باید متعلق به کاربر احراز هویت‌شده باشد
`line_selector`	int	خیر	به enum `LineSelector` مراجعه کنید
`message`	string	بله	حداکثر طول 900
`send_time`	datetime	خیر	باید >= `now - 1 minute` باشد
`local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر یکتا
`hide`	bool	خیر	مقدار پیش-فرض `false`

خطاهای رایج: 2014, 2002, 2033, 2034, 2007, 2035, 2020, 2022, 2026.

نمونهcURL

curl -X POST "https://api.adsefid.com/v1/sms/single" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <API_KEY>" \
  -d '{
    "receptor": "98912****567",
    "line_number": "983000XXX",
    "line_selector": 0,
    "message": "سلام، پیام تست",
    "send_time": "2026-04-04T10:30:00+03:30",
    "local_id": "order-10001",
    "hide": false
  }'

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ff8c-5423-7aa2-9c2b-d9c3b3f84d12",
        "local_id": "order-10001",
        "status": 1000,
        "line_number": "983000XXX",
        "line_selector": 0,
        "cost": 120,
        "receptor": "98912****567",
        "send_time": "2026-04-04T10:30:00+03:30",
        "message_id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
        "segment_count": 1,
        "hide": false
    }
}

ارسال گروهی SMS

POST/v1/sms/bulk

ارسال یک پیام مشترک برای چند گیرنده.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`receptors`	array	بله	حداقل 1 آیتم
`receptors[].receptor`	string	بله	شماره تلفن معتبر
`receptors[].local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر/request یکتا
`receptors[].hide`	bool	خیر	مقدار پیش-فرض `false`
`message`	string	بله	حداکثر طول 900
`send_time`	datetime	خیر	باید >= `now - 1 minute` و داخل send window ارائه‌دهنده باشد
`line_number`	string	بله	خط فرستنده
`line_selector`	int	خیر	به enum `LineSelector` مراجعه کنید

نقض قاعده در سطح آیتم، کل درخواست را رد نمی‌کند؛ به بخش «پذیرش جزئی» مراجعه کنید.

خطاهای رایج: 2024 (رد شدن همه آیتم‌ها)، 2020, 2019, 2035, 2022. کد هر آیتم: 2014, 2029, 2007, 2025.

نمونهJSON

{
    "receptors": [
        {
            "receptor": "98912****567",
            "local_id": "b-1",
            "hide": false
        },
        {
            "receptor": "98993****111",
            "local_id": "b-2",
            "hide": true
        }
    ],
    "message": "اطلاع رسانی سرویس",
    "send_time": "2026-04-04T11:00:00+03:30",
    "line_number": "983000XXX",
    "line_selector": 2
}

نمونه پاسخ موفق (امکان پذیرش partial وجود دارد)JSON

{
    "status": "success",
    "data": {
        "group_id": "0195ff8f-cf67-7c51-8a2a-9d2ea64eb150",
        "receptors": [
            {
                "message_id": "0195ff8f-d045-7598-86db-a4f9dff5328f",
                "receptor": "98912****567",
                "local_id": "b-1",
                "status": 1000,
                "hide": false,
                "cost": 120
            },
            {
                "message_id": null,
                "receptor": "98993****111",
                "local_id": "b-2",
                "status": 2025,
                "hide": true,
                "cost": 0
            }
        ],
        "message": "اطلاع رسانی سرویس",
        "segment_count": 1,
        "send_time": "2026-04-04T11:00:00+03:30",
        "line_number": "983000XXX",
        "line_selector": 2,
        "counts": {
            "1000": 1,
            "2025": 1
        },
        "total_count": 2,
        "total_cost": 120
    }
}

ارسال P2P SMS

POST/v1/sms/p2p

ارسال پیام‌های سفارشی برای هر گیرنده.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`messages`	array	بله	حداقل 1 آیتم
`messages[].receptor`	string	بله	شماره تلفن معتبر
`messages[].message`	string	بله	حداکثر طول 900
`messages[].local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه
`messages[].hide`	bool	خیر	مقدار پیش-فرض `false`
`send_time`	datetime	خیر	باید >= `now - 1 minute` باشد
`line_number`	string	بله	خط فرستنده
`line_selector`	int	خیر	به enum `LineSelector` مراجعه کنید

نقض قاعده در سطح آیتم، کل درخواست را رد نمی‌کند؛ به بخش «پذیرش جزئی» مراجعه کنید.

خطاهای رایج: 2024 (رد شدن همه آیتم‌ها)، 2020, 2035, 2022. کد هر آیتم: 2014, 2029, 2007, 2013, 2016, 2025.

نمونهJSON

{
    "messages": [
        {
            "receptor": "98912****567",
            "message": "سلام علی",
            "local_id": "p2p-1"
        },
        {
            "receptor": "98993****111",
            "message": "سلام رضا",
            "local_id": "p2p-2"
        }
    ],
    "send_time": "2026-04-04T11:10:00+03:30",
    "line_number": "983000XXX",
    "line_selector": 0
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ff95-79bf-7b1a-bfa1-a696a9f5e40a",
        "messages": [
            {
                "message_id": "0195ff95-7a2b-79ac-b993-ac37b6dd63b0",
                "receptor": "98912****567",
                "status": 1000,
                "local_id": "p2p-1",
                "message": "سلام علی",
                "hide": false,
                "segment_count": 1,
                "cost": 120
            },
            {
                "message_id": null,
                "receptor": "98993****111",
                "status": 2014,
                "local_id": "p2p-2",
                "message": "سلام رضا",
                "hide": false,
                "segment_count": 0,
                "cost": 0
            }
        ],
        "send_time": "2026-04-04T11:10:00+03:30",
        "line_number": "983000XXX",
        "line_selector": 0,
        "total_cost": 120,
        "counts": {
            "1000": 1,
            "2014": 1
        }
    }
}

ارسال Template پیامک

POST/v1/sms/template

ارسال یک template تاییدشده SMS.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`template_id`	string	بله	باید موجود و برای کاربر تاییدشده باشد
`parameters`	object	بله	باید placeholderهای template را کامل کند
`receptor`	string	بله	شماره تلفن معتبر
`local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر یکتا
`line_number`	string	بله	خط فرستنده
`line_selector`	int	خیر	به enum `LineSelector` مراجعه کنید
`expiry_date`	datetime	خیر	باید >= `now + 1 minute` باشد

خطاهای رایج: 2027, 2028, 2039, 2007, 2026, 2021.

نمونهJSON

{
    "template_id": "otp_login",
    "parameters": {
        "code": "459122",
        "minutes": 2
    },
    "receptor": "98912****567",
    "local_id": "otp-90001",
    "line_number": "983000XXX",
    "line_selector": 2,
    "expiry_date": "2026-04-04T12:00:00+03:30"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ff9f-f8db-747a-8c31-4d6a954f4a8d",
        "message_id": "0195ff9f-f9cf-7d62-a49e-2ca4db9a90f2",
        "status": 1000,
        "local_id": "otp-90001",
        "line_number": "983000XXX",
        "template_id": "otp_login",
        "send_time": "2026-04-04T11:40:00+03:30",
        "expiry_date": "2026-04-04T12:00:00+03:30",
        "line_selector": 2,
        "cost": 120,
        "receptor": "98912****567",
        "message": "کد ورود شما: ۴۵۹۱۲۲ - اعتبار: ۲ دقیقه",
        "segment_count": 1,
        "parameters": {
            "code": "459122",
            "minutes": 2
        }
    }
}

دریافت Status پیامک

GET/v1/sms/status

گرفتن status تحویل SMS با message ID و/یا local ID.

پارامترهای Query:

پارامتر	نوع	الزامی	توضیحات
`message_ids`	CSV UUID list	خیر	حداقل یکی از `message_ids` یا `local_ids` الزامی است
`local_ids`	CSV string list	خیر	حداقل یکی از `message_ids` یا `local_ids` الزامی است

قوانین:

تعداد یکتای message_ids + local_ids باید <= 2000 باشد.
پارامترها مقدار comma-separated می‌پذیرند.

خطاهای رایج: 2030, 2031, 2003, 2005. هر عضو نامعتبر یا خالی message_ids با 2046 INVALID_MESSAGE_IDS و شماره همان index گزارش می‌شود.

نمونهcURL

curl "https://api.adsefid.com/v1/sms/status?message_ids=0195ff8c-55aa-7e74-a337-c2fd4f6e85c5,0195ff9f-f9cf-7d62-a49e-2ca4db9a90f2&local_ids=order-10001,otp-90001" \
  -H "X-API-KEY: <API_KEY>"

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "receptors": [
            {
                "message_id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
                "local_id": "order-10001",
                "status": 1001,
                "receptor": "98912****567",
                "send_time": "2026-04-04T10:30:00+03:30",
                "delivery_time": null
            }
        ]
    }
}

لغو SMS

POST/v1/sms/cancel

لغو پیام‌های SMS در queue با ID.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`message_ids`	array(UUID)	مشروط	حداقل یکی از `message_ids` یا `local_ids` باید غیرخالی باشد
`local_ids`	array(string)	مشروط	حداقل یکی از `message_ids` یا `local_ids` باید غیرخالی باشد

نکته‌ها:

فقط پیام‌هایی که در queue هستند قابل cancel هستند.
پیام‌هایی که در queue نیستند با status فعلی در failed_to_cancel برگردانده می‌شوند.

خطاهای رایج: 2029 (IDهای نامعتبر یا ناموجود برای کاربر جاری)، 2022. در 2029، کلیدهای details.errors همان idهای ردشده و مقدار هر کدام 2029 INVALID_LOCAL_IDS است.

نمونهJSON

{
    "message_ids": [
        "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5"
    ],
    "local_ids": [
        "order-10001"
    ]
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "cancelled_messages": [
            {
                "message_id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
                "local_id": "order-10001",
                "status": 1004
            }
        ],
        "failed_to_cancel": []
    }
}

دریافت SMSهای ورودی

GET/v1/sms/receive

دریافت SMSهای inbound برای یک line.

پارامترهای Query:

پارامتر	نوع	الزامی	توضیحات
`line_number`	string	بله	line مجاز برای کاربر
`count`	int	خیر	باید `< 500` باشد (پیش‌فرض `100`)
`since`	datetime	خیر	باید در گذشته باشد

خطاهای رایج: 2024, 2004, 2005.

نمونهcURL

curl "https://api.adsefid.com/v1/sms/receive?line_number=983000XXX&count=50&since=2026-04-04T00:00:00+03:30" \
  -H "X-API-KEY: <API_KEY>"

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "messages": [
            {
                "message": "سلام",
                "line_number": "983000XXX",
                "receive_date": "2026-04-04T09:32:01+03:30",
                "sender": "98912****567"
            }
        ]
    }
}

API پیام‌رسانMessenger API

ارسال تکی Messenger

POST/v1/messenger/single

ارسال یک پیام در messenger.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`message`	string	بله	حداکثر طول 4000
`receptor`	string	بله	شماره تلفن معتبر
`profile`	UUID string	بله	باید برای کاربر جاری موجود باشد
`hide`	bool	خیر	مقدار پیش-فرض `false`
`file_id`	UUID string	خیر	باید توسط کاربر جاری آپلود شده باشد
`send_time`	datetime	خیر	باید >= `now - 1 minute` و داخل send window ارائه‌دهنده باشد
`local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر یکتا

خطاهای رایج: 2040, 2041, 2042, 2007, 2014, 2035, 2022, 2026.

نمونهJSON

{
    "message": "سلام از پیام رسان",
    "receptor": "98912****567",
    "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
    "hide": false,
    "file_id": "18dc580b-c598-4649-b2f4-dde1e5e35a57",
    "send_time": "2026-04-04T11:45:00+03:30",
    "local_id": "m-single-1"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ffa8-3420-73fd-b59d-ec8c5d32c14d",
        "message_id": "0195ffa8-34da-7397-a091-9f36b1d2f7ca",
        "status": 1000,
        "receptor": "98912****567",
        "local_id": "m-single-1",
        "hide": false,
        "cost": 80,
        "send_time": "2026-04-04T11:45:00+03:30",
        "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
        "messenger": "rubika"
    }
}

ارسال گروهی Messenger

POST/v1/messenger/bulk

ارسال یک پیام messenger یکسان برای چند گیرنده.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`receptors`	array	بله	حداقل 1 آیتم
`receptors[].receptor`	string	بله	شماره تلفن معتبر
`receptors[].local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر/request یکتا
`receptors[].hide`	bool	خیر	مقدار پیش-فرض `false`
`message`	string	بله	حداکثر طول 4000
`send_time`	datetime	خیر	باید در بازه زمانی معتبر باشد
`profile`	UUID string	بله	profile فعال برای کاربر جاری
`file_id`	UUID string	خیر	file آپلودشده معتبر

نقض قاعده در سطح آیتم، کل درخواست را رد نمی‌کند؛ به بخش «پذیرش جزئی» مراجعه کنید.

خطاهای رایج: 2040, 2041, 2042, 2024 (رد شدن همه آیتم‌ها)، 2020, 2035, 2022. کد هر آیتم: 2014, 2029, 2007, 2025.

نمونهJSON

{
    "receptors": [
        {
            "receptor": "98912****567",
            "local_id": "mb-1"
        },
        {
            "receptor": "98993****111",
            "local_id": "mb-2"
        }
    ],
    "message": "ارسال گروهی پیام رسان",
    "send_time": "2026-04-04T12:10:00+03:30",
    "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ffac-cb9d-79e0-8ab6-f451afafdf2d",
        "receptors": [
            {
                "message_id": "0195ffac-cc70-72d7-88a6-9f2347305b1b",
                "receptor": "98912****567",
                "local_id": "mb-1",
                "hide": false,
                "status": 1000,
                "cost": 80
            }
        ],
        "message": "ارسال گروهی پیام رسان",
        "send_time": "2026-04-04T12:10:00+03:30",
        "total_count": 1,
        "total_cost": 80,
        "counts": {
            "1000": 1
        },
        "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
        "messenger": "rubika"
    }
}

ارسال P2P Messenger

POST/v1/messenger/p2p

ارسال پیام‌های سفارشی messenger برای هر گیرنده.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`receptors`	array	بله	حداقل 1 آیتم
`receptors[].receptor`	string	بله	شماره تلفن معتبر
`receptors[].message`	string	بله	حداکثر طول 4000
`receptors[].local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه
`receptors[].hide`	bool	خیر	مقدار پیش-فرض `false`
`send_time`	datetime	خیر	بازه ارسال معتبر
`profile`	UUID string	بله	profile فعال
`file_id`	UUID string	خیر	file آپلودشده معتبر

نقض قاعده در سطح آیتم، کل درخواست را رد نمی‌کند؛ به بخش «پذیرش جزئی» مراجعه کنید.

خطاهای رایج: 2040, 2041, 2042, 2024 (رد شدن همه آیتم‌ها)، 2020, 2035, 2022. کد هر آیتم: 2014, 2029, 2007, 2013, 2016, 2025, 2026.

نمونهJSON

{
    "receptors": [
        {
            "receptor": "98912****567",
            "message": "سلام علی",
            "local_id": "mp2p-1"
        },
        {
            "receptor": "98993****111",
            "message": "سلام رضا",
            "local_id": "mp2p-2"
        }
    ],
    "send_time": "2026-04-04T12:30:00+03:30",
    "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ffb2-aa5e-7d42-953a-18f34d2f71e1",
        "receptors": [
            {
                "message_id": "0195ffb2-ab31-73f5-b8d7-afe7b7d2f1fd",
                "receptor": "98912****567",
                "message": "سلام علی",
                "local_id": "mp2p-1",
                "hide": false,
                "status": 1000,
                "cost": 80
            }
        ],
        "send_time": "2026-04-04T12:30:00+03:30",
        "total_count": 1,
        "total_cost": 80,
        "counts": {
            "1000": 1
        },
        "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
        "messenger": "bale"
    }
}

آپلود File در Messenger

POST/v1/messenger/file

آپلود media file برای messenger و دریافت file_id قابل استفاده مجدد.

درخواست:

Content type: multipart/form-data
Field name: file
محدودیت‌ها:
حداکثر size: 15 MB
فایل‌های مجاز:
- تصویر: image/jpeg, image/png, image/gif
- مستند: application/pdf
- صوت: audio/mpeg, audio/mp4, audio/aac, audio/ogg, audio/webm, audio/wav, audio/x-wav, audio/flac, audio/opus
- ویدیو: video/mp4, video/webm, video/ogg, video/quicktime, video/x-msvideo, video/x-matroska

خطاهای رایج: 2043, 2047 (بیش از 15 مگابایت)، 2001, 2018.

نمونهcURL

curl -X POST "https://api.adsefid.com/v1/messenger/file" \
  -H "X-API-KEY: <API_KEY>" \
  -F "file=@./brochure.pdf"

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "file_id": "18dc580b-c598-4649-b2f4-dde1e5e35a57"
    }
}

لغو پیام Messenger

POST/v1/messenger/cancel

لغو پیام‌های messenger در queue.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`message_ids`	array(UUID)	مشروط	حداقل یکی از `message_ids` یا `local_ids`
`local_ids`	array(string)	مشروط	حداقل یکی از `message_ids` یا `local_ids`

خطاهای رایج: 2029, 2022. در 2029، کلیدهای details.errors همان idهای ردشده و مقدار هر کدام 2029 INVALID_LOCAL_IDS است.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "cancelled_messages": [
            {
                "message_id": "0195ffa8-34da-7397-a091-9f36b1d2f7ca",
                "local_id": "m-single-1",
                "status": 1004
            }
        ],
        "failed_to_cancel": []
    }
}

ارسال Template پیام‌رسان

POST/v1/messenger/template

ارسال template تاییدشده از طریق messenger profile.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`template_id`	string	بله	باید برای کاربر تایید شده باشد
`parameters`	object	بله	باید placeholderهای template را کامل کند
`receptor`	string	بله	شماره تلفن معتبر
`local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر یکتا
`profile`	UUID string	بله	profile فعال
`expiry_date`	datetime	خیر	باید >= `now + 1 minute` باشد

خطاهای رایج: 2027, 2028, 2040, 2041, 2007, 2026, 2021.

نمونهJSON

{
    "template_id": "invoice_notice",
    "parameters": {
        "invoice_id": "INV-1043",
        "amount": "250000"
    },
    "receptor": "98912****567",
    "local_id": "mt-1",
    "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
    "expiry_date": "2026-04-04T13:00:00+03:30"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ffb8-ef3d-71d8-ba37-a5f6bd8fc603",
        "message_id": "0195ffb8-f03f-74d0-a97d-e90ae2f2b2d0",
        "status": 1000,
        "local_id": "mt-1",
        "template_id": "invoice_notice",
        "send_time": "2026-04-04T12:50:00+03:30",
        "expiry_date": "2026-04-04T13:00:00+03:30",
        "cost": 80,
        "receptor": "98912****567",
        "message": "فاکتور INV-1043 به مبلغ 250000 آماده است",
        "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
        "messenger": "rubika",
        "parameters": {
            "invoice_id": "INV-1043",
            "amount": "250000"
        }
    }
}

دریافت Status پیام‌رسان

GET/v1/messenger/status

گرفتن status پیام messenger با message_ids و/یا local_ids.

پارامترهای Query:

message_ids: comma-separated UUID list
local_ids: comma-separated string list

قوانین:

حداقل یکی از دو param الزامی است.
حداکثر تعداد ID یکتا در هر request برابر 2000 است.

خطاهای رایج: 2030, 2031, 2003, 2005. هر عضو نامعتبر یا خالی message_ids با 2046 INVALID_MESSAGE_IDS و شماره همان index گزارش می‌شود.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "receptors": [
            {
                "message_id": "0195ffa8-34da-7397-a091-9f36b1d2f7ca",
                "local_id": "m-single-1",
                "status": 1002,
                "receptor": "98912****567",
                "send_time": "2026-04-04T11:45:00+03:30",
                "delivery_time": "2026-04-04T11:45:08+03:30"
            }
        ]
    }
}

API کاربرUser API

دریافت اطلاعات Account

GET/v1/user/info

دریافت اطلاعات account کاربر احراز هویت‌شده.

خطاهای رایج: 2018.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "name": "علی رضایی",
        "company_name": "شرکت نمونه",
        "credit_left": 1250000,
        "email": "john@example.com",
        "phone": "98912****567",
        "account_status": "active"
    }
}

دریافت Lineهای کاربر

GET/v1/user/lines

دریافت همه lineهای ارسال‌کننده در دسترس برای کاربر احراز هویت‌شده.

خطاهای رایج: 2005, 2000.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": [
        {
            "line_number": "983000XXX",
            "line_selector": 0,
            "line_name": "Main Promotional",
            "enabled": true
        },
        {
            "line_number": "985000XXX",
            "line_selector": 2,
            "line_name": "Service Bulk",
            "enabled": false
        }
    ]
}

دریافت Profileهای کاربر

GET/v1/user/profiles

دریافت messenger profileهای در دسترس برای کاربر احراز هویت‌شده.

خطاهای رایج: 2005, 2000.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": [
        {
            "id": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
            "name": "پشتیبانی روبیکا",
            "messenger": "rubika"
        }
    ]
}

دریافت Templateهای کاربر

GET/v1/user/templates

دریافت Templateهای حذف‌نشده SMS و Messenger متعلق به کاربر احراز هویت‌شده با API key. به‌صورت پیش‌فرض همه وضعیت‌ها برگردانده می‌شوند و ترتیب نتایج از جدیدترین به قدیمی‌ترین با tie-breaker ثابت است.

پارامترهای Query:

فیلد	نوع	الزامی	قواعد
`state`	string	خیر	یکی از `pendingapproval`، `approved` یا `rejected`؛ فقط با حروف کوچک
`skip`	int	خیر	مقدار پیش‌فرض `0`؛ باید نامنفی باشد
`take`	int	خیر	مقدار پیش‌فرض `50`؛ باید بین `1` و `100` با احتساب دو سر باشد

total تعداد نتایج پس از فیلتر اختیاری وضعیت و پیش از صفحه‌بندی است. template_id همان string قابل استفاده در هر دو اندپوینت POST /v1/sms/template و POST /v1/messenger/template است. نام پارامترها دقیقاً مطابق تعریف کاربر حفظ می‌شود؛ مقادیر پارامتر از مجموعه کامل TemplateParameterType بالا و state از مجموعه کامل TemplateState استفاده می‌کند.

خطاهای رایج: 2018 برای API key ناموجود یا نامعتبر؛ 2024 برای state، skip یا take نامعتبر.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "items": [
            {
                "template_id": "payment-notice",
                "content": "Code: {{OTPCode:string}}, amount: {{amount:number}}",
                "parameters": {
                    "OTPCode": "string",
                    "amount": "number"
                },
                "state": "approved",
                "description": null,
                "created_at": "2026-09-02T10:30:00+03:30",
                "updated_at": "2026-09-02T11:00:00+03:30"
            }
        ],
        "total": 1
    }
}

نمونه صفحه خالیJSON

{
    "status": "success",
    "data": {
        "items": [],
        "total": 0
    }
}

وب‌هوک‌های خروجیOutgoing Webhooks

رویدادهاEvents

پلتفرم سه نوع رویداد پشتیبانی می‌کند:

پیام‌های دریافتی (receive)
تغییر وضعیت پیام‌های SMS (status)
تغییر وضعیت پیام‌های Messenger (messenger.status)

درخواست HTTPHTTP Request

Method: POST
Content-Type: application/json
Timeout: 10 seconds
شرط موفقیت: هر پاسخ 2xx

هدرهای ارسالی:

هدر	توضیح
`X-Atlas-Webhook-Id`	UUID عمومی delivery وب‌هوک
`X-Atlas-Webhook-Event`	نام event (`receive`، `status` یا `messenger.status`)
`X-Atlas-Webhook-Attempt`	شماره attempt (از 1 شروع می‌شود)
`X-Atlas-Webhook-Timestamp`	Unix timestamp (برحسب ثانیه)
`X-Atlas-Webhook-Signature`	فرمت signature: `v1=<base64_hmac_sha256>`
`User-Agent`	`AtlasSMS-Webhooks/1.0`

اعتبارسنجی امضاSignature Verification

الگوریتم:

اجرای HMAC-SHA256 با secret bytes مربوط به webhook endpoint
تبدیل خروجی به Base64
مقایسه با مقدار Header بعد از حذف پیشوند v1=

مهم:

اعتبارسنجی را روی raw body bytes دقیق انجام دهید.
timestamp های قدیمی را طبق replay policy رد کنید.
اکیدا توصیه می‌شود پیش از پردازش payload، signature + timestamp هر webhook request اعتبارسنجی شود.

ورودی امضاText

<timestamp>.<raw_request_body>

شبه-کدText

hex = HMAC_SHA256( $"{timestamp}.{raw_body}", secret )
base64 = BASE64(hex_to_bytes(hex))
expected_signature = "v1=" + base64

Payload رویداد ReceiveReceive Event Payload

Header:

X-Atlas-Webhook-Event: receive

BodyJSON

{
    "id": "0195ffd0-7e08-7d4d-8eef-dd4f7ca5e6fd",
    "type": "receive",
    "occurred_at": "2026-04-04T12:00:00+03:30",
    "attempt": 1,
    "version": "1",
    "data": [
        {
            "id": 1543201,
            "line_number": "983000XXX",
            "sender": "98912****567",
            "message": "سلام",
            "receive_date": "2026-04-04T11:59:58+03:30"
        }
    ]
}

Payload رویداد Status UpdateStatus Update Event Payload

Header:

X-Atlas-Webhook-Event: status

BodyJSON

{
    "id": "0195ffd2-76d4-7d10-9d40-c0d2fc61f774",
    "type": "status",
    "occurred_at": "2026-04-04T12:05:00+03:30",
    "attempt": 1,
    "version": "1",
    "data": [
        {
            "id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
            "local_id": "order-10001",
            "status_delivery": 1002,
            "delivery_time": "2026-04-04T12:04:54+03:30"
        }
    ]
}

Payload رویداد Messenger StatusMessenger Status Event Payload

Header:

X-Atlas-Webhook-Event: messenger.status

BodyJSON

{
    "id": "0195ffd2-76d4-7d10-9d40-c0d2fc61f774",
    "type": "messenger.status",
    "occurred_at": "2026-04-04T12:05:00+03:30",
    "attempt": 1,
    "version": "1",
    "data": [
        {
            "id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
            "local_id": "order-10001",
            "status_delivery": 1002,
            "delivery_time": "2026-04-04T12:04:54+03:30"
        }
    ]
}

رفتار Retry و تحویلRetry and Delivery Behavior

در صورت fail شدن attempt، retry با backoff انجام می‌شود: 5s، 60s، 120s، 360s، 600s، سپس 900s.
تلاش مجدد تا رسیدن به max attempts مربوط به endpoint ادامه می‌یابد.
پس از رسیدن به max attempts، وضعیت delivery برابر dead می‌شود و retry دیگری انجام نمی‌شود.
از delivery-item تکراری در سطح storage جلوگیری می‌شود.
وب‌هوک‌های Receive در هر delivery حداکثر به 100 آیتم chunk می‌شوند.

توصیه‌های استفاده کننده:

با X-Atlas-Webhook-Id + event item ID handler را به‌صورت idempotent طراحی کنید.
پاسخ 2xx را سریع برگردانید؛ در صورت امکان پردازش را asynchronous انجام دهید.

کیت‌های توسعهٔ رسمیSDK

برای پنج زبان برنامه‌نویسی، کتابخانه‌های رسمی و متن‌باز در دسترس‌اند. هر کتابخانه همهٔ عملیات معرفی‌شده در این مستند را پوشش می‌دهد، مدل‌های نوع‌دار برای درخواست‌ها و پاسخ‌ها و نوع‌های شمارشی وضعیت و خطا را ارائه می‌کند و ابزاری برای بررسی امضای وب‌هوک دارد (بخش «اعتبارسنجی امضا» را ببینید).

نسخهٔ آزمایشی: هر پنج کیت توسعه در حال حاضر در مرحلهٔ بتا هستند. این کتابخانه‌ها همهٔ امکانات رابط برنامه‌نویسی شرح‌داده‌شده در این مستند را پوشش می‌دهند، اما ممکن است رابط برنامه‌نویسی آن‌ها پیش از انتشار نسخهٔ 1.0 به‌شکلی ناسازگار با نسخه‌های قبلی تغییر کند. نسخهٔ دقیق هر کتابخانه را در فایل وابستگی‌های پروژه ثابت کنید و پیش از ارتقا، یادداشت‌های انتشار مخزن مربوط را بخوانید. خود رابط برنامه‌نویسی REST پایدار است و آزمایشی بودن کیت‌های توسعه اثری بر آن ندارد. مشکلات هر کتابخانه را در مخزن همان کتابخانه گزارش کنید.

بسته‌ها

زبان	بسته	دستور نصب	کد منبع
.NET 8+	`Adsefid.Sdk` (NuGet)	`dotnet add package Adsefid.Sdk`	adsefid/sdk-dotnet
Python 3.10+	`adsefid` (PyPI)	`pip install adsefid`	adsefid/sdk-python
Node.js 18+ (JS/TS)	`@adsefid/sdk` (npm)	`npm install @adsefid/sdk`	adsefid/sdk-js
PHP 8.2+	`adsefid/sdk` (Packagist)	`composer require adsefid/sdk`	adsefid/sdk-php
Go 1.22+	`github.com/adsefid/sdk-go`	`go get github.com/adsefid/sdk-go`	adsefid/sdk-go

راهنمای استفاده از هر زبان در مخزن همان کتابخانه آمده است. فایل README هر پروژه نصب، احراز هویت، پیکربندی کلاینت، نگاشت کامل متدهای کتابخانه به عملیات این مستند و مدیریت خطا را توضیح می‌دهد. نمونه‌های اجرایی، از جمله راه‌اندازی سریع و دریافت‌کنندهٔ وب‌هوک، در پوشهٔ examples/ هر مخزن قرار دارند.

نکته‌ها:

کتابخانهٔ PHP به یک کلاینت HTTP سازگار با PSR-18 نیز نیاز دارد؛ برای نمونه: composer require guzzlehttp/guzzle.
کتابخانهٔ JavaScript فقط برای اجرا در سمت سرور است. این کتابخانه کلید محرمانهٔ رابط برنامه‌نویسی شما را در اختیار دارد؛ بنابراین هرگز نباید همراه کد سمت مرورگر بسته‌بندی شود.

رفتار مشترک

همهٔ این کتابخانه‌ها به‌طور پیش‌فرض از نشانی پایهٔ https://api.adsefid.com استفاده می‌کنند و هدر X-API-KEY را با هر درخواست می‌فرستند. نشانی پایه، هدر User-Agent، مهلت پاسخ و کلاینت زیربنایی HTTP قابل تنظیم‌اند.
هیچ‌یک از این کتابخانه‌ها متغیرهای محیطی را به‌طور ضمنی نمی‌خواند. کلید رابط برنامه‌نویسی را در برنامهٔ خود بخوانید و آن را صریحاً به کلاینت بدهید.
خطاها به‌صورت نوع‌دار برگردانده می‌شوند و کد عددی WebServiceResponseCode و نام نمادین آن را در اختیار می‌گذارند. برای محدودیت نرخ درخواست، خطاهای اعتبارسنجی و خطاهای ارتباطی، نوع خطای جداگانه‌ای وجود دارد.

ابزارهای بررسی وب‌هوک

هر کتابخانه هدر X-Atlas-Webhook-Signature را بررسی می‌کند و در همان فراخوانی، بدنهٔ پیام را به یک رویداد نوع‌دار تبدیل می‌کند. همیشه بدنهٔ خام درخواست را عیناً و پیش از هرگونه تجزیهٔ JSON به تابع بدهید؛ ممکن است چارچوب برنامهٔ شما آن را پیش‌تر تجزیه کرده باشد.

زبان	تابع
.NET	`WebhookVerifier.VerifyAndParse(rawBody, signature, timestamp, secret)`
Python	`verify_and_parse_webhook(raw_body, signature_header, timestamp_header, secret)`
JavaScript / TS	`verifyAndParseWebhook({ rawBody, signatureHeader, timestampHeader, secret })`
PHP	`(new WebhookVerifier($secret))->verifyAndParse($rawBody, $signature, $timestamp)`
Go	`webhooks.Verify(rawBody, signature, timestamp, secret)`

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

نکات یکپارچه‌سازیIntegration Notes

کوئری پارامترهای message_ids و local_ids از مقادیر comma-separated پشتیبانی می‌کنند.
یکتایی local_id به ازای هر کاربر و channel enforce می‌شود.
اندپوینت‌های Status ممکن است پیام‌های تازه accepted شده را قبل از persistence کامل در DB از cache کوتاه‌عمر برگردانند.
عملیات Cancel وابسته به وضعیت queue است: پیام‌های already-sent/in-progress در failed_to_cancel برمی‌گردند.
خطاهای model-binding از envelope استاندارد استفاده می‌کنند و خطای هر فیلد زیر error.details.errors برمی‌گردد.

Conventions

نشانی پایهBase URL

برای Base URL از محیط خود استفاده کنید. مثال:

https://api.adsefid.com

احراز هویتAuthentication

همه endpointها در این مستند به Header زیر نیاز دارند:

X-API-KEY: <your_api_key>

در صورت نبودن یا نامعتبر بودن API key، پاسخ خطا با code 2018 (UNAUTHORIZED) یا 2005 (INVALID_API_KEY) برمی‌گردد.

نوع محتواContent Types

درخواست JSON: application/json
آپلود File: multipart/form-data
پاسخ JSON: application/json

نام‌گذاری و نوع‌هاNaming and Types

نام فیلدهای JSON به‌صورت snake_case است.
همه IDها مگر خلاف آن ذکر شود از نوع UUID string هستند.
فیلدهای تاریخ/زمان از فرمت ISO-8601 timestamp استفاده می‌کنند.
مقدار segment_count به encoding متن وابسته است.

قالب پاسخResponse Envelope

نکته‌ها:

مقدار error.code یک WebServiceResponseCode عددی است.
مقدار error.name نام نمادین uppercase است.
شکل error.details در همه اندپوینت‌ها یکسان است:
- errors — نگاشت نام فیلد به { "code", "name" }. کلیدها با نام snake_case فیلدهای request یکسان هستند و فیلدهای collection تو‌در‌تو به‌شکل مسیر flat مانند messages[0].local_id می‌آیند.
- items — خطای هر آیتم در اندپوینت‌های چندگیرنده، هر کدام به‌شکل { "index": n, "errors": { … } }.
هر ورودی همان جفت envelope را دارد: code مقدار عددی WebServiceResponseCode و name نام نمادین آن. هیچ‌کدام ترجمه نمی‌شوند، پس می‌توان روی هر دو شرط گذاشت.
اگر errors، items یا خود details خالی باشد، در پاسخ نمی‌آید. خطایی که جزئیاتی ندارد، کلید details هم ندارد.
بدنه‌ای که قابل تجزیه نباشد با 2024 و details.errors.request برابر INVALID_PARAMETER برگردانده می‌شود.

پاسخ موفقJSON

{
    "status": "success",
    "data": {}
}

پاسخ خطاJSON

{
    "status": "error",
    "error": {
        "code": 2024,
        "name": "INVALID_PARAMETER",
        "details": {
            "errors": {
                "line_number": {
                    "code": 2012,
                    "name": "EMPTY_LINE"
                }
            }
        }
    }
}

پذیرش جزئیPartial Acceptance

آیتم‌های ردشده در همان پاسخ 200 با status خودشان و cost: 0 برمی‌گردند و در counts شمارش می‌شوند.
کد هر آیتم یکی از این‌هاست: 2014 (INVALID_RECEPTOR), 2029 (INVALID_LOCAL_IDS), 2007 (DUPLICATE_LOCAL_ID), 2013 (EMPTY_MESSAGE), 2016 (MESSAGE_TOO_LARGE), 2025 (RECEPTOR_BLACKLISTED).
اگر یک local_id در یک درخواست تکرار شود، آیتم اول ارسال و آیتم‌های بعدی رد می‌شوند. اگر local_id پیش‌تر در ارسال دیگری استفاده شده باشد، همان آیتم رد می‌شود.
اگر همه آیتم‌ها رد شوند، درخواست با 2024 (INVALID_PARAMETER) شکست می‌خورد و details.items برای هر آیتم ردشده یک عضو با index دارد:

اگر همه آیتم‌ها به یک دلیل رد شوند، کد همان دلیل به‌جای 2024 می‌آید: 2020 (ALL_RECEPTORS_BLACKLISTED) برای درخواستی که همه گیرنده‌هایش در لیست سیاه‌اند و 2026 (INVALID_LINK_IN_MESSAGE) وقتی خط یا پروفایل لینک را نمی‌پذیرد. در هر دو حالت details.items هم برگردانده می‌شود.
خطاهای سطح درخواست همچنان کل درخواست را با 2024 و details.errors رد می‌کنند؛ همین‌طور single و template.

JSON

{
    "status": "error",
    "error": {
        "code": 2024,
        "name": "INVALID_PARAMETER",
        "details": {
            "items": [
                {
                    "index": 0,
                    "errors": {
                        "receptor": {
                            "code": 2014,
                            "name": "INVALID_RECEPTOR"
                        }
                    }
                },
                {
                    "index": 2,
                    "errors": {
                        "local_id": {
                            "code": 2007,
                            "name": "DUPLICATE_LOCAL_ID"
                        }
                    }
                }
            ]
        }
    }
}

پشتیبانی و محدودیت‌هاSupport & Limits

راه‌های ارتباط با پشتیبانی:

وب‌سایت: adsefid.com
ثبت تیکت از طریق پنل کاربری

Enums

LineSelector

مقدار	نام
0	`PromotionalSendBased`
1	`PromotionalDeliverBased`
2	`BulkServiceSendBased`
3	`BulkServiceDeliverBased`
4	`CustomerClubServiceSendBased`
5	`CustomerClubServiceDeliverBased`

WebServiceMessageStatus

مقدار	نام	نهایی
1000	`SCHEDULED`	خیر
1001	`SENDING`	خیر
1002	`DELIVERED`	بله
1003	`UNDELIVERED`	بعد از ۳ ساعت
1004	`CANCELED`	بله
1005	`SENT_TO_OPERATOR`	خیر
1006	`BLACKLISTED`	بله
1007	`PROVIDER_ERROR`	بعد از ۳ ساعت
1008	`PENDING_APPROVAL`	خیر
1009	`REJECTED`	بله
1010	`INVALID_SENDER`	بله
1011	`INVALID_ATTACHMENT`	بله
1012	`FORBIDDEN_WORD`	بله
1013	`LINK_NOT_ALLOWED`	بله
1014	`INVALID_RECEIVER`	بله
1015	`UNDELIVERABLE`	بعد از ۶ ساعت
1016	`SENDER_LIMIT_REACHED`	خیر
1999	`UNKNOWN`	خیر

WebServiceCode

در فیلدهای status و keyهای counts استفاده می‌شود.

1000-1999: مقادیر message status
2000+: مقادیر error code

در JSON و در فیلد counts، keyها به‌صورت string serialize می‌شوندJSON

{
    "counts": {
        "1000": 120,
        "2025": 8
    }
}

WebServiceResponseCode (کدهای پاسخ endpointها)

کد	نام	HTTP Status
2000	`INTERNAL_ERROR`	500
2001	`INVALID_PLAN`	400
2002	`LINE_NOT_FOUND`	404
2003	`TOO_MANY_RECEPTORS`	400
2004	`INVALID_LINE`	400
2005	`INVALID_API_KEY`	401
2006	`IP_NOT_ALLOWED`	403
2007	`DUPLICATE_LOCAL_ID`	409
2008	`USER_INFORMATION_NOT_FOUND`	404
2009	`EMPTY_RECEPTORS`	400
2010	`INVALID_RECEPTORS`	400
2011	`EMPTY_BODY`	400
2012	`EMPTY_LINE`	400
2013	`EMPTY_MESSAGE`	400
2014	`INVALID_RECEPTOR`	400
2015	`EMPTY_RECEPTOR`	400
2016	`MESSAGE_TOO_LARGE`	413
2017	`INVALID_LINE_SELECTOR`	400
2018	`UNAUTHORIZED`	401
2019	`INVALID_SEND_RANGE`	400
2020	`ALL_RECEPTORS_BLACKLISTED`	403
2021	`MESSAGE_CONTAINS_FORBIDDEN_WORDS`	400
2022	`NOT_ENOUGH_CREDIT`	402
2023	`DUPLICATE_TAG`	409
2024	`INVALID_PARAMETER`	400
2025	`RECEPTOR_BLACKLISTED`	403
2026	`INVALID_LINK_IN_MESSAGE`	400
2027	`TEMPLATE_NOT_APPROVED`	400
2028	`INVALID_TEMPLATE_PARAMETER`	400
2029	`INVALID_LOCAL_IDS`	400
2030	`EMPTY_LOCAL_IDS`	400
2031	`EMPTY_MESSAGE_IDS`	400
2032	`INVALID_SMS_TYPE`	400
2033	`LINE_NOT_ACTIVE`	400
2034	`LINE_EXPIRED`	410
2035	`MESSAGE_LIMIT_REACHED`	429
2036	`REQUEST_LIMIT_REACHED`	429
2037	`INVALID_SEND_TIME`	400
2038	`INVALID_EXPIRY`	400
2039	`INVALID_TEMPLATE_ID`	400
2040	`PROFILE_NOT_FOUND`	400
2041	`PROFILE_EXPIRED`	400
2042	`FILE_NOT_FOUND`	400
2043	`INVALID_FILE`	400
2044	`ACCESS_DENIED`	403
2045	`REJECTED`	400
2046	`INVALID_MESSAGE_IDS`	400
2047	`FILE_TOO_LARGE`	413

TemplateState

وضعیت Template به‌صورت string با حروف کوچک برمی‌گردد. مجموعه کامل مقادیر پشتیبانی‌شده:

pendingapproval
approved
rejected

TemplateParameterType

نوع پارامتر Template به‌صورت string با حروف کوچک برمی‌گردد. مجموعه کامل مقادیر پشتیبانی‌شده:

string
number

API پیامکSMS API

ارسال تکی SMS

POST/v1/sms/single

ارسال یک پیام SMS.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`receptor`	string	بله	شماره تلفن معتبر
`line_number`	string	بله	باید متعلق به کاربر احراز هویت‌شده باشد
`line_selector`	int	خیر	به enum `LineSelector` مراجعه کنید
`message`	string	بله	حداکثر طول 900
`send_time`	datetime	خیر	باید >= `now - 1 minute` باشد
`local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر یکتا
`hide`	bool	خیر	مقدار پیش-فرض `false`

خطاهای رایج: 2014, 2002, 2033, 2034, 2007, 2035, 2020, 2022, 2026.

نمونهcURL

curl -X POST "https://api.adsefid.com/v1/sms/single" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <API_KEY>" \
  -d '{
    "receptor": "98912****567",
    "line_number": "983000XXX",
    "line_selector": 0,
    "message": "سلام، پیام تست",
    "send_time": "2026-04-04T10:30:00+03:30",
    "local_id": "order-10001",
    "hide": false
  }'

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ff8c-5423-7aa2-9c2b-d9c3b3f84d12",
        "local_id": "order-10001",
        "status": 1000,
        "line_number": "983000XXX",
        "line_selector": 0,
        "cost": 120,
        "receptor": "98912****567",
        "send_time": "2026-04-04T10:30:00+03:30",
        "message_id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
        "segment_count": 1,
        "hide": false
    }
}

ارسال گروهی SMS

POST/v1/sms/bulk

ارسال یک پیام مشترک برای چند گیرنده.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`receptors`	array	بله	حداقل 1 آیتم
`receptors[].receptor`	string	بله	شماره تلفن معتبر
`receptors[].local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر/request یکتا
`receptors[].hide`	bool	خیر	مقدار پیش-فرض `false`
`message`	string	بله	حداکثر طول 900
`send_time`	datetime	خیر	باید >= `now - 1 minute` و داخل send window ارائه‌دهنده باشد
`line_number`	string	بله	خط فرستنده
`line_selector`	int	خیر	به enum `LineSelector` مراجعه کنید

نقض قاعده در سطح آیتم، کل درخواست را رد نمی‌کند؛ به بخش «پذیرش جزئی» مراجعه کنید.

خطاهای رایج: 2024 (رد شدن همه آیتم‌ها)، 2020, 2019, 2035, 2022. کد هر آیتم: 2014, 2029, 2007, 2025.

نمونهJSON

{
    "receptors": [
        {
            "receptor": "98912****567",
            "local_id": "b-1",
            "hide": false
        },
        {
            "receptor": "98993****111",
            "local_id": "b-2",
            "hide": true
        }
    ],
    "message": "اطلاع رسانی سرویس",
    "send_time": "2026-04-04T11:00:00+03:30",
    "line_number": "983000XXX",
    "line_selector": 2
}

نمونه پاسخ موفق (امکان پذیرش partial وجود دارد)JSON

{
    "status": "success",
    "data": {
        "group_id": "0195ff8f-cf67-7c51-8a2a-9d2ea64eb150",
        "receptors": [
            {
                "message_id": "0195ff8f-d045-7598-86db-a4f9dff5328f",
                "receptor": "98912****567",
                "local_id": "b-1",
                "status": 1000,
                "hide": false,
                "cost": 120
            },
            {
                "message_id": null,
                "receptor": "98993****111",
                "local_id": "b-2",
                "status": 2025,
                "hide": true,
                "cost": 0
            }
        ],
        "message": "اطلاع رسانی سرویس",
        "segment_count": 1,
        "send_time": "2026-04-04T11:00:00+03:30",
        "line_number": "983000XXX",
        "line_selector": 2,
        "counts": {
            "1000": 1,
            "2025": 1
        },
        "total_count": 2,
        "total_cost": 120
    }
}

ارسال P2P SMS

POST/v1/sms/p2p

ارسال پیام‌های سفارشی برای هر گیرنده.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`messages`	array	بله	حداقل 1 آیتم
`messages[].receptor`	string	بله	شماره تلفن معتبر
`messages[].message`	string	بله	حداکثر طول 900
`messages[].local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه
`messages[].hide`	bool	خیر	مقدار پیش-فرض `false`
`send_time`	datetime	خیر	باید >= `now - 1 minute` باشد
`line_number`	string	بله	خط فرستنده
`line_selector`	int	خیر	به enum `LineSelector` مراجعه کنید

نقض قاعده در سطح آیتم، کل درخواست را رد نمی‌کند؛ به بخش «پذیرش جزئی» مراجعه کنید.

خطاهای رایج: 2024 (رد شدن همه آیتم‌ها)، 2020, 2035, 2022. کد هر آیتم: 2014, 2029, 2007, 2013, 2016, 2025.

نمونهJSON

{
    "messages": [
        {
            "receptor": "98912****567",
            "message": "سلام علی",
            "local_id": "p2p-1"
        },
        {
            "receptor": "98993****111",
            "message": "سلام رضا",
            "local_id": "p2p-2"
        }
    ],
    "send_time": "2026-04-04T11:10:00+03:30",
    "line_number": "983000XXX",
    "line_selector": 0
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ff95-79bf-7b1a-bfa1-a696a9f5e40a",
        "messages": [
            {
                "message_id": "0195ff95-7a2b-79ac-b993-ac37b6dd63b0",
                "receptor": "98912****567",
                "status": 1000,
                "local_id": "p2p-1",
                "message": "سلام علی",
                "hide": false,
                "segment_count": 1,
                "cost": 120
            },
            {
                "message_id": null,
                "receptor": "98993****111",
                "status": 2014,
                "local_id": "p2p-2",
                "message": "سلام رضا",
                "hide": false,
                "segment_count": 0,
                "cost": 0
            }
        ],
        "send_time": "2026-04-04T11:10:00+03:30",
        "line_number": "983000XXX",
        "line_selector": 0,
        "total_cost": 120,
        "counts": {
            "1000": 1,
            "2014": 1
        }
    }
}

ارسال Template پیامک

POST/v1/sms/template

ارسال یک template تاییدشده SMS.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`template_id`	string	بله	باید موجود و برای کاربر تاییدشده باشد
`parameters`	object	بله	باید placeholderهای template را کامل کند
`receptor`	string	بله	شماره تلفن معتبر
`local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر یکتا
`line_number`	string	بله	خط فرستنده
`line_selector`	int	خیر	به enum `LineSelector` مراجعه کنید
`expiry_date`	datetime	خیر	باید >= `now + 1 minute` باشد

خطاهای رایج: 2027, 2028, 2039, 2007, 2026, 2021.

نمونهJSON

{
    "template_id": "otp_login",
    "parameters": {
        "code": "459122",
        "minutes": 2
    },
    "receptor": "98912****567",
    "local_id": "otp-90001",
    "line_number": "983000XXX",
    "line_selector": 2,
    "expiry_date": "2026-04-04T12:00:00+03:30"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ff9f-f8db-747a-8c31-4d6a954f4a8d",
        "message_id": "0195ff9f-f9cf-7d62-a49e-2ca4db9a90f2",
        "status": 1000,
        "local_id": "otp-90001",
        "line_number": "983000XXX",
        "template_id": "otp_login",
        "send_time": "2026-04-04T11:40:00+03:30",
        "expiry_date": "2026-04-04T12:00:00+03:30",
        "line_selector": 2,
        "cost": 120,
        "receptor": "98912****567",
        "message": "کد ورود شما: ۴۵۹۱۲۲ - اعتبار: ۲ دقیقه",
        "segment_count": 1,
        "parameters": {
            "code": "459122",
            "minutes": 2
        }
    }
}

دریافت Status پیامک

GET/v1/sms/status

گرفتن status تحویل SMS با message ID و/یا local ID.

پارامترهای Query:

پارامتر	نوع	الزامی	توضیحات
`message_ids`	CSV UUID list	خیر	حداقل یکی از `message_ids` یا `local_ids` الزامی است
`local_ids`	CSV string list	خیر	حداقل یکی از `message_ids` یا `local_ids` الزامی است

قوانین:

تعداد یکتای message_ids + local_ids باید <= 2000 باشد.
پارامترها مقدار comma-separated می‌پذیرند.

خطاهای رایج: 2030, 2031, 2003, 2005. هر عضو نامعتبر یا خالی message_ids با 2046 INVALID_MESSAGE_IDS و شماره همان index گزارش می‌شود.

نمونهcURL

curl "https://api.adsefid.com/v1/sms/status?message_ids=0195ff8c-55aa-7e74-a337-c2fd4f6e85c5,0195ff9f-f9cf-7d62-a49e-2ca4db9a90f2&local_ids=order-10001,otp-90001" \
  -H "X-API-KEY: <API_KEY>"

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "receptors": [
            {
                "message_id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
                "local_id": "order-10001",
                "status": 1001,
                "receptor": "98912****567",
                "send_time": "2026-04-04T10:30:00+03:30",
                "delivery_time": null
            }
        ]
    }
}

لغو SMS

POST/v1/sms/cancel

لغو پیام‌های SMS در queue با ID.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`message_ids`	array(UUID)	مشروط	حداقل یکی از `message_ids` یا `local_ids` باید غیرخالی باشد
`local_ids`	array(string)	مشروط	حداقل یکی از `message_ids` یا `local_ids` باید غیرخالی باشد

نکته‌ها:

فقط پیام‌هایی که در queue هستند قابل cancel هستند.
پیام‌هایی که در queue نیستند با status فعلی در failed_to_cancel برگردانده می‌شوند.

نمونهJSON

{
    "message_ids": [
        "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5"
    ],
    "local_ids": [
        "order-10001"
    ]
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "cancelled_messages": [
            {
                "message_id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
                "local_id": "order-10001",
                "status": 1004
            }
        ],
        "failed_to_cancel": []
    }
}

دریافت SMSهای ورودی

GET/v1/sms/receive

دریافت SMSهای inbound برای یک line.

پارامترهای Query:

پارامتر	نوع	الزامی	توضیحات
`line_number`	string	بله	line مجاز برای کاربر
`count`	int	خیر	باید `< 500` باشد (پیش‌فرض `100`)
`since`	datetime	خیر	باید در گذشته باشد

خطاهای رایج: 2024, 2004, 2005.

نمونهcURL

curl "https://api.adsefid.com/v1/sms/receive?line_number=983000XXX&count=50&since=2026-04-04T00:00:00+03:30" \
  -H "X-API-KEY: <API_KEY>"

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "messages": [
            {
                "message": "سلام",
                "line_number": "983000XXX",
                "receive_date": "2026-04-04T09:32:01+03:30",
                "sender": "98912****567"
            }
        ]
    }
}

API پیام‌رسانMessenger API

ارسال تکی Messenger

POST/v1/messenger/single

ارسال یک پیام در messenger.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`message`	string	بله	حداکثر طول 4000
`receptor`	string	بله	شماره تلفن معتبر
`profile`	UUID string	بله	باید برای کاربر جاری موجود باشد
`hide`	bool	خیر	مقدار پیش-فرض `false`
`file_id`	UUID string	خیر	باید توسط کاربر جاری آپلود شده باشد
`send_time`	datetime	خیر	باید >= `now - 1 minute` و داخل send window ارائه‌دهنده باشد
`local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر یکتا

خطاهای رایج: 2040, 2041, 2042, 2007, 2014, 2035, 2022, 2026.

نمونهJSON

{
    "message": "سلام از پیام رسان",
    "receptor": "98912****567",
    "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
    "hide": false,
    "file_id": "18dc580b-c598-4649-b2f4-dde1e5e35a57",
    "send_time": "2026-04-04T11:45:00+03:30",
    "local_id": "m-single-1"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ffa8-3420-73fd-b59d-ec8c5d32c14d",
        "message_id": "0195ffa8-34da-7397-a091-9f36b1d2f7ca",
        "status": 1000,
        "receptor": "98912****567",
        "local_id": "m-single-1",
        "hide": false,
        "cost": 80,
        "send_time": "2026-04-04T11:45:00+03:30",
        "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
        "messenger": "rubika"
    }
}

ارسال گروهی Messenger

POST/v1/messenger/bulk

ارسال یک پیام messenger یکسان برای چند گیرنده.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`receptors`	array	بله	حداقل 1 آیتم
`receptors[].receptor`	string	بله	شماره تلفن معتبر
`receptors[].local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر/request یکتا
`receptors[].hide`	bool	خیر	مقدار پیش-فرض `false`
`message`	string	بله	حداکثر طول 4000
`send_time`	datetime	خیر	باید در بازه زمانی معتبر باشد
`profile`	UUID string	بله	profile فعال برای کاربر جاری
`file_id`	UUID string	خیر	file آپلودشده معتبر

نقض قاعده در سطح آیتم، کل درخواست را رد نمی‌کند؛ به بخش «پذیرش جزئی» مراجعه کنید.

خطاهای رایج: 2040, 2041, 2042, 2024 (رد شدن همه آیتم‌ها)، 2020, 2035, 2022. کد هر آیتم: 2014, 2029, 2007, 2025.

نمونهJSON

{
    "receptors": [
        {
            "receptor": "98912****567",
            "local_id": "mb-1"
        },
        {
            "receptor": "98993****111",
            "local_id": "mb-2"
        }
    ],
    "message": "ارسال گروهی پیام رسان",
    "send_time": "2026-04-04T12:10:00+03:30",
    "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ffac-cb9d-79e0-8ab6-f451afafdf2d",
        "receptors": [
            {
                "message_id": "0195ffac-cc70-72d7-88a6-9f2347305b1b",
                "receptor": "98912****567",
                "local_id": "mb-1",
                "hide": false,
                "status": 1000,
                "cost": 80
            }
        ],
        "message": "ارسال گروهی پیام رسان",
        "send_time": "2026-04-04T12:10:00+03:30",
        "total_count": 1,
        "total_cost": 80,
        "counts": {
            "1000": 1
        },
        "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
        "messenger": "rubika"
    }
}

ارسال P2P Messenger

POST/v1/messenger/p2p

ارسال پیام‌های سفارشی messenger برای هر گیرنده.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`receptors`	array	بله	حداقل 1 آیتم
`receptors[].receptor`	string	بله	شماره تلفن معتبر
`receptors[].message`	string	بله	حداکثر طول 4000
`receptors[].local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه
`receptors[].hide`	bool	خیر	مقدار پیش-فرض `false`
`send_time`	datetime	خیر	بازه ارسال معتبر
`profile`	UUID string	بله	profile فعال
`file_id`	UUID string	خیر	file آپلودشده معتبر

نقض قاعده در سطح آیتم، کل درخواست را رد نمی‌کند؛ به بخش «پذیرش جزئی» مراجعه کنید.

خطاهای رایج: 2040, 2041, 2042, 2024 (رد شدن همه آیتم‌ها)، 2020, 2035, 2022. کد هر آیتم: 2014, 2029, 2007, 2013, 2016, 2025, 2026.

نمونهJSON

{
    "receptors": [
        {
            "receptor": "98912****567",
            "message": "سلام علی",
            "local_id": "mp2p-1"
        },
        {
            "receptor": "98993****111",
            "message": "سلام رضا",
            "local_id": "mp2p-2"
        }
    ],
    "send_time": "2026-04-04T12:30:00+03:30",
    "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ffb2-aa5e-7d42-953a-18f34d2f71e1",
        "receptors": [
            {
                "message_id": "0195ffb2-ab31-73f5-b8d7-afe7b7d2f1fd",
                "receptor": "98912****567",
                "message": "سلام علی",
                "local_id": "mp2p-1",
                "hide": false,
                "status": 1000,
                "cost": 80
            }
        ],
        "send_time": "2026-04-04T12:30:00+03:30",
        "total_count": 1,
        "total_cost": 80,
        "counts": {
            "1000": 1
        },
        "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
        "messenger": "bale"
    }
}

آپلود File در Messenger

POST/v1/messenger/file

آپلود media file برای messenger و دریافت file_id قابل استفاده مجدد.

درخواست:

Content type: multipart/form-data
Field name: file
محدودیت‌ها:
حداکثر size: 15 MB
فایل‌های مجاز:
- تصویر: image/jpeg, image/png, image/gif
- مستند: application/pdf
- صوت: audio/mpeg, audio/mp4, audio/aac, audio/ogg, audio/webm, audio/wav, audio/x-wav, audio/flac, audio/opus
- ویدیو: video/mp4, video/webm, video/ogg, video/quicktime, video/x-msvideo, video/x-matroska

خطاهای رایج: 2043, 2047 (بیش از 15 مگابایت)، 2001, 2018.

نمونهcURL

curl -X POST "https://api.adsefid.com/v1/messenger/file" \
  -H "X-API-KEY: <API_KEY>" \
  -F "file=@./brochure.pdf"

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "file_id": "18dc580b-c598-4649-b2f4-dde1e5e35a57"
    }
}

لغو پیام Messenger

POST/v1/messenger/cancel

لغو پیام‌های messenger در queue.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`message_ids`	array(UUID)	مشروط	حداقل یکی از `message_ids` یا `local_ids`
`local_ids`	array(string)	مشروط	حداقل یکی از `message_ids` یا `local_ids`

خطاهای رایج: 2029, 2022. در 2029، کلیدهای details.errors همان idهای ردشده و مقدار هر کدام 2029 INVALID_LOCAL_IDS است.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "cancelled_messages": [
            {
                "message_id": "0195ffa8-34da-7397-a091-9f36b1d2f7ca",
                "local_id": "m-single-1",
                "status": 1004
            }
        ],
        "failed_to_cancel": []
    }
}

ارسال Template پیام‌رسان

POST/v1/messenger/template

ارسال template تاییدشده از طریق messenger profile.

بدنه درخواست:

فیلد	نوع	الزامی	توضیحات
`template_id`	string	بله	باید برای کاربر تایید شده باشد
`parameters`	object	بله	باید placeholderهای template را کامل کند
`receptor`	string	بله	شماره تلفن معتبر
`local_id`	string	خیر	۱ تا ۳۶ حرف/عدد ASCII؛ `- _ . :` فقط در میانه؛ برای هر کاربر یکتا
`profile`	UUID string	بله	profile فعال
`expiry_date`	datetime	خیر	باید >= `now + 1 minute` باشد

خطاهای رایج: 2027, 2028, 2040, 2041, 2007, 2026, 2021.

نمونهJSON

{
    "template_id": "invoice_notice",
    "parameters": {
        "invoice_id": "INV-1043",
        "amount": "250000"
    },
    "receptor": "98912****567",
    "local_id": "mt-1",
    "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
    "expiry_date": "2026-04-04T13:00:00+03:30"
}

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "group_id": "0195ffb8-ef3d-71d8-ba37-a5f6bd8fc603",
        "message_id": "0195ffb8-f03f-74d0-a97d-e90ae2f2b2d0",
        "status": 1000,
        "local_id": "mt-1",
        "template_id": "invoice_notice",
        "send_time": "2026-04-04T12:50:00+03:30",
        "expiry_date": "2026-04-04T13:00:00+03:30",
        "cost": 80,
        "receptor": "98912****567",
        "message": "فاکتور INV-1043 به مبلغ 250000 آماده است",
        "profile": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
        "messenger": "rubika",
        "parameters": {
            "invoice_id": "INV-1043",
            "amount": "250000"
        }
    }
}

دریافت Status پیام‌رسان

GET/v1/messenger/status

گرفتن status پیام messenger با message_ids و/یا local_ids.

پارامترهای Query:

message_ids: comma-separated UUID list
local_ids: comma-separated string list

قوانین:

حداقل یکی از دو param الزامی است.
حداکثر تعداد ID یکتا در هر request برابر 2000 است.

خطاهای رایج: 2030, 2031, 2003, 2005. هر عضو نامعتبر یا خالی message_ids با 2046 INVALID_MESSAGE_IDS و شماره همان index گزارش می‌شود.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "receptors": [
            {
                "message_id": "0195ffa8-34da-7397-a091-9f36b1d2f7ca",
                "local_id": "m-single-1",
                "status": 1002,
                "receptor": "98912****567",
                "send_time": "2026-04-04T11:45:00+03:30",
                "delivery_time": "2026-04-04T11:45:08+03:30"
            }
        ]
    }
}

API کاربرUser API

دریافت اطلاعات Account

GET/v1/user/info

دریافت اطلاعات account کاربر احراز هویت‌شده.

خطاهای رایج: 2018.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "name": "علی رضایی",
        "company_name": "شرکت نمونه",
        "credit_left": 1250000,
        "email": "john@example.com",
        "phone": "98912****567",
        "account_status": "active"
    }
}

دریافت Lineهای کاربر

GET/v1/user/lines

دریافت همه lineهای ارسال‌کننده در دسترس برای کاربر احراز هویت‌شده.

خطاهای رایج: 2005, 2000.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": [
        {
            "line_number": "983000XXX",
            "line_selector": 0,
            "line_name": "Main Promotional",
            "enabled": true
        },
        {
            "line_number": "985000XXX",
            "line_selector": 2,
            "line_name": "Service Bulk",
            "enabled": false
        }
    ]
}

دریافت Profileهای کاربر

GET/v1/user/profiles

دریافت messenger profileهای در دسترس برای کاربر احراز هویت‌شده.

خطاهای رایج: 2005, 2000.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": [
        {
            "id": "b72ea7f4-44b4-4f5e-91ef-91816ae5f88a",
            "name": "پشتیبانی روبیکا",
            "messenger": "rubika"
        }
    ]
}

دریافت Templateهای کاربر

GET/v1/user/templates

پارامترهای Query:

فیلد	نوع	الزامی	قواعد
`state`	string	خیر	یکی از `pendingapproval`، `approved` یا `rejected`؛ فقط با حروف کوچک
`skip`	int	خیر	مقدار پیش‌فرض `0`؛ باید نامنفی باشد
`take`	int	خیر	مقدار پیش‌فرض `50`؛ باید بین `1` و `100` با احتساب دو سر باشد

خطاهای رایج: 2018 برای API key ناموجود یا نامعتبر؛ 2024 برای state، skip یا take نامعتبر.

نمونه پاسخ موفقJSON

{
    "status": "success",
    "data": {
        "items": [
            {
                "template_id": "payment-notice",
                "content": "Code: {{OTPCode:string}}, amount: {{amount:number}}",
                "parameters": {
                    "OTPCode": "string",
                    "amount": "number"
                },
                "state": "approved",
                "description": null,
                "created_at": "2026-09-02T10:30:00+03:30",
                "updated_at": "2026-09-02T11:00:00+03:30"
            }
        ],
        "total": 1
    }
}

نمونه صفحه خالیJSON

{
    "status": "success",
    "data": {
        "items": [],
        "total": 0
    }
}

وب‌هوک‌های خروجیOutgoing Webhooks

رویدادهاEvents

پلتفرم سه نوع رویداد پشتیبانی می‌کند:

پیام‌های دریافتی (receive)
تغییر وضعیت پیام‌های SMS (status)
تغییر وضعیت پیام‌های Messenger (messenger.status)

درخواست HTTPHTTP Request

Method: POST
Content-Type: application/json
Timeout: 10 seconds
شرط موفقیت: هر پاسخ 2xx

هدرهای ارسالی:

هدر	توضیح
`X-Atlas-Webhook-Id`	UUID عمومی delivery وب‌هوک
`X-Atlas-Webhook-Event`	نام event (`receive`، `status` یا `messenger.status`)
`X-Atlas-Webhook-Attempt`	شماره attempt (از 1 شروع می‌شود)
`X-Atlas-Webhook-Timestamp`	Unix timestamp (برحسب ثانیه)
`X-Atlas-Webhook-Signature`	فرمت signature: `v1=<base64_hmac_sha256>`
`User-Agent`	`AtlasSMS-Webhooks/1.0`

اعتبارسنجی امضاSignature Verification

الگوریتم:

اجرای HMAC-SHA256 با secret bytes مربوط به webhook endpoint
تبدیل خروجی به Base64
مقایسه با مقدار Header بعد از حذف پیشوند v1=

مهم:

اعتبارسنجی را روی raw body bytes دقیق انجام دهید.
timestamp های قدیمی را طبق replay policy رد کنید.
اکیدا توصیه می‌شود پیش از پردازش payload، signature + timestamp هر webhook request اعتبارسنجی شود.

ورودی امضاText

<timestamp>.<raw_request_body>

شبه-کدText

hex = HMAC_SHA256( $"{timestamp}.{raw_body}", secret )
base64 = BASE64(hex_to_bytes(hex))
expected_signature = "v1=" + base64

Payload رویداد ReceiveReceive Event Payload

Header:

X-Atlas-Webhook-Event: receive

BodyJSON

{
    "id": "0195ffd0-7e08-7d4d-8eef-dd4f7ca5e6fd",
    "type": "receive",
    "occurred_at": "2026-04-04T12:00:00+03:30",
    "attempt": 1,
    "version": "1",
    "data": [
        {
            "id": 1543201,
            "line_number": "983000XXX",
            "sender": "98912****567",
            "message": "سلام",
            "receive_date": "2026-04-04T11:59:58+03:30"
        }
    ]
}

Payload رویداد Status UpdateStatus Update Event Payload

Header:

X-Atlas-Webhook-Event: status

BodyJSON

{
    "id": "0195ffd2-76d4-7d10-9d40-c0d2fc61f774",
    "type": "status",
    "occurred_at": "2026-04-04T12:05:00+03:30",
    "attempt": 1,
    "version": "1",
    "data": [
        {
            "id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
            "local_id": "order-10001",
            "status_delivery": 1002,
            "delivery_time": "2026-04-04T12:04:54+03:30"
        }
    ]
}

Payload رویداد Messenger StatusMessenger Status Event Payload

Header:

X-Atlas-Webhook-Event: messenger.status

BodyJSON

{
    "id": "0195ffd2-76d4-7d10-9d40-c0d2fc61f774",
    "type": "messenger.status",
    "occurred_at": "2026-04-04T12:05:00+03:30",
    "attempt": 1,
    "version": "1",
    "data": [
        {
            "id": "0195ff8c-55aa-7e74-a337-c2fd4f6e85c5",
            "local_id": "order-10001",
            "status_delivery": 1002,
            "delivery_time": "2026-04-04T12:04:54+03:30"
        }
    ]
}

رفتار Retry و تحویلRetry and Delivery Behavior

در صورت fail شدن attempt، retry با backoff انجام می‌شود: 5s، 60s، 120s، 360s، 600s، سپس 900s.
تلاش مجدد تا رسیدن به max attempts مربوط به endpoint ادامه می‌یابد.
پس از رسیدن به max attempts، وضعیت delivery برابر dead می‌شود و retry دیگری انجام نمی‌شود.
از delivery-item تکراری در سطح storage جلوگیری می‌شود.
وب‌هوک‌های Receive در هر delivery حداکثر به 100 آیتم chunk می‌شوند.

توصیه‌های استفاده کننده:

با X-Atlas-Webhook-Id + event item ID handler را به‌صورت idempotent طراحی کنید.
پاسخ 2xx را سریع برگردانید؛ در صورت امکان پردازش را asynchronous انجام دهید.

کیت‌های توسعهٔ رسمیSDK

نسخهٔ آزمایشی: هر پنج کیت توسعه در حال حاضر در مرحلهٔ بتا هستند. این کتابخانه‌ها همهٔ امکانات رابط برنامه‌نویسی شرح‌داده‌شده در این مستند را پوشش می‌دهند، اما ممکن است رابط برنامه‌نویسی آن‌ها پیش از انتشار نسخهٔ 1.0 به‌شکلی ناسازگار با نسخه‌های قبلی تغییر کند. نسخهٔ دقیق هر کتابخانه را در فایل وابستگی‌های پروژه ثابت کنید و پیش از ارتقا، یادداشت‌های انتشار مخزن مربوط را بخوانید. خود رابط برنامه‌نویسی REST پایدار است و آزمایشی بودن کیت‌های توسعه اثری بر آن ندارد. مشکلات هر کتابخانه را در مخزن همان کتابخانه گزارش کنید.

بسته‌ها

زبان	بسته	دستور نصب	کد منبع
.NET 8+	`Adsefid.Sdk` (NuGet)	`dotnet add package Adsefid.Sdk`	adsefid/sdk-dotnet
Python 3.10+	`adsefid` (PyPI)	`pip install adsefid`	adsefid/sdk-python
Node.js 18+ (JS/TS)	`@adsefid/sdk` (npm)	`npm install @adsefid/sdk`	adsefid/sdk-js
PHP 8.2+	`adsefid/sdk` (Packagist)	`composer require adsefid/sdk`	adsefid/sdk-php
Go 1.22+	`github.com/adsefid/sdk-go`	`go get github.com/adsefid/sdk-go`	adsefid/sdk-go

نکته‌ها:

کتابخانهٔ PHP به یک کلاینت HTTP سازگار با PSR-18 نیز نیاز دارد؛ برای نمونه: composer require guzzlehttp/guzzle.
کتابخانهٔ JavaScript فقط برای اجرا در سمت سرور است. این کتابخانه کلید محرمانهٔ رابط برنامه‌نویسی شما را در اختیار دارد؛ بنابراین هرگز نباید همراه کد سمت مرورگر بسته‌بندی شود.

رفتار مشترک

همهٔ این کتابخانه‌ها به‌طور پیش‌فرض از نشانی پایهٔ https://api.adsefid.com استفاده می‌کنند و هدر X-API-KEY را با هر درخواست می‌فرستند. نشانی پایه، هدر User-Agent، مهلت پاسخ و کلاینت زیربنایی HTTP قابل تنظیم‌اند.
هیچ‌یک از این کتابخانه‌ها متغیرهای محیطی را به‌طور ضمنی نمی‌خواند. کلید رابط برنامه‌نویسی را در برنامهٔ خود بخوانید و آن را صریحاً به کلاینت بدهید.
خطاها به‌صورت نوع‌دار برگردانده می‌شوند و کد عددی WebServiceResponseCode و نام نمادین آن را در اختیار می‌گذارند. برای محدودیت نرخ درخواست، خطاهای اعتبارسنجی و خطاهای ارتباطی، نوع خطای جداگانه‌ای وجود دارد.

ابزارهای بررسی وب‌هوک

زبان	تابع
.NET	`WebhookVerifier.VerifyAndParse(rawBody, signature, timestamp, secret)`
Python	`verify_and_parse_webhook(raw_body, signature_header, timestamp_header, secret)`
JavaScript / TS	`verifyAndParseWebhook({ rawBody, signatureHeader, timestampHeader, secret })`
PHP	`(new WebhookVerifier($secret))->verifyAndParse($rawBody, $signature, $timestamp)`
Go	`webhooks.Verify(rawBody, signature, timestamp, secret)`

نکات یکپارچه‌سازیIntegration Notes

کوئری پارامترهای message_ids و local_ids از مقادیر comma-separated پشتیبانی می‌کنند.
یکتایی local_id به ازای هر کاربر و channel enforce می‌شود.
اندپوینت‌های Status ممکن است پیام‌های تازه accepted شده را قبل از persistence کامل در DB از cache کوتاه‌عمر برگردانند.
عملیات Cancel وابسته به وضعیت queue است: پیام‌های already-sent/in-progress در failed_to_cancel برمی‌گردند.
خطاهای model-binding از envelope استاندارد استفاده می‌کنند و خطای هر فیلد زیر error.details.errors برمی‌گردد.