ISP 프록시 API

패널의 ISP Proxies 플랜 페이지에서 할 수 있는 모든 작업은 이 API를 통해서도 가능합니다: IP를 배치할 수 있는 위치를 검색하고, 모든 프록시를 사용자 이름과 함께 나열하고, 아직 배치하지 않은 IP를 배치하고, IP를 다른 도시나 ISP로 이동할 수 있습니다.

인증

모든 엔드포인트는 api_token 쿼리 매개변수로 인증합니다. 패널의 Account → API Tokens에서 토큰을 생성하세요.

?api_token=YOUR_API_TOKEN

모든 경로는 https://shifter.io/api/v1/isp/{membership}으로 시작합니다. {membership} 경로 매개변수는 플랜 식별자의 두 형식 중 하나를 받습니다: 플랜의 패널 URL 끝에 있는 짧은 코드(예: Rxqk) 또는 플랜 페이지에 표시된 플랜 번호(예: 68057)입니다. 둘 다 동일한 플랜으로 연결됩니다.

이 API는 토큰 소유자에게 속한 ISP Proxies 플랜에만 접근합니다. 다른 플랜은 404를 반환합니다.

위치 변경 규칙

각 IP는 청구 기간당 5회 위치를 변경할 수 있습니다. 이 횟수는 플랜이 갱신될 때 초기화되며, 사용하지 않은 변경 횟수는 다음 기간으로 이월되지 않습니다. 이는 체험판에도 적용됩니다.
이동된 IP는 새 사용자 이름과 새 proxy_id를 받습니다. 기존 사용자 이름은 즉시 작동을 멈추므로, 즉시 클라이언트를 새 사용자 이름으로 전환해야 합니다.
플랜 비밀번호는 동일하게 유지됩니다. 플랜당 하나의 비밀번호가 있으며, 해당 플랜의 모든 사용자 이름이 이를 공유합니다.
사용자 이름은 대소문자를 구분합니다. 모든 프록시는 isp.shifter.io:443을 통해 HTTP(S) 또는 SOCKS5로 연결됩니다.
각 IP는 선택한 도시와 ISP를 유지합니다. 그 뒤에 있는 주소는 가정용 연결이 ISP로부터 새 주소를 받는 것과 같은 방식으로 때때로 갱신될 수 있습니다.

위치 목록 조회

GET https://shifter.io/api/v1/isp/{membership}/locations

IP를 배치할 수 있는 도시와 ISP 조합을, 각 조합에 현재 몇 개의 IP가 사용 가능한지와 함께 반환합니다. 사용 가능한 것이 없는 위치는 요청하지 않는 한 제외됩니다.

매개변수	위치	필수	설명
`membership`	path	예	플랜 ID(짧은 코드 또는 플랜 번호)
`api_token`	query	예	계정 API 토큰
`country`	query	아니요	ISO 3166-1 alpha-2 국가 코드, 예: `US`
`q`	query	아니요	검색어: 도시(현지 명칭도 가능), 지역, ISP 이름, 또는 `7922`나 `AS7922` 같은 ASN
`page`	query	아니요	페이지 번호, `1`부터 시작
`per_page`	query	아니요	페이지당 결과 수, 기본값 `100`, 최대 `500`
`include_sold_out`	query	아니요	`1`로 설정하면 사용 가능한 IP가 없는 위치도 포함

예시:

curl "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/locations?country=US&q=Dallas&api_token=YOUR_API_TOKEN"

응답:

{
  "ok": true,
  "page": 1,
  "per_page": 100,
  "total": 2,
  "has_more": false,
  "locations": [
    {
      "location_id": 1842,
      "country": "US",
      "region": "Texas",
      "city": "Dallas",
      "asn": 7922,
      "isp": "COMCAST-7922",
      "available": 7
    }
  ]
}

location_id는 고정값이므로 저장해두었다가 나중에 재사용할 수 있습니다. available은 현재 해당 위치에 배치할 수 있는 IP 개수입니다. 다음 페이지를 요청할 시점을 알기 위해 has_more를 사용하세요.

프록시 목록 조회

GET https://shifter.io/api/v1/isp/{membership}/proxies

플랜의 연결 정보와 배치된 모든 IP의 사용자 이름, 위치, 남은 위치 변경 횟수를 반환합니다.

매개변수	위치	필수	설명
`membership`	path	예	플랜 ID(짧은 코드 또는 플랜 번호)
`api_token`	query	예	계정 API 토큰

예시:

curl "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/proxies?api_token=YOUR_API_TOKEN"

응답:

