معرفی REST API

همان طور که شاید تا به حال شنیده باشید API مخفف عبارت Application Programming Interface می‌باشد که به برنامه نویسان امکان رد و بدل کردن اطلاعات مابین پلتفرم های مختلف را از طریق ارسال یک درخواست HTTP(S) ساده و فراخوانی متد های مورد نظر می‌دهد

در واقع REST یک روش ساده و انعطاف پذیری برای استفاده از API است و البته محبوب ترین و پر کاربرد ترین که می‌توان توسط این ساختار از هر کلاینت و پلتفرمی ‌درخواست ساده HTTP(S) را ارسال و پاسخ آن را دریافت نمود.
حال فرض کنید در خواست مورد نظر اطلاعات مربوط به ارسال یک پیامک باشد و جواب آن نتیجه و وضعیت پیامک ارسالی باشد.
وب سرویس ارسال پیامک کاوه نگار شماره گیرنده ، متن پیامک و شماره فرستنده را از طریق پارامتر های ورودی در متد GET یا POST دریافت می‌کند و خروجی را در غالب فرمت های XML و JSON برگشت می‌دهد.
نکته : اگر با JSON آشنائی ندارید می‌توانید با مراجعه به سایت json.org هم از ساختار فرمت آن مطلع شوید و هم درایور مربوط به زبان برنامه نویسی مورد نظر خود را دریافت نمائید.

شروع

قبل از آن که در مورد ساختار خروجی متد ها توضیح دهیم این متد را باهم اجرا کنیم :

https://api.kavenegar.com/v1/0/utils/getdate.json
{
    "return":
    {
        "status":200,
        "message":"تایید شد"
    },
    "entries":
    {
        "datetime":"02/06/2012 01:53:46 ب.ظ",
        "year":2012,
        "month":1,
        "day":26,
        "hour":13,
        "minute":53,
        "second":46,
        "unixtime":1338645226
    }
}
در صورتی که مایل هستید بافرمت XML خروجی را دریافت کنید کافیست پسوند آدرس مورد نظر را از JSON به XML تغییر دهید.

این متد تاریخ و زمان سرور کاوه نگار و همچنین زمان معادل آن به فرمت UnixTime را به شما نشان می دهد.
کلیه فیلدهای مربوط به تاریخ در وب سرویس کاوه نگار به فرمت UnixTime می‌باشد. دلیل استفاده از این فرمت جلوگیری از بروز خطا در هنگام پردازش آنهاست. برای آشنائی با فرمت UnixTime می‌توانید به اینجا مراجعه کنید و همچنین نمونه کد تبدیل آن را برای زبان های برنامه نویسی مختلف از اینجا دریافت کنید.

فرمت فراخوانی متد ها

https://api.kavenegar.com/v1/{API-KEY}/Scope/MethodName.OutputFormat

در صورتی که برای تست وب سرویس کاوه نگار API-KEY ندارید می‌توانید از این بخش ثبت نام کنید و ۱۰,۰۰۰ ریال هم اعتبار هدیه دریافت کنید.

شناسائی و اعتبار سنجی حساب کاربری Authorization در سرویس کاوه نگار توسط رشته API-KEY انجام می‌شود.

فراخوانی متد ها از طریق لایه SSL امکان پذیر است.

خطا های مربوط به حساب کاربری

401 حساب کاربری غیر فعال است
403 حساب کاربری معتبر نمی‌باشد. این خطا در صورتی که کد شناسائی API-Key اشتباه ارسال شود رخ می‌دهد

ساختار خروجی

مسلما بعد از اجرای هر متد نیاز است نتیجه حاصل از اجرای آن را دریافت و پردازش کنید. سرویس کاوه نگار برای سهولت این موضوع از دو فرمت خروجی رایج JSON و XML استفاده نموده است. نتیجه حاصل از فراخوانی متد را توسط جدول کدهای برگشتی در Http Status Code برگشت داده می‌شود. برای مثال در صورتی که متد مورد نظر وجود نداشته باشد مقدار 404 در Status Code قرار می‌گیرد. علاوه بر آن ساختار خروجی هم این خطا را نشان می‌دهد برای مثال به خروجی زیر لطفا توجه نمائید.

{
    "return":
    {
        "status":404,
        "message":"متد تعریف نشده است"
    },
    "entries":
    {
        null
    }
}

Status : کد حاصل از اجرای متد که نشان دهنده اجرای موفق یا ناموفق آن است. در صورتی که مقدار آن 200 باشد به معنای اجرای درست متد است و در غیر اینصورت باید به جدول شماره 1 کدهای برگشتی مراجعه نمائید.
Message : توضیح مربوط به کد می‌باشد.

خطا های احتمالی در هنگام اجرای متد ها

400 پارامترها ناقص هستند
402 عملیات ناموفق بود
404 متدی با این نام پیدا نشده است
405 متد فراخوانی Get یا Post اشتباه است
409 سرور قادر به پاسخگوئی نیست بعدا تلاش کنید

ساختار پیام کوتاه

طول پیامک

طول استاندارد یک پیام کوتاه 140 ﺑﺎﻳﺖ که معادل 70 کاراکتر برای یک پیامک فارسی و 140 کاراکتر برای یک پیامک لاتین و 140 بایت برای پیامک باینری می‌باشد بنابراین هر کاراکتر فارسی معادل 2 بایت محاسبه می‌شود. این موضوع به دلیل گنجاندن کاراکتر های فارسی در فرمت یونیکد می‌باشد که با وجود حتی یک کاراکتر فارسی در پیامک باعث می‌شود تا طول آن بر حسب فرمت یونیکد (هر کاراکتر 2 بایت) محاسبه شده و پیامک فارسی شود (پیامک های فارسی ارزان تر از پیامک های لاتین هستند).

پیامک های چند بخشی

در صورتی که پیامک از طول استاندارد 140 بایت بیشتر شود باید به بخش های 140 بایتی تقسیم شده و سپس به مقصد ارسال شود که البته این کار توسط وب سرویس موجود انجام می‌شود و نیاز نیست برای این موضوع عملیاتی انجام دهید کافیست کل پیام را در فراخوانی وب سرویس ارسال نمائید. البته به این موضوع باید توجه داشت که به ازای هر بخش از یک پیامک فارسی طولانی، 3 کاراکتر و به ازای هر بخش از کی پیامک لاتین طولانی ،7 کاراکتر از فضای استاندارد متین پیامک به کد UDH اختصاص پیدا میکند.یعنی در واقع هر بخش از پیامک چند قسمتی فارسی حداکثر 67 کاراکتروهربخش ازپیامک چند قسمتی لاتین حداکثر 153 کاراکتررادرخودجای می‌دهد.

ﺣﺪاﻛﺜﺮ ﻃﻮل پیامک

حداکثر طول کل متن پیامک برای پیامک لاتین 612 ﻛﺎراﻛﺘﺮ و ﺑﺮاي پیامک فارسی 268 ﻛﺎراﻛﺘﺮ میباشد. درصورتی که بیشتر از این مقدار ارسال شود مقدار پارامتر Status معادل 413 به معنای "متن پیام خالی است و یا طول آن بیشتر از حد مجاز می‌باشد" را برگشت می‌دهد. علاوه بر این موضوع در هر بار فراخوانی متدهای ارسال پیامک می‌توانید حداکثر 200 پیامک ارسال کنید. این محدودیت برای حفظ کیفیت در ارسال و سرعت پاسخگوئی قرارداده شده است همچنین در هر بار فراخوانی متدهای کنترل وضعیت Status و انصراف از ارسال پیامک Cancel می‌توانید حداکثر 500 شناسه را در ورودی قرار دهید.

