В Kodzero появилась возможность выполнять запросы к API из серверного приложения с административными правами — с помощью Admin API-ключа.
Это новый способ использовать Kodzero в архитектурах, где одного прямого взаимодействия frontend → Kodzero API уже недостаточно.
Обычные операции по-прежнему можно выполнять напрямую:
Frontend → Kodzero API
Но если приложению требуется собственная бизнес-логика — например, сложная обработка заказа, интеграция с внешним сервисом, формирование отчета или выполнение фоновой задачи — между frontend и Kodzero можно добавить собственный сервер:
Frontend → ваш сервер → Kodzero API
При этом вам не нужно использовать отдельный API или изучать новые методы. Сервер использует тот же REST API Kodzero, а API-ключ с правами администратора позволяет выполнять запросы с необходимым уровнем доступа.
В этой статье разберем, как работает серверная интеграция, в каких случаях она нужна и рассмотрим несколько практических сценариев.
Когда обычного API недостаточно
Kodzero хорошо подходит для приложений, в которых frontend напрямую работает с данными.
Например, интернет-магазину может быть достаточно стандартного CRUD + встроенных возможностей аутентификации/авторизации:
Frontend
↓
Kodzero API
↓
Products
Orders
Users
Frontend получает список товаров, создает заказ, обновляет профиль пользователя и выполняет другие стандартные операции.
Но со временем появляется бизнес-логика, которую не хочется или небезопасно выполнять на клиенте.
Например, при создании заказа нужно:
- проверить наличие товаров;
- безопасно применить скидку пользователя;
- рассчитать стоимость доставки;
- проверить промокод;
- создать заказ;
- зарезервировать товары;
- отправить данные в платежную систему.
Такой сценарий уже сложно представить как один простой CRUD-запрос из браузера.
В этом случае собственный сервер становится промежуточным слоем:
Frontend
↓
Ваш сервер
↓
Kodzero API
Frontend передает серверу только необходимые данные, сервер выполняет бизнес-логику, а затем обращается к Kodzero для чтения или изменения данных.
Что такое Admin API-ключ
Admin API-ключ — это ключ для выполнения запросов к Kodzero API из серверного приложения с использованием административного профиля.
Ключ позволяет серверу выполнять стандартные REST-операции Kodzero с правами, заданными при создании ключа.
Доступно два уровня:
- Только чтение — только операции чтения;
- Чтение и запись — чтение, создание, изменение и удаление данных.
Как это работает
Для административного запроса используются два заголовка:
Authorization: Bearer YOUR_ADMIN_API_KEY
X-Kodzero-Profile: admin
Authorization содержит Admin API-ключ, а X-Kodzero-Profile: admin сообщает Kodzero, что запрос должен выполняться с использованием административного профиля.
Например, обычный запрос к коллекции:
GET https://api.kodzero.pro/v1/:project/:collection
и запрос из серверного приложения используют один и тот же URL. Таким образом, не нужно запоминать отдельные admin-endpoint'ы.
Примеры
Создание заказа с бизнес-логикой
Представим интернет-магазин, в котором нужно реализовать собственную логику создания заказа: проверить наличие товара, проверить промокод, рассчитать скидку и стоимость доставки и выполнить другие проверки.
При нажатии кнопки «Оформить заказ» frontend отправляет данные на кастомный сервер вместе с токеном авторизованного покупателя:
Frontend
↓
POST /orders/create
Authorization: Bearer USER_TOKEN
↓
Ваш сервер
Подробнее о создании пользователей, регистрации и авторизации в Kodzero см. в документация по серверной интеграции.
Сервер проверяет токен пользователя через Kodzero, получает его идентификатор и выполняет необходимую бизнес-логику.
Получить пользователя
↓
Проверить товары
↓
Проверить промокод
↓
Рассчитать скидку
↓
Рассчитать доставку
↓
Создать заказ в Kodzero
После всех проверок сервер создает заказ в Kodzero с помощью Admin API-ключа.
const response = await fetch(
'https://api.kodzero.pro/v1/:project/orders',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.KODZERO_ADMIN_API_KEY}`,
'X-Kodzero-Profile': 'admin'
},
body: JSON.stringify({
_user,
items,
total
// прочие поля
})
}
)
const data = await response.json()
В результате Kodzero остается слоем данных, а бизнес-правила и сложная серверная логика находятся в вашем приложении.
При этом frontend не получает административный ключ и не имеет прямого доступа к операциям, которые должны выполняться только после серверных проверок.
Формирование отчетов
Другой пример — отчет по заказам.
Допустим, вам нужно получить:
- количество заказов за период;
- общую выручку;
- средний чек;
- продажи по категориям;
- статистику по клиентам.
Сервер может получить необходимые данные через API, выполнить вычисления и сформировать готовый отчет:
Kodzero
↓
Данные о заказах
↓
Ваш сервер
↓
Расчеты и агрегация
↓
Готовый отчет
Такой отчет можно затем сохранить, отправить по email или передать в другой сервис.
Интеграция с внешними сервисами
Собственный сервер также удобно использовать как промежуточный слой между Kodzero и внешними системами.
Например:
Kodzero
↓
Ваш сервер
├── CRM
├── Платежная система
├── Email-сервис
└── Telegram
Сервер получает данные из Kodzero, преобразует их в нужный формат и отправляет во внешние системы.
Это позволяет не размещать секретные ключи внешних сервисов в frontend-приложении.
Фоновые задачи
Серверная интеграция не обязательно означает наличие пользовательского запроса. Кастомный сервер может периодически обращаться к Kodzero самостоятельно.
Например:
CRON
↓
Ваш сервер
↓
Kodzero API
Так можно реализовать:
- регулярный пересчет статистики;
- импорт данных;
- очистку устаревших записей;
- генерацию документов;
- синхронизацию с внешними системами.
В таких сценариях frontend вообще не участвует.
Выполнение запросов
В серверном JavaScript-приложении можно использовать стандартный fetch:
const response = await fetch(
'https://api.kodzero.pro/v1/:project/:collection',
{
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.KODZERO_ADMIN_API_KEY}`,
'X-Kodzero-Profile': 'admin'
}
}
)
if (!response.ok) {
throw new Error('Kodzero request failed')
}
const data = await response.json()
Пара слов о безопасности
Admin API-ключ предоставляет административный доступ к данным проекта, поэтому относиться к нему нужно как к секрету.
Ключ должен находиться только в серверной среде.
Например:
KODZERO_ADMIN_API_KEY=...
Не размещайте его:
- в frontend-коде;
- в мобильном приложении;
- в репозитории;
- в публичной конфигурации;
- в логах приложения.
Не используйте один ключ для всех сервисов. Лучше создавать отдельные ключи для разных приложений и окружений.
Например:
development → отдельный ключ
staging → отдельный ключ
production → отдельный ключ
Если конкретный ключ будет скомпрометирован, его можно удалить и заменить, не затрагивая остальные сервисы.
Итог
Admin API-ключ добавляет еще один уровень архитектурных возможностей для Kodzero.
Если стандартного CRUD достаточно, frontend может продолжать работать с Kodzero напрямую:
Frontend → Kodzero
Если появляется собственная бизнес-логика, можно добавить сервер:
Frontend → ваш сервер → Kodzero
При этом Kodzero продолжает выступать единым API и источником данных, а ваш сервер получает пространство для реализации сложной логики, интеграций и фоновых процессов.
Подробнее о настройке и использовании Admin API-ключ можно узнать в документации Kodzero.