API Tự động hóa

Mục lục

• 1. 전제 조건
• 2. 인증·키 체계
• 3. 서브 아이디 가족 공유
• 4. 서버 상태
• 5. Burst 모드 (engine 선택·random)
• 6. 응답 분기 (Chromium vs Firefox)
• 7. 저장 프로필 관리
• 8. 저장 프로필 실행
• 9. 세션 관리
• 10. 에러 코드
• 11. 제한 · AUP

1. Điều kiện tiên quyết

• 데스크톱 앱 v0.1.23 이상 실행 + 라이선스 키로 활성화(디바이스 바인딩) 상태
• API 호출은 같은 PC의 http://127.0.0.1:9333 (Local API). 127.0.0.1 전용·LAN 차단
• X-API-Key 헤더에 SDK API 키 (sk_…) — 웹 마이페이지 "SDK API 키" 섹션
• 가족(메인+서브) 중 한 명이라도 앱에 활성화돼 있으면 공유 API 키 동작

2. Xác thực · hệ thống key

키가 두 종류입니다 — 헷갈리지 마세요:

공통 헤더

X-API-Key: sk_xxxxxxxx_yyyy
Content-Type: application/json

3. Tài khoản phụ · chia sẻ gia đình

• SDK API 키는 메인 1개 — 가족(메인+서브) 전체가 공유 (서브에 별도 sk_ 없음)
• 프로필 풀 공유 — 서브로 로그인해도 메인이 만든 프로필을 그대로 보고/실행
• 한도(maxProfiles) = 메인 플랜 기준. 메인+서브 합산이 한도 초과 안 됨
• 활성 디바이스: 메인이 해제돼도 서브 중 하나라도 활성이면 API 동작
• 서브 디바이스 해제: /account → 서브 표 → [디바이스 해제]

4. Trạng thái máy chủ

인증 불필요. 앱이 떠 있는지 확인.

curl http://127.0.0.1:9333/api/v1/status
# → { "ok": true, "version": "0.1.0", "activeSessions": 0 }

5. Chế độ Burst (engine: chromium/firefox/random)

프로필 저장 없이 매 호출 새 신원(지문·IP). 광고 검증·다계정 시뮬레이션·일회성에 적합. 포인트는 호출당 차감.

요청 본문 (전부 선택)

cURL — Firefox 지정

curl -X POST http://127.0.0.1:9333/api/v1/browser/start-ephemeral \
  -H "X-API-Key: sk_xxxxxxxx_yyyy" -H "Content-Type: application/json" \
  -d '{"os":"windows","engine":"firefox"}'

cURL — 호출마다 크롬/Firefox 무작위

curl -X POST http://127.0.0.1:9333/api/v1/browser/start-ephemeral \
  -H "X-API-Key: sk_xxxxxxxx_yyyy" -H "Content-Type: application/json" \
  -d '{"os":"windows","engine":"random"}'

6. Phân nhánh phản hồi (Chromium vs Firefox)

Firefox 는 Chrome식 attach(debugAddress)가 구조적으로 불가합니다. 그래서 응답이 엔진별로 다릅니다 — 스크립트가 분기해서 처리해야 합니다.

Chromium 응답

{
  "sessionId": "sess_a1b2c3...",
  "balance": 9990,
  "debugAddress": "127.0.0.1:51234",
  "wsEndpoint": "ws://127.0.0.1:51234/devtools/browser/UUID",
  "autoLocalized": false
}

Firefox 응답 — launch 재료 반환

{
  "sessionId": "sess_a1b2c3...",
  "balance": 9990,
  "engine": "firefox",
  "firefoxBinary": "C:\\Users\\...\\firefox\\firefox.exe",
  "profileDir":   "C:\\Users\\...\\Temp\\antidetect-burst-sess_...",
  "env": {
    "ANTIDETECT_HIDE_WEBDRIVER": "1",
    "ANTIDETECT_FF_CANVAS_SEED": "48213",
    "TZ": "Asia/Seoul"
  }
}

Python — 엔진 자동 분기 풀 예제 (Selenium)

import os, requests
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.firefox.options import Options as FxOptions

LOCAL = "http://127.0.0.1:9333"
H = {"X-API-Key": "sk_xxxxxxxx_yyyy", "Content-Type": "application/json"}

r = requests.post(f"{LOCAL}/api/v1/browser/start-ephemeral", headers=H,
    json={"os": "windows", "engine": "random"}, timeout=60)
r.raise_for_status()
d = r.json()
sid = d["sessionId"]

