ProxyMarket 판매자 연동: 내 프록시 판매하기
AI에게 묻기
준비된 작업내 코드에 ProxyMarket 연동 구축하기
코딩 에이전트
Claude Code데스크톱 앱을 엽니다Codex데스크톱 앱을 엽니다Cursor웹에서 앱을 엽니다채팅 어시스턴트
ChatGPT에서 열기새 탭Claude에서 열기새 탭복사
Markdown으로 보기AI 도구용 일반 텍스트프롬프트 보기
I run my own proxy or VPN platform and want to sell it on ProxyMarket (market.xproxy.io). Read https://xproxy.io/document/proxymarket-vendor-integration.md and the OpenAPI spec https://xproxy.io/docs/api/market.openapi.yaml. If you cannot open links, download them with curl. Then look at my codebase and add, in its language and framework: 1. GET/HEAD /health that answers fast. 2. The HMAC signature check of every webhook (sign the raw body, compare in constant time). 3. The /provision, /deprovision and /settings webhooks, wired to how my platform creates, deletes and updates proxy users or VPN configs. 4. Plan sync and stock updates with the Integration API. 5. Tests for the signature check and for each webhook. Keep the API key in an environment variable. When done, tell me how to check it with one real order. Never print or commit my API keys, passwords or customer logins. Ask me before you open firewall ports, restart services or change config files you did not create. Other XProxy guides, each with a Markdown copy at its URL + .md, are listed in https://xproxy.io/llms.txt. I am reading this page in Korean: https://xproxy.io/ko/document/proxymarket-vendor-integration. The Markdown copy is in English. Answer in Korean.
프롬프트가 입력된 상태로 앱이 열립니다. Enter를 누르기 전에는 아무것도 실행되지 않습니다.
내 프록시나 VPN을 ProxyMarket(market.xproxy.io)에서 판매하세요. 서버는 계속 직접 운영합니다. ProxyMarket이 쇼핑몰 운영, 결제, 고객 응대를 맡습니다. 내 쪽의 작은 커넥터가 둘을 이어 줍니다. ProxyMarket에 몇 가지 호출을 보내고 웹훅 네 개에 응답합니다.
필요한 것: market.xproxy.io의 승인된 판매자 계정, 유효한 인증서로 ProxyMarket이 HTTPS로 접속할 수 있는 서버, 작은 웹 서비스를 작성할 수 있는 사람. 모든 엔드포인트, 필드, 응답은 ProxyMarket API 레퍼런스에도 있습니다.
한눈에 보기
플랜을 보내고, 재고와 프록시 상태를 최신으로 유지하고, 필요하면 로그인을 나중에 전달합니다. 모든 호출에 X-API-Key가 붙습니다.
10분마다 상태 점검을 하고, 고객이 결제할 때, 주문이 끝날 때, 고객이 설정을 바꿀 때 웹훅을 보냅니다.
판매 건마다 내 몫은 결제가 확정되는 즉시 적립됩니다. ProxyMarket은 쇼핑몰, 결제, 고객 지원, 환불 비용으로 30%를 가져갑니다.
어떻게 작동하나요?
판매를 시작하기까지의 단계는?
이 순서대로 진행하세요. 1~3단계는 계정 설정이고, 4~7단계는 연동 작업입니다.
- market.xproxy.io에서 일반 계정 만들기나
- 판매자 신청하기(상단 메뉴의 Become Vendor)나
- 승인, 보통 24시간 이내. 그때까지 상단 메뉴에 Vendor Pending…이 표시됩니다. 계정 이메일과 함께 @xproxyio로 메시지를 보내면 더 빨라집니다ProxyMarket
- 그동안 상태 점검을 만들고 웹훅 서버를 온라인으로 올리기나
- 판매자 대시보드에서 API 키 만들기나
- 플랜 등록, 주문 처리, 웹훅 서명 확인나
- 실제 테스트 주문을 한 번 넣고 고객이 작동하는 프록시를 받는지 확인하기나 + ProxyMarket
왜 상태 점검을 먼저 만들어야 하나요?
ProxyMarket은 HEAD {webhook_url}/health로 내 서버를 점검합니다. 내 플랜이 계속 판매될지를 결정하는 단 하나의 엔드포인트입니다.
- 키를 만들 때 ProxyMarket이 한 번 호출합니다. 5xx, 연결 거부, 5초 초과 중 하나라면 키가 만들어지지 않습니다(이유와 함께 HTTP 422).
- 그 후 10분마다, 키에 판매 중인 플랜이 있는 동안 다시 호출합니다. 2번 연속 실패하면 그 키로 제공되는 모든 플랜이 쇼핑몰에서 숨겨져 구매할 수 없게 됩니다. 정상 응답이 한 번 오면 모두 자동으로 돌아옵니다.
| 정상으로 간주 | 다운으로 간주 |
|---|---|
| 5초 안에 500 미만의 상태. 로그인도 본문도 필요 없습니다. | 시간 초과, 연결 거부, 또는 5xx 상태. |
@app.route("/health", methods=["HEAD", "GET"])
def health():
return "", 200 # no login, no database, no outside call웹훅 URL 아래에 두세요. https://your-vendor-host.com/marketplace라면 /marketplace/health에서 응답합니다.
HEAD를 막는 방화벽 때문에 약 20분 만에 카탈로그 전체가 비어 버릴 수 있습니다. /health는 가장 단순한 경로로 만드세요. 로그인, 데이터베이스, 외부 호출 없이, GET에도 응답하게 하세요. 프록시 상태 보고(POST /api/integration/health)와 혼동하지 마세요. 그것은 내가 개별 프록시에 대해 보내는 호출이며, 플랜 노출을 유지해 주지 않습니다.
API 키는 어떻게 받나요?
판매자 신청이 승인되면 직접 만듭니다. 누가 보내 주지 않습니다. 판매자 대시보드에서 키 이름과 웹훅 URL(예: https://your-vendor-host.com/marketplace)을 입력하세요. 호출 한 번으로도 만들 수 있습니다(레퍼런스).
curl -X POST "https://market.xproxy.io/api/vendor/integrations" \
-H "Authorization: Bearer $PROXYMARKET_LOGIN_JWT" \
-H "Content-Type: application/json" \
-d '{"name": "primary-instance", "webhook_url": "https://your-vendor-host.com/marketplace"}'
# {"api_key": "pm_..."} <- shown only this once, save it now키 하나에서 두 가지 값이 나옵니다. 구분해서 쓰세요.
| 값 | 설명 | 용도 |
|---|---|---|
api_key | pm_로 시작하는 키 자체 | 내가 보내는 모든 호출의 X-API-Key 헤더 |
signing_key | 64자 hex로 된 SHA256(api_key) | 모든 웹훅의 X-Signature 확인(방법) |
키는 만료되지 않으며, 웹훅 URL은 나중에 바꿀 수 없습니다. 서버를 옮기려면 새 키를 만드세요. 독립된 서버를 여러 대 운영한다면 서버마다 키를 따로 주세요. 주문은 판매자 대시보드에서 각 플랜의 API Key / Server에 설정된 키로 갑니다. 동기화로 만든 플랜은 동기화한 키를 받고, 이 설정이 없는 예전 플랜은 가장 오래된 활성 키로 주문을 보냅니다.
pm-connector test가 경고합니다. 오류: X-API-Key 헤더가 없는 호출은 422, 잘못된 키는 401, 판매자 신청이 아직 대기 중인 키는 403을 받습니다. 판매자 대시보드의 Integration Status 탭에는 키별로 마지막 접속 시각, 커넥터 버전, 최근 전달 20건과 그 결과가 표시됩니다.
플랜은 어떻게 등록하나요?
커넥터가 시작될 때, 그리고 무언가 바뀔 때마다 플랜 게시 또는 업데이트로 모든 상품을 보내세요. 동기화된 플랜은 즉시 승인됩니다(대시보드에서 직접 추가한 플랜은 관리자 승인을 기다립니다). external_id는 상품(포트, 모뎀, VPN 풀)에 대한 내 ID이며, 이후의 모든 호출과 웹훅에서 사용됩니다.
curl -X POST "https://market.xproxy.io/api/integration/plans/sync" \
-H "X-API-Key: $PROXYMARKET_API_KEY" \
-H "Content-Type: application/json" \
-d '[{
"external_id": "port-1",
"name": "US Mobile 4G - Port 1",
"proxy_type": "mobile",
"protocol": "HTTP",
"country": "United States",
"duration_days": 30,
"price_usd": 25.00,
"stock": 1,
"is_active": true
}]'
# {"created": 1, "updated": 0, "plans": [{"plan_id": "...", "external_id": "port-1", "status": "created"}]}| 알아 둘 점 | 이유 |
|---|---|
같은 external_id를 다시 보내면 플랜이 업데이트됩니다 | 동기화는 반복해도 안전하며 중복을 만들지 않습니다. |
| 목록에서 뺀 플랜도 계속 판매됩니다 | 판매를 멈추려면 플랜 판매 중지를 호출하세요. |
proxy_type에는 mobile, residential, datacenter, isp, ipv6, vpn만 사용하세요 | API는 아무 텍스트나 받지만, 다른 값은 주문을 망가뜨려 고객이 로그인을 받지 못합니다. VPN과 VLESS를 참고하세요. |
country는 영어 전체 이름입니다. 예: United States | 고객은 정확한 텍스트로 필터링하므로 모든 플랜에서 철자를 똑같이 쓰세요(자세히). ProxyMarket은 이를 확인하지 않습니다. |
| 플랜은 활성 상태이고, 재고가 있고, 노출 설정되어 있고, 상태 점검으로 숨겨지지 않았을 때만 표시됩니다 | stock은 보통 모뎀 포트당 1입니다. 포트 하나에 고객 한 명입니다. |
protocol을 생략하면 HTTP입니다 | VPN과 SOCKS5 플랜에는 꼭 보내세요. |
| 동기화로 만든 플랜은 동기화한 키에 고정됩니다 | 주문은 그 키로 갑니다. 동기화는 이미 있는 플랜의 키를 절대 바꾸지 않습니다(자세히). |
누군가 구매하면 어떻게 되나요?
- 고객이 결제합니다. 내 서버가 호출되기도 전에 내 몫 70%가 잔액에 바로 적립됩니다.
- ProxyMarket이
POST {webhook_url}/provision을 호출합니다.order_id와 내external_plan_id가 함께 옵니다(페이로드). 서명을 확인한 뒤 고객의 접속 권한을 만드세요. - 응답합니다. 로그인이나 설정(가장 좋음),
pending, 또는error로 응답합니다. 아래 표를 참고하세요. - 고객이 ProxyMarket에서 로그인을 확인하고 내 서버에 연결합니다. ProxyMarket이 플랜의 재고를 자동으로 하나 줄입니다.
- 기간이 끝나면 ProxyMarket이 자동으로 주문을 종료하고(5분마다 확인)
POST {webhook_url}/deprovision을 호출합니다. 접속 권한을 삭제하고 해당 유닛을 다시 판매 상태로 돌리세요. 주문이 끝날 때를 참고하세요.
응답하는 status | 사용하는 경우 | 결과 |
|---|---|---|
provisioned(가장 좋음) | 접속 권한을 바로 만들 수 있을 때 | 고객이 즉시 받습니다. proxy_ip, proxy_port, proxy_username, proxy_password 네 가지를 모두 넣거나, VPN이면 vpn_config_file을 넣으세요. |
pending | 준비에 시간이 걸릴 때 | 프록시 로그인 또는 VPN 설정 전달로 보내세요. ProxyMarket은 시작 시점부터 총 120초를 기다립니다. 그 후에는 주문이 환불되고, 늦은 전달은 409를 받습니다. |
error | 전달할 수 없을 때(포트 오프라인, 빈 프로필 없음) | 아무것도 전달되지 않습니다. 120초가 지나면 고객은 지갑으로 환불받고 내 수익은 삭제됩니다. |
/provision이 다른 상태로 응답하거나, 시간 초과(30초)되거나, 잘못된 JSON을 반환하거나, 로그인이 불완전한데 provisioned라고 하면, ProxyMarket은 플랜에 동기화해 둔 로그인이 있을 경우 그것을 대신 고객에게 줍니다. 전달된 로그인은 플랜에 복사되지 않으며, 이미 다른 주문에 속한 플랜 로그인은 재사용되지 않고 그 주문은 환불됩니다. 호출은 재시도되지 않습니다. 응답의 expires_at은 무시됩니다. ProxyMarket이 활성화 시점부터 시간을 계산해 /deprovision에서 알려 줍니다.
일반 http:// URL에서 응답을 암호화할 수 있나요?
네, 선택 사항입니다. 200으로 응답하면서 헤더 X-PM-Encrypted: v1과 X-PM-Signature: sha256= + 서명 키로 만든 원본 본문의 hex HMAC-SHA256을 넣고, 본문은 {"enc": "v1", "nonce": "…", "ct": "…"}로 보내세요. 무작위 12바이트 nonce와, 평소 응답을 AES-256-GCM으로 암호화한 암호문(태그 덧붙임)이며 둘 다 표준 base64입니다. 키는 서명 키의 UTF-8 바이트에 대한 HKDF-SHA256(빈 salt, info pm-provision-v1, 32바이트)이고, AAD는 order_id입니다. ProxyMarket은 서명을 확인하고 복호화한 뒤 평소처럼 응답을 읽습니다. 잘못된 봉투는 시간 초과와 같이 처리됩니다. 전체 형식과 테스트 벡터는 API 레퍼런스와 가이드 5.1절에 있습니다. pm-connector는 http:// URL에서 이를 자동으로 처리합니다. 웹훅 요청은 암호화되지 않으므로 여전히 HTTPS를 권장합니다.
order_id를 저장하세요. 나중에 전달하거나, 주문을 직접 종료하거나, 다른 웹훅과 맞춰 볼 때 필요합니다.
웹훅이 정말 ProxyMarket에서 온 것인지 어떻게 확인하나요?
모든 웹훅 POST에는 원본 본문의 HMAC-SHA256인 X-Signature: sha256=…가 붙습니다. 비밀 값은 API 키 자체가 아니라 서명 키, 즉 hex로 된 SHA256(api_key)입니다. /provision, /deprovision, /update-settings에서 다른 무엇보다 먼저 확인하세요.
import hashlib, hmac, os
API_KEY = os.environ["PROXYMARKET_API_KEY"]
# The HMAC secret is SHA256(api_key) as hex, NOT the raw key. Compute it once.
SIGNING_KEY = hashlib.sha256(API_KEY.encode()).hexdigest()
def verify_signature(raw_body: bytes, header: str) -> bool:
expected = "sha256=" + hmac.new(SIGNING_KEY.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header or "")
# Flask: sign the raw bytes, before you parse the JSON
@app.route("/provision", methods=["POST"])
def provision():
if not verify_signature(request.get_data(), request.headers.get("X-Signature", "")):
return jsonify({"status": "error", "message": "Invalid signature"}), 401
data = request.get_json()
...원본 요청 본문을 사용하세요. JSON을 파싱했다가 다시 직렬화하면 바이트가 바뀌어 서명이 더 이상 맞지 않습니다.
고객이 구매하기 전에 어떻게 테스트하나요?
- 내 네트워크 밖에서
curl -I https://your-vendor-host.com/marketplace/health를 실행해 5초 안에 500 미만의 상태가 오는지 확인하세요. - 플랜 하나를 동기화하고 market.xproxy.io의 Browse에서 찾아보세요.
- 그 플랜으로 실제 주문을 한 번 넣으세요. 내 서버가 유효한 서명이 붙은
/provision을 받고, 고객의 주문에 로그인이 나타나야 합니다. - 그 로그인으로 연결한 다음, 주문이 끝날 때까지 기다리거나(또는 텔레그램으로 종료를 요청하고)
/deprovision이 접속 권한을 삭제하고 재고가 돌아오는지 확인하세요.
테스트 주문을 넣을 때 텔레그램 @xproxyio로 ProxyMarket에 알려 주세요. 그쪽에서도 확인할 수 있습니다.
재고와 상태는 어떻게 최신으로 유지하나요?
| 내 쪽에서 이런 일이 생기면 | 호출 |
|---|---|
| 모뎀이나 서버가 오프라인이 됨 | stock: 0, is_active: false로 PATCH /plans/stock |
| 다시 온라인이 되거나, 팔렸던 포트가 다시 비었음 | stock: 1, is_active: true로 PATCH /plans/stock |
| 가격, 이름, 설정이 바뀜 | 해당 플랜만 담아 POST /plans/sync |
| 상품 판매를 중단함 | DELETE /plans/{external_id} |
| 선택, 몇 분마다 | 각 프록시의 상태와 현재 IP를 담아 POST /health. current_ip는 항상 넣으세요. 빼면 저장된 IP가 지워집니다. 이 호출은 플랜 노출을 유지하지 않으며, 그것은 서버 상태 점검이 합니다. |
모든 경로는 https://market.xproxy.io/api/integration으로 시작합니다.
주문이 끝나면 어떻게 되나요?
ProxyMarket이 reason과 함께 POST {webhook_url}/deprovision을 호출합니다.
| 사유 | 의미 |
|---|---|
expired | 임대 기간이 끝났습니다. 자동으로 전송되며 최대 5분 늦을 수 있습니다. |
renewed | 고객이 사용 중인 주문의 갱신을 결제했습니다. 이전 주문은 지금 끝나고, 새 order_id로 새 /provision이 이어집니다. |
cancelled | 관리자가 주문을 취소했습니다. |
admin_refund | 관리자가 고객에게 환불했습니다. 해당 수익은 회수됩니다. |
고객의 로그인을 삭제하세요(또는 VPN 프로필을 끄세요). 그런 다음 PATCH /plans/stock으로 실제 남은 유닛 수를 보내세요. ProxyMarket은 환불 후에는 재고를 자동으로 되돌리지만, 만료 후에는 되돌리지 않습니다. {"status": "deprovisioned"}로 응답하세요. 응답은 로그에만 남습니다.
/provision에서 알 수 있습니다). 프로비저닝에 실패해 자동 환불된 주문에는 /deprovision이 아예 오지 않습니다. 주문 만료 처리는 ProxyMarket에서 주문 상태만 바꿉니다. 취소된 주문을 포함해 어떤 상태에서든 가능합니다. 고객에게 환불하거나, 재고를 바꾸거나, 웹훅을 호출하지 않습니다.
고객이 IP 화이트리스트나 TCP 핑거프린트를 바꾸면?
고객이 활성 주문에서 Proxy Settings를 저장하면 ProxyMarket이 POST {webhook_url}/update-settings를 호출합니다. 주문 유형과 상관없이 한 번 전송됩니다. 내 시스템이 지원하는 것을 적용하고 {"status": "ok"}로 응답하세요. 지원하지 않는 필드는 무시해도 됩니다. 본문에 external_plan_id가 없으므로 프로비저닝 때 저장한 order_id로 플랜을 찾으세요.
ip_whitelist: 이 IP만 프록시를 쓸 수 있습니다. 항상 단일 주소의 목록이며,[]는 IP 제한 없음을 뜻합니다.tcp_fingerprint: 연결이 어떤 OS처럼 보여야 하는지(win1Windows 11,mac1macOS,ios1iPhone 15,android1Galaxy S24 등).null은 끕니다.
VPN과 VLESS는 어떻게 판매하나요?
주문 흐름은 같고, 전달하는 것만 다릅니다. 고객이 그대로 가져올 수 있는 완전한 클라이언트 파일을 보내세요.
| 상품 | 플랜 필드 | 전달할 것 |
|---|---|---|
| OpenVPN | proxy_type: "vpn", protocol: "OpenVPN", vpn_protocol: "openvpn" | 인증서와 키가 포함된 전체 .ovpn 텍스트 |
| WireGuard | proxy_type: "vpn", protocol: "WireGuard", vpn_protocol: "wireguard" | [Interface]와 [Peer]가 있는 전체 .conf |
| VLESS (Xray) | proxy_type: "vpn", protocol: "VLESS", vpn_protocol: "vless" | 한 줄짜리 vless:// 링크 또는 전체 Xray 클라이언트 JSON |
proxy_type: "xray"는 절대 보내지 마세요. 쇼핑몰은 VLESS 플랜을 “Xray”로 표시하지만, 그 표시는 vpn_protocol에서 옵니다. xray는 API가 받아들이지만 플랜을 망가뜨립니다. 고객이 결제해도 설정이 도착하지 않습니다. 파일을 전달하는 방법은 세 가지입니다.
- 플랜의 모든 고객에게 같은 파일: 동기화할 때
vpn_config_template에 넣으세요. - 주문마다 새 파일:
/provision에서 만들고vpn_config_file로 응답하세요. - 시간이 걸리는 새 파일:
pending으로 응답한 다음 프록시 로그인 또는 VPN 설정 전달로vpn_config_file을 보내세요.
VLESS는 주문마다 고유한 UUID를 주세요(하나를 공유하면 고객 한 명을 해지할 때 모두 해지됩니다). 플랜 설명에 전송 방식(예: XTLS-Reality 또는 WS+TLS)을 적고, 주문이 끝나면 인바운드에서 UUID를 삭제하세요.
OpenVPN 파일에는 remote, dev tun 또는 dev tap이 있거나, client와 <ca> 블록이 모두 있어야 합니다. <ca> 블록만 있으면 거부됩니다. 모든 설정은 최소 50자 이상이어야 합니다.
IP 로테이션은 어떻게 작동하나요?
내가 전달하는 rotation_link는 ProxyMarket이 직접 호출하는 URL입니다. 단순 GET으로 호출하며(리디렉션 따라감, 인증서 확인 안 함, 15초 시간 제한), 고객이 Rotate를 누를 때와 고객이 고른 자동 로테이션 타이머(5~60분마다)에 맞춰 호출하고, 주문이 끝나면 멈춥니다. 고객도 링크를 보고 열 수 있습니다.
플랜 자체의 rotation_link가 대체용으로 제공되는 경우(위 참고), 이미 다른 주문에 속한 링크는 절대 제공되지 않습니다.
이미 만들어진 웹훅 서버가 있나요?
네. ProxyMarket 커넥터(pm-connector)는 Linux나 Windows 서버에서 실행되며 이 페이지의 모든 일을 대신 처리합니다. 내 시스템에서 고객의 로그인을 추가·삭제하는 작은 스크립트 하나만 넘겨주면 됩니다. Python, Node.js, shell용 준비된 스크립트가 해당 페이지에 있습니다.
- 서명을 확인하며 웹훅에 응답하고, 내 시스템에 고객의 사용자 이름과 비밀번호를 만들었다가 임대가 끝나면 삭제합니다.
- ProxyMarket hook(키 유형 ProxyMarket hook)으로 ProxyMarket에 연결합니다.
market-hook-service.xproxy.io로 나가는 연결 하나이므로 서버에 포트 개방도 도메인도 필요 없습니다. 고객은 항상 내 프록시 포트에 직접 연결합니다. - 다운타임 후에도 따라잡습니다. 오프라인인 동안 끝난 주문의 사용자는 다시 켜지는 즉시 삭제됩니다.
플랜은 Vendor Dashboard에서 만듭니다. ProxyMarket이 hook 대신 내 HTTPS 주소를 호출하게 하려면 내 주소 사용하기를 참고하세요.
수익은 어떻게 받나요?
| 내 몫 | 판매 건마다 70%(표준 요율, 판매자별로 협의 가능) |
|---|---|
| ProxyMarket 몫 | 30%, 쇼핑몰, 결제, 고객 지원, 환불 비용 |
| 적립 시점 | 고객의 결제가 확정되고 주문이 활성화되는 즉시, 내 /provision이 호출되기 전 |
| 확인하는 곳 | 판매자 대시보드의 Earnings: 판매 건별 금액, 내 금액, 적용된 요율 |
| 정산 | ProxyMarket 관리자가 내 잔액에서 지급합니다. 출금하려면 텔레그램으로 요청하세요. |
| 환불 | 자동 환불(120초 안에 아무것도 전달되지 않음)이나 관리자 환불은 내 잔액에서 해당 수익을 뺍니다. 프로모션 코드는 판매 금액을 낮추며, 내 몫도 함께 줄어듭니다. |
| 출금 | 잔액 범위 안에서 지급되며, 가장 오래된 미지급 수익부터 지급 완료로 표시됩니다. |
요율은 판매 건마다 저장되므로, 나중에 요율이 바뀌어도 이미 번 돈에는 영향이 없습니다.
내 플랜은 쇼핑몰 어디에 표시되나요?
Browse는 가장 저렴한 플랜부터 보여 주는데, 가격을 정하기 전에 알아 둘 규칙이 하나 있습니다. XProxy 소프트웨어를 쓰는 판매자의 플랜이 먼저 표시되며, Powered by xProxy 아래에 xProxy 배지와 함께 나옵니다. 내 커넥터의 플랜은 그다음 Other vendors 아래에, 역시 저렴한 순으로 나옵니다.
| 위치 | 순서를 정하는 기준 |
|---|---|
| Browse, 기본 | XProxy 그룹이 먼저, 그다음 내 플랜, 각 그룹 안에서 저렴한 순 |
| Browse, 고객이 정렬할 때 | 정렬은 각 그룹 안에서 적용되므로, 내 플랜이 더 저렴해도 XProxy 그룹 아래에 남습니다 |
| 홈페이지 “from $X” 카드 | 각 카테고리에서 가장 저렴한 XProxy 플랜. 그 카테고리에 XProxy 재고가 없을 때만 내 플랜 |
| 국가, 프로토콜, 검색 필터, 내 스토어 페이지 | 모든 판매자에게 완전히 동일 |
표시된 플랜이 모두 한 그룹에 속하면 Browse는 제목 없이 하나의 목록으로 보여 줍니다. 대부분의 고객은 국가나 프로토콜로 필터링해서 들어오며, 그곳에서는 내 플랜이 다른 모든 판매자의 플랜과 나란히 놓입니다.
오류 코드는 무슨 뜻인가요?
| 코드 | 의미 | 할 일 |
|---|---|---|
401 | Invalid API key(잘못되었거나 꺼진 키), Missing API key(빈 헤더), 또는 Vendor inactive | X-API-Key 헤더와 대시보드에서 키가 켜져 있는지 확인하세요 |
403 | 판매자 신청이 아직 대기 중(모든 호출), 또는 계정이 승인된 판매자가 아님(키 생성) | 승인을 기다리세요 |
404 | 알 수 없는 external_id 또는 order_id | ID를 확인하고, 먼저 플랜을 동기화하세요 |
409 | 더 이상 결제 또는 활성 상태가 아닌 주문에 인증 정보를 전달함 | 보통 120초가 지나 주문이 환불된 경우입니다. 재시도하지 마세요 |
422 | 값이 유효하지 않거나, X-API-Key 헤더가 아예 없음 | 응답의 detail에 해당 필드가 나옵니다 |
500 | ProxyMarket 오류 | 간격을 점점 늘리며 재시도하세요 |
오류는 {"detail": "…"} 형식으로 돌아옵니다. 공개된 요청 제한은 없지만, 짧은 루프로 반복하지 말고 변경이 있을 때 동기화하세요.
전체 예제가 있나요?
네. 이 Python 커넥터는 프록시 플랜 하나를 동기화하고, 5분마다 상태를 보고하며, 웹훅 네 개에 모두 응답합니다. 위쪽의 두 함수를 내 시스템 호출로 바꾸고, 기간이 끝나면 각 주문을 종료하는 타이머를 추가하세요.
"""Minimal ProxyMarket connector: sync plans, report health, answer the four webhooks."""
import hashlib
import hmac
import os
import secrets
import threading
import time
import requests
from flask import Flask, jsonify, request
API_KEY = os.environ["PROXYMARKET_API_KEY"] # pm_... from "Create your API key"
MARKET = "https://market.xproxy.io/api/integration"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
SIGNING_KEY = hashlib.sha256(API_KEY.encode()).hexdigest()
# ── Your system (replace with your own code) ─────────────────────────
PORTS = {
"port-1": {"name": "US Mobile 4G - Port 1", "country": "United States", "protocol": "HTTP",
"price": 25.00, "days": 30, "online": True, "ip": "203.0.113.1", "port": 8080},
}
def add_proxy_login(port_id, username, password): ... # create the customer's login
def remove_proxy_login(port_id, order_id): ... # delete it again
# ── Calls you make ───────────────────────────────────────────────────
def sync_plans():
plans = [{
"external_id": pid, "name": p["name"], "proxy_type": "mobile", "protocol": p["protocol"],
"country": p["country"], "duration_days": p["days"], "price_usd": p["price"],
"stock": 1 if p["online"] else 0, "is_active": p["online"],
} for pid, p in PORTS.items()]
r = requests.post(f"{MARKET}/plans/sync", json=plans, headers=HEADERS, timeout=15)
print("[sync]", r.status_code, r.json())
def set_stock(port_id, free):
requests.patch(f"{MARKET}/plans/stock", headers=HEADERS, timeout=15,
json=[{"external_id": port_id, "stock": 1 if free else 0, "is_active": free}])
def health_reporter():
while True:
try:
reports = [{"external_id": pid, "status": "online" if p["online"] else "offline",
"current_ip": p["ip"]} for pid, p in PORTS.items()]
requests.post(f"{MARKET}/health", json=reports, headers=HEADERS, timeout=15)
except requests.RequestException as e:
print("[health]", e)
time.sleep(300) # every 5 minutes
# ── Webhooks ProxyMarket calls ───────────────────────────────────────
app = Flask(__name__)
def signed():
expected = "sha256=" + hmac.new(SIGNING_KEY.encode(), request.get_data(), hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, request.headers.get("X-Signature", ""))
@app.route("/health", methods=["HEAD", "GET"])
def health():
return "", 200
@app.route("/provision", methods=["POST"])
def provision():
if not signed():
return jsonify({"status": "error", "message": "Invalid signature"}), 401
data = request.get_json()
port = PORTS.get(data["external_plan_id"])
if not port or not port["online"]:
return jsonify({"status": "error", "message": "Port offline"}) # ProxyMarket refunds the customer
username = f"cust_{data['order_id'][:8]}"
password = secrets.token_urlsafe(16)
add_proxy_login(data["external_plan_id"], username, password)
set_stock(data["external_plan_id"], free=False)
return jsonify({
"status": "provisioned",
"proxy_ip": port["ip"], "proxy_port": port["port"],
"proxy_username": username, "proxy_password": password,
})
@app.route("/deprovision", methods=["POST"])
def deprovision():
if not signed():
return jsonify({"status": "error", "message": "Invalid signature"}), 401
data = request.get_json()
remove_proxy_login(data["external_plan_id"], data["order_id"]) # must be safe to run twice
set_stock(data["external_plan_id"], free=True)
return jsonify({"status": "deprovisioned"})
@app.route("/update-settings", methods=["POST"])
def update_settings():
if not signed():
return jsonify({"status": "error", "message": "Invalid signature"}), 401
data = request.get_json()
# data["ip_whitelist"]: [] = allow everyone, None = leave as it is
# data["tcp_fingerprint"]: "win1", "ios1", ... or None = no spoofing
return jsonify({"status": "ok"}) # apply what you support, ignore the rest
if __name__ == "__main__":
sync_plans()
threading.Thread(target=health_reporter, daemon=True).start()
# Serve this behind HTTPS at your webhook_url, for example https://your-vendor-host.com/marketplace
app.run(host="0.0.0.0", port=9090)전체 API 레퍼런스는 어디에 있나요?
모든 호출과 웹훅의 전체 필드, 응답 예시, curl·Python·Node.js·PHP 코드는 ProxyMarket API 레퍼런스에 있습니다. OpenAPI 3.1 파일은 market.openapi.yaml입니다.
| 방향 | 엔드포인트 | 하는 일 |
|---|---|---|
| 내가 호출 | POST /api/vendor/integrations | API 키 만들기 |
| 내가 호출 | POST /plans/sync | 플랜 게시 또는 업데이트 |
| 내가 호출 | PATCH /plans/stock | 재고와 노출 변경 |
| 내가 호출 | DELETE /plans/{external_id} | 플랜 판매 중지 |
| 내가 호출 | POST /health | 프록시 상태 보고 |
| 내가 호출 | POST /orders/{order_id}/credentials | 로그인이나 설정을 나중에 전달 |
| 내가 호출 | POST /orders/{order_id}/expire | 주문 만료 처리(환불 없음) |
| ProxyMarket이 호출 | HEAD /health | 플랜 노출을 유지하는 상태 점검 |
| ProxyMarket이 호출 | POST /provision | 고객이 결제함: 전달하기 |
| ProxyMarket이 호출 | POST /deprovision | 주문이 끝남: 접속 권한 삭제 |
| ProxyMarket이 호출 | POST /update-settings | 새 IP 화이트리스트나 TCP 핑거프린트 적용 |
| 내가 호출 | GET /orders/active | 내 키로 라우팅된 결제 및 활성 주문 |
어떤 국가를 등록할 수 있나요?
어느 국가든 됩니다. United States, Germany, Vietnam처럼 영어 전체 국가 이름을 보내고, 모든 플랜에서 철자를 똑같이 쓰세요. 고객은 정확한 텍스트로 필터링합니다. ProxyMarket은 이름을 확인하지 않으며, 가이드와 판매자 대시보드의 목록에 있는 철자를 쓰면 됩니다. pm-connector test는 그 목록에 없는 이름을 거부합니다.
버전 1.13에서 무엇이 바뀌었나요?
- 새 호출: 다운타임 후 따라잡기 위한 내 키로 라우팅된 주문 목록(
GET /orders/active,routed_plans와 ETag 포함). - 더 안전한 대체 처리: 전달된 로그인이 더 이상 플랜에 복사되지 않으며, 다른 주문에 속한 플랜 로그인이나 로테이션 링크는 절대 제공되지 않습니다.
- 프로비저닝 시점:
/provision은 결제가 확정된 후에만 전송되므로, 즉시 보내는 인증 정보 푸시도 받아들여집니다./update-settings에는 항상 고객이 방금 저장한 값이 담깁니다. - ProxyMarket 커넥터: NAT 뒤에서 접속하는 방법을 포함한, 이미 만들어진 웹훅 서버. 커넥터를 참고하세요.
- 암호화된 프로비저닝 응답(선택): 일반
http://웹훅 URL에서X-PM-Encrypted: v1로/provision응답을 봉인합니다. 위를 참고하세요. - 플랜 고정: 동기화로 만든 플랜은 동기화한 키로 갑니다.
- 로테이션: ProxyMarket이
GET으로rotation_link를 호출합니다. IP 로테이션을 참고하세요. - 판매자 대시보드의 Integration Status 탭과 선택 사항인
X-PM-Connector헤더. - 코드와 일치하도록 문서화:
X-API-Key헤더가 없으면 422, 신청 대기 중에는 403, 프로비저닝 시간 제한 30초, 국가와 동기화 포트는 검증하지 않음,protocol기본값은 HTTP,current_ip없는/health보고는 IP를 지움, OpenVPN<ca>규칙,/update-settings에는external_plan_id없음.
자주 묻는 질문
XProxy를 사용합니다. 이것을 직접 만들어야 하나요?
아니요. 패널에서 ProxyMarket을 켜면(Selling Platform → ProxyMarket) 웹훅을 포함해 이 모든 것을 대신 처리합니다. ProxyMarket에서 판매를 참고하세요. 내 플랜에 xProxy 배지도 붙습니다.
왜 내 플랜이 모두 쇼핑몰에서 사라졌나요?
거의 항상 상태 점검 때문입니다. HEAD {webhook_url}/health가 두 번 연속 실패했습니다(다운, 5초보다 느림, 5xx, 또는 HEAD 차단). 문제를 고치면 다음 정상 점검 후 10분 안에 플랜이 돌아옵니다.
API 키를 잃어버렸습니다. ProxyMarket이 다시 보내 줄 수 있나요?
아니요. 해시만 저장되어 있습니다. 새 키를 만들고, 서명 키도 함께 바뀐다는 점을 기억하세요.
서명 확인이 계속 실패합니다. 왜 그런가요?
보통 둘 중 하나입니다. HMAC 비밀 값으로 hex SHA256(api_key) 대신 API 키 원본을 썼거나, 원본 요청 본문 대신 파싱 후 다시 인코딩한 JSON에 서명했습니다.
내 서버가 전달에 실패해도 수익을 받나요?
아니요. 120초 안에 쓸 수 있는 것이 오지 않으면 고객은 환불받고 수익은 내 잔액에서 빠집니다.
고객이 왜 예전 로그인을 받았나요?
내 /provision이 200이 아닌 상태로 응답했거나, 시간 초과되었거나, 잘못된 JSON을 보내서 ProxyMarket이 플랜에 동기화된 로그인을 준 것입니다. 전달된 로그인은 플랜에 저장되지 않으며, 플랜 로그인이 이미 다른 주문에 속해 있으면 재사용되지 않습니다(그 대신 해당 주문이 환불됩니다). 전달할 수 없다면 error와 함께, 항상 200으로 응답하세요.
서버 여러 대를 연결할 수 있나요?
네. 서버마다 키를 하나씩, 각각 고유한 웹훅 URL로 만드세요. 동기화로 만든 플랜은 동기화한 키로 갑니다. 예전 플랜은 대시보드에서 API Key / Server를 설정하세요. 그렇지 않으면 주문이 가장 오래된 키로 갑니다.
고객이 갱신하면 어떻게 되나요?
만료된 주문을 갱신하는 것은 일반적인 새 주문입니다. 사용 중인 주문을 갱신하면 먼저 이전 주문에 대해 reason: renewed로 /deprovision을 보내고, 그다음 새 order_id로 새 주문의 /provision을 보냅니다.
다음 단계는?
전체 레퍼런스를 열거나, 텔레그램으로 ProxyMarket에 문의하세요.

