Pular para o conteúdo

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 web

Assistentes de chat

Abrir no ChatGPTNovo separadorAbrir no ClaudeNovo separador

Copiar

Ver em MarkdownTexto simples para ferramentas de IA
Ver 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.

Não tem tempo para escrever o servidor? O conector do ProxyMarket é um servidor já pronto. Instale-o no seu servidor, dê-lhe um pequeno script que cria e apaga o acesso de um cliente no seu sistema (há scripts prontos em Python, Node.js e shell) e ele entrega todas as encomendas. Sem código, sem porta aberta, sem domínio.

Em resumo

Você chama o ProxyMarket

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.

O ProxyMarket chama-o a si

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.

Fica com 70%

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?

O seu servidormodems, proxies, VPN
ProxyMarketloja, pagamentos, suporte
Clienteliga-se ao seu proxy
O ProxyMarket vende. Você entrega as credenciais do proxy ou o ficheiro de configuração VPN, e o cliente liga-se depois diretamente ao seu servidor.

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.

  1. Crie uma conta normal em market.xproxy.ioVocê
  2. Candidate-se a vendedor (Become Vendor no menu superior)Você
  3. 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
  4. Entretanto, crie a sua verificação de estado e coloque o seu servidor de webhooks onlineVocê
  5. Crie a sua chave API no painel de vendedorVocê
  6. Publique os seus planos, trate as encomendas e verifique as assinaturas dos webhooksVocê
  7. 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 ativoConta 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.
python
@app.route("/health", methods=["HEAD", "GET"])
def health():
    return "", 200   # no login, no database, no outside call

Coloque-o sob o seu webhook URL: com https://your-vendor-host.com/marketplace, responde em /marketplace/health.

É a forma mais comum de uma loja que funciona deixar de vender sem aviso. Um deploy, um reinício ou uma firewall que bloqueia 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):

bash
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
A chave só é mostrada uma vez. O ProxyMarket guarda apenas um hash e não a pode devolver. Guarde-a de imediato. Se a perder, crie uma nova.

Dessa única chave obtém dois valores. Não os confunda:

ValorO que éPara que serve
api_keyA própria chave, a começar por pm_O cabeçalho X-API-Key de todas as chamadas que faz
signing_keySHA256(api_key) em hex de 64 caracteresVerificar 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.

Vai adicionar uma segunda chave? Os planos criados antes continuam a ir para a chave mais antiga. Defina o API Key / Server deles com a nova chave, ou desative a chave antiga. O 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.

bash
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 saberPorquê
Enviar de novo o mesmo external_id atualiza o planoA sincronização pode ser repetida sem risco; nunca cria duplicados.
Um plano que deixe de fora continua à vendaPara deixar de o vender, chame Retirar um plano de venda.
Use apenas mobile, residential, datacenter, isp, ipv6 ou vpn como proxy_typeA 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 StatesOs 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 estadoO stock é normalmente 1 por porta de modem: um cliente por porta.
protocol omitido significa HTTPEnvie-o mesmo assim nos planos VPN e SOCKS5.
Um plano criado por uma sincronização fica associado à chave que o sincronizouAs 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?

  1. O cliente paga. Os seus 70% são creditados no seu saldo de imediato, antes mesmo de o seu servidor ser chamado.
  2. O ProxyMarket chama POST {webhook_url}/provision com o order_id e o seu external_plan_id (payload). Verifique a assinatura e depois crie o acesso do cliente.
  3. Responde com as credenciais ou a configuração (o ideal), com pending ou com error. Veja a tabela abaixo.
  4. O cliente vê as credenciais no ProxyMarket e liga-se ao seu servidor. O ProxyMarket baixa sozinho o stock do plano em uma unidade.
  5. 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 respondeQuando o usarO que acontece
provisioned (o ideal)Consegue criar o acesso de imediatoO cliente recebe-o logo. Inclua os quatro: proxy_ip, proxy_port, proxy_username, proxy_password, ou vpn_config_file para VPN.
pendingA configuração demora algum tempoEnvie-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.
errorNã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.
Responda sempre HTTP 200, mesmo em caso de erro. Se /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.

python
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?

  1. A partir de fora da sua rede, execute curl -I https://your-vendor-host.com/marketplace/health e confirme que recebe um estado abaixo de 500 em 5 segundos.
  2. Sincronize um plano e encontre-o em Browse no market.xproxy.io.
  3. Faça uma encomenda real desse plano. O seu servidor deve receber /provision com uma assinatura válida, e as credenciais devem aparecer na encomenda do cliente.
  4. Ligue-se com essas credenciais, espere que a encomenda termine (ou peça no Telegram para a terminar) e confirme que /deprovision remove 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 ladoChamada
