Developer Ecosystem
基于 SyncVelo，构建出行的未来
面向车队设备、位置、行程、告警、报表和司机的开放、安全、带版本的接口，配有签名 Webhook、TypeScript SDK 和沙盒。
- REST 与 OpenAPI
- 签名 Webhook
- TypeScript SDK
- 模拟车辆沙盒
1const api = 'https://api.syncvelo.com';2const { SYNCVELO_CLIENT_ID: id, SYNCVELO_CLIENT_SECRET: secret, SYNCVELO_ORG: org } = process.env;3 4const { access_token } = await fetch(`${api}/oauth/token`, {5 method: 'POST',6 headers: { Authorization: `Basic ${btoa(`${id}:${secret}`)}` },7 body: new URLSearchParams({ grant_type: 'client_credentials' }),8}).then((r) => r.json());9 10// Cursor pagination: follow next_cursor until it is null11let cursor: string | null = null;12do {13 const url = new URL(`${api}/v1/tenants/${org}/devices?limit=100`);14 if (cursor) url.searchParams.set('cursor', cursor);15 const page = await fetch(url, { headers: { Authorization: `Bearer ${access_token}` } }).then((r) => r.json());16 for (const d of page.items) console.log(d.id, d.status, d.latitude, d.longitude, d.speed_kph);17 cursor = page.next_cursor;18} while (cursor);接入方式
多种接入方式，内置管控能力
每种接入方式从第一天起就在设计中融入了授权、租户隔离与可审计性。
公共 REST 与 OpenAPI
设备、位置、行程、地理围栏、规则、告警、报表和司机，支持游标分页和明确的版本。
管控措施: OAuth2 客户端凭证、权限范围、速率限制和每日配额。
事件 Webhook
告警、地理围栏进出和已完成行程，签名投递、退避重试，并可重放。
管控措施: 密钥轮换不丢事件；每个客户端只属于一个组织。
TypeScript SDK
由 OpenAPI 文档生成的类型化客户端；自动跟随游标，仅在安全时重试。
管控措施: 语义化版本与兼容性测试。
沙盒
一个独立的组织，配有模拟车辆、示例行程和测试 Webhook，可按需重置。
管控措施: 在根级隔离：无上级组织，无法访问真实数据。
控制台中的开发者页面
API 客户端、权限范围和 Webhook 端点由组织所有者管理，并附 API 参考。
管控措施: 密钥只显示一次，仅以指纹形式保存。
数据转发与 MQTT
转发到其他平台和政府服务器，并为集成商提供 MQTT。规划中（X5）。
管控措施: 目前尚不可用。
REST 与 OpenAPI
尊重租户边界、可预期的 API
面向资源的端点，支持游标分页、筛选、幂等键与显式版本。每个请求都携带完整的租户策略。
- OAuth2 客户端凭证，支持细粒度权限范围
- 使用规范的 SyncVelo ID，绝不暴露引擎内部键值
- 写操作支持幂等键与安全重试
- 按客户端的速率限制与每日配额
1const api = 'https://api.syncvelo.com';2const { SYNCVELO_CLIENT_ID: id, SYNCVELO_CLIENT_SECRET: secret, SYNCVELO_ORG: org } = process.env;3 4const { access_token } = await fetch(`${api}/oauth/token`, {5 method: 'POST',6 headers: { Authorization: `Basic ${btoa(`${id}:${secret}`)}` },7 body: new URLSearchParams({ grant_type: 'client_credentials' }),8}).then((r) => r.json());9 10// Cursor pagination: follow next_cursor until it is null11let cursor: string | null = null;12do {13 const url = new URL(`${api}/v1/tenants/${org}/devices?limit=100`);14 if (cursor) url.searchParams.set('cursor', cursor);15 const page = await fetch(url, { headers: { Authorization: `Bearer ${access_token}` } }).then((r) => r.json());16 for (const d of page.items) console.log(d.id, d.status, d.latitude, d.longitude, d.speed_kph);17 cursor = page.next_cursor;18} while (cursor);Webhook
实时事件，可靠送达
订阅告警（触发、解除、确认、关闭）、地理围栏进出和已完成行程。每次投递都已签名，按退避策略重试，并可在 30 天内重放。
- HMAC 签名的负载，带时间戳容差校验
- 自动重试、死信队列与重放
- OpenAPI 文档中带版本的事件目录
- 可在控制台和 API 中查看的投递日志
1POST /your/webhook2webhook-id: 6f0c2d2e-1b55-8a4e-9c3f-8f9a2b7d1e403webhook-timestamp: 17923164674webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=5 6{7 "id": "6f0c2d2e-1b55-8a4e-9c3f-8f9a2b7d1e40",8 "type": "geofence.exited",9 "schema_version": "1.0",10 "organization_id": "1f7c…",11 "occurred_at": "2026-10-19T09:41:07.000Z",12 "created_at": "2026-10-19T09:41:08.214Z",13 "data": { "device_id": "8d2a…", "geofence_id": "c41e…" }14}SDK
类型化的 TypeScript 客户端，其他语言直接用 REST
TypeScript SDK 由 OpenAPI 文档生成，随沙盒访问一并提供，尚未发布到公共仓库。其他语言可直接调用 REST API。
TypeScript
面向服务器：Node.js 20+、Deno、Bun 和边缘运行时。类型化方法、自动跟随游标、安全重试和 Webhook 校验。
import { SyncVelo } from '@syncvelo/sdk'其他任何语言
Python、Java、Go 或任何能使用 HTTPS 的语言：像上面的示例一样使用 REST API 和 OpenAPI 文档。
GET https://api.syncvelo.com/openapi.json
集成生命周期
从首个 API 密钥到正式上线，全程受控
- 01
注册
组织所有者在控制台的开发者页面创建 API 客户端，只授予所需的权限范围。
- 02
授权
客户端用其 ID 和密钥换取短期访问令牌（OAuth2 客户端凭证）。
- 03
订阅
注册 Webhook 端点、发送测试事件，并先在沙盒中试用一切。
- 04
运行
每个请求均应用配额、幂等、重试与完整的租户策略。
- 05
观测
投递日志、失败投递重放、密钥轮换与吊销。