خطای مربوط به حداکثر رکورد درخواستی در هر بار فراخوانی

414 حجم درخواست بیشتر از حد مجاز است
در ارسال پیامک هر فراخوانی 200 رکورد و کنترل وضعیت هر فراخوانی 500 رکورد

توجه : شما می‌توانید با فراخوانی متد ها از طریق ساختار Multi-Threaded میزان درخواست همزمان خود را افزایش دهید. موضوع محدودیت مربوط به تعداد در هر بار فراخوانی (Per Request) می‌باشد.

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

در طراحی وب سرویس کاوه نگار سعی شده تا جای ممکن نسبت به داده های ورودی حساسیت وجود نداشته باشد در نهایت پارامتر ها با فرمت زیر قابل تشخیص هستند در غیر اینصورت احتمال دریافت کد خطا در داده های ورودی وجود دارد.
در هنگام ارسال درخواست با متد HTTP GET حتما مقدار پارامتر ها را URL Encode نمائید.

فرمت درست خط اختصاصی فرستنده (این شماره به عنوان مثال قید شده است)

+9810004346
009810004346
10004346

فرمت درست شماره گیرنده (این شماره به عنوان مثال قید شده است)

09121234567
00989121234567
+989121234567
9121234567

متن پیام URL Encode شده معادل "خدمات پیام کوتاه کاوه نگار" message=%D8%AE%D8%AF%D9%85%D8%A7%D8%AA%20%D9%BE%DB%8C%D8%A7%D9%85%20%DA%A9%D9%88%D8%AA%D8%A7%D9%87%20%DA%A9%D8%A7%D9%88%D9%87%20%D9%86%DA%AF%D8%A7%D8%B1

خطاهای مربوط به فرمت اشتباه گیرنده و فرستنده و متن پیامک

411 شماره گیرنده پیام معتبر نمی باشد
412 شماره فرستنده معتبر نمی‌باشد
413 پیام خالی است و یا طول پیام بیش از حد مجاز می‌باشد
لاتین 612 ﻛﺎراﻛﺘﺮ و ﻓﺎرسی 268 ﻛﺎراﻛﺘﺮ
414 تعداد رکورد ها بیشتر از حد مجاز است
در ارسال پیامک حداکثر 200 گیرنده در کنترل وضعیت حداکثر 500 شناسه

Sendارسال ساده

از این متد برای ارسال پیامک استفاده می کنیم که امکان ارسال یک پیامک خاص به چندین گیرنده (Receptor) در این متد وجود دارد کافیست آنها را از طریق کاراکتر ویرگول « , » از هم جدا کنید.

ساختار URL

https://api.kavenegar.com/v1/{API-KEY}/sms/send.json

پارامترهای ورودی

پارامتر نوع نوع توضیح
receptor اجباری String شماره دریافت کننده پیامک را مشخص می کند که می توان با کاراکتر ویرگول « , » آنها را از هم جدا کرد
message اجباری String متن پیام کوتاه ، متن مورد نظر را در حالت POST یا GET حتما باید Encode کنید
sender اختیاری String شماره خط ارسال کننده پیام
date اختیاری UnixTime زمان ارسال پیام ( در صورتی که خالی باشد پیام به صورت خودکار در همان لحظه ارسال می‌شود )
type اختیاری String نوع پیام در گوشی گیرنده می‌باشد (جدول شماره 3) فقط برای خطوط 3000 امکان پذیر است
localid اختیاری String شناسه محلی در پایگاه داده های شما است ، اطلاعات بیشتر در بخش یادداشت نوشته شده
hide اختیاری byte اگر مقداری عددی پارامتر hide برابر 1 باشد شماره گیرنده در فهرست ارسال ها و کنسول وب نمایش داده نمی شود.

پارامترهای خروجی

پارامتر نوع توضیح
messageid Long شناسه یکتای این پیامک (برای اطلاع از وضعیت پیامک ارسالی این مقدار ورودی متد Status می‌باشد.)
message Integer متن پیام ارسال شده
status Integer وضعیت عددی این پیامک (اطلاعات بیشتر جدول وضعیت پیامک ها)
statustext String متن توضیح وضعیت عددی این پیامک (اطلاعات بیشتر جدول وضعیت پیامک ها)
sender String شماره فرستنده
receptor String شماره گیرنده
date UnixTime زمان ارسال این پیامک به فرمت UnixTime
cost Integer هزینه این پیامک ( ریال)

یادداشت

  • در صورت عدم ارسال پارامتر Sender پیامک با ارسال کننده پیش فرض (حساب کاربری) ارسال خواهد شد
  • برای اطلاع از وضعیت پیامک به جدول وضعیت پیامک ها مراجعه نمایید
  • برای دریافت اطلاعات و نحوه کار با تاریخ به فرمت UnixTime اینجا مراجعه نمایید
  • در مورد شناسه محلی LocalId به چند نکته توجه نمائید :
    • به وسیله مقداردهی به این پارامتر می‌توانید از ارسال پیامک تکراری جلوگیری نمائید
    • در صورت مقداردهی ،تعداد آن باید برابر تعداد گیرنده باشد و با کاراکتر ویرگول « , » آنها را از هم جدا کنید
    • در صورت وجود این شناسه محلی localid در لیست ارسال های شما، ارسال تکراری انجام نمی‌شود و رکورد مربوط به این شناسه در خروجی قرار خواهد گرفت
  • پارامتر اختیاری hide زمانی استفاده می شود که شما نیاز به این دارید که افراد دیگری که به پنل شما دسترسی دارند نتوانند شماره گیرنده را مشاهده نمایند.

جدول خطا ها

نوع توضیح
414 تعداد دریافت کننده ها (Receptor) بیشتر از 200 است
417 تاریخ ارسال اشتباه است یا تاریخ آن گذشته و یا به فرمت درست ارسال نشده است
418 اعتبار حساب شما کافی نیست

درخواست

https://api.kavenegar.com/v1/613472435563797A37677331D/sms/send.json?receptor=09125258596,09128585774&sender=10004346&message=test

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 8792343,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "status": 1,
            "statustext": "در صف ارسال",
            "sender": "10004346",
            "receptor": "09125258596",
            "date": 1356619709,
            "cost": 120
        },
        {
            "messageid": 8792344,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "status": 1,
            "statustext": "در صف ارسال",
            "sender": "10004346",
            "receptor": "09128585774",
            "date": 1356619709,
            "cost": 120
        }
    ]
}

        

SendArrayارسال گروهی

اگر می‌خواهید چندین پیامک مختلف را از شماره های مختلف ارسال کنید ، این متد کارائی زیادی برای شما دارد. نکته قابل توجه در استفاده از این متد آن است که مقادیر به صورت آرایه (فرمت Json) دریافت می شوند و باید تعداد اجزا آرایه ها با هم برابر باشد.
برای مثال :
3 ارسال کننده، 3 پیام، 3 گیرنده، علاوه بر این متد فراخوانی حتما باید POST باشد.

