مستندات وب‌سرویس NivaSMS

معرفی

این مستندات برای اتصال به وب‌سرویس پیامک NivaSMS تهیه شده است. مسیرها و ساختار درخواست/پاسخ مطابق استاندارد Edge طراحی شده‌اند و شما می‌توانید از همان الگوهای رایج SDKها و نمونه‌کدها استفاده کنید.

Base URL

تمامی درخواست‌ها به مسیر زیر ارسال می‌شوند:

https://nivasms.ir/v1

احراز هویت

برای بیشتر متدها باید هدر Authorization را ارسال کنید. این مقدار می‌تواند توکن یا API Key باشد.

Token: معمولاً بعد از ورود دریافت می‌شود و مدت اعتبار محدودی دارد (برای مثال ۱۰ ساعت).
API Key: کلید دائمی است و معمولاً از داخل پنل کاربری قابل ساخت/مدیریت است.

هدرهای مشترک

کلید	مقدار	توضیح
Authorization	YOUR_TOKEN_OR_API_KEY	توکن یا API Key خود را در این هدر قرار دهید.
Content-Type	application/json	برای درخواست‌های JSON (در ارسال‌های وب‌سرویس/پترن معمولاً لازم است).

فرمت پاسخ‌ها

پاسخ‌ها معمولاً دو بخش دارند: data و meta. مقدار meta.status نشان می‌دهد درخواست موفق بوده یا خیر.

{
  "data": {
    "example": true
  },
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

{
  "data": null,
  "meta": {
    "status": false,
    "message": "Validation error",
    "message_code": "validation_error",
    "message_parameters": [],
    "errors": {
      "field": ["This field is required"]
    }
  }
}

محدودیت‌ها

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

ورود و دریافت توکن

POST /api/auth/login

برای دریافت توکن، با نام کاربری/رمز عبور وارد شوید. (این متد نیاز به هدر Authorization ندارد.)

بدنه درخواست

پارامتر	نوع	اجباری	توضیح
username	string		نام کاربری پنل
password	string		رمز عبور

curl -X POST https://nivasms.ir/v1/api/auth/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

<?php

$ch = curl_init('https://nivasms.ir/v1/api/auth/login');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Accept: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'username' => 'YOUR_USERNAME',
    'password' => 'YOUR_PASSWORD',
  ], JSON_UNESCAPED_UNICODE),
]);

$res = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $code . PHP_EOL;
echo $res;

{
  "data": {
    "token": "eyJ...",
    "expires_in": 36000
  },
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

token را از پاسخ بردارید و در هدر Authorization استفاده کنید.

بررسی اعتبار توکن

GET /api/auth/check-token

برای اطمینان از معتبر بودن توکن/کلید.

curl -X GET https://nivasms.ir/v1/api/auth/check-token \
  -H 'Authorization: YOUR_TOKEN_OR_API_KEY' \
  -H 'Accept: application/json'

{
  "data": {
    "valid": true
  },
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

خروج

POST /api/auth/logout

ابطال توکن (در صورتی که از توکن استفاده می‌کنید).

curl -X POST https://nivasms.ir/v1/api/auth/logout \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Accept: application/json'

{
  "data": null,
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

ارسال وب‌سرویس

POST /api/send

ارسال پیامک معمولی با متن دلخواه. مقدار sending_type باید webservice باشد.

بدنه درخواست

پارامتر	نوع	توضیح
sending_type	string	نوع ارسال: `webservice`
from	string	شماره فرستنده (خط)
to	array	لیست شماره‌های مقصد
message	string	متن پیامک

curl -X POST https://nivasms.ir/v1/api/send \
  -H 'Authorization: YOUR_TOKEN_OR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"sending_type":"webservice","from":"+983000505","to":["+989120000000"],"message":"سلام از NivaSMS"}'

<?php

$payload = [
  'sending_type' => 'webservice',
  'from' => '+983000505',
  'to' => ['+989120000000'],
  'message' => 'سلام از NivaSMS',
];

$ch = curl_init('https://nivasms.ir/v1/api/send');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: YOUR_TOKEN_OR_API_KEY',
    'Content-Type: application/json',
    'Accept: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);

$res = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $code . PHP_EOL;
echo $res;

const url = 'https://nivasms.ir/v1/api/send';

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_TOKEN_OR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    sending_type: 'webservice',
    from: '+983000505',
    to: ['+989120000000'],
    message: 'سلام از NivaSMS',
  }),
})
  .then(r => r.json())
  .then(console.log)
  .catch(console.error);

import requests

url = 'https://nivasms.ir/v1/api/send'
headers = {
  'Authorization': 'YOUR_TOKEN_OR_API_KEY',
  'Content-Type': 'application/json',
  'Accept': 'application/json',
}
payload = {
  'sending_type': 'webservice',
  'from': '+983000505',
  'to': ['+989120000000'],
  'message': 'سلام از NivaSMS',
}

