E EvoCow Partner API
supplier draft EvoCow OpenAPI 硬件 OpenAPI 接入说明
Partner integration contract · Draft

EvoCow 软件供应商接入接口

本文档提供给接入 EvoCow 的软件与硬件供应商研发团队。它说明你方需要调用哪些 EvoCow 接口，以及你方必须提供哪一条硬件数据查询接口。

当前状态：接口草案。 字段与调用方向可用于联调评审，但生产域名、API Key 和硬件拉取凭证将在正式接入时单独提供。
01

只使用一个外部主体 ID

subject_id 是牛只在你方系统中的稳定 ID，用于处方关联和硬件查询。

02

硬件数据由 EvoCow 拉取

你方不在处方或报告中上传大段时序数据，只提供时间范围和标准查询接口。

03

最终报告由三类数据组成

人工反馈、全量对话由你方回传；硬件数据由 EvoCow 按时间窗口主动查询。

01

Ownership

先分清两个调用方向

你方 → EvoCow

处方与结果回传

你方软件使用 EvoCow API Key，创建处方、追加现场观察，并在处置结束后提交人工反馈和全量对话。 

POST /v1/prescriptions
PUT  /v1/prescriptions/{id}
PUT  /v1/prescriptions/{id}/report
EvoCow → 你方

硬件时序数据拉取

你方提供稳定 HTTPS 地址和拉取 Token。EvoCow 根据 subject_id 与时间范围查询标准化时序数据。 

GET /evocow/v1/subjects/{subject_id}/hardware-data
02

Conventions

鉴权与幂等

调用 EvoCow

使用 EvoCow 分配给你方的 API Key。所有 POST/PUT 还必须携带唯一的幂等键。

Authorization: Bearer <EVOCOW_API_KEY>
Idempotency-Key: <UNIQUE_KEY>

EvoCow 调用你方

你方为 EvoCow 配置独立的只读 Pull Token，不应与管理后台或其他客户共用。

Authorization: Bearer <EVOCOW_PULL_TOKEN>
接入时你方需提供：硬件 API Base URL、测试 Pull Token、生产 Pull Token，以及测试用 subject_id。这些信息不放在业务请求正文中。
03

Prescription results

处方的三种返回结果

三种结果统一返回 id + status + content。你方应按 status 驱动后续流程，并把 content 原样交给 Agent 或现场人员。

needs_more_information

信息不足。展示 content 中的问题，收集新观察后继续 PUT。

{
  "id": "rx_01JEVOCOW001",
  "status": "needs_more_information",
  "content": "请观察呼吸是否费力、能否正常站立。"
}
ready

信息足够。content 是当前处置建议，处方不再接受新观察。

{
  "id": "rx_01JEVOCOW001",
  "status": "ready",
  "content": "建议尽快联系驻场兽医检查，并持续记录体温。"
}
urgent_escalation

存在紧急风险。立即转人工或兽医，不等待其他信息补齐。

{
  "id": "rx_01JEVOCOW002",
  "status": "urgent_escalation",
  "content": "发现无法站立并伴随呼吸费力，请立即联系兽医。"
}
POST

/v1/prescriptions

你方用自己的牛只 ID 和第一条现场观察创建处方，同时指定 EvoCow 需要查询的硬件时间范围。

Request 
curl "$EVOCOW_BASE_URL/v1/prescriptions" \
  -X POST \
  -H "Authorization: Bearer $EVOCOW_API_KEY" \
  -H "Idempotency-Key: rx-create-001" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "cow-10086",
    "observation": "这头牛今天不吃草，精神很差。",
    "hardware_query": {
      "from": "2026-07-13T00:00:00Z",
      "to": "2026-07-13T08:30:00Z"
    }
  }'
201 Response 
{
  "id": "rx_01JEVOCOW001",
  "status": "needs_more_information",
  "content": "请观察呼吸是否费力、能否正常站立。"
}
PUT

/v1/prescriptions/{id}

追加一条新观察。无需重复 subject_id；需要新硬件数据时，附带新的查询时间范围。

Request 
curl "$EVOCOW_BASE_URL/v1/prescriptions/rx_01JEVOCOW001" \
  -X PUT \
  -H "Authorization: Bearer $EVOCOW_API_KEY" \
  -H "Idempotency-Key: rx-observation-002" \
  -H "Content-Type: application/json" \
  -d '{
    "observation": "呼吸不费力，可以站立，但反刍明显减少。",
    "hardware_query": {
      "from": "2026-07-13T08:30:00Z",
      "to": "2026-07-13T10:00:00Z"
    }
  }'
200 Response 
{
  "id": "rx_01JEVOCOW001",
  "status": "ready",
  "content": "建议尽快联系驻场兽医检查，并持续记录体温。"
}
GET

/v1/prescriptions/{id}

读取处方的最新状态与内容，不返回 EvoCow 内部推理或硬件原始数据。

