Accueil / Documentation API

documentation API

Version v1 · pour revendeurs et développeurs

L'API permet de passer commande, de consulter les commandes et de récupérer les codes cadeaux par programme. Le montant de la commande est débité directement de votre solde, sans paiement commande par commande.

  1. Créer un compte, dans Espace membre Recharger le solde.
  2. Dans Espace membre → API Créez une clé pour obtenir AppID et Secret; nous vous conseillons aussi de définir une liste blanche d'IP.
  3. Appelez l'API selon la méthode de signature ci-dessous.
URL de l'APIhttps://vynqlo.com/api/open/v1
Format des donnéesRequêtes et réponses en JSON, encodage UTF-8
Unité de montantYuans, 2 décimales au maximum
Fréquence d'appel10 appels par seconde maximum par clé, au-delà de quoi est renvoyé 429

Méthode de signature

Chaque requête doit inclure les 4 en-têtes suivants :

En-têtesDescription
X-App-IdVotre AppID
X-TimestampTimestamp Unix actuel (en secondes), l'écart avec le serveur ne doit pas dépasser 300 secondes
X-NonceChaîne aléatoire de 16 à 32 caractères ; une même valeur ne peut pas être réutilisée pendant 10 minutes
X-SignSignature, méthode de calcul ci-dessous

Séparez les 5 éléments ci-dessous par des sauts de ligne \n Concaténez-les pour obtenir la chaîne à signer :

horodatage\nchaîne aléatoire\nméthode de requête (en majuscules)\nchemin de la requête (avec paramètres)\ncorps brut de la requête (chaîne vide pour une requête GET)

Utilisez à nouveau Secret Appliquez un HMAC-SHA256 et convertissez le résultat en hexadécimal minuscule : c'est la X-Sign。

Exemple Python

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

Liste des produits

GET /products — Renvoie tous les produits commandables, votre prix d'achat et le stock.

{ "code": 0, "data": [ { "sku": "apple.us.25", "name": "Carte cadeau Apple · États-Unis 25 $", "delivery": "code", // code = code cadeau / link = paiement par lien / username = recharge par nom d'utilisateur "price": 189.00, "stock": 167, // null pour le paiement par lien et la recharge par nom d'utilisateur, ce qui signifie illimité "fields": [] // champs supplémentaires à envoyer à la commande, voir « Créer une commande » } ] }

Consulter le solde

GET /balance

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

Créer une commande

POST /orders — Si le solde est suffisant, il est débité immédiatement et le traitement commence.

ParamètreObligatoireDescription
skuOuiCode produit, voir le « Tableau des codes produit » en fin de page
quantityNonQuantité, 1 par défaut. 10 maximum par commande pour les codes cadeaux, 1 uniquement pour les autres produits
out_trade_noOuiLe numéro de commande de votre propre système, 6 à 64 caractères alphanumériques. Une commande soumise deux fois avec le même numéro renvoie la commande existante, sans nouveau débit
account_emailObligatoire pour le paiement par lienE-mail du compte du client
checkout_urlObligatoire pour le paiement par lienLien de paiement officiel
usernameObligatoire pour la recharge par nom d'utilisateurPar ex. nom d'utilisateur Telegram @name

Exemple de requête :

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

Exemple de réponse :

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

Consulter une commande

GET /orders/{order_no}, ou GET /orders?out_trade_no=votre_numéro

{
  "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": ""
  }
}
statusSignification
processingDébité, en cours de traitement (5 à 30 minutes en général pour les paiements par lien et recharges par nom d'utilisateur)
deliveredCode cadeau livré, sur cards dans
completedPaiement ou recharge effectué
failedÉchec du traitement, le montant a été recrédité sur votre solde ; motif dans remark

Notifications de rappel

Dans l'espace membre, une fois l'URL de rappel définie, quand une commande passe à delivered、completed ou failed , nous POST les données de commande à cette adresse, avec le même contenu que ce que renvoie « Consulter une commande » data de la même façon.

  • Les notifications comportent aussi X-App-Id、X-Timestamp、X-Nonce、X-Sign, avec la même méthode de signature ; vérifiez la signature avant de traiter.
  • Une fois le traitement réussi, renvoyez HTTP 200 et le texte success. Sinon, nouvelles tentatives après 1, 5, 15 et 60 minutes, 4 au maximum.
  • Une même commande peut recevoir plusieurs notifications ; veuillez order_no en évitant les doublons.

Code d'erreur

codeDescription
0Réussi
1001Signature erronée ou en-têtes manquants
1002Horodatage hors de la plage autorisée
1003Chaîne aléatoire réutilisée
1004IP absente de la liste blanche
2001Code produit inexistant ou produit retiré
2002Stock insuffisant
2003Champ obligatoire manquant ou format de champ incorrect
3001Solde insuffisant
4001Commande introuvable
429Appels trop fréquents

Format renvoyé en cas d'erreur :{ "code": 3001, "message": "Solde insuffisant" }

Tableau des codes produit

Les prix sont les prix d'achat actuels, selon /products selon la réponse de l'API.

Code skuProduitsMode de livraisonPrix