Главная / Документация API

Документация API

Версия v1 · для реселлеров и разработчиков

Через API можно из своего кода оформлять заказы, проверять их и получать коды. Сумма заказа списывается с баланса счёта, оплачивать каждый заказ отдельно не нужно.

  1. Зарегистрироваться, на Личный кабинет Пополните баланс.
  2. В Личный кабинет → API Создайте ключ, чтобы получить AppID и Secret; рекомендуем также настроить белый список IP.
  3. Вызывайте API, подписывая запросы так, как описано ниже.
Адрес APIhttps://vynqlo.com/api/open/v1
Формат данныхЗапросы и ответы в формате JSON, кодировка UTF-8
Единица суммыВ юанях (CNY), не более 2 знаков после запятой
Лимит запросовНе более 10 запросов в секунду на ключ; при превышении вернётся 429

Способ подписи

Каждый запрос должен содержать эти 4 заголовка:

Заголовки запросаОписание
X-App-IdВаш AppID
X-TimestampТекущая метка времени Unix (в секундах); расхождение с сервером — не более 300 секунд
X-NonceСлучайная строка, 16–32 символа; одно и то же значение нельзя повторять в течение 10 минут
X-SignПодпись; как её вычислить, см. ниже

Соедините 5 элементов ниже символом перевода строки \n — так получится строка для подписи:

метка времени\nслучайная строка\nметод запроса (заглавными буквами)\nпуть запроса (с параметрами)\nисходное тело запроса (пустая строка для GET-запросов)

Затем используйте Secret Вычислите HMAC-SHA256 и переведите результат в шестнадцатеричный вид в нижнем регистре — это и есть X-Sign。

Пример на Python

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

Список товаров

GET /products — возвращает все доступные для заказа товары, вашу оптовую цену и остатки.

{ "code": 0, "data": [ { "sku": "apple.us.25", "name": "Подарочная карта Apple · США $25", "delivery": "code", // code = код подарочной карты / link = оплата по ссылке / username = пополнение по имени пользователя "price": 189.00, "stock": 167, // у товаров с оплатой по ссылке и пополнением по имени пользователя — null, то есть без ограничений "fields": [] // дополнительные поля, которые нужно передать при заказе, см. «Создание заказа» } ] }

Проверить баланс

GET /balance

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

Создать заказ

POST /orders — если на балансе достаточно средств, сумма списывается сразу и заказ уходит в работу.

ПараметрОбязательноОписание
skuДаКод товара, см. «Таблицу кодов товаров» в конце
quantityНетКоличество, по умолчанию 1. Для подарочных карт — до 10 за заказ, для остальных товаров — только 1
out_trade_noДаНомер заказа в вашей системе, 6–64 латинских букв или цифр. При повторной отправке того же номера вернётся уже созданный заказ — дважды деньги не спишутся
account_emailОбязательно для оплаты по ссылкеEmail аккаунта покупателя
checkout_urlОбязательно для оплаты по ссылкеОфициальная ссылка на оплату
usernameОбязательно для пополнения по имени пользователянапример, имя пользователя Telegram @name

Пример запроса:

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

Пример ответа:

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

Найти заказ

GET /orders/{order_no} или GET /orders?out_trade_no=ваш_номер_заказа

{
  "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Значение
processingСписано, в обработке (заказы с оплатой по ссылке и прямым пополнением обычно 5–30 минут)
deliveredКод выдан. Посмотреть его можно в разделе cards в
completedОплата или пополнение выполнены
failedНе выполнено, сумма возвращена на баланс. Причину см. в remark

Callback-уведомления

Если указать адрес callback в личном кабинете, то когда заказ переходит в статус delivered、completed или failed мы POST данные заказа на этот адрес; содержимое такое же, как в ответе «Найти заказ» — data совпадает.

  • Уведомления также содержат X-App-Id、X-Timestamp、X-Nonce、X-Sign, подпись вычисляется так же. Сначала проверьте подпись, потом обрабатывайте.
  • При успешной обработке верните HTTP 200 и текст success. Иначе повторим попытку через 1, 5, 15 и 60 минут, максимум 4 раза.
  • По одному заказу может прийти несколько уведомлений; пожалуйста, используйте order_no для удаления дублей.

Коды ошибок

codeОписание
0Успешно
1001Неверная подпись или нет нужных заголовков
1002Метка времени вне допустимого диапазона
1003Nonce уже использован
1004IP-адреса нет в белом списке
2001Код товара не найден или товар снят с продажи
2002Нет в наличии
2003Нет обязательных полей или неверный формат поля
3001Недостаточно средств
4001Заказ не найден
429Слишком много запросов

Формат ответа при ошибке:{ "code": 3001, "message": "Недостаточно средств на балансе" }

Таблица кодов товаров

Указаны текущие оптовые цены; точные — см. /products окончательным считается ответ API.

Артикул (sku)ТоварыВыдачаЦена