Request 
curl "$EVOCOW_BASE_URL/v1/prescriptions/rx_01JEVOCOW001" \
  -H "Authorization: Bearer $EVOCOW_API_KEY"
PUT

/v1/prescriptions/{id}/report

处置结束后，你方回传人工反馈、全量对话和最终硬件查询窗口。EvoCow 接受请求后异步拉取硬件数据，因此返回 202。

Request 
curl "$EVOCOW_BASE_URL/v1/prescriptions/rx_01JEVOCOW001/report" \
  -X PUT \
  -H "Authorization: Bearer $EVOCOW_API_KEY" \
  -H "Idempotency-Key: rx-report-001" \
  -H "Content-Type: application/json" \
  -d '{
    "human_feedback": "兽医处置后 24 小时体温下降，采食开始恢复。",
    "conversation": [
      {"role": "user", "content": "这头牛今天不吃草，精神很差。"},
      {"role": "assistant", "content": "请观察呼吸是否费力、能否正常站立。"},
      {"role": "user", "content": "呼吸不费力，可以站立，但反刍明显减少。"}
    ],
    "hardware_query": {
      "from": "2026-07-13T00:00:00Z",
      "to": "2026-07-14T08:00:00Z"
    }
  }'
202 Response 
{
  "id": "rpt_01JEVOCOW001",
  "prescription_id": "rx_01JEVOCOW001",
  "status": "collecting_hardware",
  "received_at": "2026-07-14T09:30:00Z"
}
GET

/v1/prescriptions/{id}/report

查询 EvoCow 是否已经从你方硬件接口完成数据拉取。终态为 complete 或 hardware_sync_failed。

Request 
curl "$EVOCOW_BASE_URL/v1/prescriptions/rx_01JEVOCOW001/report" \
  -H "Authorization: Bearer $EVOCOW_API_KEY"
200 Response 
{
  "id": "rpt_01JEVOCOW001",
  "prescription_id": "rx_01JEVOCOW001",
  "status": "complete",
  "received_at": "2026-07-14T09:30:00Z"
}
04

API you must provide

你方必须提供：硬件数据查询接口

这条接口部署在你方系统，由 EvoCow 调用。它不是 EvoCow 提供给你方调用的接口。
GET

/evocow/v1/subjects/{subject_id}/hardware-data

按牛只 ID 和半开时间区间 [from, to) 返回标准化的硬件时序序列。所有时间使用 ISO 8601 UTC。

EvoCow → 你方 Request 
curl "$SUPPLIER_BASE_URL/evocow/v1/subjects/cow-10086/hardware-data?from=2026-07-13T00%3A00%3A00Z&to=2026-07-14T08%3A00%3A00Z&limit=1000" \
  -H "Authorization: Bearer $EVOCOW_PULL_TOKEN"
200 Response 
{
  "subject_id": "cow-10086",
  "from": "2026-07-13T00:00:00Z",
  "to": "2026-07-14T08:00:00Z",
  "series": [
    {
      "metric": "body_temperature",
      "label": "体表温度",
      "unit": "Cel",
      "device_id": "ear-sensor-42",
      "points": [
        {"at": "2026-07-13T08:00:00Z", "value": 40.2, "quality": "good"},
        {"at": "2026-07-14T08:00:00Z", "value": 39.3, "quality": "good"}
      ]
    }
  ],
  "next_cursor": null
}

查询规则

from 必须早于 to；无数据返回 200 和空 series；subject_id 不存在返回 404；超过单页时返回 next_cursor。

指标规则

metric 必须稳定，unit 使用 UCUM 代码；points 按时间升序；同一 cursor 重试必须返回一致结果。

你方实现依据：hardware-provider-openapi.yaml

05

Schemas

核心字段定义

CreatePrescriptionInput

字段 类型 必填 说明
subject_id string 是 牛只在你方系统中的稳定 ID；后续硬件查询原样使用。
observation string 是 一条自然语言现场观察，不超过 8 KB。
hardware_query object 是 本次判断所需硬件数据的 from/to UTC 时间范围。

ReportInput

字段 类型 必填 说明
human_feedback string 是 现场人员对执行过程和结果的自然语言总结。
conversation JSON object | array 是 你方系统保留的全量原始对话。
hardware_query object 是 最终报告覆盖的硬件数据 from/to UTC 时间范围。

HardwareSeries

字段 类型 必填 说明
metric string 是 你方定义的稳定指标代码，例如 body_temperature。
label string 是 指标的人类可读名称。
unit string 是 UCUM 单位代码，例如 Cel、min、1。
device_id string 否 产生数据的设备 ID，仅用于排障与审计。
points array 是 按 at 升序的数值点，每个点包含 at、value，可选 quality。
完整报告在 EvoCow 内部由三类数据合并：你方提交的 human_feedback、你方提交的 conversation、EvoCow 从你方 Hardware API 拉取的时序数据。

机器契约：EvoCow Partner OpenAPI · Hardware Provider OpenAPI