{
  "ok": true,
  "host": "isp.shifter.io",
  "port": 443,
  "password": "YOUR_PLAN_PASSWORD",
  "ips_total": 10,
  "ips_placed": 3,
  "ips_unplaced": 7,
  "changes_per_ip": 5,
  "period_ends_at": "2026-10-20T08:00:00+00:00",
  "proxies": [
    {
      "proxy_id": 5531,
      "username": "us-texas-dallas-as7922-Ksj25",
      "location_id": 1842,
      "country": "US",
      "region": "Texas",
      "city": "Dallas",
      "asn": 7922,
      "isp": "COMCAST-7922",
      "changes_left": 5
    }
  ]
}

필드	설명
`host` / `port`	플랜의 모든 프록시가 연결되는 위치
`password`	플랜 비밀번호, 모든 사용자 이름이 공유
`ips_total`	플랜에 포함된 IP 수
`ips_placed` / `ips_unplaced`	이미 위치에 배치된 IP 수와 아직 배치할 수 있는 IP 수
`changes_per_ip`	청구 기간당 각 IP가 받는 위치 변경 횟수
`period_ends_at`	현재 청구 기간이 종료되고 변경 횟수가 초기화되는 시점
`proxies[].username`	연결에 사용할 사용자 이름. 대소문자 구분
`proxies[].isp`	ASN에 대한 ISP 이름. 알려진 이름이 없으면 `null`일 수 있음
`proxies[].changes_left`	현재 기간에 이 IP에 남아 있는 위치 변경 횟수

연결하려면 다음 필드를 조합해 프록시 URL을 만드세요:

http://us-texas-dallas-as7922-Ksj25:YOUR_PLAN_PASSWORD@isp.shifter.io:443
socks5://us-texas-dallas-as7922-Ksj25:YOUR_PLAN_PASSWORD@isp.shifter.io:443

단일 IP 이동

POST https://shifter.io/api/v1/isp/{membership}/proxies/{proxy_id}/location

하나의 IP를 다른 위치로 이동합니다. 이는 해당 IP의 위치 변경 횟수 중 1회를 사용합니다.

매개변수	위치	필수	설명
`membership`	path	예	플랜 ID(짧은 코드 또는 플랜 번호)
`proxy_id`	path	예	이동할 IP의 `proxy_id`
`api_token`	query	예	계정 API 토큰
`location_id`	body	예	IP를 이동할 위치

예시:

curl -X POST "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/proxies/5531/location?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"location_id":1901}'

응답:

{
  "ok": true,
  "message": "Location changed. Use the new username from now on.",
  "old_proxy_id": 5531,
  "proxy": {
    "proxy_id": 5534,
    "username": "us-texas-austin-as7018-Pq7rT",
    "location_id": 1901,
    "country": "US",
    "region": "Texas",
    "city": "Austin",
    "asn": 7018,
    "isp": "ATT-INTERNET4",
    "changes_left": 4
  }
}

이제 IP는 새 proxy_id와 새 username을 갖습니다. 기존 사용자 이름(및 old_proxy_id)은 응답이 도착하는 즉시 작동을 멈춥니다.

여러 IP 이동

POST https://shifter.io/api/v1/isp/{membership}/proxies/location

한 번의 요청으로 여러 IP를 각각 지정한 위치로 이동합니다.

매개변수	위치	필수	설명
`membership`	path	예	플랜 ID(짧은 코드 또는 플랜 번호)
`api_token`	query	예	계정 API 토큰
`moves`	body	예	`{"proxy_id", "location_id"}` 쌍의 배열, 요청당 최대 1,000개
`dry_run`	body	아니요	`true`로 설정하면 아무것도 변경하지 않고 요청을 확인. 기본값 `false`

요청은 전부 아니면 전무입니다: 하나라도 이동할 수 없으면 어떤 IP도 이동하지 않고 오류가 반환됩니다.
IP가 이미 대상 위치에 있는 항목은 건너뛰며 변경 횟수를 사용하지 않습니다. 해당 proxy_id는 skipped에 나열됩니다.
dry_run: true인 경우 아무것도 저장되지 않습니다. 응답은 실제로 일어날 일을 보여주며, moved의 proxy_id와 username은 null로 설정됩니다. 새 값은 이동이 실제로 이루어져야만 존재하기 때문입니다.

예시:

curl -X POST "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/proxies/location?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"moves":[{"proxy_id":5531,"location_id":1901},{"proxy_id":5532,"location_id":1842}],"dry_run":false}'

응답:

