راهنمای وب‌سرویس RailBot

1. در ربات «کلیدهای API» رو باز کن و یک کلید بساز.
2. برای دریافت پولی، طبق بخش شارژ کیف پول اعتبار اضافه کن.
3. کلید رو در هدر Authorization بفرست و فقط سمت سرور نگهش دار.

Authorization: Bearer $KEY
Accept: application/json

موجودی کیف پول

موجودی تتر، تعرفهٔ هر پاسخ موفق و مصرف کلیدی که فرستادی رو برمی‌گردونه. رایگانه.

{
  "data": {
    "balance": "10.00",
    "currency": "USDT",
    "request_price": "0.05",
    "token": {
      "used": 0,
      "quota": 100
    }
  }
}

فهرست اپ‌ها

هر صفحه تا ۲۵ اپ از حساب خودت با شناسهٔ RailBot، اسم و کد کشور برمی‌گردونه. رایگانه.

{
  "data": {
    "apps": [
      {"id": 17,
       "label": "My app",
       "country": "IR"}
    ],
    "page": 1,
    "has_more": false
  }
}

دریافت اطلاعات اپ

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

برای هر درخواست تازه، یک Idempotency-Key یکتا (۸ تا ۱۲۸ کاراکتر ASCII شامل حرف، عدد یا . _ : -) بفرست. اگر ارتباط قطع شد همون مقدار رو دوباره بفرست تا دوباره هزینه کم نشه.

در مثال، BASE آدرس RailBot و KEY کلید وب‌سرویس خودته.

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: read-17-0001' \
  "$BASE/api/v1/apps/17/credentials"

{
  "data": {
    "app_id": 17,
    "api_id": 12345,
    "api_hash":
    "0123456789abcdef0123456789abcdef",
    "charged": "0.05",
    "currency": "USDT",
    "balance_after": "9.95"
  }
}

پاسخ تکراری با هدر Idempotent-Replay: true مشخص می‌شه. موجودی داخل پاسخ، موجودی زمان ثبت همون تراکنشه.

شارژ کیف پول با بها

مبلغ رو با فیلد amount به‌صورت رشتهٔ اعشاری بفرست. پاسخ ۲۰۲ یعنی ساخت فاکتور در صفه. تکرار همان درخواست با همان Idempotency-Key همان فاکتور را برمی‌گردونه. اگر فاکتور از صف خارج شده باشه، پاسخ ۲۰۰ می‌گیری.

بازهٔ مبلغ شارژ 1.00–1000.00 USDT

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: topup-0001' \
  -H 'Content-Type: application/json' \
  -d '{"amount":"10.00"}' \
  "$BASE/api/v1/wallet/topups"

{
  "data": {
    "reference": "INVOICE_REFERENCE",
    "state": "creating",
    "amount": "10.00",
    "currency": "USDT",
    "payment_url": null,
    "credited_at": null
  }
}

با reference یا نشانی Location وضعیت رو بگیر. وقتی وضعیت pending شد، payment_url رو در مرورگر باز کن. بعد از تأیید بها، وضعیت completed و اعتبار کیف پول به‌روز می‌شه.

ساخت فاکتور و بررسی وضعیت رایگان‌اند. وضعیت‌های expired و cancelled یعنی برای پرداخت باید فاکتور جدید بسازی.

در نمونه‌های زیر، RAILBOT_URL نشانی پایه و RAILBOT_KEY کلید وب‌سرویس است. برای شروع می‌تونی موجودی را رایگان بگیری.

اگر خطی کامل دیده نمی‌شه، داخل کادر کد افقی بکش.

curl -fsS \
  -H "Authorization: Bearer $RAILBOT_KEY" \
  "$RAILBOT_URL/api/v1/wallet"

const env = process.env;
const base = env.RAILBOT_URL;
const key = env.RAILBOT_KEY;
const headers = {
  Authorization: `Bearer ${key}`,
};
const response = await fetch(
  `${base}/api/v1/wallet`,
  { headers },
);
const data = await response.json();
if (!response.ok) {
  throw new Error(data.error.code);
}
console.log(data.data.balance);

$base = getenv('RAILBOT_URL');
$key = getenv('RAILBOT_KEY');
$client = curl_init($base.'/api/v1/wallet');
curl_setopt_array($client, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer '.$key],
]);
$body = curl_exec($client);
if ($body === false) {
    throw new RuntimeException(curl_error($client));
}
$result = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
if (curl_getinfo($client, CURLINFO_HTTP_CODE) >= 400) {
    throw new RuntimeException($result['error']['code']);
}
echo $result['data']['balance'], PHP_EOL;

package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
    "os"
    "time"
)

func main() {
    base := os.Getenv("RAILBOT_URL")
    key := os.Getenv("RAILBOT_KEY")
    req, err := http.NewRequest("GET", base+"/api/v1/wallet", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("Authorization", "Bearer "+key)
    client := &http.Client{Timeout: 15 * time.Second}
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    body, err := io.ReadAll(resp.Body)
    if err != nil || resp.StatusCode >= 400 {
        log.Fatalf("HTTP %d: %s (%v)", resp.StatusCode, body, err)
    }
    fmt.Println(string(body))
}

کدهای خطا

برای مدیریت خطا از error.code استفاده کن. درخواست ناموفق از موجودی یا سقف کلید کم نمی‌کنه.