آسمان سریر - مستندات فنی API
راهنمای جامع اتصال، ارسال درخواست، استعلام و دریافت رسید

راهنمای اتصال به وب‌سرویس‌های سامانه

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

۱. مقدمه و نحوه ارتباط (Overview)

تمامی متدها به صورت RESTful پیاده‌سازی شده‌اند و ورودی‌ها و خروجی‌ها در قالب استاندارد JSON با انکودینگ UTF-8 ارسال و دریافت می‌شوند. این صفحه به صورت عمومی و بدون نیاز به لاگین در دسترس است.

آدرس پایه سرویس‌ها (Base URL):
https://asemansarir.ir/api
هدر نوع محتوا (Content-Type):
application/json

۲. احراز هویت (Bearer Token)

احراز هویت وب‌سرویس از طریق ارسال کلید امنیتی (API Token) در هدر استاندارد Authorization صورت می‌پذیرد. کلید اختصاصی توسط مدیریت سیستم صادر می‌گردد.

برای دریافت توکن اختصاصی، بر روی دکمه «دریافت و مدیریت کلید API» در بالای صفحه کلیک نمایید تا راهنمای ارتباط با مدیریت را مشاهده فرمایید.
Authorization: Bearer sk_live_9f8d7e6c5b4a3...
Content-Type: application/json
Accept: application/json

۳. ثبت‌نام مسافرین انفرادی عتبات

از این متد برای ثبت اطلاعات یک خانواده یا گروه مسافران (از یک نفر تا هر تعداد نفر)، ثبت اطلاعات اقامت در نجف اشرف و درج کد رهگیری پرداخت استفاده می‌شود.

POST https://asemansarir.ir/api/atabat/individual-registration

جدول پارامترهای ارسالی (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)

{ "success": true, "message": "ثبت‌نام مسافرین انفرادی با موفقیت در سامانه ثبت شد.", "data": { "registration_id": 9, "tracking_code": "IND-20260902-8412", "head_name": "محمد رضایی", "head_national_id": "0921234567", "leader_phone": "09151234567", "province": "خراسان رضوی", "passengers_count": 3, "entry_date": "1405/01/10", "exit_date": "1405/01/15", "hotel_name": "هتل قصر الدر نجف", "paid_amount": 15000000, "payment_ref_id": "TRX-99887766", "tracking_pdf_url": "https://asemansarir.ir/atabat/individual-registration/9/tracking-pdf", "created_at": "2026-09-02T10:58:06+03:30" } }

نمونه پاسخ ناموفق / خطای اعتبارسنجی (کد 422 Unprocessable Entity)

{ "success": false, "message": "خطا در اعتبارسنجی اطلاعات ارسالی", "errors": { "entry_date": [ "فیلد تاریخ ورود به نجف (entry_date) الزامی است." ], "province": [ "فیلد استان اعزامی (province) الزامی است." ], "payment_ref_id": [ "شماره رهگیری پرداخت (payment_ref_id) الزامی است." ], "passengers.0.birth_date": [ "تاریخ تولد مسافر (birth_date) الزامی است." ], "passengers.0.relationship": [ "نسبت مسافر با سرپرست (relationship) الزامی است." ] } }

۴. رسید چاپی و پیگیری مسافرین (Tracking PDF)

به ازای هر ثبت‌نام موفق، یک لینک اختصاصی در فیلد tracking_pdf_url ایجاد می‌گردد. این آدرس برای کاربران نهایی و زائرین عمومی بوده و نیازی به ارسال توکن احراز هویت ندارد.

GET https://asemansarir.ir/atabat/individual-registration/{id}/tracking-pdf
امکانات صفحه رسید: شامل سربرگ رسمی آژانس، اطلاعات کامل سرپرست، جدول مشخصات تک‌تک همراهان، تاریخ‌های ورود/خروج نجف، مشخصات هتل، جدول مبالغ پرداختی و کد رهگیری بانک همراه با دکمه چاپ مستقیم روی برگه A4.

۵. کدهای وضعیت و پیام‌های خطا (HTTP Status Codes)

کد وضعیت عنوان وضعیت توضیحات و علت رخداد
201 Created موفقیت‌آمیز درخواست با موفقیت ثبت شد و اطلاعات مسافرین و کد رهگیری ایجاد گردید.
400 Bad Request درخواست ناقص بدنه درخواست ارسال نشده یا فرمت JSON ارسالی نامعتبر است.
401 Unauthorized عدم احراز هویت توکن Bearer ارسال نشده، اشتباه است یا منقضی شده است.
403 Forbidden عدم دسترسی توکن غیرفعال شده است، IP ارسالی مجاز نیست یا مجوز سرویس را ندارد.
422 Unprocessable Entity خطای اعتبارسنجی فیلدها یک یا چند فیلد اجباری ارسال نشده یا فرمت نامعتبر دارند (لیست خطاها در کلید errors قرار دارد).

جهت برقراری اتصال امن به وب‌سرویس‌ها و تبادل داده‌ها با نرم‌افزارهای حسابداری، اتوماسیون‌ها یا اپلیکیشن‌های اختصاصی، نیاز به یک Bearer Token معتبر دارید.

کلیدهای API برای هر کلاینت به صورت مستقل و با محدودیت‌های امنیتی (آی‌پی مجاز و سقف تعداد درخواست در دقیقه) تعریف می‌گردند.

مراحل دریافت کلید دسترسی:

پشتیبانی و هماهنگی فنی
051-32037
ارتباط مستقیم
09151013656