サーバーAPI | Noxyrドキュメント

APIで取得できる内容

このAPIは読み取り専用で、1つのサーバーに限定されます。ログインせずにダッシュボードの数値を使いたいステータスページ、スプレッドシート、社内ツール向けです。設定の変更、チケットのクローズ、請求書の作成はできません。

すべてのエンドポイントは https://noxyrbot.com/api/v1 の下にあり、JSONを返します。キーがサーバーを特定するため、どのエンドポイントもサーバーIDを指定しません。

GET /api/v1/: このキーで有効になっているスコープと、そのキーがアクセスできるエンドポイント。
GET /api/v1/server: 名前、アイコン、メンバー数、オンライン数、ブースト数、作成日。
GET /api/v1/tickets: 合計、未対応と対応済みの数、過去7日と30日の件数、平均評価。
GET /api/v1/activity?days=30: 1日ごとのメッセージ数、参加数、退出数。最大90日分。
GET /api/v1/invoices: 請求書の件数、通貨ごとの売上、支払い状況。invoice links スコープがオンの場合、?limit= を付けると、ダウンロード可能な画像URL付きの最近の請求書も含まれます。
GET /api/v1/reviews: 平均評価、星ごとの内訳、最新の公開レビュー5件。
GET /api/v1/giveaways: 開催中と終了済みの件数、合計参加数、現在のプレゼント。

キーの作成

サーバーごとにキーは1つです。キーはサーバーのAPIページで生成され、一度だけ表示されます。保存されるのはハッシュだけです。紛失した場合は再生成する必要があり、古いキーは無効になります。

ダッシュボードでサーバーを開き、API に進みます。
Generate を押し、nxr_ で始まるキーをコピーしてください。再表示されません。
必要のないスコープはオフにしてください。Invoice links は顧客の請求書画像を公開してしまうため、初期状態ではオフです。
任意: Set up channel を押すと、エンドポイント一覧を載せたAPI用のカテゴリとチャンネルをボットがサーバーに作成します。

このページには、キーが最後に使われた日時と、送信されたリクエスト数も表示されます。キーが漏えいしたかどうかを素早く確認するには、ここが最適です。トグルで無効にできます。完全に削除したい場合は取り消してください。

スコープ

スコープはフィールドではなくエンドポイントを制限します。スコープがオフのエンドポイントへのリクエストは、スコープ名を示すメッセージとともに403が返されます。

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: 画像リンク付きの最近の請求書一覧を追加します。初期状態ではオフです。
reviews: /reviews
giveaways: /giveaways

認証と送信例

キーは Authorization ヘッダーに Bearer トークンとして送信します。ブラウザからの呼び出しは許可されています(CORSは開放されています)が、フロントエンドのコードに入れたキーは公開されたキーになるため、API呼び出しは自分で管理するサーバーから行ってください。

curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
レスポンス: {"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}

レート制限

各キーは1分あたり60リクエストまで送信できます。上限は、すべてのレスポンスに含まれる標準の RateLimit ヘッダーで返されます。上限を超えると、HTTP 429と「rate_limited」のエラーが返されます。データが変わる速度より速くポーリングしないでください。チケットや売上の合計は1分に1回読み取れば十分です。

エラー

すべてのエラーは、機械が読める形式のエラーコードと人間向けのメッセージを含むJSONです。

401 認証エラー: Authorization ヘッダーがない、Bearerトークンではない、またはキーが存在しない場合です。
403 key_disabled: ダッシュボードでキーがオフにされています。
403 scope_disabled: このキーでそのスコープがオフになっています。
404 not_found: 存在しないエンドポイントです。メッセージに有効なエンドポイントが一覧表示されます。
404 guild_unavailable: ボットがそのサーバーにもういません。
429 rate_limited: 1分間に60リクエストを超えています。
500 internal_error: Noxyr側で問題が発生しました。後でもう一度お試しください。