eBayProxyPro
REST API v1.4.2

API Documentation

API thật của hệ thống proxy node: kiểm tra exit IP, khóa vị trí, thuê có thời hạn, theo dõi lưu lượng và tự thu hồi khi proxy không còn hợp lệ.

Tổng quan

Base URL local:

text
http://localhost:4001/api/v1
Public API chỉ trả exit IP đã che hai octet cuối. Thông tin proxy nguồn không xuất hiện trong response; người thuê chỉ nhận host, port và credential của relay node.

JWT authentication

Đăng nhập để nhận accessToken và gửi token theo chuẩn Bearer cho endpoint có biểu tượng khóa trong Swagger.

POST/api/v1/auth/login
bash
curl -X POST "http://localhost:4001/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your-password"}'
bash
curl "http://localhost:4001/api/v1/users/me" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Refresh token: POST /api/v1/auth/refresh với JSON {"refreshToken":"..."}.

Quy ước dữ liệu

  • type: RESIDENTIAL, DATACENTER, ISP hoặc MOBILE.
  • deviceType: ANDROID, WINDOWS, MACOS, IOS, LINUX hoặc OTHER.
  • status: LIVE, WARNING hoặc OFFLINE.
  • rentalStatus: ACTIVE, EXPIRED, RETURNED, REVOKED hoặc REFUNDED.
  • Gói IP có thời hạn cố định 24 giờ và giới hạn dung lượng do server công bố trong fixedIncludedGb; gói dung lượng có hiệu lực tối đa 30 ngày.

Danh sách kho và bộ lọc

GET/api/v1/proxies?platform=ebay

Endpoint public. Tham số platform lọc Exit IP chưa từng được cấp cho nền tảng đó. Danh sách nền tảng: GET /api/v1/proxies/platforms. Các bộ lọc khác: country, type, city, region, zipcode, isp, deviceType, status, limit và offset.

bash
curl "http://localhost:4001/api/v1/proxies?platform=ebay&country=US&type=RESIDENTIAL&deviceType=WINDOWS&region=Arizona&status=LIVE"
json
{
  "items": [{
    "id": "proxy_id",
    "type": "RESIDENTIAL",
    "deviceType": "WINDOWS",
    "country": "US",
    "region": "Arizona",
    "city": "Phoenix",
    "zipcode": "85004",
    "ip": "184.190.*.*",
    "status": "LIVE",
    "price": 0.5,
    "rentalMinutes": 30,
    "pricingMode": "FIXED_TIME",
    "fixedIncludedGb": 1,
    "pricePerGb": 1.5
  }],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Thuê proxy node

POST/api/v1/user-proxies/rent
JWT
bash
curl -X POST "http://localhost:4001/api/v1/user-proxies/rent" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"proxyId":"proxy_id","platformSlug":"ebay"}'
Hệ thống kiểm tra live và exit IP ngay trước khi thuê, sau đó kiểm tra lại mỗi 30 giây. Node hỗ trợ CONNECT và UDP ASSOCIATE khi listing hiển thị UDP: Có. Mọi gói TCP/UDP vẫn chỉ được đi tới domain và cổng của target; kết nối trực tiếp bằng IP hoặc domain khác bị chặn. Client nên bật remote DNS qua SOCKS5.

Dịch vụ thiết yếu Google Play, Android và iOS được server tự ghép vào mọi target. addonSlugs chỉ dùng cho bundle tùy chọn như PayPal. Rule seller cấm luôn có ưu tiên cao nhất.

Listing FIXED_TIME là một IP dùng tối đa 24 giờ với giá cố định và giới hạn fixedIncludedGb; node tự ngắt theo điều kiện thời gian hoặc dung lượng đến trước. Listing BANDWIDTH nhận bandwidthGb và tự ngắt khi dùng hết dung lượng.

json
{
  "id": "rental_id",
  "ip": "proxy-node.example.com",
  "port": "20000",
  "username": "node_generated_user",
  "password": "node_generated_password",
  "connectionUrl": "socks5h://node_generated_user:node_generated_password@proxy-node.example.com:20000",
  "exitIp": "203.0.113.10",
  "exitIpMasked": "203.0.*.*",
  "platformName": "eBay",
  "allowedDomains": ["ebay.com", "ebaystatic.com", "ebayimg.com"],
  "allowedKeywords": ["ebay"],
  "blockedDomains": [],
  "blockedKeywords": [],
  "addonSlugs": [],
  "policyVersion": 2,
  "billingMode": "FIXED_TIME",
  "rentalStatus": "ACTIVE",
  "expiresAt": "2026-08-08T08:00:00.000Z",
  "remainingSeconds": 86400,
  "refundWindowRemainingSeconds": 600,
  "canRequestRefund": true,
  "price": 0.5,
  "deducted": 0.5
}

Danh sách proxy node của tôi

GET/api/v1/user-proxies
JWT

Hỗ trợ filter country, type, city, region, isp, zipcode, deviceType, rentalStatus, limit và offset.

bash
curl "http://localhost:4001/api/v1/user-proxies?rentalStatus=ACTIVE&deviceType=WINDOWS" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Nếu ứng dụng gặp lỗi do thiếu domain, gọi GET /api/v1/user-proxies/{id}/blocked-domains để lấy domain relay đã chặn, sau đó gửi POST /api/v1/user-proxies/{id}/report-domain với eventId. Chỉ domain thực tế đã bị chặn mới được báo.

Hoàn proxy lỗi và tự hết hạn

POST/api/v1/user-proxies/{id}/refund
JWT

Chỉ được hoàn trong 10 phút đầu kể từ lúc thuê và khi backend xác nhận proxy không live hoặc Exit IP không khớp IP đã xác minh. Node bị ngắt, tiền được hoàn đúng một lần, proxy chuyển sang trạng thái đã sử dụng và không quay lại kho.

