documentation API
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.
- Créer un compte, dans Espace membre Recharger le solde.
- Dans Espace membre → API Créez une clé pour obtenir
AppIDetSecret; nous vous conseillons aussi de définir une liste blanche d'IP. - Appelez l'API selon la méthode de signature ci-dessous.
| URL de l'API | https://vynqlo.com/api/open/v1 |
| Format des données | Requêtes et réponses en JSON, encodage UTF-8 |
| Unité de montant | Yuans, 2 décimales au maximum |
| Fréquence d'appel | 10 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êtes | Description |
|---|---|
X-App-Id | Votre AppID |
X-Timestamp | Timestamp Unix actuel (en secondes), l'écart avec le serveur ne doit pas dépasser 300 secondes |
X-Nonce | Chaîne aléatoire de 16 à 32 caractères ; une même valeur ne peut pas être réutilisée pendant 10 minutes |
X-Sign | Signature, 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ètre | Obligatoire | Description |
|---|---|---|
sku | Oui | Code produit, voir le « Tableau des codes produit » en fin de page |
quantity | Non | Quantité, 1 par défaut. 10 maximum par commande pour les codes cadeaux, 1 uniquement pour les autres produits |
out_trade_no | Oui | Le 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_email | Obligatoire pour le paiement par lien | E-mail du compte du client |
checkout_url | Obligatoire pour le paiement par lien | Lien de paiement officiel |
username | Obligatoire pour la recharge par nom d'utilisateur | Par 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": ""
}
}
| status | Signification |
|---|---|
processing | Débité, en cours de traitement (5 à 30 minutes en général pour les paiements par lien et recharges par nom d'utilisateur) |
delivered | Code cadeau livré, sur cards dans |
completed | Paiement 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_noen évitant les doublons.
Code d'erreur
| code | Description |
|---|---|
0 | Réussi |
1001 | Signature erronée ou en-têtes manquants |
1002 | Horodatage hors de la plage autorisée |
1003 | Chaîne aléatoire réutilisée |
1004 | IP absente de la liste blanche |
2001 | Code produit inexistant ou produit retiré |
2002 | Stock insuffisant |
2003 | Champ obligatoire manquant ou format de champ incorrect |
3001 | Solde insuffisant |
4001 | Commande introuvable |
429 | Appels 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 sku | Produits | Mode de livraison | Prix |
|---|