加油站调价预案 API0 点切换前 2 小时拿到新牌价成品油调价有个固定痛点新价格当天 0 点生效但价格往往要到当天才知道。加油站的牌价、POS 结算单价、物流的次日报价都要在 0 点前准备好靠人守着刷公告既不现实也不准时。oilprice.advance就是为这个时间差准备的它在查询时把基准时间推后 2 小时因此只要平台已经录入下一批次价格你就能在新价生效前 2 小时查到它。接口是按年付费的套餐需后台授权包年内调用不额外扣费。接口速览关键事实说明接口地址https://api.xujian.tech/openapi/oilprice/advance接口编码oilprice.advance请求方式GET参数放 Query String鉴权方式请求头X-API-Key不做签名、时间戳或加密业务入参无必填province/city/district均可选不传返回全部地区返回核心字段effectiveDate/advance/total/list[]收费方式按年付费360 元/年需后台为该客户授权提前量固定2 小时不可配置包年内调用不额外扣费不消耗账户余额balance前后一致单次耗时服务端处理通常个位数毫秒costMs为真实耗时先说清楚能做什么、不能做什么接口只是在查询时把基准时间推后 2 小时。如果平台尚未录入下一批次你拿到的就是当前生效的价格advancefalse——这是正常结果不是报错。是否能提前拿到取决于平台是否已录入。一、哪些业务需要这一步场景具体用法加油站牌价预置前一晚轮询拿到新价写入待生效表0 点自动切换POS 与结算单价提前生成新的结算单价避免跨零点交易对不上账调价日切换对账0 点前后各查一次确认系统切价成功物流次日报价调价日前一天用新价报价避免 0 点后价格跳变造成亏损车队月度预算按即将生效的价格重算下月燃油预算调价提醒推送检测advance变为true时向运营 / 客户推送提醒财务毛利预估按新价测算调价后毛利变化辅助定价决策价格监测大屏大屏提前展示「即将生效」状态便于运营排班加油站排班确认有调价再安排人值守没有就不用加班会员优惠策略提前算出调价后的优惠力度避免优惠倒挂二、请求参数2.1 请求头参数名必填说明X-API-Key是开发者 API Key缺失或无效直接返回失败2.2 查询参数全部可选参数名类型示例说明provinceString重庆市 / 500000省名称或 6 位 adcode不传返回全部地区cityString杭州市 / 330100市名称或 6 位 adcodedistrictString西湖区 / 330106区县名称或 6 位 adcode地区匹配逻辑与实时接口一致区县 → 市 → 省逐级回落查不到则按省返回。名称需与标准行政区划名称完全一致如重庆市推荐直接传 6 位 adcode避免名称对不上导致返回空列表。三、返回字段3.1 顶层与 data字段类型说明codeint0成功非 0 失败统一为500msgString成功为success失败为具体原因dataObject业务数据失败时为nulldata 字段字段类型示例说明effectiveDateString2026-09-25返回价格批次的生效开始时间无数据时为nulladvancebooleantruetrue 尚未生效的新价格false 当前生效的价格totalint1本次返回条数listArray[…]价格明细字段与全量接口oilprice.all的list[]完全一致apiCodeStringoilprice.advance接口编码apiNameString提前查询发改委价格接口名称chargeTypeStringYEARLY本次计费方式balanceBigDecimal100.0000账户余额包年套餐内不扣费交易前后一致costMslong8服务端处理耗时毫秒不含公网传输时间3.2 list[] 明细字段字段类型说明effectiveDateString该行价格生效日期yyyy-MM-ddprovince/provinceCodeString省名称与 6 位 adcodecity/cityCodeString地市名称与代码null 全省统一价district/districtCodeString区县名称与代码null 全市统一价priceDiesel0/priceDiesel10/priceDiesel35BigDecimal0# / -10# / -35# 柴油价格元未维护时为nullpriceGas92/priceGas95/priceGas98BigDecimal92# / 95# / 98# 汽油价格元dataUpdateTimeString数据更新时间yyyy-MM-dd HH:mm:ss3.3 怎么判断拿到的是不是新价两种方式任选其一看advance字段——最直接比较effectiveDate与当天日期——effectiveDate大于今天就说明是尚未生效的批次。四、调用示例4.1 curl# 查全部地区curl-shttps://api.xujian.tech/openapi/oilprice/advance\-HX-API-Key: 你的APIKey# 只查重庆curl-s-Ghttps://api.xujian.tech/openapi/oilprice/advance\--data-urlencodeprovince500000\-HX-API-Key: 你的APIKey4.2 JavaHutoolimportcn.hutool.http.HttpRequest;importcn.hutool.json.JSONObject;importcn.hutool.json.JSONUtil;publicclassOilPriceAdvanceClient{privatestaticfinalStringAPI_URLhttps://api.xujian.tech/openapi/oilprice/advance;/** * 查询即将生效或当前生效的油价批次 * * param apiKey 开发者 API Key * param province 省名称或 adcode可为空 * return data 节点失败返回 null */publicstaticJSONObjectadvance(StringapiKey,Stringprovince){HttpRequestreqHttpRequest.get(API_URL).header(X-API-Key,apiKey).timeout(15000);if(province!null!province.isEmpty()){req.form(province,province);}JSONObjectjsonJSONUtil.parseObj(req.execute().body());if(json.getInt(code)null||json.getInt(code)!0){System.out.println(查询失败json.getStr(msg));returnnull;}returnjson.getJSONObject(data);}publicstaticvoidmain(String[]args){JSONObjectdataadvance(你的APIKey,500000);if(datanull){return;}booleanisNewdata.getBool(advance,false);System.out.printf(生效日期 %s是否新价%s共 %d 条%n,data.getStr(effectiveDate),isNew,data.getInt(total));}}4.3 Pythonimportrequestsdefoil_advance(api_key:str,province:strNone,city:strNone):返回 data 节点失败返回 Noneparams{}ifprovince:params[province]provinceifcity:params[city]city resprequests.get(https://api.xujian.tech/openapi/oilprice/advance,paramsparams,headers{X-API-Key:api_key},timeout15,)resultresp.json()ifresult.get(code)!0:print(查询失败,result.get(msg))returnNonereturnresult[data]if__name____main__:dataoil_advance(你的APIKey,500000)ifdata:print(data[effectiveDate],data[advance])4.4 JavaScriptasyncfunctionoilAdvance(apiKey,province){constparamsnewURLSearchParams();if(province)params.set(province,province);constrespawaitfetch(https://api.xujian.tech/openapi/oilprice/advance?${params},{headers:{X-API-Key:apiKey}});constresultawaitresp.json();if(result.code!0){thrownewError(result.msg);}returnresult.data;}五、返回示例已录入新价advance true{code:0,msg:success,data:{effectiveDate:2026-09-25,advance:true,total:1,list:[{effectiveDate:2026-09-25,provinceCode:500000,province:重庆市,cityCode:null,city:null,districtCode:null,district:null,priceDiesel0:7.41,priceDiesel10:7.86,priceDiesel35:8.20,priceGas92:8.02,priceGas95:8.48,priceGas98:9.55,dataUpdateTime:2026-09-24 22:05:00}],apiCode:oilprice.advance,apiName:提前查询发改委价格,chargeType:YEARLY,balance:100.0000,costMs:8}}尚无新价advance false返回当前生效价格属正常结果{code:0,msg:success,data:{effectiveDate:2026-09-11,advance:false,total:1,list:[{effectiveDate:2026-09-11,provinceCode:500000,province:重庆市,cityCode:null,city:null,districtCode:null,district:null,priceDiesel0:7.28,priceDiesel10:7.72,priceDiesel35:8.05,priceGas92:7.86,priceGas95:8.31,priceGas98:9.36,dataUpdateTime:2026-09-11 09:00:00}],apiCode:oilprice.advance,apiName:提前查询发改委价格,chargeType:YEARLY,balance:100.0000,costMs:7}}未授权{code:500,msg:接口未授权或授权已过期,data:null}六、可直接复用的两段代码6.1 调价日前一晚轮询拿到新价就写入待生效表importtimefromdatetimeimportdatetimedefwait_for_new_price(api_key:str,province:strNone,interval:int600,rounds:int36):调价日前一晚 22:00 起轮询拿到 advanceTrue 就返回for_inrange(rounds):dataoil_advance(api_key,province)ifdataanddata.get(advance):print(f[{datetime.now():%H:%M}] 已拿到新价生效日期{data[effectiveDate]})returndata time.sleep(interval)print(本轮未拿到新价按当前价格执行)returnNone6.2 0 点前后各查一次确认切价成功defverify_switch(api_key:str,expect_date:str,province:strNone):0 点后用实时接口复查确认生效日期已切到新批次fromdatetimeimportdate dataoil_advance(api_key,province)ifnotdata:returnFalseokdata.get(effectiveDate)expect_dateprint(f期望{expect_date}实际{data.get(effectiveDate)}切价{成功ifokelse失败})returnok七、实践建议把advancefalse当正常结果处理。它只是说明平台还没录入下一批代码里不要把它当异常去重试或告警。用oilprice.cycle决定哪天需要轮询。调价周期接口免费拿到调价日期后只在当天 / 前一天晚上跑不用天天守。提前量固定 2 小时。不能配置所以轮询窗口就设在调价日前一晚 22:00 之后。写进待生效表0 点切换。不要把新价直接覆盖当前价用「待生效 定时切换」的方式出问题可回滚。跨零点交易要按日期归属价。0 点前下单按旧价、0 点后按新价别按查询时间判断。包年内不额外扣费。既然按年付费轮询可以密一些10 分钟一次也无所谓但别把请求打到百万级。地区参数用 adcode。名称必须完全匹配标准名称传「重庆」会返回空列表。list[]里的价格可能是null。某些油品某地区未维护如南方多无 -35# 柴油展示写「暂无」不要当 0。八、错误码与排查codemsg是否扣费0success包年内不扣费500缺少请求头 X-API-Key否500API Key 无效 / API Key 已停用否500客户不存在或已停用否500接口不存在或已停用否500接口未授权或授权已过期否本接口是包年模式不会出现「余额不足」类错误包年内调用不消耗账户余额balance前后一致。九、计费与接入项目说明收费方式按年付费YEARLY360 元/年是否需要授权是需后台为该客户开通授权并设定有效期包年内调用不额外扣费不消耗账户余额balance前后一致不计费场景Key 缺失 / 无效、客户停用、接口停用、未授权或授权过期提前量固定 2 小时不可配置接入流程注册开发者账号 → 联系平台开通本接口的按年授权 → 控制台创建 API Key → 请求头带上X-API-Key即可调用无需签名或加密。控制台可查看调用量、扣费流水与余额。服务站点api.xujian.tech纯文本域名不做跳转。接口试用、授权与充值咨询可在控制台提交工单或 Vxujian_cq。十、小结这个接口解决的是一个很具体的时间差问题新价 0 点生效但业务要提前准备好。它的能力边界也很清楚——只在平台已录入下一批次时才能提前 2 小时拿到advancefalse是正常结果。四条使用要点按年付费、包年内随便调授权后不用再按次算钱轮询成本可以接受先看advance再看effectiveDate两个字段都能判断是否新价配合oilprice.cycle排程免费接口告诉你哪天该干活写待生效表而不是直接覆盖0 点切换出问题还能回滚。配套接口oilprice.realtime0.01 元/次查当前生效价、oilprice.all5 元/次一次拉全国、oilprice.cycle免费调价日期列表。