开发者/生态与资源
在 Dujiao-Next 中接入 CardV
把 CardV 作为上游供应商接入你的 Dujiao-Next（独角数卡）商店。你把 CardV 的礼品卡和游戏直充导入为自己的商品，自己定价。买家付款后，你的商店会用你的 CardV 余额向 CardV 采购，卡密自动出现在买家的订单页面。
#准备条件
| Dujiao-Next | v1.5.0 或更高版本，后台有“对接管理”菜单 |
| CardV 账号 | 已审核通过、已开通 API 权限的商户账号 |
| API Key | 商户后台中的签名 API Key（Key ID + 签名密钥） |
| 余额 | CardV 美元预付余额，商店的每笔采购都从中扣款 |
对你的买家而言，你是交易中的卖方：由你定价、回答买家的问题并处理买家的退款。
#第 1 步：获取 API Key
直接使用你在商户后台 开发者 > API 与 Webhook > API 密钥 中已有的 Key，不需要为 Dujiao-Next 另建一套密钥。
- Key ID 以
ck_live_开头。 - 签名密钥以
cs_live_开头，只在创建 Key 时显示一次。如果已经找不到，可在该 Key 上点击 重新生成密钥（Regenerate secret）：Key ID 不变，旧密钥立即失效。
没有 Key ID 的旧版 Key 不能使用，请在商户后台新建一个 Key。
#第 2 步：添加连接
在 Dujiao-Next 后台打开 对接管理 > 连接管理 > 新建连接，按下表填写：
| 字段 | 填写内容 | 原因 |
|---|---|---|
| 名称 | 例如 CardV（USD） | 只有你自己看得到，写上币种以免日后混淆 |
| Base URL | https://b2b.cardv.net/dujiao | 必须带 /dujiao，后面不要再加任何路径，也不要以斜杠结尾 |
| API Key | 你的 Key ID（ck_live_…） | |
| API Secret | 你的签名密钥（cs_live_…） | 以后编辑连接时留空，表示保留已保存的密钥 |
| 协议 | dujiao-next | |
| 回调 URL | 留空 | CardV 不发送回调，你的商店会自己查询每笔订单的结果（见交付方式） |
| 最大重试次数 / 重试间隔 | 保持默认（3 / 30,60,120） | 只对临时性错误重试 |
| 汇率 | 你自己手动填写的固定数字：当前真实的“美元 → 店铺币种”汇率，建议比实时汇率略高一点作为缓冲；店铺用美元销售就填 1 | CardV 价格一律是美元。Dujiao-Next 不会自动获取实时汇率，CardV 也无法替你设置；默认值是 1，店铺如果用人民币等其他币种销售，10 美元的卡会被标成 10 元出售 |
| 加价百分比 | 你的利润率，例如 15 | 默认是 0，也就是没有利润 |
| 价格取整 | 向上取整（0.1） 或 向上取整（整数） | 向上取整不会让售价低于成本 |
| 同步时自动更新价格 | 是 | CardV 价格变动后，下次同步时按你的汇率和加价重新计算售价 |
汇率和加价的计算方式：CardV 价格 × 汇率 × （1 + 加价百分比），再取整。例如，假设汇率为 7.2（仅为示例，请填写你自己查到的当前汇率）、加价 15%，5.78 美元的卡售价为 47.9。
汇率变动后，请回到连接里更新汇率，再点击 重新应用加价，已导入商品的价格会一起更新。修改加价时也是一样。
#第 3 步：测试连接
在连接上点击 Ping。看到 Ping 成功 说明 Key 可用，连接状态会变为 已激活。如果出现错误，请查看常见错误。
#第 4 步：导入商品
- 打开 对接管理 > 商品映射 > 从上游导入，选择你的 CardV 连接。
- 按分类浏览，或切换到 列表模式 挑选单个商品。
- 选择一个本地分类，或勾选 自动创建本地同名分类。商品必须有分类才能保存。
- 导入。商品会带上标题、简介、使用说明和面额（例如
10 USD）。
导入的商品默认是下架状态。逐个检查后，在商品编辑页打开 立即上架。
#第 5 步：每单只卖 1 件
每个导入的商品都要打开编辑页，把 单次最大购买数量 设为 1。
CardV 每笔采购只交付 1 件。如果买家在一个订单里买了 2 张卡，CardV 会拒绝这笔采购，你需要手动处理这个订单。Dujiao-Next 无法自动从 CardV 获取这个限制，所以需要你自己设置。
在编辑页里我们还建议：
- 前台库存展示：选择 隐藏数量。CardV 在订单到达时才向品牌方采购，商店显示的库存数字只表示“有货”。
- 商品图片：没有图片的商品可以自己上传。
#交付方式
- 买家在你的商店付款。
- 你的商店向 CardV 提交采购，CardV 从你的 CardV 余额中扣款。
- 你的商店到 CardV 查询这笔订单。我们实测时，卡密在一分钟内到达。
- 卡密显示在买家的订单页面：
Code、PIN（卡有 PIN 时）和Expires（卡有有效期时）。交付的始终是卡密，不会是链接。
直充商品。 有些商品直接充值到买家的游戏或应用账号。买家结账时要填写商品需要的信息，例如玩家 ID 或手机号。充值完成后，买家的订单页面显示 Top-up completed.
CardV 无法交付时。 CardV 会把这笔采购的金额退回你的 CardV 余额，你的商店会把这笔采购标记为已取消。之后由你在商店里为买家退款或处理。
#暂不支持的商品
导入列表只显示能通过这个连接销售的商品：
- 只支持固定面额。 需要买家自己输入金额的卡不会出现。
- 不会出现： 手机话费充值、支付与钱包类商品、加密货币，以及预付支付卡。
- 只发卡密。 只能以链接形式交付的商品不会出现。
你看到的价格是你自己账户的 CardV 美元价格。
#IP 白名单
如果你在商户后台设置了 IP 白名单，请把运行 Dujiao-Next 商店的服务器公网 IP 加进去，否则 CardV 会拒绝来自这台服务器的所有请求。同一个 Key 的白名单和请求频率限制，同时适用于 CardV API 和 Dujiao-Next。
#常见错误
这些提示会出现在 Dujiao-Next 后台：点击 Ping 后、导入时，或者在 采购单管理 的采购记录上。
| 提示 | 原因 | 处理方法 |
|---|---|---|
status 401 (invalid_signature): signature verification failed | API Secret 填错了，或者你在商户后台重新生成过密钥 | 把当前的签名密钥重新填入连接 |
status 403 (invalid_api_key): api key is invalid or disabled | API Key 填的不是 Key ID（ck_live_…），或者这个 Key 已停用 | 填写一个启用中的 Key 的 Key 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 余额充值后，在 采购单管理 中对这笔采购点击 重试 |
quantity must be 1: CardV accepts one item per order | 买家对同一商品下单超过 1 件 | 把 单次最大购买数量 设为 1（见第 5 步），再手动处理这个订单 |
sku is invalid or not available | 这个商品已经不能从 CardV 购买 | 对该映射执行一次同步，CardV 不再提供的商品会自动下架 |
status 429 (rate_limited) | 一分钟内请求过多 | 商店会自动重试；如果经常出现，请降低同步频率 |
#常见问题
Dujiao-Next 需要单独的 API Key 吗？ 不需要，直接用你已有的签名 API Key。如果这个 Key 同时用于你自己的 CardV API 对接，两边共用同一份请求频率额度。
为什么回调 URL 要留空？ CardV 不会向商店发送回调，你的 Dujiao-Next 商店会自己查询每笔订单，直到得到最终结果。
CardV 价格变了怎么办？ 打开 同步时自动更新价格 后，下次同步时会按你的汇率和加价重新计算售价。如果关闭，商店会继续按旧价格销售。
在 CardV 哪里能看到这些订单？ 在商户后台的 订单 页面，“您的订单 ID”一栏以 dujiao: 开头，后面接 Dujiao-Next 的子订单号（例如 dujiao:DJ…-01）。如果你配置了 CardV Webhook，这些订单同样会触发。
可以修改商品标题、简介和图片吗？ 可以。同步只更新价格和可售状态，不会覆盖你的标题和图片。
可以销售自定义金额的卡吗？ 目前在 Dujiao-Next 中还不行，只支持固定面额。
#支持
如需帮助，请发送邮件至 [email protected]，并附上你的商户号（Merchant ID）、Dujiao-Next 订单号和错误提示。你对 CardV 服务的使用受我们的服务条款约束。
接入遇到问题？请发送邮件至 [email protected]，并附上 Merchant ID 与订单号或请求 ID。