API · Луч знаний

API-документация

Общий API-шлюз для педагогических сайтов: сайт определяется по X-API-Key, разработчик передаёт только событие и данные клиента/заказа.

X-API-Key required

Авторизация

Для сайта используйте scoped backend key проекта. Полный ключ показывается один раз при создании, в базе хранится hash и последние 4 символа.

X-API-Key: gs_live_... Content-Type: application/json

Создать или отключить API-ключ

Внешний API-шлюз

Метод	Назначение	Пример
`GET /api/scoped/events/catalog`	Получить общий каталог событий API-шлюза и список событий, поддерживаемых текущим ключом
`POST /api/scoped/send/transactional`	Отправить/поставить транзакционное письмо по event_type	{"event_type":"contest_results","email":"client@example.com","name":"Мария","fields":{"event_title":"Конкурс","work_title":"Работа","place":"1 место"},"idempotency_key":"ORDER-1:contest_results"}
`POST /api/scoped/events/order-created`	Создан заказ/заявка. Для сайтов с корзинами: cart_type=course/diploma; сайт определяется по ключу	{"cart_type":"course","email":"client@example.com","order_id":"ORDER-1","course_name":"Педагогика","fields":{"pay_url":"https://site.ru/pay/ORDER-1"}}
`POST /api/scoped/events/purchase`	Оплата заказа: остановить pending-письма неоплаченной корзины по order_id, добавить в общую книгу оплативших и, если передан fields.course_category_id, дополнительно в категорийную книгу	{"cart_type":"course","email":"client@example.com","order_id":"kpk_515309","course_id":"kpk_515309","amount":990,"currency":"RUB","fields":{"paid_at":"2026-07-06T12:55:17+03:00","account_url":"https://uchitelu.ru/profile","course_category_id":"2"}}
`GET /api/admin/external-events`	Админ: хронология входящих API-событий	?site_key=luch&order_id=ORDER-1
`GET /api/admin/external-events/stats`	Админ: статистика входящих API-событий	?site_key=luch

Формат ответа

Если обязательных данных не хватает, API возвращает 422 и список недостающих полей.

Успех: {"ok":true,"site_key":"solncesvet","event_type":"contest_results","email":"client@example.com","scheduled_email_id":123,"sent":0,"failed":0} Ошибка 422: {"detail":{"ok":false,"error":{"code":"validation_error","message":"Недостаточно данных для события contest_results","event_type":"contest_results","missing_fields":["fields.work_title"],"required_fields":["event_type","email","fields.event_title","fields.work_title"]}}}

Каталог API-событий

Это поддерживаемые API-события сервиса. Они существуют отдельно от шаблонов: сайт отправляет event_type, а соответствие событие → шаблон настраивается внутри Guru Send позднее.

