مفاهیم اولیه

معرفی REST API

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

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

شروع

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

خروجی باید چیزی شبیه به این باشد :

{
    "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
    }
}
<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <datetime>02/06/2012 01:53:46 ب.ظ</datetime>
            <year>2012</year>
            <month>06</month>
            <day>02</day>
            <hour>13</hour>
            <minute>53</minute>
            <second>46</second>
            <unixtime>1338645226</unixtime>
        </item>
    </entries>
</response>
در صورتی که مایل هستید بافرمت XML خروجی را دریافت کنید کافیست پسوند آدرس مورد نظر را از JSON به XML تغییر دهید.

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

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

http(s)://api.kavenegar.com/v1/Your-Api-Key/Scope/MethodName.OutputFormat

در صورتی که API-KEY ندارید می توانید از این بخش ثبت نام کنید و 5،000 ریال هم اعتبار هدیه برای تست وب سرویس کاوه نگار دریافت کنید

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

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

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

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

ساختار خروجی

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

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

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

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

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

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

طول پیامک

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

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

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

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

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

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

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

توجه : شما می توانید با فراخوانی متد ها از طریق ساختار 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 گیرنده و در کنترل وضعیت حداکثر 3000 شناسه

ارسال ساده

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/send.json

متد : POST,GET
پارامترهای ورودی
receptor اجباری String شماره دریافت کننده پیامک را مشخص می کند که می توان با کاراکتر ویرگول "," آنها را از هم جدا کرد
message اجباری String متن پیام کوتاه ، متن مورد نظر را در حالت POST یا GET حتما بایدEncode شود
sender اختیاری String شماره خط ارسال کننده پیام مثال : 30002225 است
date اختیاری UnixTime زمان ارسال پیام ( در صورتی که خالی باشد پیام به صورت خودکار در همان لحظه ارسال می شود )
type اختیاری Integer نوع پیام در گوشی گیرنده می باشد (جدول شماره 3) فقط برای خطوط 3000 امکان پذیر است .
localid اختیاری String شناسه محلی در پایگاه داده های شما است ، اطلاعات بیشتر در بخش یادداشت نوشته شده
پارامترهای خروجی

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

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

یادداشت ها :

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

خطاها :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A37677331D/sms/send.json?receptor=09125258596,09128585774&sender=10004346&message=خدمات پیام کوتاه کاوه نگار

جواب :

{
    "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
        }
    ]
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A37677331D/sms/send.xml?receptor=09125258596,09128585774&sender=10004346&message=خدمات پیام کوتاه کاوه نگار

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>8792343</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>1</status>
            <statustext>در صف ارسال</statustext>
            <sender>10004346</sender>
            <receptor>09125258596</receptor>
            <date>1356620651</date>
            <cost>120</cost>
        </item>
        <item>
            <messageid>8792344</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>1</status>
            <statustext>در صف ارسال</statustext>
            <sender>10004346</sender>
            <receptor>09128585774</receptor>
            <date>1356620651</date>
            <cost>120</cost>
        </item>
    </entries>
</response>

ارسال گروهی

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/sendarray.json

متد : 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 شناسه این پیامک در پایگاه داده های شما است ، اطلاعات بیشتر در بخش یادداشت نوشته شده
پارامترهای خروجی

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

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

یادداشت ها :

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

خطاها :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/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
        }
    ]
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/sendarray.xml

جواب :

<response>
	<return>
		<status>200</status>
		<message>تایید شد</message>
	</return>
	<entries>
		<item>
			<messageid>8792343</messageid>
			<message>خدمات پیام کوتاه کاوه نگار</message>
			<status>1</status>
			<statustext>در صف ارسال</statustext>
			<sender>30002626</sender>
			<receptor>09121321111</receptor>
			<date>1356619709</date>
			<cost>120</cost>
		</item>
		<item>
			<messageid>8792344</messageid>
			<message>خدمات پیام کوتاه کاوه نگار</message>
			<status>1</status>
			<statustext>در صف ارسال</statustext>
			<sender>30002627</sender>
			<receptor>09121230000</receptor>
			<date>1356619709</date>
			<cost>120</cost>
		</item>
		<item>
			<messageid>8792345</messageid>
			<message>خدمات پیام کوتاه کاوه نگار</message>
			<status>1</status>
			<statustext>در صف ارسال</statustext>
			<sender>30002727</sender>
			<receptor>09123210000</receptor>
			<date>1356619709</date>
			<cost>120</cost>
		</item>		
	</entries>