پارامترهای ورودی

receptor اجباری Array of String شماره های دریافت کنندگان پیام
sender اجباری Array of String شماره خط های ارسال کننده پیام
message اجباری Array of String متن پیام کوتاه ، بهتر است هر متن پیامک را در حالت POST حتما HTML-Encode شود ، برای بحث (Delimeters)
date اختیاری UnixTime زمان ارسال پیام ( در صورتی که خالی باشد پیام به صورت خودکار در همان لحظه ارسال می‌شود )
type اختیاری Array of Integer نوع پیام در گوشی گیرنده می‌باشد (جدول شماره 3) فقط برای خطوط 3000 امکان پذیر است.
localmessageid اختیاری Array of String شناسه این پیامک در پایگاه داده های شما است، اطلاعات بیشتر در بخش یادداشت نوشته شده
hide اختیاری byte اگر مقداری عددی پارامتر hide برابر 1 باشد شماره گیرنده در فهرست ارسال ها و کنسول وب نمایش داده نمی شود.

پارامترهای خروجی

خروجی آرایه ای از ساختار زیر خواهد بود .
messageid Long شناسه یکتای این پیامک
برای اطلاع از وضعیت پیامک ارسالی این مقدار را به متد Status ارسال نمائید.
message Integer متن پیام ارسال شده
status Integer وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
statustext String متن توضیح وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
sender String شماره فرستنده
receptor String شماره گیرنده
date UnixTime زمان ارسال این پیامک به فرمت UnixTime
cost Integer هزینه این پیامک ( ریال)

یادداشت

  • برای مشاهده مقادیر ورودی به بخش مثال مراجعه نمائید
  • تعداد گیرندگان و خط ارسال کننده و پیام ها که به صورت آرایه ارسال شده اند باید با هم برابر باشد
  • برای مشاهده جدول نوع پیامک ها در گوشی گیرنده به جدول نوع نمایش پیامک مراجعه کنید
  • در مورد localmessageid به چند نکته توجه نمائید :
    • با مقدار دادن به این پارامتر می‌توانید از ارسال پیامک تکراری جلوگیری نمائید
    • تعداد مقادیر باید برابر تعداد گیرنده باشد. با کاراکتر ویرگول « , » آنها را از هم جدا کنید زیرا به صورت یکسان با تعداد گیرندگان کنترل می‌شود
    • در صورت وجود شناسه ( localmessageid) در ارسال های قبلی شما، ارسال تکراری انجام نمی‌شود و رکورد مربوط به این شناسه در خروجی قرار خواهد گرفت
  • پارامتر اختیاری hide زمانی استفاده می شود که شما نیاز به این دارید که افراد دیگری که به پنل شما دسترسی دارند نتوانند شماره گیرنده را مشاهده نمایند.

خطاها

405 متد Get/Post اشتباه است. (این متد فقط با متد فراخوانی POST قابل اجرا می‌باشد)
412 تعداد دریافت کننده ها بیشتر از 200 می‌باشد .
417 تاریخ اشتباه است .
418 اعتبار کافی نیست .
419 تعداد اعضای آرایه متن و گیرنده و ارسال کننده هم اندازه نیست .

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/sendarray.json

پارامتر ها ارسال شده

receptor=["09121321111","09121230000","09123210000"]
sender=["30002626","30002627","30002727"]
message=["وب سرویس ارسال","وب سرویس پیامک","کاوه نگار"]

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 8792343,
            "message": "کاوه نگار",
            "status": 1,
            "statustext": "در صف ارسال",
            "sender": "30002626",
            "receptor": "09121321111",
            "date": 1356619709,
            "cost": 120
        },
        {
            "messageid": 8792344,
            "message": "وب سرویس پیامک",
            "status": 1,
            "statustext": "در صف ارسال",
            "sender": "30002627",
            "receptor": "09121230000",
            "date": 1356619709,
            "cost": 120
        },
        {
            "messageid": 8792345,
            "message": "وب سرویس ارسال",
            "status": 1,
            "statustext": "در صف ارسال",
            "sender": "30002727",
            "receptor": "09123210000",
            "date": 1356619709,
            "cost": 120
        }
    ]
}

Status کنترل وضعیت

پیامک ها بعد از ارسال از طریق وب سرویس، وضعیت در صف خواهند داشت ، در کمتر از 1 ثانیه به مخابرات تحویل داده میشوند و وضعیت ارسال به مخابرات را خواهند گرفت ، بعد از 5 دقیقه از زمان تحویل به مخابرات تا زمانی که وضعیت آنها تغییر نکند دائما کنترل میشوند ، در نهایت پیامک های ارسالی یکی از مقادیر جدول 2 وضعیت پیامک ها را خواهند داشت.
از این تابع برای کنترل وضعیت رسید Delivery پیامک استفاده می‌شود. برای این منظور باید شناسه یکتای هر پیامک messageid را که در هنگام ارسال پیامک از خروجی دریافت کرده اید را ارسال نمائید.
در هر بار اجرای این متد می‌توانید از وضعیت ۳۰۰۰ پیامک با خبر شوید. کافیست شناسه یکتای پیامک ها را از طریق کاراکتر ویرگول « , » از هم جدا کنید.

پارامترهای ورودی

messageid اجباری Long شناسه یکتای پیامک مورد نظر

پارامترهای خروجی

خروجی آرایه ای از ساختار زیر خواهد بود.

messageid Long شناسه یکتای پیامک
status Integer وضعیت عددی پیامک - اطلاعات بیشتر جدول 2 وضعیت پیامک ها
statustext String توضیح وضعیت پیامک

یادداشت

  • برای اطلاع از وضعیت پیامک ها به جدول وضعیت پیامک ها مراجعه نمائید
  • در صورتی که شناسه پیامک messageid معتبر نباشد یا متعلق به شما نباشد مقدار فیلد status = 100 خواهد بود، معادل معتبر نبودن
  • در صورت تمایل به استفاده از خدمات Status Callback URL (ارسال وضعیت به URL) می‌توانید از بخش تنظیمات خطوط فعال نمائید.

پاسخ

414 حجم درخواست بیشتر از حد مجاز است ، هر فراخوانی 500 شناسه پیامک
400 پارامترها ناقص هستند

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/status.json?messageid=85463238,85463239

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 85463238,
            "status": 10,
            "statustext": "رسیده به گیرنده"
        },
        {
            "messageid": 85463239,
            "status": 4,
            "statustext": "ارسال به مخابرات"
        }
    ]
}

StatusByLocalidدریافت وضعیت با شناسه محلی شما

شما علاوه بر واکشی وضعیت پیامک های ارسال توسط متد Status ،می‌توانید توسط پارامتر localid که در هنگام ارسال پیامک پاس داده اید هم وضعیت پیامک ها را واکشی نمائید، ساختار خروجی این متد همانند متد Status می‌باشد.
ممکن است به هر دلیلی ساختار پایگاه داده شما به نحوی باشد که توانائی ذخیره سازی شناسه یکتای پیامک messageid را نداشته باشید، آنگاه برای واکشی وضعیت پیامک های ارسالی می‌توانید از این متد استفاده نمائید.
در نهایت پیامک های ارسالی یکی از مقادیر جدول 2 وضعیت پیامک ها را خواهند داشت.
در هر بار اجرای این متد می‌توانید از وضعیت 3،000 پیامک با خبر شوید. کافیست شناسه محلی پیامک ها localid را از طریق کاراکتر ویرگول « , » از هم جدا کنید.

