# LocalSERP Proxy API 문서

> localserpproxy.com/api의 LocalSERP Proxy REST API: 잔액, 충전, 주문, 프록시 관련 API 키, 오류, 한도 및 엔드포인트.

- URL: https://localserpproxy.com/ko/docs/api/
- 마지막 업데이트: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

계정에서 하는 모든 작업을 스크립트로 처리할 수 있습니다. 잔액 확인, 암호화폐로 충전, 요금제 구매, 프록시 인증 정보 생성, 모바일 IP 변경까지 가능합니다. HTTPS를 통한 JSON, API 키 1개, curl, Python, Node.js 예제를 제공합니다.

## LocalSERP Proxy API는 어떻게 사용하나요?

**빠른 답변**

API 키를 헤더 `Authorization: Bearer API_KEY`에 넣어 `https://localserpproxy.com/api/v1`로 HTTPS 요청을 보내세요. 계정의 [개발자 페이지](https://localserpproxy.com/app/developer?lang=ko)에서 키를 만들거나 `POST /v1/api-keys`을 사용하고, 필요한 권한만 부여하세요. 요청과 응답은 JSON 형식이며, 오류는 항상 `{ "error": { "code", "message" } }`로 반환됩니다.

## 한눈에 보기

| 속성 | 값 |
| --- | --- |
| 기본 URL | `https://localserpproxy.com/api/v1` |
| 형식 | HTTPS를 통한 JSON, UTF-8 |
| 인증 | API 키: `Authorization: Bearer API_KEY` |
| API 키 권한 범위 | `read`, `proxies`, `billing` |
| 금액 | 소수점 이하 2자리의 문자열 형식 USD (`"29.00"`) |
| 암호화폐 금액 | 부동소수점 숫자가 아닌 십진 문자열 (`"0.00045210"`) |
| 트래픽 | 바이트 (1 GB = 1,000,000,000바이트) |
| 날짜 | UTC 기준 ISO 8601(`2026-10-05T14:03:11Z`) |
| 버전 | 모든 경로에 `/v1` 포함 |

## 인증

공개 카탈로그를 제외한 모든 요청에는 API 키가 필요합니다: `Authorization: Bearer API_KEY`. 키는 생성할 때 **한 번만** 전체가 표시되므로 비밀번호처럼 보관하세요. 언제든 키를 폐기할 수 있으며, 폐기한 키로 요청하면 `401 unauthorized`이 반환됩니다.

### 권한 범위

스크립트에 필요한 권한만 각 키에 부여하세요. 필요한 권한 범위가 없는 키를 사용하면 `403 forbidden`이 반환됩니다.

| 권한 범위 | 허용되는 작업 |
| --- | --- |
| `read` | 계정, 잔액, 서비스, 사용량 등 모든 정보 읽기. |
| `proxies` | 프록시 설정 및 인증 정보 변경(라벨, 자동 갱신, 새 비밀번호), 하위 사용자 관리, IP 허용 목록 관리, 모바일 포트 회전(회전 링크 포함). |
| `billing` | 주문 및 충전 생성, 잔액으로 결제. |

유일한 예외는 **모바일 회전 링크**입니다. 브라우저 북마크나 일반 `curl`에서 호출하도록 만들어졌습니다: `GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (`proxies` 범위의 키). [모바일 포트 및 IP 회전](https://localserpproxy.com/ko/docs/api/mobile/)을 참조하세요.

*잔액 확인*

```bash
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`에 각 잘못된 필드를 표시합니다. 새 코드가 추가될 수 있으므로 알 수 없는 코드는 일반 오류로 처리하세요.

*422 validation_failed*

```json
{
  "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"
  }
}
```

### 상태 코드

| 상태 | 의미 |
| --- | --- |
| `422` | `validation_failed`: 하나 이상의 입력란이 올바르지 않습니다. |
| `401` | `unauthorized`: 토큰이 없거나 올바르지 않거나 만료되었습니다. |
| `402` | `insufficient_balance`: 잔액이 주문 금액보다 부족합니다. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: API 키에 필요한 권한 범위가 없거나 계정이 정지되었습니다. |
| `404` | `not_found`: 리소스가 존재하지 않거나 다른 계정에 속해 있습니다. |
| `409` | `conflict`(또는 더 구체적인 코드): 현재 상태에서는 작업을 수행할 수 없습니다. |
| `429` | `rate_limited` 또는 `rotation_too_soon`. |

## 요청 제한

모든 응답에는 `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`가 포함됩니다. 제한을 초과하면 API는 `Retry-After` 헤더(초 단위)와 함께 `429 rate_limited`을 반환합니다. 표시된 시간만큼 기다린 후 다시 시도하세요. 모바일 포트의 IP는 30초에 한 번만 변경할 수 있습니다(`429 rotation_too_soon`, `Retry-After` 포함).

## API 레퍼런스

- **[계정 및 잔액](https://localserpproxy.com/ko/docs/api/account/)** — 계정 설정, 선불 USD 잔액 및 잔액의 모든 내역(충전, 구매, 환불)을 확인하세요.
- **[암호화폐 충전](https://localserpproxy.com/ko/docs/api/top-ups/)** — 암호화폐로 잔액을 충전하세요. 입금 주소와 정확한 금액을 확인하고, 해당 금액을 정확히 전송한 다음 결제 완료를 알리세요(거래 ID는 선택 사항). 이후 잔액에 충전 금액이 반영될 때까지 진행 상황을 확인하세요. 잔액은 모든 요금제 결제에 사용할 수 있습니다.
- **[주문](https://localserpproxy.com/ko/docs/api/orders/)** — 요금제와 가격을 확인하고, 잔액으로 요금제(신규 서비스, 트래픽 추가 또는 포트 연장)를 구매한 다음 이전 주문 내역을 확인하세요.
- **[레지덴셜 프록시 및 인증 정보](https://localserpproxy.com/ko/docs/api/residential/)** — 트래픽 구독(GB 단위 레지덴셜 프록시 및 로테이팅 4G/5G)을 관리하세요. 프록시 인증 정보, 자체 인증 정보와 트래픽 한도가 있는 하위 사용자, 일일 사용량, 프록시 사용자 이름으로 지정할 수 있는 위치를 관리할 수 있습니다.
- **[모바일 포트 및 IP 로테이션](https://localserpproxy.com/ko/docs/api/mobile/)** — 전용 4G/5G 포트: 지금 또는 예약한 시간에 IP를 변경하고, 로테이션 링크를 사용해 일일 트래픽을 확인하세요.
- **[API 키 및 IP 허용 목록](https://localserpproxy.com/ko/docs/api/api-keys/)** — 권한 범위가 제한된 API 키를 생성하고 폐기하세요. IP 허용 목록도 관리할 수 있습니다. 사용자 이름과 비밀번호 없이 프록시를 사용할 수 있도록 소스 IP를 최대 10개까지 허용하세요.

> **스크립트에서 결제하기** 요금제는 항상 선불 USD 잔액으로 결제합니다. POST /v1/topups로 암호화폐를 충전한 다음(최소 25.00 USD) POST /v1/orders로 구매하세요. 두 작업을 한 번의 호출로 처리할 수도 있습니다. 충전 요청에 purchase를 포함하면 충전이 잔액에 반영되는 즉시 요금제가 구매됩니다.

---

LocalSERP Proxy: LocalSERP Proxy는 도시별로 지역 검색 결과, 광고와 가격을 확인하는 미국 레지덴셜 프록시 서비스로, 암호화폐로 결제하며 신분증 업로드가 필요 없습니다.