</response>

دریافت وضعیت

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/status.json

متد : POST , GET
پارامترهای ورودی
messageid اجباری Long شناسه یکتای پیامک مورد نظر
پارامترهای خروجی

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

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

یادداشت ها :

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

خطاها :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/status.json?messageid=85463238,85463239

جواب :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/status.xml?messageid=85463238,85463238

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>85463238</messageid>
            <status>10</status>
            <statustext>رسیده به گیرنده</statustext>
        </item>
        <item>
            <messageid>85463239</messageid>
            <status>4</status>
            <statustext>ارسال به مخابرات</statustext>
        </item>
    </entries>
</response>

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

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/statuslocalmessageid.json

متد : POST , GET
پارامترهای ورودی
localid اجباری Long شناسه محلی پیامک مورد نظر
پارامترهای خروجی

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

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

یادداشت ها :

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

خطاها :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/statuslocalmessageid.json?localid=450

جواب :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/statuslocalmessageid.xml?localid=450

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>85463238</messageid>
											 <localid>450</localid>
            <status>10</status>
            <statustext>رسیده به گیرنده</statustext>
        </item>
     </entries>
</response>

انتخاب پیامک

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/select.json

متد : POST , GET
پارامترهای ورودی
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 حجم درخواست بیشتر از حد مجاز است ، هر فراخوانی 3000 شناسه پیامک
400 پارامترها ناقص هستند
مثال برای نمایش مثال کلیک نمایید

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/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
        }
    ]
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/select.xml?messageid=30034577,30034578

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>30034577</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>10</status>
            <statustext>رسیده به گیرنده</statustext>
            <sender>30001528961415</sender>
            <receptor>09125258596</receptor>
            <date>1356619709</date>
            <cost>120</cost>
        </item>
        <item>
            <messageid>30034578</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>11</status>
            <statustext>نرسیده به گیرنده</statustext>
            <sender>30001528961415</sender>
            <receptor>09128585774</receptor>
            <date>1356619709</date>
            <cost>120</cost>
        </item>
    </entries>
</response>

لیست ارسال ها

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/selectoutbox.json

متد : POST , GET
پارامترهای ورودی
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 را خالی ارسال نمائید.
  • حداکثر تعداد رکورد های خروجی این متد حداکثر 3,000 رکورد می باشد ، قابلیت Paging به این متد به زودی اضافه میشود.
  • تاریخ پایان نباید از تاریخ شروع کوچکتر باشد.
  • در صورتی که میخواهید ارسال های یک خط خاص را دریافت نمائید کافیست پارامتر Sender را مقدار دهی کنید.

خطاها :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/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
        }
    ]
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/selectoutbox.xml?startdate=1409533200&enddate=1410570000

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>30034577</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>10</status>
            <statustext>رسیده به گوشی</statustext>
            <sender>30002626</sender>
            <receptor>09125258596</receptor>
            <date>1409533200</date>
            <cost>120</cost>
        </item>
        <item>
            <messageid>30034578</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>10</status>
            <statustext>رسیده به گوشی</statustext>
            <sender>30002626</sender>
            <receptor>09128585774</receptor>
            <date>1409565600</date>
            <cost>120</cost>
        </item>
    </entries>
</response>

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

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/latestoutbox.json

متد : POST , GET
UnixTime پارامترهای ورودی
pagesize اختیاری Long تعداد آخرین رکورد های مورد نیاز (حداکثر 3000 رکورد)
sender اختیاری String خط اختصاصی ارسال کننده پیامک
پارامترهای خروجی

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

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

یادداشت ها :

  • حداکثر تعداد رکورد های خروجی این متد حداکثر 3000 رکورد می باشد ، قابلیت Paging به این متد به زودی اضافه میشود.
  • در صورتی که Pagesize مقدار دهی نشود مقدار 3000 برای آن لحاظ میشود.
  • در صورتی که میخواهید ارسال های یک خط خاص را دریافت نمائید کافیست پارامتر Sender را مقدار دهی کنید.

خطاها :

