پیامک تایید (OTP)

ارسال کد تایید

کد تایید یا هر پیام کوتاه قالب‌دار را با یک قالب از پیش تاییدشده می‌فرستد. فقط مقدار توکن‌ها را ارسال می‌کنید و متن از قالب ساخته می‌شود؛ این مسیر از صف پیامک‌های تبلیغاتی جداست.

GET POST
https://api.payamras.ir/v1/YOUR_API_KEY/verify/lookup.json
  • قالب باید از قبل ساخته و تایید شده باشد (بخش «قالب‌های تایید»).
  • توکن‌های token تا token3 نباید فاصله داشته باشند. token10 تا ۵ فاصله و token20 تا ۸ فاصله را می‌پذیرد.
  • اگر گیرنده تلفن ثابت باشد، پیام به‌صورت خودکار به تماس صوتی تبدیل می‌شود.

پارامترها

نامنوعتوضیح
receptor الزامی String شماره گیرنده. شماره بین‌المللی را با پیشوند 00 و کد کشور بنویسید.
template الزامی String نام قالب تاییدشده.
token الزامی String مقدار جایگزین %token در قالب. حداکثر ۱۰۰ کاراکتر، بدون فاصله.
token2 اختیاری String مقدار %token2. حداکثر ۱۰۰ کاراکتر، بدون فاصله.
token3 اختیاری String مقدار %token3. حداکثر ۱۰۰ کاراکتر، بدون فاصله.
token10 اختیاری String مقدار %token10. حداکثر ۱۰۰ کاراکتر و ۵ فاصله.
token20 اختیاری String مقدار %token20. حداکثر ۱۰۰ کاراکتر و ۸ فاصله.
type اختیاری String sms (پیش‌فرض) یا call برای تماس صوتی. تماس صوتی فقط برای توکن عددی ممکن است.
tag اختیاری String برچسب دسته‌بندی گزارش.

نمونه درخواست

curl -G "https://api.payamras.ir/v1/YOUR_API_KEY/verify/lookup.json" \
  --data-urlencode "receptor=09121234567" \
  --data-urlencode "template=login" \
  --data-urlencode "token=4821"

پاسخ

فیلدهای هر ردیف entries:

فیلدنوعتوضیح
messageid Long شناسه یکتای پیام؛ برای پیگیری وضعیت ذخیره کنید.
message String متن پیام.
status Integer وضعیت پیام (صفحه وضعیت پیام‌ها).
statustext String شرح وضعیت.
sender String خط فرستنده.
receptor String شماره گیرنده.
date UnixTime زمان ثبت یا زمان‌بندی ارسال.
cost Integer هزینه پیام به ریال.
response.json
{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 8792360,
            "message": "کد ورود شما: 4821\nپیام‌رس",
            "status": 5,
            "statustext": "ارسال به مخابرات",
            "sender": "10004346",
            "receptor": "09121234567",
            "date": 1760337000,
            "cost": 1200
        }
    ]
}

خطاهای رایج

علاوه بر خطاهای عمومی مثل 403 و 418، این متد ممکن است این کدها را در return.status برگرداند:

  • 418 اعتبار حساب کافی نیست.
  • 422 داده‌ها به دلیل کاراکتر نامناسب قابل پردازش نیستند.
  • 424 قالب پیدا نشد.
  • 426 استفاده از این متد به سرویس پیشرفته نیاز دارد.
  • 428 ارسال کد با تماس صوتی برای این توکن ممکن نیست.
  • 431 فرمت توکن نامعتبر است.
  • 432 پارامتر %token در متن قالب پیدا نشد.
  • 607 نام برچسب (tag) نامعتبر است.