{
  "ok": true,
  "dry_run": false,
  "message": "1 IP moved. Use the new username from now on. 1 IP was already there and stays as it is.",
  "moved": [
    {
      "old_proxy_id": 5531,
      "proxy_id": 5535,
      "username": "us-texas-austin-as7018-Zt3wQ",
      "location_id": 1901,
      "country": "US",
      "region": "Texas",
      "city": "Austin",
      "asn": 7018,
      "isp": "ATT-INTERNET4",
      "changes_left": 4
    }
  ],
  "skipped": [5532]
}

미배치 IP 배치

POST https://shifter.io/api/v1/isp/{membership}/proxies/place

아직 위치에 배치되지 않은 IP(프록시 목록의 ips_unplaced)를 배치합니다. IP를 배치하는 것은 위치 변경 횟수를 사용하지 않습니다.

매개변수	위치	필수	설명
`membership`	path	예	플랜 ID(짧은 코드 또는 플랜 번호)
`api_token`	query	예	계정 API 토큰
`placements`	body	예	`{"location_id", "count"}` 쌍의 배열: 각 위치에 배치할 IP 수

예시:

curl -X POST "https://shifter.io/api/v1/isp/YOUR_PLAN_ID/proxies/place?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"placements":[{"location_id":1901,"count":2}]}'

응답:

{
  "ok": true,
  "message": "2 IPs are ready.",
  "placed": 2,
  "ips_unplaced": 5,
  "proxies": [
    {
      "proxy_id": 5540,
      "username": "us-texas-austin-as7018-Hh8aa",
      "location_id": 1901,
      "country": "US",
      "region": "Texas",
      "city": "Austin",
      "asn": 7018,
      "isp": "ATT-INTERNET4",
      "changes_left": 5
    }
  ]
}

전체 흐름 예시

Austin의 위치를 찾고, IP 두 개를 그곳으로 이동한 다음, 이후 사용할 사용자 이름을 다시 읽어옵니다. 이 예시는 JSON을 읽기 위해 jq를 사용합니다.

TOKEN="YOUR_API_TOKEN"
PLAN="YOUR_PLAN_ID"
BASE="https://shifter.io/api/v1/isp/$PLAN"

# 1. Find a location with IPs available
LOCATION=$(curl -s "$BASE/locations?country=US&q=Austin&api_token=$TOKEN" \
  | jq '.locations[0].location_id')

# 2. Move two IPs there
curl -s -X POST "$BASE/proxies/location?api_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"moves\":[{\"proxy_id\":5531,\"location_id\":$LOCATION},{\"proxy_id\":5532,\"location_id\":$LOCATION}]}" \
  | jq -r '.moved[].username'

# 3. Read every current username and build proxy URLs
curl -s "$BASE/proxies?api_token=$TOKEN" \
  | jq -r '.password as $p | .proxies[] | "http://\(.username):\($p)@isp.shifter.io:443"'

2단계 또는 3단계에서 얻은 새 사용자 이름으로 클라이언트를 즉시 업데이트하세요: 기존 사용자 이름은 이동이 완료되는 즉시 작동을 멈춥니다.

오류

요청이 실패하면 "ok": false와 함께 기계가 읽을 수 있는 error 코드와 읽기 쉬운 message가 반환됩니다:

{
  "ok": false,
  "error": "plan_inactive",
  "message": "This plan is not active, so locations cannot be assigned."
}

상태	`error`	의미
`404`	`not_found`	플랜 또는 IP가 계정에 존재하지 않음. `proxy_ids`가 포함될 수 있음
`422`	`validation`	매개변수가 누락되었거나 유효하지 않음
`422`	`no_changes_left`	하나 이상의 IP가 이번 기간의 위치 변경 횟수를 모두 사용함. `proxy_ids` 포함
`409`	`out_of_stock`	해당 위치에 사용 가능한 IP가 충분하지 않음. `location_id`와 `available` 포함
`409`	`plan_inactive`	플랜이 활성 상태가 아니므로 해당 플랜의 IP를 배치하거나 이동할 수 없음

속도 제한

요청	제한
읽기(`GET`)	계정당 분당 60회
쓰기(`POST`)	계정당 분당 20회

제한을 초과하면 API는 429를 반환합니다. 대기 후 백오프와 함께 재시도하세요. 여러 IP를 이동하려면 IP당 하나씩 요청을 보내는 대신 여러 IP 이동 요청 하나로 보내세요.

참고 자료

ISP Proxies 개요
IP 관리, 패널에서 수행하는 동일한 작업
사용량 및 쿼터 API