企业集成

企业集成开放接口技术文档

面向印刷厂与客户 ERP 的企业集成入口：用商户后台「防伪设置」中的 AccessKey 验签调用批次、码文件下载、经销商同步与渠道绑定接口。以下技术细节按行业常见接口规范描述签名与字段。

企业集成开放接口是什么

企业集成开放接口是位格验真面向品牌与印刷/渠道系统的对接能力，用于同步批次、码库、召回状态、经销商与门店等主数据，支撑一物一码防伪与企业内部系统协同。返回位格验真解决方案首页或了解域名风险智能监测防护。

1. 获取凭证

登录商户后台 https://mc.weige.pub → 防伪设置，生成并保管：

AccessKeyID（请求头 X-Access-Key）
AccessKeySk（访问密钥，仅用于本地计算签名，勿传给服务端以外的系统）

接口基址与商户后台 API 同源，路径前缀为 /v1/open/...。生产环境请使用 HTTPS。

2. 验签规范（HMAC-SHA256）

与行业常见 OpenAPI 一致：对规范串做 HMAC-SHA256，结果为小写十六进制。

请求头

头	说明
`X-Access-Key`	AccessKeyID
`X-Timestamp`	Unix 秒级时间戳，与服务器偏差 ≤ 300 秒
`X-Nonce`	随机串，建议 UUID
`X-Signature`	签名十六进制
`Content-Type`	JSON 接口使用 `application/json`

规范串

METHOD\nPATH\nTimestamp\nNonce\nBodySHA256

METHOD：大写，如 POST
PATH：不含 query，如 /v1/open/batches
BodySHA256：请求体 UTF-8 的 SHA256 十六进制；无 body 时对空字节计算
Signature = HMAC_SHA256(AccessKeySk, Canonical) 十六进制小写

伪代码示例

bodyHash = hex(sha256(bodyBytes))
canonical = METHOD + "\n" + path + "\n" + timestamp + "\n" + nonce + "\n" + bodyHash
signature = hex(hmac_sha256(sk, canonical))

3. 批次管理

状态：0 已创建 · 1 已生成 · 2 已赋码 · 3 召回中 · 4 已关闭

3.1 创建批次 `POST /v1/open/batches`

{
  "product_id": 1001,
  "plan_qty": 10000,
  "batch_name": "2026Q1-印刷",
  "sales_area": "广东省",
  "land_domain_id": 0,
  "land_domain": ""
}

落地域规则：

品牌为自有域名：可传 land_domain（主机名），由对接方自行指定。
品牌为平台分配域名：勿传 land_domain；可不传 land_domain_id，系统自动取已分配且已验证的类型 3 域名中最新一条；也可显式传 land_domain_id。

3.2 批次列表 `GET /v1/open/batches`

分页查询本商户批次。常用查询参数：

参数	说明
`page` / `page_size`	分页，默认 1 / 10，最大 100
`product_id`	可选，按商品筛选
`status`	可选，0～4
`batch_code`	可选，批次码

GET /v1/open/batches?page=1&page_size=20&status=1

返回 list + total；列表项字段与详情一致（含 code_file_ready / code_file_url）。

3.3 查询批次详情（轮询码文件） `GET /v1/open/batches/:id`

创建后异步生成防伪码。轮询详情直至：

code_file_ready = true
code_file_url 为带时效签名的下载地址（约 1 小时有效）

3.4 下载防伪码 CSV

使用轮询得到的 code_file_url 直接 GET（query 含 access_key、expires、sign），无需再带头签名。过期后重新查询批次获取新链接。

3.5 修改状态 `PUT /v1/open/batches/:id/status`

{"status": 2}   // 打印完成 → 已赋码
{"status": 3}   // 召回中

仅允许 2 / 3。标记已赋码时批次须已处于「已生成」。

4. 批次渠道绑定

POST /v1/open/batches/:id/channel-bind

{"dealer_id": 12, "shop_id": 34}

将批次内未验真且未绑定的码绑定到指定经销商+门店。需已开通渠道年费。返回 total / bound / skipped / failed。

商户后台「渠道绑定」页同步支持整批绑定；单码绑定能力保持不变。

5. 渠道调拨

与商户后台同一规则：类型 1 退货解绑 · 2 改门店 · 3 改经销商+门店。 未绑定且类型为 2/3 时直接绑定到目标并写调拨日志；已验真不可调拨；类型 1 对未绑定码无效。

5.1 单码调拨 `POST /v1/open/channel-reallocates`

{
  "code": "16位码或验真URL",
  "realloc_type": 3,
  "to_dealer_id": 12,
  "to_shop_id": 34,
  "remark": "ERP调拨"
}

5.2 批次调拨 `POST /v1/open/batches/:id/channel-reallocate`

{
  "realloc_type": 3,
  "to_dealer_id": 12,
  "to_shop_id": 34,
  "remark": "整批调拨"
}

