Turelay API — Полный справочник разработчика (v3.1.7)

🔐 Аутентификация

Все запросы к Turelay API требуют аутентификации через заголовок X-Turelay-Key. Ключи выдаются в консоли управления организацией. Существует два типа ключей: тестовые (начинаются с tl_test_) и боевые (начинаются с tl_live_).

ℹ️ Заголовки запроса

Обязательные заголовки для всех запросов: X-Turelay-Key и Content-Type: application/json

Пример заголовков

X-Turelay-Key: tl_live_8f3a2c1e9b7d6f5e4a3b2c1d0e9f8a7b
Content-Type: application/json
User-Agent: MyApp/2.0

⚠️ Безопасность

Никогда не передавайте API-ключи в клиентском коде или публичных репозиториях. Используйте переменные окружения на сервере.

⚡ Лимиты запросов

Лимиты применяются на уровне API-ключа. При превышении возвращается HTTP 429 с заголовком Retry-After (в секундах).

План	Лимит	Период	Стоимость
Starter	100 запросов	минута	Бесплатно
Growth	1 000 запросов	минута	$49/мес
Scale	10 000 запросов	минута	$199/мес
Enterprise	Без лимитов	—	По запросу

ℹ️ Заголовки лимитов

Каждый ответ содержит заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset.

📦 Объекты

Объекты — это универсальная сущность для хранения любых данных. Каждый объект имеет тип, статус и метаданные.

GET /v3/objects Пагинация

Возвращает список объектов с поддержкой фильтрации, сортировки и пагинации.

cURL пример

curl -X GET "https://api.turelay.io/v3/objects?limit=50&offset=0&status=active&sort=-created_at" \
  -H "X-Turelay-Key: tl_live_8f3a2c1e9b7d6f5e4a3b2c1d0e9f8a7b"

Параметр	Тип	Описание
limit optional	integer	Количество результатов (1–200, default: 20)
offset optional	integer	Смещение для пагинации
status optional	string	Фильтр: `active`, `archived`, `pending`, `deleted`
type optional	string	Фильтр по типу объекта
sort optional	string	Сортировка: `created_at`, `-created_at`, `updated_at`
metadata.* optional	string	Фильтр по произвольному метаданному

Ответ 200 OK

{
  "success": true,
  "data": [
    {
      "id": "obj_3f8a2c1e9b7d6f5e",
      "type": "invoice",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:35:00Z",
      "metadata": {
        "customer_id": "cus_8821",
        "amount": 12500
      }
    }
  ],
  "pagination": {
    "total": 147,
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "request_id": "req_9f8e7d6c5b4a3f2e"
}

POST /v3/objects Создание

Создает новый объект. Метаданные могут содержать до 8KB произвольных данных.

cURL пример

curl -X POST "https://api.turelay.io/v3/objects" \
  -H "X-Turelay-Key: tl_live_8f3a2c1e9b7d6f5e4a3b2c1d0e9f8a7b" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "status": "active",
    "metadata": {
      "customer_id": "cus_8821",
      "amount": 12500,
      "currency": "RUB"
    }
  }'

Параметр	Тип	Описание
type required	string	Тип объекта (до 64 символов)
status optional	string	Начальный статус (default: `active`)
metadata optional	object	Произвольные данные (до 8KB)

GET /v3/objects/:id

Возвращает полную информацию об объекте по ID.

cURL пример

curl -X GET "https://api.turelay.io/v3/objects/obj_3f8a2c1e9b7d6f5e" \
  -H "X-Turelay-Key: tl_live_8f3a2c1e9b7d6f5e4a3b2c1d0e9f8a7b"

PUT /v3/objects/:id

Полностью обновляет объект. Неуказанные поля будут сброшены.

⚠️ Внимание

PUT заменяет весь объект. Для частичного обновления используйте PATCH.

PATCH /v3/objects/:id

Частично обновляет объект. Обновляются только указанные поля.

DELETE /v3/objects/:id Необратимо

Удаляет объект навсегда. Рекомендуется использовать PATCH со статусом archived для мягкого удаления.

⛔ Осторожно

Удаление необратимо. Данные нельзя будет восстановить.

💳 Платежи

Модуль обработки платежей с поддержкой возвратов, подтверждений и различных платежных провайдеров.

POST /v3/payments

Создает платежное намерение. После создания можно перенаправить пользователя на страницу оплаты.

cURL пример

