API همراتیک

یکپارچه سازی آسان با سیستم صدور بلیط امن و قابل استعلام

معرفی

API همراتیک به سایت های فروش بلیط و پلتفرم های مدیریت رویداد اجازه می دهد تا به صورت مستقیم با سامانه همراتیک ارتباط برقرار کرده و قابلیت های امنیتی منحصر به فرد ما را در فرآیند صدور، استعلام و انتقال بلیط ادغام کنند. با استفاده از این API، می توانید بلیط های رویدادهای خود را با QR کدهای پویا و متصل به هویت کاربر صادر کرده و اطمینان حاصل کنید که هر بلیط فقط توسط مالک اصلی قابل استفاده یا انتقال است.

مزایای استفاده از API

• کاهش چشمگیر کلاهبرداری: QR کدهای پویا و اتصال به شماره موبایل کاربر، جعل و فروش چندباره بلیط را تقریباً غیرممکن می کند.
• اعتماد مشتریان: ارائه بلیط های امن و قابل استعلام باعث افزایش اعتماد خریداران به پلتفرم شما می شود.
• مدیریت آسان انتقال: امکان انتقال امن و ردیابی شده بلیط ها از طریق API، فرآیند خدمات پس از فروش را تسهیل می کند.
• یکپارچگی ساده: مستندات کامل و SDK های آماده برای یکپارچگی سریع و بدون دردسر.

نمودار جریان کار API (مثال: صدور بلیط)

نمودار شماتیک جریان کار API صدور بلیط

احراز هویت

برای استفاده از اندپوینت های API همراتیک، نیاز به احراز هویت دارید. ما از روش احراز هویت مبتنی بر توکن (Bearer Token) استفاده می کنیم. شما یک کلید API (API Key) دریافت می کنید که باید آن را در سربرگ Authorization هر درخواست ارسال کنید.

دریافت کلید API

برای دریافت کلید API خود، باید در پنل همراتیک ثبت نام کرده و درخواست کلید API را ارسال کنید. کلید API به صورت یک رشته منحصر به فرد برای شما صادر خواهد شد.

استفاده از توکن در درخواست ها

کلید API شما در واقع همان توکن دسترسی شماست. این توکن باید در سربرگ Authorization با پیشوند Bearer ارسال شود:

Authorization: Bearer YOUR_DEMO_API_KEY

نمونه کد احراز هویت

fetch('https://api.ticketsafe.ir/v1/some-endpoint', {
  method: 'GET', // or POST, etc.
  headers: {
    'Authorization': 'Bearer YOUR_DEMO_API_KEY',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

<?php
$apiKey = 'YOUR_DEMO_API_KEY';
$url = 'https://api.ticketsafe.ir/v1/some-endpoint';

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);
?>

import requests

api_key = 'YOUR_DEMO_API_KEY'
url = 'https://api.ticketsafe.ir/v1/some-endpoint'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)
data = response.json()

print(data)

صدور بلیط

این اندپوینت برای صدور بلیط امن جدید در سامانه همراتیک استفاده می شود. پس از ارسال موفقیت آمیز درخواست، سامانه همراتیک یک بلیط امن با QR کد پویا و متصل به شماره موبایل خریدار صادر کرده و اطلاعات آن را در پاسخ برمی گرداند.

POST /v1/tickets/issue

پارامترهای ورودی (Request Body - JSON)

پاسخ موفقیت آمیز (Response - 201 Created)

{
  "status": "success",
  "message": "Ticket issued successfully",
  "data": {
    "ticket_id": "TKS-1404-ABCDEF-1234",
    "event_name": "کنسرت محسن یگانه",
    "buyer_mobile": "09123456789",
    "verification_url": "https://ticketsafe.ir/verify/TKS-1404-ABCDEF-1234",    "ticket_view_url": "https://ticketsafe.ir/view/TKS-1404-ABCDEF-1234",
    "issued_at": "2025-06-15T10:00:00Z"
  }
}

پاسخ خطا (مثال: 400 Bad Request)

{
  "status": "error",
  "message": "Invalid input parameters",
  "errors": [
    {
      "field": "buyer_mobile",
      "message": "Invalid mobile number format"
    },
     {
      "field": "event_date",      "message": "Event date is required"
    }
  ]
}

کنسول تعاملی (دمو)

{}

استعلام بلیط

این اندپوینت برای استعلام اصالت و وضعیت یک بلیط امن صادر شده استفاده می شود. با ارائه کد یکتای بلیط و شماره موبایل خریدار، می توانید از معتبر بودن و وضعیت استفاده آن مطلع شوید.

GET /v1/tickets/verify

پارامترهای ورودی (Query Parameters)

پاسخ موفقیت آمیز (Response - 200 OK)

{
  "status": "success",
  "message": "Ticket is valid",
  "data": {
    "ticket_id": "TKS-1404-ABCDEF-1234",
    "event_name": "کنسرت نمونه",
    "event_date": "2025-07-05",
    "event_time": "21:00",
    "event_location": "برج میلاد - تهران",
    "ticket_type": "VIP",    "seat_number": "A4",
    "buyer_mobile": "09123456789",
    "buyer_name": "کاربر تست",
    "status": "active", // possible values: 'active', 'used', 'transferred', 'cancelled', 'expired'
    "last_verified_at": "2025-06-15T10:30:00Z"
  }
}

پاسخ موفقیت آمیز (Response - 200 OK - بلیط نامعتبر)

{
  "status": "error",
  "message": "Ticket not found or invalid",
  "error_code": "TICKET_NOT_FOUND_OR_INVALID"
}

کنسول تعاملی (دمو)

{}

انتقال بلیط

این اندپوینت برای آغاز فرآیند انتقال مالکیت یک بلیط امن به شماره موبایل جدید استفاده می شود. این فرآیند معمولاً نیاز به تأیید از سمت مالک فعلی بلیط (مثلاً از طریق پنل کاربری یا کد تأیید) دارد.

POST /v1/tickets/transfer/initiate

آغاز فرآیند انتقال و ارسال کد تأیید به مالک فعلی یا گیرنده.

پارامترهای ورودی (Request Body - JSON)

پاسخ موفقیت آمیز (Response - 200 OK)

{
  "status": "success",
  "message": "Transfer initiation successful. Confirmation code sent.",
  "data": {
    "transfer_session_id": "TRN-SESS-XYZ123",
    "expires_at": "2025-06-15T10:05:00Z"
  }
}

POST /v1/tickets/transfer/confirm

تأیید نهایی فرآیند انتقال با ارائه کد تأیید.

پارامترهای ورودی (Request Body - JSON)

پاسخ موفقیت آمیز (Response - 200 OK)

{
  "status": "success",
  "message": "Ticket transferred successfully",
  "data": {
    "ticket_id": "TKS-1404-ABCDEF-1234",
    "old_owner_mobile": "09123456789",
    "new_owner_mobile": "09987654321",
    "transferred_at": "2025-06-15T10:04:30Z",
    "transfer_id": "TR-140403151004-987654"
  }
}

کنسول تعاملی (دمو)

{}

{}

گزارش گیری

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

GET /v1/reports/tickets

دریافت لیستی از بلیط های صادر شده بر اساس فیلترها.

پارامترهای ورودی (Query Parameters)

پاسخ موفقیت آمیز (Response - 200 OK)

{
  "status": "success",
  "message": "Tickets report generated",
  "data": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "tickets": [
      {
        "ticket_id": "TKS-1404-ABCDEF-1234",
        "event_name": "کنسرت نمونه",
        "buyer_mobile": "09123456789",
        "status": "active",
        "issued_at": "2025-06-15T10:00:00Z",
        "last_status_change": "2025-06-15T10:00:00Z"
      },
      {
        "ticket_id": "TKS-1404-GHIJKL-5678",
        "event_name": "تئاتر دمو",
        "buyer_mobile": "09987654321",
        "status": "used",
        "issued_at": "2025-06-14T15:30:00Z",
        "last_status_change": "2025-06-14T20:00:00Z"
      }
      // ... more tickets
    ]
  }
}