پارامترهای ورودی

localid اجباری Long شناسه محلی پیامک مورد نظر

پارامترهای خروجی

خروجی آرایه ای از ساختار زیر خواهد بود .

messageid Long شناسه یکتای پیامک
localid Long شناسه محلی پیامک
status Integer وضعیت عددی پیامک - اطلاعات بیشتر جدول 2 وضعیت پیامک ها
statustext String توضیح وضعیت پیامک

یادداشت

  • برای اطلاع از وضعیت پیامک ها به جدول وضعیت پیامک ها مراجعه نمائید.
  • در صورتی که حساب شما شناسه محلی localid مورد نظر را در هنگام ارسال ارائه نکرده باشد مقدار فیلد خروجی Status = 100 خواهد بود، معادل معتبر نبودن
  • در صورت تمایل به استفاده از خدمات Status Callback URL (ارسال وضعیت به URL) می‌توانید از بخش تنظیمات خطوط فعال نمائید.

خطاها

414 حجم درخواست بیشتر از حد مجاز است ، هر فراخوانی 500 شناسه پیامک

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/statuslocalmessageid.json?localid=450

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 85463238,
            "localid": "450",
            "status": 10,
            "statustext": "رسیده به گیرنده"
        }
    ]
}

Select انتخاب پیامک

در صورتی که می‌خواهید اطلاعات پیامک ارسالی را بازیابی نمائید، می‌توانید با messageid و استفاده از این متد اطلاعات رکورد را دریافت کنید.
در هر بار اجرای این متد می‌توانید از وضعیت ۳۰۰۰ پیامک با خبر شوید. کافیست شناسه یکتای پیامک ها را از طریق کاراکتر ویرگول « , » از هم جدا کنید.

پارامترهای ورودی

messageid اجباری Long شناسه پیام مورد نظر، می تواند چندین شناسه را با کاراکتر ویرگول « , » از هم جدا کنید

پارامترهای خروجی

خروجی آرایه ای از ساختار بالا خواهد بود

messageid Long شناسه یکتای پیامک
message Integer متن پیام ارسال شده
status Integer وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
statustext String توضیح وضعیت این پیامک
sender String شماره فرستنده
receptor String شماره گیرنده
date UnixTime زمان ارسال این پیامک به فرمت UnixTime
cost Integer هزینه این پیامک ( ریال)

یادداشت

  • در صورتی که شناسه پیامک messageid معتبر نباشد یا متعلق به شما نباشد مقدار فیلد status=100 خواهد بود، معادل معتبر نبودن
  • تفاوت این متد با متد status در نوع خروجی است ، این متد اطلاعات بیشتر همراه خود دارد ولی بهتر است برای کنترل وضعیت پیامک از متد status استفاده کنید زیرا حجم اطلاعات خروجی کمتر و سرعت آن بیشتر است

خطاها

414 حجم درخواست بیشتر از حد مجاز است ، هر فراخوانی 500 شناسه پیامک
400 پارامترها ناقص هستند

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/select.json?messageid=30034577,30034578

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 30034577,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "status": 10,
            "statustext": "رسیده به گیرنده",
            "sender": "30001528961415",
            "receptor": "09125258596",
            "date": 1356619709,
            "cost": 120
        },
        {
            "messageid": 30034578,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "status": 11,
            "statustext": "نرسیده به گیرنده",
            "sender": "30001528961415",
            "receptor": "09128585774",
            "date": 1356619709,
            "cost": 120
        }
    ]
}

SelectOutboxلیست ارسال ها

گاهی پیش می آید نیاز داریم فهرست پیامک های ارسال شده را در بازه زمانی مشاهده کنیم ، در این حالت از این متد استفاده کنید. برای این کار کافیست تاریخ شروع و پایان بازه زمانی مورد نظر را به فرمت UnixTime را ارسال کنید .

پارامترهای ورودی

startdate اجباری Long تاریخ شروع بازه مورد نظر به فرمت UnixTime
enddate اختیاری Long تاریخ پایان بازه مورد نظر به فرمت UnixTime
sender اختیاری String خط اختصاصی ارسال کننده پیامک

پارامترهای خروجی

messageid Long شناسه یکتای پیامک
message Integer متن پیام ارسال شده
status Integer وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
statustext String متن توضیح وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
sender String شماره فرستنده
receptor String شماره گیرنده
date UnixTime زمان ارسال این پیامک به فرمت UnixTime
cost Integer هزینه این پیامک ( ریال)

یادداشت

  • در صورتی که می‌خواهید پیامک های ارسال شده از تاریخی تا این لحظه (Now) را دریافت نمائید پارامتر enddate را خالی ارسال نمائید.
  • حداکثر تعداد رکورد های خروجی این متد حداکثر 500 رکورد می‌باشد ، قابلیت Pagination به این متد به زودی اضافه می‌شود.
  • تاریخ پایان نباید از تاریخ شروع کوچکتر باشد.
  • در صورتی که می‌خواهید ارسال های یک خط خاص را دریافت نمائید کافیست پارامتر Sender را مقداردهی کنید.

خطاها

412 ارسال کننده نامعتبر است یا متعلق به شما نمی‌باشد.
417 تاریخ معتبر نمی‌باشد یا تاریخ پایان از آغاز کوچتر است .

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/selectoutbox.json?startdate=1409533200&enddate=1410570000

پاسخ

        {
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 30034577,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "status": 10,
            "statustext": "رسیده به گیرنده",
            "sender": "30002626",
            "receptor": "09125258596",
            "date": 1409533200,
            "cost": 120
        },
        {
            "messageid": 30034578,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "status": 10,
            "statustext": "رسیده به گیرنده",
            "sender": "30002626",
            "receptor": "09128585774",
            "date": 1409565600,
            "cost": 120
        }
    ]
}

LatestOutBox آخرین ارسال ها

برای دریافت آخرین پیامک های ارسال شده می‌توانید از این متد استفاده نمائید. با ارسال مقدار پارامتر pagesize می‌توانید تعداد رکورد های مورد نیاز را مشخص نمائید.

پارامترهای ورودی

pagesize اختیاری Long تعداد آخرین رکورد های مورد نیاز (حداکثر 500 رکورد)
sender اختیاری String خط اختصاصی ارسال کننده پیامک

پارامترهای خروجی

messageid Long شناسه یکتای پیامک
message Integer متن پیام ارسال شده
status Integer وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
statustext String متن توضیح وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
sender String شماره فرستنده
receptor String شماره گیرنده
date UnixTime زمان ارسال این پیامک به فرمت UnixTime
cost Integer هزینه این پیامک ( ریال)

یادداشت

  • تعداد رکورد های خروجی این متد حداکثر 500 رکورد می‌باشد.
  • قابلیت Pagination به زودی اضافه می‌شود.
  • در صورتی که pagesize مقداردهی نشود مقدار 500 برای آن لحاظ می‌شود.
  • در صورتی که می‌خواهید ارسال های یک خط خاص را دریافت نمائید کافیست پارامتر sender را مقداردهی کنید.

