メインコンテンツへ移動
AIチュートリアル

Zad Top HTTP APIでリセラー向けワークフローを構築する

Zad Top HTTP APIへの接続方法、リクエストの認証、プレイヤー向けコードの引き換え、使用前のカード確認、プレイヤー詳細の照会、文書化されたエンドポイントを使ったリセラー在庫の管理について説明します。

約13分で読了
Zad Top HTTP APIでリセラー向けワークフローを構築

Zad Topは、再販業者、ショップ、パネル、カスタムボット向けの独立したTelegramボットおよびHTTP APIです。Free Fire、PUBG Mobile、Yalla Ludo、Jawaker、iTunes、Razer Gold向けに、コード引き換え、カードチェック、プレイヤー検索、在庫引き換え、注文スクリーンショット取得などのサービスを提供します。

このリポジトリは、ボットのソースコードではなく、公開開発者ハブです。ライブAPIドキュメントはapi.zadtop.com/docsで確認でき、対話型のSwaggerインターフェースとOpenAPIドキュメントも利用できます。

Zad Top — Telegram引き換えボットとHTTP API

構築できるもの

Zad Topを使うと、プレイヤーIDにデジタルコードを送信し、引き換え前に対応カードを確認し、ゲーム内のプレイヤー名と地域を取得し、保存済みの在庫から商品を引き換える再販ワークフローを作成できます。引き換え成功後にショップ注文画像をリクエストすることもできます。

  • Free Fire、PUBG Mobile UC、Yalla Ludo DiamondsとGold、Jawakerトークンを引き換える。
  • 対応するFree Fire、PUBG、Yalla Ludo Diamonds、iTunes、Razer Goldカードを確認する。
  • Razer Gold PINを自分のウォレットにチャージする。
  • コードを使用する前に、プレイヤーのゲーム内名と地域を検索する。
  • ボットにコードを保存し、個別のコードを送信する代わりに在庫パックを引き換える。
  • ショップワークフロー用の注文スクリーンショットを取得する。
ゲームとカード

アクセスと認証を準備する

HTTP APIを使用するには、Telegramで@ZadTopBotを開き、Subscription、続いてHTTP APIを選択します。有効なプランとHTTP APIアドオンが必要です。READMEには、アドオン料金として30日間15 USDTと記載されています。別のCode checkingサブスクリプションでは、チェック用ルートのみを呼び出せます。

APIキーを取得したら、認証が必要なすべてのリクエストでX-API-Keyヘッダーに設定します。

X-API-Key: pk_YOUR_KEY

GitHubでZad Topにスターを付ける

新しいキーを作成すると以前のキーは無効になるため、認証情報をローテーションするたびにアプリケーション設定を更新してください。キーはサーバー上で管理し、ブラウザ側のコードや公開リポジトリに公開しないでください。

最初の即時引き換えを実行する

POST /v1/jobs/instant-redeemルートは、1つ以上のコードをプレイヤーIDに対して引き換えます。リクエストにはJSON、APIキー、Content-Typeヘッダーが必要です。

curl -sS -X POST https://api.zadtop.com/v1/jobs/instant-redeem \
  -H "X-API-Key: pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"2186053213","codes":["4233939008625064"],"game":"freefire"}'

この例のgame値はfreefireです。その他の対応値には、pubg、ludo、ludogold、jawaker、razer_rechargeのほか、APIドキュメントに記載されている各サービス固有の値があります。

引き換えリクエストはジョブとして処理されます。ジョブがdoneになると処理は完了していますが、送信した各コードには個別のsuccess結果があり、該当する場合はerr_codeも返されます。ジョブの完了だけを根拠に、すべてのコードが成功したと判断しないでください。

即時引き換え

ジョブと結果を追跡する

GET /v1/jobs/{id}を使用して、ジョブの状態と結果を取得します。?wait=25を追加すると、すぐにポーリングせず、指定した期間まで待機できます。

curl -sS "https://api.zadtop.com/v1/jobs/JOB_ID?wait=25" \
  -H "X-API-Key: pk_YOUR_KEY"

Zad Top — Telegram引き換えボットとHTTP API

実用的な連携では、ジョブIDを保存してジョブ結果を取得し、その後、コード単位のすべての結果を確認します。成功したコードと失敗したコードは、顧客または再販業者ダッシュボードに分けて表示してください。

引き換え前にコードを確認する

POST /v1/codes/checkルートでは、引き換えずに最大20枚のカードを確認できます。大規模なバッチには、最大10,000枚のカードをジョブとして処理できるPOST /v1/jobs/code-checkを使用します。

使用する前にコードを確認

結果はゲームによって異なります。Free Fireでは未使用、使用済み、無効の状態を確認でき、パックが含まれる場合もあります。PUBGでは未使用、使用済み、期限切れ、無効の状態を確認でき、ショップが把握している場合は価値も含まれます。Yalla Ludo Diamondsは確認できますが、Goldにはチェック用ルートがありません。Diamondsチェッカーに送信したGoldコードは使用される可能性があるため、送信前に商品タイプを確認してください。

iTunesのチェックではドル残高が返されます。一定期間リクエストがなかった後の最初の読み取りには、最大1分かかる場合があります。Razer Goldのチェックでは、PINを使用せずに有効、使用済み、無効の状態が返されますが、READMEではPINごとに5回までという制限が指定されています。

先にプレイヤーを検索する

引き換え前にGET /v1/player/lookupを呼び出して、ゲーム内の名前と地域を取得します。これにより、有効なコードを誤ったプレイヤーIDに送信するのを防げます。

