供应商对接接口

Supplier Integration API

WMS 与劳务商系统之间的人员、叉车证、考勤数据通道。本文为提议版接口契约，字段与规则可按你们实际调整。

The data channel between WMS and supplier systems for workers, forklift certification, and attendance. This is a proposed contract — fields and rules are adjustable to your operation.

1 · 总览

1 · Overview

基础地址 https://api.flexdock.example/v1 · 全程 HTTPS · 请求/响应均为 JSON · 版本通过路径前缀（/v1）管理。

Base URL https://api.flexdock.example/v1 · HTTPS only · JSON request/response · versioned by path prefix (/v1).

两种对接模式

Two integration modes

• 模式 A（推荐给有系统的供应商）：供应商接入我方 API，轮询需求、提交人员、读取试工与考勤结果。
• Mode A (for vendors with a system): the vendor calls our API to poll requests, submit workers, and read tryout/attendance results.
• 模式 B（WMS 主动拉取）：供应商暴露一个只读候选人端点，由我方 WMS 定时拉取人员与叉车证（你之前选的方向）。
• Mode B (WMS-initiated pull): the vendor exposes a read-only candidates endpoint and our WMS pulls workers + certs on a schedule (the direction you chose).
• 无系统的供应商：直接用 FlexDock 供应商门户网页填报，无需对接。
• Vendors without a system: use the FlexDock supplier portal in the browser — no integration needed.

2 · 认证与数据隔离

2 · Authentication & Data Isolation

每个供应商分配一把 API Key，绑定唯一 vendor_id。请求头携带：

Each vendor gets an API key bound to a unique vendor_id. Send it in the header:

Authorization: Bearer vk_live_3a9f...e21
Content-Type: application/json
Idempotency-Key: 8f14e45f   # POST 去重，可选

3 · 端点

3 · Endpoints

3.1 获取派给本公司的需求

3.1 List requests assigned to you

查询参数：status（open / filling / tryout / closed）、shift、date。仅返回本 vendor_id 的需求。

Query params: status (open / filling / tryout / closed), shift, date. Returns only your vendor_id's requests.

{
  "data": [{
    "request_id": "REQ-2402",
    "role": "forklift",
    "shift": "night",
    "headcount_needed": 4,
    "tryout_buffer": 6,          # 多要人来试工：需 4 报 6
    "forklift_required": true,
    "report_time": "2026-06-22T19:00:00-04:00",
    "location": "Ontario DC-3",
    "urgent": false,
    "status": "open"
  }]
}

3.2 提交回填人员（含叉车证）

3.2 Submit candidates (with forklift cert)

模式 B 下，等价于 WMS 调用供应商的 GET /candidates?request_id= 拉取同样结构。

In Mode B this maps to WMS calling the vendor's GET /candidates?request_id= returning the same shape.

{
  "candidates": [{
    "external_worker_id": "V-B-10293",   # 供应商侧唯一ID，用于去重
    "full_name": "Diego R.",
    "role": "forklift",
    "source": "indeed",
    "report_time": "2026-06-22T19:00:00-04:00",
    "location": "Ontario",
    "bill_rate": 27.0,                    # 仅本供应商可见
    "forklift_cert": {
      "status": "valid",                  # valid | pending | none
      "cert_no": "ON-FLT-88421",
      "expires_on": "2027-03-01"
    }
  }]
}

3.3 填不满时提交卡点原因

3.3 Report a shortfall reason

{
  "filled_count": 2,
  "reason": "Local pool thin this week; contacted 3 channels, still short."
}

reason 服务端强制 ≥ 40 字符，过短返回 422。原因留档，供供应商内部反思与我方评估。

reason must be ≥ 40 chars (server-enforced); shorter returns 422. Stored for the vendor's review and our evaluation.

3.4 读取试工结果

3.4 Read tryout outcomes

{
  "results": [
    { "external_worker_id": "V-B-10293", "outcome": "retained" },
    { "external_worker_id": "V-B-10311", "outcome": "released" }   # 试工不计费
  ]
}

3.5 考勤同步（只读 + 改动留痕）

3.5 Attendance sync (read-only + audit)

考勤以现场签到为准，供应商只读。任何修改都带留痕，用于 HRBP 的考勤修改率监控。

Site check-in is the source of truth; vendors read only. Every change carries an audit trail feeding HRBP's attendance-modification-rate monitoring.

{
  "records": [{
    "external_worker_id": "V-C-77210",
    "request_id": "REQ-2403",
    "status": "no_show",            # present | no_show | scheduled
    "check_in": null,
    "modification": {               # 有改动时出现
      "modified_by": "hrbp.ontario",
      "modified_at": "2026-06-22T16:40:00-04:00",
      "from": "present", "to": "no_show",
      "reason": "Left after 1h, corrected by floor lead"
    }
  }]
}

4 · 错误码

4 · Error Codes

5 · 关键字段

5 · Key Fields