مستندات API سرویس Spark

۱. احراز هویت

تمامی درخواست‌ها به این API باید با استفاده از هدرهای HTTP احراز هویت شوند. شما باید کلید (`API Key`) و پسورد (`API Pass`) خود را در هدر هر درخواست ارسال کنید.

X-API-KEY: کلید API منحصر به فرد شما.

X-API-PASS: پسورد API شما.

IP: در صورت ثبت ایپی سرور حتما باید با همان ایپی درخواست دهید

⚠️ نکته امنیتی: هرگز کلید و پسورد خود را در بدنه درخواست (payload) یا به صورت پارامتر در URL ارسال نکنید.

۲. ارسال پیامک (SMS)

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

POST /api/send_sms.php

پارامترهای درخواست (JSON Body)

پارامتر	نوع	توضیحات	الزامی
template_id	Integer	شناسه پترن تایید شده	بله
mobile	String	شماره موبایل گیرنده (09xxxxxxxxx)	بله
parameters	Object	آبجکت متغیرهای پترن	بله
sl	Integer	شماره خط ارسال (1، 2 یا 3). پیش‌فرض 2 است.	خیر

نمونه پاسخ موفق

{
    "status": true,
    "data": {
        "message_sent": true,
        "cost": 250,
        "segments": 1,
        "sent_from": "YOUR_SENDER_NUMBER"
    }
}

curl -X POST https://spark.darkzed.ir/api/send_sms.php \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "X-API-PASS: YOUR_API_PASS" \
-d '{
    "template_id": 123,
    "mobile": "09123456789",
    "parameters": {
        "name": "علی",
        "code": "54321"
    },
    "sl": 1
}'

<?php
$apiKey = 'YOUR_API_KEY';
$apiPass = 'YOUR_API_PASS';
$url = 'https://spark.darkzed.ir/api/send_sms.php';

$payload = json_encode([
    'template_id' => 123,
    'mobile'      => '09123456789',
    'parameters'  => [ 'name' => 'علی', 'code' => '54321' ],
    'sl' => 1
]);

$headers = [
    'Content-Type: application/json',
    'X-API-KEY: ' . $apiKey,
    'X-API-PASS: ' . $apiPass
];

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_TIMEOUT => 15
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

import requests
import json

api_key = "YOUR_API_KEY"
api_pass = "YOUR_API_PASS"
url = "https://spark.darkzed.ir/api/send_sms.php"

payload = {
    "template_id": 123,
    "mobile": "09123456789",
    "parameters": { "name": "علی", "code": "54321" },
    "sl": 1
}

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": api_key,
    "X-API-PASS": api_pass
}

try:
    response = requests.post(url, data=json.dumps(payload), headers=headers, timeout=15)
    response.raise_for_status()
    print(response.json())
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

۳. ارسال ایمیل (Email)

این Endpoint برای ارسال ایمیل‌های مبتنی بر قالب‌های تایید شده استفاده می‌شود.

POST /api/send_email.php

پارامترهای درخواست (JSON Body)

پارامتر	نوع	توضیحات	الزامی
template_id	Integer	شناسه قالب ایمیل تایید شده	بله
email	String	آدرس ایمیل گیرنده	بله
parameters	Object	آبجکت متغیرهای قالب	بله

نمونه پاسخ موفق

{
    "status": true,
    "data": {
        "email_request_sent": true
    }
}

curl -X POST https://spark.darkzed.ir/api/send_email.php \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "X-API-PASS: YOUR_API_PASS" \
-d '{
    "template_id": 456,
    "email": "recipient@example.com",
    "parameters": {
        "user": "مریم",
        "invoice_id": "9876"
    }
}'

<?php
$apiKey = 'YOUR_API_KEY';
$apiPass = 'YOUR_API_PASS';
$url = 'https://spark.darkzed.ir/api/send_email.php';

$payload = json_encode([
    'template_id' => 456,
    'email'       => 'recipient@example.com',
    'parameters'  => [ 'user' => 'مریم', 'invoice_id' => '9876' ]
]);

$headers = [
    'Content-Type: application/json',
    'X-API-KEY: ' . $apiKey,
    'X-API-PASS: ' . $apiPass
];

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_TIMEOUT => 15
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

import requests
import json

api_key = "YOUR_API_KEY"
api_pass = "YOUR_API_PASS"
url = "https://spark.darkzed.ir/api/send_email.php"

payload = {
    "template_id": 456,
    "email": "recipient@example.com",
    "parameters": { "user": "مریم", "invoice_id": "9876" }
}

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": api_key,
    "X-API-PASS": api_pass
}

try:
    response = requests.post(url, data=json.dumps(payload), headers=headers, timeout=15)
    response.raise_for_status()
    print(response.json())
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

۴. کدهای خطا

کد وضعیت HTTP	کد خطا (error_code)	توضیحات
400 Bad Request	2001 / 3001	پارامترهای ارسالی ناقص یا نامعتبر هستند.
401 Unauthorized	1001 / 1006	کلید یا پسورد API ارسال نشده یا اشتباه است.
402 Payment Required	2003	موجودی حساب شما برای انجام عملیات کافی نیست.
403 Forbidden	1003 / 1004	کلید API شما فعال نیست یا دسترسی از IP شما مجاز نیست.
404 Not Found	1002 / 2002	کلید API یا شناسه قالب/پترن یافت نشد.
500 Internal Server Error	1005	یک خطای داخلی در سرور رخ داده است.
503 Service Unavailable	2005 / 3005	سرویس‌دهنده خارجی (پیامک/ایمیل) در دسترس نیست.