خطاها

412 ارسال کننده نامعتبر است یا متعلق به شما نمی‌باشد
400 پارامترها ناقص هستند ، در صورتی که مقدار pagesize بیشتر از 500 باشد پارامتر ناقص لحاظ می‌شود

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/latestoutbox.json?pagesize=1000

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 30034577,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "status": 10,
            "statustext": "رسیده به گیرنده",
            "sender": "30002626",
            "receptor": "09125258596",
            "date": 1409533200,
            "cost": 120
        },
        {
            "messageid": 30034578,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "status": 10,
            "statustext": "رسیده به گیرنده",
            "sender": "30002626",
            "receptor": "09128585774",
            "date": 1409565600,
            "cost": 120
        },
        {
            "messageid": 30034579,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "status": 10,
            "statustext": "رسیده به گیرنده",
            "sender": "30002626",
            "receptor": "09124585774",
            "date": 1409565600,
            "cost": 120
        }
    ]
}

CountOutbox تعداد ارسال ها

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

پارامترهای ورودی

startdate اجباری Long تاریخ شروع بازه مورد نظر به فرمت Unixtime
enddate اختیاری Long تاریخ پایان بازه مورد نظر به فرمت Unixtime
status اختیاری Integer در صورت تمایل به دریافت تعداد پیامک با وضعیت مورد نظر از این پارامتر استفاده نمائید

پارامترهای خروجی

startdate Long تاریخ شروع
enddate Long تاریخ پایان
sumpart Long مجموع تعداد صفحات پیامک های ارسالی
sumcount Long تعداد پیامک های ارسالی
cost Long هزینه پیامک های ارسالی - ریال

یادداشت

  • حداکثر فاصله زمانی بین متغیر startdate تا متغیر enddate برابر با 1 روز می باشد
  • تاریخ شروع startdate نباید کوچکتر از 60 روز قبل باشد
  • در صورتی که می‌خواهید تعداد پیامک های ارسال شده از تاریخی تا این لحظه (Now) را دریافت نمائید پارامتر enddate را خالی ارسال نمائید
  • مقدار sumpart ضرب در تعرفه ارسال پیامک برابر با مقدار فیلد cost خواهد شد
  • تاریخ پایان نباید از تاریخ شروع کوچکتر باشد
  • در صورتی که می‌خواهید تعداد پیامک های در صف را دریافت نمائید کافیست پارامتر Status = 1 را ارسال نمائید

خطاها

417 تاریخ معتبر نمی‌باشد یا تاریخ پایان از آغاز کوچتر است

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/countoutbox.json?startdate=1409533200&enddate=1410570000&status=10

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "startdate": 1409533200,
            "enddate": 1409533200,
            "sumpart": 45000,
            "sumcount": 15000,
            "cost": 5175000
        }
    ]
}

Cancel انصراف از ارسال

شما می‌توانید در هنگام ارسال پیامک از طریق پارامتر Date تاریخ ارسال پیامک را مشخص نمائید. در صورتی که ارسال پیامک در تاریخ معینی تنظیم شود پیامک زمانبندی می‌شود. حال اگر شما مایل هستید این زمان بندی را لغو نمائید ، راه حل شما استفاده از این متد است. در هر بار اجرای این متد می‌توانید ارسال حداکثر 500 پیامک را لغو نمائید. کافیست شناسه ها را از طریق کاراکتر ویرگول « , » از هم جدا کنید.

پارامترهای ورودی

messageid اجباری Long شناسه یکتای پیامک مورد نظر

پارامترهای خروجی

messageid Long شناسه یکتای پیامک
status Integer وضعیت جدید پیامک - اطلاعات بیشتر جدول 2 وضعیت پیامک ها
statustext String توضیح وضعیت پیامک

یادداشت

  • در صورتی که شناسه پیامک MessageId معتبر نباشد یا متعلق به شما نباشد مقدار فیلد Status برابر با 100 خواهد بود. در صورت ارسال درخواست برای لغو پیامکی که ارسال شده است.
  • برای اطلاع از وضعیت پیامک ها به جدول وضعیت پیامک ها مراجعه نمائید
  • فقط در صورتی که پیامک مورد نظر زمانبندی شده باشد امکان لغو آن وجود دارد
  • در صورت لغو شدن ارسال پیامک هزینه آن به اعتبار حساب شما بازگشت داده می‌شود

خطاها

412 درخواست لغو شد ( تعداد شناسه پیامک ها بیشتر از 200 بوده است )

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/cancel.json?messageid=31031212,31031213,31031214

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 31031212,
            "status": 13,
            "statustext": "لغو شده"
        },
        {
            "messageid": 31031213,
            "status": 13,
            "statustext": "لغو شده"
        },
        {
            "messageid": 31031214,
            "status": 13,
            "statustext": "لغو شده"
        }
    ]
}

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

API کاوه نگار علاوه برامکان ارسال پیامک های دریافت شده به URL شما Receive via Callback URL امکان این را دارد که شما از طریق فراخوانی این متد پیامک های دریافتی خط مورد نظر را واکشی کنید. بعد از فراخوانی این متد پیامک های که در خروجی قرار می گیرند وضعیت خوانده شده isRead = 1 را خواهند داشت.
علاوه بر این شما می‌توانید سیستم دریافت پیامک خود را با تنظیم URL در بخش تنظیمات به صورت Real-Time داشته باشید که به محظ دریافت پیامک از مخابرات آن را برای شما از طریق URL ارسال نماید. در نهایت در صورتی که پیامک های دریافت شده از طریق URL به هر دلیلی به دست شما نرسد وضعیت خوانده نشده isRead = 0 خواهند داشت که می‌توانید با اجرای این متد کلیه پیام ها را دریافت کنید.

پارامترهای ورودی

linenumber اجباری String شماره خط مورد نظر ( مثل 30002225 )
isread اجباری Integer خوانده شده : 1 ، خوانده نشده : 0
برای دریافت پیامک های خوانده نشده (جدید) مقدار 0 را باید در این پارامتر قرار دهید .

پارامترهای خروجی

messageid Long شناسه پیام دریافتی
message String متن پیام دریافت شده
sender String شماره ارسال کننده پیامک
receptor String شماره دریافت کننده
date UnixTime تاریخ دریافت پیامک

یادداشت

  • در هر بار فراخوانی این متد 100 پیامک دریافت شده در خروجی قرار می گیرد. برای ادامه کافیست مادامی که تعداد رکورد های خروجی برابر 100 است این متد را فراخوانی نمائید.

نمونه مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/receive.json?linenumber=3000202030&isread=0

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "messageid": 35850015,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "sender": "09360462960",
            "receptor": "3000202030",
            "date": 1357206241
        },
        {
            "messageid": 35850016,
            "message": "خدمات پیام کوتاه کاوه نگار",
            "sender": "09123832441",
            "receptor": "3000202030",
            "date": 1357103281
        }
    ]
}

CountInbox تعداد پیامک های دریافت شده