412 ارسال کننده نامعتبر است یا متعلق به شما نمی باشد.
400 پارامترها ناقص هستند ، در صورتی که مقدار Pagesize بیشتر از 3000 باشد پارامتر ناقص لحاظ میشود.
مثال برای نمایش مثال کلیک نمایید

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/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
        }
    ]
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/latestoutbox.xml?pagesize=1000

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>30034577</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>10</status>
            <statustext>رسیده به گیرنده</statustext>
            <sender>30002626</sender>
            <receptor>09125258596</receptor>
            <date>1409533200</date>
            <cost>120</cost>
        </item>
        <item>
            <messageid>30034578</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>10</status>
            <statustext>رسیده به گیرنده</statustext>
            <sender>30002626</sender>
            <receptor>09128585774</receptor>
            <date>1409565600</date>
            <cost>120</cost>
        </item>
       <item>
          <messageid>30034579</messageid>
          <message>خدمات پیام کوتاه کاوه نگار</message>
          <status>10</status>
          <statustext>رسیده به گیرنده</statustext>
          <sender>30002626</sender>
          <receptor>09124585774</receptor>
          <date>1409565600</date>
          <cost>120</cost>
       </item>
    </entries>
</response>

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

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/countoutbox.json

متد : POST , GET
پارامترهای ورودی
statustext اجباری Long تاریخ شروع بازه مورد نظر به فرمت Unixtime
enddate اختیاری Long تاریخ پایان بازه مورد نظر به فرمت Unixtime
status اختیاری int در صورت تمایل به دریافت تعداد پیامک با وضعیت مورد نظر از این پارامتر استفاده نمائید
پارامترهای خروجی
startdate Long تاریخ شروع
enddate Long تاریخ پایان
sumpart Long مجموع تعداد + هر پیامک های ارسالی
sumcount Long تعداد پیامک های
cost Long هزینه پیامک های ارسالی - ریال

یادداشت ها :

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

خطاها :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/countoutbox.json?startdate=1409533200&enddate=1410570000&status=10

جواب :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/countoutbox.xml?startdate=1409533200&enddate=1410570000&status=10

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <startdate>1409533200</startdate>
            <enddate>1409533200</enddate>
            <sumpart>45000</sumpart>
            <sumcount>15000</sumcount>
            <cost>5175000</cost>
        </item>
    </entries>
</response>

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

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/cancel.json

متد : POST , GET
پارامترهای ورودی
messageid اجباری Long شناسه یکتای پیامک مورد نظر
پارامترهای خروجی

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

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

یادداشت ها :

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

خطاها :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/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" : "لغو شده"
        }   
    ]
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/cancel.xml?messageid=31031212,31031213,31031214

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
       <item>
          <messageid>31031212</messageid>
          <status>13</status>
          <statustext>لغو شده</statustext>
       </item> 
          <item>
          <messageid>31031213</messageid>
          <status>13</status>
          <statustext>لغو شده</statustext>
       </item> 
       <item>
          <messageid>31031214</messageid>
          <status>13</status>
          <statustext>لغو شده</statustext>
       </item> 
    </entries>
</response>

دریافت پیامک

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/receive.json

متد : POST , GET
پارامترهای ورودی
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/613472435563797A3767733D/sms/receive.json?linenumber=3000202030&status=0

جواب :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/receive.xml?linenumber=3000202030&status=0

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>35850015</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <sender>09360462960</sender>
            <receptor>3000202030</receptor>
            <date>1357103281</date>
        </item>
        <item>
            <messageid>35850016</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <sender>09123832441</sender>
            <receptor>3000202030</receptor>
            <date>1357103281</date>
        </item>
    </entries>
</response>

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

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/countinbox.json

متد : POST , GET
پارامترهای ورودی
startdate اجباری Long تاریخ شروع بازه مورد نظر به فرمت Unixtime
enddate اختیاری Long تاریخ پایان بازه مورد نظر به فرمت Unixtime
linenumber اختیاری String شماره خط مورد نظر ( مثل 30002225 )
isread اختیاری int وضعیت پیامک دریافتی - مقدار 0 به معنی خوانده نشده و 1 خوانده شده
پارامترهای خروجی
startdate Long تاریخ شروع
enddate Long تاریخ پایان
sumcount Long تعداد پیامک دریافت شده

یادداشت ها :

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

خطاها :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/countinbox.json?startdate=1409533200&enddate=1410570000&linenumber=10008284&isread=1

جواب :

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

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/countinbox.xml?startdate=1409533200&enddate=1410570000&linenumber=10008284&isread=1

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <startdate>1409533200</startdate>
            <enddate>1409533200</enddate>
            <sumcount>15000</sumcount>
        </item>
    </entries>
</response>

استعلام تعداد گیرنده براساس منطقه پستی