json
{
  "returned": true,
  "refunded": true,
  "refundedAmount": 0.5,
  "balance": 10.5,
  "reason": "UPSTREAM_OFFLINE: connection timeout"
}

Khi expiresAt đến hạn bình thường, backend tự đóng mọi connection và đặt trạng thái EXPIRED; trường hợp này không hoàn tiền.

POST/api/v1/user-proxies/bulk-delete
JWT
json
{"ids":["rental_id_1","rental_id_2"]}

Thống kê lưu lượng

GET/api/v1/usage?period=30d
JWT

Period hợp lệ: 7d, 30d hoặc 90d. Response gồm bandwidth, request, success rate và dữ liệu theo ngày.

Tra cứu thông tin IP

POST/api/v1/user-proxies/check-ip
JWT
json
{"ip":"8.8.8.8"}

Response gồm country, region, city, zipcode, ISP, ASN, timezone và phân loại residential/datacenter/mobile.

Tạo và cập nhật hồ sơ seller

POST/api/v1/seller/profile
JWT

Gọi endpoint này trước khi đăng proxy hoặc yêu cầu payout. Gọi lại cùng endpoint để cập nhật hồ sơ.

bash
curl -X POST "http://localhost:4001/api/v1/seller/profile" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Clean Proxy Store","payoutMethod":"USDT-TRC20","payoutAccount":"T..."}'
Không gửi password, token hoặc secret payout ngoài trường tài khoản nhận cần thiết.

Kiểm tra proxy trước khi đăng

POST/api/v1/seller/proxies/preview
JWT

Preview kiểm tra TCP, UDP, Exit IP, GeoIP, ISP/ASN và BrowserLeaks JA4T fingerprint nhưng không lưu listing.

bash
curl -X POST "http://localhost:4001/api/v1/seller/proxies/preview" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"proxyLine":"socks5://username:password@geo.example.com:10800"}'

Định dạng nhận: HOST:PORT:USER:PASS, USER:PASS@HOST:PORT, socks5:// và socks5h://. Hỗ trợ hostname, IPv4, IPv6 có ngoặc vuông và password chứa dấu hai chấm.

json
{
  "exitIp": "203.0.113.10",
  "countryCode": "US",
  "region": "California",
  "city": "Los Angeles",
  "isp": "Example ISP",
  "asn": "AS64500",
  "proxyType": "RESIDENTIAL",
  "deviceType": "WINDOWS",
  "osFingerprint": "WINDOWS",
  "osFingerprintConfidence": 0.98,
  "udpSupported": true,
  "latencyMs": 820
}
Proxy rotation, credential session-* tạm và Exit IP trùng listing đang chờ/đang bán sẽ bị từ chối.

Đăng proxy chờ admin duyệt

POST/api/v1/seller/proxies
JWT

Server luôn probe lại, không tin kết quả preview cũ. Metadata, thiết bị, vị trí và giá được server tự điền.

bash
curl -X POST "http://localhost:4001/api/v1/seller/proxies" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "proxyLine":"geo.example.com:10800:username:password",
    "pricingMode":"FIXED_TIME",
    "blockedDomains":["bank.example.com"],
    "blockedKeywords":["crypto"]
  }'
  • FIXED_TIME: một IP cố định tối đa 24 giờ, có giới hạn dung lượng do server cấu hình.
  • BANDWIDTH: tính theo số GB khách mua.
  • blockedDomains: chặn domain chính xác và subdomain.
  • blockedKeywords: chặn mọi hostname chứa từ khóa.

Response là listing trạng thái PENDING. Admin probe lại khi duyệt sang ACTIVE.

Đăng proxy hàng loạt chạy nền

POST/api/v1/seller/proxies/bulk
JWT · HTTP 202

Gửi tối đa 1.000 proxy. API chỉ validate payload, loại dòng trùng và enqueue Redis nên phản hồi nhanh; worker kiểm tra từng proxy độc lập.

bash
curl -X POST "http://localhost:4001/api/v1/seller/proxies/bulk" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "proxyLines":[
      "host1.example.com:1080:user1:pass1",
      "socks5://user2:pass2@host2.example.com:1080"
    ],
    "pricingMode":"FIXED_TIME",
    "blockedDomains":["bank.example.com"],
    "blockedKeywords":["crypto"]
  }'
json
{
  "jobId": "123",
  "state": "waiting",
  "accepted": 2,
  "duplicatesRemoved": 0
}
GET/api/v1/seller/proxy-jobs/{jobId}
JWT
GET/api/v1/seller/proxy-jobs
JWT

State: waiting, active, completed, failed hoặc delayed. Progress gồm processed, succeeded, failed và percent. Mỗi item lỗi có số dòng và message.

Credential proxy chỉ tồn tại trong Redis khi job đang chờ/chạy, sau đó bị redacted. Job và kết quả được giữ tối đa 24 giờ. Chỉ seller tạo job được xem.

Dashboard seller và payout

GET/api/v1/seller/dashboard
JWT

Response gồm profile, sellerSettings, listings, earnings và payouts. Giá bán và tỷ lệ chia do admin quản lý.

bash
curl "http://localhost:4001/api/v1/seller/dashboard" \
  -H "Authorization: Bearer ACCESS_TOKEN"
POST/api/v1/seller/payouts
JWT
bash
curl -X POST "http://localhost:4001/api/v1/seller/payouts" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount":10}'
Payout tối thiểu 10 USD và chỉ dùng số dư availableBalance. Yêu cầu mới có trạng thái PENDING để admin đối soát.

Swagger / OpenAPI đầy đủ

Swagger là nguồn tham chiếu đầy đủ cho mọi request field, response schema và nút Try it out.

Mở Swagger