از این متد برای دریافت تعداد پیامک های دریافت شده به کلیه خطوط اختصاصی یا یک خط خاص در بازه زمانی استفاده می کنیم.

پارامترهای ورودی

startdate اجباری Long تاریخ شروع بازه مورد نظر به فرمت Unixtime
enddate اختیاری Long تاریخ پایان بازه مورد نظر به فرمت Unixtime
linenumber اختیاری String شماره خط مورد نظر
isread اختیاری Integer وضعیت پیامک دریافتی - مقدار 0 به معنی خوانده نشده و 1 خوانده شده

پارامترهای خروجی

startdate Long تاریخ شروع
enddate Long تاریخ پایان
sumcount Long تعداد پیامک دریافت شده

یادداشت

  • در صورتی که می‌خواهید تعداد پیامک های دریافت شده از تاریخ معینی تا این لحظه را دریافت نمائید پارامتر enddate را خالی ارسال نمائید.
  • در صورتی که پارامتر linenumber مقداری نداشته باشد ، تعداد دریافت کلیه خطوط اختصاصی حساب شما در خروجی قرار خواهد گرفت .
  • تاریخ پایان نباید از تاریخ شروع کوچکتر باشد.
  • در صورتی که می‌خواهید تعداد پیامک های خوانده نشده را دریافت نمائید کافیست پارامتر isread = 0 را ارسال نمائید .

خطاها

417 تاریخ معتبر نمی‌باشد یا تاریخ پایان از آغاز کوچتر است .

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/sms/countinbox.json?startdate=1409533200&enddate=1410570000&linenumber=10008284&isread=1

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": [
        {
            "startdate": 1409533200,
            "enddate": 1409533200,
            "sumcount": 15000
        }
    ]
}

Lookupاعتبار سنجی

از طریق این متد می‌توانید برای احراز هویت کاربران با ارسال کد اعتبار سنجی و یا اطلاعات ضروری مانند ارسال رمزعبور، کد تایید عضویت ، شماره فاکتور، کدهای خرید و تخفیف و ... استفاده نمائید. فرق این متد با متد ارسال پیامک در این است که پیامک های این متد بالاترین اولویت را دارند و هیچ کدام از پیامک های آن فیلتر نخواهند شد( ارسال پیامک به افرادی که پیامک تبلیغاتی خود را بسته اند) همچنین این متد قابلیت ارسال پیامک به ۱۴۸ کشور دنیا را دارد.
برای مشاهده ویژگی های این سرویس به صفحه معرفی آن مراجعه کنید. (معرفی سرویس اعتبار سنجی)
در ساختار این متد نیازی نیست فرستنده را ارسال کنید کافیست گیرنده و مقدار کد Token را ارسال نمائید. سیستم بهترین پیش شماره داخلی یا خارجی را انتخاب می کند و پیامک را ارسال می کند.
برای استفاده از این متد نیاز است ابتدا الگوی پیام خود را از طریق پنل مشخص نمائید.

مثالی از متن الگو

کد تایید عضویت 
token%

ممنون از خرید شما
کد شارژ : %token 
سریال : %token2 
مدت اعتبار : %token3

تعریف الگوی اعتبار سنجی

ساختار URL

https://api.kavenegar.com/v1/{API-KEY}/verify/lookup.json

پارامترهای ورودی

receptor اجباری string شماره گیرنده که می‌خواهید اعتبار سنجی شود
در صورتی که شماره بین المللی است با کد کشور و دو صفر ارسال شود 00974211234565
token اجباری string این رشته فقط میتواند حاوی کاراکتر های انگلیسی و عدد باشد
token2 اختیاری string این رشته همانند token فقط میتواند حاوی کاراکتر های انگلیسی و عدد باشد
token3 اختیاری string این رشته همانند token فقط میتواند حاوی کاراکتر های انگلیسی و عدد باشد
template اجباری string نام الگوی تعریف شده برای اعتبار سنجی
type اختیاری string نوع پیام را مشخص میکند (پیامک صوتی یا متنی) پیش فرض پیامک (sms) می‌باشد

پارامترهای خروجی

messageid Long شناسه یکتای این پیامک
برای اطلاع از وضعیت پیامک ارسالی این مقدار ورودی متد Status می‌باشد.
message String متن پیامک ارسال شده
status Integer وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
statustext String متن توضیح وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
sender String شماره فرستنده
receptor String شماره گیرنده
date UnixTime زمان ارسال این پیامک به فرمت UnixTime
cost Integer هزینه این پیامک ( ریال)

یادداشت

  • پارامتر type دارای دو مقدار است که توضیح هر کدام به شرح زیر است :
    • call : در صورتی که نیاز به ارسال پیام صوتی دارید
    • sms : در صورتی که نیاز به ارسال پیام متنی دارید
  • برای اطلاع از وضعیت پیامک به جدول وضعیت پیامک ها مراجعه نمائید
  • برای پیامک به کشور های دیگر کد کشور را با دو صفر ارسال نمائید
  • برای استفاده از این متد نیاز است سرویس پیشرفته را فعال نمائید
  • در صورت وجود اختلال در پیش شماره های داخلی ، پیامک از پیش شماره های بین المللی ارسال خواهد شد
  • در صورت تمایل واحد فنی توکن های بیشتری را در اختیار شما قرار خواهد داد.

توجه : در صورتی که Token فقط شامل عدد باشد استفاده از تماس تلفنی امکان پذیر است. اگر گیرنده تلفن ثابت ایران باشد نوع پیام به صورت خودکار به تماس تلفنی تغییر خواهد کرد. مقدار پیش فرض این پارامتر SMS است.

خطاها

418 اعتبار حساب شما کافی نیست
422 داده ها به دلیل وجود کاراکتر نامناسب قابل پردازش نیست
424 الگوی مورد نظر پیدا نشد ، زمانی که نام الگو نادرست باشد یا طرح آن هنوز تائید نشده باشد رخ می‌دهد
426 استفاده از این متد نیازمند سرویس پیشرفته می‌باشد
428 ارسال کد از طریق تماس تلفنی امکان پذیر نیست، درصورتی که توکن فقط حاوی عدد نباشد این خطا رخ می‌دهد
431 ساختار کد صحیح نمی‌باشد ، اگر توکن حاوی خط جدید،فاصله، UnderLine یا جداکننده باشد این خطا رخ می‌دهد
432 پارامتر کد در متن پیام پیدا نشد ، اگر در هنگام تعریف الگو پارامتر token% را تعریف نکرده باشید این خطا رخ می‌دهد

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/verify/lookup.json?receptor=09361234567&token=852596&template=myverification

پاسخ

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": {
        "messageid": 8792343,
        "message": "ممنون از ثبت نام شما کد تایید عضویت  : 852596	",
        "status": 5,
        "statustext": "ارسال به مخابرات",
        "sender": "10004346",
        "receptor": "09361234567",
        "date": 1356619709,
        "cost": 120
    }
}

TTSتماس صوتی

از این متد برای ارسال تماس صوتی استفاده می کنیم، امکان ارسال یک تماس صوتی خاص به چندین گیرنده ( Receptor ) در این متد وجود دارد کافیست آنها را از طریق کاراکتر ویرگول « , » از هم جدا کنید .

پارامترهای ورودی