curl -sS "https://api.zadtop.com/v1/player/lookup?player_id=2186053213&game=freefire" \
  -H "X-API-Key: pk_YOUR_KEY"

返されたプレイヤー情報を、ユーザーインターフェースでの確認手順として使用します。READMEには、選択したプレイヤーIDについて利用者が責任を負うこと、また有効なコードはショップへの最初の正常な連絡で送信されたアカウントに付与されることが記載されています。

即時利用

在庫利用を使う

Zad Topで在庫を管理している場合は、注文ごとにコードを貼り付ける代わりに、POST /v1/jobs/stock-redeemを使用して保管済みの在庫から利用します。GET /v1/stock/summaryルートでは、ゲームおよびパックごとの在庫が報告されます。

curl -sS https://api.zadtop.com/v1/stock/summary \
  -H "X-API-Key: pk_YOUR_KEY"

正確な在庫利用フィールドとパック識別子は、最新のリファレンスまたはリポジトリのエンドポイントガイドから確認してください。これにより、利用可能な在庫カテゴリについての前提をハードコードせずに済みます。

ゲーム別の注意事項

  • Free Fire: 利用と確認に対応しています。
  • PUBG Mobile: UCの利用と確認に対応しています。
  • Yalla Ludo: 状況に応じてludoまたはludogoldを使用します。利用にはtierが必要です。ダイヤモンドは確認できますが、Goldは確認できません。
  • Jawaker: 利用に対応していますが、12文字のPIN単独の確認機能はありません。
  • iTunes: 残高確認は一覧に記載されたサービス経由でのみ対応しています。非アクティブ状態の後の最初のリクエストには、最大1分かかる場合があります。
  • Razer Gold: PINを使用せずに確認できます。razer_recharge操作ではPINをウォレットに付与しますが、メールアドレスとパスワードが必要です。パスワードは保存されません。

アカウントおよびショップ操作を追加する

APIには、アカウントおよびリセラー向けのルートも用意されています。

  • アカウント情報にはGET /v1/me。
  • 利用枠情報にはGET /v1/quota。
  • 操作履歴にはGET /v1/history。
  • 保存済みプレイヤーにはGET /v1/players。
  • 利用成功後のショップ注文画像にはPOST /v1/order/screenshot。

使用前にコードを確認

これらのルートは管理ダッシュボードを支援でき、ジョブおよび検索ルートは顧客向けの注文フローに利用できます。

制限と利用コストを理解する

READMEによると、利用にはコード1件につき1リクエスト、確認にはカード1枚につき1リクエスト、Razer Goldの確認にはPIN 1件につき5リクエストが必要です。プレイヤー検索には0.25リクエストかかります。ショップによる拒否や、結果が返る前の失敗も、文書化された利用ルールに従ってカウントされます。

1日の制限はUTCの午前0時にリセットされ、プラン内のゲーム、Telegramボット、APIで共有されます。新規アカウントには10回分の無料利用枠があります。プランの価格と提供状況は変更される可能性があるため、請求フローを構築する前に、ボットまたは公式サイトで最新の条件を確認してください。

推奨される連携フロー

  1. プレイヤーのゲーム、プレイヤーID、商品、コードを収集します。
  2. プレイヤー検索エンドポイントを呼び出し、返された名前と地域を確認用に表示します。
  3. 対応商品では、利用前にコードを確認します。
  4. 即時利用または在庫利用のジョブを送信します。
  5. /v1/jobs/{id}をポーリングするか、waitパラメータを使用します。
  6. ジョブ全体の状態と、各コードのsuccessおよびerr_codeフィールドを確認します。
  7. 顧客に明確な結果を表示し、必要に応じて注文スクリーンショットをリクエストします。

高度な実装のヒント

認証情報を保護する

APIキーは、サーバー側の環境変数またはシークレット管理ツールに保存します。モバイルアプリ、フロントエンドJavaScript、ログ、サポート用スクリーンショットに配置しないでください。

ゲームとカード

非同期処理に対応する

利用および一括確認の操作はジョブとして処理されます。ジョブ識別子を永続化し、安全なステータス読み取りの再試行に対応するとともに、通信エラーとコードレベルの失敗を区別します。done状態のジョブでも、個々の結果を確認する必要があります。

商品とゲームの組み合わせを検証する

アプリケーション内で明示的な商品マッピングを使用し、Diamonds、Gold、UCなどの商品が誤って別のルートやチェッカーに送信されないようにします。これはYalla Ludoで特に重要です。Goldには確認機能がなく、不適切な確認リクエストによって使用される可能性があるためです。

レイテンシと利用枠を考慮する

iTunesの残高読み取りや一括ジョブには、余裕を持った時間を設定します。特にRazerの確認では、PIN 1件で5リクエストを消費するため、利用枠をローカルで追跡してください。また、ボットとAPIの活動で共有される1日の利用枠も考慮します。

まとめ

Zad Topは、デジタルゲームおよびギフトカードのリセラー業務に特化したAPIを提供します。まずAPIアクセスとX-API-Keyヘッダーを設定し、プレイヤーIDを確認し、対応している場合はチェックを実行して、利用ジョブを送信します。その後、各コードレベルの結果を必ず評価してください。エンドポイントの詳細と現在のサービス動作については、HTML APIリファレンス、Swaggerドキュメント、およびプロジェクトのGitHubリポジトリを参照してください。

Zad Topは独立したサービスであり、Garena、Krafton、Tencent、Yalla Games、Apple、Razer、Jawakerとは提携していません。