LocalSERP Proxy APIドキュメント

認証

公開カタログを除くすべてのリクエストにAPIキーが必要です：Authorization: Bearer API_KEY。キーが全文表示されるのは作成時の1回のみです。パスワードと同様に保管してください。キーはいつでも無効化できます。無効化後、そのキーを使ったリクエストは401 unauthorizedを返します。

curl -s "https://localserpproxy.com/api/v1/balance" \
  -H "Authorization: Bearer $API_KEY"

リクエストとレスポンス

• JSONを送信し、JSONを受信: 本文付きでContent-Type: application/jsonを送信します。
• 件数が増えるリストはpage（1から）とperPage（1～100、デフォルトは20）でページ分割され、{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }を返します。短いリストは{ "data": [...] }を返します。
• IDはタイププレフィックス付きの不透明な文字列です: ord_（注文）、top_（チャージ）、txn_（残高の移動）、res_（トラフィックサブスクリプション）、mob_（モバイルポート）、key_（APIキー）、ipw_（IP許可リストのエントリー）。
• 安全な再試行: POST /v1/ordersとPOST /v1/topupsはIdempotency-Keyヘッダーを受け付けます（任意の一意な文字列。24時間保持）。同じキーで再送すると、二重購入や二重チャージを防ぎ、最初のレスポンスを返します。
• 例は各レスポンスの形式を示しています。例に含まれるID、IP、金額、日付は説明用です。プランIDと価格は実際のものです。

エラー

すべてのエラーで同じ本文が返されます。codeは安定しており、コードでの処理を想定しています。messageは変更される場合がある英語の文です。バリデーションエラーでは、無効なフィールドがfieldsに列挙されます。新しいコードが追加される場合があります。不明なコードは一般的なエラーとして処理してください。

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": [
      {
        "field": "amountUsd",
        "code": "too_small",
        "message": "The minimum top-up is 25.00 USD."
      }
    ],
    "requestId": "req_2b7c0f"
  }
}

レート制限

すべてのレスポンスにはRateLimit-Limit、RateLimit-Remaining、RateLimit-Resetが含まれます。上限を超えると、APIはRetry-Afterヘッダー（秒数）とともに429 rate_limitedを返します。指定された秒数だけ待ってから再試行してください。モバイルポートのIPは、30秒に1回まで変更できます（429 rotation_too_soon、Retry-Afterを使用）。