Início / Documentação da API

Documentação da API

Versão v1 · para agentes e desenvolvedores

Pela API você pode fazer pedidos, consultar pedidos e obter códigos por programa. O valor do pedido é debitado direto do saldo da conta, sem pagar pedido por pedido.

  1. Criar conta, em Área de membros Recarregue o saldo.
  2. Em Área de membros → API Crie uma chave para obter AppID e Secret, recomendamos configurar também a lista de IPs permitidos.
  3. Siga o método de assinatura abaixo para chamar a API.
Endereço da APIhttps://vynqlo.com/api/open/v1
Formato dos dadosRequisição e resposta em JSON, codificação UTF-8
Unidade do valorYuans (CNY), no máximo duas casas decimais
Limite de chamadasCada chave pode fazer no máximo 10 chamadas por segundo; acima disso retorna 429

Método de assinatura

Toda requisição deve levar os 4 cabeçalhos abaixo:

CabeçalhosDescrição
X-App-IdSeu AppID
X-TimestampTimestamp Unix atual (segundos); a diferença para o servidor não pode passar de 300 segundos
X-NonceString aleatória de 16–32 caracteres; o mesmo valor não pode ser reutilizado em 10 minutos
X-SignAssinatura, veja como calcular abaixo

Una os 5 itens abaixo com quebras de linha \n Una tudo para obter a string a ser assinada:

timestamp\nstring aleatória\nmétodo da requisição (maiúsculas)\ncaminho da requisição (com parâmetros de consulta)\ncorpo original da requisição (string vazia em GET)

Depois use Secret Aplique HMAC-SHA256 e converta o resultado em hexadecimal minúsculo, esse é o X-Sign。

Exemplo em Python

import hmac, hashlib, json, time, secrets, requests APP_ID = "vq_xxxxxxxxxxxxxxxx" SECRET = "seu Secret" BASE = "https://vynqlo.com/api/open/v1" def call(method, path, body=None): raw = json.dumps(body, ensure_ascii=False, separators=(",", ":")) if body else "" ts, nonce = str(int(time.time())), secrets.token_hex(8) msg = "\n".join([ts, nonce, method, "/api/open/v1" + path, raw]) sign = hmac.new(SECRET.encode(), msg.encode(), hashlib.sha256).hexdigest() headers = {"X-App-Id": APP_ID, "X-Timestamp": ts, "X-Nonce": nonce, "X-Sign": sign, "Content-Type": "application/json"} return requests.request(method, BASE + path, headers=headers, data=raw.encode() or None).json() print(call("GET", "/balance"))

Lista de produtos

GET /products — retorna todos os produtos disponíveis, seu preço de atacado e o estoque.

{ "code": 0, "data": [ { "sku": "apple.us.25", "name": "Gift card Apple · EUA US$ 25", "delivery": "code", // code = código / link = pagamento por link / username = recarga por usuário "price": 189.00, "stock": 167, // em produtos de pagamento por link e recarga por usuário é null, ou seja, sem limite "fields": [] // campos extras a enviar no pedido, veja “Criar pedido” } ] }

Consultar saldo

GET /balance

{ "code": 0, "data": { "balance": 2380.50 } }

Criar pedido

POST /orders — se o saldo for suficiente, o valor é debitado na hora e o pedido começa a ser processado.

ParâmetrosObrigatórioDescrição
skuSimCódigo do produto, veja a “Tabela de códigos de produtos” no final
quantityNãoQuantidade, padrão 1. Produtos com código: no máximo 10 por pedido; os demais, só 1
out_trade_noSimNúmero do pedido do seu próprio sistema, 6–64 caracteres alfanuméricos. Enviar o mesmo número de novo retorna o pedido existente, sem cobrar duas vezes
account_emailObrigatório no pagamento por linkE-mail da conta do cliente
checkout_urlObrigatório no pagamento por linkLink de checkout oficial
usernameObrigatório na recarga por usuárioPor exemplo, usuário do Telegram @name

Exemplo de requisição:

{ "sku": "chatgpt.plus.1m", "out_trade_no": "A20261119001",
  "account_email": "user@example.com",
  "checkout_url": "https://chatgpt.com/checkout/..." }

Exemplo de resposta:

{
  "code": 0,
  "data": {
    "order_no": "VQ2611190001",
    "out_trade_no": "A20261119001",
    "status": "processing",
    "amount": 169.00,
    "balance": 2211.50
  }
}

Consultar pedido

GET /orders/{order_no}, ou GET /orders?out_trade_no=seu_número_do_pedido

{
  "code": 0,
  "data": {
    "order_no": "VQ2611190002",
    "out_trade_no": "A20261119002",
    "sku": "apple.us.25",
    "quantity": 2,
    "amount": 378.00,
    "status": "delivered",
    "cards": ["XXXX-XXXX-XXXX-XXXX", "YYYY-YYYY-YYYY-YYYY"],
    "created_at": 1795060000,
    "finished_at": 1795060003,
    "remark": ""
  }
}
statusSignificado
processingValor debitado, em processamento (pagamentos por link e recargas por usuário costumam levar 5–30 minutos)
deliveredCódigo já enviado, em cards em
completedPagamento ou recarga concluído
failedFalha no processamento, o valor foi devolvido ao saldo, motivo em remark

Notificação de callback

Depois de definir a URL de callback na área de membros, quando o pedido passar para delivered、completed ou failed , nós POST os dados do pedido para este endereço, com o mesmo conteúdo que retorna a data igual.

  • A notificação também leva X-App-Id、X-Timestamp、X-Nonce、X-Sign, com o mesmo método de assinatura; valide a assinatura antes de processar.
  • Quando o processamento der certo, retorne HTTP 200 e o texto success. Caso contrário, tentamos de novo após 1, 5, 15 e 60 minutos, no máximo 4 vezes.
  • O mesmo pedido pode gerar várias notificações; trate de forma idempotente, conforme o order_no Sem duplicidade.

Códigos de erro

codeDescrição
0Sucesso
1001Assinatura inválida ou cabeçalhos ausentes
1002Timestamp fora do intervalo permitido
1003Nonce reutilizado
1004IP fora da lista de permissões
2001Código do produto inexistente ou produto retirado
2002Sem estoque
2003Campo obrigatório ausente ou formato de campo inválido
3001Saldo insuficiente
4001Pedido não encontrado
429Chamadas demais

Formato retornado em caso de erro:{ "code": 3001, "message": "Saldo insuficiente" }

Tabela de códigos de produtos

O preço é o de atacado atual, conforme /products vale o que a API retornar.

Código skuProdutoForma de entregaPreço