در صورتی که میخواهید از تعداد شماره موبایل در منطقه پستی خاصی اطلاع داشته باشید از این متد استفاده کنید .
توجه نمائید بیشتر شماره های موجود براساس کد پستی 5رقمی می باشند در واقع 5 رقم شروع کد پستی نشان دهنده شهر،منطقه،خیابان و کوچه است و 5 رقم دیگر به شماره پلاک و طبقه و پلاک و... اشاره دارد که در اطلاعات 5 رقم دوم در دسترس نیست ، بنابراین برای دریافت استعلام درست کد پستی کافیست 5 یا 4 یا 3 رفم اول کد پستی منطقه مورد نظر را وارد کنید.

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/countpostalcode.json

متد : POST , GET
پارامترهای ورودی
postalcode اجباری Long کد پستی منطقه مورد نظر
پارامترهای خروجی

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

section String نام اختصاری اپراتور
value Int تعداد گیرندگان

یادداشت ها :

  • در صورتی که کد پستی گیرنده 0 را برگشت داد لطفا یک رقم از سمت راست کد پستی کم کنید تا بازه بزرگ تر شود.
  • کلمات MTN و MCI نام های اختصاری همراه اول و ایرانسل می باشد
مثال برای نمایش مثال کلیک نمایید

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/countpostalcode.json?postalcode=11252

جواب :

