Chuyển tới nội dung
Sursa Developers

Thời gian và định dạng

JSON và văn bản

  • Phần thân yêu cầu và phản hồi là JSON mã hóa UTF-8, với Content-Type: application/json. Tải tệp lên dùng multipart/form-data.
  • Tên trường và giá trị enum viết theo snake_case: next_retry_at, index_failed.
  • Thông báo lỗi và các văn bản của API bằng tiếng Anh. Văn bản do bạn viết, chẳng hạn tiêu đề thẻ, được trả về đúng như bạn đã viết, bằng bất kỳ ngôn ngữ nào.

Thời gian

Mọi thời điểm là một dấu thời gian RFC 3339 theo UTC:

{"created_at": "2026-10-24T10:00:00Z"}
  • Các trường mới hơn dùng dạng ngắn với Z, như trên.
  • Một số trường có từ trước dùng dạng 2026-10-24T10:00:00.123456+00:00, với tối đa sáu chữ số phần lẻ của giây. Đó vẫn là cùng một thời điểm theo UTC. Hãy phân tích cả hai dạng bằng một trình phân tích RFC 3339 tiêu chuẩn; không so sánh dấu thời gian như chuỗi.
  • Mọi trường có tên kết thúc bằng _at là một dấu thời gian.

Thời điểm bạn gửi phải có độ lệch múi giờ, hoặc Z, hoặc một độ lệch dạng số như +02:00. Thời điểm không có độ lệch là không rõ ràng và trả về 422 với mã validation.failed. Sursa chuyển mọi thời điểm nhận được sang UTC.

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

Trong chuỗi truy vấn, dấu + phải được viết thành %2B, nếu không nó sẽ bị đọc là dấu cách. Hãy mã hóa URL cho giá trị thời gian, hoặc dùng Z.

Ngày, khoảng thời gian và số lượng

LoạiDạngVí dụ
Ngày không có giờYYYY-MM-DD, trong trường kết thúc bằng _date"due_date": "2026-11-01"
Khoảng thời gianSố nguyên, đơn vị nằm trong tên trường"interval_days": 90, "timeout_seconds": 30
Số lượngSố nguyên, trong trường kết thúc bằng _count"part_count": 12
Đúng hoặc saiBoolean, đặt tên bằng tính từ, không có is_"active": true, "sensitive": false

Số tiền

Số tiền trong các phản hồi tài chính là chuỗi thập phân, chẳng hạn "1250.00", không bao giờ là số dấu phẩy động, để không mất độ chính xác. Tiền tệ là một trường riêng với mã ISO 4217, chẳng hạn "EUR". Hãy phân tích số tiền bằng kiểu thập phân trong ngôn ngữ của bạn.

ID

ID là chuỗi hoặc số nguyên tùy theo đối tượng. Xem ID của đối tượng.

Tập giá trị enum

Trường có tập giá trị cố định, chẳng hạn trạng thái, là chuỗi. Mọi tập giá trị trong phản hồi đều có thể nhận giá trị mới ở phiên bản sau: hãy coi giá trị bạn không biết là “khác”. Xem Phiên bản và khả năng tương thích.

Trường null và trường vắng mặt

  • null nghĩa là “không có giá trị”: thẻ không có người phụ trách có "owner_id": null.
  • Một trường có thể vắng mặt trong phản hồi khi nó không áp dụng cho đối tượng này hoặc yêu cầu này. Tài liệu tham chiếu API đánh dấu những trường luôn có mặt.
  • Trong PATCH, trường bạn bỏ qua giữ nguyên giá trị. Gửi null để xóa giá trị của trường ở chỗ tài liệu tham chiếu cho phép null.