返回 total / done / skipped / failed，以及可选 skip_stats（跳过原因计数）。

6. 经销商数据同步

6.1 经销商列表 `GET /v1/open/dealers`

分页查询本商户经销商。查询参数：

参数	说明
`page` / `page_size`	分页，默认 1 / 10，最大 100
`name`	可选，名称模糊匹配
`status`	可选，1 停用 / 2 启用

GET /v1/open/dealers?page=1&page_size=50&status=2

返回 list（含 id/name/contact/phone/sort/status）+ total。

6.2 按名称增删改

以名称作为业务主键（ERP 侧常用）。

方法	路径	说明
POST	`/v1/open/dealers`	新增；同名已存在则失败
PUT	`/v1/open/dealers`	按 `name` 修改；可用 `new_name` 改名
DELETE	`/v1/open/dealers`	按 `name` 删除（须先无下属门店/账号）

// 新增 / 修改
{"name":"华南总代","contact":"张三","phone":"13800000000","status":2}

// 删除
{"name":"华南总代"}

7. 门店数据同步

门店以经销商 + 门店名称定位（可传 dealer_id 或 dealer_name）。需已开通渠道年费。

7.1 门店列表 `GET /v1/open/shops`

参数	说明
`page` / `page_size`	分页，默认 1 / 10，最大 100
`dealer_id` / `dealer_name`	可选，按经销商筛选
`name`	可选，门店名称模糊匹配
`status`	可选，1 停用 / 2 启用

GET /v1/open/shops?page=1&page_size=50&dealer_name=华南总代

7.2 查询经销商下的门店 `GET /v1/open/dealers/shops`

须指定 dealer_id 或 dealer_name。

GET /v1/open/dealers/shops?dealer_name=华南总代&page=1&page_size=50

7.3 按名称增删改

方法	路径	说明
POST	`/v1/open/shops`	新增；同经销商下同名已存在则失败
PUT	`/v1/open/shops`	按经销商+门店名修改；可用 `new_name` 改名
DELETE	`/v1/open/shops`	按经销商+门店名删除（须先无下属渠道账号）

// 新增 / 修改
{
  "dealer_name": "华南总代",
  "name": "天河店",
  "province": "广东省",
  "city": "广州市",
  "district": "天河区",
  "address": "某某路 1 号",
  "status": 2
}

// 删除
{"dealer_name":"华南总代","name":"天河店"}

8. 并发与限流

同一 AccessKey：约 120 次/分钟（超限返回友好错误）
创建批次、改状态、批次绑定/调拨、经销商/门店按名同步：服务端短时互斥锁，避免并发写冲突

9. 验收脚本（推荐）

提供 Bash 脚本 anti_open_api_acceptance.sh：先本地校验 HMAC 验签是否与文档一致，再用你的 AccessKey 对真实环境做只读列表与经销商/门店增删改查冒烟。

下载验收脚本

环境要求

macOS / Linux，Bash
已安装：openssl、jq、curl、python3
无需 Go 源码；独立下载即可跑在线验收

使用步骤

下载脚本后赋予执行权限：chmod +x anti_open_api_acceptance.sh
在商户后台「防伪设置」取得 AccessKeyID / AccessKeySk
执行（密钥请勿提交到仓库或发到公开群）：

ACCESS_KEY_ID='你的AccessKeyID' \
ACCESS_KEY_SK='你的AccessKeySk' \
BASE_URL=https://mc.weige.pub \
./anti_open_api_acceptance.sh

常用可选参数

环境变量	说明
`BASE_URL`	API 基址，默认 `https://mc.weige.pub`
`SKIP_WRITE=1`	只做列表探测，不创建/修改/删除经销商与门店
`KEEP_FIXTURES=1`	冒烟创建的经销商/门店不自动清理
`PRODUCT_ID`	若设置则额外尝试创建批次（会扣发码额度，慎用）

# 仅只读
SKIP_WRITE=1 ACCESS_KEY_ID=... ACCESS_KEY_SK=... ./anti_open_api_acceptance.sh

# 含创建 1 条批次（慎用）
PRODUCT_ID=1001 ACCESS_KEY_ID=... ACCESS_KEY_SK=... ./anti_open_api_acceptance.sh

脚本退出码：全部通过为 0，任一 FAIL 为 1。汇总行会打印通过/失败/跳过数量。密钥泄露请立即在后台轮换 AccessKey。验收脚本若使用 ACCESS_KEY_SK（或同名访问密钥环境变量），与此处 AccessKeySk 为同一凭证。

10. 响应格式

与商户后台一致：成功时 code=0（或业务约定成功码）且 data 为业务体；失败时返回错误信息。对接时请以实际返回 JSON 为准。

更多能力（营销模板、核销等）请使用商户后台或联系商务开通定制。