API-ключ и доступ
Партнёрский API-ключ, заголовки, лимиты и безопасность.
Нет личного кабинета?
Зарегистрируйтесь на Apergrex, затем откройте настройки кабинета и выпустите API-ключ.
Партнёрский API-ключ
Аутентификация — партнёрский API-ключ формата fl_live_<64 hex>. Он используется для генерации, биллинга и вебхуков. Исключение: выпуск и отзыв API-ключей требуют сессию кабинета; используйте Настройки → API.
Передавайте ключ одним из двух способов:
# Заголовок X-API-Key (рекомендуется)
curl -H "X-API-Key: $FRANKLAB_KEY" https://apergrex.ru/franklab/api/v1/billing/balance
# Или Authorization: Bearer
curl -H "Authorization: Bearer $FRANKLAB_KEY" https://apergrex.ru/franklab/api/v1/billing/balanceСтатусы ответов
| Код | Причина | Что делать |
|---|---|---|
| 401 | Ключ отсутствует, неизвестен или деактивирован | Проверьте ключ; новый выпускается в кабинете (Настройки → API) |
| 403 | Передан legacy service-ключ | Нужен именно партнёрский fl_live_-ключ |
| 429 | Превышен лимит запросов | Повторите позже; по умолчанию 60 запросов/мин на API-ключ |
Лимиты
Значения ниже — настройки по умолчанию, а не гарантия доступной пропускной способности. Биллинг и вебхуки используют общий счётчик: 60 запросов/мин на API-ключ; операции через сессию — 60/мин на партнёра. Дополнительно действует ограничитель по IP для каждого метода (по умолчанию 100/мин), с исключениями:
| Метод | Лимит по IP в минуту |
|---|---|
POST /v1/billing/payment/link | 3 |
POST /v1/billing/legal-invoices/create | 3 |
POST /v1/billing/legal-invoices/{id}/refresh | 6 |
POST /v1/billing/legal-invoices/{id}/sbp-link | 6 |
GET /v1/billing/legal-invoices/{id}/pdf | 12 |
POST /v1/webhooks/endpoints | 10 |
POST /v1/webhooks/endpoints/{id}/rotate-secret | 10 |
POST /v1/webhooks/endpoints/{id}/test | 6 |
POST /v1/webhooks/deliveries/{id}/replay | 30 |
Лимиты применяются одновременно. Для 429 учитывайте Retry-After и правила повторов; не переносите лимит биллинга на запуск генерации.
Права ключа (scopes) и срок действия
По умолчанию ключ — полный: он открывает генерацию, биллинг и вебхуки. Ранее выпущенные ключи не меняются — они продолжают работать ровно как раньше, ничего делать не нужно.
При выпуске ключ можно ограничить набором прав. Актуальный список прав и то, какие методы каждое из них открывает, отдаёт сам сервер:
# справочник прав (сессия кабинета)
curl -b "franklab_token=$COOKIE" https://apergrex.ru/franklab/api/auth/api-keys/operations| Право | Что открывает |
|---|---|
usage:read | Дневной расход аккаунта; проверка учётных данных в n8n |
billing:read | Баланс, тариф, операции, история пополнений |
pricing:read | Каталог цен и оценка стоимости (без списания) |
tasks:read | Статусы и результаты своих задач |
media:run | Запуск обработки и генерации (возможен расход) |
webhooks:read | Чтение эндпоинтов и журнала доставок |
webhooks:manage | Создание, ротация секрета, тест и повтор доставки |
Правила, которые стоит знать заранее:
- Права можно только сузить. Ограниченному ключу нельзя вернуть полный доступ — выпустите новый.
- Создание платёжных ссылок недоступно ни одному ограниченному ключу: ни одно право его не открывает. Это делается из сессии кабинета.
- Ограниченный ключ всегда может прочитать свои права (
GET /v1/billing/api-keys), но права соседних ключей в этом ответе скрыты (scopes: null). *не является правом и не принимается ни в запросе, ни в базе.
Срок действия задаётся при выпуске (expiresInDays, от 1 до 365 дней) и по умолчанию отсутствует: ключ без срока не истекает. Истёкший ключ отвечает 401 с кодом API_KEY_EXPIRED и остаётся в списке кабинета — его видно, пока вы не включите «скрыть истёкшие». Продлить истёкший ключ нельзя — выпустите новый; PATCH меняет только права и название и никогда не трогает срок.
Отзыв действует со следующего запроса: ключ перечитывается на каждом обращении, кэша учётных данных нет. При отзыве можно записать причину (DELETE /auth/api-keys/{id}?reason=...) — она видна в списке.
| Код | Когда | HTTP |
|---|---|---|
API_KEY_EXPIRED | Срок действия ключа истёк | 401 |
API_KEY_SCOPE_REQUIRED | У ключа нет права на этот метод | 403 |
API_KEY_SCOPE_UNKNOWN | В запросе указано неизвестное право (в том числе *) | 400 |
API_KEY_SCOPE_EMPTY | Ограниченный ключ запрошен без единого права | 400 |
API_KEY_SCOPE_DOWNGRADE_FORBIDDEN | Попытка вернуть ограниченному ключу полный доступ | 400 |
API_KEY_EXPIRY_OUT_OF_RANGE | Срок вне диапазона 1…365 дней | 400 |
API_KEY_QUOTA_EXCEEDED | Больше 20 активных ключей на аккаунт | 400 |
Изменения в ответах на повтор доставки
POST /v1/webhooks/deliveries/{id}/replay раньше отвечал одним 404 на любую причину отказа. Теперь причины различимы:
| Код | HTTP | Причина |
|---|---|---|
DELIVERY_NOT_FOUND | 404 | Доставки с таким id у вас нет |
DELIVERY_NOT_REPLAYABLE | 409 | Доставка в статусе, из которого повтор невозможен (например, уже в очереди) |
DELIVERY_ENDPOINT_DELETED | 409 | Эндпоинт этой доставки удалён — повторять некуда |
DELIVERY_ENDPOINT_INACTIVE | 409 | Эндпоинт этой доставки неактивен |
Если ваш код считал любой неуспех повтора «404 — доставки нет», обновите его: три новые причины приходят с 409. Списки доставок при этом получили постраничность — GET /v1/webhooks/deliveries?limit=1..100&cursor=... возвращает {deliveries, nextCursor, shown}.
Безопасность ключа
- Ключ хранится на сервере только как хэш — «показать снова» невозможно; потерянный ключ отзывают и выпускают новый.
- Передавайте ключ только по HTTPS, никогда — в URL, логах или клиентском коде.
- Ключ можно отозвать мгновенно из сессии кабинета:
DELETE /v1/billing/api-keys/{id}(или страница Настройки → API). Отзыв ключа не требует самого ключа — и ключ не может создать себе замену. - Заведите отдельный ключ на каждую интеграцию — метка помогает отличать их в списке.
Управление ключами
Чтение списка ключей — по API-ключу. Выпуск и отзыв — только в сессии кабинета (cookie партнёра): API-ключ не может выпускать новые ключи, поэтому скомпрометированный ключ отзывается полностью — у него нет «потомков», которые пережили бы отзыв. Это то же доверие, что у страницы Настройки → API.
# список (только префиксы, сырое значение не возвращается) — по API-ключу
curl -H "X-API-Key: $FRANKLAB_KEY" https://apergrex.ru/franklab/api/v1/billing/api-keysСоздать (POST /v1/billing/api-keys) и отозвать (DELETE /v1/billing/api-keys/{id}) ключ можно из кабинета: Настройки → API — или тем же запросом из залогиненной сессии кабинета (cookie franklab_token).