{
    "return":
    {
        "status":200,
        "message":"تایید شد"
    },
    "entries": 
    [
        {
            "section" : "MCI" , 
            "value" : 853654
        },
        {
            "section" : "MTN" , 
            "value" : 15234 
        }
    ]
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/sms/countpostalcode.xml?postalcode=11252

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
       <item>
          <messageid>MCI</messageid>
          <status>853654</status>
       </item> 
          <item>
          <messageid>MTN</messageid>
          <status>15234</status>
       </item> 
    </entries>
</response>

ارسال پیام با کد پستی

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/sms/sendbypostalcode.json

متد : POST,GET
پارامترهای ورودی
postalcode اجباری Long کد پستی منطقه مورد نظر
sender اجباری String شماره خط ارسال کننده پیام ، مثال : 30002225
message اجباری String متن پیام کوتاه ، بهتر است متن مورد نظر را در حالت POST حتما HTML-Encode شود
mcistartindex اجباری Int ردیف شروع گیرندگان اپراتور همراه اول
mcicount اجباری Int تعداد گیرندگان مورد نظر در اپراتور همراه اول
mtnstartindex اجباری Int ردیف شروع گیرندگان اپراتور ایرانسل
mtncount اجباری Int تعداد گیرندگان مورد نظر در اپراتور ایرانسل
date اختیاری UnixTime زمان ارسال پیام ( در صورتی که خالی باشد پیام به صورت خودکار در همان لحظه ارسال می شود )
پارامترهای خروجی

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

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

یادداشت ها :

  • برای اطلاع از وضعیت پیامک به جدول وضعیت پیامک ها مراجعه نمایید .
  • برای دریافت اطلاعات و نحوه کار با تاریخ به فرمت UnixTime به اینجا مراجعه نمایید .
  • چند حالت را باهم مقدار دهی می کنیم تا بیشتر با این متد آشنا شوید :
    • ارسال به منطقه X همراه اول : 1000 شماره اول ترتیبی و ایرانسل از شماره 5000 به تعداد 4000 گیرنده ترتیبی
      MciStartindex = 0 , MciCount = 1000 MtnStartindex = 5000 , MtnCount = 4000
    • ارسال به منطقه X همراه اول : کل شماره ها و ایرانسل به تعداد 1000 گیرنده تصادفی
      MciStartindex = 0 , MciCount = 0 MtnStartindex = -1 , MtnCount = 1000
  • در صورتی که شماره ای در کد پستی مورد نظر نباشد خروجی فیلد entries خالی خواهد بود .
  • در صورتی که مقدار MciCount , MtnCount برزگ تر از تعداد کل گیرندگان آن اپراتور باشد خطای 415 به معنی اندیس شروع بزرگ تر از کل تعداد شماره های مورد نظر است رخ خواهد داد .

خطاها :

415 اندیس شروع بزرگ تر از کل تعداد شماره های مورد نظر است
417 تاریخ ارسال اشتباه است ، تاریخ آن گذشته و یا به فرمت درست ارسال نشده است .
418 اعتبار حساب شما کافی نیست .
مثال برای نمایش مثال کلیک نمایید

درخواست :

https://api.kavenegar.com/v1/613472435563797A37677331D/sms/sendbypostalcode.json?postalcode=85154&sender=300002626&message=خدمات پیام کوتاه کاوه نگار &mcistartIndex=0&mcicount=2&mtnstartindex=-1&mtncount=2

جواب :

{
    "return":
    {
        "status":200,
        "message":"تایید شد"
    },
    "entries": 
    [
        {
            "messageid":8792343,
            "message":"خدمات پیام کوتاه کاوه نگار",
            "status":1,
            "statustext":"در صف ارسال",
            "sender":"300002626",
            "receptor":"0912132111*",
            "date":1356619709,
            "cost":120
        },
        {
            "messageid":8792344,
            "message":"خدمات پیام کوتاه کاوه نگار",
            "status":1,
            "statustext":"در صف ارسال",
            "sender":"300002626",
            "receptor":"0912123000*",
            "date":1356619709,
            "cost":120
        },
        {
           "messageid":8792345,
           "message":"خدمات پیام کوتاه کاوه نگار",
           "status":1,
           "statustext":"در صف ارسال",
           "sender":"300002626",
           "receptor":"0938520525*",
           "date":1356619709,
           "cost":120
        },
        {
           "messageid":8792346,
           "message":"خدمات پیام کوتاه کاوه نگار",
           "status":1,
           "statustext":"در صف ارسال",
           "sender":"300002626",
           "receptor":"0938452142*",
           "date":1356619709,
           "cost":120
        }
    ]
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A37677331D/sms/sendbypostalcode.xml?postalcode=85154&sender=300002626&message=خدمات پیام کوتاه کاوه نگار &mcistartIndex=0&mcicount=2&mtnstartindex=-1&mtncount=2

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>8792343</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>1</status>
            <statustext>در صف ارسال</statustext>
            <sender>300002626</sender>
            <receptor>0912132111*</receptor>
            <date>1356619709</date>
            <cost>120</cost>
        </item>
        <item>
            <messageid>8792344</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>1</status>
            <statustext>در صف ارسال</statustext>
            <sender>300002626</sender>
            <receptor>0912123000*</receptor>
            <date>1356619709</date>
            <cost>120</cost>
        </item>
      <item>
            <messageid>8792345</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>1</status>
            <statustext>در صف ارسال</statustext>
            <sender>300002626</sender>
            <receptor>0938520525*</receptor>
            <date>1356619709</date>
            <cost>120</cost>
        </item>
        <item>
            <messageid>8792346</messageid>
            <message>خدمات پیام کوتاه کاوه نگار</message>
            <status>1</status>
            <statustext>در صف ارسال</statustext>
            <sender>300002626</sender>
            <receptor>0938452142*</receptor>
            <date>1356619709</date>
            <cost>120</cost>
        </item>
    </entries>
</response>

اعتبار سنجی Lookup

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

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

ممنون از ثبت نام شما
کد تایید عضویت token%

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

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/verify/lookup.json

متد : POST , GET
پارامترهای ورودی
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/613472435563797A3767733D/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
   }    
    
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/verify/lookup.xml?receptor=09361234567&token=852596&=myverification

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>8792343</messageid>
            <message>ممنون از ثبت نام شما کد تایید عضویت  :852596</message>
            <status>5</status>
            <statustext>ارسال به مخابرات</statustext>
            <sender>10004346</sender>
            <receptor>09361234567</receptor>
            <date>1356620651</date>
            <cost>120</cost>
        </item>
    </entries>
</response>

تماس صوتی TTS

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/call/maketts.json

متد : POST , GET
پارامترهای ورودی
receptor اجباری String شماره دریافت کننده پیامک را مشخص می کند که می توان با کاراکتر ویرگول "," آنها را از هم جدا کرد
message اجباری String متن پیام کوتاه ، متن مورد نظر را در حالت POST یا GET حتما بایدEncode شود
date اختیاری UnixTime زمان ارسال پیام ( در صورتی که خالی باشد پیام به صورت خودکار در همان لحظه ارسال می شود )
localid اختیاری String شناسه محلی در پایگاه داده های شما است ، اطلاعات بیشتر در بخش یادداشت نوشته شده
پارامترهای خروجی
messageid Long شناسه یکتای این پیامک
برای اطلاع از وضعیت پیامک ارسالی این مقدار ورودی متد Status می باشد.
message String متن پیامک ارسال شده
status Integer وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
statustext String متن توضیح وضعیت عددی این پیامک - اطلاعات بیشتر جدول وضعیت پیامک ها
sender String شماره فرستنده
receptor String شماره گیرنده
date UnixTime زمان ارسال این پیامک به فرمت UnixTime
cost Integer هزینه این پیامک ( ریال)

یادداشت ها :

  • برای اطلاع از وضعیت پیامک به جدول وضعیت پیامک ها مراجعه نمایید .
  • برای دریافت اطلاعات و نحوه کار با تاریخ به فرمت 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
   }    
    
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/call/maketts.xml?receptor=09361234567&&message=

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
            <messageid>8792343</messageid>
            <message>ممنون از ثبت نام شما کد تایید عضویت  :852596</message>
            <status>5</status>
            <statustext>ارسال به مخابرات</statustext>
            <sender>10004346</sender>
            <receptor>09361234567</receptor>
            <date>1356620651</date>
            <cost>120</cost>
        </item>
    </entries>