receptor اجباری String شماره دریافت کننده پیامک را مشخص می کند که می توان با کاراکتر ویرگول "," آنها را از هم جدا کرد
message اجباری String متن پیام کوتاه ، متن مورد نظر را در حالت POST یا GET حتما بایدEncode شود
date اختیاری UnixTime زمان ارسال پیام ( در صورتی که خالی باشد پیام به صورت خودکار در همان لحظه ارسال می شود )
localid اختیاری String شناسه محلی در پایگاه داده های شما است ، اطلاعات بیشتر در بخش یادداشت نوشته شده
repeat اختياري int تکرار ارسال (0 -5)

پارامترهای خروجی

messageid Long شناسه یکتای این پیامک
برای اطلاع از وضعیت پیامک ارسالی این مقدار ورودی متد Status می باشد.
message String متن پیامک ارسال شده
status Integer وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
statustext String متن توضیح وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
sender String شماره فرستنده
receptor String شماره گیرنده
date UnixTime زمان ارسال این پیامک به فرمت UnixTime
cost Integer هزینه این پیامک ( ریال)

یادداشت ها :

  • در صورتي که تماس ارسالي به گيرنده نرسد سرويس کاوه نگار با توجه به مقدار پارامتر repeat که بين بازه 0 تا 5 مي باشد دوباره اقدام به ارسال آن تماس مي کند که بازه زماني بين هر تکرار 3 دقيقه مي باشد.
  • برای اطلاع از وضعیت پیامک به جدول وضعیت پیامک ها مراجعه نمایید .
  • برای دریافت اطلاعات و نحوه کار با تاریخ به فرمت UnixTime به اینجا مراجعه نمایید .
  • در مورد شناسه محلی LocalId به چند نکته توجه نمائید :
    • به وسیله مقدار دهی به این پارامتر میتوانید از ارسال پیامک تکرار جلوگیری نمائید. ... اطلاعات بیشتر
    • در صورت مقدار دهی ، تعداد آن باید برابر تعداد گیرنده باشد ، با کاراکتر ویرگول , آنها را از هم جدا کنید.
    • در صورت وجود این شناسه محلی LocalId در لیست ارسال های شما، ارسال تکراری انجام نمیشود و رکورد مربوط به این شناسه در خروجی قرار خواهد گرفت.

خطاها :

414 تعداد دریافت کننده ها ( Receptor) بیشتر از 200 است .
417 تاریخ ارسال اشتباه است ، تاریخ آن گذشته و یا به فرمت درست ارسال نشده است .
418 اعتبار حساب شما کافی نیست .

مثال

درخواست

https://api.kavenegar.com/v1/613472435563797A3767733D/call/maketts.json?receptor=09361234567&&message=خدمات پیام کوتاه کاوه نگار

پاسخ

{
    "return":
    {
        "status":200,
        "message":"تایید شد"
    },
    "entries":
         {
            "messageid":8792343,
		    "message": "ممنون از ثبت نام شما کد تایید عضویت  : 852596	",
            "status":5,
            "statustext":"ارسال به مخابرات",
            "sender":"10004346",
            "receptor":"09361234567",
            "date":1356619709,
            "cost":120
          }    
    
}

Infoدریافت اطلاعات حساب کاربری

این متد برای دریافت اطلاعات حساب خود و یا مشتریان ایجاد شده توسط شما استفاده می‌شود. دریافت اعتبار باقی مانده و تاریخ یکی از مهم ترین فیلدهای خروجی این متد است.

ساختار URL

https://api.kavenegar.com/v1/{API-KEY}/account/info.json

پارامترهای خروجی

remaincredit Long اعتبار باقی مانده حساب مورد نظر ( ریال )
expiredate UnixTime تاریخ انقضاء که برای مسائل امنیتی قرار داده شده است
type String نوع حساب مورد نظر را مشخص می کند که شامل دو حالت master, child می‌باشد

یادداشت

  • مقدار اعتبار باقی مانده بر اساس واحد ریال می‌باشد
  • مقدار تاریخ انقضاء جنبه امنیتی دارد و نگران انقضاء حساب خود نباشید. استفاده آن در بخش مدیریت مشتریان شما می‌باشد

مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/account/info.json

جواب

