Документация для разработчиков

YFG ID — провайдер входа по OAuth 2.0 / OpenID Connect и публичная платформа данных YFG. Партнёр может впустить пользователя на свой сайт, показать афишу и каталог мастеров, продать билет во встроенном виджете и получать изменения через вебхуки.

Базовые адреса

Запросы из браузера к /id/api/* разрешены только с origin, добавленных в «Разрешённые адреса» приложения. Для остальных origin CORS-заголовки не возвращаются.

1. Создайте приложение в кабинете YFG ID. Укажите название, сайт, redirect_uri и разрешённые origin для виджетов. Секрет показывается один раз — сохраните его на сервере.
2. Выберите сценарий. Вход пользователя — Authorization Code + PKCE. Серверная витрина — client_credentials или Basic. Встраивание на страницу — виджет.
3. Получите токен или авторизуйте приложение. Для каталога достаточно Basic, для пользовательских данных нужен access token.
4. Вызовите API. Каталог — https://yfg.su/id/api/events и /api/masters; данные пользователя — /api/me/*.
5. Подпишитесь на вебхуки в карточке приложения, чтобы получать изменения мероприятий без polling.

Сервер-сервер за минуту

curl -X POST https://yfg.su/id/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope="events:read masters:read"

curl "https://yfg.su/id/api/events?when=upcoming&per_page=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Basic-авторизация работает только для публичного каталога и только для конфиденциальных приложений. client_secret никогда не попадает в браузер.

Провайдер поддерживает Authorization Code, Refresh Token и Client Credentials. Для браузерных приложений используйте Authorization Code с PKCE S256; implicit flow намеренно не поддерживается.

Шаг 1. Отправьте пользователя на вход

https://yfg.su/id/authorize?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://partner.example/callback
  &scope=openid%20profile%20email
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256

• response_type — только code.
• state обязателен для защиты от CSRF, nonce — для ID token.
• prompt=consent или force_confirm=1 повторно показывает согласие; login_hint подсказывает логин.
• Код живёт 5 минут, одноразовый и привязан к client_id, redirect_uri и PKCE.

Шаг 2. Обменяйте код на токены

curl -X POST https://yfg.su/id/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=CODE_FROM_CALLBACK \
  -d redirect_uri=https://partner.example/callback \
  -d code_verifier=ORIGINAL_VERIFIER

{
  "access_token": "yfg_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "yfg_rt_...",
  "scope": "openid profile email",
  "id_token": "eyJhbGciOiJSUzI1NiIs..."
}

Публичное приложение не отправляет секрет, но обязано передать client_id и code_verifier. Поле scope возвращается, если выданных прав меньше, чем у приложения; id_token приходит при scope openid.

Шаг 3. Прочитайте профиль

curl https://yfg.su/id/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Ответ содержит стандартные OIDC-поля и совместимые с Яндекс ID id, login, display_name, default_email, emails, is_avatar_empty — в пределах выданных scope.

Client Credentials

Только для конфиденциальных приложений и только для events:read / masters:read. Пользовательские права в машинном токене запрещены. Refresh-токен не выдаётся.

curl -X POST https://yfg.su/id/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope="events:read masters:read"

Если scope не передан, выдаётся пересечение разрешённых приложению каталоговых прав. Для Basic-авторизации каталога токен не нужен: -u "client_id:client_secret".

Обновление и отзыв

curl -X POST https://yfg.su/id/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=YOUR_REFRESH_TOKEN

При обновлении сохраните новый refresh token — старый сразу становится недействительным. Отзыв: POST https://yfg.su/id/revoke_token с token и token_type_hint. Выход из YFG ID: GET https://yfg.su/id/end_session с id_token_hint и post_logout_redirect_uri.

Пользователь может посмотреть и отозвать доступы в кабинете YFG ID → «Подключённые приложения». После отзыва все токены приложения перестают работать.

Права запрашиваются через scope и проверяются на каждом endpoint. Неизвестное право — ошибка invalid_scope, а не молчаливое отбрасывание.

Псевдонимы принимаются для совместимости с Яндекс ID: login:info, login:email, login:avatar, login:birthday, login:default_phone, user:read, default, basic, events, tickets. Они приводятся к каноническим правам до выдачи согласия.

Публичные мероприятия: published, completed и cancelled. Черновики, модерация и удалённые записи не отдаются. По умолчанию — ближайшие опубликованные.

Фильтры списка

curl -u "$YFGID_CLIENT_ID:$YFGID_CLIENT_SECRET" \
  "https://yfg.su/id/api/events?when=upcoming&status=all&per_page=20"

{
  "id": 123,
  "title": "Ночь настольных игр",
  "status": "published",
  "cancelled": false,
  "date": "2026-11-15T20:00:00+03:00",
  "date_label": "15.11.2026 20:00",
  "location": "Москва",
  "price": 1200,
  "price_label": "от 1 200 руб.",
  "sold_out": false,
  "ticket_counts": {
    "total": 100, "available": 37, "sold": 63, "sold_out": false
  },
  "ticket_types": [
    {"id": 1, "name": "Стандарт", "quota": 80, "available": 37,
     "sold": 43, "is_active": true, "sold_out": false},
    {"id": 2, "name": "VIP", "quota": 20, "available": 0,
     "sold": 20, "is_active": true, "sold_out": true}
  ]
}

ticket_counts считается по активным типам; если типов нет — по агрегатам мероприятия. sold не бывает отрицательным. Для отменённого события cancelled: true и заполнен cancelled_at; причина отмены — внутренняя и в API не отдаётся.

Списки поддерживают ETag и If-None-Match (304), Link, X-Total-Count и X-RateLimit-*. Ответы кэшируются как private, max-age=30.

Только активные, проверенные модерацией мастера с активным аккаунтом. Скрытые и забаненные пользователи не попадают в каталог.

Фильтры

{
  "id": 7,
  "user_id": 42,
  "username": "master",
  "display_name": "Мастер",
  "headline": "Иллюстрации и персонажи",
  "specializations": ["artist"],
  "rating": 4.9,
  "review_count": 12,
  "is_verified": true,
  "is_available": true,
  "price_from": 1500,
  "price_label": "от 1 500 руб.",
  "services_count": 3,
  "url": "https://yfg.su/user/42"
}

Детальная карточка добавляет services, portfolio (до 24 работ), slots (до 30 будущих свободных окон), review_summary, время ответа и ссылки на соцсети. Email и другие приватные данные не отдаются.

Пять ресурсов /api/me/* требуют пользовательский Bearer-токен и соответствующий scope. Машинные токены и Basic здесь не работают.

curl "https://yfg.su/id/api/me/tickets?page=1&per_page=50" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

Коллекции поддерживают page и per_page (до 100, по умолчанию 100 для обратной совместимости). Ответ: items + pagination + meta.api_version. /api/me/master возвращает объект {"master": ...} или {"master": null}.

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

<script src="https://yfg.su/static/js/yfgid_widget.js"
        data-yfgid-client="YOUR_CLIENT_ID"
        data-yfgid-theme="auto"></script>

<div data-yfgid-events="123,456" data-yfgid-columns="2"></div>
<div data-yfgid-buy="123" data-yfgid-label="Купить билет"></div>
<div data-yfgid-login></div>

JavaScript API

YFGID.on('purchase', function (payload) {
  console.log('покупка', payload.event_id, payload.ok);
});
YFGID.on('login', function () { /* свой сценарий входа */ });
YFGID.refresh();

