时间与格式

JSON 与文本

请求体和响应体都是 UTF-8 编码的 JSON，Content-Type: application/json。文件上传使用 multipart/form-data。
字段名和枚举值采用 snake_case：next_retry_at、index_failed。
错误消息和 API 自身的文本是英文。您写入的文本（例如卡片标题）按原样返回，可以是任何语言。

所有时间都是 UTC 时区的 RFC 3339 时间戳：

{"created_at": "2026-10-24T10:00:00Z"}

较新的字段使用带 Z 的简短形式，如上所示。
一些早期就有的字段使用 2026-10-24T10:00:00.123456+00:00 形式，秒的小数部分最多六位。两种形式表示的都是 UTC 中的同一时刻。请用标准的 RFC 3339 解析器解析这两种形式，不要按字符串比较时间戳。
名称以 _at 结尾的字段都是时间戳。

发送的时间必须带时区偏移：Z 或数字偏移（例如 +02:00）。不带偏移的时间有歧义，会返回 422，错误码为 validation.failed。Sursa 把收到的所有时间都转换为 UTC。

const since = new Date(Date.now() - 24 * 3600 * 1000).toISOString(); // "2026-10-23T10:00:00.000Z"

在查询字符串中，+ 必须写作 %2B，否则会被当作空格。请对时间值做 URL 编码，或者使用 Z。

类型	形式	示例
不带时间的日期	`YYYY-MM-DD`，字段名以 `_date` 结尾	`"due_date": "2026-11-01"`
时长	整数，单位写在字段名中	`"interval_days": 90`、`"timeout_seconds": 30`
数量	整数，字段名以 `_count` 结尾	`"part_count": 12`
是或否	布尔值，字段名是不带 `is_` 的形容词	`"active": true`、`"sensitive": false`

财务类响应中的金额是十进制字符串，例如 "1250.00"，从不使用浮点数，以免损失精度。货币是单独的字段，值为 ISO 4217 代码，例如 "EUR"。请用所用语言中的十进制类型解析金额。

ID 是字符串还是整数，取决于对象。参见对象 ID。

取值固定的字段（例如状态）是字符串。响应中的每个枚举都可能在之后的版本中新增值：遇到不认识的值时按“其他”处理。参见版本与兼容性。