{
    "return": 
    {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": 
    {
        "remaincredit": 1500000,
        "expiredate": 13548889,
        "type": "master"
    }
}

تنظیمات ضروریConfig

از این متد می‌توانید برای دریافت تنظیمات حساب و یا تغییر مقادیر آن استفاده نمائید، برای دریافت مقادیر کافیست درخواست GET بدون هیچ پارامتری ارسال نمائید، همچنین برای تنظیم مقدار هر پارامتر نام پارامتر به همراه مقدار آن را توسط درخواست GET یا POST ارسال نمائید.

ساختار URL

https://api.kavenegar.com/v1/{API-KEY}/account/config.json

پارامترهای ورودی

پارامتر نوع نوع توضیح
apilogs اختیاری String وضعیت لاگ کردن رکوئست های وب سرویس را مشخص می کند، اطلاعات بیشتر در یادداشت
dailyreport اختیاری String وضعیت ارائه گزارش روزانه ارسال و دریافت پیامک را مشخص می کند، اطلاعات بیشتر در یادداشت
debugmode اختیاری String در صورت فعال بودن این مقدار حساب شما در حالت دیباگ قرار گرفته و هیچ کدام از درخواست های ارسال پیامک را انجام نمی هد تا شما کد خود را تست کنید
defaultsender اختیاری String با تنظیم این پارامتر خط پیش فرض ارسال کنند اکانت شما مشخص می‌شود در صورتی که در هنگام ارسال پیامک ارسال کننده را مشخص نکنید مقدار این پارامتر به عنوان خط ارسال کنند لحاظ می‌شود.
mincreditalarm اختیاری Integer این پارامتر حداقل اعتبار حساب شما برای دریافت هشدار کمبود اعتبار را به ریال تنظیم می کند
resendfailed اختیاری String این پارامتر وضعیت ارسال مجدد و خودکار پیامک هایی که به گیرنده نرسیده اند را مشخص می کند

پارامترهای خروجی

با هر بار تنظیم مقادیر جدید در خروجی بروز میشوند .

پارامتر نوع توضیح
apilogs String مقادیر این پارامتر دارای سه حالت است که توصیه می‌شود بخش یادداشت را مطالع نمائید
dailyreport String در صورت فعال بودن هر روز ساعت 10 صبح گزارش ارسال و دریافت دیروز را برای شما پیامک میکند
debugmode String در صورت فعال بودن هیچ یک از پیامک های شما ارسال نخواهند شد و وضعیت لغو شده خواهند گرفت
defaultsender String خط ارسال کننده پیش فرض اکانت را مشخص می کند برای اطلاعات بیشتر به یادداشت مراجعه فرمائید
mincreditalarm Integer این پارامتر حداقل اعتبار حساب شما (به ریال) برای دریافت هشدار کمبود اعتبار را تنظیم می کند
resendfailed String این پارامتر وضعیت ارسال مجدد و خودکار پیامک هایی که به گیرنده نرسیده اند را مشخص می کند

یادداشت

  • پارامتر apilogs دارای سه مقدار است که توضیح هر کدام به شرح زیر است :
    • justfaults : در صورتی که در فراخوانی متد های وب سرویس فقط خطایی رخ دهد لاگ آن ذخیره خواهد شد
    • enabled : لاگ کلیه درخواست های وب سرویس چه خطا دار و چه موفق ذخیره خواهند شد
    • disabled : لاگ هیچ درخواستی ذخیره نخواهد شد
  • با فعال بودن dailyreport گزارشی از تعداد ارسال و دریافت و خطاهای API و هزینه ارسال روز قبل از طریق پیامک هر روز 10 صبح ارسال می‌شود
    • enabled : ارسال گزارش فعال است
    • disabled : ارسال گزارش غیرفعال است
  • در مواقعی که در حال تست کد های خود هستید و مایل نیستید در صورت فراخوانی متد های ارسال پیامک، ارسالی انجام شود و اعتبار شما هزینه شود می‌توانید debugMode را فعال کنید
    • enabled : حالت دیباگ فعال است
    • disabled : حالت دیباگ غیرفعال است
  • همان طور که مشاهده کرده اید پارامتر sender در متد ارسال پیامک send اجباری نمی‌باشد ، در صورتی که شما در هنگام استفاده از متد send این پارامتر را مقداردهی نکنید سیستم defaultsender را به عنوان ارسال کننده پیش فرض در نظر خواهد گرفت.
  • منظور از پارامتر mincreditalarm حداقل مبلغ اعتبار حساب شما برای دریافت پیامک هشدار کمبود اعتبار است
  • درصورت فعال بودن پارامتر resendfailed اگر پیامک های ارسال شما وضعیت نرسیده به گیرنده را بگیرند به صورت خودکار دوباره ارسال خواهند شد
    • enabled : وضعیت ارسال مجدد فعال است
    • disabled : وضعیت ارسال مجدد غیر فعال است

خطاها

407 دسترسی به اطلاعات مورد نظر برای شما امکان پذیر نیست

نمونه مثال

درخواست

https://api.kavenegar.com/v1/{API-KEY}/account/config.json?defaultsender=10004535&apilogs=justfaults&debugmode=enabled

جواب

{
    "return": {
        "status": 200,
        "message": "تایید شد"
    },
    "entries": 
    {
        "apilogs": "justfaults",
        "dailyreport": "disabled",
        "debugmode": "enabled",
        "defaultsender": "10004535",
        "mincreditalarm": "50000",
        "resendfailed": "true"
    }
}

جدول ۱ - کدهای برگشتی

کد توضیحات
200 درخواست تایید شد
400 پارامترها ناقص هستند
401 حساب کاربری غیرفعال شده است
402 عملیات ناموفق بود
403 کد شناسائی API-Key معتبر نمی‌باشد
404 متد نامشخص است
405 متد Get/Post اشتباه است
406 پارامترهای اجباری خالی ارسال شده اند
407 دسترسی به اطلاعات مورد نظر برای شما امکان پذیر نیست
409 سرور قادر به پاسخگوئی نیست بعدا تلاش کنید
411 دریافت کننده نامعتبر است
412 ارسال کننده نامعتبر است
413 پیام خالی است و یا طول پیام بیش از حد مجاز می‌باشد. لاتین ﻛﺎراﻛﺘﺮ و ﻓﺎرﺳﻲ 268 ﻛﺎراﻛﺘﺮ
414 حجم درخواست بیشتر از حد مجاز است ،ارسال پیامک :هر فراخوانی حداکثر 200 رکوردو کنترل وضعیت :هر فراخوانی 3000 رکورد
415 اندیس شروع بزرگ تر از کل تعداد شماره های مورد نظر است
416 IP سرویس مبدا با تنظیمات مطابقت ندارد
417 تاریخ ارسال اشتباه است و فرمت آن صحیح نمی باشد.
418 اعتبار شما کافی نمی‌باشد
419 طول آرایه متن و گیرنده و فرستنده هم اندازه نیست
422 داده ها به دلیل وجود کاراکتر نامناسب قابل پردازش نیست
424 الگوی مورد نظر پیدا نشد
426 استفاده از این متد نیازمند سرویس پیشرفته می‌باشد
428 ارسال کد از طریق تماس تلفنی امکان پذیر نیست
431 ساختار کد صحیح نمی‌باشد
432 پارامتر کد در متن پیام پیدا نشد

جدول ۲ - وضعیت پیامک ها

مقدار توضیحات
1 در صف ارسال قرار دارد
2 زمان بندی شده (ارسال در تاریخ معین)
4 ارسال شده به مخابرات
5 ارسال شده به مخابرات (همانند وضعیت 4)
6 خطا در ارسال پیام که توسط سر شماره پیش می آید و به معنی عدم رسیدن پیامک می‌باشد (Failed)
10 رسیده به گیرنده (Delivered)
11 نرسیده به گیرنده ، این وضعیت به دلایلی از جمله خاموش یا خارج از دسترس بودن گیرنده اتفاق می افتد (Undelivered)
13 ارسال پیام از سمت کاربر لغو شده یا در ارسال آن مشکلی پیش آمده که هزینه آن به حساب برگشت داده می‌شود
14 بلاک شده است، عدم تمایل گیرنده به دریافت پیامک از خطوط تبلیغاتی که هزینه آن به حساب برگشت داده می‌شود
100 شناسه پیامک نامعتبر است ( به این معنی که شناسه پیام در پایگاه داده کاوه نگار ثبت نشده است یا متعلق به شما نمی‌باشد)

جدول ۳ - نوع نمایش پیام

کد توضیحات
0 پیامک بصورت مستقیم برروی صفحه موبایل شخص گیرنده ظاهرمی‌شود.این حالت پیامک درموبایل یا سیم کارت شخص گیرنده بصورت اتوماتیک ذخیره نمی‌شود و با خروج از آن حذف می‌شود(پیامک خبری)
1 در حافظه ﻣﻮﺑﺎﻳﻞ ﺷﺨﺺ گیرنده ذخیره می‌شود. (پیامک عادی) در صورتی که پارامتر مربوطه خالی ارسال شود به صورت پیش فرض پیامک مورد نظر با این نوع ارسال می‌شود
2 پیامک برروی حافظه سیمکارت گوشی گیرنده ذخیره می‌شود
3 درصورتی که موبایل شخص گیرنده دارای یک نرم افزار کابردی خاص برای ذخیره پیامک باشد و یا به یک نرم افزار کاربردی خاص برروی یک کامپیوترمتصل باشد، پیامک دریافتی درآن نرم افزارها ذخیره می‌شود

آخرین تغییرات

  • متد استعلام با کدپستی CountPostalCode حذف گرید.
  • متد ارسال پیام با کد پستی SendByPostalCode حذف گرید.
  • بازه ارسال در متدهای SelectOutbox , SelectOutbox , SelectOutbox به 1 روز تغییر پیدا کرد.
  • تاریخ شروع در متدهای SelectOutbox , SelectOutbox , SelectOutbox نباید کوچکتر از 60 روز قبل باشد.
  • پارامتر Pagesize در سایر متدها از مقدار 500 به 200 تغییر پیدا کرد.
  • اگر مقداری عددی پارامتر hide برابر 1 باشد شماره گیرنده در فهرست ارسال ها و کنسول وب نمایش داده نمی شود.