Домен страницы должен быть в «Разрешённых адресах» приложения. В консоли браузера виджет подскажет точный origin, который нужно добавить.

Подписки настраиваются в карточке приложения. До 5 endpoint'ов на приложение, только HTTPS. Секрет whsec_... показывается один раз и хранится в зашифрованном виде. Там же можно повернуть секрет, удалить подписку и посмотреть последние доставки.

{
  "id": "evt_...",
  "type": "event.cancelled",
  "api_version": "1",
  "created_at": "2026-10-28T00:00:00+03:00",
  "data": { "id": 123, "status": "cancelled", "cancelled": true, "...": "..." }
}

import hashlib
import hmac

message = f"{timestamp}.{raw_body}".encode("utf-8")
expected = "sha256=" + hmac.new(
    secret.encode("utf-8"), message, hashlib.sha256
).hexdigest()
assert hmac.compare_digest(expected, signature)

Отвечайте 2xx быстро; тело можно обрабатывать асинхронно. 410 Gone отключает endpoint. Ошибки и таймауты повторяются до 8 попыток; паузы — 60 секунд, 5, 30 минут, 2, 6, 12 и 24 часа. После 20 последовательных сбоев подписка отключается.

Каждый ответ API содержит X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset и X-RateLimit-Window. При 429 приходит Retry-After.

Ошибки API имеют вид {"error": "...", "error_description": "...", "request_id": "..."}. При обращении к API сохраняйте request_id — по нему быстрее разобрать инцидент.

Текущая версия API — 1. Она передаётся в X-API-Version, meta.api_version и X-YFG-Api-Version вебхуков. Обратно совместимые изменения (новые поля и фильтры) выходят без смены версии; ломающие — только в новой версии API.

• Машинный контракт: OpenAPI 3.1.
• Метаданные OIDC: discovery.
• Исходный код и примеры: GitHub YFG-CodeBase.
• Кабинет и выпуск секретов: YFG ID → Приложения.

Ограничения версии 1

Вебхуки сейчас покрывают только мероприятия; управление подписками — через кабинет, без публичного API. Каталог только для чтения. Пагинация — page/per_page, без cursor-режима. Песочницы нет: для тестов используйте отдельное приложение и реальные тестовые мероприятия.