跳到主要内容
开发者平台

基于
CouthActs 开发。

面向 AI 助手的智能体 API 和 MCP 服务器、面向调度和车载信息系统的服务商 API，以及用于核验已签名监管记录的公开接口。基于 HTTPS 的简洁 JSON，使用 Bearer 密钥。

获取 API 密钥 联系我们

密钥与限额

选择您的密钥。

智能体密钥

无方案费用

供代表客户账户操作的 AI 智能体和助手使用。

  • 由您选择权限：报价、任务、预订、钱包和信任
  • 单笔任务和每月支出限额，以及审批阈值
  • 每个密钥每分钟最多 120 次请求
  • 在“设置 → AI 智能体”中创建，或通过 OAuth 连接助手
创建智能体密钥

服务商 API

Basic 方案

供服务商连接自有调度或车载信息系统。

  • Basic：每月 500 次调用，超出后调用将被拒绝
  • 开放任务、您的预订、您的钱包和位置更新
  • Professional（每月 5,000 次调用）和 Enterprise：即将推出
  • 在“设置 → 服务商 API 密钥”中创建密钥
管理服务商密钥

客户 API

按约定

用于客户自己的任务、报价和钱包的 REST 接口。

  • Starter：每月 1,000 次调用，超出后调用将被拒绝
  • Growth：每月 5,000 次调用，超出后每次 US$0.20，于次月从您的钱包扣除
  • Enterprise：限额按约定
  • 密钥尚不支持自助开通；大多数客户应改用智能体密钥
联系我们

服务商 API 付费方案（Professional 和 Enterprise）即将推出；如现在就需要更高限额，请联系我们。您当前的方案和用量显示在“设置”中。API 不提供服务等级承诺。

快速开始

三步完成首次调用。

第 01 步

获取密钥

客户和 AI 智能体：设置 → AI 智能体。服务商：设置 → 服务商 API 密钥。完整密钥仅在创建时显示一次。

第 02 步

发出第一个请求

在 Authorization: Bearer 中发送您的密钥。服务商可以从 GET /api/provider/v1/jobs 开始。

第 03 步

了解智能体工具

智能体密钥：查看 /api/agent/openapi.json 中的 OpenAPI 描述，或将 MCP 客户端指向 /api/mcp。

示例请求

curl -X GET https://couthacts.com/api/provider/v1/jobs \
  -H "Authorization: Bearer ca_provider_your_key_here" \
  -H "Content-Type: application/json"

