Public API — интеграция проверки диктантов

Public API предназначен для корпоративных заказчиков, которые хотят встроить проверку диктантов Письмовника в собственную инфраструктуру: корпоративный портал, LMS, мобильное приложение или веб-сервис.

API позволяет авторизовать пользователей по email и сохранять результаты проверки диктантов, переданные в формате JSON.

Основные сведения

Параметр	Значение
Базовый URL	`https://pismovnik.ru/api/public/`
Формат запроса и ответа	JSON (`Content-Type: application/json`)
CORS	`Access-Control-Allow-Origin: *`
CSRF	Отключён (`@csrf_exempt`), токен не требуется
Preflight	Поддерживаются `OPTIONS`-запросы (ответ 200)

Аутентификация

Доступ к API контролируется ключом заказчика (key). Ключ должен существовать в таблице CorpCustomer (поле key). Ключ выдаётся администратором Письмовника после заключения договора.

Ключ передаётся в теле каждого запроса. Без валидного ключа API возвращает ошибку 400.

1. Список эндпоинтов

GET /api/public/ — возвращает список всех доступных эндпоинтов.

Ответ 200:

{
    "auth_user": "/api/public/auth_user",
    "save_check_result": "/api/public/save_check_result"
}

2. Авторизация пользователя

POST /api/public/auth_user — авторизация пользователя по email. Если пользователь с таким email не существует — создаётся новый с автосгенерированным паролем (пароль отправляется на email).

Параметры запроса

Поле	Тип	Обязательное	Описание
`key`	string	да	Ключ заказчика (CorpCustomer.key)
`email`	string	да	Email пользователя (валидный формат)
`login`	string	да	Имя или логин пользователя

Ответ 200:

{"success": true, "user": "42"}

Поле user — строковый pk пользователя (integer), используется в save_check_result.

Ошибка 400: невалидный ключ, email или отсутствует обязательное поле.

3. Сохранение результата проверки

POST /api/public/save_check_result — сохранение результата проверки диктанта.

Параметры запроса

Поле	Тип	Обязательное	Описание
`key`	string	да	Ключ заказчика
`user`	string	да	ID пользователя (из `auth_user`)
`dict`	string	да	pk CorpDict (UUID)
`text`	string	да	Написанный текст
`model`	string	да	JSON-строка с результатом проверки (см. формат ниже)
`sendEmailToUser`	boolean	нет	Отправить письмо пользователю с результатом

Формат поля model

{
    "summary": {
        "score": 75,
        "counts": {"ORFO": 2, "PUNCT": 1, "TYPO": 0},
        "wrong_words": 0
    }
}

Ответ 200:

{"success": true}

Ошибка 400: невалидный ключ, пользователь не найден, dict не найден, model не парсится или не содержит summary.counts.ORFO, summary.counts.PUNCT, summary.score.

Примеры запросов (cURL)

Авторизация пользователя

curl -X POST https://pismovnik.ru/api/public/auth_user \
  -H "Content-Type: application/json" \
  -d '{
    "key": "test-key",
    "email": "user@example.com",
    "login": "Иван"
  }'
# → {"success":true,"user":"1"}

Сохранение результата

curl -X POST https://pismovnik.ru/api/public/save_check_result \
  -H "Content-Type: application/json" \
  -d '{
    "key": "test-key",
    "user": "1",
    "dict": "0192abcd-1234-7890-abcd-ef1234567890",
    "text": "текст",
    "model": "{\"summary\":{\"score\":75,\"counts\":{\"ORFO\":2,\"PUNCT\":1,\"TYPO\":0},\"wrong_words\":0}}",
    "sendEmailToUser": true
  }'
# → {"success":true}

Примечание по model

Поле model передаётся как JSON-строка (не объект), поэтому в cURL его нужно экранировать. В большинстве языков программирования достаточно сериализовать объект в строку через JSON.stringify() или аналогичный метод.

Сценарии интеграции

Public API может использоваться в двух сценариях:

Встраивание формы написания — вы размещаете на своём сайте стандартную форму написания диктанта от Письмовника с помощью JavaScript-кода. Результаты автоматически попадают в кабинет организатора. API в этом случае не требуется.
Собственная форма + API — вы разрабатываете собственную форму написания диктанта, встраиваете скрипт проверки от Письмовника и используете Public API для сохранения результатов. Этот сценарий описан в руководстве по организации диктанта.

Обработка ошибок

При ошибках API возвращает HTTP-статус 400 и тело с описанием проблемы. Рекомендуется проверять HTTP-статус ответа перед обработкой:

HTTP-статус	Причина
200	Успех. Тело содержит `{"success": true}` и, возможно, дополнительные поля.
400	Ошибка запроса: невалидный ключ, email, отсутствуют обязательные поля, model не парсится.