Группа	Направление	Этап	event_type	За что отвечает	Когда отправлять	Обязательные fields	Шаблон
Обучение / КПК	Курс повышения квалификации	Создан заказ/заявка	`qualification_course_order_created`	Создан заказ/заявка на курс повышения квалификации.	Отправлять сразу после создания неоплаченного заказа/заявки на КПК.	`course_name`	API есть, шаблон не назначен
Обучение / КПК	Курс повышения квалификации	Оплата прошла	`qualification_course_paid`	Оплата курса повышения квалификации прошла успешно.	Отправлять после подтверждения успешной оплаты КПК.	`course_name`	API есть, шаблон не назначен
Обучение / КПК	Курс повышения квалификации	Удостоверение/документ готов	`qualification_course_document_ready`	Удостоверение/документ по КПК готов.	Отправлять, когда документ по КПК сформирован и доступен клиенту.	`course_name`	API есть, шаблон не назначен
Обучение / КПП	Профессиональная переподготовка	Создан заказ/заявка	`retraining_course_order_created`	Создан заказ/заявка на профессиональную переподготовку.	Отправлять сразу после создания неоплаченного заказа/заявки на КПП.	`course_name`	API есть, шаблон не назначен
Обучение / КПП	Профессиональная переподготовка	Оплата прошла	`retraining_course_paid`	Оплата профессиональной переподготовки прошла успешно.	Отправлять после подтверждения успешной оплаты КПП.	`course_name`	API есть, шаблон не назначен
Обучение / КПП	Профессиональная переподготовка	Диплом/документ готов	`retraining_course_document_ready`	Диплом/документ по профессиональной переподготовке готов.	Отправлять, когда документ по КПП сформирован и доступен клиенту.	`course_name`	API есть, шаблон не назначен
Обучение / КПО	Профессиональное обучение	Создан заказ/заявка	`professional_training_order_created`	Создан заказ/заявка на профессиональное обучение.	Отправлять сразу после создания неоплаченного заказа/заявки на КПО.	`course_name`	API есть, шаблон не назначен
Обучение / КПО	Профессиональное обучение	Оплата прошла	`professional_training_paid`	Оплата профессионального обучения прошла успешно.	Отправлять после подтверждения успешной оплаты КПО.	`course_name`	API есть, шаблон не назначен
Обучение / КПО	Профессиональное обучение	Документ готов	`professional_training_document_ready`	Документ по профессиональному обучению готов.	Отправлять, когда документ по КПО сформирован и доступен клиенту.	`course_name`	API есть, шаблон не назначен
Педагогические мероприятия	Олимпиада/тест	Участие принято	`olympiad_participation_created`	Участие в олимпиаде/тесте принято.	Отправлять после регистрации/принятия участия в олимпиаде или тесте.	`event_title`	API есть, шаблон не назначен
Педагогические мероприятия	Олимпиада/тест	Результаты готовы	`olympiad_results`	Результаты олимпиады/теста готовы.	Отправлять, когда доступны баллы, место или диплом по олимпиаде/тесту.	`event_title`	API есть, шаблон не назначен
Педагогические мероприятия	Конкурс	Работа отправлена	`contest_work_submitted`	Конкурсная работа отправлена/принята.	Отправлять после успешной загрузки или принятия работы на творческий конкурс.	`event_title, work_title`	API есть, шаблон не назначен
Педагогические мероприятия	Конкурс	Результаты готовы	`contest_results`	Результаты творческого конкурса готовы.	Отправлять, когда подведены итоги конкурса и доступен результат/диплом.	`event_title, work_title`	API есть, шаблон не назначен
Педагогические мероприятия	Семинар	Регистрация/участие принято	`seminar_registration_created`	Регистрация/участие в семинаре принято.	Отправлять после регистрации пользователя на семинар.	`event_title`	API есть, шаблон не назначен
Педагогические мероприятия	Семинар	Сертификат готов	`seminar_certificate_ready`	Сертификат семинара готов.	Отправлять, когда сертификат по семинару сформирован.	`event_title`	API есть, шаблон не назначен
Педагогические мероприятия	Конференция	Регистрация/участие принято	`conference_registration_created`	Регистрация/участие в конференции принято.	Отправлять после регистрации пользователя на конференцию.	`event_title`	API есть, шаблон не назначен
Педагогические мероприятия	Конференция	Сертификат готов	`conference_certificate_ready`	Сертификат конференции готов.	Отправлять, когда сертификат по конференции сформирован.	`event_title`	API есть, шаблон не назначен
Педагогические мероприятия	Вебинар/мастер-класс	Регистрация/участие принято	`webinar_registration_created`	Регистрация/участие в вебинаре или мастер-классе принято.	Отправлять после регистрации пользователя на вебинар/мастер-класс.	`event_title`	API есть, шаблон не назначен
Педагогические мероприятия	Вебинар/мастер-класс	Сертификат готов	`webinar_certificate_ready`	Сертификат вебинара/мастер-класса готов.	Отправлять, когда сертификат по вебинару/мастер-классу сформирован.	`event_title`	API есть, шаблон не назначен
Педагогические мероприятия	Публикация на сайте	Материал отправлен	`publication_site_submitted`	Материал для публикации на сайте отправлен.	Отправлять после успешной отправки материала на публикацию на сайте.	`publication_title`	API есть, шаблон не назначен
Педагогические мероприятия	Публикация на сайте	Опубликовано / свидетельство готово	`publication_site_published`	Материал опубликован на сайте / свидетельство готово.	Отправлять, когда публикация на сайте размещена или готово свидетельство.	`publication_title`	API есть, шаблон не назначен
Педагогические мероприятия	Публикация в сборнике/книге	Материал отправлен	`publication_book_submitted`	Материал для публикации в сборнике/книге отправлен.	Отправлять после успешной отправки материала в сборник/книгу.	`publication_title`	API есть, шаблон не назначен
Педагогические мероприятия	Публикация в сборнике/книге	Опубликовано / документы готовы	`publication_book_published`	Публикация в сборнике/книге готова / документы готовы.	Отправлять, когда сборник/книга опубликованы или готовы документы.	`publication_title`	API есть, шаблон не назначен
Педагогические мероприятия	Публикация в журнале	Материал отправлен	`publication_journal_submitted`	Материал для публикации в журнале отправлен.	Отправлять после успешной отправки материала в журнал.	`publication_title`	API есть, шаблон не назначен
Педагогические мероприятия	Публикация в журнале	Опубликовано / документы готовы	`publication_journal_published`	Публикация в журнале готова / документы готовы.	Отправлять, когда журнал опубликован или готовы документы.	`publication_title`	API есть, шаблон не назначен