Um modem ou servidor fica offlinePATCH /plans/stock com stock: 0, is_active: false
Volta a ficar online, ou uma porta vendida fica livre de novoPATCH /plans/stock com stock: 1, is_active: true
Um preço, nome ou configuração mudaPOST /plans/sync só com esse plano
Deixa de vender um produtoDELETE /plans/{external_id}
Opcional, a cada poucos minutosPOST /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:

MotivoSignificado
expiredO tempo de aluguer terminou. Enviado automaticamente, com até 5 minutos de atraso.
renewedO cliente pagou para renovar uma encomenda em curso. A encomenda antiga termina agora e segue-se um novo /provision com um novo order_id.
cancelledUm administrador cancelou a encomenda.
admin_refundUm 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.

Esta chamada é enviada uma vez e nunca repetida. Se o seu servidor estiver em baixo nesse momento, o cliente mantém o acesso. Termine também cada encomenda com o seu próprio temporizador quando o tempo acabar (sabe a duração a partir de /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 (win1 Windows 11, mac1 macOS, ios1 iPhone 15, android1 Galaxy S24, entre outros). null desativa-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.

ProdutoCampos do planoO que entrega
OpenVPNproxy_type: "vpn", protocol: "OpenVPN", vpn_protocol: "openvpn"O texto .ovpn completo, com certificados e chaves incluídos
WireGuardproxy_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
Nunca envie 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_template ao sincronizar.
  • Um novo ficheiro por encomenda: crie-o em /provision e responda com vpn_config_file.
  • Um novo ficheiro que demora a criar: responda pending e depois envie vpn_config_file com 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 parte70% de cada venda (a taxa normal; pode ser acordada por vendedor)
Parte do ProxyMarket30%, pela loja, pagamentos, suporte e reembolsos
Quando é creditadaAssim 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
PagamentosPagos pelo administrador do ProxyMarket a partir do seu saldo. Peça no Telegram quando quiser levantar.
ReembolsosUm 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.
LevantamentosUm 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.

OndeO que decide a ordem
Browse, por predefiniçãoPrimeiro o grupo XProxy, depois o seu, cada um do mais barato para o mais caro
Browse, quando o cliente ordenaA 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 inicialO 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 lojaExatamente 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ódigoSignificadoO que fazer
401Invalid API key (chave errada ou desativada), Missing API key (cabeçalho vazio) ou Vendor inactiveVerifique o cabeçalho X-API-Key e se a chave está ativa no painel
403A 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
404external_id ou order_id desconhecidoVerifique o ID; sincronize primeiro o plano
409Entrega de credenciais a uma encomenda que já não está paga nem ativaNormalmente os 120 segundos passaram e a encomenda foi reembolsada. Não repita
422Um valor não é válido, ou falta por completo o cabeçalho X-API-KeyO detail da resposta indica o campo
500Erro do ProxyMarketRepita 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.

python
"""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.

SentidoEndpointO que faz
Você chamaPOST /api/vendor/integrationsCriar a sua chave API
Você chamaPOST /plans/syncPublicar ou atualizar planos
Você chamaPATCH /plans/stockAlterar stock e visibilidade
Você chamaDELETE /plans/{external_id}Retirar um plano de venda
Você chamaPOST /healthReportar o estado dos seus proxies
Você chamaPOST /orders/{order_id}/credentialsEntregar credenciais ou configuração mais tarde
Você chamaPOST /orders/{order_id}/expireMarcar uma encomenda como expirada (sem reembolso)
Nós chamamosHEAD /healthVerificação de estado que mantém os seus planos listados
Nós chamamosPOST /provisionUm cliente pagou: entregue
Nós chamamosPOST /deprovisionUma encomenda terminou: remova o acesso
Nós chamamosPOST /update-settingsAplicar uma nova whitelist de IPs ou impressão digital TCP
Você chamaGET /orders/activeAs 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, com routed_plans e 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: /provision só é enviado depois de o pagamento estar registado, por isso um envio imediato de credenciais é aceite. /update-settings leva 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 /provision com X-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_link com GET. 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, protocol por predefinição HTTP, um relatório /health sem current_ip apaga-o, a regra <ca> do OpenVPN e nenhum external_plan_id em /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.

Continua com dificuldades?Um técnico pode verificar o seu dispositivo com um PIN de utilização única, ou fale connosco no Telegram.