接口简介
「条形码生成与校验」是数据鱼API平台提供的条形码与点阵码的生成、校验接口,Base 路径 /api/barcode,共 12 个端点,支持 8 种码制:商品条码 EAN-13、EAN-8、UPC-A,物流通用 Code128、Code39、ITF-14、Codabar,以及二维点阵码 DataMatrix(ECC 200)。生成结果输出 SVG 矢量图或包含 SVG 字符串的 JSON,可无损缩放、直接嵌入网页或经排版引擎转印到标签。
接口把「校验」与「生成」拆成独立端点。校验端点对输入码做归一化、按码制规则校验位数与字符集,并计算校验位:输入码自带校验位时逐位比对,不带时补算出期望的完整码,返回 valid 与 expected_code,适合入库前清洗脏数据。生成端点则封装了从编码到 SVG 渲染的完整流程,提供高度、缩放、文本显示、前景背景色、渐变结束色等渲染参数。
八种码制各有一个以码制命名的快捷端点(如 ean13、code128),参数集与统一生成端点一致,免去每次传 type;另有批量端点一次渲染多个码。数据鱼API 的该接口为纯算法实现:无外部依赖、无存储,校验位计算与 SVG 绘制均在服务端本地完成。
端点总览
方法 路径 说明 鉴权
GET /api/barcode/ping 健康检查,返回码制能力表 免鉴权
GET /api/barcode/validate 按码制校验并计算校验位 需要
GET /api/barcode/generate 统一生成端点,需传 type 需要
GET /api/barcode/ean13 EAN-13 快捷生成 需要
GET /api/barcode/ean8 EAN-8 快捷生成 需要
GET /api/barcode/upca UPC-A 快捷生成 需要
GET /api/barcode/code128 Code128 快捷生成 需要
GET /api/barcode/code39 Code39 快捷生成 需要
GET /api/barcode/itf14 ITF-14 快捷生成 需要
GET /api/barcode/codabar Codabar 快捷生成 需要
GET /api/barcode/datamatrix DataMatrix 快捷生成 需要
POST /api/barcode/batch 批量生成 需要
通用约定
鉴权使用数据鱼API 全站统一 Key(X-API-Key 头或 ?api_key= 参数);4011/4013 含义与全站一致。响应为 {code, msg, data}。本接口特有之处:码内容位数或字符集不符合码制规则时返回 4001 并给出具体规则提示(如 EAN13 需要 12 或 13 位、Codabar 必须以 A/B/C/D 开头结尾);format=svg 时直接返回 image/svg+xml 内容而非 JSON 包装。各码制能力可在 ping 端点获取:内容类型(纯数字/ASCII/受限字符集)与长度区间。
核心端点详解
校验 validate
参数 类型 必填 默认 说明
code string 是 - 待校验的码
type string 否 ean13 码制:ean13/ean8/upca/itf14 等数字型码制
checksum string 否 0 输入是否已含校验位的声明
返回 input、normalized(归一化结果)、payload(剔除校验位的数据体)、check_digit(计算所得校验位)、input_check_digit(输入自带校验位)、input_has_check_digit、valid、code(补全校验位后的完整码)与 expected_code。对 12 位 EAN-13 输入,接口按缺校验位处理并补算第 13 位;13 位输入则逐位比对。校验只覆盖支持校验位的数字型码制。
GET /api/barcode/validate?type=ean13&code=6901234567892
X-API-Key: YOUR_API_KEY
生成 generate
参数 类型 必填 默认 说明
code string 是 - 码内容,须符合码制字符集与长度
type string 否 ean13 码制,见端点总览
height int 否 80 条码高度(像素)
scale int 否 2 模块缩放倍数
show_text string 否 1 是否在图下方渲染可读文本
format string 否 svg svg 直接输出图像;json 返回含 SVG 字符串的数据对象
checksum string 否 0 输入是否已含校验位
ecl string 否 M DataMatrix 纠错等级
fg / bg string 否 #000000 / #ffffff 前景与背景色
fg_end string 否 - 渐变结束色
style string 否 standard 渲染样式变体
format=json 时返回 type、code、display_code、modules(模块宽度)、width/height(画布尺寸,高度含文本区)与 svg 字符串;format=svg 时 HTTP 响应即为图像。数字型码制传 12 位 EAN-13、11 位 UPC-A、13 位 ITF-14 时自动补算校验位。
GET /api/barcode/generate?type=code128&code=ABC-123&format=json&height=100
X-API-Key: YOUR_API_KEY
批量生成 batch
参数 类型 必填 默认 说明
items array 是 - 非空 JSON 数组,每项含 type、code 及可选渲染参数
POST JSON 请求体。返回 total 与 results 数组,每项带 index(对应输入下标)与该码的渲染结果;单项失败不影响其他项,错误随对应下标返回。
POST /api/barcode/batch
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{"items": [{"type": "ean13", "code": "6901234567892"}, {"type": "code128", "code": "ABC123", "format": "json"}]}
快捷端点(ean13/ean8/upca/code128/code39/itf14/codabar/datamatrix)
参数集与 generate 完全一致,仅省略 type;另接受与端点同名的别名参数(如 ean13=...)作为 code 的等价写法。各码制约束:EAN-13 需 12/13 位纯数字;EAN-8 需 7/8 位;UPC-A 需 11/12 位;ITF-14 需 13/14 位;Code128 为 1 至 48 位 ASCII;Code39 为大写字母与数字等受限字符集;Codabar 字符集为数字与 - $ : / . + 及起止符 ABCD,且必须以 A/B/C/D 开头结尾;DataMatrix 接受任意文本,纠错遵循 ECC 200。
数据与限制
Code128、Code39、Codabar 内容长度上限 48 字符;DataMatrix 无长度限制参数,按内容自动选尺寸。
渲染参数仅影响 SVG 输出:height 为条高,文本区另行增加约 20 像素;scale 控制模块宽度精度。
校验位自动补算仅对 EAN-13/EAN-8/UPC-A/ITF-14 四类数字码制生效;Code128/Code39/DataMatrix 无独立校验位输出。
输出全部为 SVG 矢量图;如需 PNG/JPEG 需调用方自行转换。
典型使用场景
商品与物流系统:为 SKU、运单批量生成 EAN/ITF-14/Code128 标签。
入库数据清洗:validate 批量核对历史条码数据的校验位与码制合规性。
票据与单据:Codabar/Code39 用于会员卡、快递单等传统单据码制,DataMatrix 用于小尺寸高密度场景。
注意事项
各快捷端点参数表中带有一个与端点同名的可选参数(如 ean13),实测它与 code 等价、可二选一;两个都传时以 code 为准更稳妥。
format=svg 的响应不是 JSON,客户端需按图像内容处理,HTTP 头为 image/svg+xml;解析失败时的 JSON 错误仍按统一结构返回。
DataMatrix 的 ecl 仅对该码制生效,对一维码制传值无副作用;show_text 对 DataMatrix 无意义(点阵码无下方文本约定)。
Code39 内容仅支持其受限字符集,小写字母需调用方先转大写;Codabar 忘记传起止符是最常见的 4001 来源。
数据鱼API 的校验通过仅代表码值自洽合规,不代表该商品编码已在编码机构注册。