开发者

供应商 API

一个端点。发布一个价格数组，获取哪些已发布、哪些被暂扣。无需安装 SDK，也无需为集成安排通话——若您的系统已有当日数字，这只是一次 HTTP 请求。

获取密钥

打开供应商门户，填入您报价台所用的地址。收到的链接会为您登录，密钥就在该页面上。密钥以 bfps_ 开头，且永不过期；您可从同一页面轮换密钥。

请将其视同密码。任何持有它的人都能以您的名义发布价格，而归于您名下的错误价格对您的损害大于对我们的损害。

发布价格

POST https://bunkerfuelprices.com/api/v1/supplier/prices

curl -X POST https://bunkerfuelprices.com/api/v1/supplier/prices \
  -H "Authorization: Bearer bfps_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prices": [
      { "port": "SGSIN", "grade": "VLSFO", "amount": 784.50 },
      { "port": "SGSIN", "grade": "MGO",   "amount": 1146.00 },
      { "port": "AEFJR", "grade": "VLSFO", "amount": 795.00,
        "minMt": 200, "validHours": 24, "basis": "delivered" }
    ]
  }'

字段

字段	类型		说明
port	string	required	UN/LOCODE，五个字母——SGSIN、NLRTM、AEFJR。不是港口名称。未知代码仅该行被拒，其余仍会发布。
grade	enum	required	VLSFO · HSFO · MGO · ULSFO · LNG · B24 · B30
amount	number	required	价格，采用下方的币种和单位。
currency	USD \| EUR	optional	默认为 USD。EUR 按当日 ECB 参考汇率实时换算。
unit	mt \| litre \| m3	optional	默认为 mt。每升数字按该油品的密度换算。
basis	delivered \| ex_wharf \| fob	optional	默认为 delivered。这一点很重要：将码头交货价当作船边交货价显示会低估买家实际支付的金额，而我们只在同一交货基准内进行比较。
minMt	number	optional	该价格适用的最小批量。
validHours	1–168	optional	有效时长。默认为 24，之后会被标记为过时，而非显示为当前价。
taxIncluded	boolean	optional	默认为 false。主要与游艇泊位相关。

响应

{
  "accepted": 3,
  "published": 2,
  "held": 1,
  "results": [
    { "port": "SGSIN", "grade": "VLSFO", "ok": true, "published": true,
      "submissionId": "..." },
    { "port": "SGSIN", "grade": "MGO",   "ok": true, "published": true,
      "submissionId": "..." },
    { "port": "AEFJR", "grade": "VLSFO", "ok": true, "published": false,
      "heldForReview": ["38% away from the $795 median across 6 other ports"] }
  ]
}

与其他港口市场价相差甚远的行会被暂扣，等待人工查看，而非发布。这并非对您的怀疑——而是防止一个错输的数字变成买家据以行动的价格，它对您名号的保护更甚于对我们的。被暂扣的价格通常当日即会放行。

各行相互独立。一个坏行不会导致整批被拒。

读回我们所持有的数据

curl https://bunkerfuelprices.com/api/v1/supplier/prices \
  -H "Authorization: Bearer bfps_YOUR_KEY"

返回您最近一百条提交及其状态，让您无需自行记录我们接受了哪些内容即可对账。

公开价格板

开放访问，无需密钥，便于您在发布前查看自己的价格在整个市场中所处的位置。

curl "https://bunkerfuelprices.com/api/v1/prices?grade=VLSFO&limit=50"

错误与限制

状态	含义
200	已处理。请检查 results ——200 并不意味着每一行都已发布。
400	请求体无法解析。响应会指明字段。
401	密钥缺失、错误或已暂停。

每次请求最多 200 条价格。您可随时发布——多数报价台在早晨发布一次，市场波动时再发一次。重新发布同一港口和油品会取代先前的价格，而非重复发布。

我们如何处理它

您的价格会作为指示性价格出现在港口页面上，署您公司名，附上日期。查看该港口的买家看到的是您的名号旁附着一个数字，而非一片空白，询价会送达您手上，而非从您身边错过。

我们不是燃油供应商、贸易商或经纪商，对任何货物均不持交易头寸，因此我们对您的价格除了求其准确之外别无所图。完整细节见数据与定价政策。您可随时从门户撤回，或来函至 data@bunkerfuelprices.com.