راهنمای API ارسال Gift با Token

معرفی API

ارسال سریع و آنی گیفت با استفاده از API های GemStar تنها با چند پارامتر ساده و توکن برای احراز هویت.

Endpoint

برای ارسال گیفت از endpoint زیر استفاده کنید:

متد و نوع ارسال

این API فقط با متد POST کار می‌کند. می‌توانید داده‌ها را به صورت application/json یا form-data ارسال کنید.

منطق پردازش درخواست

این endpoint درخواست را به ترتیب زیر پردازش می‌کند:

فیلدهای ورودی

نمونه درخواست با cURL

نمونه ارسال با JSON:

curl -X POST "https://api.gemstarbot.xyz/sendgift" \
  -H "Content-Type: application/json" \
  -d '{
    "token":"YOUR_TOKEN",
    "gift":5,
    "amount":1,
    "username":"target_username",
    "message":"سلام",
    "hide_name":true
  }'

نمونه ارسال فقط با فیلدهای ضروری:

curl -X POST "https://api.gemstarbot.xyz/sendgift" \
  -H "Content-Type: application/json" \
  -d '{
    "token":"YOUR_TOKEN",
    "gift":5,
    "username":"target_username"
  }'

نمونه با form-data:

curl -X POST "https://api.gemstarbot.xyz/sendgift" \
  -d "token=YOUR_TOKEN" \
  -d "gift=5" \
  -d "amount=1" \
  -d "username=target_username" \
  -d "message=سلام" \
  -d "hide_name=1"

نمونه درخواست با PHP

نمونه ارسال با cURL در PHP:

<?php
$url = "https://api.gemstarbot.xyz/sendgift";

$data = [
  "token" => "YOUR_TOKEN",
  "gift" => 5,
  "amount" => 1,
  "username" => "target_username",
  "message" => "سلام",
  "hide_name" => true
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Content-Type: application/json"
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $response;
?>

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

در صورت معتبر بودن token و موفق بودن ارسال، پاسخ به این شکل خواهد بود:

{
  "ok": true,
  "message": "ارسال گیفت با موفقیت انجام شد",
  "result": {
    "success_count": 1,
    "requested_amount": 1,
    "target": "target_username",
    "target_kind": "username",
    "factor_number": "YOUR_TOKEN"
  },
  "meta": {
    "gift_input_id": 5,
    "session_name": "ashkan"
  }
}

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

در صورت بروز خطا در API اصلی یا اعتبارسنجی، پاسخ می‌تواند به این شکل باشد:

{
  "ok": false,
  "message": "ارسال گیفت ناموفق بود",
  "http_code": 400,
  "errors": [
    "گیفت #1: USERNAME_INVALID"
  ],
  "api_response": {
    "ok": false,
    "success_count": 0,
    "requested_amount": 1,
    "target": "target_username",
    "target_kind": "username",
    "factor_number": "YOUR_TOKEN",
    "errors": [
      "گیفت #1: USERNAME_INVALID"
    ]
  },
  "meta": {
    "gift_input_id": 5,
    "session_name": "ashkan"
  }
}

فیلدهای خروجی

نمونه خطاها

در بعضی شرایط پاسخ خطا به این شکل خواهد بود:

توکن ارسال نشده:

{
  "ok": false,
  "message": "token الزامی است"
}

توکن در جدول safety پیدا نشد:

{
  "ok": false,
  "message" => "توکن معتبر نیست"
}

اطلاعات کاربر در دیتابیس دوم پیدا نشد:

{
  "ok": false,
  "message": "اطلاعات کاربر در دیتابیس دوم پیدا نشد"
}

خطا در ارتباط با API اصلی:

{
  "ok": false,
  "message": "خطا در ارتباط با API ارسال گیفت",
  "errors": [
    "Operation timed out"
  ]
}