curl -X POST "https://api.turelay.io/v3/payments" \
  -H "X-Turelay-Key: tl_live_8f3a2c1e9b7d6f5e4a3b2c1d0e9f8a7b" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12500,
    "currency": "RUB",
    "description": "Подписка на Pro план",
    "customer": {
      "email": "client@example.com"
    },
    "success_url": "https://mysite.com/success",
    "cancel_url": "https://mysite.com/cancel"
  }'

Параметр	Тип	Описание
amount required	integer	Сумма в минимальных единицах валюты (копейки)
currency required	string	ISO 4217 код валюты
customer.email optional	string	Email для уведомлений
success_url optional	string	URL перенаправления при успехе
cancel_url optional	string	URL при отмене

GET /v3/payments

Возвращает список платежей с фильтрацией по статусу, дате и клиенту.

GET /v3/payments/:id

Возвращает детальную информацию о платеже, включая статус, историю изменений и данные плательщика.

POST /v3/payments/:id/refund

Инициирует возврат средств. Частичный возврат возможен в течение 180 дней.

POST /v3/payments/:id/capture

Подтверждает списание средств для платежей с отложенным списанием.

👤 Пользователи

Управление пользователями вашей платформы: создание, обновление, поиск и управление правами.

GET /v3/users

Возвращает список пользователей с пагинацией и фильтрацией.

POST /v3/users

Создает нового пользователя.

cURL пример

curl -X POST "https://api.turelay.io/v3/users" \
  -H "X-Turelay-Key: tl_live_8f3a2c1e9b7d6f5e4a3b2c1d0e9f8a7b" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "Иван Петров",
    "role": "developer"
  }'

GET /v3/users/:id

Возвращает информацию о пользователе.

PUT /v3/users/:id

Обновляет данные пользователя.

📊 Аналитика

Отправка и получение аналитических данных в реальном времени.

POST /v3/analytics/events

Отправляет событие в поток аналитики. Максимальный размер пакета — 100 событий.

cURL пример

curl -X POST "https://api.turelay.io/v3/analytics/events" \
  -H "X-Turelay-Key: tl_live_8f3a2c1e9b7d6f5e4a3b2c1d0e9f8a7b" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "payment.succeeded",
    "properties": {
      "amount": 12500,
      "currency": "RUB",
      "source": "web"
    },
    "timestamp": "2025-01-15T10:31:00Z"
  }'

GET /v3/analytics/summary

Возвращает агрегированную сводку по событиям за период.

GET /v3/analytics/export

Экспортирует аналитические данные в CSV или JSON.

🔧 Дополнительные эндпоинты

POST /v3/files

Загружает файл. Максимальный размер — 50MB.

GET /v3/search

Полнотекстовый поиск по всем объектам и метаданным.

GET /v3/health

Проверка состояния API. Не требует аутентификации.

Ответ 200 OK

{
  "status": "healthy",
  "version": "3.1.7",
  "latency_ms": 2,
  "timestamp": "2025-01-15T10:35:00Z"
}

🔔 Вебхуки

Turelay API может отправлять уведомления на ваш сервер при наступлении событий. Настройте URL вебхука в консоли управления.

ℹ️ Подпись вебхуков

Каждый вебхук содержит заголовок X-Turelay-Signature для проверки подлинности. Используйте HMAC-SHA256 с вашим секретом вебхука.

Пример тела вебхука

{
  "event": "payment.succeeded",
  "data": {
    "payment_id": "pay_8f3a2c1e9b7d",
    "amount": 12500,
    "currency": "RUB"
  },
  "created_at": "2025-01-15T10:31:00Z"
}

⚠️ Обработка ошибок

API использует стандартные HTTP-коды. Все ошибки возвращаются в формате JSON с машиночитаемым кодом.

HTTP код	Код ошибки	Описание
400	`INVALID_JSON`	Некорректный JSON
400	`VALIDATION_ERROR`	Ошибка валидации полей
401	`UNAUTHORIZED`	Неверный API-ключ
403	`FORBIDDEN`	Недостаточно прав
404	`NOT_FOUND`	Ресурс не найден
409	`CONFLICT`	Конфликт данных
422	`UNPROCESSABLE`	Невозможно обработать
429	`RATE_LIMITED`	Превышен лимит
500	`INTERNAL_ERROR`	Внутренняя ошибка
503	`SERVICE_UNAVAILABLE`	Сервис временно недоступен

Пример ошибки

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Поле 'amount' должно быть положительным числом.",
    "details": {
      "field": "amount",
      "expected": "integer > 0"
    },
    "request_id": "req_8f3a2c1e9b7d6f5e"
  }
}