Documentação da API
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.
- Criar conta, em Área de membros Recarregue o saldo.
- Em Área de membros → API Crie uma chave para obter
AppIDeSecret, recomendamos configurar também a lista de IPs permitidos. - Siga o método de assinatura abaixo para chamar a API.
| Endereço da API | https://vynqlo.com/api/open/v1 |
| Formato dos dados | Requisição e resposta em JSON, codificação UTF-8 |
| Unidade do valor | Yuans (CNY), no máximo duas casas decimais |
| Limite de chamadas | Cada 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çalhos | Descrição |
|---|---|
X-App-Id | Seu AppID |
X-Timestamp | Timestamp Unix atual (segundos); a diferença para o servidor não pode passar de 300 segundos |
X-Nonce | String aleatória de 16–32 caracteres; o mesmo valor não pode ser reutilizado em 10 minutos |
X-Sign | Assinatura, 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âmetros | Obrigatório | Descrição |
|---|---|---|
sku | Sim | Código do produto, veja a “Tabela de códigos de produtos” no final |
quantity | Não | Quantidade, padrão 1. Produtos com código: no máximo 10 por pedido; os demais, só 1 |
out_trade_no | Sim | Nú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_email | Obrigatório no pagamento por link | E-mail da conta do cliente |
checkout_url | Obrigatório no pagamento por link | Link de checkout oficial |
username | Obrigatório na recarga por usuário | Por 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": ""
}
}
| status | Significado |
|---|---|
processing | Valor debitado, em processamento (pagamentos por link e recargas por usuário costumam levar 5–30 minutos) |
delivered | Código já enviado, em cards em |
completed | Pagamento ou recarga concluído |
failed | Falha 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_noSem duplicidade.
Códigos de erro
| code | Descrição |
|---|---|
0 | Sucesso |
1001 | Assinatura inválida ou cabeçalhos ausentes |
1002 | Timestamp fora do intervalo permitido |
1003 | Nonce reutilizado |
1004 | IP fora da lista de permissões |
2001 | Código do produto inexistente ou produto retirado |
2002 | Sem estoque |
2003 | Campo obrigatório ausente ou formato de campo inválido |
3001 | Saldo insuficiente |
4001 | Pedido não encontrado |
429 | Chamadas 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 sku | Produto | Forma de entrega | Preço |
|---|