# Response
{
  "success": true,
  "data": [
    {
      "id": "clx...",
      "mode": "FREIGHT_TRUCKING",
      "title": "Freight: Dallas, TX → Houston, TX",
      "status": "OPEN",
      "originAddress": "Dallas, TX",
      "destinationAddress": "Houston, TX",
      "pickupDate": "2026-11-05T08:00:00.000Z",
      "budgetUsd": "2500",
      "insuranceTier": "NONE",
      "_count": { "bids": 3 }
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "pages": 1, "requestId": "…", "timestamp": "…" }
}

接口

完整参考。

API、代理和 MCP 响应中的所有金额均以美元计（以 Usd 结尾的字段）：CouthActs 只以美元收款和付款。如需显示本地货币等值，请每个界面调用一次 GET /api/currency/display，然后相乘：本地金额 ≈ amountUsd × rate。先显示美元金额，本地金额作为估算显示。

智能体 API 与 MCP

  • GET/api/agent/v1/tools

    列出您的智能体密钥可执行的操作及其输入结构。

    智能体密钥
  • POST/api/agent/v1/tools/{name}

    在密钥的权限、支出限额和审批规则范围内执行操作（例如 get_quote 或 post_job）。

    智能体密钥
  • GET/api/agent/openapi.json

    智能体工具的 OpenAPI 3.1 描述。

    无
  • POST/api/mcp

    通过模型上下文协议（MCP）提供相同操作，适用于 Claude、ChatGPT 及其他支持 MCP 的助手。

    智能体密钥 / OAuth

服务商 API

  • GET/api/provider/v1/jobs

    您登记的运输模式中的开放任务（可按模式筛选，分页返回）。

    服务商 API 密钥
  • GET/api/provider/v1/bookings

    您的预订，包括状态、追踪码和付款冻结状态。

    服务商 API 密钥
  • POST/api/provider/v1/tracking

    为进行中的预订上报位置；客户可见，并记录在监管记录中。

    服务商 API 密钥
  • GET/api/provider/v1/wallet

    您的钱包余额和近期交易。

    服务商 API 密钥

客户 API

  • GET · POST/api/v1/jobs

    列出您的任务，或发布任务（扣除费用并从钱包冻结预算）。

    客户 API 密钥
  • GET · PATCH/api/v1/jobs/{id}

    获取单个任务，更新其预算或描述，或取消任务。

    客户 API 密钥
  • GET · POST/api/v1/bids

    列出您任务收到的报价，或接受、拒绝报价。

    客户 API 密钥
  • GET/api/v1/wallet

    您的钱包余额。

    客户 API 密钥

公开（无需密钥）

  • GET/api/track/{code}

    通过追踪码获取预订的状态、路线和追踪事件。不含财务数据。

    无
  • GET/api/custody/public/{trackingCode}

    预订监管记录完整无改动的公开证明（事件类型、时间、哈希和签名）。

    无
  • GET/api/credentials/provider/{id}

    服务商的已签名凭证（验证状态和履约记录）。

    无
  • GET/.well-known/couthacts-keys.json

    CouthActs 用于核验签名的 Ed25519 公钥。

    无
  • POST/api/trust/verify

    核验监管证书或服务商凭证。

    无
  • GET/api/currency/display

    用户的显示货币及其对美元汇率（无实时汇率时 rate 为 null：仅显示美元）。

    无
  • GET/api/currency/supported

    供选择器使用的显示货币：代码、名称、符号和小数位数。

    无

服务商追踪

从您的系统上报位置。

为已确认或进行中的预订发送位置。位置会实时显示给客户，并作为检查点记录在已签名的监管记录中。您可以用图层名称标注每条读数的来源。CouthActs 会记录该标注，但不会自行接入或核验 AIS、航班、ELD、传感器或卫星数据：数据即为您上报的内容。

可接受的图层标注

MOBILE_GPS

移动 GPS

来自手机或车载 GPS 的位置（默认）。

AIS_MARITIME

AIS（海运）

来自您 AIS 数据源的船舶位置。

FLIGHT_TRACKING

航班追踪

来自您航班追踪数据源的飞机位置。

ELD_INTEGRATION

ELD

来自您电子行车记录设备的卡车位置。

QR_PIN_CONFIRMATION

PIN 交接

交接时的位置。交付 PIN 本身在应用中输入。

IOT_DEVICE

物联网设备

来自您追踪器的位置。不保存传感器读数。

SATELLITE

卫星

来自您卫星追踪器的位置。

DOCUMENT_POD_AI

交付证明

仅为位置标注。CouthActs 不分析文件。

BIOMETRIC

生物识别

仅为位置标注。CouthActs 不在交接时进行生物识别核验。

上报位置

POST /api/provider/v1/tracking
Authorization: Bearer ca_provider_your_key_here
Content-Type: application/json

{
  "bookingId": "clx...",
  "lat": 32.7767,
  "lng": -96.7970,
  "layer": "MOBILE_GPS",
  "status": "IN_TRANSIT",
  "note": "Departed Dallas warehouse"
}

认证与安全

访问如何受控。

Bearer 密钥

每个请求都需要 Authorization: Bearer。密钥在“设置”中创建，只显示一次，可随时撤销。

仅限 HTTPS

仅通过 HTTPS 发送密钥。切勿将密钥嵌入公开代码或客户端应用。

限额

智能体密钥：每分钟 120 次请求。服务商和客户 API 密钥：其方案的每月调用次数，通过 X-RateLimit-Limit 和 X-RateLimit-Remaining 响应头返回。

活动日志

每个智能体操作都会记录所用工具、状态、金额、输入和结果，并显示在“设置”中。服务商密钥会显示请求次数和最近使用时间。

支出限额与审批

智能体密钥不能超出单笔任务或每月限额，超过审批阈值的操作需等待账户所有者批准（请求在 72 小时后失效）。

签名的是记录，而非请求

监管记录和服务商凭证使用 CouthActs 的 Ed25519 密钥签名，任何人都可以核验。API 请求和响应不签名，CouthActs 也不发送出站 Webhook。

响应格式

一致，可预期。

服务商 API 和客户 API 的响应采用下方格式。智能体 API 的响应则包含 status、actionId 和 result 字段；请参阅 OpenAPI 描述。

成功（2xx）

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_...",
    "timestamp": "2026-04-01T..."
  }
}

错误（4xx/5xx）

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "bookingId, lat, lng required"
  },
  "meta": {
    "requestId": "req_...",
    "timestamp": "2026-04-01T..."
  }
}
欢迎开发者

准备好 集成了吗？

在“设置”中创建密钥，几分钟内即可完成首次调用。如需更高限额或 Enterprise 方案，请联系我们。

获取 API 密钥 联系我们