کنسول تعاملی (دمو)

{}

کدهای خطا

در صورت بروز خطا در پردازش درخواست های API، پاسخی با کد وضعیت HTTP مناسب (معمولاً ۴xx یا ۵xx) و یک بدنه JSON حاوی جزئیات خطا برگردانده می شود. بدنه خطا شامل فیلدهای status ("error")، message (توضیح کلی خطا) و در برخی موارد error_code (کد خطای مشخص) و errors (جزئیات خطاهای اعتبارسنجی ورودی) خواهد بود.

کدهای وضعیت HTTP

• 200 OK: درخواست با موفقیت انجام شد (معمولاً برای GET).
• 201 Created: منبع جدیدی با موفقیت ایجاد شد (معمولاً برای POST).
• 400 Bad Request: درخواست نامعتبر است (مثال: پارامترهای ورودی اشتباه).
• 401 Unauthorized: احراز هویت انجام نشده یا ناموفق است.
• 403 Forbidden: دسترسی به منبع مورد نظر مجاز نیست.
• 404 Not Found: منبع مورد نظر یافت نشد (مثال: بلیط با ticket_id مشخص وجود ندارد).
• 409 Conflict: درخواست با وضعیت فعلی منبع در تضاد است (مثال: تلاش برای انتقال بلیطی که قبلاً منتقل شده).
• 429 Too Many Requests: تعداد درخواست ها بیش از حد مجاز است (Rate Limiting).
• 500 Internal Server Error: خطایی در سرور رخ داده است.

کدهای خطای مشخص (Error Codes)

علاوه بر کدهای وضعیت HTTP، برخی خطاها دارای کد خطای مشخصی در بدنه پاسخ JSON هستند:

محدودیت ها

برای اطمینان از پایداری و عملکرد بهینه سیستم، محدودیت هایی بر روی استفاده از API اعمال می شود.

محدودیت نرخ درخواست (Rate Limiting)

تعداد درخواست هایی که می توانید در یک بازه زمانی مشخص ارسال کنید محدود شده است. این محدودیت بر اساس پلن اشتراک شما تعیین می شود. در صورت عبور از این محدودیت، پاسخ 429 Too Many Requests دریافت خواهید کرد.

جزئیات دقیق محدودیت ها در پنل کاربری شما قابل مشاهده است. توصیه می شود برای مدیریت درخواست ها از مکانیزم های Exponential Backoff استفاده کنید.

محدودیت حجم داده

حجم بدنه درخواست های POST و پاسخ های API ممکن است محدودیت داشته باشد. لطفاً از ارسال داده های غیرضروری در درخواست ها خودداری کنید.

دانلود SDK و نمونه پروژه ها

برای تسریع در یکپارچگی، ما SDK های آماده برای زبان های برنامه نویسی محبوب و نمونه پروژه های کاربردی ارائه می دهیم.

SDK ها

SDK ها شامل کلاس ها و توابعی هستند که کار با API همراتیک را ساده تر می کنند.

نمونه پروژه ها

نمونه پروژه ها نحوه استفاده از SDK ها و پیاده سازی سناریوهای رایج را نشان می دهند.