ارسال گروهی
وقتی تعداد گیرندگان از ۱۰۰ بیشتر است، آنها را در چند درخواست پیاپی زیر یک شناسهی گروه (batchId) ثبت میکنید. تا زمانی که ارسال نهایی اعلام نشود، پیامی ارسال نمیشود. در درخواست آخر با IsFinal=true همهی گیرندگان یکجا ارسال میشوند. هزینهی کل پیش از ارسال نهایی محاسبه میشود و اگر اعتبار کافی نباشد، خطای کمبود موجودی همراه با مبلغ کسری برمیگردد.
مشخصات
| مورد | مقدار |
|---|---|
| متد و مسیر | POST /api/Message/SendBatch |
| احراز هویت | کلید API یا Bearer |
| نوع بدنه | application/json |
پارامترهای query
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
IsFinal | بولی | خیر | true برای ارسال نهایی گروه. پیشفرض false |
Schedule | رشته | خیر | تاریخ و ساعت شمسی ارسال، مانند 1405/08/30 10:30. در ارسال نهایی اعمال میشود |
بدنهی درخواست
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
batchId | عدد صحیح (long) | بله | شناسهی دلخواه شما برای این گروه. در همهی درخواستهای یک گروه یکسان است |
code | عدد صحیح (long) | بله | کد الگو؛ باید در همهی درخواستهای گروه یکی باشد |
lineNumber | رشته | خیر | شمارهی خط ارسال |
recipients | آرایه | بله | گیرندگان همین درخواست؛ حداکثر ۱۰۰ مورد. در درخواست نهایی میتواند خالی باشد |
ساختار هر گیرنده مانند ارسال پیامک است.
گام ۱: ثبت گیرندگان
هر درخواست حداکثر ۱۰۰ گیرنده را ثبت میکند. این درخواست را با batchId یکسان، بهتعداد لازم تکرار کنید:
- curl
- C#
- Python
- Node.js
- PHP
- Go
curl -X POST "https://api.payavasms.com/api/Message/SendBatch?IsFinal=false" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}'
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
var json = """
{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
""";
using var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.payavasms.com/api/Message/SendBatch?IsFinal=false", content);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
import requests
url = "https://api.payavasms.com/api/Message/SendBatch?IsFinal=false"
headers = {
"X-Api-Key": "YOUR_API_KEY",
}
payload = {
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.text)
const response = await fetch("https://api.payavasms.com/api/Message/SendBatch?IsFinal=false", {
method: "POST",
headers: {
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}),
});
console.log(response.status, await response.text());
<?php
$ch = curl_init("https://api.payavasms.com/api/Message/SendBatch?IsFinal=false");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-Api-Key: YOUR_API_KEY",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}
JSON,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status . " " . $response;
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
body := strings.NewReader(`{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}`)
req, _ := http.NewRequest("POST", "https://api.payavasms.com/api/Message/SendBatch?IsFinal=false", body)
req.Header.Set("X-Api-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
data, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(data))
}
گام ۲: ارسال نهایی
پس از ثبت همهی گیرندگان، با IsFinal=true ارسال را نهایی کنید. اگر گیرندهی دیگری هم باقی مانده، میتوانید در همین درخواست بفرستید؛ در غیر این صورت recipients را خالی بگذارید:
- curl
- C#
- Python
- Node.js
- PHP
- Go
curl -X POST "https://api.payavasms.com/api/Message/SendBatch?IsFinal=true" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": []
}'
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
var json = """
{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": []
}
""";
using var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.payavasms.com/api/Message/SendBatch?IsFinal=true", content);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
import requests
url = "https://api.payavasms.com/api/Message/SendBatch?IsFinal=true"
headers = {
"X-Api-Key": "YOUR_API_KEY",
}
payload = {
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": []
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.text)
const response = await fetch("https://api.payavasms.com/api/Message/SendBatch?IsFinal=true", {
method: "POST",
headers: {
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": []
}),
});
console.log(response.status, await response.text());
<?php
$ch = curl_init("https://api.payavasms.com/api/Message/SendBatch?IsFinal=true");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-Api-Key: YOUR_API_KEY",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": []
}
JSON,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status . " " . $response;
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
body := strings.NewReader(`{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": []
}`)
req, _ := http.NewRequest("POST", "https://api.payavasms.com/api/Message/SendBatch?IsFinal=true", body)
req.Header.Set("X-Api-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
data, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(data))
}
نمونهی پاسخ
{
"status": 0,
"message": "عملیات با موفقیت انجام شد.",
"data": {
"result": {
"messages": [
{
"registerCode": 10000001,
"phoneNumber": "989120000000",
"parts": 1
}
]
},
"platform": "Sms"
}
}
ساختار پاسخ مانند ارسال پیامک است.
خطاهای مخصوص ارسال گروهی
status | معنا |
|---|---|
8000 | مقادیر درخواست جدید (مثلاً کد الگو) با درخواستهای قبلی همان گروه مطابقت ندارد |
8001 | موجودی کافی نیست و مبلغ کسری در پیام آمده است |
8002 | خطا در بررسی موجودی |
8010 | شناسهی گروه در سامانه موجود نیست (مثلاً ارسال نهایی بدون ثبت قبلی) |
سایر خطاها مانند ارسال پیامک است.