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=uchitelu&order_id=ORDER-1
`GET /api/admin/external-events/stats`	Админ: статистика входящих API-событий	?site_key=uchitelu

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

Если обязательных данных не хватает, 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`	✅ шаблон назначен
Педагогические мероприятия	Конкурс	Работа отправлена	`contest_work_submitted`	Конкурсная работа отправлена/принята.	Отправлять после успешной загрузки или принятия работы на творческий конкурс.	`event_title, work_title`	API есть, шаблон не назначен
Педагогические мероприятия	Конкурс	Результаты готовы	`contest_results`	Результаты творческого конкурса готовы.	Отправлять, когда подведены итоги конкурса и доступен результат/диплом.	`event_title, work_title`	✅ шаблон назначен
Педагогические мероприятия	Семинар	Регистрация/участие принято	`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`	✅ шаблон назначен
Педагогические мероприятия	Публикация на сайте	Опубликовано / свидетельство готово	`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 в проекте uchitelu

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

event_type	Сценарий	Тема письма
`course_abandoned_cart_1d`	Курсы — брошенная корзина 1d	{{ name }}, ваш доступ к курсу по спеццене ещё активен
`course_abandoned_cart_1h`	Курсы — брошенная корзина 1h	{{ name }}, оплатите курс со скидкой до конца дня!
`course_abandoned_cart_3d`	Курсы — брошенная корзина 3d	{{ name }}, скидка 40% на «{{ course_name }}» скоро сгорит
`course_order_created`	Курсы — заявка сформирована	✅ Подтверждение вашей заявки на «{{ course_name }}»
`course_document_ready`	Курсы — обучение завершено, тест сдан, документ готов	Ваш документ готов!
`course_finished_test_missing`	Курсы — срок обучения завершён, тест не сдан	Остался последний шаг для получения документа!
`course_paid`	Курсы — оплата успешно проведена	🎉 Доступ к курсу «{{ course_name }}» открыт!
`course_test_failed`	Курсы — итоговое тестирование неуспешно	Результат итогового теста по курсу «{{ course_name }}»
`course_test_passed`	Курсы — итоговое тестирование успешно	🌟 Поздравляем! Вы успешно сдали итоговый тест «{{ course_name }}»
`course_track_number`	Курсы — трек-номер документа	Трек-номер вашего документа
`form_lead_collective_notify`	Заявка — коллективное обучение	Новая заявка на коллективное обучение с сайта
`pedportal_abandoned_cart_1d`	Педпортал — брошенная корзина 1d	Ваш диплом готов! Сохраните его
`pedportal_abandoned_cart_1h`	Педпортал — брошенная корзина 1h	Ваш диплом готов! Сохраните его
`pedportal_abandoned_cart_3d`	Педпортал — брошенная корзина 3d	Ваш диплом готов! Сохраните его
`contest_results`	Педпортал — результаты конкурса	Результаты конкурса
`contest_work_accepted`	Педпортал — работа принята на конкурс	Ваша работа участвует в конкурсе
`olympiad_results`	Педпортал — результаты олимпиады	Результаты олимпиады
`diploma_paid`	Педпортал — оплата успешно проведена	Оплата прошла успешно
`publication_site_submitted`	Педпортал — публикация на сайте	Ваша публикация «{{ publication_title }}» принята

Переменные

Верхний уровень 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
`1`	Педагог дошкольного образования (воспитатель и т.д.)	`pedagog-doshkolnogo-obrazovaniya`	35
`2`	Педагог начальной школы	`pegagog-nachalnoi-shkoly`	36
`3`	Педагог общего образования	`pedagog-obshchego-obrazovaniya`	37
`6`	Преподаватель СПО и ВО	`prepodavatel-spo-i-vo`	40
`4`	Педагог дополнительного образования	`pedagog-dopolnitelnogo-obrazovaniya`	38
`9`	Администрация ОО (директор, заведующий, завуч, старший воспитатель)	`administraciya-oo-direktor-zaveduyushchiy-zavuch-starshiy-vospitatel`	43
`8`	Учитель-логопед/ дефектолог	`uchitel-logoped-defektolog`	42
`5`	Педагог-психолог, Психолог	`pedagog-psikholog-psikholog`	39
`7`	Социальный педагог	`sotsialnyy-pedagog`	41
`12`	Педагог-организатор	`pedagog-organizator`	46
`10`	Библиотекарь	`bibliotekar`	44
`11`	Методист	`metodist`	45

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