</response>

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

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/account/info.json

متد : POST ، GET
پارامترهای ورودی

کافیست این متد را بدون هیچ پارامتر اضافی فراخوانی کنید . خروجی ، مشخصات API Key قرار داده شده در URL می باشد .

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

یادداشت ها :

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

درخواست :

https://api.kavenegar.com/v1//613472435563797A3767733D/account/info.json

جواب :

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

درخواست :

https://api.kavenegar.com/v1//613472435563797A3767733D/account/info.json

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
       <remaincredit>1500000</remaincredit>
       <expiredate>13548889</expiredate>
       <type>master</type>
    </entries>
</response>

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

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

ساختار URL :

https://api.kavenegar.com/v1/Your-API-Key/account/config.json

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

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

apilogs String مقادیر این پارامتر دارای سه حالت است که توصیه میشود بخش یادداشت ها را مطالع نمائید
dailyreport String در صورت فعال بودن هر روز ساعت 10 صبح گزارش ارسال و دریافت دیروز را برای شما پیامک میکند
debugmode String در صورت فعال بودن هیچ یک از پیامک های شما ارسال نخواهند شد و وضعیت لغو شده خواهند گرفت
defaultsender String خط ارسال کننده پیش فرض اکانت را مشخص می کند برای اطلاعات بیشتر به یادداشت مراجعه فرمائید
mincreditalarm Int
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/613472435563797A3767733D/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"
   }    
    
}

درخواست :

https://api.kavenegar.com/v1/613472435563797A3767733D/account/config.xml?defaultsender=10004535&apilogs=justfaults&debugmode=enabled

جواب :

<response>
    <return>
        <status>200</status>
        <message>تایید شد</message>
    </return>
    <entries>
        <item>
		<apilogs>justfaults</apilogs>
		<dailyreport>disabled</dailyreport>
		<debugmode>enabled</debugmode>
		<defaultsender>10004535</defaultsender>
		<mincreditalarm>50000</mincreditalarm>
		<resendfailed>true</resendfailed>
        </item>
    </entries>
</response>

کدهای برگشتی

کد توضیحات
200 درخواست تایید شد
400 پارامترها ناقص هستند
401 حساب کاربری غیرفعال شده است
402 عملیات ناموفق بود
403 کد شناسائی API-Key معتبر نمی باشد
404 متد نامشخص است
405 متد Get/Post اشتباه است
406 پارامترهای اجباری خالی ارسال شده اند
407 دسترسی به اطلاعات مورد نظر برای شما امکان پذیر نیست
409 سرور قادر به پاسخگوئی نیست بعدا تلاش کنید
411 دریافت کننده نامعتبر است
412 ارسال کننده نامعتبر است
413 پیام خالی است و یا طول پیام بیش از حد مجاز می باشد. لاتین ﻛﺎراﻛﺘﺮ و ﻓﺎرﺳﻲ 268 ﻛﺎراﻛﺘﺮ
414 حجم درخواست بیشتر از حد مجاز است ،ارسال پیامک :هر فراخوانی حداکثر 200 رکوردو کنترل وضعیت :هر فراخوانی 3000 رکورد
415 اندیس شروع بزرگ تر از کل تعداد شماره های مورد نظر است
417 تاریخ معتبر نمی باشد ، مقدار 0 به معنای زمان فعلی است و در غیر اینصورت فرمت UnixTime را ارسال نمایید.
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 درصورتی که موبایل شخص گیرنده دارای یک نرم افزار کابردی خاص برای ذخیره پیامک باشد و یا به یک نرم افزار کاربردی خاص برروی یک کامپیوترمتصل باشد، پیامک دریافتی درآن نرم افزارها ذخیره میشود.
^