跳转到内容
TrakarIA TrakarIA Docs

快速开始

目前公开 API 支持 Rental。你的系统可以同步车辆和 Rental 业务档案、准备检查，并读取已验证的结果。API 参考是每个请求和响应的准确契约。

1. 创建 API 密钥

Section titled “1. 创建 API 密钥”

组织管理员在 TrakarIA 的 API 与集成 页面创建密钥。API 使用权限取决于组织的 Rental 套餐。每个集成系统应使用单独的密钥；完整密钥只显示一次。参阅身份验证与访问控制。

基础地址为 https://api.trakaria.com。使用密钥发出的请求会操作账号中的真实数据。

2. 检查访问权限和实际限制

Section titled “2. 检查访问权限和实际限制”

在终端中设置密钥，且不要将其提交到源代码仓库，然后发送只读请求：

Terminal window
export TRAKARIA_API_KEY='your-api-key'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  https://api.trakaria.com/v1/capabilities

响应会给出当前组织可用的 Rental 功能与限制。401 表示凭证无效或已过期；403 可能表示该操作或套餐不可用。参阅同步规则与错误处理。

3. 同步车辆和 Rental 档案

Section titled “3. 同步车辆和 Rental 档案”

测试时请使用易于识别且不会冲突的外部 ID，并避免使用真实客户信息。以下请求会在账号中创建数据。再次使用同一外部 ID 会更新同一资源；请保存响应中的公开 id。

Terminal window
curl --fail-with-body --silent --show-error \
  -X PUT 'https://api.trakaria.com/v1/vehicles/by-external/demo-vehicle-001' \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"plate":"AA-123-AA","name":"Demo vehicle","photo_url":"https://cdn.example.com/fleet/demo-vehicle-001.jpg","make":"Example","model":"Car","trim":"Business","year":2025,"registration_date":"2025-03-20","vehicle_type":"hatchback","energy":"petrol","gearbox":"automatic","transmission":"fwd","color":"Blue","mileage":12000,"source_revision":1}'


curl --fail-with-body --silent --show-error \
  -X PUT 'https://api.trakaria.com/v1/rentals/by-external/demo-reservation-001' \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"vehicle_external_id":"demo-vehicle-001","source_revision":1}'

第二个请求会立即在计划中创建可见条目。响应同时包含 Rental id 和 planning.entry_id。请求体中只有 vehicle_external_id 必填；计划时间、业务编号、地点、联系人和驾驶人均为可选，可以提前、在现场交车时或之后补充。未提供交车时间时，TrakarIA 使用创建时间；未提供还车时间时，计划保持开放。

后续修改必须使用严格递增的 source_revision。省略字段会保留当前值，并更新同一个计划条目而非创建重复条目。车辆 upsert 成功后，也会把车辆分配给 API 密钥所属组织，使该组获授权用户可以看到车辆；重复发送未变更的 upsert 可安全修复缺失的关联。

测试后请在 TrakarIA 中检查并按组内可用操作清理数据。公开 API 可在交车前通过 POST /v1/rentals/{rental_id}/cancel 取消 Rental 及其计划条目，但不提供车辆或 Rental 的通用 DELETE；取消不会抹除历史。

4. 继续检查流程

Section titled “4. 继续检查流程”

使用第二个请求返回的公开 Rental id 准备交车检查，不要使用外部 ID 或计划 ID：

Terminal window
export RENTAL_ID='rental_...'
export DEPARTURE_IDEMPOTENCY_KEY="departure-${RENTAL_ID}"


curl --fail-with-body --silent --show-error \
  -X POST "https://api.trakaria.com/v1/rentals/${RENTAL_ID}/inspections" \
  -H "Authorization: Bearer ${TRAKARIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${DEPARTURE_IDEMPOTENCY_KEY}" \
  -d '{"type":"departure"}'

该调用会创建或恢复同一个检查：201 表示新建，200 表示已存在。发生超时、断网、503 或 REQUEST_ALREADY_PROCESSING 时，必须用**相同的方法、路径、请求体和 Idempotency-Key**重试。不要新建 Rental 或外部 ID。也不要发送 Kernel 的私有并发字段，例如 cycle ID、revision、ETag、If-Match 或 expectedRevision。

TrakarIA 用户必须登录并打开返回的 launch_url，由本人完成车辆状况验证；API 调用不会代替人工验证。完成交车后读取 departure 报告；还车时准备 return 检查并读取 comparison 报告。继续阅读 Rental 工作流、API 参考和Webhook。