Integração de vendedor no ProxyMarket: venda os seus próprios proxies
Perguntar à IA
Tarefa prontaCriar a integração com o ProxyMarket no seu código
Agentes de programação
Claude CodeAbre a aplicação de computadorCodexAbre a aplicação de computadorCursorAbre a aplicação na webAssistentes de chat
Abrir no ChatGPTNovo separadorAbrir no ClaudeNovo separadorCopiar
Ver em MarkdownTexto simples para ferramentas de IAVer o prompt
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 Portuguese: https://xproxy.io/pt/document/proxymarket-vendor-integration. The Markdown copy is in English. Answer in Portuguese.
A aplicação abre com o prompt preenchido. Nada é executado até premir Enter.
Venda os seus próprios proxies ou VPN no ProxyMarket (market.xproxy.io). Continua a gerir os seus servidores. O ProxyMarket gere a loja, recebe os pagamentos e responde aos clientes. Um pequeno conector do seu lado liga os dois: faz algumas chamadas ao ProxyMarket e responde a quatro webhooks.
Precisa de: uma conta de vendedor aprovada em market.xproxy.io, um servidor que o ProxyMarket consiga alcançar por HTTPS com um certificado válido e alguém capaz de escrever um pequeno serviço web. Todos os endpoints, campos e respostas estão também na referência da API do ProxyMarket.
Em resumo
Envie os seus planos, mantenha o stock e o estado dos proxies atualizados e entregue um acesso mais tarde, se precisar. Todas as chamadas levam a sua X-API-Key.
Uma verificação de estado a cada 10 minutos e depois um webhook quando um cliente paga, quando uma encomenda termina e quando um cliente altera uma definição.
A sua parte de cada venda é creditada assim que o pagamento é confirmado. O ProxyMarket fica com 30% pela loja, pagamentos, suporte e reembolsos.
Como funciona?
Quais são os passos para começar a vender?
Siga-os por esta ordem. Os passos 1 a 3 configuram a sua conta; os passos 4 a 7 são a integração.
- Crie uma conta normal em market.xproxy.ioVocê
- Candidate-se a vendedor (Become Vendor no menu superior)Você
- Aprovação, normalmente em 24 horas. Até lá, o menu superior mostra Vendor Pending…; envie uma mensagem a @xproxyio com o e-mail da sua conta para acelerarProxyMarket
- Entretanto, crie a sua verificação de estado e coloque o seu servidor de webhooks onlineVocê
- Crie a sua chave API no painel de vendedorVocê
- Publique os seus planos, trate as encomendas e verifique as assinaturas dos webhooksVocê
- Faça uma encomenda de teste real e confirme que o cliente recebe um proxy a funcionarVocê + ProxyMarket
Porque criar primeiro a verificação de estado?
O ProxyMarket verifica o seu servidor com HEAD {webhook_url}/health. É o único endpoint que decide se os seus planos continuam à venda:
- Quando cria a sua chave, o ProxyMarket chama-o uma vez. Um 5xx, uma ligação recusada ou mais de 5 segundos: não há chave (HTTP 422 com o motivo).
- Depois disso, a cada 10 minutos, enquanto a chave tiver planos à venda, chama-o de novo. Após 2 falhas seguidas, todos os planos servidos por essa chave ficam ocultos na loja e não podem ser comprados. Uma única resposta correta repõe-nos todos sozinha.
| Conta como ativo | Conta como em baixo |
|---|---|
| Qualquer estado abaixo de 500, em 5 segundos. Sem autenticação nem corpo. | Um tempo esgotado, uma ligação recusada ou qualquer estado 5xx. |
@app.route("/health", methods=["HEAD", "GET"])
def health():
return "", 200 # no login, no database, no outside callColoque-o sob o seu webhook URL: com https://your-vendor-host.com/marketplace, responde em /marketplace/health.
HEAD pode esvaziar todo o seu catálogo em cerca de 20 minutos. Faça de /health a rota mais simples que tem: sem autenticação, sem base de dados, sem chamadas externas, e responda também a GET. Não a confunda com Reportar o estado dos seus proxies (POST /api/integration/health). Essa é uma chamada que você faz sobre proxies individuais; não mantém os seus planos listados.
Como obtenho a minha chave API?
Cria-a você mesmo assim que a sua candidatura de vendedor for aprovada; ninguém lha envia. No painel de vendedor, dê um nome à chave e indique o seu webhook URL, por exemplo https://your-vendor-host.com/marketplace. Também o pode fazer com uma chamada (referência):
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 nowDessa única chave obtém dois valores. Não os confunda:
| Valor | O que é | Para que serve |
|---|---|---|
api_key | A própria chave, a começar por pm_ | O cabeçalho X-API-Key de todas as chamadas que faz |
signing_key | SHA256(api_key) em hex de 64 caracteres | Verificar a X-Signature de cada webhook (como) |
A chave nunca expira e o seu webhook URL não pode ser alterado depois: para mudar de servidor, crie uma nova chave. Se gere vários servidores independentes, dê a cada um a sua própria chave. As encomendas vão para a chave definida em API Key / Server de cada plano, no painel de vendedor. Um plano criado por uma sincronização fica com a chave que o sincronizou; um plano mais antigo sem essa definição envia as encomendas para a sua chave ativa mais antiga.
pm-connector test avisa quando um plano vai para outro lado. Erros: uma chamada sem o cabeçalho X-API-Key recebe 422, uma chave errada 401 e uma chave cuja candidatura de vendedor ainda está pendente 403. O separador Integration Status do painel de vendedor mostra, por chave, quando foi vista pela última vez, a versão do conector e as últimas 20 entregas com o respetivo resultado.
Como publico os meus planos?
Envie todos os seus produtos com Publicar ou atualizar os seus planos quando o seu conector arranca e de novo sempre que algo muda. Os planos sincronizados são aprovados de imediato (os planos que adiciona manualmente no painel aguardam um administrador). O seu external_id é o seu próprio ID do produto (uma porta, um modem, um conjunto VPN), e todas as chamadas e webhooks seguintes o usam.
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"}]}| A saber | Porquê |
|---|---|
Enviar de novo o mesmo external_id atualiza o plano | A sincronização pode ser repetida sem risco; nunca cria duplicados. |
| Um plano que deixe de fora continua à venda | Para deixar de o vender, chame Retirar um plano de venda. |
Use apenas mobile, residential, datacenter, isp, ipv6 ou vpn como proxy_type | A API aceita qualquer texto, mas outro valor estraga a encomenda: o cliente nunca recebe as credenciais. Consulte VPN e VLESS. |
country é o nome completo em inglês, por exemplo United States | Os clientes filtram pelo texto exato, por isso escreva-o da mesma forma em todos os planos (mais). O ProxyMarket não o verifica. |
| Um plano só é mostrado quando está ativo, com stock, listado e não ocultado pela verificação de estado | O stock é normalmente 1 por porta de modem: um cliente por porta. |
protocol omitido significa HTTP | Envie-o mesmo assim nos planos VPN e SOCKS5. |
| Um plano criado por uma sincronização fica associado à chave que o sincronizou | As suas encomendas vão para essa chave. Uma sincronização nunca altera a chave de um plano que já existe (mais). |
O que acontece quando alguém compra?
- O cliente paga. Os seus 70% são creditados no seu saldo de imediato, antes mesmo de o seu servidor ser chamado.
- O ProxyMarket chama
POST {webhook_url}/provisioncom oorder_ide o seuexternal_plan_id(payload). Verifique a assinatura e depois crie o acesso do cliente. - Responde com as credenciais ou a configuração (o ideal), com
pendingou comerror. Veja a tabela abaixo. - O cliente vê as credenciais no ProxyMarket e liga-se ao seu servidor. O ProxyMarket baixa sozinho o stock do plano em uma unidade.
- Quando o tempo acaba, o ProxyMarket termina a encomenda sozinho (verifica a cada 5 minutos) e chama
POST {webhook_url}/deprovision. Remove o acesso e volta a pôr a unidade à venda. Consulte Quando uma encomenda termina.
status com que responde | Quando o usar | O que acontece |
|---|---|---|
provisioned (o ideal) | Consegue criar o acesso de imediato | O cliente recebe-o logo. Inclua os quatro: proxy_ip, proxy_port, proxy_username, proxy_password, ou vpn_config_file para VPN. |
pending | A configuração demora algum tempo | Envie-o com Entregar as credenciais do proxy ou a configuração VPN. O ProxyMarket espera 120 segundos no total, contados desde o início; depois disso, a encomenda é reembolsada e uma entrega tardia recebe 409. |
error | Não consegue entregar (porta offline, sem perfil livre) | Nada é entregue. Após os 120 segundos, o cliente é reembolsado na carteira e o seu ganho é removido. |
/provision responder com outro estado, esgotar o tempo (após 30 segundos), devolver JSON inválido ou disser provisioned com credenciais incompletas, o ProxyMarket entrega ao cliente as credenciais que sincronizou no plano, se existirem. Umas credenciais entregues nunca são copiadas para o plano, e as credenciais de um plano que já pertençam a outra encomenda não são reutilizadas: essa encomenda é reembolsada. A chamada não é repetida. O expires_at da sua resposta é ignorado: o ProxyMarket conta o tempo a partir da ativação e indica-lho em /deprovision.
Posso encriptar a resposta num URL http:// simples?
Sim, opcionalmente. Responda 200 com os cabeçalhos X-PM-Encrypted: v1 e X-PM-Signature: sha256= + o HMAC-SHA256 em hex do corpo em bruto com a sua signing key como chave, e o corpo {"enc": "v1", "nonce": "…", "ct": "…"}: um nonce aleatório de 12 bytes e o texto cifrado AES-256-GCM da sua resposta normal (com a tag no fim), ambos em base64 padrão. A chave é HKDF-SHA256 sobre os bytes UTF-8 da sua signing key (salt vazio, info pm-provision-v1, 32 bytes), e o AAD é o order_id. O ProxyMarket verifica a assinatura, desencripta e lê a resposta como habitualmente; um envelope inválido conta como tempo esgotado. O formato completo e um vetor de teste estão na referência da API e na secção 5.1 do guia. O pm-connector faz isto sozinho num URL http://. O HTTPS continua a ser recomendado, porque os pedidos de webhook não são encriptados.
Guarde o order_id: precisa dele para entregar mais tarde, para terminar a encomenda você mesmo e para associar os outros webhooks.
Como verifico que um webhook vem mesmo do ProxyMarket?
Cada POST de webhook leva X-Signature: sha256=…, um HMAC-SHA256 do corpo em bruto. O segredo é a sua signing key, SHA256(api_key) em hex, e não a própria chave API. Verifique-a em /provision, /deprovision e /update-settings antes de fazer qualquer outra coisa.
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()
...Use o corpo do pedido em bruto. Analisar o JSON e voltar a gerá-lo altera os bytes, e a assinatura deixa de corresponder.
Como testo antes de os clientes comprarem?
- A partir de fora da sua rede, execute
curl -I https://your-vendor-host.com/marketplace/healthe confirme que recebe um estado abaixo de 500 em 5 segundos. - Sincronize um plano e encontre-o em Browse no market.xproxy.io.
- Faça uma encomenda real desse plano. O seu servidor deve receber
/provisioncom uma assinatura válida, e as credenciais devem aparecer na encomenda do cliente. - Ligue-se com essas credenciais, espere que a encomenda termine (ou peça no Telegram para a terminar) e confirme que
/deprovisionremove o acesso e que o stock volta.
Avise o ProxyMarket no Telegram @xproxyio quando fizer a encomenda de teste, para que também possa ser verificada do lado deles.
Como mantenho o stock e o estado atualizados?
| Quando isto acontece do seu lado | Chamada |
|---|---|
| Um modem ou servidor fica offline | PATCH /plans/stock com stock: 0, is_active: false |
| Volta a ficar online, ou uma porta vendida fica livre de novo | PATCH /plans/stock com stock: 1, is_active: true |
| Um preço, nome ou configuração muda | POST /plans/sync só com esse plano |
| Deixa de vender um produto | DELETE /plans/{external_id} |
| Opcional, a cada poucos minutos | POST /health com o estado e o IP atual de cada proxy. Inclua sempre current_ip: omiti-lo apaga o IP guardado. Não mantém os seus planos listados; isso cabe à verificação de estado do seu servidor. |
Todos os caminhos começam por https://market.xproxy.io/api/integration.
O que acontece quando uma encomenda termina?
O ProxyMarket chama POST {webhook_url}/deprovision com um reason:
| Motivo | Significado |
|---|---|
expired | O tempo de aluguer terminou. Enviado automaticamente, com até 5 minutos de atraso. |
renewed | O cliente pagou para renovar uma encomenda em curso. A encomenda antiga termina agora e segue-se um novo /provision com um novo order_id. |
cancelled | Um administrador cancelou a encomenda. |
admin_refund | Um administrador reembolsou o cliente. O seu ganho correspondente é retirado. |
Remova as credenciais do cliente (ou desative o perfil VPN). Depois envie o seu número real de unidades livres com PATCH /plans/stock: o ProxyMarket repõe o stock sozinho após um reembolso, mas não após uma expiração. Responda {"status": "deprovisioned"}; a resposta é apenas registada.
/provision). Uma encomenda cujo aprovisionamento falhou e foi reembolsada automaticamente não recebe /deprovision. Marcar uma encomenda como expirada só altera o seu estado no ProxyMarket, em qualquer situação, mesmo cancelada. Não reembolsa o cliente, não altera o stock nem chama o seu webhook.
E se um cliente alterar a whitelist de IPs ou a impressão digital TCP?
Quando um cliente guarda Proxy Settings numa encomenda ativa, o ProxyMarket chama POST {webhook_url}/update-settings. É enviado uma vez, para qualquer tipo de encomenda. Aplique o que o seu sistema suporta e responda {"status": "ok"}; pode ignorar um campo que não suporta. O corpo não tem external_plan_id, por isso encontre o plano a partir do order_id que guardou no aprovisionamento.
ip_whitelist: só estes IPs podem usar o proxy. Sempre uma lista de endereços individuais;[]significa sem limite de IPs.tcp_fingerprint: com que sistema operativo a ligação deve parecer (win1Windows 11,mac1macOS,ios1iPhone 15,android1Galaxy S24, entre outros).nulldesativa-a.
Como vendo VPN e VLESS?
O fluxo da encomenda é o mesmo; só muda o que entrega. Envie o ficheiro de cliente completo, exatamente como o cliente o deve importar.
| Produto | Campos do plano | O que entrega |
|---|---|---|
| OpenVPN | proxy_type: "vpn", protocol: "OpenVPN", vpn_protocol: "openvpn" | O texto .ovpn completo, com certificados e chaves incluídos |
| WireGuard | proxy_type: "vpn", protocol: "WireGuard", vpn_protocol: "wireguard" | O .conf completo com [Interface] e [Peer] |
| VLESS (Xray) | proxy_type: "vpn", protocol: "VLESS", vpn_protocol: "vless" | Uma ligação vless:// numa só linha, ou o JSON de cliente Xray completo |
proxy_type: "xray". A loja mostra os planos VLESS como “Xray”, mas esse rótulo vem de vpn_protocol. A API aceita xray, mas isso estraga o plano: o cliente paga e a configuração nunca chega. Três formas de entregar o ficheiro:
- O mesmo ficheiro para todos os clientes do plano: coloque-o em
vpn_config_templateao sincronizar. - Um novo ficheiro por encomenda: crie-o em
/provisione responda comvpn_config_file. - Um novo ficheiro que demora a criar: responda
pendinge depois envievpn_config_filecom Entregar as credenciais do proxy ou a configuração VPN.
Para VLESS, dê a cada encomenda o seu próprio UUID (partilhar um significa que revogar um cliente revoga todos), indique o transporte na descrição do plano (por exemplo XTLS-Reality ou WS+TLS) e remova o UUID do seu inbound quando a encomenda terminar.
Um ficheiro OpenVPN tem de conter remote, dev tun ou dev tap, ou então client e um bloco <ca>; um bloco <ca> sozinho é rejeitado. Todas as configurações precisam de pelo menos 50 caracteres.
Como funciona a rotação de IP?
O rotation_link que entrega é um URL que o próprio ProxyMarket chama, com um GET simples (segue redirecionamentos, não verifica o certificado, tempo limite de 15 segundos). Fá-lo quando o cliente clica em Rotate e no temporizador de rotação automática que o cliente escolhe (a cada 5 a 60 minutos), e para quando a encomenda termina. O cliente também vê a ligação e pode abri-la.
Se o rotation_link do próprio plano for entregue como alternativa (veja acima), nunca é um que já pertença a outra encomenda.
Existe um servidor de webhooks já pronto?
Sim: o conector do ProxyMarket (pm-connector) corre no seu servidor Linux ou Windows e faz por si tudo o que está nesta página. Só tem de lhe dar um pequeno script que cria e apaga o acesso de um cliente no seu sistema; há scripts prontos em Python, Node.js e shell na página dele.
- Responde aos webhooks com verificação de assinatura, cria o nome de utilizador e a palavra-passe do cliente no seu sistema e apaga-os quando o aluguer termina.
- Chega ao ProxyMarket através do ProxyMarket hook (tipo de chave ProxyMarket hook): uma ligação de saída para
market-hook-service.xproxy.io, por isso o servidor não precisa de porta aberta nem de domínio. Os clientes ligam-se sempre diretamente à porta do seu proxy. - Recupera após uma paragem: as encomendas que terminaram enquanto estava offline perdem o utilizador assim que volta.
Os planos são criados no Vendor Dashboard. Se quiser que o ProxyMarket chame o seu próprio endereço HTTPS em vez do hook, consulte usar o seu próprio endereço.
Como sou pago?
| A sua parte | 70% de cada venda (a taxa normal; pode ser acordada por vendedor) |
|---|---|
| Parte do ProxyMarket | 30%, pela loja, pagamentos, suporte e reembolsos |
| Quando é creditada | Assim que o pagamento do cliente é confirmado e a encomenda fica ativa, antes de o seu /provision ser chamado |
| Onde a vê | Earnings no seu painel de vendedor: cada venda com o valor, o seu montante e a taxa aplicada |
| Pagamentos | Pagos pelo administrador do ProxyMarket a partir do seu saldo. Peça no Telegram quando quiser levantar. |
| Reembolsos | Um reembolso automático (nada entregue em 120 segundos) ou um reembolso feito por um administrador retira o ganho do seu saldo. Um código promocional baixa o valor da venda e, com ele, a sua parte. |
| Levantamentos | Um pagamento pode ir até ao seu saldo e marca como pagos os seus ganhos por pagar mais antigos. |
A taxa é guardada com cada venda, por isso uma alteração posterior da taxa nunca afeta o dinheiro que já ganhou.
Onde aparecem os meus planos na loja?
Browse lista os planos do mais barato para o mais caro, com uma regra a conhecer antes de definir preços: os planos de vendedores que usam o software XProxy aparecem primeiro, em Powered by xProxy, com um selo xProxy. Os planos do seu próprio conector vêm a seguir, em Other vendors, também do mais barato para o mais caro.
| Onde | O que decide a ordem |
|---|---|
| Browse, por predefinição | Primeiro o grupo XProxy, depois o seu, cada um do mais barato para o mais caro |
| Browse, quando o cliente ordena | A ordenação aplica-se dentro de cada grupo, por isso um plano seu mais barato continua abaixo do grupo XProxy |
| Cartões “from $X” da página inicial | O plano XProxy mais barato de cada categoria; os seus só quando a XProxy não tem stock nessa categoria |
| Filtros de país, protocolo e pesquisa, a sua página de loja | Exatamente iguais para todos os vendedores |
Quando tudo o que está listado pertence a um só grupo, Browse mostra uma lista única sem títulos. A maioria dos clientes chega filtrando por país ou protocolo, e aí os seus planos aparecem ao lado dos de todos os outros.
O que significam os códigos de erro?
| Código | Significado | O que fazer |
|---|---|---|
401 | Invalid API key (chave errada ou desativada), Missing API key (cabeçalho vazio) ou Vendor inactive | Verifique o cabeçalho X-API-Key e se a chave está ativa no painel |
403 | A sua candidatura de vendedor ainda está pendente (em qualquer chamada), ou a conta não é um vendedor aprovado (criação de chave) | Aguarde a aprovação |
404 | external_id ou order_id desconhecido | Verifique o ID; sincronize primeiro o plano |
409 | Entrega de credenciais a uma encomenda que já não está paga nem ativa | Normalmente os 120 segundos passaram e a encomenda foi reembolsada. Não repita |
422 | Um valor não é válido, ou falta por completo o cabeçalho X-API-Key | O detail da resposta indica o campo |
500 | Erro do ProxyMarket | Repita com um intervalo crescente |
Os erros chegam como {"detail": "…"}. Não há limites de pedidos publicados; sincronize quando algo muda e não num ciclo apertado.
Existe um exemplo completo?
Sim. Este conector em Python sincroniza um plano de proxy, reporta o estado a cada 5 minutos e responde aos quatro webhooks. Substitua as duas funções do topo por chamadas ao seu próprio sistema e acrescente um temporizador que termina cada encomenda quando o tempo acaba.
"""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)Onde está a referência completa da API?
Todas as chamadas e webhooks, com todos os campos, respostas de exemplo e código em curl, Python, Node.js e PHP, estão na referência da API do ProxyMarket. O ficheiro OpenAPI 3.1 está em market.openapi.yaml.
| Sentido | Endpoint | O que faz |
|---|---|---|
| Você chama | POST /api/vendor/integrations | Criar a sua chave API |
| Você chama | POST /plans/sync | Publicar ou atualizar planos |
| Você chama | PATCH /plans/stock | Alterar stock e visibilidade |
| Você chama | DELETE /plans/{external_id} | Retirar um plano de venda |
| Você chama | POST /health | Reportar o estado dos seus proxies |
| Você chama | POST /orders/{order_id}/credentials | Entregar credenciais ou configuração mais tarde |
| Você chama | POST /orders/{order_id}/expire | Marcar uma encomenda como expirada (sem reembolso) |
| Nós chamamos | HEAD /health | Verificação de estado que mantém os seus planos listados |
| Nós chamamos | POST /provision | Um cliente pagou: entregue |
| Nós chamamos | POST /deprovision | Uma encomenda terminou: remova o acesso |
| Nós chamamos | POST /update-settings | Aplicar uma nova whitelist de IPs ou impressão digital TCP |
| Você chama | GET /orders/active | As encomendas pagas e ativas encaminhadas para a sua chave |
Que países posso listar?
Qualquer um. Envie o nome completo do país em inglês, por exemplo United States, Germany ou Vietnam, e escreva-o da mesma forma em todos os planos: os clientes filtram pelo texto exato. O ProxyMarket não verifica o nome; a lista no guia e no painel de vendedor é a grafia a usar. O pm-connector test rejeita um nome que não esteja nessa lista.
O que mudou na versão 1.13?
- Nova chamada: Listar as encomendas encaminhadas para a sua chave (
GET /orders/active, comrouted_planse ETag), para recuperar após uma paragem. - Alternativa mais segura: umas credenciais entregues já não são copiadas para o plano, e as credenciais ou a ligação de rotação de um plano que pertençam a outra encomenda nunca são entregues.
- Momento do aprovisionamento:
/provisionsó é enviado depois de o pagamento estar registado, por isso um envio imediato de credenciais é aceite./update-settingsleva sempre os valores que o cliente acabou de guardar. - Conector do ProxyMarket: um servidor de webhooks já pronto, incluindo como chegar a ele atrás de NAT. Consulte o conector.
- Resposta de aprovisionamento encriptada (opcional): num webhook URL
http://simples, sele a sua resposta a/provisioncomX-PM-Encrypted: v1. Consulte acima. - Associação de planos: um plano criado por uma sincronização vai para a chave que o sincronizou.
- Rotação: o ProxyMarket chama o seu
rotation_linkcomGET. Consulte Rotação de IP. - Separador Integration Status no painel de vendedor e o cabeçalho opcional
X-PM-Connector. - Documentado de acordo com o código: 422 sem cabeçalho
X-API-Key, 403 enquanto a candidatura está pendente, tempo limite de aprovisionamento de 30 segundos, país e porta de sincronização não validados,protocolpor predefinição HTTP, um relatório/healthsemcurrent_ipapaga-o, a regra<ca>do OpenVPN e nenhumexternal_plan_idem/update-settings.
Perguntas frequentes
Uso a XProxy. Preciso de criar isto?
Não. Ative o ProxyMarket no painel (Selling Platform → ProxyMarket) e ele faz tudo isto por si, incluindo os webhooks. Consulte Vender no ProxyMarket. Os seus planos recebem também o selo xProxy.
Porque desapareceram todos os meus planos da loja?
Quase sempre por causa da verificação de estado: HEAD {webhook_url}/health falhou duas vezes seguidas (em baixo, mais lento do que 5 segundos, um 5xx ou HEAD bloqueado). Corrija-a e os planos voltam após a verificação correta seguinte, em 10 minutos.
Perdi a minha chave API. O ProxyMarket pode enviá-la de novo?
Não. Só é guardado um hash. Crie uma nova chave e lembre-se de que a signing key muda com ela.
A verificação da assinatura falha sempre. Porquê?
Normalmente por um de dois motivos: usou a chave API em bruto como segredo do HMAC em vez de SHA256(api_key) em hex, ou assinou o JSON depois de o analisar e voltar a codificar, em vez do corpo do pedido em bruto.
Recebo se o meu servidor não conseguir entregar?
Não. Se nada utilizável chegar em 120 segundos, o cliente é reembolsado e o ganho é retirado do seu saldo.
Porque recebeu um cliente credenciais antigas?
O seu /provision respondeu com um estado diferente de 200, esgotou o tempo ou enviou JSON inválido, por isso o ProxyMarket entregou as credenciais que sincronizou no plano. Umas credenciais entregues nunca são guardadas no plano, e as credenciais do plano não são reutilizadas quando já pertencem a outra encomenda (nesse caso, essa encomenda é reembolsada). Responda sempre 200, com error se não conseguir entregar.
Posso ligar vários servidores?
Sim. Crie uma chave por servidor, cada uma com o seu próprio webhook URL. Um plano criado por uma sincronização vai para a chave que o sincronizou; nos planos mais antigos, defina API Key / Server no painel, ou as encomendas vão para a sua chave mais antiga.
O que acontece quando um cliente renova?
Renovar uma encomenda expirada é uma nova encomenda normal. Renovar uma em curso envia primeiro /deprovision com reason: renewed para a encomenda antiga e depois /provision para a nova, com um novo order_id.
E agora?
Abra a referência completa, ou fale com o ProxyMarket no Telegram.

