Inicio / Documentación de la API

Documentación de la API

Versión v1 · Para agentes y desarrolladores

Con la API puedes hacer pedidos, consultarlos y obtener códigos por programa. El importe se descuenta directamente del saldo de la cuenta, sin pagar pedido por pedido.

  1. Crear cuenta, en Centro de miembros Recargar saldo.
  2. en Centro de miembros → API Crea una clave y obtendrás AppID y Secret; te recomendamos configurar también la lista blanca de IP.
  3. Llama a la API con el método de firma que se indica abajo.
Dirección de la APIhttps://vynqlo.com/api/open/v1
Formato de datosLa solicitud y la respuesta son JSON, con codificación UTF-8
Unidad del importeYuanes (RMB), máximo dos decimales
Límite de llamadasCada clave admite como máximo 10 llamadas por segundo; si te pasas, devuelve 429

Método de firma

Cada solicitud debe llevar estas 4 cabeceras:

CabecerasDescripción
X-App-IdTu AppID
X-TimestampMarca de tiempo Unix actual (segundos); no puede diferir más de 300 segundos del servidor
X-NonceCadena aleatoria de 16–32 caracteres; el mismo valor no se puede repetir en 10 minutos
X-SignFirma, cómo se calcula abajo

Une estos 5 elementos con saltos de línea \n únelos y obtendrás la cadena a firmar:

marca de tiempo\nstring aleatorio\nmétodo de la solicitud (en mayúsculas)\nruta de la solicitud (con parámetros de consulta)\ncuerpo original de la solicitud (cadena vacía en solicitudes GET)

Vuelve a usar Secret haz HMAC-SHA256 y convierte el resultado a hexadecimal en minúsculas; eso es X-Sign。

Ejemplo en Python

import hmac, hashlib, json, time, secrets, requests APP_ID = "vq_xxxxxxxxxxxxxxxx" SECRET = "tu 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 productos

GET /products — Devuelve todos los productos disponibles, tu precio de mayorista y el stock.

{ "code": 0, "data": [ { "sku": "apple.us.25", "name": "Tarjeta de regalo de Apple · EE. UU. $25", "delivery": "code", // code código / link pago por enlace / username recarga por usuario "price": 189.00, "stock": 167, // para pago por enlace y recarga por usuario es null, es decir, sin límite "fields": [] // campos adicionales al hacer el pedido, ver "Crear pedido" } ] }

Consultar saldo

GET /balance

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

Crear pedido

POST /orders — Si el saldo alcanza, se cobra al instante y empezamos a procesarlo.

ParámetroObligatorioDescripción
skuSíCódigo de producto, ver "Tabla de códigos de producto" al final
quantityNoCantidad, 1 por defecto. Las tarjetas admiten hasta 10 por pedido; los demás productos, solo 1
out_trade_noSíTu propio número de pedido, de 6 a 64 caracteres alfanuméricos. Si envías el mismo número otra vez, se devuelve el pedido existente sin cobrar de nuevo
account_emailObligatorio en pago por enlaceCorreo de la cuenta del cliente
checkout_urlObligatorio en pago por enlaceEnlace de pago oficial
usernameObligatorio en recarga por usuarioPor ejemplo, un usuario de Telegram @name

Ejemplo de solicitud:

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

Ejemplo de respuesta:

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

Consultar pedido

GET /orders/{order_no}, o GET /orders?out_trade_no=tu_número_de_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
processingCobrado, en proceso (los pedidos de pago por enlace y recarga suelen tardar 5–30 minutos)
deliveredCódigo entregado, en cards en
completedPago por enlace o recarga completados
failedFalló el procesamiento, el importe se devolvió al saldo; el motivo está en remark

Notificaciones de callback

Una vez que configures la URL de callback en el Centro de miembros, cuando el pedido pase a delivered、completed o failed , nosotros POST los datos del pedido a esta dirección; el contenido es igual al que devuelve "Consultar pedido" data igual.

  • Las notificaciones también llevan X-App-Id、X-Timestamp、X-Nonce、X-Sign; el método de firma es el mismo, verifica la firma antes de procesar.
  • Cuando se procese correctamente, responde con HTTP 200 y el texto success. Si no, se reintenta a los 1, 5, 15 y 60 minutos, hasta 4 veces.
  • Un mismo pedido puede recibir varias notificaciones; por favor order_no sin duplicados.

Códigos de error

codeDescripción
0Éxito
1001Firma incorrecta o faltan cabeceras
1002Marca de tiempo fuera del rango permitido
1003Cadena aleatoria repetida
1004La IP no está en la lista blanca
2001El código de producto no existe o ya no está disponible
2002Sin stock suficiente
2003Faltan campos obligatorios o su formato no es correcto
3001Saldo insuficiente
4001El pedido no existe
429Demasiadas llamadas

Formato de respuesta en caso de error:{ "code": 3001, "message": "Saldo insuficiente" }

Tabla de códigos de producto

El precio es el de mayorista actual, según /products lo que devuelva la API.

Código skuProductoForma de entregaPrecio