ID	Название	Статус	Last4	Права
21	uchitelu.ru site backend Guru Send key reissued 20260709_125146	active	…qvsU	{"permissions": ["transactional_send", "cart_events_write"], "allowed_api_events": ["course_order_created", "course_paid", "course_test_passed", "course_test_failed", "course_document_ready", "course_finished_test_missing", "course_track_number", "diploma_created", "diploma_order_created", "diploma_paid", "olympiad_results", "contest_work_accepted", "contest_results", "publication_site_submitted", "publication_site_published", "form_lead_collective_notify"], "allowed_cart_types": ["course", "diploma"], "note": "reissued by Hermes for the-teacher staging handoff 20260709_125146: transactional + course/diploma cart events"}
16	uchitelu.ru site backend Guru Send key	active	…Rwok	{"permissions": ["transactional_send", "cart_events_write"], "allowed_api_events": ["course_order_created", "course_paid", "course_test_passed", "course_test_failed", "course_document_ready", "course_finished_test_missing", "course_track_number", "diploma_created", "diploma_order_created", "diploma_paid", "olympiad_results", "contest_work_accepted", "contest_results", "publication_site_submitted", "publication_site_published", "form_lead_collective_notify"], "allowed_template_keys": ["course_application_created", "course_payment_success", "course_test_passed", "course_test_failed", "course_completed_passed_document_ready", "course_completed_test_not_passed", "course_track_number", "pedportal_payment_success", "pedportal_olympiad_results", "pedportal_contest_work_accepted", "pedportal_contest_results", "pedportal_publication_status", "form_lead_collective_notify"], "allowed_cart_types": ["course", "diploma"], "note": "uchitelu.ru site backend: transactional API events + course/diploma cart events"}
12	uchitelu n8n course events key	active	…LPgA	`{"permissions": ["cart_events_write"], "allowed_cart_types": ["course"], "note": "n8n key: uchitelu course order-created + purchase events only"}`
11	uchitelu n8n course cart and paid-list key	disabled	…QAmI	`{"permissions": ["cart_events_write", "list_contacts_write"], "allowed_cart_types": ["course"], "note": "n8n key: uchitelu course cart events + upsert only to paid courses address book"}`
7	uchitelu site backend developer key	active	…57B5	{"permissions": ["transactional_send", "cart_events_write"], "allowed_template_keys": ["course_application_created", "course_payment_success", "course_test_passed", "course_test_failed", "course_completed_passed_document_ready", "course_completed_test_not_passed", "course_track_number", "pedportal_payment_success", "pedportal_olympiad_results", "pedportal_contest_work_accepted", "pedportal_contest_results", "pedportal_publication_status", "form_lead_collective_notify"], "allowed_cart_types": ["course", "diploma"], "note": "uchitelu site backend: transactional + cart events only"}
6	uchitelu cart events developer key	disabled	…za5k	`{"permissions": ["cart_events_write"], "allowed_cart_types": ["course", "pedportal"], "note": "add unpaid order to cart books and remove/cancel on purchase for uchitelu only"}`
5	uchitelu transactional developer key	disabled	…WhJI	{"permissions": ["transactional_send"], "allowed_template_keys": ["course_application_created", "course_payment_success", "course_test_passed", "course_test_failed", "course_completed_passed_document_ready", "course_completed_test_not_passed", "course_track_number", "pedportal_payment_success", "pedportal_olympiad_results", "pedportal_contest_work_accepted", "pedportal_contest_results", "pedportal_publication_status", "form_lead_collective_notify"], "note": "send only uchitelu transactional templates, no carts"}
4	uchitelu list 31 add-only developer key	active	…f_lI	`{"permissions": ["list_contacts_write"], "note": "add/upsert contacts only to uchitelu list 31"}`
3	uchitelu list 31 add-only developer key	disabled	…grbQ	`{"permissions": ["list_contacts_write"], "note": "add/upsert contacts only to uchitelu list 31"}`

Служебные/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 — Заблокирован администратором