r = requests.post(url, json=payload, headers=headers, timeout=15)
print(r.status_code)
print(r.text)

{
  "data": {
    "bulk_id": 123456
  },
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

شناسه ارسال (مثلاً bulk_id) را برای گزارش‌ها نگه دارید.

ارسال پترن

POST /api/send

ارسال پیامک بر اساس پترن/قالب. مقدار sending_type باید pattern باشد.

بدنه درخواست

پارامتر	نوع	توضیح
sending_type	string	نوع ارسال: `pattern`
pattern_code	string\|int	کد پترن
mobile	string	شماره مقصد
variables	object	متغیرهای پترن (کلید/مقدار)

curl -X POST https://nivasms.ir/v1/api/send \
  -H 'Authorization: YOUR_TOKEN_OR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"sending_type":"pattern","pattern_code":"abcd1234","mobile":"+989120000000","variables":{"code":"12345"}}'

<?php

$payload = [
  'sending_type' => 'pattern',
  'pattern_code' => 'abcd1234',
  'mobile' => '+989120000000',
  'variables' => [
    'code' => '12345',
  ],
];

$ch = curl_init('https://nivasms.ir/v1/api/send');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: YOUR_TOKEN_OR_API_KEY',
    'Content-Type: application/json',
    'Accept: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);

$res = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $code . PHP_EOL;
echo $res;

{
  "data": {
    "message_id": 987654
  },
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

لیست ارسال‌ها (Outbox)

GET /api/report/outbox

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

Query Params (اختیاری)

پارامتر	نوع	اجباری	توضیح
page	int		شماره صفحه
per_page	int		تعداد در هر صفحه

curl -X GET 'https://nivasms.ir/v1/api/report/outbox?page=1&per_page=20' \
  -H 'Authorization: YOUR_TOKEN_OR_API_KEY' \
  -H 'Accept: application/json'

{
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "per_page": 20
    }
  },
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

جزئیات یک ارسال

GET /api/report/outbox/{bulk_id}

دریافت جزئیات و وضعیت یک ارسال بر اساس شناسه bulk_id.

Path Params

پارامتر	نوع	اجباری	توضیح
bulk_id	int		شناسه ارسال

curl -X GET https://nivasms.ir/v1/api/report/outbox/123456 \
  -H 'Authorization: YOUR_TOKEN_OR_API_KEY' \
  -H 'Accept: application/json'

{
  "data": {
    "bulk_id": 123456
  },
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

لیست دریافتی‌ها (Inbox)

GET /api/report/inbox

لیست پیامک‌های دریافتی روی خطوط شما.

Query Params (اختیاری)

پارامتر	نوع	اجباری	توضیح
page	int		شماره صفحه
per_page	int		تعداد در هر صفحه

curl -X GET 'https://nivasms.ir/v1/api/report/inbox?page=1&per_page=20' \
  -H 'Authorization: YOUR_TOKEN_OR_API_KEY' \
  -H 'Accept: application/json'

{
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "per_page": 20
    }
  },
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

اعتبار من

GET /api/payment/credit/mine

مشاهده اعتبار/کیف پول حساب کاربری.

curl -X GET https://nivasms.ir/v1/api/payment/credit/mine \
  -H 'Authorization: YOUR_TOKEN_OR_API_KEY' \
  -H 'Accept: application/json'

{
  "data": {
    "credit": 10000
  },
  "meta": {
    "status": true,
    "message": "OK",
    "message_code": "ok",
    "message_parameters": []
  }
}

کدها و خطاهای رایج

HTTP	عنوان	توضیح
200	موفق	درخواست با موفقیت انجام شد.
400	درخواست نامعتبر	ساختار درخواست یا پارامترها اشتباه است.
401	عدم احراز هویت	Authorization ارسال نشده یا نامعتبر است.
403	عدم دسترسی	به این متد دسترسی ندارید یا مجوز لازم را ندارید.
404	یافت نشد	مسیر یا منبع درخواستی وجود ندارد.
422	اعتبارسنجی	پارامترها صحیح نیستند. جزئیات در `meta.errors` می‌آید.
429	محدودیت درخواست	تعداد درخواست‌ها زیاد است. کمی صبر کنید و دوباره تلاش کنید.
500	خطای سرور	خطای داخلی سرور.
502	خطای Gateway	عدم ارتباط با سرویس بالادستی.

مستندات API

معرفی

Base URL

احراز هویت

فرمت پاسخ‌ها

محدودیت‌ها

ورود و دریافت توکن

بدنه درخواست

بررسی اعتبار توکن

خروج

ارسال وب‌سرویس

بدنه درخواست

ارسال پترن

بدنه درخواست

لیست ارسال‌ها (Outbox)

Query Params (اختیاری)

جزئیات یک ارسال

Path Params

لیست دریافتی‌ها (Inbox)

Query Params (اختیاری)

اعتبار من

کدها و خطاهای رایج