۱. مقدمه و نحوه ارتباط (Overview)
تمامی متدها به صورت RESTful پیادهسازی شدهاند و ورودیها و خروجیها در قالب استاندارد JSON با انکودینگ UTF-8 ارسال و دریافت میشوند. این صفحه به صورت عمومی و بدون نیاز به لاگین در دسترس است.
۲. احراز هویت (Bearer Token)
احراز هویت وبسرویس از طریق ارسال کلید امنیتی (API Token) در هدر استاندارد Authorization صورت میپذیرد. کلید اختصاصی توسط مدیریت سیستم صادر میگردد.
Content-Type: application/json
Accept: application/json
۳. ثبتنام مسافرین انفرادی عتبات
از این متد برای ثبت اطلاعات یک خانواده یا گروه مسافران (از یک نفر تا هر تعداد نفر)، ثبت اطلاعات اقامت در نجف اشرف و درج کد رهگیری پرداخت استفاده میشود.
جدول پارامترهای ارسالی (Request Body)
کلیه پارامترهای زیر باید در بدنه درخواست (JSON Body) ارسال گردند:
| نام پارامتر | نوع داده | وضعیت | توضیحات و فرمت مجاز | نمونه مقدار |
|---|---|---|---|---|
| entry_date | string | اجباری | تاریخ ورود به نجف اشرف (فرمت شمسی YYYY/MM/DD یا میلادی) | "1405/01/10" |
| exit_date | string | اجباری | تاریخ خروج از نجف اشرف | "1405/01/15" |
| province | string | اجباری | نام استان اعزامکننده مسافرین | "خراسان رضوی" |
| leader_phone | string | اجباری | شماره تلفن همراه سرپرست جهت هماهنگی و اطلاعرسانی پیامکی | "09151234567" |
| payment_ref_id | string | اجباری | شماره پیگیری / کد مرجع تراکنش پرداخت بانکی (RefID) | "TRX-99887766" |
| paid_amount | integer | اجباری | مبلغ پرداختی به تومان | 15000000 |
| hotel_name | string | اختیاری | نام هتل محل اقامت در نجف (پیشفرض: هتل نجف اشرف) | "هتل قصر الدر نجف" |
| passengers | array | اجباری | آرایهای از مشخصات مسافران خانواده (حداقل یک نفر) | [ ... ] |
| passengers[].first_name | string | اجباری | نام مسافر | "محمد" |
| passengers[].last_name | string | اجباری | نام خانوادگی مسافر | "رضایی" |
| passengers[].national_id | string | اجباری | کد ملی ۱۰ رقمی مسافر | "0921234567" |
| passengers[].birth_date | string | اجباری | تاریخ تولد مسافر (فرمت شمسی YYYY/MM/DD) جهت محاسبه رده سنی | "1365/02/15" |
| passengers[].relationship | string | اجباری | نسبت با سرپرست (مثال: سرپرست، همسر، فرزند، مادر، پدر، ...) | "سرپرست" |
| passengers[].gender | string | اختیاری | جنسیت مسافر (male / female / مرد / زن) |
"male" |
| passengers[].phone | string | اختیاری | شماره همراه اختصاصی مسافر (در صورت وجود) | "09151234567" |
نمونه کدهای ارسال درخواست (Request Code Samples)
curl --location 'https://asemansarir.ir/api/atabat/individual-registration' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"entry_date": "1405/01/10",
"exit_date": "1405/01/15",
"province": "خراسان رضوی",
"leader_phone": "09151234567",
"payment_ref_id": "TRX-99887766",
"paid_amount": 15000000,
"hotel_name": "هتل قصر الدر نجف",
"passengers": [
{
"first_name": "محمد",
"last_name": "رضایی",
"national_id": "0921234567",
"birth_date": "1365/02/15",
"relationship": "سرپرست",
"gender": "male"
},
{
"first_name": "فاطمه",
"last_name": "سلیمانی",
"national_id": "0929876543",
"birth_date": "1370/08/20",
"relationship": "همسر",
"gender": "female"
},
{
"first_name": "علی",
"last_name": "رضایی",
"national_id": "0925556667",
"birth_date": "1401/05/10",
"relationship": "فرزند",
"gender": "male"
}
]
}'
<?php
$apiToken = 'YOUR_API_TOKEN';
$url = 'https://asemansarir.ir/api/atabat/individual-registration';
$payload = [
'entry_date' => '1405/01/10',
'exit_date' => '1405/01/15',
'province' => 'خراسان رضوی',
'leader_phone' => '09151234567',
'payment_ref_id' => 'TRX-99887766',
'paid_amount' => 15000000,
'hotel_name' => 'هتل قصر الدر نجف',
'passengers' => [
[
'first_name' => 'محمد',
'last_name' => 'رضایی',
'national_id' => '0921234567',
'birth_date' => '1365/02/15',
'relationship' => 'سرپرست',
'gender' => 'male',
],
[
'first_name' => 'فاطمه',
'last_name' => 'سلیمانی',
'national_id' => '0929876543',
'birth_date' => '1370/08/20',
'relationship' => 'همسر',
'gender' => 'female',
],
[
'first_name' => 'علی',
'last_name' => 'رضایی',
'national_id' => '0925556667',
'birth_date' => '1401/05/10',
'relationship' => 'فرزند',
'gender' => 'male',
]
]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $apiToken,
'Content-Type: application/json',
'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload, JSON_UNESCAPED_UNICODE));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpCode === 201 && ($result['success'] ?? false)) {
echo "ثبت موفق! کد رهگیری: " . $result['data']['tracking_code'] . "\n";
echo "آدرس رسید چاپی: " . $result['data']['tracking_pdf_url'] . "\n";
} else {
echo "خطا در ثبت اطلاعات: " . ($result['message'] ?? 'نامشخص') . "\n";
print_r($result);
}
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client();
$response = $client->post('https://asemansarir.ir/api/atabat/individual-registration', [
'headers' => [
'Authorization' => 'Bearer YOUR_API_TOKEN',
'Accept' => 'application/json',
],
'json' => [
'entry_date' => '1405/01/10',
'exit_date' => '1405/01/15',
'province' => 'خراسان رضوی',
'leader_phone' => '09151234567',
'payment_ref_id' => 'TRX-99887766',
'paid_amount' => 15000000,
'passengers' => [
[
'first_name' => 'محمد',
'last_name' => 'رضایی',
'national_id' => '0921234567',
'birth_date' => '1365/02/15',
'relationship' => 'سرپرست',
]
]
]
]);
$data = json_decode($response->getBody(), true);
print_r($data);
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
public class Program
{
public static async Task Main()
{
var client = new HttpClient();
client.BaseAddress = new Uri("https://asemansarir.ir");
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
client.DefaultRequestHeaders.Accept.Add(
new MediaTypeWithQualityHeaderValue("application/json"));
var payload = new
{
entry_date = "1405/01/10",
exit_date = "1405/01/15",
province = "خراسان رضوی",
leader_phone = "09151234567",
payment_ref_id = "TRX-99887766",
paid_amount = 15000000,
hotel_name = "هتل قصر الدر نجف",
passengers = new[]
{
new { first_name = "محمد", last_name = "رضایی", national_id = "0921234567", birth_date = "1365/02/15", relationship = "سرپرست", gender = "male" },
new { first_name = "فاطمه", last_name = "سلیمانی", national_id = "0929876543", birth_date = "1370/08/20", relationship = "همسر", gender = "female" }
}
};
var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("/api/atabat/individual-registration", content);
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Status: {response.StatusCode}");
Console.WriteLine(responseString);
}
}
using RestSharp;
using System;
using System.Threading.Tasks;
var client = new RestClient("https://asemansarir.ir");
var request = new RestRequest("/api/atabat/individual-registration", Method.Post);
request.AddHeader("Authorization", "Bearer YOUR_API_TOKEN");
request.AddHeader("Accept", "application/json");
request.AddJsonBody(new
{
entry_date = "1405/01/10",
exit_date = "1405/01/15",
province = "خراسان رضوی",
leader_phone = "09151234567",
payment_ref_id = "TRX-99887766",
paid_amount = 15000000,
passengers = new[]
{
new { first_name = "محمد", last_name = "رضایی", national_id = "0921234567", birth_date = "1365/02/15", relationship = "سرپرست" }
}
});
var response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
const url = 'https://asemansarir.ir/api/atabat/individual-registration';
const token = 'YOUR_API_TOKEN';
const payload = {
entry_date: '1405/01/10',
exit_date: '1405/01/15',
province: 'خراسان رضوی',
leader_phone: '09151234567',
payment_ref_id: 'TRX-99887766',
paid_amount: 15000000,
hotel_name: 'هتل قصر الدر نجف',
passengers: [
{
first_name: 'محمد',
last_name: 'رضایی',
national_id: '0921234567',
birth_date: '1365/02/15',
relationship: 'سرپرست',
gender: 'male'
},
{
first_name: 'فاطمه',
last_name: 'سلیمانی',
national_id: '0929876543',
birth_date: '1370/08/20',
relationship: 'همسر',
gender: 'female'
}
]
};
async function register() {
const res = await fetch(url, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify(payload)
});
const result = await res.json();
console.log('Response:', result);
}
register();
import requests
url = "https://asemansarir.ir/api/atabat/individual-registration"
headers = {
"Authorization": "Bearer YOUR_API_TOKEN",
"Content-Type": "application/json",
"Accept": "application/json"
}
payload = {
"entry_date": "1405/01/10",
"exit_date": "1405/01/15",
"province": "خراسان رضوی",
"leader_phone": "09151234567",
"payment_ref_id": "TRX-99887766",
"paid_amount": 15000000,
"hotel_name": "هتل قصر الدر نجف",
"passengers": [
{
"first_name": "محمد",
"last_name": "رضایی",
"national_id": "0921234567",
"birth_date": "1365/02/15",
"relationship": "سرپرست",
"gender": "male"
}
]
}
response = requests.post(url, json=payload, headers=headers)
print("Status Code:", response.status_code)
print("Data:", response.json())
جدول توضیحات مقادیر پاسخ (Response Parameters Table)
توضیحات و نوع دادههای خروجی ارسال شده در پاسخ وبسرویس:
| نام فیلد خروجی | نوع داده | توضیحات و مفهوم مقدار | نمونه مقدار خروجی |
|---|---|---|---|
| success | boolean | وضعیت کلی اجرای درخواست (true در صورت ثبت موفق، false در صورت بروز خطا) | true |
| message | string | پیام متنی فارسی وضعیت پردازش جهت نمایش به کاربر یا لاگ سیستم | "ثبتنام مسافرین انفرادی با موفقیت در سامانه ثبت شد." |
| data | object | شیء اصلی حاوی مشخصات رکورد ثبت شده در پایگاه داده | { ... } |
| data.registration_id | integer | شناسه عددی یکتا (ID) ثبتنام در دیتابیس سامانه | 9 |
| data.tracking_code | string | کد رهگیری استاندارد سامانه (جهت پیگیریهای بعدی زائرین) | "IND-20260902-8412" |
| data.head_name | string | نام و نام خانوادگی کامل سرپرست خانواده | "محمد رضایی" |
| data.head_national_id | string | کد ملی سرپرست خانواده | "0921234567" |
| data.leader_phone | string | شماره همراه سرپرست | "09151234567" |
| data.province | string | استان محل سکونت / اعزام | "خراسان رضوی" |
| data.passengers_count | integer | تعداد کل مسافران ثبت شده در این درخواست | 3 |
| data.entry_date | string | تاریخ ورود ثبت شده به نجف اشرف | "1405/01/10" |
| data.exit_date | string | تاریخ خروج ثبت شده از نجف اشرف | "1405/01/15" |
| data.hotel_name | string | نام هتل محل اقامت اختصاص یافته | "هتل قصر الدر نجف" |
| data.paid_amount | integer | مبلغ پرداختی ثبت شده به تومان | 15000000 |
| data.payment_ref_id | string | شماره پیگیری پرداخت بانکی ثبت شده | "TRX-99887766" |
| data.tracking_pdf_url | string | آدرس مستقیم اینترنتی جهت مشاهده، دانلود و پرینت رسید چاپی مسافرین | "http://.../atabat/individual-registration/9/tracking-pdf" |
| data.created_at | string | تاریخ و زمان ثبت به فرمت استاندارد ISO-8601 | "2026-09-02T10:58:06+03:30" |
نمونه پاسخ موفق (کد 201 Created)
نمونه پاسخ ناموفق / خطای اعتبارسنجی (کد 422 Unprocessable Entity)
۴. رسید چاپی و پیگیری مسافرین (Tracking PDF)
به ازای هر ثبتنام موفق، یک لینک اختصاصی در فیلد tracking_pdf_url ایجاد میگردد. این آدرس برای کاربران نهایی و زائرین عمومی بوده و نیازی به ارسال توکن احراز هویت ندارد.
۵. کدهای وضعیت و پیامهای خطا (HTTP Status Codes)
| کد وضعیت | عنوان وضعیت | توضیحات و علت رخداد |
|---|---|---|
| 201 Created | موفقیتآمیز | درخواست با موفقیت ثبت شد و اطلاعات مسافرین و کد رهگیری ایجاد گردید. |
| 400 Bad Request | درخواست ناقص | بدنه درخواست ارسال نشده یا فرمت JSON ارسالی نامعتبر است. |
| 401 Unauthorized | عدم احراز هویت | توکن Bearer ارسال نشده، اشتباه است یا منقضی شده است. |
| 403 Forbidden | عدم دسترسی | توکن غیرفعال شده است، IP ارسالی مجاز نیست یا مجوز سرویس را ندارد. |
| 422 Unprocessable Entity | خطای اعتبارسنجی فیلدها | یک یا چند فیلد اجباری ارسال نشده یا فرمت نامعتبر دارند (لیست خطاها در کلید errors قرار دارد). |