if d.get("engine") == "firefox":
    # Firefox: selenium-Firefox 로 직접 실행 (geckodriver Selenium Manager 자동)
    for k, v in (d.get("env") or {}).items():
        os.environ[k] = str(v)
    fo = FxOptions()
    fo.binary_location = d["firefoxBinary"]
    fo.add_argument("-profile"); fo.add_argument(d["profileDir"])
    driver = webdriver.Firefox(options=fo)
else:
    # Chromium: debugAddress 로 attach
    o = Options()
    o.add_experimental_option("debuggerAddress", d["debugAddress"])
    driver = webdriver.Chrome(options=o)

try:
    driver.get("https://pixelscan.net")
    # ... 작업 ...
finally:
    try: driver.quit()
    except: pass
    requests.post(f"{LOCAL}/api/v1/browser/stop", headers=H,
        json={"sessionId": sid}, timeout=30)

Puppeteer/Playwright(Chromium)는 wsEndpoint 로 connect. Firefox는 Playwright/Selenium-Firefox 로 launch(위 예제처럼 binary+profile).

7. Quản lý profile đã lưu

앱 UI 또는 API로 만든 영구 프로필. 가족 공유 풀이라 서브 PC에서도 메인 프로필을 그대로 사용. 엔진(브라우저 커널)은 프로필 생성/수정 시 engine 필드로 지정.

curl -H "X-API-Key: sk_..." http://127.0.0.1:9333/api/v1/profile/list
# → { "profiles": [{ "id":"prof_aa11...", "name":"쇼핑몰-1",
#                    "engine":"chromium", "tags":["instagram"], ... }, ...],
#     "balance": 9990 }

curl -X POST -H "X-API-Key: sk_..." -H "Content-Type: application/json" \
  -d '{"name":"새 프로필","engine":"firefox"}' \
  http://127.0.0.1:9333/api/v1/profile/create
# → { "profile": { "id":"prof_xx...", ... }, "balance": 9990 }

프로필 수정 — engine·group·startUrls·fingerprintOverrides 등.

curl -X PATCH -H "X-API-Key: sk_..." -H "Content-Type: application/json" \
  -d '{"engine":"firefox","group":"마케팅"}' \
  http://127.0.0.1:9333/api/v1/profile/prof_xx...

curl -X DELETE -H "X-API-Key: sk_..." http://127.0.0.1:9333/api/v1/profile/prof_xx...

8. Chạy profile đã lưu

profileId 로 저장 프로필 실행. 응답·attach 방식은 Burst와 동일하게 엔진별 분기(profile.engine 따름).

curl -X POST -H "X-API-Key: sk_..." -H "Content-Type: application/json" \
  -d '{"profileId":"prof_xx...","headless":false}' \
  http://127.0.0.1:9333/api/v1/browser/start
# Chromium 프로필 → { sessionId, debugAddress, wsEndpoint, balance }
# Firefox  프로필 → { sessionId, engine:"firefox", firefoxBinary, profileDir, env, balance }

Python — 프로필 불러와 실행

import requests
LOCAL = "http://127.0.0.1:9333"
H = {"X-API-Key": "sk_xxxxxxxx_yyyy", "Content-Type": "application/json"}

# 1) 목록 받아오기 (가족 공유 풀)
profiles = requests.get(f"{LOCAL}/api/v1/profile/list", headers=H).json()["profiles"]
target = next(p for p in profiles if p["name"] == "쇼핑몰-1")

# 2) 실행
r = requests.post(f"{LOCAL}/api/v1/browser/start", headers=H,
    json={"profileId": target["id"]}).json()

# 3) Burst 예제와 동일하게 engine 분기해서 attach/launch (위 §6 참고)

9. Quản lý phiên

curl -X POST -H "X-API-Key: sk_..." -H "Content-Type: application/json" \
  -d '{"sessionId":"sess_xxx"}' http://127.0.0.1:9333/api/v1/browser/stop
# → { "ok": true, "balance": 9990 }

curl -H "X-API-Key: sk_..." http://127.0.0.1:9333/api/v1/browser/sessions
# → { "sessions": [
#       { "sessionId":"sess_xxx", "profileId":"prof_yy...", "startedAt": 1716... }
#     ], "balance": 9990 }

10. Mã lỗi

11. Giới hạn · AUP

• Rate limit: API 키당 분당 200회(서버) + 100회(로컬 1차 캡)
• 충전 단위: 1만/3만/5만/10만원만
• 포인트 유효기간: 12개월 (미사용 시 자동 만료)
• 활성화 후 환불 불가 (환불 정책)
• 앱 "로그아웃" ≠ "디바이스 해제" — 로그아웃은 토큰만 버림, 바인딩 유지
• Burst 세션 종료 시 임시 프로필 디렉토리 자동 삭제(흔적 0)

지원: [email protected]