Перейти к содержанию
Sursa для разработчиков

Время и форматы

JSON и текст

  • Тела запросов и ответов — JSON в UTF-8 с Content-Type: application/json. Для загрузки файлов используется multipart/form-data.
  • Имена полей и значения перечислений записываются в snake_case: next_retry_at, index_failed.
  • Сообщения об ошибках и тексты API — на английском. Тексты, которые пишете вы, например заголовки карточек, возвращаются так, как вы их написали, на любом языке.

Время

Любое время — метка времени RFC 3339 в UTC:

{"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". Разбирайте суммы десятичным типом своего языка.

Идентификаторы

Идентификаторы — строки или целые числа в зависимости от объекта. Подробнее — в разделе Идентификаторы объектов.

Перечисления

Поля с фиксированным набором значений, например статус, — строки. Любое перечисление в ответе может получить новые значения в следующей версии: считайте незнакомое значение вариантом «другое». Подробнее — в разделе Версии и совместимость.

Null и отсутствующие поля

  • null означает «значения нет»: у карточки без владельца "owner_id": null.
  • Поля может не быть в ответе, если оно не относится к этому объекту или этому запросу. В справочнике API отмечено, какие поля есть всегда.
  • В PATCH поле, которое вы не передали, сохраняет своё значение. Передайте null, чтобы очистить поле, если справочник указывает, что null допустим.