LocalSERP Proxy API 문서

인증

공개 카탈로그를 제외한 모든 요청에는 API 키가 필요합니다: Authorization: Bearer API_KEY. 키는 생성할 때 한 번만 전체가 표시되므로 비밀번호처럼 보관하세요. 언제든 키를 폐기할 수 있으며, 폐기한 키로 요청하면 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초에 한 번만 변경할 수 있습니다(429 rotation_too_soon, Retry-After 포함).