Event → template routing в проекте luch

Это отдельная настройка шаблонов, не каталог API. API-событие может приниматься и логироваться даже если шаблон ещё не назначен.

event_type	Сценарий	Тема письма
Для проекта пока нет event_type-шаблонов

Переменные

Верхний уровень JSON: event_type, email, name, order_id, idempotency_key, amount, currency. Обязательные верхние поля: event_type, email. name и idempotency_key пока необязательны, но желательны. Обязательные fields зависят от event_type: course_name для КПК/КПП/КПО; event_title для олимпиад/семинаров/конференций/вебинаров; event_title + work_title для конкурсов; publication_title для публикаций. document_url необязателен. Для оплаты курса можно передать факультативно fields.course_category_id — ID категории курса из таблицы ниже. Тогда контакт попадёт не только в общую книгу “Курсы — успешная оплата”, но и в категорийную книгу.

Категории курса для purchase/course

Передавайте ID в поле fields.course_category_id. Не передавайте list_id: Guru Send сам маршрутизирует контакт в нужную книгу.

ID	Категория	slug	list_id
Для проекта нет настроенных категорий курсов

API-ключи проекта

ID	Название	Статус	Last4	Права
Нет ключей проекта

Служебные/legacy endpoints

Для внутренних интеграций и админских сценариев; внешнему разработчику сайта обычно нужен блок “Внешний API-шлюз”.

Метод	Назначение	Пример JSON
`POST /api/sites`	Создать/обновить проект	{"site_key":"luch","name":"Луч знаний","from_email":"no-reply@mail.luchznaniy.ru"}
`POST /api/contacts/upsert`	Создать/обновить контакт	{"site_key":"luch","email":"user@example.com","name":"Ирина","fields":{"course":"Педагогика"}}
`POST /api/templates`	Создать email-шаблон	{"site_key":"luch","name":"Welcome","subject":"Привет {{name}}","html":"<p>...</p>","text":"..."}
`POST /api/lists`	Создать адресную книгу	{"site_key":"luch","name":"Клиенты"}
`POST /api/lists/{list_id}/contacts`	Добавить контакт в адресную книгу	{"contact_id":123}
`POST /api/events/unpaid-order`	Legacy: событие неоплаченного заказа	{"site_key":"luch","email":"client@example.com","order_id":"ORDER-1"}
`POST /api/sequences`	Создать автоцепочку	{"site_key":"luch","name":"Repeat","steps":[{"template_id":1,"delay_minutes":0}]}
`GET /api/campaigns/{campaign_id}/stats`	Статистика рассылки
`GET /api/stats/overview`	Общая статистика сервиса

Статусы контакта

active — Активен unsubscribed — Отписался invalid — Адрес не существует admin_blocked — Заблокирован администратором