Форматы даты и времени

Стандарты ISO 8601 и Unix timestamp, используемые в API Premiss Cloud

Обзор

В API Premiss Cloud используются два формата представления даты и времени:

Формат	Стандарт	Где используется
ISO 8601	RFC 3339	Тела запросов и ответов
Unix timestamp	POSIX time	HTTP-заголовки

ISO 8601

Основной формат для всех полей даты и времени в телах запросов и ответов API.

Формат

YYYY-MM-DDTHH:mm:ss.sssZ

Часть	Описание	Пример
`YYYY`	Год (4 цифры)	`2026`
`MM`	Месяц (01–12)	`03`
`DD`	День (01–31)	`05`
`T`	Разделитель даты и времени	`T`
`HH`	Часы (00–23)	`14`
`mm`	Минуты (00–59)	`30`
`ss`	Секунды (00–59)	`00`
`.sss`	Миллисекунды (000–999)	`.000`
`Z`	Часовой пояс UTC	`Z`

Примеры

"2026-03-05T14:30:00.000Z"   // 5 марта 2026, 14:30 UTC
"2026-01-01T00:00:00.000Z"   // 1 января 2026, полночь UTC

Все временные метки в API возвращаются в UTC (суффикс Z). Конвертация в локальное время — на стороне клиента.

Поля в ответах API

Эти поля всегда возвращаются в формате ISO 8601:

Поле	Где встречается	Описание
`created_at`	Задачи, транзакции, пайплайны	Дата создания
`updated_at`	Задачи, пайплайны	Дата последнего обновления
`completed_at`	Задачи	Дата завершения обработки
`expires_at`	Задачи	Дата истечения TTL результата
`timestamp`	Webhook payload	Время отправки webhook

Параметры фильтрации

Query-параметры from и to в эндпоинтах списков также принимают ISO 8601:

Фильтрация по дате

# Транзакции за март 2026
curl "https://premiss.ru/api/v1/billing/transactions?from=2026-03-01T00:00:00.000Z&to=2026-03-31T23:59:59.999Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Стоимость обработки за последнюю неделю
curl "https://premiss.ru/api/v1/billing/costs?from=2026-02-26T00:00:00.000Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Границы from и to — включительные (inclusive). Записи, созданные точно в указанное время, попадут в выборку.

Допустимые форматы ввода

При отправке дат в query-параметрах API принимает любой валидный формат ISO 8601:

2026-03-05T14:30:00.000Z     // Полный формат с миллисекундами
2026-03-05T14:30:00Z          // Без миллисекунд
2026-03-05T14:30:00+03:00     // С указанием часового пояса
2026-03-05                     // Только дата (интерпретируется как 00:00:00 UTC)

Unix Timestamp

Используется только в HTTP-заголовках rate limiting.

Формат

Целое число — количество секунд с 1 января 1970 00:00:00 UTC (Unix epoch).

1709294400    // = 2026-03-01T12:00:00Z

Где используется

Заголовок	Формат	Описание
`X-RateLimit-Reset`	Unix timestamp (секунды)	Время сброса окна rate limit
`Retry-After`	Целое число (секунды)	Сколько секунд ждать до повторного запроса

Пример заголовков при 429 Too Many Requests

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709294400
Retry-After: 25

Конвертация

Unix timestamp → Date

const resetTimestamp = parseInt(headers.get('X-RateLimit-Reset'));
const resetDate = new Date(resetTimestamp * 1000); // × 1000 для миллисекунд
console.log(resetDate.toISOString()); // "2026-03-01T12:00:00.000Z"

Unix timestamp → datetime

import datetime
reset_timestamp = int(headers['X-RateLimit-Reset'])
reset_date = datetime.datetime.fromtimestamp(reset_timestamp, tz=datetime.timezone.utc)
print(reset_date.isoformat())  # "2026-03-01T12:00:00+00:00"

Сводная таблица

Контекст	Формат	Стандарт	Пример
Поля в JSON-ответах	`YYYY-MM-DDTHH:mm:ss.sssZ`	ISO 8601 / RFC 3339	`2026-03-05T14:30:00.000Z`
Query-параметры `from`, `to`	`YYYY-MM-DDTHH:mm:ss.sssZ`	ISO 8601	`2026-03-01T00:00:00.000Z`
Заголовок `X-RateLimit-Reset`	Целое число (секунды)	Unix timestamp	`1709294400`
Заголовок `Retry-After`	Целое число (секунды)	HTTP/1.1 (RFC 7231)	`25`

Форматы даты и времени

На этой странице