条形码查询 API Python 实战:通过 UPC/EAN/ISBN 获取商品详情
收货台上只需要三格数据,就能把返回形状走完。一格是瓶子上的 3017620422003,一格是旧精装书上的 9780747532699,一格是搜索框里的 nutella。条形码查询 API 只有一个操作 search-product-details。三个值都进 query,但 data 下面不是「同一个对象缺几个字段」,而是两种结构;条码没查到时,还会用搜索那种空数组来表示——数字进、空列表出,这才是最容易写错分支的地方。
登录 后从控制台复制 Key,放进服务端环境变量 OPENDATA_API_KEY。下面的 curl 用占位符 YOUR_API_KEY。Key 出现在查询字符串里,不要贴进工单、截图或扫码 App。打开本页、复制示例都不会发请求。
桌上的一条码
先打瓶子上的数字,这是扫码入库最常见的形状:
curl --get 'https://api.opendata-api.com/api/project/barcodes-lookup/search-product-details?key=YOUR_API_KEY' \
--data-urlencode 'query=3017620422003'
条码模式不要带 page。HTTP 4xx/5xx 表示请求没跑成(鉴权、额度、网关);跑成了还要看信封 {code, message, data}。code 为 200 只说明平台受理了,不说明目录里有这件货。命中时 data 里是 product 对象;从未收录的数字条码会走搜索那套空壳:results 为 [],nextPage 为 null。分支看哪个键在,别看 HTTP 200,也别把空数组当成超时去连打。
ISBN 走同一个参数,没有「图书专用接口」。图书馆扫 ISBN-10 还是 ISBN-13,都是这一格:
curl --get 'https://api.opendata-api.com/api/project/barcodes-lookup/search-product-details?key=YOUR_API_KEY' \
--data-urlencode 'query=9780747532699'
UPC-A、EAN-13、JAN、ISBN-10/13 都进 query。命中后看 product.barcode_formats,里面会回显 ean_13、upc_a、isbn_10、isbn_13 里实际对上的那些。跨境上架常要同时记下 EAN 和 UPC,就从这张表抄,不要自己在数字前面补零再当另一种码去打第二次。
解信封的最小写法:先过 HTTP,再过 code,最后只认 product 是对象才算命中。搜索结果或空 results 在条码路径里一律当未收录。
data.product 里到底有什么
有 product 时,把它当目录卡片走一遍,别当货架,也别当营养数据库。
title、description 是 listing 文案,可能很长,也可能带某个店的成色标记——书名里夹着 Used、Hardcover 很常见,直接当书名展示会很难看,入库前要决定是原样落库还是裁掉尾注。category 是从宽到窄的路径数组,食品可能是 Food, Beverages & Tobacco → Food Items → Dips & Spreads,书可能是 Media → Books。拼进 PIM 时用连接符即可,不要假设层数固定,也不要只取最后一截当类目名,前面几层才是跨境站点常见的一级类。
brand 和 manufacturer 彼此独立,名品也可能是 null。榛子酱这种例子里,制造商有值、品牌却空着,不要擅自用标题里的单词填品牌列,除非产品规则写明了回退。attributes 多数时候是表:mpn、asin、size、dimensions、weight,偶尔有 model。asin 只是「有则用之」的补充,不是 UPC 转 ASIN 的保证;有的记录这个字段会给空数组 [] 而不是 {},先判断是不是 dict 再 .get,否则进销存脚本会在最常见的书目上炸掉。features 是卖点列表,可以为空,空列表不等于没这件货。
images 是图片 URL 数组;搜索命中用的是单数 image,那是另一种对象,不要把两套字段写进同一个解析器。author / artist 出现在图书和音像上,食品一般是 null。nutrition_facts、ingredients 只在食品上出现,而且经常仍是 null;nutrition_facts 有值时也可能是一整段字符串,不是分项表,卡路里应用要按类型读,不要按键去取蛋白质克数。
online_stores 有报价时是 {name, price, url} 数组。price 是带货币符号的展示串,欧元、澳元、美元会混在同一列表里,不是单一币种的小数;看起来很完整的记录也可能整个字段是 null。比价页可以拿店名和链接做展示,结算价仍以自己的进价表为准。barcode_formats 回显这条卡片绑过的码,扫码枪读到哪种就和这里对一下,确认不是把 ISBN-10 和 ISBN-13 当成两件货。
除了 product 本身是对象,上面这些都不保证有。入库表单能填的先填 title、category、manufacturer、images,其余按字段在不在走。
同一个 query 怎么变成搜索
query 换成普通词,模式就切了,没有额外开关。选品、找替代装、从品牌名反查条码,都走这条:
curl --get 'https://api.opendata-api.com/api/project/barcodes-lookup/search-product-details?key=YOUR_API_KEY' \
--data-urlencode 'query=nutella'
这时 data 里是 results 和 nextPage。每条命中是瘦行:barcode、title、category、image、manufacturer,brand / author 常常是 null。这不是 data.product,没有 attributes、没有 online_stores、没有 images 数组。要完整卡片,拿命中里的 barcode 再打一次条码模式——那是第二次请求,不是你漏读的字段。不要把搜索瘦行直接塞进上架模板,缺尺寸重量时站点会拒登。
nextPage 是游标,原样回传为 page。这个接口里它看起来经常像整数,仍然不要自己加一,更不要在条码查询上带 page。自己编页码要么空页,要么 silently 走到别人的结果集。
curl --get 'https://api.opendata-api.com/api/project/barcodes-lookup/search-product-details?key=YOUR_API_KEY' \
--data-urlencode 'query=nutella' \
--data-urlencode 'page=2'
nextPage 为 null 就停。跨页用 barcode 去重。关键词页里会混进只是标题提到该词的配件、贴膜、手机壳,搜索不是 GTIN 解析器,也不能当「这个品牌下面所有正装」。
稀疏记录和缺头的商店
字段深浅跟目录熟不熟有关,跟品牌响不响无关。同一条流水线里会同时碰到三种货。
饮料 EAN 可能只给一个词的 title,brand 是 null,online_stores 是 null,nutrition_facts 却是一长串。榛子酱可能描述很长、attributes 很全、店报价有好几条,但 nutrition_facts、ingredients、brand 仍是 null。书可能有 author、封面 images 和二手市场的 online_stores,同时 attributes 是 []、manufacturer 是 null。把「名品一定字段齐」写进断言,第一天就会红。
扫码入库按这四步走:
- 没有
product、results为空 → 目录没有。记found: false,转人工补录。不要当故障原地重试;HTTP 200 加空数组是业务层未收录,隔一阵再复核可以,紧循环只会烧额度。 - 有
product但online_stores空或 null → 你有身份,没有比价表。标题和类目照样能预填。 attributes不是 dict → 跳过 ASIN/MPN,别崩。- 食品没有
nutrition_facts→ 留下标题和空位,不要补零,也不要显示成「0 千卡」。
CSV 批量增强也是同一套走法:保留原条码、是否命中,以及通过存在性检查的字段。一列条码进、一列结构化行出,缺的格子就空着,比编造完整行更安全。
别当成实时库存
这份 JSON 是目录快照。它不是库存在架数量,不是你本币的货架价,也不保证报价链接现在还能买到这个 SKU。比价插件、进销存、跨境预填都可以用它当起点,但不能把它当成仓里那一托的真相。
不要把 HTTP 200 或信封 code 200 当成「查到了」,去看 data.product。不要在数字条码上带 page,也不要在搜索里自己编页码。不要把搜索瘦行塞进指望 attributes、features、online_stores 的上架模板。不要把 online_stores[].price 当单一币种小数,更不要标成「现价」。不要把 attributes.asin 当成稳赚的 UPC→ASIN。不要把空 results 当传输失败来重试。不要把平台 Key 写进扫码 App 或公开仓库,查询 URL 会把它漏出去。
用它预填收货单、给 PIM 行补类目路径和图片、或从关键词收集候选条码。库存数量、结算价、仓库里到底有没有,仍以自己的系统为准。