Разработчикам/Экосистема и ресурсы
CardV для Dujiao-Next
Подключите CardV как поставщика в своём магазине Dujiao-Next. Вы импортируете подарочные карты и игровые пополнения CardV как свои товары и сами устанавливаете цены. Когда покупатель оплачивает заказ, ваш магазин покупает товар у CardV с вашего баланса CardV, и код автоматически появляется на странице заказа покупателя.
#Что понадобится
| Dujiao-Next | v1.5.0 или новее, с функцией подключения к поставщику (меню Integration) |
| Аккаунт CardV | Одобренный аккаунт мерчанта с включённым доступом к API |
| API-ключ | Подписанный API-ключ из личного кабинета (ID ключа + секрет подписи) |
| Баланс | Предоплаченный баланс CardV в USD. Каждый заказ вашего магазина оплачивается с него |
Продавцом для ваших покупателей являетесь вы: вы устанавливаете цены, отвечаете на их вопросы и занимаетесь их возвратами.
#Шаг 1: получите API-ключ
Используйте API-ключ, который у вас уже есть в личном кабинете (Merchant Portal) в разделе API и вебхуки > API-ключи. Отдельный ключ для Dujiao-Next не нужен.
- ID ключа начинается с
ck_live_. - Секрет подписи начинается с
cs_live_. Он показывается только один раз, при создании ключа. Если у вас его больше нет, нажмите у ключа Сгенерировать новый секрет. ID ключа не меняется, а старый секрет сразу перестаёт работать.
Старые ключи без ID ключа использовать нельзя. Вместо этого создайте в личном кабинете новый ключ.
#Шаг 2: добавьте подключение
В админке Dujiao-Next откройте Integration > Connection Management > New Connection и заполните форму:
| Поле | Что ввести | Зачем |
|---|---|---|
| Name | Например, CardV (USD) | Его видите только вы. Валюта в названии поможет не запутаться позже |
| Base URL | https://b2b.cardv.net/dujiao | С /dujiao и без чего-либо после него, без косой черты в конце |
| API Key | Ваш ID ключа (ck_live_…) | |
| API Secret | Ваш секрет подписи (cs_live_…) | Если позже вы будете редактировать подключение, оставьте поле пустым, чтобы оставить сохранённый секрет |
| Protocol | dujiao-next | |
| Callback URL | Оставьте пустым | CardV не отправляет обратные вызовы (callbacks). Ваш магазин сам проверяет результат каждого заказа (см. Как работает выдача) |
| Max Retries / Retry Intervals | Оставьте значения по умолчанию (3 / 30,60,120) | Повторы применяются только к временным ошибкам |
| Exchange Rate | Фиксированное число, которое вы вводите сами: текущий реальный курс USD к валюте вашего магазина, немного выше него для запаса. Введите 1, если ваш магазин продаёт в USD | Цены CardV всегда в USD. Dujiao-Next не получает курсы в реальном времени, а CardV не может задать это значение за вас. По умолчанию стоит 1, поэтому магазин, который продаёт в другой валюте, выставил бы карту за 10 USD по цене 10 в своей валюте |
| Price Markup (%) | Ваша наценка, например 15 | По умолчанию 0, то есть без прибыли |
| Price Rounding | Round up (0.1) или Round up (integer) | При округлении вверх цена никогда не опускается ниже вашей себестоимости |
| Auto-update price on sync | Yes | Когда цена CardV меняется, ваша цена продажи пересчитывается при следующей синхронизации |
Курс и наценка применяются так: цена CardV × курс × (1 + наценка), затем округление. Например, при курсе 7.2 (это только пример; введите текущий курс, который вы найдёте сами) и наценке 15% карта за 5.78 USD продаётся за 47.9.
Когда курс меняется, обновите его в подключении и нажмите Reapply Markup, чтобы обновить цены уже импортированных товаров. Сделайте то же самое, когда меняете наценку.
#Шаг 3: проверьте подключение
Нажмите Ping у подключения. Ping succeeded означает, что ключ работает, и статус подключения меняется на Active. Если вместо этого появилась ошибка, см. Решение проблем.
#Шаг 4: импортируйте товары
- Откройте Integration > Product Mappings > Import from Upstream и выберите подключение CardV.
- Просматривайте товары по категориям или переключитесь на Flat List, чтобы выбрать отдельные товары.
- Выберите локальную категорию или отметьте Auto-create local categories. Товар нельзя сохранить без категории.
- Импортируйте. Каждый товар сохраняет название, описание, инструкцию по активации и номиналы (например,
10 USD).
Импортированные товары сняты с продажи. Проверьте каждый товар, затем включите Active в редакторе товара.
#Шаг 5: одна единица товара в заказе
Для каждого импортированного товара откройте редактор товара и установите Max purchase quantity на 1.
CardV выдаёт одну единицу товара на заказ. Если покупатель оплатит два кода в одном заказе, CardV отклонит покупку, и вам придётся разбираться с этим заказом вручную. Dujiao-Next не может получить это ограничение от CardV автоматически, поэтому установите его сами.
Пока вы в редакторе, мы также рекомендуем:
- Отображение остатка на витрине: выберите Hide quantity. CardV покупает у бренда, когда поступает заказ, поэтому остаток, который показывает ваш магазин, означает только «в наличии».
- Изображения: добавьте свои, если у товара их нет.
#Как работает выдача
- Покупатель оплачивает заказ в вашем магазине.
- Ваш магазин отправляет покупку в CardV, и CardV списывает сумму с вашего баланса CardV.
- Ваш магазин проверяет заказ в CardV. В наших тестах код приходил в течение минуты.
- Код появляется на странице заказа покупателя как
Code,PIN(если у карты он есть) иExpires(если у карты есть срок действия). Это всегда код, а не ссылка.
Прямые пополнения. Некоторые товары зачисляются прямо на игровой аккаунт или аккаунт в приложении покупателя. При оформлении заказа покупатель вводит данные, которые нужны товару, например ID игрока или номер телефона. Когда пополнение выполнено, на странице заказа покупателя отображается Top-up completed.
Если CardV не может выдать товар. CardV возвращает сумму заказа на ваш баланс CardV, а ваш магазин помечает покупку как отменённую. Дальше вы делаете возврат покупателю или помогаете ему в своём магазине.
#Что недоступно
В списке импорта есть только товары, которые ваш магазин может продавать через это подключение:
- Только фиксированные номиналы. Карты, где покупатель вводит свою сумму, в списке не показываются.
- Не показываются: пополнения мобильной связи, платёжные продукты и кошельки, криптовалюта и предоплаченные платёжные карты.
- Только коды. Товары, которые можно выдать только ссылкой, в списке не показываются.
Цены, которые вы видите, — это ваши собственные цены CardV в USD.
#Список разрешённых IP
Если вы настроили в личном кабинете список разрешённых IP, добавьте публичный IP-адрес сервера, на котором работает ваш магазин Dujiao-Next. Иначе CardV будет отклонять все запросы с него. Для CardV API и для Dujiao-Next действуют один и тот же ключ, один и тот же список разрешённых IP и одни и те же лимиты запросов.
#Решение проблем
Эти сообщения появляются в админке Dujiao-Next: после Ping, во время импорта или у покупки в Procurement Orders.
| Сообщение | Причина | Что делать |
|---|---|---|
status 401 (invalid_signature): signature verification failed | API Secret неверный, или вы сгенерировали новый секрет в личном кабинете | Скопируйте текущий секрет подписи в подключение |
status 403 (invalid_api_key): api key is invalid or disabled | В API Key указан не ID ключа (ck_live_…), или ключ отключён | Используйте ID ключа активного ключа |
status 403 (user_disabled): merchant API access is not enabled | Ваш аккаунт ещё не одобрен для доступа к API | Пройдите проверку компании в личном кабинете |
status 403 (forbidden): source IP is not allowed for this merchant | В вашем списке разрешённых IP нет сервера магазина | Добавьте публичный IP-адрес сервера в личном кабинете |
status 401 (timestamp_expired): timestamp expired | Часы вашего сервера расходятся больше чем на 60 секунд | Включите на сервере автоматическую синхронизацию времени (NTP) |
status 404 и затем веб-страница | Base URL неверный, обычно не хватает /dujiao | Используйте https://b2b.cardv.net/dujiao |
CardV wallet balance is insufficient | Вашего баланса CardV не хватает на покупку. Заказ покупателя остаётся оплаченным | Пополните баланс CardV, затем нажмите Retry у покупки в Procurement Orders |
quantity must be 1: CardV accepts one item per order | Покупатель заказал больше одной единицы товара | Установите Max purchase quantity на 1 (Шаг 5), затем обработайте заказ вручную |
sku is invalid or not available | Товар больше не доступен в CardV | Запустите синхронизацию для этого сопоставления. Товары, которые CardV больше не предлагает, снимаются с продажи |
status 429 (rate_limited) | Слишком много запросов за одну минуту | Ваш магазин повторит запрос сам. Если это повторяется, уменьшите частоту синхронизации |
#FAQ
Нужен ли новый API-ключ для Dujiao-Next? Нет. Используйте подписанный API-ключ, который у вас уже есть. Если вы также используете ключ для своей интеграции с CardV API, у них общие лимиты запросов.
Почему Callback URL оставляют пустым? CardV не отправляет обратные вызовы магазинам. Ваш магазин Dujiao-Next сам проверяет каждый заказ, пока не получит окончательный результат.
Что происходит, когда меняются цены CardV? Если Auto-update price on sync включено, ваши цены продажи пересчитываются с вашим курсом и наценкой при следующей синхронизации. Если выключено, магазин продолжает продавать по старой цене.
Где увидеть эти заказы в CardV? На странице Заказы в личном кабинете. Значение в столбце Ваш ID заказа начинается с dujiao:, за которым идёт номер подзаказа Dujiao-Next (например, dujiao:DJ…-01). Если вы настроили вебхуки CardV, они срабатывают и для этих заказов.
Можно ли менять названия, описания и изображения товаров? Да. Синхронизация обновляет цены и наличие. Ваши названия и изображения она не перезаписывает.
Можно ли продавать произвольные суммы? Через Dujiao-Next пока нет. Доступны только фиксированные номиналы.
#Поддержка
Напишите на [email protected] и укажите ваш Merchant ID, номер заказа Dujiao-Next и текст ошибки. Использование CardV регулируется нашими Условиями обслуживания.
Вопросы по интеграции? Напишите на [email protected], указав ваш Merchant ID и ID заказа или запроса.